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 · Why ChainWeaver? · Is this for me? · Product validation · Quick Start · Architecture · Docs site · 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