{"id":31527023,"url":"https://github.com/artificial-sapience/clearflow","last_synced_at":"2026-01-20T17:53:00.754Z","repository":{"id":308049555,"uuid":"1031459059","full_name":"artificial-sapience/clearflow","owner":"artificial-sapience","description":"Correctness-first orchestration for emergent AI. Type-safe, deeply immutable, 100% code coverage.","archived":false,"fork":false,"pushed_at":"2025-09-24T02:48:18.000Z","size":643,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-24T04:24:47.013Z","etag":null,"topics":["agentic-ai","agentic-framework","agentic-workflow","agents","ai-framework","ai-frameworks","artificial-intelligence","dspy","functional-programming","immutable","large-language-model","large-language-models","llm","llm-agent","message-driven","mission-critical","pocketflow","pydantic","python","type-safety"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/artificial-sapience.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-08-03T19:31:07.000Z","updated_at":"2025-09-21T17:02:33.000Z","dependencies_parsed_at":"2025-08-18T21:30:53.691Z","dependency_job_id":"cddc2e0c-2de7-466c-a024-fe957c76b2a7","html_url":"https://github.com/artificial-sapience/clearflow","commit_stats":null,"previous_names":["consent-ai/clearflow","sociocratic-ai/clearflow"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/artificial-sapience/clearflow","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artificial-sapience%2Fclearflow","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artificial-sapience%2Fclearflow/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artificial-sapience%2Fclearflow/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artificial-sapience%2Fclearflow/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/artificial-sapience","download_url":"https://codeload.github.com/artificial-sapience/clearflow/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/artificial-sapience%2Fclearflow/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":276706300,"owners_count":25689959,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-24T02:00:09.776Z","response_time":97,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","agentic-framework","agentic-workflow","agents","ai-framework","ai-frameworks","artificial-intelligence","dspy","functional-programming","immutable","large-language-model","large-language-models","llm","llm-agent","message-driven","mission-critical","pocketflow","pydantic","python","type-safety"],"created_at":"2025-10-03T21:19:44.724Z","updated_at":"2025-10-03T21:19:45.458Z","avatar_url":"https://github.com/artificial-sapience.png","language":"Python","readme":"# ClearFlow\n\n[![PyPI Downloads](https://static.pepy.tech/personalized-badge/clearflow?period=total\u0026units=INTERNATIONAL_SYSTEM\u0026left_color=BLACK\u0026right_color=GREEN\u0026left_text=downloads)](https://pepy.tech/projects/clearflow)\n[![Coverage Status](https://coveralls.io/repos/github/artificial-sapience/clearflow/badge.svg?branch=main)](https://coveralls.io/github/artificial-sapience/clearflow?branch=main)\n[![PyPI](https://badge.fury.io/py/clearflow.svg)](https://pypi.org/project/clearflow/)\n![Python](https://img.shields.io/badge/Python-3.13%2B-blue)\n![License](https://img.shields.io/badge/License-MIT-yellow)\n[![llms.txt](https://img.shields.io/badge/llms.txt-green)](https://raw.githubusercontent.com/artificial-sapience/clearflow/main/llms.txt)\n\nCorrectness-first orchestration for probabilistic AI. Type-safe, deeply immutable, 100% code coverage.\n\n## Why ClearFlow?\n\n- **Message-driven architecture** – Commands trigger actions, Events record facts\n- **100% test coverage** – Every path verified to work\n- **Type-safe flows** – Full static typing with pyright strict mode\n- **Deep immutability** – All state transformations create new immutable data\n- **Minimal dependencies** – Only Pydantic for validation and immutability\n- **Single completion** – Exactly one end message type per flow\n\n## How It Works\n\nClearFlow uses message-driven orchestration:\n\n```text\nCommand → Node → Event → Node → Event → End\n```\n\n- **Commands** request actions: \"analyze this portfolio\"\n- **Events** record what happened: \"risk assessment completed\"\n- **Nodes** process messages and emit new ones\n- **Flows** route messages between nodes based on type\n\nEvery message knows where it came from (causality tracking), making complex AI orchestration debuggable and testable.\n\n## Quick Start\n\n```bash\npip install clearflow\n```\n\n**Note**: ClearFlow is in alpha. Pin your version in production (`clearflow==0.x.y`) as breaking changes may occur in minor releases.\n\n## Real-World Examples\n\n| Example | What It Shows |\n|---------|---------------|\n| [Chat](examples/chat/) | OpenAI integration with conversation history |\n| [Portfolio Analysis](examples/portfolio_analysis/) | Multi-agent coordination using DSPy |\n| [RAG](examples/rag/) | Document chunking and FAISS vector search |\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## ClearFlow vs PocketFlow\n\n| Aspect | ClearFlow | PocketFlow |\n|--------|-----------|------------|\n| **Architecture** | Message-driven (Commands/Events) | State-based transformations |\n| **State** | Immutable messages with causality tracking | Mutable, passed via `shared` param |\n| **Routing** | Message type-based explicit routes | Action-based graph edges |\n| **Completion** | Single end message type | Multiple exits allowed |\n| **Type safety** | Full static typing with pyright strict | Dynamic (no annotations) |\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","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartificial-sapience%2Fclearflow","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fartificial-sapience%2Fclearflow","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fartificial-sapience%2Fclearflow/lists"}