noodlelab

Verifiable science for AI agents, and for the people who check their work.

AI agents write scientific and engineering code quickly, but nothing makes them show their work. A number comes back without a unit, a measured input without an uncertainty, a design "works" without saying by how much, and nobody can say later what was run. noodlelab gives every calculation:

• units on every number;
• uncertainty on every measured input;
• requirements that are checked, with margins;
• a provenance record of every run.

Then it audits the calculation, so an agent can prove its work and you can check it.

_{Example 24: sizing a cantilever bracket. Each requirement shows its margin and the run that verified it.}

Designed for AI agents

noodlelab is built around the loop a coding agent works in: write, run, check, fix. Each part of it is machine-readable, and the agent can't skip a step without it showing.

This is what an agent sees when it cuts corners:

$ noodlelab verify sloppy.py
✗ sloppy.py
  ✗ beam sizing: incomplete
    ✓ STR-001: 180 MPa meets ≤ 250 MPa (margin +70 MPa, +28.0 %)
    ! NL002 DEF-001 was never verified
    ! NL004 result 'stress' has no unit (say unit='1' if it is dimensionless)
    ! NL005 result 'stress' has no uncertainty (give its inputs one, or exact=True)
    · NL006 input 'load' has no source
    record: runs/20260926-100232-beam-sizing-4eece145/provenance.json
0 of 1 passed

The exit code is 1, so the agent doesn't report "done" until it has fixed these.

Three ways in

1. The Agent panel in the editor. Press Agent to open Claude Code or Codex CLI in a terminal under the canvas, sign in as it asks, and describe the analysis. It builds the graph, the requirements and the report through noodlelab's tools, and every graph it saves appears on your canvas.

_{A drop test built by an agent: fall time and impact speed from √(2h/g) and √(2gh) with propagated uncertainty, two requirements verified, a PDF report. Here a scripted agent calls the same MCP tools Claude Code would.}

2. Your own agent, in your own project.

uv add noodlelab && noodlelab init-agent   # AGENTS.md, CLAUDE.md, skill, .mcp.json
codex mcp add noodlelab -- noodlelab mcp   # Codex CLI (Claude Code reads .mcp.json)

The MCP server has tools for:

• finding nodes and examples;
• saving and editing graphs;
• checking and running them;
• reading requirement verdicts;
• verifying scripts and graphs.

docs/agents/adopt-in-existing-project.md is the step-by-step for "make my project verifiable".

3. Plain Python, for scripts, notebooks and tests (pip install noodlelab):

import noodlelab.verify as nv

with nv.record("drop test") as rec:  # writes runs/<...>/provenance.json
    h = rec.input("h", "2.00 ± 0.01 m", source="tape measure, lab book p. 4")
    g = rec.input("g", "9.81 ± 0.02 m/s^2", source="local gravity survey")
    t = rec.result("fall time", (2 * h / g) ** 0.5)  # (0.6386 ± 0.0017) s
    v = rec.result("impact speed", (2 * g * h) ** 0.5)  # (6.264 ± 0.017) m/s
    rec.require("""
        DRP-001 fall_time <= 1 s [Analysis]      # The drop shall take at most 1 s
        DRP-002 impact_speed <= 7 m/s [Analysis] # The part shall land below 7 m/s
    """)
    rec.verify("DRP-001", t)
    rec.verify("DRP-002", v)

$ noodlelab verify drop.py
✓ drop.py
  ✓ drop test: passed
    ✓ DRP-001: 0.6386 s meets ≤ 1 s (margin +0.3614 s, +36.1 %)
    ✓ DRP-002: 6.264 m/s meets ≤ 7 m/s (margin +0.7358 m/s, +10.5 %)
1 of 1 passed

What each piece does:

• Units: Pint quantities, so adding metres to seconds raises an error.
• Uncertainty: propagated as the GUM describes, with correlations kept. nv.budget() shows which input dominates, and nv.monte_carlo() checks whether the linear result holds.
• Requirements: written as text a person can read, and verified with margins.
• Checking a result: rec.expect() tests any condition, rec.close_to() compares with a reference value, and @nv.traced records a function's calls.

See the quickstart.

The editor

Every node is a type-hinted Python function. You wire them up in the browser, see previews on the nodes while you edit, and write the results up as a PDF.

A link budget (example 23): symbolic equations with units, five requirements, a trade over candidate radios.

A geospatial study (example 20): well data joined with districts, interpolated and summarised, with a map preview on every node.

The Reporting canvas builds the report from what Processing computed. The Outputs list has every figure, table and number, ready to drag in (⧉ shows Processing and Reporting side by side):

Rendering the report gives the equations, figures, compliance matrix and a reproducibility appendix (run, software versions, input checksums, every step):

Also in the editor:

• Requirements and Tracked tabs, which follow verdicts and values from run to run, with where each came from.
• Checkpoints, so runs resume where they left off.
• Sweep, optimize and repeat zones.
• Uncertainty budgets and Monte Carlo.
• Export to plain Python.
• Shared servers with roles, and Slurm clusters.

docs/editor.md has the details, and the Help tab has 24 examples to open and run.

Install

pip install noodlelab           # the library: noodlelab.verify, verify/run/test/mcp on the command line
uvx "noodlelab[full]" .         # the editor with every node pack, on this folder

docs/installation.md lists every node by tier, and explains adding packs and remote storage.

Command line

noodlelab verify model.py analysis.graph.json --json  # run and audit: exit 1 if anything fails
noodlelab mcp                                         # the MCP server for agents (stdio)
noodlelab init-agent                                  # set up a project for agents
noodlelab run analysis.graph.json -v                  # run a graph headless
noodlelab test *.graph.json --baseline final          # checks and regression against a final run
noodlelab export analysis.graph.json -o analysis.py   # a graph as a plain Python script
noodlelab serve .                                     # the editor

Writing a node

from noodlelab import Quantity, node


@node(category="Engineering/Structures")
def bending_stress(moment: Quantity["N*m"], section_modulus: Quantity["mm^3"]) -> Quantity["MPa"]:
    """Bending stress at the outer fibre: M / Z."""
    return (moment / section_modulus).to("MPa")

The type hints decide the sockets, units and widgets. Links convert units on the way in, and the editor refuses to link incompatible dimensions. The docstring is the help text that people and agents read. Uncertainty propagates through the node without any code in it: give it 1200 ± 30 N·m and it returns (150.0 ± 3.7) MPa. Ship nodes as a pack with a noodlelab.nodes entry point: see examples/noodlelab-example-pack, or run noodlelab new-pack.

More

• For agents: AGENTS.md, llms.txt, docs/llms-full.txt (the whole API and every node in one file), docs/agents
• Installation tiers and every node · The editor · Shared servers, Slurm and Docker · Slurm in detail · Releasing
• Development: make install, make dev (API on :8000, Vite on :5173), make test lint

License

See LICENSE.