noodlelab 0.1.0__py3-none-any.whl

noodlelab/__init__.py

@@ -0,0 +1,64 @@
+"""noodlelab: verifiable science for people and AI agents.
+
+For calculations in plain Python (units, uncertainty, requirements, checks and
+a provenance record of every run), use :mod:`noodlelab.verify`::
+
+    import noodlelab.verify as nv
+
+    with nv.record("pendulum") as rec:
+        L = rec.input("L", "1.000 ± 0.002 m", source="tape measure")
+        ...
+
+The public API for node-pack authors lives here::
+
+    from noodlelab import Param, Probe, ProbeContext, RunContext, node, register_type
+"""
+
+from importlib import metadata as _metadata
+
+from .core.codecs import register_codec
+from .core.context import RunContext
+from .core.files import FileRef, as_file
+from .core.health import Problem, error, warning
+from .core.meta import register_meta
+from .core.node import Param, node
+from .core.ports import register_fields
+from .core.preview import Preview, register_preview
+from .core.probe import Probe, ProbeContext, downsample, image_preview, table_preview
+from .core.sample import register_sampler
+from .core.types import register_type
+from .core.uncertainty import Uncertain
+from .core.units import Quantity, register_unit, unit_type
+
+try:  # set from the git tag at build time (hatch-vcs)
+    __version__ = _metadata.version("noodlelab")
+except _metadata.PackageNotFoundError:  # running from a source tree that is not installed
+    __version__ = "0.0.0"
+
+__all__ = [
+    "FileRef",
+    "Param",
+    "Preview",
+    "Probe",
+    "ProbeContext",
+    "Problem",
+    "Quantity",
+    "RunContext",
+    "Uncertain",
+    "as_file",
+    "downsample",
+    "error",
+    "image_preview",
+    "node",
+    "register_codec",
+    "register_fields",
+    "register_meta",
+    "register_preview",
+    "register_sampler",
+    "register_type",
+    "register_unit",
+    "table_preview",
+    "unit_type",
+    "warning",
+    "__version__",
+]

noodlelab/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

noodlelab/agent/__init__.py

