iterion

module
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 7, 2026 License: MIT

README

🔄 Iterion

Declarative workflow orchestration for AI agents.

Define complex, multi-agent LLM workflows as readable .iter files — chain agents, judges, routers, human gates, parallel branches, bounded loops, and budget caps into a single, auditable execution graph.

⚠️ This project is highly experimental. APIs, DSL syntax, and storage formats may change without notice. Use at your own risk in production environments. Feedback and contributions are welcome!

Table of Contents

🧩 What is Iterion?

If you've ever noticed yourself repeating the same prompt-and-review patterns while vibe-coding with an LLM — "ask the model, eyeball the diff, ask it to fix what it missed, run the tests, ask again" — and wondered how to automate and optimize that loop, Iterion is built for you. Capture the pattern once as an .iter workflow, give it budget caps, parallel reviewers, judges and human gates, and let the engine run it deterministically every time.

Iterion is a workflow engine that turns .iter files into executable AI pipelines. You describe what your agents should do — review code, plan fixes, check compliance, ask a human — and Iterion handles how: scheduling branches in parallel, enforcing budgets, persisting state, and routing between nodes.

.iter file → Parse → Compile → Validate → Execute
                                            │
                    ┌───────────────────────┐│
                    │  agents, judges,      ││
                    │  routers, joins,      ││
                    │  humans, tools        ││
                    │  running in parallel  ││
                    │  with budget tracking ││
                    └───────────────────────┘│
                                            ▼
                              results, artifacts, event log

Think of it as a DAG runner purpose-built for LLM workflows — with first-class support for things like structured I/O, conversation sessions, human-in-the-loop pauses, and cost control.

📋 Features

Authoring & orchestration
  • 📝 Declarative DSL — Human-readable .iter files with indentation-based syntax
  • 🤖 Multi-agent orchestration — Chain agents, judges, routers, and joins into complex graphs
  • 🖥️ Visual editor — Browser-based workflow builder with drag-and-drop, live validation, and source view
  • 🙋 Human-in-the-loop — Pause for human input, auto-answer via LLM, or let the LLM decide when to ask
  • 🔀 Parallel branching — Fan-out via routers, converge with join nodes (wait_all / best_effort)
  • 🧭 4 routing modes — fan_out_all, condition, round_robin, and llm-driven routing
  • 🔁 Bounded loops — Retry and refinement cycles with configurable iteration limits
  • 🔲 Structured I/O — Typed schemas for inputs and outputs with enum constraints
  • 🔗 MCP support — Declare MCP servers directly in .iter files (stdio, http)
  • 🧪 Recipe system — Bundle workflows with presets for comparison and benchmarking
  • 📐 Mermaid diagrams — Auto-generate visual workflow diagrams (compact / detailed / full)
Execution & runtime
  • 🔌 Delegation — Offload execution to external agents (Claude Code, Codex) with full tool access — works with Claude and ChatGPT/Codex subscriptions
  • 🌐 Provider-agnostic — In-process claw backend supports Anthropic and OpenAI (validated), plus Bedrock, Vertex, Foundry (via the vendored claw-code-go SDK)
  • 💰 Budget enforcement — Shared, mutex-protected caps on tokens, cost (USD), duration, parallel branches, and loop iterations
  • 🛡️ Tool policies — Allowlist-based access control with exact, namespace, and wildcard matching
  • 🌳 Worktree auto-finalization — worktree: auto runs the workflow in a fresh git worktree, persists commits to a named branch, and fast-forwards the current branch on success — see docs/resume.md
  • 🛡️ Per-run sandbox — sandbox: auto isolates each run inside a Docker/Podman container with the worktree bind-mounted at /workspace and an HTTP CONNECT proxy enforcing a network allowlist — see docs/sandbox.md
  • 🔐 Privacy filter — Built-in Go-native privacy_filter / privacy_unfilter tools redact and restore PII (emails, phones, IBANs, credit cards, URLs, ~25 secret patterns) — see docs/privacy_filter.md
Persistence & observability
  • 📦 Artifact versioning — Per-node, per-iteration versioned outputs persisted to disk
  • 📊 Event sourcing — Append-only JSONL event log for full replay and debugging
  • ⏯️ Resumable runs — Checkpoint-based resume from failed_resumable / paused_waiting_human / cancelled states — see docs/resume.md
  • 📈 Observability stack — Prometheus /metrics, OTLP traces, and a self-contained docker-compose stack with pre-built Grafana dashboards — see docs/observability/README.md
