Skip to main content

Dynamic Subgraphs

License: Apache 2.0 Python 3.11+ CI Typed

A governed runtime for LLM-generated workflows. A stable Supervisor turns a prompt into a validated plan — data, never executable code — then compiles and runs it as a transient LangGraph workflow over a bounded, allowlisted vocabulary of node kinds. Recording is opt-in: when enabled, each run is captured as a replayable, diffable, cost-attributed artifact under runs/<run_id>/ — the public SDK defaults to in-memory execution and writes no files.

What that buys you over a free-form agent loop: the model proposes the workflow but never executes arbitrary code; the compiler only instantiates registry-approved node kinds; recursion is depth- and budget-capped; and any run — success or failure — can be recorded for inspection and replay. LangGraph types stay behind the compiler/ and runtime/ boundaries. An optional thin FastAPI layer exposes the supervisor over HTTP.

What can it build?

From one prompt, the planner assembles a transient graph out of a small set of governed node kinds — llm_call, tool_call, branch, reduce, parallel_map, spawn_subagent, spawn_subgraph, gauntlet, wait_for_event, emit_artifact. A few of the shapes it produces (these render in the same Mermaid the engine writes to graph.mmd for every run):

Parallel research → recommend — fan out to independent workers, then reduce:

graph TD
    START([START])
    END([END])
    extract_a["extract_a<br/>tool_call"]
    extract_b["extract_b<br/>tool_call"]
    summarize_a["summarize_a<br/>llm_call"]
    summarize_b["summarize_b<br/>llm_call"]
    compare["compare_and_recommend<br/>reduce"]
    START --> extract_a
    START --> extract_b
    extract_a --> summarize_a
    extract_b --> summarize_b
    summarize_a --> compare
    summarize_b --> compare
    compare --> END

Tool-grounded answer — search the web, answer from it, write a report:

graph TD
    START([START])
    END([END])
    search["web_search<br/>tool_call"]
    answer["answer<br/>llm_call"]
    report["report<br/>emit_artifact"]
    START --> search
    search --> answer
    answer --> report
    report --> END

Dynamic routing — classify the request, then take only the path it warrants:

graph TD
    START([START])
    END([END])
    classify["classify_intent<br/>llm_call"]
    route{"route<br/>branch"}
    answer["answer<br/>llm_call"]
    search["web_search<br/>tool_call"]
    investigate["investigate<br/>spawn_subgraph"]
    START --> classify
    classify --> route
    route -->|simple| answer
    route -->|needs data| search
    route -->|complex| investigate
    search --> answer
    investigate --> answer
    answer --> END

Human-in-the-loop — pause for an external event, then resume:

graph TD
    START([START])
    END([END])
    draft["draft_proposal<br/>llm_call"]
    review["await_approval<br/>wait_for_event"]
    finalize["finalize<br/>llm_call"]
    START --> draft
    draft --> review
    review --> finalize
    finalize --> END

Gauntlet loop — build against a concrete reference, judged blind, until ours wins or a boundary fires (rounds, budget, a gap repeated three times):

graph TD
    START([START])
    END([END])
    fetch["fetch_reference<br/>tool_call"]
    loop["beat_reference<br/>gauntlet"]
    report["report<br/>emit_artifact"]
    START --> fetch
    fetch --> loop
    loop --> report
    report --> END

The gauntlet node runs Matt Shumer's builder/critic loop inside one node: each round plans a builder child graph (depth- and budget-clamped like spawn_subgraph), then a fresh-context critic compares the artifact with the reference under a sealed A/B mapping and returns one gap that briefs the next round. The outer graph stays a DAG; the round log, verdicts, and stop reason land in the run's output.json. Losing to a strong reference is normal — the best artifact so far is still returned, never relabeled as a win.