@@ -0,0 +1,138 @@
+"""noodlelab for AI coding agents (Claude Code, Codex CLI and others).
+
+- :mod:`noodlelab.agent.mcp`: ``noodlelab mcp``, a Model Context Protocol server
+  whose tools build, check, run and verify graphs and reports
+  (:mod:`noodlelab.agent.tools`).
+- :func:`init_project`: ``noodlelab init-agent``, which sets up a project so that
+  agents working in it find noodlelab. It writes the MCP server into
+  ``.mcp.json``, a section of rules into ``AGENTS.md`` (imported from
+  ``CLAUDE.md``), and a skill in ``.claude/skills/noodlelab/``.
+- ``guide.md``: the rules and workflow, served by the ``guide`` tool and copied
+  into the skill.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+from dataclasses import dataclass, field
+from importlib import resources
+from pathlib import Path
+
+START, END = "<!-- noodlelab:start -->", "<!-- noodlelab:end -->"
+
+SKILL_HEADER = """\
+---
+name: noodlelab
+description: Verifiable scientific and engineering calculations with noodlelab - units and
+  uncertainty on every number, requirements checked with margins, checks, and a provenance
+  record of every run. Use whenever code computes physical quantities, measurement results,
+  design margins or other results people rely on, or when asked to build or change a
+  noodlelab graph, report or requirement.
+---
+
+"""
+
+AGENTS_SECTION = """\
+## Verifiable calculations (noodlelab)
+
+This project uses [noodlelab](https://github.com/nkalis/noodlelab) so that its
+calculations can be checked, not just trusted. When code computes a physical
+quantity, a measurement result or a design margin:
+
+- Use quantities with units (`nv.q("9.81 m/s^2")`), and measured values with an
+  uncertainty and a source (`rec.input("g", "9.81 ± 0.02 m/s^2", source=...)`).
+- Write requirements down (`COM-001 link_margin >= 3 dB [Analysis]`) and verify
+  each one; report margins, not just pass/fail.
+- Wrap each calculation in `with noodlelab.verify.record(...)` (or build it as a
+  noodlelab graph), so every run leaves a `provenance.json`.
+- Before saying the work is done, run `noodlelab verify <script.py|graph.json>
+  --json` and fix what it reports.
+
+The `noodlelab` MCP server (in `.mcp.json`) can build, run and verify graphs and PDF
+reports. Call its `guide` tool first. The full guide is in
+`.claude/skills/noodlelab/SKILL.md`.
+"""
+
+
+@dataclass
+class Setup:
+    """What :func:`init_project` did."""
+
+    written: list[str] = field(default_factory=list)
+    unchanged: list[str] = field(default_factory=list)
+    hints: list[str] = field(default_factory=list)
+
+
+def guide() -> str:
+    return (resources.files("noodlelab.agent") / "guide.md").read_text("utf-8")
+
+
+def mcp_command() -> tuple[str, list[str]]:
+    """How an agent should start the server: the installed ``noodlelab`` when
+    there is one, else uvx (which fetches it)."""
+    if shutil.which("noodlelab"):
+        return "noodlelab", ["mcp"]
+    return "uvx", ["noodlelab", "mcp"]
+
+
+def init_project(
+    project: str | Path,
+    *,
+    command: tuple[str, list[str]] | None = None,
+    claude: bool = True,
+    mcp: bool = True,
+) -> Setup:
+    """Set up ``project`` for AI agents (idempotent: run it again to update)."""
+    root = Path(project).resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    done = Setup()
+    cmd, args = command or mcp_command()
+
+    def write(rel: str, text: str) -> None:
+        path = root / rel
+        old = path.read_text("utf-8") if path.is_file() else None
+        if old == text:
+            done.unchanged.append(rel)
+            return
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(text, "utf-8")
+        done.written.append(rel)
+
+    # AGENTS.md: read by Codex, Cursor, Copilot, Gemini CLI and many others
+    agents = root / "AGENTS.md"
+    old = agents.read_text("utf-8") if agents.is_file() else "# Notes for AI agents\n"
+    write("AGENTS.md", _with_section(old, AGENTS_SECTION))
+
+    if claude:
+        # Claude Code reads CLAUDE.md, which can import AGENTS.md
+        claude_md = root / "CLAUDE.md"
+        text = claude_md.read_text("utf-8") if claude_md.is_file() else ""
+        if "@AGENTS.md" not in text:
+            text = (text.rstrip() + "\n\n" if text.strip() else "") + "@AGENTS.md\n"
+        write("CLAUDE.md", text)
+        write(".claude/skills/noodlelab/SKILL.md", SKILL_HEADER + guide())
+
+    if mcp:
+        path = root / ".mcp.json"
+        config = {}
+        if path.is_file():
+            try:
+                config = json.loads(path.read_text("utf-8"))
+            except ValueError:
+                done.hints.append(".mcp.json is not valid JSON: left as it is")
+                config = None
+        if config is not None:
+            config.setdefault("mcpServers", {})["noodlelab"] = {"command": cmd, "args": args}
+            write(".mcp.json", json.dumps(config, indent=2) + "\n")
+        codex = " ".join(["codex mcp add noodlelab --", cmd, *args])
+        done.hints.append(f"Codex CLI: {codex}")
+    return done
+
+
+def _with_section(text: str, section: str) -> str:
+    block = f"{START}\n{section.rstrip()}\n{END}"
+    if START in text and END in text:
+        return re.sub(re.escape(START) + r".*?" + re.escape(END), lambda _: block, text, flags=re.S)
+    return text.rstrip() + "\n\n" + block + "\n"

noodlelab/agent/guide.md

@@ -0,0 +1,129 @@
+# noodlelab for AI agents
+
+noodlelab makes scientific and engineering calculations verifiable. Use it
+whenever code computes a physical quantity, a measurement result, a design
+margin or anything a person will rely on. The point is that a reviewer (or
+another agent) can check what you did, not just trust it.
+
+## The rules
+
+1. **Units on every number.** Use quantities (`q("9.81 m/s^2")`), never bare
+   floats with the unit in a variable name or a comment. Mixing dimensions then
+   raises instead of silently giving nonsense. Dimensionless results say so
+   (`unit="1"`).
+2. **Uncertainty on every measured input, and a source.** Write
+   `"9.81 ± 0.02 m/s^2"` and say where it came from (an instrument, datasheet,
+   paper or dataset). Uncertainty propagates by itself (GUM, first order, with
+   correlations kept). `budget()` shows which input dominates. For strongly
+   non-linear models, check with `monte_carlo()`.
+3. **Write the requirements down before checking them**, one per line:
+   `COM-001 link_margin >= 3 dB [Analysis]  # The link shall close with 3 dB to spare`.
+   Verify each one: a check reports its margin, not just pass or fail.
+4. **Leave a record.** Wrap the calculation in `with nv.record(...)`, or build
+   it as a graph. Every run then writes a `provenance.json` holding inputs,
+   results, checks, the code (hash, git commit), files (SHA-256) and the
+   environment.
+5. **Verify before you say you are done.** Run `noodlelab verify <script.py |
+   graph.json> --json` and fix what it reports. Exit code 0 means every check
+   passed and every requirement was verified. Report the margins and any
+   warnings to the user; don't hide failures.
+
+Never invent a measured value or its uncertainty. When a number is assumed,
+say so with `rec.note(...)` and `source="assumed: ..."`.
+
+## Python: `noodlelab.verify`
+
+```python
+import noodlelab.verify as nv
+
+with nv.record("link budget") as rec:  # writes runs/<time>-link-budget-<id>/provenance.json
+    p_tx = rec.input("p_tx", "10.0 ± 0.3 W", source="PA datasheet rev C")
+    d = rec.input("d", nv.q("1200 km"), source="orbit design")
+    ...
+    margin = rec.result("link_margin", computed_margin)  # a quantity, e.g. in dB
+    rec.require("COM-001 link_margin >= 3 dB [Analysis]  # The link shall close")
+    rec.verify("COM-001", margin)  # Check(passed, margin=+1.2 dB, ...)
+    rec.expect(0 < efficiency.m < 1, "efficiency is a fraction")
+    rec.close_to("vs. textbook", result, nv.q("2.006 s"), rtol=0.01)
+print(rec.summary())
+```
+
+- `nv.q(text_or_number, unit)` returns an exact quantity. `nv.measure("x ± u unit")`
+  or `nv.measure(x, u, unit, name=...)` returns an uncertain one.
+- `nv.requirements(text)` and `nv.verify(req, value)` work outside a record too.
+- `@nv.traced` records every call of a function (arguments, result, source hash)
+  inside a record.
+- `nv.monte_carlo(model, trials)`, where `model` makes its inputs with
+  `measure()` and returns the result, checks whether the GUM result can be
+  trusted (JCGM 101).
+- `nv.audit(record)` lists findings NL001–NL010: failed checks, unverified
+  requirements, results without units or uncertainty, inputs without a source,
+  and code that was dirty or has changed since.
+
+## Graphs: node pipelines the user can open in the editor
+
+A graph is a JSON file `<name>.graph.json` in the workspace. Nodes are typed
+Python functions (`list_nodes`, `describe_node`). Every input is either a
+value or a link to another node's output:
+
+```json
+{"nodes": [
+  {"id": "1", "type": "core.number", "inputs": {"value": {"value": 3}}},
+  {"id": "2", "type": "core.math",
+   "inputs": {"operation": {"value": "power"},
+              "a": {"link": {"node": "1", "output": "result"}},
+              "b": {"value": 2}}}
+ ],
+ "report": [
+  {"id": "1", "type": "report.new_report", "inputs": {"title": {"value": "Results"}}},
+  {"id": "2", "type": "report.add_value",
+   "inputs": {"report": {"link": {"node": "1", "output": "result"}},
+              "label": {"value": "3 squared"},
+              "value": {"link": {"node": "2", "output": "result", "tab": "processing"}}}},
+  {"id": "3", "type": "report.render_report",
+   "inputs": {"report": {"link": {"node": "2", "output": "result"}}}}
+ ]}
+```
+
+- `nodes` is the processing canvas and `report` is the Reporting canvas. A
+  report node reads a processing output with `"tab": "processing"` in its
+  link. Data only flows from processing into the report.
+- The usual shape for a verified analysis:
+  - **Requirements** (`requirements.requirements`, one per line), then the
+    inputs, with units and uncertainty (`units.*`, `uncertainty.*`), then the
+    model.
+  - **Verify Requirement** for each requirement, chaining its `log` output
+    from one to the next.
+  - A report: **New Report**, Add Heading / Text / Value / Figure /
+    Requirements, then Add Compliance Matrix (from the last `log`), Run
+    Details (provenance), and Render Report (the PDF).
+- Start from a similar example (`list_examples`, `get_example`). Example 23
+  (satellite link budget) and example 24 (cantilever bracket) are complete
+  verified studies with reports.
+
+## MCP tools (server `noodlelab mcp`)
+
+| Tool | Use |
+|---|---|
+| `guide` | this text |
+| `list_nodes`, `describe_node` | find nodes and their inputs, outputs, units and options |
+| `list_examples`, `get_example` | complete graphs to copy from |
+| `list_graphs`, `get_graph` | the workspace's graphs |
+| `save_graph` | write a whole graph (validated; the open editor reloads it) |
+| `edit_graph` | add, set, remove, retitle or track nodes without resending the graph |
+| `check_graph` | problems before running: types, units, missing inputs |
+| `run_graph` | run it; returns each node's result, checks, requirements, files and provenance |
+| `requirements` | each requirement's latest verdict, margin and history |
+| `verify` | audit a script, graph or records, as `noodlelab verify --json` does |
+
+When you are started from the editor's Agent panel, the user is watching the
+canvas: every graph you save opens there, laid out automatically.
+`NOODLELAB_GRAPH` names the graph they had open.
+
+The workflow:
+1. `guide`, then `list_examples` / `list_nodes`.
+2. `save_graph`, then `check_graph` until there are no errors.
+3. `run_graph`, then read the checks and margins.
+4. Fix and iterate. Finish with `verify`.
+5. Tell the user what passed, the margins, what was assumed, and where the
+   report PDF and provenance are.

noodlelab/agent/mcp.py

@@ -0,0 +1,219 @@
+"""``noodlelab mcp``: the workspace's tools for AI agents over the Model Context
+Protocol (stdio).
+
+Add it to an agent once and it can build, check, run and verify graphs and
+reports, and audit scripts::
+
+    claude mcp add noodlelab -- uvx noodlelab mcp          # Claude Code
+    codex mcp add noodlelab -- uvx noodlelab mcp           # Codex CLI
+
+or write ``.mcp.json`` with ``noodlelab init-agent``. The protocol is small
+enough to speak directly (JSON-RPC 2.0, one message per line on stdin and
+stdout), so the server needs nothing beyond the library itself.
+"""
+
+from __future__ import annotations
+
+import inspect
+import json
+import sys
+import traceback
+import typing
+from collections.abc import Callable
+from pathlib import Path
+from typing import IO, Any
+
+from .. import __version__
+from .tools import Remote, ToolError, Workspace
+
+PROTOCOL_VERSIONS = ("2025-06-18", "2025-03-26", "2024-11-05")
+TOOLS = (
+    "guide",
+    "list_nodes",
+    "describe_node",
+    "list_examples",
+    "get_example",
+    "copy_example",
+    "list_graphs",
+    "get_graph",
+    "save_graph",
+    "edit_graph",
+    "check_graph",
+    "run_graph",
+    "requirements",
+    "verify",
+)
+READ_ONLY = {
+    "guide",
+    "list_nodes",
+    "describe_node",
+    "list_examples",
+    "get_example",
+    "list_graphs",
+    "get_graph",
+    "check_graph",
+    "requirements",
+}
+INSTRUCTIONS = (
+    "noodlelab makes calculations verifiable: units and uncertainty on every number, "
+    "requirements checked with margins, a provenance record of every run. Call `guide` "
+    "first. Build analyses as graphs (save_graph/edit_graph, check_graph, run_graph) or as "
+    "Python with noodlelab.verify, and finish with `verify`."
+)
+
+
+def _schema(fn: Callable[..., Any]) -> dict[str, Any]:
+    """A JSON schema of a tool's arguments, from its signature."""
+    hints = typing.get_type_hints(fn)
+    props: dict[str, Any] = {}
+    required = []
+    for name, p in inspect.signature(fn).parameters.items():
+        if name == "self":
+            continue
+        props[name] = _json_type(hints.get(name, Any))
+        if p.default is inspect.Parameter.empty:
+            required.append(name)
+        else:
+            props[name]["default"] = p.default
+    return {"type": "object", "properties": props, "required": required}
+
+
+def _json_type(hint: Any) -> dict[str, Any]:
+    origin = typing.get_origin(hint)
+    if origin in (typing.Union, getattr(__import__("types"), "UnionType", None)):
+        args = [a for a in typing.get_args(hint) if a is not type(None)]
+        return _json_type(args[0]) if len(args) == 1 else {}
+    if hint is str:
+        return {"type": "string"}
+    if hint is bool:
+        return {"type": "boolean"}
+    if hint is int:
+        return {"type": "integer"}
+    if hint is float:
+        return {"type": "number"}
+    if origin is list or hint is list:
+        (item,) = typing.get_args(hint) or (Any,)
+        return {"type": "array", "items": _json_type(item)}
+    if origin is dict or hint is dict:
+        return {"type": "object"}
+    return {}
+
+
+class Server:
+    """Answers MCP requests with a :class:`Workspace`'s tools."""
+
+    def __init__(self, workspace: Workspace) -> None:
+        self.ws = workspace
+        self.tools = {name: getattr(workspace, name) for name in TOOLS}
+
+    def tool_list(self) -> list[dict[str, Any]]:
+        out = []
+        for name, fn in self.tools.items():
+            doc = inspect.getdoc(fn) or ""
+            out.append(
+                {
+                    "name": name,
+                    "description": doc,
+                    "inputSchema": _schema(fn),
+                    "annotations": {"readOnlyHint": name in READ_ONLY},
+                }
+            )
+        return out
+
+    def handle(self, msg: dict[str, Any]) -> dict[str, Any] | None:
+        """The response to one JSON-RPC message (None for a notification)."""
+        method, mid = msg.get("method"), msg.get("id")
+        if mid is None:  # notifications/initialized, cancelled...
+            return None
+        try:
+            result = self._dispatch(method, msg.get("params") or {})
+        except _RpcError as exc:
+            return {"jsonrpc": "2.0", "id": mid, "error": {"code": exc.code, "message": str(exc)}}
+        return {"jsonrpc": "2.0", "id": mid, "result": result}
+
+    def _dispatch(self, method: str | None, params: dict[str, Any]) -> Any:
+        if method == "initialize":
+            asked = params.get("protocolVersion")
+            return {
+                "protocolVersion": asked if asked in PROTOCOL_VERSIONS else PROTOCOL_VERSIONS[0],
+                "capabilities": {"tools": {"listChanged": False}},
+                "serverInfo": {"name": "noodlelab", "version": __version__},
+                "instructions": INSTRUCTIONS,
+            }
+        if method == "ping":
+            return {}
+        if method == "tools/list":
+            return {"tools": self.tool_list()}
+        if method == "tools/call":
+            return self.call(params.get("name", ""), params.get("arguments") or {})
+        if method in ("resources/list", "prompts/list"):
+            return {method.split("/")[0]: []}
+        raise _RpcError(-32601, f"Method not found: {method}")
+
+    def call(self, name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+        fn = self.tools.get(name)
+        if fn is None:
+            raise _RpcError(-32602, f"Unknown tool: {name}")
+        try:
+            value = fn(**arguments)
+        except ToolError as exc:
+            return _content(str(exc), error=True)
+        except TypeError as exc:  # arguments that do not fit the signature
+            return _content(f"Bad arguments for {name}: {exc}", error=True)
+        except Exception as exc:  # report the failure to the agent, keep serving
+            detail = "".join(traceback.format_exception_only(type(exc), exc)).strip()
+            return _content(f"{name} failed: {detail}", error=True)
+        return _content(value)
+
+
+class _RpcError(Exception):
+    def __init__(self, code: int, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def _content(value: Any, *, error: bool = False) -> dict[str, Any]:
+    text = value if isinstance(value, str) else json.dumps(value, indent=1, default=str)
+    out: dict[str, Any] = {"content": [{"type": "text", "text": text}], "isError": error}
+    if isinstance(value, dict) and not error:
+        out["structuredContent"] = json.loads(json.dumps(value, default=str))
+    return out
+
+
+def serve(
+    workspace: Workspace, stdin: IO[str] | None = None, stdout: IO[str] | None = None
+) -> None:
+    """Answer requests on stdin until it closes. Anything a node prints goes to
+    stderr, so stdout carries only protocol messages."""
+    stdin = stdin or sys.stdin
+    out = stdout or sys.stdout
+    server = Server(workspace)
+    real_stdout = sys.stdout
+    sys.stdout = sys.stderr  # prints from nodes and scripts must not corrupt the protocol
+    try:
+        for line in stdin:
+            if not line.strip():
+                continue
+            try:
+                msg = json.loads(line)
+            except ValueError:
+                reply: Any = {
+                    "jsonrpc": "2.0",
+                    "id": None,
+                    "error": {"code": -32700, "message": "Parse error"},
+                }
+            else:
+                if isinstance(msg, list):  # a batch
+                    reply = [r for m in msg if (r := server.handle(m)) is not None] or None
+                else:
+                    reply = server.handle(msg)
+            if reply is not None:
+                out.write(json.dumps(reply, default=str) + "\n")
+                out.flush()
+    finally:
+        sys.stdout = real_stdout
+
+
+def main(root: Path, home: Path | None = None) -> int:
+    serve(Workspace(root, remote=Remote.from_env(), home=home))
+    return 0