noodlelab 0.1.0__tar.gz

noodlelab-0.1.0/.claude/skills/noodlelab/SKILL.md

@@ -0,0 +1,138 @@
+---
+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.
+---
+
+# 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-0.1.0/.devcontainer/devcontainer.json

@@ -0,0 +1,21 @@
+// "Open in GitHub Codespaces": a private, throwaway copy of noodlelab for each visitor.
+// A codespace is billed to the account that creates it (GitHub includes free monthly
+// hours), not to this repository's owner.
+{
+  "name": "noodlelab",
+  "image": "mcr.microsoft.com/devcontainers/python:3.12",
+  "features": {
+    "ghcr.io/devcontainers/features/node:1": { "version": "22" }
+  },
+  "postCreateCommand": "pip install --user uv && uv sync --extra full && cd frontend && npm ci && npm run build",
+  // A workspace outside the repository, so trying things out leaves git clean.
+  "postAttachCommand": "mkdir -p ~/noodlelab-workspace && uv run noodlelab serve ~/noodlelab-workspace --no-browser",
+  "forwardPorts": [8000],
+  "portsAttributes": {
+    "8000": { "label": "noodlelab", "onAutoForward": "openBrowser" }
+  },
+  "customizations": {
+    "vscode": { "extensions": ["ms-python.python", "charliermarsh.ruff"] },
+    "codespaces": { "openFiles": ["README.md"] }
+  }
+}

noodlelab-0.1.0/.dockerignore