Nested composition — a node plans and runs a child graph on a fresh, isolated state envelope under enforced depth and spend ceilings (recursion that can't run away):

graph TD
    START([START])
    END([END])
    plan["plan<br/>llm_call"]
    investigate["investigate<br/>spawn_subgraph"]
    synthesize["synthesize<br/>reduce"]
    START --> plan
    plan --> investigate
    investigate --> synthesize
    synthesize --> END

How it works

Those graphs are transient — planned, validated, run, and recorded per request. The only thing that stays fixed is the Supervisor, a stable host graph that governs every run:

graph LR
    START([prompt]) --> plan
    plan["plan<br/>(GraphSpec)"] --> validate
    validate["validate<br/>(registry + budgets)"] --> run
    run["compile & run<br/>(transient graph)"] --> record
    record["record<br/>(spec·trace·mermaid·cost)"] --> replay
    replay["replay / diff / audit"] --> respond
    respond([result]) --> END([END])

The planner emits a plan, never code; the compiler only instantiates registry-approved node kinds; and every run — success or failure — is recorded as a replayable, diffable, cost-attributed artifact. That audit trail is the point: it's what a free-form agent loop can't give you.

When (not) to reach for it

Dynamic Subgraphs earns its keep when the shape of the work varies per input and you need the run governed and auditable. Use it when:

  • The workflow can't be enumerated ahead of time — the right nodes/edges depend on the request (heterogeneous intake, branching investigations, data-dependent recursion whose depth isn't known until runtime).
  • You need an audit trail: a validated plan, a per-node trace, deterministic replay, and cost attribution — for compliance, debugging, or reproducibility.
  • The model should propose the workflow but must not execute arbitrary code, and its tool/capability surface must stay allowlisted and budget-capped.

Reach for something simpler when:

  • The shape is known. If you can draw the DAG ahead of time, hand-author a fixed LangGraph graph — it's cheaper and more predictable. (If you can write the orchestration as a script, you don't need a planner generating it.)
  • The task is small. A frontier model in a plain tool loop already decomposes a one-to-three-step task in-context; a planning round-trip is pure overhead there.
  • Your hard problem is global consistency, not orchestration. Isolated child envelopes are great for blast-radius but work against shared canonical state — pair DS with a retrieval/consistency layer rather than expecting it to enforce one.

Install

With uv (recommended):

uv add dynamic-subgraphs                 # slim core (engine only)
uv add "dynamic-subgraphs[openai]"       # + OpenAI provider
uv add "dynamic-subgraphs[anthropic]"    # + Anthropic provider
uv add "dynamic-subgraphs[ollama]"       # + local Ollama provider
uv add "dynamic-subgraphs[api]"          # + FastAPI HTTP surface
uv add "dynamic-subgraphs[cost]"         # + automatic result.cost (LiteLLM prices)
uv add "dynamic-subgraphs[all]"          # everything

Or with pip:

pip install dynamic-subgraphs
pip install "dynamic-subgraphs[openai]"  # same extras: anthropic, ollama, api, cost, all

The core install is intentionally light (langgraph, langchain-core, pydantic, python-dotenv); provider SDKs and the API server are optional extras so you only pull what you use.

Quickstart (development)

# Set up the dev environment (all extras + dev tooling)
uv sync --all-extras

# Run the offline mock demo (free, no tokens)
uv run python -m app.main "compare A and B"

# Run the HTTP API (boots in mock mode by default; needs the `api` extra)
uv run python -m app.api

By default everything runs in mock mode — free and offline. Set DS_PLANNER=llm and DS_PROVIDER=<provider> to use the real planner and grounded tools. The legacy DS_PLANNER=openai value still maps to planner=llm with provider=openai.

Built-in providers (default_model_providers()):

DS_PROVIDER Package Credentials
openai langchain-openai OPENAI_API_KEY
anthropic langchain-anthropic ANTHROPIC_API_KEY
ollama langchain-ollama none (local server; OLLAMA_BASE_URL optional)

Each role (planner, worker, reducer, subagent, judge) can target a different provider/model through RunConfig's role-specific ModelRef fields; unset roles fall back to the worker model, then to the base provider+model.

SDK usage

The dynamic_subgraphs package is the importable facade — build an EngineConfig, hand it to the engine, then call run():

from dynamic_subgraphs import DynamicSubgraphs, EngineConfig, Model

# Cloud (key from env)
engine = DynamicSubgraphs(EngineConfig(model=Model("openai", "gpt-5.4-nano")))

