ClearFlow

Correctness-first orchestration for probabilistic AI. Type-safe, deeply immutable, 100% code coverage.

Why ClearFlow?

• Message-driven architecture – Commands trigger actions, Events record facts
• 100% test coverage – Every path verified to work
• Type-safe flows – Full static typing with pyright strict mode
• Deep immutability – All state transformations create new immutable data
• Minimal dependencies – Only Pydantic for validation and immutability
• Single completion – Exactly one end message type per flow

How It Works

ClearFlow uses message-driven orchestration:

Command → Node → Event → Node → Event → End

• Commands request actions: "analyze this portfolio"
• Events record what happened: "risk assessment completed"
• Nodes process messages and emit new ones
• Flows route messages between nodes based on type

Every message knows where it came from (causality tracking), making complex AI orchestration debuggable and testable.

Quick Start

pip install clearflow

Note: ClearFlow is in alpha. Pin your version in production (clearflow==0.x.y) as breaking changes may occur in minor releases.

Real-World Examples

AI Assistant Integration

ClearFlow provides comprehensive documentation in llms.txt format for optimal AI assistant support.

Claude Code Setup

Add ClearFlow documentation to Claude Code with one command:

claude mcp add-json clearflow-docs '{
    "type":"stdio",
    "command":"uvx",
    "args":["--from", "mcpdoc", "mcpdoc", "--urls", "ClearFlow:https://raw.githubusercontent.com/artificial-sapience/clearflow/main/llms.txt"]
}'

For IDEs (Cursor, Windsurf), see the mcpdoc documentation.

ClearFlow vs PocketFlow

Development

Install uv

• Please see official uv docs for other ways to install uv.

curl -LsSf https://astral.sh/uv/install.sh | sh

Clone and set up development environment

git clone https://github.com/artificial-sapience/clearflow.git
cd clearflow
uv sync --all-extras     # Creates venv and installs deps automatically
./quality-check.sh       # Run all checks

License

MIT

Acknowledgments

Inspired by PocketFlow's Node-Flow-State pattern.