{"repo": "alikon-art/determinflow", "files": {"README.en.md": {"38af3aa0aff3fa65fbb28915050ce27e691b37b7": {"t": 1786068580.9930716, "n": 13989, "h": "367b8a97096406dd", "c": "
\n\n

\n \n \n \"DeterminFlow\"\n \n

\n\n

Deterministic workflows for probabilistic AI.

\n\n

Build, validate, recover, and ship complex AI workflows as dependable services.

\n\n

\n \"Release\"\n \"CI\"\n \"License:\n \"Python\n

\n\n

\n Why DeterminFlow ·\n Case study ·\n Features ·\n Quick start ·\n Plugins ·\n Community\n

\n\n

English · 简体中文

\n\n
\n\n

\n \n \"The\n \n

\n\n

A real chapter-production workflow: direction, context, specialist writers, synthesis, validation, rendering, and persistence.

\n\nDeterminFlow is a production-oriented AI workflow runtime. It turns LLM calls, scripts, APIs,\ndatabase operations, and human approvals into versioned, validated, retryable, recoverable, and\nauditable workflows.\n\nEach Agent owns one clearly bounded node: it receives only the context and tools needed for that\nstep and returns a verifiable result. DeterminFlow owns control flow, data flow, retries, and recovery.\n\n> DeterminFlow has already been validated in the real AI novel production pipeline behind\n> [NovelBuilt](https://novelbuilt.com/).\n\n\n\n## Why not just use Codex, Claude, or another single-agent framework?\n\nCodex, Claude, and similar single-agent frameworks are excellent when the path is unknown. Once a\nprocess is clear, asking one Agent to reread the full context, remember every step, and call every\ntool usually makes the job slower, more expensive, and harder to maintain.\n\n| Problem | Codex, Claude, and similar single-agent frameworks | DeterminFlow |\n|---|---|---|\n| Change the process | Edit prompts, skills, and natural-language constraints | Change versioned nodes, variables, branches, and subprocesses |\n| Isolate context | Long runs typically carry a growing history forward | Each Agent Node sees only its local context |\n| Enforce structured output | Rely on the model to keep following the agreement | Structured outputs, script validation, automatic repair, and targeted retries |\n| Handle failures | Decide manually where to restart | Resume from the failed node without rerunning completed work |\n| Limit permissions | One Agent typically receives the tools needed by the whole process | Each node receives only the tools it needs |\n| Audit cost | Usage is typically aggregated around the whole task | Account for every node, attempt, and model call separately |\n| Ship the result | Build an additional delivery layer | Package it as an API, background service, Automation, or Plugin |\n\nThe difference is practical:\n\n- **Faster development:** Combine reliable nodes, validate the flow, then connect it to an API or service.\n- **Easier maintenance:** Processes, parameters, and outputs have a stable structure instead of living in one large prompt.\n- **More stable execution:** Models handle judgment while the Runtime owns control flow and data flow.\n- **No full restart after failure:** Audit, retry, and recover any node without rerunning a long process from the beginning.\n- **Fewer tokens:** Each model reads only the context it needs instead of repeatedly carrying the full history.\n- **Smaller permissions:** Tools can be narrowed per node, with stronger LLM workspace sandboxing on the Roadmap.\n\n\n\n## Case study: saving 70%–89% of tokens in AI novel chapter production\n\n[NovelBuilt](https://novelbuilt.com/) uses DeterminFlow to coordinate a chapter-production pipeline\nwith directors, world-state and character maintenance, specialist writers, synthesis, validation,\nrendering, and persistence.\n\nOne completed production task used **11 isolated model sessions**. A single run in DeterminFlow\nconsumed **176,584 tokens**. If the same process were handled by one long-chain Agent carrying\nrepeated context, tool results, and repair loops, estimated token usage could reach **9.1×** that of\nDeterminFlow:\n\n| Single-agent scenario | Estimated total tokens | Relative to DeterminFlow | DeterminFlow saving | Terra API equivalent | Sol API equivalent |\n|---|---:|---:|---:|---:|---:|\n| Highly optimized, almost no extra tool loops | ~595K | 3.4× | ~70% | $0.90 | $2.26 |\n| Typical tool calls and context growth | ~970K | 5.5× | ~82% | $1.47 | $3.68 |\n| Validation repair, retries, or long context | ~1.61M | 9.1× | ~89% | $2.43 | $6.08 |\n\n> Estimated from the real Workflow token ledger plus repeated context, tool output, and repair-loop\n> overhead in a long-chain Agent; API prices reflect the rates used at the time of estimation.\n\nIn this real production workflow, node-level context isolation is estimated to reduce token usage by\nroughly **70%–89%**.\n\n\n\n## DeterminFlow's core capabilities\n\n### Workflow authoring\n\n- Visual Workflow Editor with variables, conditions, parallel branches, loops, approvals, and subprocesses\n- Agent, Script, Approval, and Subprocess Core Nodes\n- Per-node inputs, outputs, model selection, and failure policy\n- A general Core Node abstraction for contributors and forks that need new node types\n\n### Reliable execution\n\n- Frozen Workflow definitions and inputs for every running task\n- Automatic retry, manual retry, skip, and resume from the failed node\n- Persistent checkpoints across process restarts\n- Independent attempt history for parallel branches, loops, and subprocesses\n\n### LLM boundaries\n\n- Isolated sessions and token ledgers for every Agent Node\n- Per-node tool allowlists, denylists, workspace configuration, and maximum turns\n- JSON detection, parsing, repair, and model retry\n- Directed upstream rejection when a downstream node needs a specific result corrected\n\n### Delivery and operations\n\n- Usage and status views across Workflow, Task, Node, attempt, and model call\n- FastAPI endpoints, React control plane, Cron Automation, WebSocket events, and health checks\n- MCP tools, Prompt and Agent templates, Skills, and Rules as reusable Workflow building blocks\n- A standalone Core that does not require any product plugin\n\n### One workspace around the Workflow\n\nConversation, Workflow authoring, Cron, Skills, Rules, and Plugins live in one control plane.\n\n![DeterminFlow control plane](docs/assets/screenshots/console-home.png)\n\n## How it works\n\n```mermaid\nflowchart LR\n I[\"API / Event / Manual Input\"] --> W[\"Versioned Workflow\"]\n W --> A[\"Agent Node
local context + minimum tools\"]\n A --> V[\"Output validation\"]\n V -->|\"invalid\"| A\n V -->|\"valid\"| S[\"Script / API / Database\"]\n S --> C[\"Checkpoint + audit trail\"]\n C --> O[\"API / Service / Plugin Output\"]\n```\n\n1. Freeze the Workflow, parameters, and node inputs when a task starts.\n2. Run each Agent Node in an independent session with only the tools it needs.\n3. Repair, retry, skip, or request human input when an output fails validation.\n4. Use Script Nodes for deterministic work such as file conversion, API calls, and persistence.\n5. Store every attempt, error, token record, artifact, and checkpoint so execution can resume safely.\n\n\n\n## Extension: deliver complete AI products as Plugins\n\nDeterminFlow handles process execution. Plugins package the process with everything it needs to ship.\nCommon use cases include:\n\n| Use case | What a Plugin can ship with it |\n|---|---|\n| Let a team or community install a mature process | Workflows, Agents, Prompts, Skills, Rules, and preset phrases |\n| Turn a process into a callable business service | APIs, managed background processes, configuration, health checks, and lightweight pages |\n| Deliver a stateful product workflow | Script Libraries, database migrations, persistence, and recovery logic |\n\n### Official plugins and an open-source case study\n\nOfficial plugins live in\n[`DeterminFlow-Plugins`](https://github.com/alikon-art/DeterminFlow-Plugins). The\n[`bishu-novel`](https://github.com/alikon-art/DeterminFlow-Plugins/tree/main/plugins/bishu-novel)\npackage is an open-source AI novel Workflow case drawn from NovelBuilt's production pipeline. Its\ncurrent public release contains:\n\n| Production Workflows | Orchestration nodes | Agent / Prompt pairs | Reusable script modules |\n|---:|---:|---:|---:|\n| 7 | 84 | 33 | 15 |\n\nIt covers book setup, characters, story planning, volume and near-term outlines, chapter production,\npost-hoc state updates, and polishing, together with APIs, SSE jobs, PostgreSQL migrations, and\ncheckpoint recovery. Plugins are the best way to package and deliver a complete AI business engine.\n\n> [!NOTE]\n> Plugins compose Workflows from existing Core Nodes. Developers who need a new node type can fork\n> Core and extend the general Node abstraction.\n\n> **Security note:** Plugins currently run as trusted local code without sandbox isolation. Install\n> only trusted sources. Stronger per-node LLM and workspace sandboxing remains on the Roadmap.\n\n\n\n## Quick start 🚀\n\nPython 3.11+, Node.js 22.12+, and npm are required. Choose the commands for your system.\n\n### macOS / Linux\n\n```bash\ngit clone https://github.com/alikon-art/DeterminFlow.git\ncd DeterminFlow\npython -m venv .venv\nsource .venv/bin/activate\npython -m pip install -r requirements.lock\ncp .env.example .env\ncp config/models_config.example.json config/models_config.json\npython run.py\n```\n\n### Windows PowerShell\n\n```powershell\ngit clone https://github.com/alikon-art/DeterminFlow.git\nSet-Location DeterminFlow\npython -m venv .venv\n.\\.venv\\Scripts\\python.exe -m pip install -r requirements.lock\nCopy-Item .env.example .env\nCopy-Item config\\models_config.example.json config\\models_config.json\n.\\.venv\\Scripts\\python.exe run.py\n```\n\nYou can start first and enter the API key on the Settings page. Alternatively, set\n`DEEPSEEK_API_KEY` in `.env`; the model configuration reads it through\n`${DEEPSEEK_API_KEY}`.\n\nThen open:\n\n- Web UI: `http://localhost:8020`\n- API docs: `http://localhost:8020/docs`\n- Plugin status: `GET /api/extensions`\n\nOr start with Docker:\n\n```bash\ndocker compose up --build\n```\n\nNew configuration uses the `DETERMINFLOW_*` prefix. Existing `AI_COMPANY_*` environment variables\nand the `ai_company.extensions` entry-point group remain supported as compatibility aliases; the new\nname wins when both are set.\n\n## Documentation\n\n- [Architecture](docs/architecture.md)\n- [Plugin Package specification](docs/plugin-packages.md)\n- [Extension development guide](docs/extension-development.md)\n\n## Development\n\n```bash\npython -m pip install -r requirements-dev.lock\npython -m pytest -q\n(cd web && npm run lint && npm run test:extensions && npm run build)\ndocker compose -f docker-compose.yml config -q\n```\n\n\n\n## Community and collaboration\n\n| If you want to... | Start here |\n|---|---|\n| Report a bug or suggest a feature | [GitHub Issues](https://github.com/alikon-art/DeterminFlow/issues) |\n| Discuss usage, Workflows, and Plugin development | Join the QQ or WeChat group below |\n| Request custom Workflow or Plugin development, private deployment, or product integration | WeChat `Reactive404` · [Email](mailto:alikon.art@qq.com?subject=DeterminFlow%20cooperation) |\n\n### Join the group chat\n\n\n \n \n \n \n \n \n \n \n \n \n \n \n
QQ groupWeChat group
\"NovelBuilt\"NovelBuilt
Group ID: 945515407Temporary QR code, valid through August 9, 2026
\n\n## Roadmap\n\n- Complete the remaining internal compatibility-name migration to DeterminFlow\n- Add stronger per-node workspace and LLM execution sandboxes\n- Provide reusable templates for publishing a Workflow as an independent API or service\n- Add more reproducible production Workflow examples\n- Define the compatibility and versioning policy beyond `v0.1.0`\n\n## License\n\nDeterminFlow is licensed under the\n[GNU AGPL v3](https://github.com/alikon-art/DeterminFlow/blob/main/LICENSE) (`AGPL-3.0-only`).\n\n---\n\n

\n Created and maintained by alikon-art.
\n Built from the production workflow needs behind NovelBuilt.\n

\n"}}}}