# ...or a local LM Studio / Ollama server (bring your own URL/key/model)
engine = DynamicSubgraphs(EngineConfig(model=Model.lmstudio("google/gemma-3-27b")))
engine = DynamicSubgraphs(EngineConfig(model=Model.ollama("llama3.1")))

result = engine.run("Compare two sources on X and recommend one.")
result.response      # synthesized answer text
result.values        # {output_key: value, ...}
result.plan          # the generated GraphSpec
result.artifacts     # {filename: Path} (populated only when recording is on)
result.usage         # exact TokenUsage: input/output/total + per-model breakdown
result.cost          # USD (None unless a pricing book is configured — see below)
result.effective_budget  # the host-granted budget (planner request capped by policy)
result.plan_attempts     # planner attempts (>1 if a rejected plan was repaired)

Token usage & cost

result.usage is always populated with the providers' own reported token counts (via LangChain's usage callback — exact, all providers, no estimation).

Cost works automatically with the cost extra (it uses LiteLLM's maintained price map — you don't specify prices, and we don't ship a table that goes stale):

pip install "dynamic-subgraphs[openai,cost]"
engine = DynamicSubgraphs(EngineConfig(model=Model("openai", "gpt-5.4-nano")))
r = engine.run("...")
r.usage.total_tokens   # e.g. 3233   (exact, free, always)
r.cost                 # e.g. 0.0021 (USD — auto-computed)

Without the extra, result.cost is None (tokens are still exact). You can also pass a manual pricing book on EngineConfig to override prices or to cover local / custom-endpoint models LiteLLM doesn't know:

EngineConfig(model=..., pricing={"my-model": {"input_per_1m": 0.5, "output_per_1m": 1.0}})

(If you use LangSmith, it computes cost server-side as well.)

All engine configuration lives on EngineConfig: the per-role models (model, planner_model, worker_model, reducer_model, subagent_model, judge_model), the recording policy, planner mode, runs_dir, providers, checkpointer, the host-owned policy (ExecutionPolicy), and max_plan_attempts (the plan-repair loop).

Governance: host-owned limits & plan repair

The planner proposes a workflow; the host owns the limits. An ExecutionPolicy is the contract — and it's enforced, not advisory:

from dynamic_subgraphs import DynamicSubgraphs, EngineConfig, ExecutionPolicy, Model

engine = DynamicSubgraphs(EngineConfig(
    model=Model("openai", "gpt-5.4-nano"),
    policy=ExecutionPolicy(
        max_nodes=6, max_llm_calls=4, max_depth=2, max_fanout=16,
        allowed_tools=frozenset({"web_search"}),   # host ∩ registry
    ),
))
r = engine.run("...")
r.effective_budget   # the granted budget = min(host, planner request)

Enforced at validation (root and every nested spawn_subgraph child):

  • Budgets — node/LLM-call counts capped at min(host, planner request); a plan can't grant itself a larger budget.
  • Allow-sets — tool / subagent / node-kind use is the host ∩ registry intersection; a plan naming a disallowed capability is rejected.
  • Fan-out — a parallel_map over more items than max_fanout halts before any work fires.
  • Nesting — a child's budget is the parent's remaining allowance, so a nest can't outspend the root; depth is capped at the tighter of the host and the rail.
  • Wall-clock — a run that outruns max_wall_seconds is abandoned (a hung runner can't block forever).

When a plan is rejected for a recoverable reason, the supervisor feeds the issues + host limits back into a re-plan, up to max_plan_attempts (default 2 — repair once; set 1 for strict block-and-report). So a too-ambitious plan is re-planned within the limits instead of just failing. Defaults are permissive-but-bounded, so a typical plan is unaffected.

⚠️ Use a capable model for the planner. The planner must emit a valid GraphSpec; small local models (7B-class, and in practice anything below ~20–30B) frequently produce invalid plans and fail. Run small/local models as the worker_model with a stronger planner_model.

Recording (opt-in)

By default the engine writes no files — embedding it never clutters your working tree. Suggestion: set a recording policy while developing or debugging to capture the trace under runs/<run_id>/, then leave it at the default in production / library use:

from dynamic_subgraphs import Recording, Artifact

engine = DynamicSubgraphs(EngineConfig(
    model=Model("openai", "gpt-5.4-nano"),
    recording=Recording.debug(),      # capture everything
    runs_dir="runs",
))

Recording is granular — choose exactly which artifacts to write with the Artifact enum (its values are the filenames) and the Recording policy:

recording=Recording.visual_only()           # just graph.mmd (the diagram)
recording=Recording.all() - {Artifact.SPEC}  # everything except spec.json
recording={Artifact.MERMAID, Artifact.TRACE}  # a raw set works too
Preset Writes Use for
Recording.none() (default) nothing embedding / production
Recording.all() every artifact full capture
Recording.debug() every artifact debugging a run
Recording.visual_only() graph.mmd a picture of the graph
Recording.replayable() spec.json + output.json enabling resume/replay

Coding agents can enumerate every valid option via DynamicSubgraphs.capabilities(). See docs/recipes.md for copy-pasteable patterns.

Engine model defaults can be overridden per run() call, so each run picks the models for its own node calls (e.g. a cheap cloud planner with local workers):

result = engine.run(
    "Investigate this task.",
    planner_model=Model("openai", "gpt-5.4-nano"),
    worker_model=Model.lmstudio("openai/gpt-oss-20b"),
)

Documentation

  • examples/ — runnable, standalone SDK integration examples (one file per pattern).
  • docs/recipes.md — copy-pasteable SDK patterns (local models, hybrid, recording presets, debugging) + tested-model and latency tables.
  • docs/api-stability.md — API stability & change policy: what counts as public, SemVer, deprecation, and how we keep changes non-breaking.
  • docs/evals/ — eval reports (e.g. the gpt-5.4-nano vs claude-haiku-4-5 e2e comparison: latency / tokens / cost / quality, traced via LangSmith).
  • docs/api.md — the HTTP surface over the supervisor (endpoints, modes, auth, examples).
  • docs/dynamic-graphs-canonical-design-v1.md — canonical project design and source of truth.
  • docs/index.md — full documentation index.
  • AGENTS.md — agent-facing package map and MVP sequence.

Contributing & support

Contributions are welcome — see CONTRIBUTING.md for the dev setup, test, and formatting workflow, and CODE_OF_CONDUCT.md. Found a bug or have a request? Open an issue. For security reports, see SECURITY.md.

Status

Pre-1.0 (0.x) — the public SDK surface is usable and tested, but the API may change between minor versions until 1.0. See CHANGELOG.md.

License

Licensed under the Apache License 2.0. See NOTICE for attribution.

Metadata

Release files for dynamic-subgraphs 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for dynamic-subgraphs 0.6.0
File Size Uploaded Provenance Actions
dynamic_subgraphs-0.6.0.tar.gz 202.6 kB With provenance Details for dynamic_subgraphs-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for dynamic-subgraphs 0.6.0
File Interpreter ABI Platform Actions
dynamic_subgraphs-0.6.0-py3-none-any.whl Python 3 none any Details for dynamic_subgraphs-0.6.0-py3-none-any.whl

Total release size: 382.3 kB

Release files / dynamic_subgraphs-0.6.0.tar.gz

Download URL dynamic_subgraphs-0.6.0.tar.gz
Size 202.6 kB
Tags Source
SHA-256 checksum
How to use checksums
d44d0a575f790205855d35b33736c212410bda6fa2353ad322a7c9b6ab8e8b4c
BLAKE2b-256 checksum
How to use checksums
ebe60da22f51372627fc1c63666a5615f60066534e27f1dbcffbb2d693b41ffc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Release files / dynamic_subgraphs-0.6.0-py3-none-any.whl

Download URL dynamic_subgraphs-0.6.0-py3-none-any.whl
Size 179.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
96f651e312715531b0bc4fe68f11ad2c95e4310fc1db612ec7c53ba0d4522bfe
BLAKE2b-256 checksum
How to use checksums
269e5375e68cc21ef9b41780ede12d194c90004454e65658eb4b707bfc063261
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

Security for dynamic-subgraphs 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for dynamic_subgraphs-0.6.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 3, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page