Distribution & integration
  • ☁️ Cloud mode — Multi-tenant Helm deployment with MongoDB + S3-compatible blob store + NATS JetStream queue; KEDA-scaled runner pool; per-run Kubernetes sandbox pods
  • 🧰 TypeScript SDK — @iterion/sdk wraps the CLI with typed run / resume / events streaming for Node, Deno, and Bun apps
  • 🧠 AI agent skill — Install as a skill in Claude Code, Codex, Cursor, Windsurf, GitHub Copilot, Cline, Aider, and other AI coding agents

🚀 Quick Start

Pick your install

Same engine, six delivery modes — pick the one that fits your workflow:

Mode Best for Install Docs
🖥️ CLI Scripted runs, CI/CD pipelines curl -fsSL https://socialgouv.github.io/iterion/install.sh | sh install.md
🌐 Web editor Visual workflow design (browser-based) Bundled with the CLI: iterion editor visual-editor.md
🪟 Desktop app Native window, multi-project, OS keychain, auto-update Download iterion-desktop from Releases desktop.md
🐳 Docker Zero-install runs, reproducible CI docker run --rm ghcr.io/socialgouv/iterion:latest install.md#docker
☁️ Cloud / server Multi-tenant deployment, shared run store, REST/WS API helm install iterion oci://ghcr.io/socialgouv/charts/iterion cloud.md
📦 TypeScript SDK Programmatic invocation from Node/Deno/Bun npm install @iterion/sdk sdks/typescript/

All six invoke the same Go core. The DSL, runtime, persistence and observability are identical — they only differ in how you reach them.

Your first workflow
# Scaffold a new project
mkdir my-project && cd my-project
iterion init

# Configure your API key
cp .env.example .env
# Edit .env → set ANTHROPIC_API_KEY (or OPENAI_API_KEY)
source .env && export ANTHROPIC_API_KEY

# Validate the workflow
iterion validate pr_refine_single_model.iter

# Run it
iterion run pr_refine_single_model.iter \
  --var pr_title="Fix auth middleware" \
  --var review_rules="No SQL injection, no hardcoded secrets"

iterion init creates a complete PR refinement workflow (review → plan → compliance check → act → verify) that you can run immediately.

Inspect results
iterion inspect                          # List all runs
iterion inspect --run-id <id> --events   # View a specific run with events
iterion report --run-id <id>             # Generate a detailed report

All run data (events, artifacts, interactions) is stored in .iterion/runs/.

✨ A Taste of the DSL

Here's the simplest possible workflow — an agent reviews code and decides pass/fail:

prompt review_system:
  You are a code reviewer. Evaluate the submission
  and decide if it meets quality standards.

prompt review_user:
  Review this code:
  {{input.code}}

schema review_input:
  code: string

schema review_output:
  approved: bool
  summary: string

agent reviewer:
  model: "${MODEL}"
  input: review_input
  output: review_output
  system: review_system
  user: review_user

workflow minimal:
  entry: reviewer
  reviewer -> done when approved
  reviewer -> fail when not approved

That's it — 28 lines. The agent gets a code input, produces a structured {approved, summary} output, and the workflow routes to done or fail based on the verdict.

From here you can add judges for multi-pass review, routers for parallel fan-out, human gates for approval, bounded loops for retry, budget caps for cost control, and more — see docs/dsl.md for the full reference.

📚 Documentation

The full documentation lives under docs/ — start with the documentation index. Highlights:

Get going

Author workflows

Run & operate

Architecture & contributing

References

📄 License

MIT. See LICENSE for the full text. Copyright © SocialGouv.

Directories

Path Synopsis
cmd
iterion command
Command iterion is the CLI for the iterion workflow engine.
 Command iterion is the CLI for the iterion workflow engine.
iterion-desktop command
Package main is the Iterion Desktop binary.
 Package main is the Iterion Desktop binary.
examples
mcp_test_server command
Tiny MCP stdio server used by the live tests.
 Tiny MCP stdio server used by the live tests.
