Metadata-Version: 2.4
Name: apflow
Version: 0.22.1
Summary: AI-Perceivable Distributed Orchestration
Author-email: aiperceivable <team@aiperceivable.com>
License: Apache-2.0
Project-URL: Homepage, https://aiperceivable.com
Project-URL: Source, https://github.com/aiperceivable/apflow
Keywords: ai,agent,middleware,production,durable-execution,cost-governance,apcore
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic[email]>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: sqlalchemy-session-proxy>=0.1.0
Requires-Dist: alembic>=1.13.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: click>=8.0
Requires-Dist: apcore>=0.22.0
Requires-Dist: apcore-toolkit>=0.8.0
Requires-Dist: apcore-mcp>=0.15.0
Requires-Dist: apcore-a2a>=0.4.0
Requires-Dist: apcore-cli>=0.10.0
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
Requires-Dist: mkdocs-mermaid2-plugin>=1.0.0; extra == "docs"
Requires-Dist: mkdocs-minify-plugin>=0.7.0; extra == "docs"
Requires-Dist: pymdown-extensions>=10.0.0; extra == "docs"
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29.0; extra == "postgres"
Requires-Dist: psycopg2-binary>=2.9.9; extra == "postgres"
Requires-Dist: greenlet>=3.0.0; extra == "postgres"
Provides-Extra: scheduling
Requires-Dist: croniter>=1.0.0; extra == "scheduling"
Provides-Extra: email
Requires-Dist: aiosmtplib>=3.0.0; extra == "email"
Provides-Extra: all
Requires-Dist: apflow[email,postgres,scheduling]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.1.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Dynamic: license-file

# apflow

**AI-Perceivable Distributed Orchestration**

apflow is a distributed task orchestration engine where every capability is AI-perceivable — discoverable, understandable, and invocable by AI agents through the apcore module standard.

## The Tesla Analogy

Think of Tesla's Full Self-Driving (FSD):

```
Tesla = Traditional car systems (brakes, steering, battery management)
        + FSD (the AI brain that perceives and controls everything)

        The braking system doesn't need to be "smart."
        But it must be perceivable and controllable by FSD.

apflow = Traditional orchestration (dependency graphs, priority scheduling,
         distributed coordination)
        + apcore (makes every capability AI-perceivable)

        Task orchestration doesn't need AI.
        But it must be perceivable and invocable by AI agents.
```

**Tesla doesn't build a competitor to FSD — it builds the best car that FSD can control. apflow doesn't build AI agents — it builds the best orchestration engine that AI agents can invoke.**

## What apflow IS and IS NOT

| apflow IS | apflow IS NOT |
|---|---|
| A distributed orchestration engine | An AI agent framework |
| AI-perceivable via apcore | An AI/LLM product |
| Deterministic, reliable task coordination | A competitor to LangGraph/CrewAI |
| The "car systems" that AI agents control | The "FSD brain" itself |

## Requirements

- Python >= 3.11

## Install

```bash
pip install apflow
```

## Quick Start

```python
from apflow import TaskManager, create_session
from apflow.app import create_app

# One line to bootstrap the full stack
app = create_app()

# Start A2A server — AI agents can now discover and invoke orchestration
from apcore_a2a import serve
serve(app.registry, name="apflow")
```

```bash
# Or from the command line
apflow serve              # A2A HTTP server
apflow serve --explorer   # With Explorer UI
apflow serve --all        # Unified REST + A2A + MCP on one port (/, /a2a, /mcp)
apflow worker --db <postgres-url>  # Start distributed worker node (requires PostgreSQL)
apflow rest               # REST/HTTP API + OpenAPI docs at /docs (default :8080)
apflow scheduler          # Run the internal poll-based scheduler (foreground process)
apflow mcp                # MCP server (stdio, for Claude/Cursor)
apflow mcp --transport streamable-http --approval  # HTTP + async human-approval workflow
apflow info               # Show version, config, and registered modules
```

## Core Capabilities

### Task Orchestration (Dual Model: Structure Tree + Execution DAG)

apflow uses a **dual model** — structure tree (`parent_id`) for organization and execution DAG (`dependencies`) for ordering. This is not redundancy; each serves different operations:

