Metadata-Version: 2.4
Name: aceteam-workflow-engine
Version: 1.0.0rc2
Summary: A powerful workflow orchestration engine for composing complex computational tasks from modular, type-safe nodes
Project-URL: Homepage, https://aceteam.ai/workflow-engine
Project-URL: Documentation, https://aceteam.ai/workflow-engine
Project-URL: Repository, https://github.com/aceteam-ai/workflow-engine
Project-URL: Issues, https://github.com/aceteam-ai/workflow-engine/issues
Project-URL: Changelog, https://github.com/aceteam-ai/workflow-engine/releases
Author-email: Anthony Tecsa <anthonytecsa@gmail.com>, Jason Sun <jason@adanomad.com>, Justin Xu <xu.justin.j@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: async,automation,dag,execution,graph,orchestration,pipeline,workflow
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Pydantic :: 2
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.12
Requires-Dist: dotenv>=0.9.9
Requires-Dist: networkx<4.0.0,>=3.4.2
Requires-Dist: overrides>=7.7.0
Requires-Dist: pydantic<3.0.0,>=2.11.1
Provides-Extra: dev
Requires-Dist: pydot>=3.0.0; extra == 'dev'
Requires-Dist: pyright>=1.1.403; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.26.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
Requires-Dist: pytest>=8.3.5; extra == 'dev'
Requires-Dist: python-dotenv>=1.1.0; extra == 'dev'
Requires-Dist: ruff>=0.11.8; extra == 'dev'
Requires-Dist: twine>=6.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Aceteam Workflow Engine

A powerful, modular workflow orchestration system designed for composing complex computational tasks from smaller, configurable steps. This engine powers the workflow functionality in [Aceteam.ai](https://aceteam.ai/workflow-engine) and is now available as an open-source package.

## Overview

The Workflow Engine enables you to:

- Define workflows as directed acyclic graphs (DAGs)
- Chain node-based tasks with type-safe data passing
- Persist and retrieve node outputs using various storage backends
- Execute workflows programmatically or via API

## Installation

```bash
pip install aceteam-workflow-engine
```

## Example

```python
import asyncio

from workflow_engine import IntegerValue, Workflow
import workflow_engine.nodes
from workflow_engine.contexts import LocalContext
from workflow_engine.execution import TopologicalExecutionAlgorithm

context = LocalContext()
algorithm = TopologicalExecutionAlgorithm()

# Load and run a workflow
with open("examples/addition.json") as f:
    workflow = Workflow.model_validate_json(f.read())

result = asyncio.run(algorithm.execute(
    context=context,
    workflow=workflow,
    input={"c": IntegerValue(-256)},
)) # {'sum': 1811}
```

Check the `examples` directory for more sample workflows in JSON form:

- [`addition.json`](./examples/addition.json): basic arithmetic operations
- [`append.json`](./examples/append.json): text file manipulation
- [`error.json`](./examples/error.json): graceful error handling

## Key Features

### Core Functionality

- **Graph-Based Execution**: Workflows are executed as DAGs with automatic dependency resolution
- **Type-Safe Data Flow**: Data passing between nodes is validated using MIME types
- **Flexible Storage**: Supports multiple storage backends (Supabase, Local, In-Memory)
- **Error Handling**: Robust error propagation and logging system
- **Versioning**: Built-in support for workflow versioning

### Node Types

- **Input Nodes**: Accept workflow inputs with type constraints
- **Processing Nodes**: Execute computational tasks with configurable parameters
- **Output Nodes**: Format and return workflow results

### Storage Backends

- **Supabase**: Primary storage backend for production use
- **Local**: File-system based storage for development
- **In-Memory**: Lightweight storage for testing

### Value Type Casting

The workflow engine supports automatic type casting between Value types. The graph below shows all available casting paths:

![Value Typecasting Graph](docs/typecast_graph.svg)

## Architecture

```
src/workflow_engine/
├── contexts/          # Storage backend implementations
│   ├── in_memory.py   # In-memory storage
│   └── local.py       # Local file system storage
├── core/              # Core workflow components
│   ├── context.py     # Execution context
│   ├── data.py        # Data handling
│   ├── edge.py        # Edge definitions
│   ├── execution.py   # Execution logic
│   ├── file.py        # File handling
│   ├── node.py        # Node base classes
│   └── workflow.py    # Workflow definitions
├── execution/         # Execution strategies
│   └── topological.py # DAG-based execution
├── nodes/             # Node implementations
│   ├── arithmetic.py  # Math operations
│   ├── constant.py    # Constant values
│   ├── json.py        # JSON operations
│   └── text.py        # Text operations
└── utils/             # Helper utilities
```

## Development

### Setup

```bash
# Using uv (recommended)
uv sync

# Using pip
pip install -e .
```

### Testing

```bash
uv run pytest  # Runs both unit and integration tests
```

## Documentation

- [Aceteam Workflow Documentation](https://aceteam.ai/workflow-engine)
- [API Reference](https://aceteam.ai/docs/api) (TODO)
- [Examples](./examples)

Available test suites:

- `test_type_checking.py`: Type system validation
- `test_workflow_validation.py`: Workflow validation tests

## Future Enhancements

- [ ] Support for iterative workflows and sub-workflows
- [ ] Enhanced parallel execution capabilities
- [ ] Additional storage backend implementations
- [ ] Improved error recovery and retry mechanisms
- [ ] Real-time workflow monitoring

## Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

## License

[MIT License](LICENSE)

## About

This workflow engine is developed and maintained by [Adanomad Consulting](https://adanomad.com) and powers the workflow functionality in [Aceteam.ai](https://aceteam.ai). For commercial support or consulting, please contact us at [contact@adanomad.com](mailto:contact@adanomad.com).
