clearflow 0.5.0

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

ClearFlow

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

Why ClearFlow?

• Message-driven architecture – Commands trigger actions, Events record facts
• 100% test coverage – Every path proven 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

Example	What It Shows
Chat	Message routing between user and LLM
Portfolio Analysis	DSPy-driven portfolio analysis
RAG	Document processing pipeline

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

Aspect	ClearFlow	PocketFlow
Architecture	Message-driven (Commands/Events)	State-based transformations
State	Immutable messages with causality tracking	Mutable, passed via shared param
Routing	Message type-based explicit routes	Action-based graph edges
Completion	Single end message type	Multiple exits allowed
Type safety	Full static typing with pyright strict	Dynamic (no annotations)

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.