```
parent_id    → Structure: copy, link, archive, progress aggregation
dependencies → Execution: parallel scheduling, fan-in, result injection
```

```python
tasks = [
    {"id": "a", "name": "Step A", "priority": 1},
    {"id": "b", "name": "Step B", "priority": 1},
    {"id": "merge", "name": "Merge", "parent_id": "a", "priority": 2,
     "dependencies": [{"id": "a"}, {"id": "b"}]},  # fan-in: waits for both
]
tree = await task_creator.create_task_tree_from_array(tasks)
await task_manager.distribute_task_tree(tree)
```

### Five Task Creation Modes

| Mode | Method | When to use |
|------|--------|-------------|
| **Create** | `create_task_tree_from_array()` | Build a new workflow from scratch |
| **Link** | `from_link()` | Reference a completed workflow (read-only, low storage) |
| **Copy** | `from_copy()` | Clone a workflow with modifications (re-run with new params) |
| **Archive** | `from_archive()` | Freeze an existing completed workflow in place (audit, compliance) |
| **Mixed** | `from_mixed()` | Partial copy + partial link (re-run only changed steps) |

See [Task Orchestration Architecture](docs/architecture/task-orchestration.md) for the full design rationale.

### Durable Execution

Checkpoint/resume, retry with configurable backoff, circuit breaker per executor.

### Cost Governance

Token budget management, model downgrade chains, policy engine (block/downgrade/notify).

### Distributed Coordination

Leader election, task leasing, worker management — scales from single process to multi-node cluster.

### AI-Perceivable (via apcore)

Every orchestration capability is automatically exposed as an apcore Module:
- **MCP** — AI agents (Claude, Cursor) discover and call orchestration tools
- **A2A** — Other services invoke orchestration via HTTP
- **CLI** — Humans operate orchestration from the terminal

## Architecture

```
AI Agents / Services / Humans
    ↓ discover & invoke
    ↓
┌──────────────────────────────────────────────┐
│  apflow — AI-Perceivable Distributed         │
│           Orchestration Engine                │
│                                              │
│  ┌── Protocol Exposure (apcore) ───────────┐ │
│  │ apcore-mcp · apcore-a2a · apcore-cli    │ │
│  │              ↕                          │ │
│  │       apcore Registry (Modules)         │ │
│  └──────────────┬──────────────────────────┘ │
│                 │                             │
│  ┌──────────────▼──────────────────────────┐ │
│  │  Orchestration Core                     │ │
│  │  TaskManager · TaskCreator · Scheduler  │ │
│  │  Dependency Graphs · Priority · DAG     │ │
│  ├─────────────────────────────────────────┤ │
│  │  Durability    │  Governance            │ │
│  │  Checkpoint    │  Budget · Policy       │ │
│  │  Retry         │  Model Downgrade       │ │
│  │  Circuit Break │  Usage Reporting       │ │
│  ├─────────────────────────────────────────┤ │
│  │  Infrastructure                         │ │
│  │  SQLite/PostgreSQL · Distributed Runtime│ │
│  │  ConfigManager · Adapters               │ │
│  └─────────────────────────────────────────┘ │
└──────────────────────────────────────────────┘
```

apcore is not a separate layer — it's embedded inside apflow as the mechanism that makes orchestration capabilities AI-perceivable (like a CAN bus makes car systems perceivable to FSD).

## Built-in Executors

| Executor | Purpose |
|----------|---------|
| RestExecutor | HTTP/REST API calls (example executor) |
| AggregateResultsExecutor | Combine results from dependency tasks |
| ApFlowApiExecutor | Inter-instance orchestration (cluster) |
| SendEmailExecutor | Email notifications |

These are examples and utilities. The real executors are your AI agents, business logic, or any `ExecutableTask` implementation.

## Documentation

- [PRD](docs/prd.md) — Product requirements
- [Tech Design](docs/tech-design.md) — Architecture and design
- [Feature Specs](docs/features/overview.md) — Implementation specifications

## Contributing

Contributions welcome. Please open an issue or PR on GitHub.

## License

Apache-2.0

## Links

- **Website**: [aiperceivable.com](https://aiperceivable.com)
- **GitHub**: [aiperceivable/apflow](https://github.com/aiperceivable/apflow)
- **PyPI**: [apflow](https://pypi.org/project/apflow/)
