# ClearFlow
[](https://coveralls.io/github/artificial-sapience/clearflow?branch=main)
[](https://pypi.org/project/clearflow/)
[](https://pepy.tech/projects/clearflow)
[](https://raw.githubusercontent.com/artificial-sapience/clearflow/main/llms.txt)
Compose type-safe flows for emergent AI. 100% test coverage, zero dependencies.
## Why ClearFlow?
- **100% test coverage** – Every path proven to work
- **Type-safe transformations** – Errors caught at development time, not runtime
- **Immutable state** – No hidden mutations
- **Zero dependencies** – No hidden failure modes
- **Single exit enforcement** – No ambiguous endings
- **AI-Ready Documentation** – llms.txt for optimal coding assistant integration
## Quick Start
```bash
pip install clearflow
```
> **Upgrading from v0.x?** See the [Migration Guide](MIGRATION.md) for breaking changes.
## AI Assistant Integration
ClearFlow provides comprehensive documentation in [llms.txt](https://llmstxt.org/) format for optimal AI assistant support.
### Claude Code Setup
Add ClearFlow documentation to Claude Code with one command:
```bash
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](https://github.com/langchain-ai/mcpdoc#configuration).
### Direct URL Access
Use these URLs directly in any AI tool that supports llms.txt:
- **Minimal index** (~2KB): <https://raw.githubusercontent.com/artificial-sapience/clearflow/main/llms.txt>
- **Full documentation** (~63KB): <https://raw.githubusercontent.com/artificial-sapience/clearflow/main/llms-full.txt>
## Examples
| Name | Description |
|------|-------------|
| [Chat](examples/chat/) | Simple conversational flow with OpenAI |
| [Portfolio Analysis](examples/portfolio_analysis/) | Multi-specialist workflow for financial analysis |
| [RAG](examples/rag/) | Full retrieval-augmented generation with vector search |
## Core Concepts
### `Node[TIn, TOut]`
A unit that transforms state from `TIn` to `TOut` (or `Node[T]` when types are the same).
- `prep(state: TIn) -> TIn` – optional pre-work/validation
- `exec(state: TIn) -> NodeResult[TOut]` – **required**; return new state + outcome
- `post(result: NodeResult[TOut]) -> NodeResult[TOut]` – optional cleanup/logging
Nodes are frozen dataclasses that execute async transformations without mutating input state.
### `NodeResult[T]`
Holds the **new state** and an **outcome** string used for routing.
### `flow()`
A function that creates a flow with **explicit routing**:
```python
flow("Name", start_node)
.route(start_node, "outcome1", next_node)
.route(next_node, "outcome2", final_node)
.end(final_node, "done") # exactly one termination
```
**Routing**: Routes are `(node, outcome)` pairs. Each outcome must have exactly one route.
**Type inference**: The flow infers types from start to end, supporting transformations.
**Composability**: A flow is itself a `Node` – compose flows within flows.
## ClearFlow vs PocketFlow
| Aspect | ClearFlow | PocketFlow |
|--------|-----------|------------|
| **State** | Immutable, passed via `NodeResult` | Mutable, passed via `shared` param |
| **Routing** | Outcome-based explicit routes | Action-based graph edges |
| **Termination** | Exactly one exit enforced | Multiple exits allowed |
| **Type safety** | Full Python 3.13+ generics | Dynamic (no annotations) |
ClearFlow emphasizes **robust, type-safe orchestration** with validation and guardrails. PocketFlow emphasizes **brevity and flexibility** with minimal overhead.
## Development
### Install uv
- Please see [official uv docs](https://docs.astral.sh/uv/getting-started/installation/#installation-methods) for other ways to install uv.
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
### Clone and set up development environment
```bash
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](LICENSE)
## Acknowledgments
Inspired by [PocketFlow](https://github.com/The-Pocket/PocketFlow)'s Node-Flow-State pattern.
Raw data
{
"_id": null,
"home_page": null,
"name": "clearflow",
"maintainer": "ClearFlow Contributors",
"docs_url": null,
"requires_python": ">=3.13",
"maintainer_email": null,
"keywords": "agents, ai-agents, async, language-models, orchestration, reliable, type-safe, zero-dependencies",
"author": null,
"author_email": "Richard Beauchamp <rbeauchamp@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/41/7c/99c307e53d411ae2eb87993013b34ac1645d0d77ec089794cb1dff8d676a/clearflow-1.0.3.tar.gz",
"platform": null,
"description": "# ClearFlow\n\n[](https://coveralls.io/github/artificial-sapience/clearflow?branch=main)\n[](https://pypi.org/project/clearflow/)\n[](https://pepy.tech/projects/clearflow)\n\n\n[](https://raw.githubusercontent.com/artificial-sapience/clearflow/main/llms.txt)\n\nCompose type-safe flows for emergent AI. 100% test coverage, zero dependencies.\n\n## Why ClearFlow?\n\n- **100% test coverage** \u2013 Every path proven to work\n- **Type-safe transformations** \u2013 Errors caught at development time, not runtime\n- **Immutable state** \u2013 No hidden mutations\n- **Zero dependencies** \u2013 No hidden failure modes\n- **Single exit enforcement** \u2013 No ambiguous endings\n- **AI-Ready Documentation** \u2013 llms.txt for optimal coding assistant integration\n\n## Quick Start\n\n```bash\npip install clearflow\n```\n\n> **Upgrading from v0.x?** See the [Migration Guide](MIGRATION.md) for breaking changes.\n\n## AI Assistant Integration\n\nClearFlow provides comprehensive documentation in [llms.txt](https://llmstxt.org/) format for optimal AI assistant support.\n\n### Claude Code Setup\n\nAdd ClearFlow documentation to Claude Code with one command:\n\n```bash\nclaude mcp add-json clearflow-docs '{\n \"type\":\"stdio\",\n \"command\":\"uvx\",\n \"args\":[\"--from\", \"mcpdoc\", \"mcpdoc\", \"--urls\", \"ClearFlow:https://raw.githubusercontent.com/artificial-sapience/clearflow/main/llms.txt\"]\n}'\n```\n\nFor IDEs (Cursor, Windsurf), see the [mcpdoc documentation](https://github.com/langchain-ai/mcpdoc#configuration).\n\n### Direct URL Access\n\nUse these URLs directly in any AI tool that supports llms.txt:\n\n- **Minimal index** (~2KB): <https://raw.githubusercontent.com/artificial-sapience/clearflow/main/llms.txt>\n- **Full documentation** (~63KB): <https://raw.githubusercontent.com/artificial-sapience/clearflow/main/llms-full.txt>\n\n## Examples\n\n| Name | Description |\n|------|-------------|\n| [Chat](examples/chat/) | Simple conversational flow with OpenAI |\n| [Portfolio Analysis](examples/portfolio_analysis/) | Multi-specialist workflow for financial analysis |\n| [RAG](examples/rag/) | Full retrieval-augmented generation with vector search |\n\n## Core Concepts\n\n### `Node[TIn, TOut]`\n\nA unit that transforms state from `TIn` to `TOut` (or `Node[T]` when types are the same).\n\n- `prep(state: TIn) -> TIn` \u2013 optional pre-work/validation \n- `exec(state: TIn) -> NodeResult[TOut]` \u2013 **required**; return new state + outcome \n- `post(result: NodeResult[TOut]) -> NodeResult[TOut]` \u2013 optional cleanup/logging \n\nNodes are frozen dataclasses that execute async transformations without mutating input state.\n\n### `NodeResult[T]`\n\nHolds the **new state** and an **outcome** string used for routing.\n\n### `flow()`\n\nA function that creates a flow with **explicit routing**:\n\n```python\nflow(\"Name\", start_node)\n .route(start_node, \"outcome1\", next_node)\n .route(next_node, \"outcome2\", final_node)\n .end(final_node, \"done\") # exactly one termination\n```\n\n**Routing**: Routes are `(node, outcome)` pairs. Each outcome must have exactly one route. \n**Type inference**: The flow infers types from start to end, supporting transformations. \n**Composability**: A flow is itself a `Node` \u2013 compose flows within flows.\n\n## ClearFlow vs PocketFlow\n\n| Aspect | ClearFlow | PocketFlow |\n|--------|-----------|------------|\n| **State** | Immutable, passed via `NodeResult` | Mutable, passed via `shared` param |\n| **Routing** | Outcome-based explicit routes | Action-based graph edges |\n| **Termination** | Exactly one exit enforced | Multiple exits allowed |\n| **Type safety** | Full Python 3.13+ generics | Dynamic (no annotations) |\n\nClearFlow emphasizes **robust, type-safe orchestration** with validation and guardrails. PocketFlow emphasizes **brevity and flexibility** with minimal overhead.\n\n## Development\n\n### Install uv\n\n- Please see [official uv docs](https://docs.astral.sh/uv/getting-started/installation/#installation-methods) for other ways to install uv.\n\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\n### Clone and set up development environment\n\n```bash\ngit clone https://github.com/artificial-sapience/clearflow.git\ncd ClearFlow\nuv sync --all-extras # Creates venv and installs deps automatically\n./quality-check.sh # Run all checks\n```\n\n## License\n\n[MIT](LICENSE)\n\n## Acknowledgments\n\nInspired by [PocketFlow](https://github.com/The-Pocket/PocketFlow)'s Node-Flow-State pattern.\n",
"bugtrack_url": null,
"license": null,
"summary": "Compose type-safe flows for emergent AI",
"version": "1.0.3",
"project_urls": {
"Examples": "https://github.com/artificial-sapience/clearflow/tree/main/examples",
"Homepage": "https://github.com/artificial-sapience/clearflow",
"Inspiration": "https://github.com/The-Pocket/PocketFlow",
"Issues": "https://github.com/artificial-sapience/clearflow/issues",
"Repository": "https://github.com/artificial-sapience/clearflow.git",
"Source": "https://github.com/artificial-sapience/clearflow"
},
"split_keywords": [
"agents",
" ai-agents",
" async",
" language-models",
" orchestration",
" reliable",
" type-safe",
" zero-dependencies"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "22643aff5697f7ed9533ad6f1cc52d3707974c0e96c403ccdc56dd62b5b43d20",
"md5": "e6fd358b699166301a225381cd04df5f",
"sha256": "d4d9be77a4a9575e1887d19d924193fe1cbfe004588cc66a682f56274f403d7e"
},
"downloads": -1,
"filename": "clearflow-1.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e6fd358b699166301a225381cd04df5f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.13",
"size": 7603,
"upload_time": "2025-09-11T02:51:25",
"upload_time_iso_8601": "2025-09-11T02:51:25.610740Z",
"url": "https://files.pythonhosted.org/packages/22/64/3aff5697f7ed9533ad6f1cc52d3707974c0e96c403ccdc56dd62b5b43d20/clearflow-1.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "417c99c307e53d411ae2eb87993013b34ac1645d0d77ec089794cb1dff8d676a",
"md5": "08bcacef08099cd18e1afbe10df49dc4",
"sha256": "53c98f8f13fe3dc23ea418c2e8e2419d7028298215f6b434d0fe29ef2c24ce1e"
},
"downloads": -1,
"filename": "clearflow-1.0.3.tar.gz",
"has_sig": false,
"md5_digest": "08bcacef08099cd18e1afbe10df49dc4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.13",
"size": 55020,
"upload_time": "2025-09-11T02:51:26",
"upload_time_iso_8601": "2025-09-11T02:51:26.840589Z",
"url": "https://files.pythonhosted.org/packages/41/7c/99c307e53d411ae2eb87993013b34ac1645d0d77ec089794cb1dff8d676a/clearflow-1.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-11 02:51:26",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "artificial-sapience",
"github_project": "clearflow",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "clearflow"
}
JSON
