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

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

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.