Metadata-Version: 2.4
Name: cascade-auto
Version: 0.4.10
Summary: An agent factory with dynamic DAG scheduling for multi-agent task coordination
Project-URL: Homepage, https://github.com/autoseek-ai/Cascade
Project-URL: Repository, https://github.com/autoseek-ai/Cascade
Project-URL: Issues, https://github.com/autoseek-ai/Cascade/issues
Project-URL: Documentation, https://github.com/autoseek-ai/Cascade/blob/main/docs/guide.md
Author-email: Autoseek <dev@autoseek.vip>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,dag,llm,multi-agent,orchestration,scheduling
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
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Requires-Dist: filelock>=3.12.0
Requires-Dist: typing-extensions>=4.9.0
Provides-Extra: dev
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# Cascade

[![CI](https://github.com/autoseek-ai/Cascade/actions/workflows/ci.yml/badge.svg)](https://github.com/autoseek-ai/Cascade/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/)

**English** | [中文](docs/i18n/README.zh-CN.md) | [日本語](docs/i18n/README.ja.md) | [Español](docs/i18n/README.es.md)

An agent factory with dynamic DAG scheduling. Orchestrators build and adapt task graphs in real time while stateless workers claim, execute, and deliver — coordinating through contracts on edges and attributed context flow.

## Key Features

- **Dynamic DAG** — split, rework, refine, remove tasks mid-execution
- **Attributed context** — each upstream contribution kept separate with provenance (path, distance, contract)
- **Contract-driven edges** — every edge carries `expectation` (consumer needs) and `promise` (producer delivers)
- **Critical path scheduling** — READY tasks prioritized by downstream depth
- **Cancellation protocol** — pull (check token) or push (CancelNotifier) across processes
- **ACTIVE protection** — cannot remove/split nodes with active agents
- **Event sourcing** — every mutation recorded with optional `reason` for audit

## Installation

```bash
# As a CLI tool
pipx install cascade-auto
# or
uv tool install cascade-auto

# As a Python library
pip install cascade-auto
```

For development:

```bash
git clone https://github.com/autoseek-ai/Cascade.git
cd Cascade
uv sync
```

## Quick Start

```python
from cascade import CascadeClient, Contract

cascade = CascadeClient()

# Build a task graph — split horizontally for parallelism
cascade.add("analyze")
cascade.add("design", deps={
    "analyze": Contract("Feature requirements and constraints", "Deliver prioritized feature list"),
})

# Agent claims a task — critical path first
r = cascade.claim("agent-001")

# Complete with context that flows to downstream agents
# Framework auto-injects produced_at and git_ref into critical
cascade.complete("analyze",
    summary="Requirements: JWT auth + REST API",
    critical={"auth_type": "JWT", "endpoints": ["/users", "/posts"]},
)
```

When `agent-002` claims `design`, it sees:

```json
{
  "upstream": [{
    "node_id": "analyze",
    "state": "COMPLETED",
    "distance": 1,
    "expectation": "Feature requirements and constraints",
    "promise": "Deliver prioritized feature list",
    "delivered": {
      "summary": "Requirements: JWT auth + REST API",
      "critical": {
        "auth_type": "JWT",
        "endpoints": ["/users", "/posts"],
        "produced_at": 1778050765.98,
        "git_ref": "a3f8c2e..."
      }
    }
  }]
}
```

No merging, no overwriting — each upstream source is a separate entry.

## Architecture

```
types → core → context → view → operations → tools → client
```

| Package | Purpose |
|---------|---------|
| `types` | Value types: `Contract`, `Context`, `ContextEntry`, `TokenStatus` |
| `core` | `Cascade` graph, `Node`, `NodeState` (6-state FSM) |
| `context` | BFS ancestor propagation + cancellation (in-process) |
| `view` | Upstream view builder (`get_node_view`) |
| `events` | Append-only event log (14 event types) |
| `operations` | Compound mutations: Split, Remove, Rework |
| `storage` | JSON persistence + file locking + token store |
| `tools` | 12 LLM-facing functions — the dict-based serialization boundary |
| `client` | `CascadeClient` — typed Python API wrapping tools with IDE support |

## Tools

The typed Python API is `CascadeClient`. All methods return `Result`; typed projections via `TaskView.from_result()` and `NodeInfo.list_from_result()`. The underlying tool layer uses `(StorageProtocol, dict) → dict` signatures for CLI and JSON boundaries.

| Category | Tools |
|----------|-------|
| Structure | `add_node`, `remove_node`, `split_node`, `refine_node`, `edit_node` |
| Execution | `get_task`, `finish_task` |
| Feedback | `rework` |
| Cancellation | `check_task` |
| Monitoring | `check_timeouts` |
| Query | `list_nodes`, `history` |

All mutation tools support `reason` for event log audit.

## Context Flow

Three channels, each upstream entry attributed with provenance:

| Channel | Propagation | Use for |
|---------|-------------|---------|
| `critical` | Indefinite | Structured KV data (decisions, configs) |
| `summary` | 2 hops | Brief text description |
| `artifacts` | Indefinite | Full documents, code, specs |

## Cancellation

One semantic, two implementations:

| Scenario | Mechanism |
|----------|-----------|
| Cross-process (CLI, multi-machine) | `TokenStore` — file-backed `.cascade/tokens/` |
| In-process (framework embedding) | `CancellationToken` — memory, instant callbacks |

Both use the `CancelNotifier` protocol for push notifications.

## Running Tests

```bash
uv run pytest tests/        # 298 tests
uv run ruff check src tests  # lint
```

## Documentation

- [Guide](docs/guide.md) — comprehensive usage walkthrough
- [Architecture](docs/architecture.md) — system design, state machine, Mermaid diagrams
- [CONTRIBUTING.md](CONTRIBUTING.md) — development guidelines
- [SECURITY.md](SECURITY.md) — vulnerability reporting and security model

## License

Apache-2.0 — see [LICENSE](LICENSE).
