# EpochFlow - Algorithm Graph Compiler
[](https://badge.fury.io/py/epochflow)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
**EpochFlow** is a compiler that transforms Python-like algorithm specifications into dataflow graph representations. It parses constrained Python syntax using AST compilation and generates node/edge graphs suitable for execution by dataflow runtime engines.
## Features
- 🐍 **Pure Python AST Parsing** - No custom grammar or parsers needed
- 🔄 **Automatic Type Casting** - Seamless Boolean ↔ Number conversions
- ⏰ **Timeframe Validation** - Built-in pandas offset validation
- 🔌 **Extensible Registry** - Plugin your own component metadata
- 🚀 **Zero Dependencies** - Only Python standard library required
- 🎯 **Type Safe** - Full type hints support
- 📦 **Standalone Package** - Use independently or with EpochAI
## Installation
```bash
pip install epochflow
```
### Optional Dependencies
```bash
# For timeframe validation
pip install epochflow[pandas]
# For development
pip install epochflow[dev]
```
## Quick Start
### Basic Usage
```python
from epochflow import compile_algorithm, set_transforms_list
# Define your component metadata
transforms = [
{
"id": "market_data_source",
"inputs": [],
"outputs": [{"id": "close"}, {"id": "volume"}],
"options": [{"id": "timeframe"}],
"requiresTimeFrame": True,
},
{
"id": "sma",
"inputs": [{"id": "source"}],
"outputs": [{"id": "result"}],
"options": [{"id": "period"}],
}
]
# Set transforms metadata
set_transforms_list(transforms)
# Compile algorithm code
code = """
src = market_data_source(timeframe="1D")
sma_20 = sma(period=20)(src.close)
"""
result = compile_algorithm(code)
print(result)
# Output: {'nodes': [...], 'edges': [...]}
```
### Advanced Usage with Custom Loader
```python
from epochflow import set_transforms_loader, compile_algorithm
import requests
# Define a custom loader function
def load_transforms():
response = requests.get("https://api.example.com/transforms")
return response.json()
# Set the loader
set_transforms_loader(load_transforms)
# Compile (automatically loads transforms when needed)
result = compile_algorithm("src = market_data_source(timeframe='1H')")
```
## Syntax Overview
EpochFlow supports a constrained subset of Python:
### Variable Assignment
```python
src = market_data_source(timeframe="1D")
ema_fast = ema(period=12)(src.close)
```
### Operators
```python
# Arithmetic
result = a + b - c * d / e
# Comparison
condition = price > threshold
# Logical
signal = long_condition and not short_condition
```
### Lag Operator (Subscript)
```python
prev_close = src.close[1] # Previous bar
```
### Ternary Expressions
```python
value = high_val if condition else low_val
```
### Tuple Unpacking
```python
upper, middle, lower = bollinger_bands(period=20)(src.close)
```
## API Reference
### Core Functions
#### `compile_algorithm(source, registry=None, transforms_list=None)`
Compiles algorithm code to node/edge graph.
**Parameters:**
- `source` (str): Algorithm code in EpochFlow syntax
- `registry` (dict, optional): Pre-built registry dictionary
- `transforms_list` (list, optional): Transform metadata for type checking
**Returns:** `dict` with `nodes` and `edges` keys
#### `set_transforms_list(transforms)`
Set transforms metadata directly.
**Parameters:**
- `transforms` (list): List of transform metadata dictionaries
#### `set_transforms_loader(loader)`
Set a custom loader function for transforms.
**Parameters:**
- `loader` (callable): Function that returns transform metadata list
#### `get_transforms_list()`
Get currently configured transforms metadata.
**Returns:** `list` or `None`
### Classes
#### `AlgorithmCompiler(registry, transforms_list=None)`
Low-level compiler class for advanced usage.
## Transform Metadata Format
Transforms metadata should be a list of dictionaries:
```python
{
"id": "component_name",
"inputs": [
{"id": "input_name", "type": "Number"}
],
"outputs": [
{"id": "output_name", "type": "Decimal"}
],
"options": [
{"id": "parameter_name", "type": "integer"}
],
"requiresTimeFrame": False,
"isCrossSectional": False,
"atLeastOneInputRequired": True,
"category": "Indicators"
}
```
## Examples
See [STANDALONE_USAGE.md](STANDALONE_USAGE.md) for comprehensive examples including:
- Simple moving average crossover
- FastAPI integration
- Custom component metadata
- Error handling patterns
## Architecture
```
EpochFlow Components:
├── compiler/
│ └── ast_compiler.py # AST parsing and graph generation
├── registry/
│ └── transform_registry.py # Component metadata management
└── syntax/
└── rules.py # Syntax documentation for LLMs
```
**Design Philosophy:**
- Constrained Python syntax with direct AST compilation
- No custom grammar or structured parsers
- Optimized for LLM code generation
- Clean separation of parsing and validation
## Use Cases
- **Trading Strategies**: Compile algorithm specs for backtesting engines
- **Data Pipelines**: Transform declarative specs into execution graphs
- **Visual Programming**: Backend for node-based editors
- **Code Generation**: Target for LLM-generated algorithm code
- **Research Tools**: Analyze and validate quantitative strategies
## Integration with EpochAI
EpochFlow was extracted from the EpochAI project and maintains full backward compatibility. When used within EpochAI, it automatically detects and uses the parent project's transform metadata.
```python
# In EpochAI - works automatically
from epochflow import compile_algorithm
result = compile_algorithm(code) # Uses EpochAI's metadata
```
## Development
```bash
# Clone the repository
git clone https://github.com/epochai/epochflow.git
cd epochflow
# Install in development mode
pip install -e .[dev]
# Run tests
pytest
# Format code
black .
ruff check --fix .
```
## Testing
```bash
# Run all tests
pytest
# Run with coverage
pytest --cov=epochflow --cov-report=html
# Run specific test file
pytest epochflow/tests/test_py_algo_ast_compiler.py
```
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Support
- **Documentation**: [GitHub README](https://github.com/epochai/epochflow#readme)
- **Issues**: [GitHub Issues](https://github.com/epochai/epochflow/issues)
- **Discussions**: [GitHub Discussions](https://github.com/epochai/epochflow/discussions)
## Changelog
See [CHANGELOG.md](https://github.com/epochai/epochflow/releases) for version history.
## Acknowledgments
EpochFlow is part of the EpochAI quantitative trading platform ecosystem.
---
Made with ❤️ by the EpochAI Team
Raw data
{
"_id": null,
"home_page": null,
"name": "epochflow",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "EpochAI Team <support@epochai.com>",
"keywords": "compiler, ast, dataflow, graph, algorithm, trading, strategy, quantitative, finance",
"author": null,
"author_email": "EpochAI Team <support@epochai.com>",
"download_url": null,
"platform": null,
"description": "# EpochFlow - Algorithm Graph Compiler\n\n[](https://badge.fury.io/py/epochflow)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n\n**EpochFlow** is a compiler that transforms Python-like algorithm specifications into dataflow graph representations. It parses constrained Python syntax using AST compilation and generates node/edge graphs suitable for execution by dataflow runtime engines.\n\n## Features\n\n- \ud83d\udc0d **Pure Python AST Parsing** - No custom grammar or parsers needed\n- \ud83d\udd04 **Automatic Type Casting** - Seamless Boolean \u2194 Number conversions\n- \u23f0 **Timeframe Validation** - Built-in pandas offset validation\n- \ud83d\udd0c **Extensible Registry** - Plugin your own component metadata\n- \ud83d\ude80 **Zero Dependencies** - Only Python standard library required\n- \ud83c\udfaf **Type Safe** - Full type hints support\n- \ud83d\udce6 **Standalone Package** - Use independently or with EpochAI\n\n## Installation\n\n```bash\npip install epochflow\n```\n\n### Optional Dependencies\n\n```bash\n# For timeframe validation\npip install epochflow[pandas]\n\n# For development\npip install epochflow[dev]\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nfrom epochflow import compile_algorithm, set_transforms_list\n\n# Define your component metadata\ntransforms = [\n {\n \"id\": \"market_data_source\",\n \"inputs\": [],\n \"outputs\": [{\"id\": \"close\"}, {\"id\": \"volume\"}],\n \"options\": [{\"id\": \"timeframe\"}],\n \"requiresTimeFrame\": True,\n },\n {\n \"id\": \"sma\",\n \"inputs\": [{\"id\": \"source\"}],\n \"outputs\": [{\"id\": \"result\"}],\n \"options\": [{\"id\": \"period\"}],\n }\n]\n\n# Set transforms metadata\nset_transforms_list(transforms)\n\n# Compile algorithm code\ncode = \"\"\"\nsrc = market_data_source(timeframe=\"1D\")\nsma_20 = sma(period=20)(src.close)\n\"\"\"\n\nresult = compile_algorithm(code)\nprint(result)\n# Output: {'nodes': [...], 'edges': [...]}\n```\n\n### Advanced Usage with Custom Loader\n\n```python\nfrom epochflow import set_transforms_loader, compile_algorithm\nimport requests\n\n# Define a custom loader function\ndef load_transforms():\n response = requests.get(\"https://api.example.com/transforms\")\n return response.json()\n\n# Set the loader\nset_transforms_loader(load_transforms)\n\n# Compile (automatically loads transforms when needed)\nresult = compile_algorithm(\"src = market_data_source(timeframe='1H')\")\n```\n\n## Syntax Overview\n\nEpochFlow supports a constrained subset of Python:\n\n### Variable Assignment\n```python\nsrc = market_data_source(timeframe=\"1D\")\nema_fast = ema(period=12)(src.close)\n```\n\n### Operators\n```python\n# Arithmetic\nresult = a + b - c * d / e\n\n# Comparison\ncondition = price > threshold\n\n# Logical\nsignal = long_condition and not short_condition\n```\n\n### Lag Operator (Subscript)\n```python\nprev_close = src.close[1] # Previous bar\n```\n\n### Ternary Expressions\n```python\nvalue = high_val if condition else low_val\n```\n\n### Tuple Unpacking\n```python\nupper, middle, lower = bollinger_bands(period=20)(src.close)\n```\n\n## API Reference\n\n### Core Functions\n\n#### `compile_algorithm(source, registry=None, transforms_list=None)`\nCompiles algorithm code to node/edge graph.\n\n**Parameters:**\n- `source` (str): Algorithm code in EpochFlow syntax\n- `registry` (dict, optional): Pre-built registry dictionary\n- `transforms_list` (list, optional): Transform metadata for type checking\n\n**Returns:** `dict` with `nodes` and `edges` keys\n\n#### `set_transforms_list(transforms)`\nSet transforms metadata directly.\n\n**Parameters:**\n- `transforms` (list): List of transform metadata dictionaries\n\n#### `set_transforms_loader(loader)`\nSet a custom loader function for transforms.\n\n**Parameters:**\n- `loader` (callable): Function that returns transform metadata list\n\n#### `get_transforms_list()`\nGet currently configured transforms metadata.\n\n**Returns:** `list` or `None`\n\n### Classes\n\n#### `AlgorithmCompiler(registry, transforms_list=None)`\nLow-level compiler class for advanced usage.\n\n## Transform Metadata Format\n\nTransforms metadata should be a list of dictionaries:\n\n```python\n{\n \"id\": \"component_name\",\n \"inputs\": [\n {\"id\": \"input_name\", \"type\": \"Number\"}\n ],\n \"outputs\": [\n {\"id\": \"output_name\", \"type\": \"Decimal\"}\n ],\n \"options\": [\n {\"id\": \"parameter_name\", \"type\": \"integer\"}\n ],\n \"requiresTimeFrame\": False,\n \"isCrossSectional\": False,\n \"atLeastOneInputRequired\": True,\n \"category\": \"Indicators\"\n}\n```\n\n## Examples\n\nSee [STANDALONE_USAGE.md](STANDALONE_USAGE.md) for comprehensive examples including:\n- Simple moving average crossover\n- FastAPI integration\n- Custom component metadata\n- Error handling patterns\n\n## Architecture\n\n```\nEpochFlow Components:\n\u251c\u2500\u2500 compiler/\n\u2502 \u2514\u2500\u2500 ast_compiler.py # AST parsing and graph generation\n\u251c\u2500\u2500 registry/\n\u2502 \u2514\u2500\u2500 transform_registry.py # Component metadata management\n\u2514\u2500\u2500 syntax/\n \u2514\u2500\u2500 rules.py # Syntax documentation for LLMs\n```\n\n**Design Philosophy:**\n- Constrained Python syntax with direct AST compilation\n- No custom grammar or structured parsers\n- Optimized for LLM code generation\n- Clean separation of parsing and validation\n\n## Use Cases\n\n- **Trading Strategies**: Compile algorithm specs for backtesting engines\n- **Data Pipelines**: Transform declarative specs into execution graphs\n- **Visual Programming**: Backend for node-based editors\n- **Code Generation**: Target for LLM-generated algorithm code\n- **Research Tools**: Analyze and validate quantitative strategies\n\n## Integration with EpochAI\n\nEpochFlow was extracted from the EpochAI project and maintains full backward compatibility. When used within EpochAI, it automatically detects and uses the parent project's transform metadata.\n\n```python\n# In EpochAI - works automatically\nfrom epochflow import compile_algorithm\nresult = compile_algorithm(code) # Uses EpochAI's metadata\n```\n\n## Development\n\n```bash\n# Clone the repository\ngit clone https://github.com/epochai/epochflow.git\ncd epochflow\n\n# Install in development mode\npip install -e .[dev]\n\n# Run tests\npytest\n\n# Format code\nblack .\nruff check --fix .\n```\n\n## Testing\n\n```bash\n# Run all tests\npytest\n\n# Run with coverage\npytest --cov=epochflow --cov-report=html\n\n# Run specific test file\npytest epochflow/tests/test_py_algo_ast_compiler.py\n```\n\n## Contributing\n\nContributions are welcome! Please:\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Documentation**: [GitHub README](https://github.com/epochai/epochflow#readme)\n- **Issues**: [GitHub Issues](https://github.com/epochai/epochflow/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/epochai/epochflow/discussions)\n\n## Changelog\n\nSee [CHANGELOG.md](https://github.com/epochai/epochflow/releases) for version history.\n\n## Acknowledgments\n\nEpochFlow is part of the EpochAI quantitative trading platform ecosystem.\n\n---\n\nMade with \u2764\ufe0f by the EpochAI Team\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Algorithm Graph Compiler for DataFlow Execution - Compiles Python-like algorithm specifications into nodes/edges graphs",
"version": "0.2.0",
"project_urls": {
"Changelog": "https://github.com/epochai/epochflow/releases",
"Documentation": "https://github.com/epochai/epochflow#readme",
"Homepage": "https://github.com/epochai/epochflow",
"Issues": "https://github.com/epochai/epochflow/issues",
"Repository": "https://github.com/epochai/epochflow"
},
"split_keywords": [
"compiler",
" ast",
" dataflow",
" graph",
" algorithm",
" trading",
" strategy",
" quantitative",
" finance"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "04765792d96aa19768a5384f212a30b1f2170f87508b1bbd64ce23c6e7795129",
"md5": "d234b5bf07f9a6ae567bcbdb43de3291",
"sha256": "2e55fe5c396c082f584b3e7283fb028515c997543891601213d0a42fc763cede"
},
"downloads": -1,
"filename": "epochflow-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d234b5bf07f9a6ae567bcbdb43de3291",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 78855,
"upload_time": "2025-10-14T03:28:03",
"upload_time_iso_8601": "2025-10-14T03:28:03.481226Z",
"url": "https://files.pythonhosted.org/packages/04/76/5792d96aa19768a5384f212a30b1f2170f87508b1bbd64ce23c6e7795129/epochflow-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-14 03:28:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "epochai",
"github_project": "epochflow",
"github_not_found": true,
"lcname": "epochflow"
}
JSON