@@ -0,0 +1,15 @@
+.git
+.github
+.venv
+**/__pycache__
+**/*.pyc
+.pytest_cache
+.ruff_cache
+noodlelab-data
+noodlelab-output
+dist
+frontend/node_modules
+frontend/public/vendor
+src/noodlelab/static
+examples
+tests

noodlelab-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,89 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  # the release workflow runs these checks before it builds anything
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # the version comes from the git tags
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - run: uv sync --locked --all-extras
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pytest -q
+
+  frontend:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - run: npm ci
+      - run: npm run typecheck
+      - run: npm run build
+
+  # Each installation tier on its own: exactly its packs load (a bigger tier's
+  # dependency leaking into a smaller extra fails here), and every example it
+  # covers runs.
+  tiers:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        tier: [library, basic, maths, science, engineering, geo, full]
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+          enable-cache: true
+      - name: Install the ${{ matrix.tier }} tier
+        run: |
+          uv venv .tier
+          case "${{ matrix.tier }}" in
+            library) spec="." ;;
+            basic) spec=".[app]" ;;
+            *) spec=".[${{ matrix.tier }}]" ;;
+          esac
+          VIRTUAL_ENV=.tier uv pip install "$spec"
+      - name: Check its packs and run its examples
+        run: .tier/bin/python scripts/check_tier.py ${{ matrix.tier }} --examples
+
+  docker:
+    runs-on: ubuntu-latest
+    needs: [python, frontend]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          push: false
+          tags: noodlelab:ci
+          cache-from: type=gha,scope=full
+          cache-to: type=gha,mode=max,scope=full

noodlelab-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,287 @@
+name: Release
+
+# Push a version tag to release it:
+#
+#   git tag v0.3.0 && git push origin v0.3.0        # PyPI, GitHub Release, Docker images
+#   git tag v0.3.0rc1 && git push origin v0.3.0rc1  # a pre-release: TestPyPI instead of PyPI
+#
+# checks -> build -> smoke -> GitHub Release -> PyPI / TestPyPI + Docker (GHCR) -> verify
+#
+# One-time setup (see docs/releasing.md): trusted publishers on PyPI and TestPyPI
+# for this workflow, with the environments "pypi" and "testpypi".
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+env:
+  TAG: ${{ github.ref_name }}
+
+jobs:
+  checks:
+    uses: ./.github/workflows/ci.yml
+
+  build:
+    needs: checks
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      prerelease: ${{ steps.version.outputs.prerelease }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # hatch-vcs reads the version from the tag
+      - name: Version from the tag
+        id: version
+        run: |
+          version="${TAG#v}"
+          if ! [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+((a|b|rc)[0-9]+)?$ ]]; then
+            echo "::error::Tag $TAG is not vX.Y.Z or vX.Y.Z(a|b|rc)N"
+            exit 1
+          fi
+          echo "version=$version" >> "$GITHUB_OUTPUT"
+          if [[ "$version" =~ (a|b|rc) ]]; then pre=true; else pre=false; fi
+          echo "prerelease=$pre" >> "$GITHUB_OUTPUT"
+          echo "Releasing $version (pre-release: $pre)"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - name: Build the editor into the package
+        working-directory: frontend
+        run: npm ci && npm run build
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - name: Check the distributions
+        env:
+          VERSION: ${{ steps.version.outputs.version }}
+        run: |
+          ls -l dist
+          wheel="dist/noodlelab-${VERSION}-py3-none-any.whl"
+          test -f "$wheel" || { echo "::error::No $wheel: the built version is not the tag's"; exit 1; }
+          test -f "dist/noodlelab-${VERSION}.tar.gz"
+          for page in index.html admin.html; do
+            unzip -l "$wheel" | grep -q "noodlelab/static/$page" \
+              || { echo "::error::The wheel has no editor ($page)"; exit 1; }
+          done
+          uvx twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  # The wheel installs and serves on every OS, before anything is published.
+  smoke:
+    needs: build
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        tier: [basic]
+        include:
+          - os: ubuntu-latest
+            tier: full
+    runs-on: ${{ matrix.os }}
+    defaults:
+      run:
+        shell: bash
+    env:
+      VERSION: ${{ needs.build.outputs.version }}
+      TIER: ${{ matrix.tier }}
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - name: Install the wheel as a uv tool
+        run: |
+          if [ "$TIER" = basic ]; then spec="noodlelab[app]==$VERSION"; else spec="noodlelab[$TIER]==$VERSION"; fi
+          uv tool install "$spec" --find-links dist
+          uv tool dir --bin >> "$GITHUB_PATH"
+      - name: Version and tier
+        run: |
+          noodlelab --version | tee version.txt
+          grep -qF "$VERSION" version.txt
+          noodlelab tiers --json > tiers.json
+          uv run --no-project python -c "import json; r = json.load(open('tiers.json')); assert r['installed'] == '$TIER', r"
+      - name: The server starts
+        run: |
+          mkdir ws
+          noodlelab serve ws --no-browser --port 8123 > serve.log 2>&1 &
+          for _ in $(seq 1 60); do
+            if curl -fsS http://127.0.0.1:8123/api/health; then exit 0; fi
+            sleep 1
+          done
+          cat serve.log
+          exit 1
+
+  github-release:
+    needs: [build, smoke]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      VERSION: ${{ needs.build.outputs.version }}
+      PRERELEASE: ${{ needs.build.outputs.prerelease }}
+      GH_TOKEN: ${{ github.token }}
+      GH_REPO: ${{ github.repository }}
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - name: Create the release (or update its files when re-run)
+        run: |
+          if gh release view "$TAG" > /dev/null 2>&1; then
+            gh release upload "$TAG" dist/* --clobber
+          else
+            flags=()
+            if [ "$PRERELEASE" = true ]; then flags+=(--prerelease); fi
+            gh release create "$TAG" dist/* --verify-tag --generate-notes \
+              --title "noodlelab $VERSION" "${flags[@]}"
+          fi
+
+  publish-pypi:
+    needs: [build, github-release]
+    if: needs.build.outputs.prerelease == 'false'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/noodlelab/${{ needs.build.outputs.version }}/
+    permissions:
+      id-token: write # trusted publishing: no API token
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - uses: astral-sh/setup-uv@v6
+      - run: uv publish --trusted-publishing always --check-url https://pypi.org/simple/
+
+  publish-testpypi:
+    needs: [build, github-release]
+    if: needs.build.outputs.prerelease == 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/noodlelab/${{ needs.build.outputs.version }}/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - uses: astral-sh/setup-uv@v6
+      - run: >-
+          uv publish --trusted-publishing always
+          --publish-url https://test.pypi.org/legacy/
+          --check-url https://test.pypi.org/simple/
+
+  # One image per tier, for amd64 and arm64:
+  #   ghcr.io/<owner>/noodlelab:0.3.0        the full tier (also :0.3.0-full)
+  #   ghcr.io/<owner>/noodlelab:0.3.0-maths  a smaller tier
+  # A final release also moves :0.3(-<tier>), :<tier> and :latest (the full tier).
+  docker:
+    needs: [build, github-release]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    strategy:
+      fail-fast: false
+      matrix:
+        tier: [basic, maths, science, engineering, geo, full]
+    env:
+      VERSION: ${{ needs.build.outputs.version }}
+      PRERELEASE: ${{ needs.build.outputs.prerelease }}
+      TIER: ${{ matrix.tier }}
+    steps:
+      - uses: actions/checkout@v4
+      - name: Image tags
+        id: tags
+        run: |
+          image="ghcr.io/${GITHUB_REPOSITORY,,}"
+          minor="$(echo "$VERSION" | cut -d. -f1,2)"
+          tags="$image:$VERSION-$TIER"
+          if [ "$TIER" = full ]; then tags="$tags,$image:$VERSION"; fi
+          if [ "$PRERELEASE" = false ]; then
+            tags="$tags,$image:$minor-$TIER,$image:$TIER"
+            if [ "$TIER" = full ]; then tags="$tags,$image:$minor,$image:latest"; fi
+          fi
+          echo "tags=$tags" >> "$GITHUB_OUTPUT"
+          echo "$tags" | tr , '\n'
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.tags.outputs.tags }}
+          build-args: |
+            NOODLELAB_TIER=${{ matrix.tier }}
+            NOODLELAB_VERSION=${{ needs.build.outputs.version }}
+          labels: |
+            org.opencontainers.image.title=noodlelab (${{ matrix.tier }})
+            org.opencontainers.image.version=${{ needs.build.outputs.version }}
+            org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
+            org.opencontainers.image.revision=${{ github.sha }}
+          cache-from: type=gha,scope=${{ matrix.tier }}
+          cache-to: type=gha,mode=max,scope=${{ matrix.tier }}
+
+  # What was published installs: from the package index with uv, and from GHCR.
+  verify:
+    needs: [build, publish-pypi, publish-testpypi, docker]
+    if: >-
+      always() && needs.docker.result == 'success' &&
+      (needs.publish-pypi.result == 'success' || needs.publish-testpypi.result == 'success')
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: read
+    env:
+      VERSION: ${{ needs.build.outputs.version }}
+      PRERELEASE: ${{ needs.build.outputs.prerelease }}
+    steps:
+      - uses: astral-sh/setup-uv@v6
+      - name: uvx runs the published package
+        run: |
+          index=()
+          if [ "$PRERELEASE" = true ]; then
+            index=(--index https://test.pypi.org/simple/ --index-strategy unsafe-best-match)
+          fi
+          # the index can take a few minutes to list a new release
+          for _ in $(seq 1 20); do
+            if uvx --refresh "${index[@]}" --from "noodlelab[maths]==$VERSION" noodlelab tiers; then
+              exit 0
+            fi
+            sleep 15
+          done
+          exit 1
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - name: The images run
+        run: |
+          image="ghcr.io/${GITHUB_REPOSITORY,,}"
+          docker run --rm "$image:$VERSION-basic" noodlelab --version | grep -F "$VERSION"
+          docker run --rm "$image:$VERSION" noodlelab tiers

noodlelab-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# Frontend
+frontend/node_modules/
+frontend/public/vendor/
+src/noodlelab/static/*
+!src/noodlelab/static/.gitkeep
+
+# Runtime data (workspace state; run outputs are yours to keep or ignore)
+.noodlelab/
+noodlelab-data/
+noodlelab-output/
+.env

noodlelab-0.1.0/AGENTS.md

@@ -0,0 +1,83 @@
+# AGENTS.md
+
+Notes for AI coding agents (Claude Code, Codex CLI, Cursor, Copilot and
+others). There are two cases: **using** noodlelab in someone's project, and
+**working on** this repository.
+
+## Using noodlelab in a project
+
+noodlelab makes calculations verifiable. Every number carries its unit and
+uncertainty, requirements are checked with margins, and every run leaves a
+provenance record. When a user asks you to "use noodlelab", "make this
+verifiable", or to build a noodlelab graph or report:
+
+1. `pip install noodlelab`, or `uv add noodlelab` (the library: `noodlelab.verify`).
+   Add `[app]` for the browser editor, and `[full]` for every node pack.
+2. Run `noodlelab init-agent` in the project. It writes an `AGENTS.md` section,
+   a `CLAUDE.md` import, a skill (`.claude/skills/noodlelab/SKILL.md`) and the
+   MCP server in `.mcp.json`. For Codex, run
+   `codex mcp add noodlelab -- noodlelab mcp`.
+3. Read [`src/noodlelab/agent/guide.md`](src/noodlelab/agent/guide.md) (the MCP
+   `guide` tool returns the same text). It has the rules, the Python API, the
+   graph format and the workflow.
+4. Before saying you are done, run `noodlelab verify <script.py | graph.json> --json`.
+   Exit code 0 means every check passed and every requirement was verified.
+
+Recipes:
+- [docs/agents/quickstart.md](docs/agents/quickstart.md): a verified calculation in 10 lines
+- [docs/agents/adopt-in-existing-project.md](docs/agents/adopt-in-existing-project.md):
+  the steps for "extend my project to use noodlelab"
+- [docs/agents/graphs-and-reports.md](docs/agents/graphs-and-reports.md): building
+  graphs and PDF reports over MCP or as JSON
+- [llms.txt](llms.txt): an index of everything, and
+  [docs/llms-full.txt](docs/llms-full.txt), all the API docs and every node in one file
+
+## Working on this repository
+
+```bash
+uv sync --all-extras            # Python env with every pack and the dev tools
+cd frontend && npm ci && cd ..  # editor dependencies
+make test                       # uv run pytest -q (parallel; -n0 for serial)
+make lint                       # ruff check + ruff format --check + tsc
+make frontend                   # build the editor into src/noodlelab/static
+```
+
+CI (`.github/workflows/ci.yml`) runs lint and tests on Python 3.11–3.13, the
+frontend build, and each installation tier on its own (`scripts/check_tier.py`).
+After changing a docstring, a node or the guide, run
+`uv run python scripts/gen_llms.py` (a test fails when `llms.txt` is stale).
+
+### Map
+
+| Path | What |
+|---|---|
+| `src/noodlelab/verify.py` | `noodlelab.verify`: records, measure/q, requirements, audit, Monte Carlo check |
+| `src/noodlelab/core/` | the engine, independent of the editor: graph model (`graph.py`), `executor.py`, `units.py`, `uncertainty.py` (GUM), `montecarlo.py` (JCGM 101), `requirements.py`, `checks.py`, `provenance.py`, `tracked.py` / `reqlog.py` (run histories), `registry.py`, `typesys.py` |
+| `src/noodlelab/nodes/` | the built-in node packs (entry points in `pyproject.toml`), one per tier |
+| `src/noodlelab/agent/` | agent support: `guide.md`, the MCP server (`mcp.py`, `tools.py`), `init-agent` |
+| `src/noodlelab/server/` | FastAPI app (`app.py`), REST API (`api.py`), WebSocket runs (`ws.py`), workspaces, auth, Slurm, agent terminal |
+| `src/noodlelab/reports/` | Typst PDF reports |
+| `src/noodlelab/examples/` | 24 example graphs (`*.graph.json`) with data: the best reference for graph JSON |
+| `src/noodlelab/cli.py` | `noodlelab serve / run / test / verify / mcp / init-agent / nodes / export ...` |
+| `src/noodlelab/tiers.py` | installation tiers (library, basic = `[app]`, maths, science, engineering, geo, full) |
+| `frontend/src/` | the editor: TypeScript + litegraph, no framework (`main.ts` wires everything) |
+| `tests/` | pytest; `conftest.py` has the `registry`, `packs` and `executor` fixtures and the `graph`/`link`/`value` helpers |
+
+### Conventions
+
+- Docstrings and comments are plain prose saying *why*. Modules open with a
+  docstring that explains the concept (read `core/graph.py` and
+  `core/uncertainty.py` for the style).
+- A node is a type-hinted function with `@node`. Its hints decide the sockets,
+  units (`Quantity["m"]`) and widgets (`Annotated[int, Param(min=1)]`), and its
+  docstring is the help text. A node pack checks its dependencies with
+  `noodlelab.tiers.require()`.
+- Anything that records history or provenance must never fail a run: catch,
+  log, and carry on.
+- The bare library must not import the web server or typst at module level
+  (CI's `library` tier checks this).
+- Line length 100, ruff rules E, F, I, UP, B, SIM. TypeScript is checked with
+  `tsc --noEmit`.
+- Tests describe behaviour in their names
+  (`test_a_run_without_requirements_records_nothing`), and use real graphs
+  through `executor.run(graph(...))` rather than mocks.

noodlelab-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md