feat: ChainWeaver v0.1.0 — deterministic MCP tool-chain orchestration

[Copilot]

LLM-powered agents commonly insert a model call between every tool invocation to decide the next action. For fully deterministic chains this is pure waste — latency, cost, and token burn with no reasoning value. ChainWeaver eliminates these intermediate calls by compiling known tool sequences into schema-validated execution graphs.

Core abstractions

• Tool — callable + Pydantic input/output schemas; validates both directions on every invocation
• FlowStep — maps keys from the accumulated execution context into a tool's input (string = context lookup, non-string = literal constant)
• Flow — ordered FlowStep list; deterministic=True by default; optional trigger_conditions metadata for agent-side dispatch
• FlowRegistry — in-memory catalogue; register_flow, get_flow, list_flows, match_flow_by_intent (substring, Phase 2 TODO: embedding-based)
• FlowExecutor — sequential runner; no LLM calls; merges step outputs into a shared context dict; returns ExecutionResult with per-step StepRecord log

Error handling

Typed exception hierarchy under ChainWeaverError: ToolNotFoundError, FlowNotFoundError, FlowAlreadyExistsError, SchemaValidationError, InputMappingError, FlowExecutionError — each carrying the step index and tool name for traceability.

Usage

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

class NumberInput(BaseModel):
    number: int

class ValueOutput(BaseModel):
    value: int

class ValueInput(BaseModel):
    value: int

class FormattedOutput(BaseModel):
    result: str

double = Tool("double", "...", NumberInput, ValueOutput, lambda i: {"value": i.number * 2})
add_ten = Tool("add_ten", "...", ValueInput, ValueOutput, lambda i: {"value": i.value + 10})
fmt = Tool("format_result", "...", ValueInput, FormattedOutput, lambda i: {"result": f"Final value: {i.value}"})

flow = Flow(
    name="double_add_format",
    description="Doubles a number, adds 10, formats.",
    steps=[
        FlowStep(tool_name="double",        input_mapping={"number": "number"}),
        FlowStep(tool_name="add_ten",       input_mapping={"value": "value"}),
        FlowStep(tool_name="format_result", input_mapping={"value": "value"}),
    ],
)

registry = FlowRegistry()
registry.register_flow(flow)

executor = FlowExecutor(registry=registry)
for t in [double, add_ten, fmt]:
    executor.register_tool(t)

result = executor.execute_flow("double_add_format", {"number": 5})
# result.final_output → {'number': 5, 'value': 20, 'result': 'Final value: 20'}

Phase 2 design markers

TODO comments placed throughout for: DAG execution with parallel step groups, conditional branching, determinism scoring, runtime chain observation + flow suggestion, JSON/YAML persistence, async mode, and embedding-based intent matching.

Original prompt

Build a production-ready Python library called ChainWeaver.

Vision

ChainWeaver is a deterministic orchestration layer for MCP-based agents.

It solves this problem:

When an agent chains tools (A → B → C), LLM calls are often inserted between each step to decide the next action. But many chains are deterministic and do not require reasoning between tool calls. This causes unnecessary latency, cost, and token usage.

ChainWeaver compiles deterministic multi-tool chains into executable flows that run without intermediate LLM calls.

Think:

Interpreted agent reasoning → Compiled execution graph

Dynamic chaining → Deterministic orchestration

Core Goals

Allow registration of tools (MCP or generic tools)

Allow definition of deterministic flows (linear or DAG)

Execute flows without LLM involvement between steps

Provide structured JSON data passing between steps

Support runtime observation of agent-created chains

Optionally learn and persist deterministic chains

Architecture Requirements

1. Core Concepts

Implement the following abstractions:

Tool

name

description

input_schema (pydantic model)

output_schema (pydantic model)

callable function

FlowStep

tool_name

input_mapping (how to map previous outputs into this tool’s inputs)

Flow

name

description

trigger_conditions (optional)

list of FlowSteps

deterministic: bool

FlowRegistry

register_flow

list_flows

