ChainWeaver

ChainWeaver

Find where your agent no longer needs to reason. Review the evidence. Turn the accepted path into a governed deterministic capability.

Product thesis under validation — observe → prove → review → compile. ChainWeaver can inspect repeated tool behavior, surface candidates, and execute reviewed deterministic paths with typed contracts. Deterministic execution by itself is not the moat: if you already know the exact workflow, a normal Python function, LangGraph node, or provider-native tool may be simpler. The hypothesis being tested is that trace-derived evidence, useful rejection, governed promotion, security-boundary preservation, and drift detection make ChainWeaver worth adopting. See Product validation & adoption gates and #553.

Remove reasoning boundaries, never security boundaries. Compiling several tool calls into one capability must not silently aggregate privileges or erase child approval requirements. That invariant is tracked explicitly in #554.

Governance for deterministic tool paths. Typed I/O at every step, file-serializable flows, schema-drift detection, determinism *attestation*, property fuzzing, and structured audit traces provide a disciplined execution substrate for paths that have actually earned deterministic promotion.

Benchmarks are evidence about the executor, not proof of product-market fit.

The repo's benchmark report is reproducible —

regenerate it yourself with python benchmarks/report.py — and shows the

deterministic core avoiding model-mediated transitions in its synthetic

comparison. It does not establish that every repeated path should

be compiled, or that ChainWeaver beats the obvious plain-Python implementation.

The independent validation program requires that manual baseline explicitly.

from chainweaver import Tool, Flow, FlowStep, FlowRegistry, FlowExecutor

(NumberInput, ValueOutput, double_fn defined in full example below)

1. Wrap any function as a schema-validated Tool

double = Tool(name="double", description="Doubles a number.", input_schema=NumberInput, output_schema=ValueOutput, fn=double_fn)

2. Wire tools into a Flow

flow = Flow(name="calc", description="Double a number.", steps=[FlowStep(tool_name="double", input_mapping={"number": "number"})])

3. Register and execute — zero LLM calls

registry = FlowRegistry() registry.register_flow(flow) executor = FlowExecutor(registry=registry) executor.register_tool(double) result = executor.execute_flow("calc", {"number": 5})

result.final_output → {"number": 5, "value": 10}

See the full example below or run python examples/simple_linear_flow.py

