noodlelab

The scientific method, for code.

Units, uncertainty, requirements and provenance on every calculation, whether a student, a professor, an engineer or an AI wrote it.

Most scientific and engineering code passes bare floating-point numbers around: stress = 180.0. Is that MPa or psi? Plus or minus what? Is it good enough, and by how much? Which inputs produced it, and could anyone rerun it next year? A good lab notebook answers these questions. Code usually doesn't. noodlelab makes it answer them, by giving every calculation:

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

Then it audits the calculation and tells you what is missing, so the work can be checked by the person who did it and by everyone who relies on it.

AI agents get the same discipline through a built-in MCP server (noodlelab mcp): Claude Code, Codex CLI or any MCP client can build, run and verify analyses you can open and review. See Built for code written by AI.

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

A calculation that shows its work

In 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 instead of giving a wrong number.
• 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.
• Constants: nv.const.c, nv.const.g0 or rec.constant("k_B") instead of retyped digits: each has its unit and source, and measured ones (G, m_e...) their CODATA uncertainty. Your own go in a workspace's constants.toml or a graph's Constants tab.
• Checking a result: rec.expect() tests any condition, rec.close_to() compares with a reference value, and @nv.traced records a function's calls.
• Provenance: every run writes a provenance.json with the inputs and their sources, the results, the checks, the code's hash and git commit, file SHA-256s and the environment.

See the quickstart.

Who it's for

The audit

A calculation that runs is not the same as a calculation that is right. noodlelab verify runs a script or graph and audits it (NL001–NL011): it flags requirements that were never verified or whose margin is within the result's uncertainty, results without units or uncertainty, inputs without a source, and uncommitted code.

$ 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 0 only when every check passed and every requirement was verified, so the same command works in CI, in a grading script, or as the last step before you call an analysis finished. --json gives the verdict as data.

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.
• A Constants tab and a Constant node: π, c, g0, k_B... built in, plus the workspace's and the graph's own.
• 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, remote storage and Slurm clusters (below).

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

Built for code written by AI

More and more scientific code will be written by AI. It is written quickly and reads fluently, which makes a quiet mistake easy to miss: a dropped unit, an ignored uncertainty, a design that "works" without saying by how much. noodlelab is designed to be the human side of that work. Whatever an agent builds, you can read it: graphs open as nodes in the editor, every result carries its unit and uncertainty, every run leaves a record, and noodlelab verify fails until the work has actually been checked. The agent does the typing; you stay the reviewer.

An MCP server, built in

noodlelab mcp is a Model Context Protocol server that ships with the bare library, with no extra dependencies. Add it to Claude Code, Codex CLI, Cursor or any other MCP client, and the agent works through noodlelab instead of writing loose floats next to it:

claude mcp add noodlelab -- uvx noodlelab mcp   # Claude Code
codex mcp add noodlelab -- uvx noodlelab mcp    # Codex CLI

Every run the agent starts is a real run: it writes provenance and adds to the graph's requirement and tracked-value history, like a run from the editor. And when the server is connected to a running editor (as it is in the Agent panel below), every graph the agent saves reloads on your canvas as it saves it, so you watch the analysis being built node by node.

The Agent panel in the editor. Press Agent to open Claude Code or Codex CLI in a terminal under the canvas, already connected to the MCP server. Sign in as it asks and describe the analysis. It builds the graph, the requirements and the report through noodlelab's tools, and each graph it saves appears on your canvas, where you can inspect it.

_{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.}

Your own agent, in your own project.

uv add noodlelab && noodlelab init-agent   # AGENTS.md, CLAUDE.md, skill, .mcp.json

init-agent registers the MCP server in .mcp.json (which Claude Code reads) alongside the instructions and skill.

As a Claude Code plugin. The skill and the MCP server in one install, for every project:

claude plugin marketplace add nkalis/noodlelab
claude plugin install noodlelab@noodlelab

The MCP server is also listed in the MCP Registry as io.github.nkalis/noodlelab, for clients that install servers from it. docs/agents/adopt-in-existing-project.md is the step-by-step for "make my project verifiable".

Everything else is machine-readable too

An agent can't skip a step without it showing:

One server for the whole team

noodlelab serve on a laptop needs no setup. The same editor also runs as a shared server for a lab, a group or a company, with an admin portal for the rest.

Users and roles. With --auth users, admins create accounts and everyone signs in with a personal token. Each workspace is a project with its own members, and each member has a role:

The server enforces the roles; viewers and runners get a read-only canvas. Graphs reach only their own workspace's files and the admin's mounts, so one project cannot read another's (a shared folder on the server is a local:// mount). Guest links give someone without an account view-only or view-and-run access to one workspace until they expire or are revoked.

Remote storage. An admin gives remote storage a short name, a mount, such as lab-s3 → s3://my-bucket/raw, and can limit it to some workspaces. Nodes then read lab-s3://2026/run1.csv as if it were local, and people see the mount's name, never its URL or credentials. Any fsspec backend works: S3 (and MinIO, Ceph, R2), Google Cloud Storage, Azure, SFTP, SMB, HTTP, or a network share on the server. Install the extras you need, for example "noodlelab[full,s3]".

Slurm clusters. Point the server at a Slurm cluster under Admin → Cluster and people get a Run on menu: On the server or On the cluster. A cluster run is a batch job, but it looks the same in the editor: live progress, previews, reports, Stop to cancel. Its checkpoints and provenance land in the workspace, so the next run reuses them wherever it runs, and the provenance records who ran it.

docs/server.md covers roles, guest links and Docker, and docs/slurm.md the cluster setup.

Install

pip install noodlelab           # the library: noodlelab.verify, verify/run/test 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 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
noodlelab init-agent                                  # set up a project for AI agents
noodlelab mcp                                         # the MCP server for agents (stdio)

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. A node never changes what it is given: results are cached and shared with every node linked to them, so arrays arrive read-only (copy one before changing it, x = x.copy()), while tables and lists arrive as copies of their own. Ship nodes as a pack with a noodlelab.nodes entry point: see examples/noodlelab-example-pack, or run noodlelab new-pack.

More

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

License

See LICENSE.