Cascade

English | 中文 | 日本語 | Español

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

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

# As a Python library
pip install cascade-auto

For development:

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

Quick Start

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:

{
  "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

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.

All mutation tools support reason for event log audit.

Context Flow

Three channels, each upstream entry attributed with provenance:

Cancellation

One semantic, two implementations:

Both use the CancelNotifier protocol for push notifications.

Running Tests

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

Documentation

• Guide — comprehensive usage walkthrough
• Architecture — system design, state machine, Mermaid diagrams
• CONTRIBUTING.md — development guidelines
• SECURITY.md — vulnerability reporting and security model

License

Apache-2.0 — see LICENSE.