[Installation](#installation) · [Why ChainWeaver?](#why-chainweaver) · [Is this for me?](#is-this-for-me) · [Product validation](docs/product-validation.md) · [Quick Start](#quick-start) · [Architecture](#architecture) · [Docs site](https://chainweaver.readthedocs.io/) · [Roadmap](#roadmap)

---

See it in 30 seconds

The deterministic executor solves a simple problem: once a path has been shown to need no intermediate reasoning, stop paying a model to re-decide the same plumbing on every run.

Before — a model-mediated path:

turn 1   ─►  LLM("plan")    ─►  search(query)         ─► 12 results

turn 2 ─► LLM("next?") ─► extract(results) ─► 8 facts turn 3 ─► LLM("next?") ─► validate(facts) ─► 7 facts turn 4 ─► LLM("next?") ─► format(facts) ─► answer

After review — the accepted path can run deterministically:

turn 1   ─►  LLM("plan")    ─►  search_summarize_flow(query)

└─ search ─► extract ─► validate ─► format

The agent still decides *which* capability to invoke. The deterministic steps inside it run with strict Pydantic validation and no LLM involvement.

The harder product question comes before this diagram: should this path be compiled at all? A useful ChainWeaver analysis must be able to show why a candidate is recurrent and structurally safe and reject paths where semantic judgment, side effects, authorization, or approval boundaries still matter. That claim is currently being tested on independent traces in #553.

Copy-paste executor path:

pip install 'chainweaver[yaml]'

python examples/simple_linear_flow.py

The summary below is a condensed view of the real ExecutionResult the script produces:

flow=double_add_format success=True

final_output={'number': 5, 'value': 20, 'result': 'Final value: 20'} step 0 double {'value': 10} step 1 add_ten {'value': 20} step 2 format_result {'result': 'Final value: 20'}

---

Why ChainWeaver?

Why not just write a Python function?

Often, you should.

If your team already knows the workflow is fixed, a normal function or the workflow primitives in your existing framework are usually the lowest-complexity answer. ChainWeaver should earn another dependency only when its lifecycle adds meaningful value—for example:

• discovering non-obvious repeated model-mediated paths from real traces;
• showing evidence for recurrence, dataflow compatibility, and counterexamples;
• rejecting tempting paths that still require semantic judgment;
• preserving approval and authorization constraints during promotion;
• producing reproducible review evidence and artifact identity;
• detecting schema/safety/policy drift after promotion;
• exporting or executing the accepted capability without pretending that fewer model calls automatically means greater correctness.

Whether those advantages are strong enough in real teams is a falsifiable product hypothesis, not a README assumption. See docs/product-validation.md.

When an LLM-powered agent routes tools together — fetch_data → transform → store — a common pattern is to insert an LLM call between steps so the model can decide what to do next. For a path that has been demonstrated and reviewed as fully deterministic, those intermediate calls can add latency, cost, and variability without adding useful judgment.

ChainWeaver's executor can run an accepted deterministic path without any LLM involvement between steps:

User request

│ ▼ FlowExecutor ──► Tool A ──► Tool B ──► Tool C │ ▼ Response

How is this different from LangChain / LangGraph / Prefect / Dagster / Temporal?

Those frameworks can also execute deterministic code. ChainWeaver should not be selected because deterministic execution is impossible elsewhere. Its current product thesis is narrower: start from observed agent/tool behavior, establish which regions no longer need reasoning, make the evidence and rejections reviewable, then promote accepted paths into governed deterministic capabilities.

The execution substrate remains deliberately small and LLM-free between steps, but the project is testing whether the evidence/governance lifecycle—not the mere existence of another workflow runtime—is the part users value.

See docs/comparisons.md for the detailed, versioned comparison and docs/product-validation.md for the criteria that can falsify this positioning.

---

Is this for me?

ChainWeaver is built for one specific shape of problem. The full fit/non-fit page covers the nuances; the short version:

Use ChainWeaver when

• You have real agent/tool traces and suspect parts of the path are repeated plumbing rather than useful model judgment.
• You want evidence and review around which paths deserve deterministic promotion, not only a runtime for a workflow you already know.
• Determinism, strict schemas, auditability, and drift detection matter once a path is promoted.
• You are prepared to keep security and approval boundaries explicit rather than treating a macro-tool invocation as blanket child authorization.

Don't use ChainWeaver when

• You already know the workflow and a normal Python function or your existing framework expresses it clearly enough.
• Every step requires open-ended reasoning to pick the next one (use an agent framework: LangGraph, the OpenAI / Anthropic SDK tool-use loops).
• You need a general workflow engine for scheduled / durable jobs across time (use Prefect, Dagster, or Temporal).
• You expect the executor to call an LLM. It deliberately doesn't.
• You cannot preserve the authorization/approval semantics of a side-effecting path during compilation.

The product thesis, validation protocol, and kill/pivot criteria are public in docs/product-validation.md.

For the correctness argument behind the deterministic execution design, see docs/data-integrity.md.

Part of the Weaver Stack

ChainWeaver is the deterministic multi-step tool execution layer of the Weaver Stack — a family of small, composable SDKs that share weaver-spec's SelectableItem routing contract. On the request path a router picks *which* capability to invoke, ChainWeaver runs the deterministic tool path *behind* it, and downstream layers gate and guard the call:

flowchart LR

req([Request]) --> ctx[contextweaver context assembly] ctx --> cw[ ChainWeaver deterministic flow execution] cw --> ak[agent-kernel capability gating] ak --> af[agentfence runtime guardrails] subgraph adjacent [Adjacent · use any subset] vg[vibeguard] lw[lessonweaver] se[skdr-eval] end

Use standalone or together. Each layer stands on its own — ChainWeaver's base install has no hard dependency on any sibling and works fully standalone. Real interop runs through the chainweaver[weaver-stack] extra, which pins the published weaver-contracts package: ChainWeaver consumes its SelectableItem / RoutingDecision / CapabilityToken types directly, so a router can hand a routing decision straight to resolve_flow_from_routing_decision() for deterministic execution. See the runnable Weaver Stack golden path (issue #234).

| Layer | What i