Deterministic AI Workflow Engine · Interactive Playground
The open-source deterministic DAG orchestration engine & white-box interactive playground built for AI engineers, learners, and builders.
English | 简体中文 | 📖 Quick Start Guide | ⚙️ Configuration
PatchCat is an open-source, deterministic AI workflow orchestration engine and white-box interactive playground created by GuoBug. Designed for AI engineers, product engineers, agent developers, and self-learners, PatchCat transforms complex multi-agent interactions, LLMs, code transforms, and conditional branches into visual, parallelized, and deterministic workflows.
More than a production-grade orchestration engine, PatchCat is an interactive AI engineering playground: test and inspect topological DAG scheduling, self-healing state machines, and fault tolerance mechanisms offline with zero API keys needed. With zero mandatory backend setup (Client-Only BYOK Mode) and direct connectivity to Google Gemini, DeepSeek, OpenAI, SiliconFlow, and local Ollama, PatchCat delivers high-performance AI workflow orchestration and prompt engineering directly inside your browser with enterprise-grade telemetry and zero data leakage.
Note
Core Design Philosophy: Why Deterministic Workflows?
AI models are probabilistic by nature — prone to hallucinations, unexpected schema shifts, and unpredictable costs when left entirely autonomous. PatchCat believes AI should do the heavy lifting of reasoning, drafting, and tool invocation, while a deterministic DAG state machine strictly enforces boundaries, conditional routes, and fallback safeguards.
Tip
💡 PatchCat Core Engineering Axioms
- Defense-in-Depth: "L1 guards physical syntax, L2 guards domain invariants, L3 guards system robustness, and L4 guards scheduler availability. Deterministic orchestration does not rob LLMs of creativity—it equips probabilistic outputs with deterministic engineering airbags."
- Validation vs. Correctness: "Zod only proves 'no violation detected', not 'correct data'. Satisfied ≠ Correct. Un-flagged does not equal correct: naive field freezing locks hallucinations into local optimizer traps."
- Architectural Purity: "If we take this engine code to do a legal contract review workflow, would we need to modify it? If yes -> business logic has leaked into the engine. The core engine must remain strictly domain-blind; business rules belong in Presets."
- Retry vs. Self-Healing: "Retrying without structured feedback merely makes the model spin in the same local minimum (isomorphic retry trap); true self-healing is not 'rerunning blindly', but 're-consulting with diagnostic history'."
- Scientific Attribution: "The gain in end-to-end success rate does not come from the model making fewer errors upfront, but from the effective recovery of the self-healing state machine."
Watch the full end-to-end demo: from client-side API key configuration, drag-and-drop canvas building, real-time topological execution, to interactive chat testing and API publishing.
0915.mp4
PatchCat Visual DAG Canvas — Drag-and-drop workflow builder with real-time LLM token streaming
Why choose PatchCat over heavyweight orchestration tools?
| Feature / Metric | PatchCat 🐱 (Ours) | Flowise | Dify | Langflow |
|---|---|---|---|---|
| Positioning & Learning Barrier | Deterministic Engine + Interactive Playground (Zero-key simulation & white-box inspection) | Production Builder (Black-box) | Production Builder (Black-box) | Experiment Builder (Heavy Setup) |
| Architecture | 100% Client-Side / Edge | Node.js + Backend DB | Python + Celery + Redis + Postgres | Python + Backend DB |
| Deployment Weight | Zero Setup (Static Web / 0MB) | Heavy (Docker Compose) | Enterprise Heavy (~2GB+ Docker) | Heavy (Pip / Docker) |
| Data Privacy | Zero Data Leakage (BYOK In-Browser) | Server-stored Keys | Server-stored Keys | Server-stored Keys |
| Local LLM Support | Direct Ollama Web API | Proxy Bridge Required | Docker Network Configuration | Backend Proxy |
| Execution Engine | Deterministic DAG State Machine (Kahn) | Sequential Graph | Async Event Worker | Directed Graph |
| Cold Start Latency | < 300 ms | 10 ~ 30 s | 30 ~ 60 s | 15 ~ 30 s |
| Memory Footprint | < 35 MB (Browser Tab) | ~300 MB | ~1.5 GB | ~500 MB |
| Code Node Sandbox | Native JS / Isolated Worker | VM2 Sandbox | Python Sandbox | Restricted Python |
- Built-in ReAct Loop: Enclosed
Think -> Act -> Observe -> Thinkcycle with cycle prevention and maxIterations safeguards. - Universal Tool Calling Client: Full support for OpenAI, Gemini, and DeepSeek standard tool schemas with streaming
delta.tool_callsassembly. - Multi-Type Tool Dispatcher: Route to sandboxed JavaScript (
builtin_code), external REST endpoints (builtin_http), or delegate to canvas nodes (canvas_node). - Loop & Sub-Workflow Primitives: Dynamic array batch iterator (
LoopNode) and composite workflow encapsulation (SubWorkflowNode).
- Deterministic DAG Scheduling: Powered by Kahn's topological sort algorithm, executing parallel execution waves while eliminating race conditions and cyclic deadlocks.
- Drag-and-Drop Workflow Canvas: Built on
@xyflow/react(React Flow v12) with 12 specialized node components (Input,Prompt,LLM,Agent,Loop,Sub-Workflow,Code,Output,Knowledge,Condition,Aggregator,HTTP). - Dynamic Conditional Routing & Skipping: IF/ELSE multi-branch evaluation with dynamic downstream skipping (
NODE_SKIPPED) and variable aggregation. - Interactive Chat Debug & API Publishing: Slide-over Chat drawer (
Ctrl+Shift+D) and instant FastAPI REST endpoint generation with API Key auth.
- Direct Cloud & Local LLM Connectivity:
- 🔵 Google Gemini: Full support for
gemini-2.5-flash,gemini-2.5-pro,gemini-2.0-flash, with dynamic model discovery. - 🐳 DeepSeek: Seamless integration with DeepSeek-R1 (with live reasoning/thought streaming) and DeepSeek-V3.
- 🟢 OpenAI: Native support for GPT-4o, GPT-4o-mini, and custom models.
- ⚡ SiliconFlow: High-speed hosted open-source models.
- 🦙 Ollama & Local Models: Direct connection to local LLM instances (Llama 3, Qwen 2.5, Mistral).
- 🛠️ Custom OpenAI-Compatible Endpoints: Connect to any proxy, OneAPI, or self-hosted vLLM instance.
- 🔵 Google Gemini: Full support for
- Cross-Vendor Model Auto-Remapping: Intelligently adapts preset templates to your currently selected provider without broken requests.
- Transient 503 Auto-Retry & Diagnostics: Built-in exponential backoff for high-concurrency spikes and actionable Chinese/English error diagnostics.
- Live Token Streaming: Token-by-token real-time canvas rendering with fluid animations.
- Dual-Stream Reasoning Inspection: Dedicated visualization panel for DeepSeek R1 and Gemini thinking chains.
- Precise Token & Latency Telemetry: Accurate per-node execution duration and token usage calculation.
- In-Browser Safe Execution: Execute custom JavaScript scripts directly in browser sandbox with
inputsandconsole.logcapture. - Automatic JSON Markdown Stripping: Effortlessly parse structured outputs from LLMs wrapped in
```jsonblocks. - Smart Decision Routing: Conditionally dispatch workflows based on intent, urgency, and confidence scores.
- Configurable 3-Level Logging:
Summary (概要): System lifecycle (START,COMPLETE,ERROR), HTTP status codes, latency, and failure traces.Detailed (详细): Node IDs, runtime parameters (model,temperature,max_tokens), and DAG layer wave timing.Dev (开发): Full prompt inputs, intermediate outputs, and LLM responses.
- Zero-Exposure Security Sanitization (
sanitizeData):- Automatic recursive masking of all API Keys (
sk-***,AIzaSy***), Bearer tokens, and password fields across all log levels.
- Automatic recursive masking of all API Keys (
- Collapsible Visual Console Drawer: Built-in IDE-style terminal drawer with search, type filters, JSON payload inspector, and one-click JSON/TXT export.
- Mustache-Style Syntax: Interpolate data with
{{nodeId.propertyPath}}. - Deep Object & Array Navigation: Access nested fields such as
{{classifier.result.tags[0].name}}. - Fallback Defaults: Built-in fallback syntax
{{nodeId.output | "default_value"}}to safeguard against missing values.
- IndexedDB Asynchronous Persistence: High-capacity, non-blocking browser client storage overcoming 5MB
sessionStoragelimits and tab-closure data loss. - Workflow-Scoped Isolation: Messages are strictly partitioned by
${workflowId}::${sessionId}to prevent cross-canvas contamination during testing. - Tier-1 Global Policy & 2-Tier Configuration: Configure global defaults in Settings (
SettingsPage.tsx) for sliding window rounds (1–20), token budget limit (500–16,000), and pruning strategies (hybrid,window,token_budget). - Dynamic Context Injection: Automatically prunes historical dialogue and injects formatted multi-turn context into
{{chat_history}},{{conversation_history}}, and{{history}}variable slots. - Storage Architecture FAQ & Q&A: Embedded interactive card disclosing client-side IndexedDB benefits, self-hosted SQLite (
patchcat.db) zero-config persistence, and browser sandbox File System Access API authorization constraints.
- Recent 10 Execution Runs Timeline: Dedicated slide-over drawer (
Ctrl+Shift+Hor top header) displaying the latest 10 canvas execution records with duration and token consumption. - Aggregate KPI Overview: Instant glance at total latency, Prompt/Completion token breakdown, and dynamic USD cost estimates across top model providers.
- Execution Waterfall Timeline: Visual horizontal Gantt/bar chart displaying relative start offsets and proportional execution durations per node.
- Step Data Freeze-Frame Inspector: Modal inspector to review exact inputs, outputs, error traces, and telemetry metadata captured for any historical step.
- OpenTelemetry & OpenInference Alignment: Pure-frontend W3C Trace Context generation (128-bit Trace ID, 64-bit Span ID) with hierarchical Root -> Wave -> Node spans and Time-to-First-Token (TTFT) recording.
- One-Click OTel JSON Export: Losslessly export or copy standard OTel ResourceSpans JSON ready for Langfuse, Datadog, Jaeger, or any APM platform.
- Client-Side FIFO Eviction: Enforces an automatic 10-record ring buffer per workflow in IndexedDB, preventing local storage growth while maintaining local-first privacy.
# Clone the repository
git clone https://github.com/GuoBug/PatchCat.git
cd PatchCat
# Install dependencies
npm installnpm run devOpen your browser and navigate to http://localhost:5173.
- Click the API Key button in the top navigation bar.
- Select your preferred provider (Google Gemini, DeepSeek, OpenAI, SiliconFlow, or Ollama).
- Enter your API Key and click 测试连通性 (Test Connection) to fetch available models.
- Click ▶ Run Workflow to execute the pipeline!
PatchCat maintains rigorous code quality with 100% test coverage across core scheduling, variable resolution, and logging engines:
# Run all unit tests (Topological Sort, Engine, LLM Client, Logger, Routing)
npm test
# Run TypeScript type check
npm run typecheck
# Build for production
npm run build
# Preview production build locally
npm run previewPatchCat comes with ready-to-use industrial presets:
| Preset Name | Description | Nodes Involved |
|---|---|---|
| Customer Support Routing | Multi-class intent classification, urgency grading, and automated VIP queue dispatch. | Input ➔ Prompt ➔ LLM Classifier ➔ Code Router ➔ Output Dispatch |
| Self-Reflective Report Generator | Drafter generation combined with an expert Critic review loop for polished outputs. | Input Topic ➔ Drafter Prompt ➔ LLM Generator ➔ Critic Prompt ➔ LLM Critic ➔ Final Report |
| Multi-Agent Arbitration Pipeline | Parallel execution of policy check and sentiment analysis for dispute resolution. | Input Order ➔ Prompt Builder ➔ LLM Policy + LLM Sentiment (Parallel) ➔ Code Arbitrator ➔ Report |
| Layer | Technology |
|---|---|
| Frontend Framework | React 18 + TypeScript 5.7+ |
| Build & Tooling | Vite 6 |
| Canvas & Nodes | @xyflow/react (React Flow v12) |
| State Management | Zustand + Immer |
| Styling & UI | Tailwind CSS v4 + Lucide Icons |
| Workflow Engine | Deterministic In-Browser Kahn's DAG State Machine + SSE Stream Client |
| Backend & Storage | FastAPI + SQLAlchemy 2.0 (SQLite / PostgreSQL + pgvector) |
| Testing | Node.js Native Test Runner (node --test) + Pytest |
- Visual DAG Canvas with Kahn's Algorithm & Parallel Wave Execution
- Multi-Provider Hub (Google Gemini, DeepSeek, OpenAI, SiliconFlow, Ollama)
- DeepSeek R1 Thought/Reasoning Stream Visualization
- Dynamic JavaScript Code Node & Real-Time Transformation Sandbox
- 3-Tier Enterprise Logging Console & Secret Sanitization
- Template Import & Export (JSON Schema Draft-07)
- RAG & Vector Knowledge Base Node Integration (Zero-setup SQLite / PGVector)
- Multi-Agent Autonomous Tool Calling Loop (ReAct Agent)
- One-Click Workflow Export as Standalone REST API Endpoint
- Local Python Server Backend (FastAPI + Async Engine + Alembic Migrations)
- Asuswrt-Merlin Router Plugin & Lightweight Go Gateway (v0.4.7)
- Run Observability, Step Snapshot Inspection & OpenTelemetry Tracing (v0.4.8)
- Immutable Checkpointing & Resumable Execution Subgraph (v0.4.10)
- Local Lightweight Hybrid Search (BM25 + Vectors) (v0.4.12)
- Reranker Cross-Encoder API Integration (v0.4.14)
PatchCat is created and actively maintained by GuoBug (Guo Qiang) — a Product Engineer combining platform engineering rigor (DAG state machines, deterministic orchestration, developer tooling) with product-led growth and user experience empathy.
Engineered through an AI pair programming workflow with rigorous verification and open-source milestones. Inquiries, architectural discussions, and contributions are warmly welcome!
We welcome contributions from the global open-source community!
- 🐛 Found a bug? Submit an Issue
- 💡 Have a feature idea? Start a Discussion
- 🚀 Want to contribute code? Read the Contributing Guide (中文版)
- 🛡️ Found a security vulnerability? See our Security Policy
- 📜 Community standards: Code of Conduct
Distributed under the MIT License. Free for commercial and personal use.