Composable Model Graph
Systems field guide / research build

Field note 00 / Executable architecture

R&D status / active Research build · concepts evolving

Design the system before you build the agent.

Explore boundaries, compare architectures, and exercise failure paths with typed transforms before attaching models, tools, and application code. Then run the same graph and inspect what happened.

Input Transform Trace / state Evaluation Feedback
Architecture draft / evidence synthesis responsibilities explicit ↓
Definition → what should happen Implementation attaches later
Boundary register Before implementation

Question

State crossing
Research question and caller context
Responsibility
Caller-defined typed input
Relation to preserve
Intent and scope survive every downstream transform
Failure response
Reject malformed or underspecified input before model work
01 / Problem

Implementation hides architecture.

Prompts, retrieval, tools, loops, and application code quickly become the architecture by accident. A final answer cannot show which boundaries were intentional—or which decisions disappeared inside one agent.

A / Boundary

Which state should cross from one responsibility to the next?

B / Determinism

Which computation should be ordinary code instead of model reasoning?

C / Relation

What must remain true across the whole composition?

D / Failure

Should failure accept, retry, adjust, reject, or ask a human?

Do not let one agent become the architecture.
02 / Primitive

One small model for many systems.

CMG stays domain-free. The core vocabulary is deliberately small enough to investigate, compose, and verify.

01 / Definition

Transform

A named, typed state transition. It does one piece of work and exposes where state changes.

Transform<I, O>
02 / Record

Trace

Every intermediate input and output remains inspectable after a run.

TraceStep[]
03 / Judgment

Evaluation

Decide whether the final state passed, failed, partially passed, or remains unknown.

EvaluationResult
03 / System scan

Find the boundaries before choosing the machinery.

Start with a structured examination, not an automatic generator. The builder decides which boundaries matter; CMG makes those decisions executable and inspectable.

01 / Contract

Input and accepted output

What enters the system, and what evidence makes an output acceptable?

02 / Transitions

State-changing work

Which named transformations turn the input into progressively more useful state?

03 / Responsibility

Deterministic or uncertain

Which work belongs in ordinary code, and where is model reasoning genuinely required?

04 / Boundaries

State crossing each edge

What typed value moves between responsibilities, tools, models, and humans?

05 / Relations

What must remain true

Which caller-defined relationships must survive the full composition?

06 / Response

What follows failure

Should the completed run accept, retry, adjust, reject, or request human input?

Method boundary / CMG does not scan a product idea automatically. The builder projects the problem into transforms, connections, evaluation, and feedback; CMG supplies the executable object.

04 / Architecture lab

Compare system shapes before one agent becomes the system.

Use the same evidence-synthesis problem to inspect four candidate patterns. These are architecture hypotheses—not performance claims. Signals arrive only after execution.

Linear baselineSequential ModelGraph
Makes inspectableThe input, one model boundary, final output, and evaluation.
New failure modeRetrieval, reasoning, and evidence handling remain hidden inside one transform.
Choose whenYou need the smallest baseline before introducing more boundaries.
05 / Execution

See the system you actually built.

The architecture definition and the executed graph are the same object. The terminal view derives from that graph and its completed trace—there is no separately maintained whiteboard diagram.

Executable topology / selected designselect a node ↓
Graph → intended executionTrace → observed execution
Run trace / 0017Evaluation: fail
·Questioninput
Extract evidence+ sources
Generate claims+ claims
×Validate supportclaim c3 unsupported
!Evaluationfail
Feedbackrequest evidence
cmg / renderRunplain text · deterministic
Graph
[Reading] ─┬─▶ [Physics]   ─┐
           └─▶ [Empirical] ─┴─▶ [Reconcile]

Run
  physics       40 → 125
  empirical     40 → 145
  reconcile     [125,145] → 20
  evaluation    fail
  feedback      retry

Run → judge → act → next run

Checked-in values from repository example 12. Feedback returns an action; the caller decides whether to run again.

reading 40 Physics model 40 → 125 Empirical table 40 → 145 Reconcile [125,145] → 20 evaluation fail · feedback retry
06 / Relations

Local validity does not imply system validity.

A transform can return a valid value while the relation between transforms is wrong. Record the relation you expect, then inspect whether the run preserved it.

Evidence synthesis

Claims exist. Support does not.

Expected relation

Every generated claim maps to at least one retrieved source.

Observed violation

Well-formed prose passes local checks while unsupported claims cross the evidence boundary.

Ordered process

Steps pass. Sequence fails.

Expected relation

Analysis must consume the normalized output produced earlier in the run.

Observed violation

Each function accepts its input, but the graph connects analysis to the unnormalized branch.

Reconciliation

Branches agree for the wrong reason.

Expected relation

Independent specialists contribute distinct evidence before reconciliation.

Observed violation

Two branches reuse the same source, creating apparent consensus without independent support.

The graph makes relations inspectable. The evaluator decides which relations matter.

07 / Experiment

Compare evidence after the architectures run.

Architecture sketches make tradeoffs discussable; executed traces make them measurable. Missing evidence stays missing—it is never replaced with a confident score.

Recorded measure
Graph A / naive route
Graph B / structured route
Output qualityexact-match accuracy
46.7%
93.3%
Execution costrecorded costUsd
$0.00208
$0.01198
Token signal
104
703
Retries
not recorded
not recorded
Evidence support
not recorded
not recorded
Useful flow Φaccepted quality / cost
requires chosen quality + cost weights
requires chosen quality + cost weights
Evidence register Quality, tokens, and cost are copied from the checked-in output of TypeScript example 06, “Skill Routing.” Retry and evidence-support signals are not recorded by that example, so this plate does not invent them. CMG exposes usefulFlowScore(quality, cost); callers decide what quality and cost mean.
08 / Surface

Theory in the bones. Executable code at the surface.

Control theory

Informs evaluation and feedback.

judge → act

Neural systems

Inform error and sensitivity.

error × sensitivity

Network flow

Informs useful output and bottlenecks.

Φ = Q / C

Software engineering

Provides types, traces, and deterministic interfaces.

I → O
createTransform(...) createModelGraph(...) graph.run(...)

You should not need to learn the theory before you can inspect the system.

TypeScript and Python capabilities ship at parity. This concise specimen is adapted from the repository’s core pipeline and terminal APIs.

import { createModelGraph, createTransform } from "@composable-model-graph/core";
import { renderRun } from "@composable-model-graph/terminal";

const trim = createTransform<string, string>({
  id: "trim", name: "Trim",
  run: (input) => input.trim(),
});
const words = createTransform<string, string[]>({
  id: "words", name: "Split words",
  run: (input) => input.toLowerCase().split(/\s+/),
});
const graph = createModelGraph({
  id: "pipeline", name: "Core pipeline",
  transforms: [trim, words],
});
const run = await graph.run("  Hello Model Graph  ");
console.log(renderRun(graph, run));
from composable_model_graph import (
    create_model_graph, create_transform,
)
from composable_model_graph.terminal import render_run

trim = create_transform(
    "trim", "Trim", lambda text, ctx: text.strip()
)
words = create_transform(
    "words", "Split words",
    lambda text, ctx: text.lower().split(),
)
graph = create_model_graph(
    "pipeline", "Core pipeline", [trim, words]
)
run = graph.run("  Hello Model Graph  ")
print(render_run(graph, run))
09 / Begin

Design. Run. Inspect. Revise.

Use the architecture workbench to expose boundaries before implementation—then use the same graph to execute, inspect, evaluate, and improve the system.