{"id":47591366,"url":"https://github.com/folkadonis/flowk","last_synced_at":"2026-04-01T17:30:12.574Z","repository":{"id":345262350,"uuid":"1185137762","full_name":"folkadonis/flowk","owner":"folkadonis","description":"Flowk is a lightweight, high-performance workflow orchestration engine built for AI and LLM pipelines. It provides a simpler, developer-first alternative to complex frameworks like LangGraph, with native support for async execution, parallel DAGs, Pydantic state validation, conditional routing, human-in-the-loop interrupts, session memory, SQLite c","archived":false,"fork":false,"pushed_at":"2026-03-18T12:17:11.000Z","size":25,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-19T00:58:26.667Z","etag":null,"topics":["flowk","langcha","langraph","llm","python"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/flowk/0.1.0/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/folkadonis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"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":null,"dco":null,"cla":null}},"created_at":"2026-03-18T09:22:57.000Z","updated_at":"2026-03-18T12:16:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/folkadonis/flowk","commit_stats":null,"previous_names":["folkadonis/flowk"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/folkadonis/flowk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folkadonis%2Fflowk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folkadonis%2Fflowk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folkadonis%2Fflowk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folkadonis%2Fflowk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/folkadonis","download_url":"https://codeload.github.com/folkadonis/flowk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/folkadonis%2Fflowk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290537,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["flowk","langcha","langraph","llm","python"],"created_at":"2026-04-01T17:30:11.779Z","updated_at":"2026-04-01T17:30:12.475Z","avatar_url":"https://github.com/folkadonis.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Flowk 🌊\n\n[![PyPI version](https://img.shields.io/pypi/v/flowk.svg)](https://pypi.org/project/flowk/)\n[![Python](https://img.shields.io/pypi/pyversions/flowk.svg)](https://pypi.org/project/flowk/)\n[![CI](https://github.com/folkadonis/flowk/actions/workflows/python-package.yml/badge.svg)](https://github.com/folkadonis/flowk/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n**Flowk** is a lightweight, high-performance workflow orchestration engine specifically designed for AI and LLM pipelines. It offers a simpler, developer-first alternative to complex frameworks like LangGraph. \n\nEverything you need to build Enterprise Agentic Workflows is packed into pure, readable Python: async execution, dynamic routing, CLI visualizers, SQLite/Redis time-travel, Pydantic type-safety, API deployments, streaming, and a local Observability UI.\n\n---\n\n## 🚀 All Features\n\n### Core Execution\n- **Extremely Simple API:** Turn standard Python functions into executable graph nodes effortlessly.\n- **Node Resiliency:** Configure Node retries, timeouts, and fallback policies automatically (`@g.node(retries=3)`).\n- **Standard Routing:** Route branch paths explicitly using standard Python functions (`g.route()`).\n- **🛡️ Type-Safety:** Graph states are strictly validated upon every transition using `Pydantic`.\n- **⚡ Async \u0026 Streaming:** Natively await APIs and stream real-time events (`g.astream()`).\n- **Parallel Fan-Out:** Split a node into three; Flowk natively runs them exactly concurrently via `asyncio.gather`.\n\n### Intelligence\n- **🧠 Zero-Boilerplate Auto-Routing:** Eliminate `if/else` logic by letting OpenAI/Anthropic pick your exact graph branches using strictly validated zero-shot classification (`@g.llm_router`).\n- **📦 Multi-Agent Composition:** Build nested agent networks by packaging entire sub-graphs as natively executable Nodes (`g.as_node()`).\n\n### Developer Experience \u0026 Tooling\n- **🛑 Human-in-the-Loop:** Set breakpoints to pause execution and later resume the exact thread stacks.\n- **🚀 1-Click API Deployment:** Turn any Flowk `.py` into a fully typed FastAPI instance in milliseconds (`g.serve()`).\n- **Terminal Visualization:** Render beautiful CLI graphs of your execution layout (`g.show()`).\n- **Time Travel Replays:** Encounter a bug? Flowk traces everything. Replay historical executions in debug mode (`g.replay()`).\n- **📊 Observability Dashboard:** Track sessions and modify global Graph context visually through the local Streamlit dashboard (`flowk ui`).\n- **🧩 Pluggable Metrics:** Hook models (e.g. OpenAIPlugin) into `MetricsRegistry` to precisely track token consumption and cost.\n\n---\n\n## 📦 Installation\n\nFlowk is modular by design.\n\n```bash\n# Core execution engine\npip install flowk\n\n# Add-ons:\npip install \"flowk[api]\"    # 1-Click FastAPI Deployment\npip install \"flowk[ui]\"     # Streamlit Observability Dashboard\npip install \"flowk[llm]\"    # Auto-Router \u0026 Token Metrics\npip install \"flowk[redis]\"  # Distributed Persistence\n\n# Install Everything\npip install \"flowk[all]\"\n```\n\n---\n\n## ⚡ Quick Start\n\nBuilding your first AI agent pipeline with Flowk takes less than a minute.\n\n```python\nimport asyncio\nfrom pydantic import BaseModel\nfrom flowk import Graph\n\n# 1. Define strict state\nclass AgentState(BaseModel):\n    query: str\n    processed: bool = False\n\ng = Graph(state_schema=AgentState)\n\n# 2. Define Nodes\n@g.node(retries=3)  # Built-in resiliency\nasync def intake(query: str, state: dict):\n    state[\"query\"] = query\n    print(f\"📥 Received: {query}\")\n    return query\n\n@g.node()\nasync def agent(query: str, state: dict):\n    state[\"processed\"] = True\n    print(\"🤖 Processing context...\")\n    return f\"Processed Output for {query}\"\n\n# 3. Connect nodes\ng.connect(intake, agent)\n\n# 4. View Architecture\ng.show()\n\n# 5. Run async pipeline\nif __name__ == \"__main__\":\n    result = asyncio.run(g.arun(\"Calculate the speed of light.\"))\n```\n\n---\n\n## 🧠 Zero-Boilerplate LLM Auto-Routing\n\nWhy write manual `if/else` logic when LLMs can intelligently route workflows based directly on your docstrings? Flowk handles the prompts and the deterministic structured outputs for you.\n\n```python\n@g.llm_router(\n    model=\"gpt-4o-mini\",\n    targets={\n        \"math_node\": \"Use this if the query contains numbers or equations.\",\n        \"search_node\": \"Use this if the user asks for real-time news.\"\n    }\n)\ndef supervisor_router(state: dict):\n    return state.get(\"query\", \"\")\n\ng.connect(parse_input, supervisor_router) \n```\n\n---\n\n## 🚀 1-Click API Gen (FastAPI)\n\nSkip writing API boilerplate. Flowk automatically converts your Graph and Pydantic models into a fully validated FastAPI instance with `/docs`, `/invoke`, and `/stream`.\n\n```python\n# Launch app\ng = Graph(state_schema=MyState)\ng.connect(A, B)\n\nif __name__ == \"__main__\":\n    g.serve(host=\"0.0.0.0\", port=8000)\n```\n\nInvoke your pipeline instantaneously:\n```bash\ncurl -X POST \"http://localhost:8000/invoke\" \\\n     -H \"Content-Type: application/json\" \\\n     -d '{\"initial_state\": {\"user_id\": 123}, \"input_data\": \"Search for X\"}'\n```\n\n---\n\n## 🛑 Human-in-The-Loop (Interrupts)\n\nCreate breakpoints in your workflows. Execution suspends gracefully to allow human review (e.g. paying an invoice), letting you resurrect the session precisely where you left off.\n\n```python\n# Set visual breakpoint\ng.compile(interrupt_before=[\"commit_payment_node\"])\n\n# Run pipeline until suspended\nfor event in g.astream(input_data, session_id=\"user_john\"):\n    if event[\"type\"] == \"interrupt\":\n        print(\"Payment halted. Waiting for human approval...\")\n\n# Resume from checkpoint using identical session_id\ng.arun(None, session_id=\"user_john\")\n```\n\n---\n\n---\n\n## 📊 Observability Dashboard \u0026 Persistence\n\nFlowk effortlessly saves run-histories exactly as they mutate across node transactions.\n\n```python\n# Native Memory Configurations\ng = Graph()                                         # Ephemeral RAM\ng = Graph(checkpoint_db=\"local_traces.db\")          # SQLite Storage\ng = Graph(checkpoint_db=\"redis://localhost:6379/0\") # Redis\n```\n\nSpin up the native **Production-Grade Dashboard** (v2) to review these checkpoints visually with interactive graph topology and state diffing:\n```bash\nflowk ui\n# Launches at http://localhost:8502\n```\n\nThe new dashboard provides:\n- **Interactive SVG Graphs**: Visualize your workflow logic and execution paths.\n- **State Diff Engine**: Compare state snapshots step-by-step.\n- **Session History**: Browse and resume historical agent runs from SQLite/Redis.\n\n---\n\n## 📦 Multi-Agent Composition\n\nBuild powerful hierarchical orchestrations by compiling smaller sub-graphs and mounting them identically as nodes within a massive supervisor pipeline.\n\n```python\n# Internal Research Graph\nresearch_graph = Graph()\nresearch_graph.connect(search_web, summarize)\n\n# Packaged perfectly as a Node\nresearch_node = research_graph.as_node(state_key=\"research_metadata\")\n\n# Plugged into Chief Editor Agent\nmain_graph = Graph()\nmain_graph.connect(plan_outline, research_node)\n```\n\n---\n\n## 🐞 Time Travel \u0026 Execution Telemetry\n\nIf a run fails in production, you can trace exactly what inputs hit what nodes.\n\n```python\n# Run your pipeline in debug mode\ng.debug(\"input\", session_id=\"user_1\")\n\n# Encountered a crash? Replay the precise global trajectory:\ng.replay(\"run_id_outputted_by_telemetry\")\n\n# Track Cost Metrics via extensible Plugins\nfrom flowk.plugins.llm import OpenAIPlugin\nfrom flowk import MetricsRegistry\n\nPluginManager.register(OpenAIPlugin(model=\"gpt-4o\"))\nprint(MetricsRegistry.get_summary()) # =\u003e Evaluated 4040 tokens ($0.12)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffolkadonis%2Fflowk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffolkadonis%2Fflowk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffolkadonis%2Fflowk/lists"}