pkg
backend/cost
Package cost holds the per-model token-pricing table used to annotate generation outputs with `_tokens` / `_model` / `_cost_usd`.
 Package cost holds the per-model token-pricing table used to annotate generation outputs with `_tokens` / `_model` / `_cost_usd`.
backend/delegate
Package delegate provides the Backend interface and types for executing agent/judge nodes via pluggable backends (CLI agents like claude-code/codex, or API-based backends like claw).
 Package delegate provides the Backend interface and types for executing agent/judge nodes via pluggable backends (CLI agents like claude-code/codex, or API-based backends like claw).
backend/delegate/claudesdk
Package claudesdk provides a Go SDK for the Claude Code CLI.
 Package claudesdk provides a Go SDK for the Claude Code CLI.
backend/llmtypes
Package llmtypes defines iterion-owned types for the LLM generation layer.
 Package llmtypes defines iterion-owned types for the LLM generation layer.
backend/mcp
backend/model
Package model provides the ModelRegistry and claw-based NodeExecutor for resolving "provider/model-id" specs and executing LLM nodes.
 Package model provides the ModelRegistry and claw-based NodeExecutor for resolving "provider/model-id" specs and executing LLM nodes.
backend/recipe
Package recipe defines the RecipeSpec model and loading/application logic.
 Package recipe defines the RecipeSpec model and loading/application logic.
backend/tool
Package tool provides a unified ToolRegistry that normalizes built-in tools and MCP server tools under a single namespace and resolution scheme.
 Package tool provides a unified ToolRegistry that normalizes built-in tools and MCP server tools under a single namespace and resolution scheme.
backend/tool/privacy
Package privacy implements two iterion built-in tools that detect and redact personally identifiable information (PII):
 Package privacy implements two iterion built-in tools that detect and redact personally identifiable information (PII):
backend/tool/privacy/detector
Package detector implements the pure-Go PII detection backend used by the privacy_filter / privacy_unfilter built-in tools.
 Package detector implements the pure-Go PII detection backend used by the privacy_filter / privacy_unfilter built-in tools.
benchmark
Package benchmark implements a multi-recipe benchmark runner with isolated workspaces and comparable metrics collection.
 Package benchmark implements a multi-recipe benchmark runner with isolated workspaces and comparable metrics collection.
cli
Package cli implements the iterion command-line interface.
 Package cli implements the iterion command-line interface.
cloud/metrics
Package metrics centralises the Prometheus metrics exposed by the cloud-mode iterion server and runner pods.
 Package metrics centralises the Prometheus metrics exposed by the cloud-mode iterion server and runner pods.
cloud/tracing
Package tracing wires the OpenTelemetry trace SDK so the spans emitted by pkg/runtime, pkg/runner, and pkg/server are actually exported.
 Package tracing wires the OpenTelemetry trace SDK so the spans emitted by pkg/runtime, pkg/runner, and pkg/server are actually exported.
config
Package config loads iterion runtime configuration from environment variables and an optional YAML file.
 Package config loads iterion runtime configuration from environment variables and an optional YAML file.
dsl/ast
MarshalFile / UnmarshalFile provide JSON serialization and deserialization for File types, converting Go iota-based enums to human-readable string representations.
 MarshalFile / UnmarshalFile provide JSON serialization and deserialization for File types, converting Go iota-based enums to human-readable string representations.
dsl/expr
Package expr implements a small expression language used by iterion's `compute` nodes and `when` edge clauses.
 Package expr implements a small expression language used by iterion's `compute` nodes and `when` edge clauses.
dsl/ir
Package ir defines the canonical Intermediate Representation (IR) produced by compiling an AST.
 Package ir defines the canonical Intermediate Representation (IR) produced by compiling an AST.
dsl/parser
dsl/types
Package types defines shared enum types used by both the AST and IR packages.
 Package types defines shared enum types used by both the AST and IR packages.
dsl/unparse
Package unparse converts an ast.File back into .iter DSL text.
 Package unparse converts an ast.File back into .iter DSL text.
git
Package git is a minimal wrapper around the `git` CLI for the editor's modified-files panel.
 Package git is a minimal wrapper around the `git` CLI for the editor's modified-files panel.