get_flow

match_flow_by_intent (basic version)

FlowExecutor

execute_flow(flow_name, initial_input)

sequential execution

pass structured outputs

strict schema validation

error handling with traceable execution log

Phase 1 Scope (MVP)

Keep it minimal but real:

Linear flows only (no DAG yet)

In-memory registry

JSON-like structured passing

Full type safety using Pydantic

Logging for each step

Phase 2 Preparation (Design only, no full implementation)

Design extensibility for:

DAG-based execution

Conditional branching

Determinism scoring

Runtime chain observation + flow suggestion

Flow persistence (JSON/YAML storage)

Add TODO markers in code for these.

Project Structure

Use this structure:

chainweaver/
init.py
tools.py
flow.py
registry.py
executor.py
exceptions.py
logging.py
examples/
simple_linear_flow.py
tests/
test_flow_execution.py
test_registry.py
pyproject.toml
README.md

README Requirements

The README must:

Clearly explain the problem (LLM cost between deterministic tool calls)

Explain the “compiled vs interpreted” analogy

Show a full example:

Define 3 dummy tools

Create a deterministic flow

Execute it

Show how this integrates with MCP agents conceptually

Include roadmap section

Include comparison to naive agent chaining

Tone:
Serious, infrastructure-level, not experimental.

Example Implementation Requirements

Create an example where:

Tool A:

Takes number

Returns {"value": number * 2}

Tool B:

Takes value

Returns {"value": value + 10}

Tool C:

Takes value

Returns {"result": f"Final value: {value}"}

Define flow:
Double → Add → Format

Run execution from initial input 5 and show result.

Code Quality Requirements

Python 3.10+

Type hints everywhere

Pydantic models

Clean docstrings

No unnecessary dependencies

Small, readable, extensible

Tests

Use pytest.

Test:

Flow registration

Successful execution

Invalid schema error

Missing tool error

Important Design Principles

Determinism is explicit

Execution is reproducible

No LLM inside executor

Middleware style architecture

Agent-agnostic

Non-Goals (for now)

No direct MCP protocol implementation

No async complexity

No network layer

No UI

Final Deliverable

Produce:

Fully working library

Passing tests

Clear README

Example script runnable with:
python examples/simple_linear_flow.py

Do not leave placeholders.
Do not generate stubs without implementation.
Make it clean and realistic.

If possible, make the design strong enough that this could become a foundational layer for the MCP ecosystem.

When you generate files, create clean commits grouped logically (core, tests, docs).

This should produce a serious v0.1.0 foundation.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull request overview

Introduces ChainWeaver v0.1.0, a small Python library for deterministic orchestration of multi-tool chains (no intermediate LLM calls), with Pydantic-based schema validation, an in-memory flow registry, and a sequential executor with structured step logging.

Changes:

• Adds core library modules: Tool, Flow/FlowStep, FlowRegistry, FlowExecutor, typed exceptions, and logging helpers.
• Adds an end-to-end example script demonstrating a 3-step deterministic flow.
• Adds a pytest suite covering flow registration, intent matching, execution success, and failure modes.

Reviewed changes

Copilot reviewed 12 out of 14 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
chainweaver/__init__.py	Exposes the public API and version.
chainweaver/tools.py	Implements the schema-validated Tool abstraction.
chainweaver/flow.py	Defines Flow and FlowStep data models.
chainweaver/registry.py	Implements an in-memory FlowRegistry with basic intent matching.
chainweaver/executor.py	Implements deterministic sequential execution with per-step records.
chainweaver/exceptions.py	Adds a typed exception hierarchy for traceable errors.
chainweaver/logging.py	Adds structured logging helpers for step start/end/error.
examples/simple_linear_flow.py	Demonstrates a “double → add_ten → format_result” flow.
tests/test_registry.py	Tests registry behavior (register/get/list/match/overwrite).
tests/test_flow_execution.py	Tests successful execution and key failure modes.
pyproject.toml	Adds packaging metadata and pytest config.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.