internal/appinfo
internal/proc
Package proc holds tiny process-management primitives shared across iterion's shell-out wrappers (gitCmd, dockerCmd, kubectlCmd).
 Package proc holds tiny process-management primitives shared across iterion's shell-out wrappers (gitCmd, dockerCmd, kubectlCmd).
log
Package log provides a leveled logger with emoji-rich console output for the iterion workflow engine.
 Package log provides a leveled logger with emoji-rich console output for the iterion workflow engine.
queue
Package queue defines the message contract exchanged between the iterion server (publisher) and the iterion runner (consumer).
 Package queue defines the message contract exchanged between the iterion server (publisher) and the iterion runner (consumer).
queue/nats
Package nats wraps the NATS / JetStream / KV layer for iterion's cloud queue.
 Package nats wraps the NATS / JetStream / KV layer for iterion's cloud queue.
runner
Package runner implements the cloud-mode iterion runner pod.
 Package runner implements the cloud-mode iterion runner pod.
runtime
Package runtime implements the workflow execution engine.
 Package runtime implements the workflow execution engine.
runtime/recovery
Package recovery defines typed recovery recipes that decide what to do when a node fails.
 Package recovery defines typed recovery recipes that decide what to do when a node fails.
runview
Package runview exposes a service-layer view of iterion runs for programmatic consumers — the HTTP server and the future "run console" UI.
 Package runview exposes a service-layer view of iterion runs for programmatic consumers — the HTTP server and the future "run console" UI.
runview/eventstream
Package eventstream abstracts the live + historical event source the run console subscribes to.
 Package eventstream abstracts the live + historical event source the run console subscribes to.
sandbox
Package sandbox defines the iterion sandboxing abstraction.
 Package sandbox defines the iterion sandboxing abstraction.
sandbox/devcontainer
Package devcontainer parses the subset of devcontainer.json fields iterion's sandbox driver consumes.
 Package devcontainer parses the subset of devcontainer.json fields iterion's sandbox driver consumes.
sandbox/docker
Package docker implements the Docker/Podman sandbox driver.
 Package docker implements the Docker/Podman sandbox driver.
sandbox/kubernetes
Package kubernetes implements iterion's sandbox driver for cloud (in-cluster) deployments.
 Package kubernetes implements iterion's sandbox driver for cloud (in-cluster) deployments.
sandbox/netproxy
Package netproxy implements iterion's HTTP CONNECT proxy that enforces the workflow's sandbox network policy.
 Package netproxy implements iterion's HTTP CONNECT proxy that enforces the workflow's sandbox network policy.
sandbox/noop
Package noop provides the always-available passthrough sandbox driver.
 Package noop provides the always-available passthrough sandbox driver.
sandbox/registry
Package registry centralises the iterion-shipped sandbox-driver constructor list.
 Package registry centralises the iterion-shipped sandbox-driver constructor list.
server
Package server provides an HTTP API for the iterion editor.
 Package server provides an HTTP API for the iterion editor.
server/cloudpublisher
Package cloudpublisher wires runview.LaunchPublisher on top of NATS + Mongo so the cloud-mode `iterion server` can hand work off to the runner pool instead of executing in-process.
 Package cloudpublisher wires runview.LaunchPublisher on top of NATS + Mongo so the cloud-mode `iterion server` can hand work off to the runner pool instead of executing in-process.
store
Package store implements the file-backed persistence layer for iterion runs.
 Package store implements the file-backed persistence layer for iterion runs.
store/blob
Package blob defines the artifact-blob interface implemented by S3 (cloud) and (potentially) a local filesystem variant for testing.
 Package blob defines the artifact-blob interface implemented by S3 (cloud) and (potentially) a local filesystem variant for testing.
store/cloud
Package cloud wires the Mongo + S3 cloud backend into the store factory.
 Package cloud wires the Mongo + S3 cloud backend into the store factory.
store/mongo
Package mongo implements the cloud-mode RunStore on top of MongoDB for run metadata + events + interactions, paired with an external blob.Client (S3) for artifact bodies.
 Package mongo implements the cloud-mode RunStore on top of MongoDB for run metadata + events + interactions, paired with an external blob.Client (S3) for artifact bodies.
store/storetest
Package storetest exposes the conformance suite that every store.RunStore backend must satisfy.
 Package storetest exposes the conformance suite that every store.RunStore backend must satisfy.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.