Merge pull request #1 from athurlow/claude/qcal-copilot-mvp-OZ9wj

.github/workflows/release.yml

@@ -0,0 +1,199 @@
+name: Release to PyPI
+
+# Tag-triggered release for `qcal-copilot`. Pipeline:
+#
+#   build → publish-testpypi → smoke-test-testpypi → publish-pypi → github-release
+#
+# Uses PyPI Trusted Publishing (OIDC), so no long-lived tokens in secrets.
+# BEFORE this workflow can publish, configure the trusted publisher once on
+# each index:
+#
+#   TestPyPI: https://test.pypi.org/manage/account/publishing/
+#   PyPI:     https://pypi.org/manage/account/publishing/
+#
+# For both, register:
+#   repo owner:    athurlow
+#   repo name:     qcal
+#   workflow:      release.yml
+#   environment:   pypi           (for PyPI)
+#                  testpypi       (for TestPyPI)
+#
+# Matching GitHub environments `pypi` and `testpypi` must exist with
+# `id-token: write` permitted — that's the only way OIDC tokens get minted.
+#
+# Manual dry-run: Actions tab → Run workflow → set `testpypi_only: true`
+# to publish a pre-release to TestPyPI without touching PyPI. The tag push
+# path always publishes to both.
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+  workflow_dispatch:
+    inputs:
+      testpypi_only:
+        description: "Publish to TestPyPI only (skip PyPI + GitHub release)"
+        type: boolean
+        default: true
+
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+jobs:
+  # -------------------------------------------------------------------------
+  # 1. Build sdist + wheel once. Downstream jobs consume the artifact so the
+  #    exact bytes published to TestPyPI are the same ones published to PyPI.
+  # -------------------------------------------------------------------------
+  build:
+    name: Build sdist + wheel
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade pip build
+
+      # Fail the release if pyproject.toml's version doesn't match the tag,
+      # so we never ship a 0.1.0 wheel tagged as v0.2.0 (or vice versa).
+      # Skipped on workflow_dispatch since there's no tag to compare against.
+      - name: Verify pyproject version matches tag
+        if: github.event_name == 'push'
+        run: |
+          tag_version="${GITHUB_REF_NAME#v}"
+          pkg_version=$(python -c "
+          import tomllib, pathlib
+          print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])
+          ")
+          if [ "${tag_version}" != "${pkg_version}" ]; then
+            echo "::error::Tag v${tag_version} does not match pyproject.toml version ${pkg_version}."
+            echo "Bump pyproject.toml or retag before pushing."
+            exit 1
+          fi
+          echo "Version check OK: ${pkg_version}"
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: List built artifacts
+        run: ls -la dist/
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  # -------------------------------------------------------------------------
+  # 2. Publish to TestPyPI first, always.
+  # -------------------------------------------------------------------------
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/project/qcal-copilot/
+    permissions:
+      id-token: write  # required for Trusted Publishing OIDC
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          # TestPyPI sometimes has leftover versions from prior dry runs;
+          # don't fail the release over it.
+          skip-existing: true
+
+  # -------------------------------------------------------------------------
+  # 3. Smoke-test: install from TestPyPI in a clean runner and assert that
+  #    the CLI + Python imports work. If this fails, do NOT publish to PyPI.
+  # -------------------------------------------------------------------------
+  smoke-test-testpypi:
+    name: Smoke-test TestPyPI install
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install from TestPyPI
+        run: |
+          # TestPyPI doesn't mirror transitive deps — fall back to PyPI for those.
+          # Retry a few times because TestPyPI's CDN takes 30-60s to propagate
+          # a fresh upload before the new version becomes resolvable.
+          for attempt in 1 2 3 4 5; do
+            if python -m pip install \
+                --index-url https://test.pypi.org/simple/ \
+                --extra-index-url https://pypi.org/simple/ \
+                qcal-copilot; then
+              exit 0
+            fi
+            echo "Attempt ${attempt} failed, sleeping before retry..."
+            sleep 15
+          done
+          echo "::error::pip install from TestPyPI failed after 5 attempts."
+          exit 1
+
+      - name: Verify CLI + imports
+        run: |
+          qcal version
+          python -c "
+          import qcal
+          from qcal import analyzer, codegen, data, decoder, fit, simulator, config, cli
+          assert qcal.__version__, 'missing __version__'
+          print('smoke test OK, version =', qcal.__version__)
+          "
+
+  # -------------------------------------------------------------------------
+  # 4. Publish to real PyPI. Skipped on workflow_dispatch dry runs.
+  # -------------------------------------------------------------------------
+  publish-pypi:
+    name: Publish to PyPI
+    needs: smoke-test-testpypi
+    if: github.event_name == 'push' || github.event.inputs.testpypi_only != 'true'
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/qcal-copilot/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  # -------------------------------------------------------------------------
+  # 5. Attach the built wheel + sdist to a GitHub Release, with auto-generated
+  #    notes. Tag-push only.
+  # -------------------------------------------------------------------------
+  github-release:
+    name: Create GitHub Release
+    needs: publish-pypi
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

.github/workflows/sync-to-hf-space.yml

@@ -0,0 +1,78 @@
+name: Sync to Hugging Face Space
+
+# Mirrors this repo to https://huggingface.co/spaces/athurlow/qcal so the
+# Space rebuilds whenever you push here. The Space itself is a git repo;
+# this workflow just force-pushes the latest commit to its `main` branch.
+
+on:
+  push:
+    branches:
+      - main
+      - claude/qcal-copilot-mvp-OZ9wj
+  workflow_dispatch:  # allow manual sync from the Actions tab
+
+env:
+  # Opt in to Node 24 now so JS actions (checkout@v4) don't emit the Node 20
+  # deprecation warning. Safe to remove once Node 24 is the runner default.
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo (full history — HF rejects shallow clones)
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      # Fail fast with a human-readable message if HF_TOKEN is missing or
+      # obviously invalid, rather than letting `git push` die with a cryptic
+      # "Authentication required" 40 lines into the log.
+      - name: Preflight — HF_TOKEN sanity check
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          if [ -z "${HF_TOKEN}" ]; then
+            echo "::error::HF_TOKEN secret is not set on this repository."
+            echo "Create a Write-scope token at https://huggingface.co/settings/tokens"
+            echo "and add it as a repo secret named HF_TOKEN (Settings → Secrets → Actions)."
+            exit 1
+          fi
+          # Real HF user tokens start with `hf_` and are >=20 chars. This
+          # catches pasted-in empties/quotes without hitting the API.
+          case "${HF_TOKEN}" in
+            hf_*) : ;;
+            *)
+              echo "::error::HF_TOKEN does not look like a Hugging Face user token (expected prefix 'hf_')."
+              echo "Regenerate at https://huggingface.co/settings/tokens with Write scope."
+              exit 1
+              ;;
+          esac
+          if [ "${#HF_TOKEN}" -lt 20 ]; then
+            echo "::error::HF_TOKEN is suspiciously short (${#HF_TOKEN} chars) — likely truncated."
+            exit 1
+          fi
+          # Verify the token is actually accepted by HF's whoami endpoint
+          # before we try to push. Saves wading through git's auth output.
+          http_code=$(curl -s -o /tmp/hf_whoami.json -w "%{http_code}" \
+            -H "Authorization: Bearer ${HF_TOKEN}" \
+            https://huggingface.co/api/whoami-v2)
+          if [ "${http_code}" != "200" ]; then
+            echo "::error::HF whoami returned ${http_code}. Token is invalid or revoked."
+            echo "Regenerate at https://huggingface.co/settings/tokens with Write scope."
+            exit 1
+          fi
+          echo "HF_TOKEN looks good (whoami returned 200)."
+
+      - name: Push to Hugging Face Space
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+          HF_USER: athurlow
+          HF_SPACE: qcal
+        run: |
+          git config user.name  "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git remote add space "https://${HF_USER}:${HF_TOKEN}@huggingface.co/spaces/${HF_USER}/${HF_SPACE}"
+          # Force-push the current branch onto the Space's main branch.
+          git push --force space "HEAD:main"

.gitignore

@@ -1,6 +1,8 @@
 __pycache__/
 *.py[cod]
 *.egg-info/
+build/
+dist/
 .venv/
 venv/
 .env

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 QCal Copilot contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,32 +1,117 @@
-# QCal Copilot — MVP
-
-AI-assisted quantum calibration. Upload a calibration plot or CSV, get an
-analysis from NVIDIA's Ising Calibration vision-language model, receive a
-ready-to-run CUDA-Q Python script with the suggested tuning, and execute it
-on the local `cudaq` simulator.
+---
+title: QCal Copilot
+emoji: ⚛️
+colorFrom: blue
+colorTo: purple
+sdk: gradio
+sdk_version: 4.44.0
+python_version: "3.12"
+app_file: app.py
+pinned: false
+license: mit
+short_description: AI-assisted quantum calibration + CUDA-Q + Ising decoder
+---
+
+# QCal Copilot
+
+AI-assisted quantum calibration. Point it at a raw `.npy` trace (or image, or
+CSV) and it renders a plot, auto-fits the standard calibration model (Rabi,
+Ramsey, T1, T2-echo), hands both to NVIDIA's Ising Calibration VLM, and emits a
+ready-to-run CUDA-Q script seeded with the recommended tuning.
+
+Ships three ways:
+
+- **`pip install qcal-copilot`** — CLI + Python API (`qcal analyze`, `from qcal.data import from_npy`).
+- **Gradio web app** — `qcal serve` or [the hosted Space](https://huggingface.co/spaces/athurlow/qcal).
+- **Jupyter** — see `examples/` for Rabi, Ramsey-drift, and readout-IQ notebooks.
 
 ```
 ┌─────────┐   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
 │  Upload │──▶│   Analyzer   │──▶│  Code gen    │──▶│  Simulator   │
 │ (img/csv│   │ (Ising VLM)  │   │  (CUDA-Q)    │   │ (cudaq.sample│
-└─────────┘   └──────────────┘   └──────────────┘   └──────────────┘
+└─────────┘   └──────┬───────┘   └──────────────┘   └──────────────┘
+                     │
+                     ▼
+             ┌───────────────────────────────┐
+             │   Decoder  (optional)         │
+             │   Ising 3D CNN → PyMatching   │
+             └───────────────────────────────┘
 ```
 
 ## Layout
 
 ```
 app.py                 # Gradio UI + pipeline wiring
-qcal/
-  data.py              # image/CSV preprocessing
+pyproject.toml         # package metadata + CLI entry point
+src/qcal/
+  data.py              # image/CSV/.npy/.npz preprocessing + plot rendering
+  fit.py               # scipy-backed curve fits (Rabi/Ramsey/T1/T2)
   analyzer.py          # Ising VLM (local HF or NIM)
   codegen.py           # CUDA-Q script generator
   simulator.py         # executes the generated script
+  decoder.py           # Ising 3D CNN pre-decoder + MWPM
+  config.py            # persists NIM API key to ~/.config/qcal/config.toml
+  cli.py               # `qcal ...` Typer commands
+examples/              # Rabi / Ramsey-drift / readout-IQ notebooks
 requirements.txt
 ```
 
 The analyzer and simulator are decoupled, so adding a later-stage 3D CNN
 decoder or swapping in a different model is a one-file change.
 
+## Install (pip)
+
+```bash
+pip install qcal-copilot                   # CLI + NIM backend
+pip install "qcal-copilot[decoder]"        # + PyMatching
+pip install "qcal-copilot[gui]"            # + Gradio (for `qcal serve`)
+pip install "qcal-copilot[ml]"             # + torch + transformers (local 35B VLM)
+pip install "qcal-copilot[all]"            # everything
+```
+
+Store your NIM API key (or set `NVIDIA_API_KEY` in your shell):
+
+```bash
+qcal login           # prompts for the key, saves to ~/.config/qcal/config.toml (0600)
+```
+
+### CLI
+
+```bash
+# Rabi trace stored as a 1-D .npy with a matching time axis
+qcal analyze rabi.npy --experiment rabi --out report.md --script rabi.py
+
+# .npz archive with x, y arrays
+qcal analyze ramsey.npz --experiment ramsey --json out.json
+
+# Regenerate the CUDA-Q script from a saved analysis
+qcal generate out.json --out rabi.py
+
+# Run the Ising 3D CNN decoder on a synthetic syndrome volume
+qcal decode --variant fast --distance 5 --rounds 5 --p 0.005 --shots 128
+
+# Launch the Gradio UI locally (needs [gui])
+qcal serve
+```
+
+### Python
+
+```python
+from qcal.data import from_npy
+from qcal.analyzer import analyze_payload
+from qcal.codegen import generate_script
+
+payload = from_npy("rabi.npy", experiment_type="rabi",
+                   x_path="rabi_time.npy", x_unit="s")
+payload.fit             # FitResult: {amplitude, freq_per_s, tau_s, offset, phase_rad, R^2}
+
+result = analyze_payload(payload, backend="auto")   # "nim" if key present, else local
+print(result.markdown())
+print(generate_script(result.parsed))
+```
+
+Both `payload.fit` and `result` render as rich markdown in Jupyter.
+
 ## Quick start
 
 ### 1. System requirements
@@ -99,20 +184,99 @@ Open <http://localhost:7860>. Upload a calibration plot, click
 **Analyze calibration**, inspect the generated CUDA-Q script, then click
 **Run simulation** to execute it on the `cudaq` simulator.
 
+## Deploy to Hugging Face Spaces
+
+This repo is ready to deploy as a Gradio Space (e.g. `athurlow/qcal`). The
+YAML frontmatter at the top of this README tells Spaces which SDK to use and
+which file to run.
+
+1. Push the repo to the Space:
+
+   ```bash
+   git remote add space https://huggingface.co/spaces/athurlow/qcal
+   git push space claude/qcal-copilot-mvp-OZ9wj:main
+   ```
+2. In the Space **Settings → Variables and secrets**, add:
+   - `NVIDIA_API_KEY` — required; the hosted Space can't download the 35B
+     VLM locally, so the app should call the NIM endpoint.
+3. (Optional) Override model ids via Space secrets if you have custom
+   deployments: `QCAL_NIM_MODEL`, `QCAL_DECODER_FAST_ID`,
+   `QCAL_DECODER_ACCURATE_ID`.
+4. **Hardware:** a free CPU Space runs the decoder's small CNN (~1.8M params)
+   and the NIM-backed analyzer fine. A GPU Space (T4 or better) is only
+   needed if you want to host the calibration VLM locally; `cudaq` requires
+   an NVIDIA GPU Space to run the simulation stage.
+
+The app falls back gracefully when dependencies are missing: no
+`NVIDIA_API_KEY` → analyzer reports the missing key; no `cudaq` → simulator
+button surfaces the install hint; no `pymatching` → decoder shows density
+metrics without MWPM timing.
+
+## Error-correction decoder (optional stage)
+
+After a successful calibration analysis, expand the
+**"Error-correction decoder (Ising 3D CNN)"** panel to run an NVIDIA Ising
+surface-code pre-decoder on a synthetic syndrome volume. The panel lets you:
+
+- Pick the `fast` (~912k params) or `accurate` (~1.79M params) variant.
+- Set code distance (d), syndrome rounds (T), physical error rate (p),
+  and shot count.
+- See before/after metrics: syndrome density, CNN inference time, MWPM
+  decode time on raw vs denoised syndromes (via PyMatching), and a
+  logical-error-rate proxy.
+- View a side-by-side plot of the raw and denoised syndrome slices plus a
+  before/after bar chart.
+
+The `p` slider auto-populates from the calibration analysis (larger drive
+amplitude mismatch → larger `p`). Running the decoder regenerates the
+CUDA-Q script with a header block documenting the decoder variant and
+improvement metrics.
+
+**What's synthetic and what's real:** syndromes are sampled from Bernoulli(p)
+with a few injected correlated chains, the matching graph is a toy 6-nearest-
+neighbor graph (not a stim-generated DEM), and "LER" is a syndrome-weight
+proxy. If the Ising decoder weights aren't reachable, the module falls back
+to a 3D neighbor-support sparsifier so the pipeline still demos end-to-end.
+
+**Swapping in real data:** call
+`qcal.decoder.run_decoder(...)` directly with your own `numpy` volume in place
+of the generated one, or replace `generate_syndromes()` with a stim-backed
+sampler.
+
 ## Environment variables
 
-| Variable            | Purpose                                               |
-| ------------------- | ----------------------------------------------------- |
-| `NVIDIA_API_KEY`    | API key for the NIM endpoint (backend = `nim`)        |
-| `QCAL_MODEL_ID`     | Override local HF model id                            |
-| `QCAL_NIM_MODEL`    | Override NIM model name                               |
-| `QCAL_NIM_ENDPOINT` | Override NIM base URL                                 |
-| `QCAL_HOST`         | Gradio bind host (default `0.0.0.0`)                  |
-| `QCAL_PORT`         | Gradio port (default `7860`)                          |
-| `QCAL_SHARE`        | Set to `1` to enable Gradio public share link         |
+| Variable                    | Purpose                                          |
+| --------------------------- | ------------------------------------------------ |
+| `NVIDIA_API_KEY`            | API key for the NIM endpoint (backend = `nim`)   |
+| `QCAL_MODEL_ID`             | Override local HF calibration VLM id             |
+| `QCAL_NIM_MODEL`            | Override NIM model name                          |
+| `QCAL_NIM_ENDPOINT`         | Override NIM base URL                            |
+| `QCAL_DECODER_FAST_ID`      | Override HF id for the fast decoder variant      |
+| `QCAL_DECODER_ACCURATE_ID`  | Override HF id for the accurate decoder variant  |
+| `QCAL_HOST`                 | Gradio bind host (default `0.0.0.0`)             |
+| `QCAL_PORT`                 | Gradio port (default `7860`)                     |
+| `QCAL_SHARE`                | Set to `1` to enable Gradio public share link    |
+| `QCAL_CONFIG_PATH`          | Override config file path (default `~/.config/qcal/config.toml`) |
+| `NIM_API_KEY`               | Alias for `NVIDIA_API_KEY`                       |
 
 ## Input formats
 
+- **`.npy` / `.npz`** (preferred for real-hardware workflows) — Raw measurement
+  arrays from your control stack. Pass `--experiment` (or `experiment_type=`)
+  so `qcal` knows the expected shape and fit model:
+
+  | `experiment_type`      | Array shape   | Auto-fit model                               |
+  |------------------------|---------------|----------------------------------------------|
+  | `rabi`                 | `(N,)`        | damped sine → `{amplitude, freq, tau, offset, phase}` |
+  | `ramsey`               | `(N,)`        | damped cosine → `{amplitude, detuning, t2star, offset, phase}` |
+  | `t1`, `t2_echo`        | `(N,)`        | exponential decay → `{amplitude, tau, offset}` |
+  | `rabi_chevron`         | `(F, A)`      | heatmap (no fit)                             |
+  | `readout_iq`           | `(N, 2)`      | scatter (no fit)                             |
+  | `iq_trace`, `resonator_spec`, `unknown` | `(N,)` | plot only |
+
+  `.npz` should contain at least a `y` key and optionally an `x` key. Disable
+  fitting for air-gapped installs without `scipy` via `--no-fit` (CLI) or
+  `from_npy(..., fit=False)` (Python).
 - **Images** — `.png`, `.jpg`, `.jpeg`, `.bmp`, `.tiff`, `.webp`. Any
   calibration artifact the VLM understands: Rabi chevrons, T1/T2 decays,
   Ramsey fringes, readout histograms, resonator spectroscopy, oscilloscope
@@ -134,6 +298,28 @@ Module boundaries to keep the MVP clean:
 
 - `qcal.data` — file I/O and normalization only.
 - `qcal.analyzer` — model calls; returns a strict JSON dict.
-- `qcal.codegen` — pure function: analysis dict → script text.
+- `qcal.codegen` — pure function: analysis dict (+ optional decoder info) → script text.
 - `qcal.simulator` — executes script text; never imports `cudaq` itself.
+- `qcal.decoder` — Ising 3D CNN sparsifier + optional PyMatching MWPM.
 - `app.py` — UI glue only; no ML logic.
+
+### Testing the decoder stage
+
+Without launching the UI:
+
+```python
+from qcal.decoder import run_decoder
+
+r = run_decoder(variant="fast", distance=5, rounds=5, error_rate=0.01, n_shots=64)
+print(r.markdown())
+print("density reduction:", round(r.density_reduction * 100, 1), "%")
+```
+
+Through the UI:
+
+1. Upload any calibration plot and click **Analyze calibration**.
+2. Expand **Error-correction decoder (Ising 3D CNN)**.
+3. Pick `fast` or `accurate`, adjust `d` / `T` / `p`, click **Run decoder**.
+4. Inspect the metrics panel (density reduction, MWPM timing, LER proxy
+   improvement) and the side-by-side plot.
+5. The CUDA-Q script auto-refreshes with a decoder header block.

app.py

@@ -1,26 +1,66 @@
 """QCal Copilot — Gradio MVP.
 
 Upload a calibration plot (image) or CSV, get an AI analysis from the
-Ising Calibration VLM, generate a runnable CUDA-Q script, and optionally
-execute it on the local cudaq simulator.
+Ising Calibration VLM, generate a runnable CUDA-Q script, execute it on
+the local cudaq simulator, and optionally run the Ising 3D CNN decoder
+stage on a synthetic surface-code syndrome volume.
 
 Run:
     python app.py
 
 Environment (optional):
-    NVIDIA_API_KEY        API key for build.nvidia.com NIM endpoint
-    QCAL_MODEL_ID         HF model id (default: nvidia/Ising-Calibration-1-35B-A3B)
-    QCAL_NIM_MODEL        NIM model name
-    QCAL_NIM_ENDPOINT     NIM base URL
+    NVIDIA_API_KEY              API key for build.nvidia.com NIM endpoint
+    QCAL_MODEL_ID               HF model id for the calibration VLM
+    QCAL_NIM_MODEL              NIM model name
+    QCAL_NIM_ENDPOINT           NIM base URL
+    QCAL_DECODER_FAST_ID        Override fast decoder HF id
+    QCAL_DECODER_ACCURATE_ID    Override accurate decoder HF id
 """
 
 from __future__ import annotations
 
 import os
+import sys
+from pathlib import Path
+
+# On HF Spaces the build step only mounts requirements.txt, so `pip install -e .`
+# can't reach pyproject.toml. Put src/ on sys.path so `from qcal import ...`
+# resolves against the src-layout package without needing it installed.
+_SRC = Path(__file__).resolve().parent / "src"
+if _SRC.is_dir() and str(_SRC) not in sys.path:
+    sys.path.insert(0, str(_SRC))
+
+# gradio 4.44.0 crashes on every page load when a JSON sub-schema is a bool
+# (JSON Schema draft 2020-12 allows `additionalProperties: True|False`, and
+# pydantic emits it). Fixed in 4.44.1, but HF Spaces pins 4.44.0 in its
+# build bootstrap. Wrap both the schema walker and the type dispatcher so
+# bool schemas degrade to "Any" instead of raising APIInfoParseError.
+# Recursion inside gradio_client.utils resolves these names via module
+# globals, so patching the module attributes intercepts every call site.
+try:
+    from gradio_client import utils as _gc_utils
+
+    _orig_walk = _gc_utils._json_schema_to_python_type
+    _orig_get_type = _gc_utils.get_type
+
+    def _safe_walk(schema, defs=None):
+        if isinstance(schema, bool):
+            return "Any"
+        return _orig_walk(schema, defs)
+
+    def _safe_get_type(schema):
+        if not isinstance(schema, dict):
+            return "Any"
+        return _orig_get_type(schema)
+
+    _gc_utils._json_schema_to_python_type = _safe_walk
+    _gc_utils.get_type = _safe_get_type
+except Exception:  # noqa: BLE001 — best-effort; don't block startup
+    pass
 
 import gradio as gr
 
-from qcal import analyzer, codegen, data, simulator
+from qcal import analyzer, codegen, data, decoder, simulator
 
 
 # ---------------------------------------------------------------------------
@@ -35,12 +75,17 @@ def step_analyze(file_obj, backend_choice: str):
             gr.update(value=""),
             gr.update(value=""),
             None,
+            gr.update(value=decoder.suggest_error_rate(None)),
         )
 
     try:
         payload = data.load_payload(file_obj.name if hasattr(file_obj, "name") else file_obj)
     except Exception as exc:  # noqa: BLE001
-        return gr.update(value=f"**Input error:** {exc}"), "", "", None
+        return (
+            gr.update(value=f"**Input error:** {exc}"),
+            "", "", None,
+            gr.update(value=decoder.suggest_error_rate(None)),
+        )
 
     summary = payload.summary()
     table_md = payload.table_preview_markdown() if payload.kind == "csv" else None
@@ -56,9 +101,10 @@ def step_analyze(file_obj, backend_choice: str):
     analysis_md = header + result.markdown()
 
     script = codegen.generate_script(result.parsed) if result.ok else ""
-    script_md_hint = "" if result.ok else "_(no script generated — fix the analysis error first)_"
+    script_hint = "" if result.ok else "_(no script generated — fix the analysis error first)_"
+    suggested_p = decoder.suggest_error_rate(result.parsed)
 
-    return analysis_md, script, script_md_hint, result.parsed
+    return analysis_md, script, script_hint, result.parsed, gr.update(value=suggested_p)
 
 
 def step_run_simulation(script_text: str):
@@ -68,6 +114,48 @@ def step_run_simulation(script_text: str):
     return simulator.format_result_markdown(result)
 
 
+def step_run_decoder(
+    variant: str,
+    distance: int,
+    rounds: int,
+    error_rate: float,
+    n_shots: int,
+    analysis: dict | None,
+    script_text: str,
+):
+    """Run the Ising 3D CNN decoder and refresh metrics/plots/script."""
+    result = decoder.run_decoder(
+        variant=variant,
+        distance=int(distance),
+        rounds=int(rounds),
+        error_rate=float(error_rate),
+        n_shots=int(n_shots),
+    )
+    metrics_md = result.markdown()
+
+    try:
+        fig = decoder.plot_comparison(result) if result.ok else None
+    except Exception as exc:  # noqa: BLE001
+        fig = None
+        metrics_md += f"\n\n_(plot unavailable: {exc})_"
+
+    # Re-generate the CUDA-Q script with a decoder header block, so the user
+    # can copy a script that documents which decoder ran upstream.
+    new_script = script_text
+    if result.ok and analysis:
+        decoder_info = {
+            "variant": result.variant,
+            "model_id": result.model_id,
+            "distance": result.distance,
+            "rounds": result.rounds,
+            "density_reduction": result.density_reduction,
+            "ler_improvement": result.ler_improvement,
+        }
+        new_script = codegen.generate_script(analysis, decoder_info=decoder_info)
+
+    return metrics_md, fig, new_script
+
+
 # ---------------------------------------------------------------------------
 # UI
 # ---------------------------------------------------------------------------
@@ -88,11 +176,16 @@ def build_ui() -> gr.Blocks:
             """
             <div id="qcal-header">
               <h1>QCal Copilot</h1>
-              <p>AI-assisted quantum calibration · Ising Calibration VLM + CUDA-Q</p>
+              <p>AI-assisted quantum calibration · Ising VLM + 3D CNN decoder + CUDA-Q</p>
             </div>
             """
         )
 
+        # State holds the parsed analysis dict so downstream stages (decoder,
+        # future 3D CNN tile, etc.) can read it without re-calling the VLM.
+        analysis_state = gr.State(value=None)
+
+        # ---- Stage 1: calibration analysis ---------------------------------
         with gr.Row():
             with gr.Column(scale=1):
                 file_in = gr.File(
@@ -129,20 +222,72 @@ def build_ui() -> gr.Blocks:
                     script_hint = gr.Markdown()
                 sim_out = gr.Markdown(label="Simulation result")
 
-        # State holds the parsed analysis dict so we could extend the flow
-        # later (e.g. decoder stage) without re-calling the VLM.
-        analysis_state = gr.State(value=None)
+        # ---- Stage 2: error-correction decoder -----------------------------
+        with gr.Accordion("Error-correction decoder (Ising 3D CNN)", open=False):
+            gr.Markdown(
+                "Sparsify a synthetic surface-code syndrome volume with one of "
+                "the Ising pre-decoders, then hand off to MWPM (PyMatching). "
+                "Error rate defaults are suggested from your calibration analysis."
+            )
+            with gr.Row():
+                with gr.Column(scale=1):
+                    variant_choice = gr.Radio(
+                        label="Decoder variant",
+                        choices=[decoder.VARIANT_FAST, decoder.VARIANT_ACCURATE],
+                        value=decoder.VARIANT_FAST,
+                        info=(
+                            "`fast` ≈ 912k params — lower latency. "
+                            "`accurate` ≈ 1.79M params — better LER."
+                        ),
+                    )
+                    distance_slider = gr.Slider(
+                        3, 11, value=5, step=2,
+                        label="Code distance (d)",
+                    )
+                    rounds_slider = gr.Slider(
+                        1, 17, value=5, step=1,
+                        label="Syndrome rounds (T)",
+                    )
+                    error_rate_slider = gr.Slider(
+                        0.0, 0.05, value=0.005, step=0.001,
+                        label="Physical error rate (p)",
+                    )
+                    shots_slider = gr.Slider(
+                        16, 1024, value=128, step=16,
+                        label="Shots",
+                    )
+                    run_decoder_btn = gr.Button(
+                        "Run decoder", variant="primary"
+                    )
+
+                with gr.Column(scale=2):
+                    decoder_metrics = gr.Markdown(
+                        "_Run the decoder to see density reduction, MWPM timing, "
+                        "and LER-proxy improvement here._"
+                    )
+                    decoder_plot = gr.Plot(label="Raw vs denoised syndromes")
 
         analyze_btn.click(
             fn=step_analyze,
             inputs=[file_in, backend_choice],
-            outputs=[analysis_out, script_out, script_hint, analysis_state],
+            outputs=[
+                analysis_out, script_out, script_hint, analysis_state,
+                error_rate_slider,
+            ],
         )
         run_btn.click(
             fn=step_run_simulation,
             inputs=[script_out],
             outputs=[sim_out],
         )
+        run_decoder_btn.click(
+            fn=step_run_decoder,
+            inputs=[
+                variant_choice, distance_slider, rounds_slider,
+                error_rate_slider, shots_slider, analysis_state, script_out,
+            ],
+            outputs=[decoder_metrics, decoder_plot, script_out],
+        )
 
     return demo
 
@@ -153,6 +298,11 @@ def main() -> None:
         server_name=os.getenv("QCAL_HOST", "0.0.0.0"),
         server_port=int(os.getenv("QCAL_PORT", "7860")),
         share=os.getenv("QCAL_SHARE", "").lower() in {"1", "true", "yes"},
+        # Gradio 4.44.0's client-side schema serializer crashes on
+        # `additionalProperties: False` ("argument of type 'bool' is not
+        # iterable"); fixed in 4.44.1, but HF Spaces pins 4.44.0. Disabling
+        # the OpenAPI endpoint avoids the crash — the UI is unaffected.
+        show_api=False,
     )
 
 

examples/01_rabi.ipynb

@@ -0,0 +1,89 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Rabi calibration with QCal Copilot\n",
+    "\n",
+    "Load a raw `.npy` Rabi trace, auto-fit a damped sine, hand the plot + fit numbers to\n",
+    "the Ising Calibration VLM, and emit a CUDA-Q script seeded with the recommended\n",
+    "pulse amplitude.\n",
+    "\n",
+    "Inputs expected: a 1-D numpy array of readout populations vs drive amplitude (or time)\n",
+    "and an optional matching `x` array. Works offline — the local VLM is optional."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "\n",
+    "# Synthesize a Rabi sweep (replace with `np.load('your_trace.npy')`).\n",
+    "t = np.linspace(0, 500e-9, 201)              # seconds\n",
+    "y = 0.5 * np.exp(-t/300e-9) * np.sin(2*np.pi*10e6*t) + 0.5\n",
+    "np.save('rabi_trace.npy', y)\n",
+    "np.save('rabi_time.npy', t)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from qcal.data import from_npy\n",
+    "\n",
+    "payload = from_npy(\n",
+    "    'rabi_trace.npy',\n",
+    "    experiment_type='rabi',\n",
+    "    x_path='rabi_time.npy',\n",
+    "    x_unit='s',\n",
+    ")\n",
+    "payload.fit  # FitResult — rich-displays in Jupyter as a table"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "payload.image  # the rendered plot the VLM will see"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from qcal.analyzer import analyze_payload\n",
+    "\n",
+    "# backend='auto' uses NIM when NVIDIA_API_KEY is set, else the local HF weights.\n",
+    "result = analyze_payload(payload, backend='auto')\n",
+    "result  # _repr_markdown_ — shows experiment, issues, recommended params"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from qcal.codegen import generate_script\n",
+    "\n",
+    "print(generate_script(result.parsed))"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"},
+  "language_info": {"name": "python", "version": "3.11"}
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

examples/02_ramsey_drift.ipynb

@@ -0,0 +1,106 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Ramsey detuning drift over a shift\n",
+    "\n",
+    "Track how the detuning (qubit frequency - drive frequency) drifts across a series\n",
+    "of Ramsey experiments run over several hours — the signature of a TLS hop, a thermal\n",
+    "excursion, or flux-line crosstalk that the VLM is good at flagging.\n",
+    "\n",
+    "Typical workflow: your control stack dumps one `.npz` per Ramsey run into a\n",
+    "watched directory; this notebook walks that directory, auto-fits each trace, and\n",
+    "plots the extracted detuning vs wall-clock time."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "import matplotlib.pyplot as plt\n",
+    "\n",
+    "rng = np.random.default_rng(1)\n",
+    "tau = np.linspace(0, 10e-6, 201)                 # 10 µs delay sweep\n",
+    "wall_times = np.arange(8) * 30 * 60               # every 30 min, 4 hours total\n",
+    "\n",
+    "# Simulate detuning drifting from 120 kHz → 180 kHz with a TLS-like jump halfway.\n",
+    "detunings = np.array([120e3, 125e3, 132e3, 140e3, 170e3, 172e3, 175e3, 180e3])\n",
+    "\n",
+    "for i, det in enumerate(detunings):\n",
+    "    phase = rng.uniform(0, 2*np.pi)\n",
+    "    y = 0.5 * np.exp(-tau/4e-6) * np.cos(2*np.pi*det*tau + phase) + 0.5\n",
+    "    y += rng.normal(0, 0.01, tau.shape)          # readout noise\n",
+    "    np.savez(f'ramsey_{i:02d}.npz', x=tau, y=y, wall_time=wall_times[i])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pathlib import Path\n",
+    "from qcal.data import from_npz\n",
+    "\n",
+    "records = []\n",
+    "for path in sorted(Path('.').glob('ramsey_*.npz')):\n",
+    "    p = from_npz(path, experiment_type='ramsey', x_unit='s')\n",
+    "    if p.fit and p.fit.ok:\n",
+    "        det = next(v for k, v in p.fit.params.items() if k.startswith('detuning_per_'))\n",
+    "        t2s = next(v for k, v in p.fit.params.items() if k.startswith('t2star_'))\n",
+    "        records.append({'file': path.name, 'detuning_hz': det, 't2star_s': t2s,\n",
+    "                        'fit_quality': p.fit.fit_quality})\n",
+    "\n",
+    "import pandas as pd\n",
+    "df = pd.DataFrame(records)\n",
+    "df"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "fig, ax = plt.subplots(figsize=(6.5, 3.8))\n",
+    "ax.plot(wall_times/3600, df['detuning_hz']/1e3, marker='o')\n",
+    "ax.set_xlabel('Wall time (hours)')\n",
+    "ax.set_ylabel('Fitted detuning (kHz)')\n",
+    "ax.set_title('Qubit detuning drift')\n",
+    "ax.grid(True, alpha=0.3)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Hand the **most recent** Ramsey trace to the VLM. It sees both the plot and the\n",
+    "fitted numbers in the prompt, so `notes` / `drift_prediction` usually flag the\n",
+    "step change in detuning."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from qcal.analyzer import analyze_payload\n",
+    "\n",
+    "latest = from_npz('ramsey_07.npz', experiment_type='ramsey', x_unit='s')\n",
+    "analyze_payload(latest, backend='auto')"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"},
+  "language_info": {"name": "python", "version": "3.11"}
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

examples/03_readout_iq.ipynb

@@ -0,0 +1,87 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Readout IQ blob classification\n",
+    "\n",
+    "Feed a dense cloud of single-shot IQ values to the VLM. The model recognizes\n",
+    "under-separated blobs, leakage to `|2⟩`, and skewed populations — all things\n",
+    "that degrade readout fidelity. We also sketch a cheap linear threshold for\n",
+    "reference."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import numpy as np\n",
+    "\n",
+    "rng = np.random.default_rng(7)\n",
+    "n = 4000\n",
+    "ground = rng.normal(loc=(-0.9, 0.1), scale=(0.35, 0.35), size=(n//2, 2))\n",
+    "excited = rng.normal(loc=(+0.8, 0.4), scale=(0.40, 0.40), size=(n//2, 2))\n",
+    "iq = np.vstack([ground, excited])\n",
+    "np.save('readout_iq.npy', iq)\n",
+    "iq.shape"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from qcal.data import from_npy\n",
+    "\n",
+    "payload = from_npy('readout_iq.npy', experiment_type='readout_iq')\n",
+    "payload.image"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from qcal.analyzer import analyze_payload\n",
+    "\n",
+    "result = analyze_payload(payload, backend='auto')\n",
+    "result"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Once the VLM returns a `recommended_parameters.readout_threshold`, wire it into\n",
+    "your control stack's classifier. Below: a crude linear threshold along the I-axis\n",
+    "for reference."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "\n",
+    "thresh = result.parsed.get('recommended_parameters', {}).get('readout_threshold', 0.0)\n",
+    "fig, ax = plt.subplots(figsize=(5, 5))\n",
+    "ax.scatter(iq[:, 0], iq[:, 1], s=3, alpha=0.4)\n",
+    "ax.axvline(thresh, color='r', linewidth=1.0, label=f'threshold = {thresh}')\n",
+    "ax.set_xlabel('I'); ax.set_ylabel('Q'); ax.legend(); ax.grid(alpha=0.3)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {"display_name": "Python 3", "language": "python", "name": "python3"},
+  "language_info": {"name": "python", "version": "3.11"}
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "qcal-copilot"
+version = "0.1.0"
+description = "AI-assisted quantum calibration: Ising VLM analysis, surface-code decoder, and CUDA-Q codegen for calibration engineers."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "QCal Copilot contributors" }]
+keywords = ["quantum", "calibration", "cudaq", "ising", "nvidia", "surface-code"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Physics",
+]
+
+dependencies = [
+    "numpy>=1.26",
+    "pandas>=2.2",
+    "matplotlib>=3.8",
+    "pillow>=10.0",
+    "requests>=2.32",
+    "scipy>=1.11",              # curve_fit for rabi/ramsey/t1/t2 auto-fitting
+    "typer>=0.12",              # CLI
+    "platformdirs>=4.0",        # ~/.config/qcal lookup
+    "tomli>=2.0; python_version<'3.11'",
+]
+
+[project.optional-dependencies]
+# Vision-language model path — needed for local inference of the Ising VLM.
+# Users who only want NIM can skip this and save ~2 GB of installs.
+ml = [
+    "torch>=2.3",
+    "torchvision>=0.18",
+    "torchaudio>=2.3",
+    "transformers>=4.45",
+    "accelerate>=0.33",
+]
+
+# Surface-code decoder MWPM stage.
+decoder = [
+    "pymatching>=2.2",
+]
+
+# Gradio web UI (app.py). `qcal serve` needs this.
+gui = [
+    "gradio>=4.44",
+]
+
+# Integrations with common quantum frameworks. Phase 2 territory, but we
+# register the extra now so the import path is stable.
+integrations = []
+
+# Everything.
+all = [
+    "qcal-copilot[ml,decoder,gui,integrations]",
+]
+
+[project.scripts]
+qcal = "qcal.cli:app"
+
+[project.urls]
+Homepage = "https://github.com/athurlow/qcal"
+Issues = "https://github.com/athurlow/qcal/issues"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

qcal/data.py

@@ -1,102 +0,0 @@
-"""Input preprocessing for QCal Copilot.
-
-Normalizes user uploads (image file or CSV) into a structured payload the
-analyzer module can send to the vision-language model.
-"""
-
-from __future__ import annotations
-
-import io
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Optional
-
-import pandas as pd
-from PIL import Image
-
-
-SUPPORTED_IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".bmp", ".tiff", ".webp"}
-SUPPORTED_TABLE_EXTS = {".csv", ".tsv"}
-
-
-@dataclass
-class CalibrationPayload:
-    """Container holding normalized calibration data for downstream analysis."""
-
-    image: Optional[Image.Image] = None
-    table: Optional[pd.DataFrame] = None
-    source_name: str = ""
-    kind: str = "unknown"  # "image" | "csv" | "unknown"
-
-    def summary(self) -> str:
-        if self.kind == "image" and self.image is not None:
-            w, h = self.image.size
-            return f"Image `{self.source_name}` ({w}x{h}, mode={self.image.mode})"
-        if self.kind == "csv" and self.table is not None:
-            rows, cols = self.table.shape
-            col_list = ", ".join(map(str, self.table.columns[:8]))
-            more = " …" if self.table.shape[1] > 8 else ""
-            return (
-                f"Table `{self.source_name}` ({rows} rows × {cols} cols). "
-                f"Columns: {col_list}{more}"
-            )
-        return "No data provided."
-
-    def table_preview_markdown(self, max_rows: int = 10) -> str:
-        if self.table is None:
-            return ""
-        return self.table.head(max_rows).to_markdown(index=False)
-
-
-def _render_table_as_image(df: pd.DataFrame) -> Image.Image:
-    """Render a small preview image of a table so the VLM can still see it.
-
-    We only render a capped view — enough for the model to reason about shape
-    and rough values without blowing up token budgets.
-    """
-    import matplotlib.pyplot as plt
-
-    preview = df.head(25)
-    fig, ax = plt.subplots(
-        figsize=(min(2 + 1.1 * len(preview.columns), 14), min(1 + 0.3 * len(preview), 10))
-    )
-    ax.axis("off")
-    tbl = ax.table(
-        cellText=preview.round(4).astype(str).values,
-        colLabels=[str(c) for c in preview.columns],
-        loc="center",
-        cellLoc="center",
-    )
-    tbl.auto_set_font_size(False)
-    tbl.set_fontsize(8)
-    tbl.scale(1, 1.2)
-    buf = io.BytesIO()
-    fig.savefig(buf, format="png", bbox_inches="tight", dpi=120)
-    plt.close(fig)
-    buf.seek(0)
-    return Image.open(buf).convert("RGB")
-
-
-def load_payload(file_path: str | Path) -> CalibrationPayload:
-    """Load an uploaded file into a CalibrationPayload."""
-    if file_path is None:
-        return CalibrationPayload()
-
-    path = Path(file_path)
-    ext = path.suffix.lower()
-    name = path.name
-
-    if ext in SUPPORTED_IMAGE_EXTS:
-        img = Image.open(path).convert("RGB")
-        return CalibrationPayload(image=img, source_name=name, kind="image")
-
-    if ext in SUPPORTED_TABLE_EXTS:
-        sep = "," if ext == ".csv" else "\t"
-        df = pd.read_csv(path, sep=sep)
-        img = _render_table_as_image(df)
-        return CalibrationPayload(image=img, table=df, source_name=name, kind="csv")
-
-    raise ValueError(
-        f"Unsupported file type '{ext}'. Accepted: "
-        f"{sorted(SUPPORTED_IMAGE_EXTS | SUPPORTED_TABLE_EXTS)}"
-    )

requirements.txt

@@ -1,14 +1,49 @@
-gradio>=4.44.0
-transformers>=4.45.0
-torch>=2.3.0
-torchvision>=0.18.0
-torchaudio>=2.3.0
-accelerate>=0.33.0
-pillow>=10.0.0
-numpy>=1.26.0
-pandas>=2.2.0
-matplotlib>=3.8.0
-requests>=2.32.0
-python-dotenv>=1.0.1
-# CUDA-Q is installed separately (see README). Pin here if wheels are available:
-# cudaq>=0.8.0
+# HF Space / quick-start requirements.
+#
+# We DON'T use `-e .[...]` here because HF Spaces only mounts requirements.txt
+# during the pip-install build step — pyproject.toml isn't available yet — and
+# the editable install fails with "file:///app does not appear to be a Python
+# project". Instead we list the deps directly; `app.py` puts `src/` on sys.path
+# at import time so `from qcal import ...` still resolves.
+#
+# For a proper pip install (CLI + Python API), use:
+#   pip install qcal-copilot                   # core + NIM
+#   pip install "qcal-copilot[decoder]"        # + PyMatching
+#   pip install "qcal-copilot[gui]"            # + Gradio
+#   pip install "qcal-copilot[ml]"             # + torch + transformers
+#   pip install "qcal-copilot[all]"            # everything
+
+# Core (kept in sync with pyproject.toml [dependencies])
+numpy>=1.26
+pandas>=2.2
+matplotlib>=3.8
+pillow>=10.0
+requests>=2.32
+scipy>=1.11
+typer>=0.12
+platformdirs>=4.0
+tabulate>=0.9          # pandas.DataFrame.to_markdown
+
+# [decoder]
+pymatching>=2.2
+
+# [gui] — HF Space's bootstrap pins gradio==4.44.0, so don't override it here.
+# Python 3.13 removed the stdlib `audioop` module (PEP 594), which pydub
+# (pulled in by gradio) still imports at load time. Install the backport
+# on 3.13+ so the app starts. Harmless on 3.10–3.12.
+audioop-lts>=0.2.1; python_version >= "3.13"
+
+# Gradio 4.44's oauth module imports `HfFolder`, which was removed in
+# huggingface-hub 0.30. Pin below that until we can upgrade Gradio.
+huggingface-hub>=0.23,<0.30
+
+# Starlette 0.40 made `request` the first positional arg of
+# `TemplateResponse`, but gradio 4.44.0 still calls it as
+# `TemplateResponse(name, context, ...)`. With a newer starlette the
+# context dict lands in the `name` slot and Jinja2 crashes with
+# "unhashable type: 'dict'" the moment the UI is requested. Pin to the
+# pre-break line; fastapi capped to match.
+starlette<0.40
+fastapi<0.113
+
+# CUDA-Q is installed separately on the Space (see README).

{qcal → src/qcal}/analyzer.py

@@ -20,6 +20,9 @@ from typing import Any, Optional
 
 from PIL import Image
 
+from .data import CalibrationPayload
+from .fit import FitResult
+
 
 DEFAULT_MODEL_ID = os.getenv("QCAL_MODEL_ID", "nvidia/Ising-Calibration-1-35B-A3B")
 NIM_ENDPOINT = os.getenv(
@@ -65,6 +68,9 @@ class AnalysisResult:
     parsed: dict = field(default_factory=dict)
     backend: str = "unknown"
     error: Optional[str] = None
+    fit_params: dict = field(default_factory=dict)  # auto-fit params, if any
+    fit: Optional[FitResult] = None                  # full FitResult for tooling
+    source: str = ""
 
     @property
     def ok(self) -> bool:
@@ -92,6 +98,12 @@ class AnalysisResult:
         for k, v in (p.get("recommended_parameters") or {}).items():
             lines.append(f"- `{k}` = {v}")
         lines.append("")
+        if self.fit is not None and self.fit.ok:
+            lines.append("**Auto-fit (numerical):**")
+            for k, v in self.fit.params.items():
+                lines.append(f"- `{k}` = {self.fit._fmt(v)}")
+            lines.append(f"- R² = {self.fit.fit_quality:.4f}")
+            lines.append("")
         lines.append(f"**Drift prediction:** {p.get('drift_prediction', 'n/a')}")
         lines.append("")
         lines.append(f"**Notes:** {p.get('notes', '')}")
@@ -99,6 +111,9 @@ class AnalysisResult:
         lines.append(f"_Backend: {self.backend}_")
         return "\n".join(lines)
 
+    def _repr_markdown_(self) -> str:  # Jupyter renders this directly
+        return self.markdown()
+
 
 # ---------------------------------------------------------------------------
 # Backend: NVIDIA NIM (HTTP)
@@ -242,28 +257,101 @@ def _safe_json(text: str) -> dict[str, Any]:
     return {}
 
 
+def _resolve_backend(choice: str) -> str:
+    if choice == "auto":
+        return "nim" if _resolve_api_key() else "local"
+    return choice
+
+
+def _resolve_api_key() -> Optional[str]:
+    """Look up the NIM API key. Env var wins; config file is a fallback.
+
+    Kept as a thin indirection so :mod:`qcal.config` can install itself later
+    without touching callers.
+    """
+    env = os.getenv("NVIDIA_API_KEY") or os.getenv("NIM_API_KEY")
+    if env:
+        return env
+    try:
+        from .config import get_api_key  # local import to avoid cycle at import-time
+
+        return get_api_key()
+    except Exception:  # noqa: BLE001 — config is optional, never block analysis on it
+        return None
+
+
 def analyze(
     image: Image.Image,
     source: str = "uploaded file",
     table_preview: Optional[str] = None,
     backend: str = "auto",
+    fit: Optional[FitResult] = None,
+    extra_context: Optional[str] = None,
 ) -> AnalysisResult:
     """Run the Ising Calibration VLM on a calibration image.
 
-    backend:
-      "auto"   — NIM if NVIDIA_API_KEY is set, else local HF
-      "nim"    — force NIM
-      "local"  — force local HF
+    Parameters
+    ----------
+    image
+        PIL image of the calibration artifact.
+    source
+        Short label for the input — shown in logs and the VLM prompt.
+    table_preview
+        Optional markdown table to append to the prompt (used for CSV input).
+    backend
+        ``"auto"`` — NIM if an API key is available, else local HF.
+        ``"nim"``  — force NIM. ``"local"`` — force local HF weights.
+    fit
+        Optional :class:`~qcal.fit.FitResult`; its summary is appended to the
+        prompt and stored on the returned :class:`AnalysisResult`.
+    extra_context
+        Any additional text to weave into the prompt (stats, metadata, …).
     """
     if image is None:
         return AnalysisResult(raw_text="", backend=backend, error="No image provided.")
 
-    extra = f"\n\nAccompanying table preview (markdown):\n{table_preview}" if table_preview else ""
-
-    choice = backend
-    if choice == "auto":
-        choice = "nim" if os.getenv("NVIDIA_API_KEY") or os.getenv("NIM_API_KEY") else "local"
+    bits: list[str] = []
+    if table_preview:
+        bits.append(f"Accompanying table preview (markdown):\n{table_preview}")
+    if fit is not None and fit.ok:
+        bits.append(fit.summary_text())
+    if extra_context:
+        bits.append(extra_context)
+    extra = ("\n\n" + "\n\n".join(bits)) if bits else ""
 
+    choice = _resolve_backend(backend)
     if choice == "nim":
-        return _analyze_via_nim(image, extra, source)
-    return _analyze_via_local(image, extra, source)
+        result = _analyze_via_nim(image, extra, source)
+    else:
+        result = _analyze_via_local(image, extra, source)
+
+    result.source = source
+    if fit is not None:
+        result.fit = fit
+        if fit.ok:
+            result.fit_params = dict(fit.params)
+    return result
+
+
+def analyze_payload(
+    payload: CalibrationPayload,
+    backend: str = "auto",
+) -> AnalysisResult:
+    """Convenience wrapper: analyze a :class:`CalibrationPayload` directly.
+
+    Pulls the image, fit, and numeric/metadata context from the payload and
+    hands them to :func:`analyze`. This is the entrypoint the CLI and the
+    notebook examples use.
+    """
+    if payload is None or payload.image is None:
+        return AnalysisResult(
+            raw_text="", backend=backend, error="No image in payload."
+        )
+    return analyze(
+        image=payload.image,
+        source=payload.source_name or "uploaded file",
+        table_preview=payload.table_preview_markdown() if payload.table is not None else None,
+        backend=backend,
+        fit=payload.fit,
+        extra_context=payload.prompt_context(),
+    )

src/qcal/cli.py

@@ -0,0 +1,282 @@
+"""Command-line interface for QCal Copilot.
+
+Installed as the ``qcal`` console script via :mod:`pyproject.toml`.
+
+Commands
+--------
+* ``qcal analyze FILE``      — run the Ising VLM on a calibration artifact
+* ``qcal decode``            — run the Ising 3D CNN decoder on synthetic syndromes
+* ``qcal generate FILE``     — write a CUDA-Q script from a saved analysis JSON
+* ``qcal serve``             — launch the Gradio UI (needs ``qcal[gui]``)
+* ``qcal login``             — store an NVIDIA NIM API key in the user config
+* ``qcal logout``            — clear the stored API key
+* ``qcal config``            — print resolved config
+* ``qcal version``           — print installed version
+
+Design notes
+------------
+All commands honor ``--json`` for machine-readable output so labs can wire
+``qcal`` into CI or drift-monitoring cron jobs. Exit codes: 0 on success,
+1 on analyzer/decoder error, 2 on user error, 3 on missing optional dep.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from . import __version__, config
+from .data import load_payload
+
+
+app = typer.Typer(
+    add_completion=False,
+    no_args_is_help=True,
+    help="AI-assisted quantum calibration (Ising VLM + 3D CNN decoder + CUDA-Q).",
+    context_settings={"help_option_names": ["-h", "--help"]},
+)
+
+
+# ---------------------------------------------------------------------------
+# analyze
+# ---------------------------------------------------------------------------
+
+@app.command()
+def analyze(
+    file: Path = typer.Argument(..., exists=True, readable=True, help="Input file (.npy, .npz, .csv, .png, .jpg, …)."),
+    experiment: str = typer.Option(
+        "unknown",
+        "--experiment", "-e",
+        help="Experiment type for .npy inputs: rabi|ramsey|t1|t2_echo|readout_iq|rabi_chevron|iq_trace|resonator_spec|unknown.",
+    ),
+    backend: str = typer.Option("auto", "--backend", "-b", help="auto | nim | local"),
+    no_fit: bool = typer.Option(False, "--no-fit", help="Skip scipy curve-fitting for .npy inputs."),
+    out: Optional[Path] = typer.Option(None, "--out", "-o", help="Write the markdown report to this path."),
+    json_out: Optional[Path] = typer.Option(None, "--json", help="Write the raw analyzer JSON to this path."),
+    script_out: Optional[Path] = typer.Option(None, "--script", help="Write the generated CUDA-Q script to this path."),
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="Suppress stdout; only write files + exit code."),
+) -> None:
+    """Analyze a calibration artifact with the Ising VLM."""
+    from . import analyzer, codegen  # local imports so `qcal --help` stays fast
+
+    try:
+        payload = load_payload(file, experiment_type=experiment, fit=not no_fit)
+    except Exception as exc:  # noqa: BLE001
+        typer.secho(f"Failed to load {file}: {exc}", err=True, fg=typer.colors.RED)
+        raise typer.Exit(code=2)
+
+    result = analyzer.analyze_payload(payload, backend=backend)
+
+    if not result.ok:
+        typer.secho(
+            f"Analyzer error ({result.backend}): {result.error or 'empty response'}",
+            err=True, fg=typer.colors.RED,
+        )
+        if result.raw_text and not quiet:
+            typer.echo(result.raw_text)
+        raise typer.Exit(code=1)
+
+    md = result.markdown()
+    if out:
+        out.write_text(md, encoding="utf-8")
+    if json_out:
+        json_out.write_text(
+            json.dumps(
+                {
+                    "analysis": result.parsed,
+                    "fit": result.fit_params,
+                    "backend": result.backend,
+                    "source": result.source,
+                    "qcal_version": __version__,
+                },
+                indent=2,
+            ),
+            encoding="utf-8",
+        )
+    if script_out:
+        script_text = codegen.generate_script(result.parsed)
+        script_out.write_text(script_text, encoding="utf-8")
+
+    if not quiet:
+        typer.echo(md)
+
+
+# ---------------------------------------------------------------------------
+# decode
+# ---------------------------------------------------------------------------
+
+@app.command()
+def decode(
+    variant: str = typer.Option("fast", "--variant", "-v", help="fast | accurate"),
+    distance: int = typer.Option(5, "--distance", "-d", min=3, max=15),
+    rounds: int = typer.Option(5, "--rounds", "-r", min=1, max=25),
+    error_rate: float = typer.Option(0.005, "--p", help="Physical error rate."),
+    shots: int = typer.Option(128, "--shots", "-n", min=1),
+    seed: int = typer.Option(42, "--seed"),
+    json_out: Optional[Path] = typer.Option(None, "--json"),
+    quiet: bool = typer.Option(False, "--quiet", "-q"),
+) -> None:
+    """Run the Ising 3D CNN pre-decoder on a synthetic syndrome volume."""
+    from . import decoder
+
+    result = decoder.run_decoder(
+        variant=variant,
+        distance=distance,
+        rounds=rounds,
+        error_rate=error_rate,
+        n_shots=shots,
+        seed=seed,
+    )
+    if not result.ok:
+        typer.secho(f"Decoder error: {result.error}", err=True, fg=typer.colors.RED)
+        raise typer.Exit(code=1)
+
+    if json_out:
+        payload = {
+            "variant": result.variant,
+            "model_id": result.model_id,
+            "distance": result.distance,
+            "rounds": result.rounds,
+            "error_rate": result.error_rate,
+            "n_shots": result.n_shots,
+            "density_before": result.density_before,
+            "density_after": result.density_after,
+            "density_reduction": result.density_reduction,
+            "inference_ms": result.inference_ms,
+            "mwpm_ms_before": result.mwpm_ms_before,
+            "mwpm_ms_after": result.mwpm_ms_after,
+            "ler_proxy_before": result.ler_proxy_before,
+            "ler_proxy_after": result.ler_proxy_after,
+            "ler_improvement": result.ler_improvement,
+            "backend_note": result.backend_note,
+        }
+        json_out.write_text(json.dumps(payload, indent=2), encoding="utf-8")
+    if not quiet:
+        typer.echo(result.markdown())
+
+
+# ---------------------------------------------------------------------------
+# generate
+# ---------------------------------------------------------------------------
+
+@app.command()
+def generate(
+    analysis_json: Path = typer.Argument(..., exists=True, readable=True, help="Analyzer JSON produced by `qcal analyze --json`."),
+    out: Optional[Path] = typer.Option(None, "--out", "-o"),
+) -> None:
+    """Generate a CUDA-Q script from a saved analyzer JSON."""
+    from . import codegen
+
+    try:
+        blob = json.loads(analysis_json.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        typer.secho(f"Invalid JSON in {analysis_json}: {exc}", err=True, fg=typer.colors.RED)
+        raise typer.Exit(code=2)
+
+    analysis = blob.get("analysis") if isinstance(blob, dict) and "analysis" in blob else blob
+    script = codegen.generate_script(analysis)
+    if out:
+        out.write_text(script, encoding="utf-8")
+    else:
+        typer.echo(script)
+
+
+# ---------------------------------------------------------------------------
+# serve
+# ---------------------------------------------------------------------------
+
+@app.command()
+def serve(
+    host: str = typer.Option("0.0.0.0", envvar="QCAL_HOST"),
+    port: int = typer.Option(7860, envvar="QCAL_PORT"),
+    share: bool = typer.Option(False, "--share", envvar="QCAL_SHARE"),
+) -> None:
+    """Launch the Gradio UI locally (requires ``qcal[gui]``)."""
+    try:
+        import gradio  # noqa: F401
+    except ImportError:
+        typer.secho(
+            "Gradio isn't installed. Run: pip install 'qcal-copilot[gui]'",
+            err=True, fg=typer.colors.RED,
+        )
+        raise typer.Exit(code=3)
+
+    # Import the app defined at repo root; when running from an installed
+    # wheel we fall back to a minimal in-package launcher.
+    try:
+        sys.path.insert(0, str(Path.cwd()))
+        import app as gradio_app  # type: ignore[import-not-found]
+
+        demo = gradio_app.build_ui()
+    except Exception:  # noqa: BLE001
+        from . import app_inproc
+
+        demo = app_inproc.build_ui()
+
+    demo.queue(max_size=8).launch(server_name=host, server_port=port, share=share)
+
+
+# ---------------------------------------------------------------------------
+# login / logout / config
+# ---------------------------------------------------------------------------
+
+@app.command()
+def login(
+    api_key: Optional[str] = typer.Option(
+        None, "--api-key",
+        help="NIM API key. If omitted, you'll be prompted (hidden input).",
+    ),
+) -> None:
+    """Store an NVIDIA NIM API key under ``~/.config/qcal/config.toml``."""
+    key = api_key or typer.prompt("NVIDIA NIM API key", hide_input=True)
+    if not key.strip():
+        typer.secho("Empty key — nothing saved.", err=True, fg=typer.colors.RED)
+        raise typer.Exit(code=2)
+    path = config.set_api_key(key.strip())
+    typer.secho(f"Saved API key to {path} (mode 0600).", fg=typer.colors.GREEN)
+
+
+@app.command()
+def logout() -> None:
+    """Remove the stored NIM API key."""
+    path = config.clear_api_key()
+    if path:
+        typer.echo(f"Cleared API key from {path}.")
+    else:
+        typer.echo("No stored API key to clear.")
+
+
+@app.command(name="config")
+def config_cmd(show_key: bool = typer.Option(False, "--show-key", help="Print the stored API key in full.")) -> None:
+    """Print the resolved config (key masked unless ``--show-key``)."""
+    data = config.load()
+    key = config.get_api_key()
+    if key and not show_key:
+        masked = key[:6] + "…" + key[-4:] if len(key) > 12 else "***"
+        data.setdefault("nvidia", {})["api_key"] = masked
+    elif key:
+        data.setdefault("nvidia", {})["api_key"] = key
+    typer.echo(json.dumps(data, indent=2))
+    typer.echo(f"\nconfig path: {config.config_path()}")
+
+
+# ---------------------------------------------------------------------------
+# version
+# ---------------------------------------------------------------------------
+
+@app.command()
+def version() -> None:
+    """Print the installed qcal-copilot version."""
+    typer.echo(__version__)
+
+
+def main() -> None:  # entry point target for scripts
+    app()
+
+
+if __name__ == "__main__":
+    main()

{qcal → src/qcal}/codegen.py

@@ -17,6 +17,7 @@ Auto-generated CUDA-Q calibration script from QCal Copilot.
 Experiment: {experiment}
 Qubit: {qubit_id}
 Notes: {notes}
+{decoder_header}
 """
 
 import cudaq
@@ -89,8 +90,31 @@ def _params_repr(params: dict[str, Any]) -> str:
     return dumped
 
 
-def generate_script(analysis: dict[str, Any]) -> str:
-    """Build the CUDA-Q script text from analyzer output."""
+def _decoder_header(decoder_info: dict[str, Any] | None) -> str:
+    """Format a header block summarizing the decoder stage, if present."""
+    if not decoder_info:
+        return ""
+    variant = decoder_info.get("variant", "n/a")
+    model_id = decoder_info.get("model_id", "n/a")
+    distance = decoder_info.get("distance", "n/a")
+    rounds = decoder_info.get("rounds", "n/a")
+    density_reduction = decoder_info.get("density_reduction", 0.0)
+    ler_improvement = decoder_info.get("ler_improvement", 1.0)
+    return (
+        "\nError-correction decoder (applied upstream):\n"
+        f"  variant:           {variant}\n"
+        f"  model_id:          {model_id}\n"
+        f"  surface code:      d={distance}, rounds={rounds}\n"
+        f"  syndrome density:  {density_reduction*100:.1f}% reduction\n"
+        f"  LER proxy:         {ler_improvement:.2f}x improvement"
+    )
+
+
+def generate_script(
+    analysis: dict[str, Any],
+    decoder_info: dict[str, Any] | None = None,
+) -> str:
+    """Build the CUDA-Q script text from analyzer (+ optional decoder) output."""
     experiment = analysis.get("experiment") or "unspecified"
     qubit_id = analysis.get("qubit_id") or "q0"
     notes = (analysis.get("notes") or "").replace('"""', "'''")
@@ -101,5 +125,6 @@ def generate_script(analysis: dict[str, Any]) -> str:
         qubit_id=qubit_id,
         notes=textwrap.shorten(notes, width=240, placeholder="…"),
         params_repr=_params_repr(params),
+        decoder_header=_decoder_header(decoder_info),
     )
     return script

src/qcal/config.py

@@ -0,0 +1,129 @@
+"""Persistent config for QCal Copilot.
+
+Stores user-level settings (API keys, endpoint overrides) in a TOML file
+under ``~/.config/qcal/config.toml`` (XDG-compliant via ``platformdirs``).
+Callers should always prefer environment variables when present; the config
+file is a convenience for long-lived interactive use, never a security
+boundary.
+
+Schema (TOML)::
+
+    [nvidia]
+    api_key       = "nvapi-..."
+    nim_endpoint  = "https://integrate.api.nvidia.com/v1/chat/completions"
+    nim_model     = "nvidia/ising-calibration-1-35b-a3b"
+    vlm_model_id  = "nvidia/Ising-Calibration-1-35B-A3B"
+    decoder_fast  = "nvidia/Ising-Decoder-SurfaceCode-1-Fast"
+    decoder_accurate = "nvidia/Ising-Decoder-SurfaceCode-1-Accurate"
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any, Optional
+
+from platformdirs import user_config_dir
+
+if sys.version_info >= (3, 11):
+    import tomllib  # type: ignore[attr-defined]
+else:  # pragma: no cover — 3.10 fallback declared in pyproject
+    import tomli as tomllib  # type: ignore[no-redef]
+
+
+APP_NAME = "qcal"
+CONFIG_FILENAME = "config.toml"
+
+
+def config_path() -> Path:
+    """Absolute path to the config file. Directory is created on first write."""
+    override = os.getenv("QCAL_CONFIG_PATH")
+    if override:
+        return Path(override)
+    return Path(user_config_dir(APP_NAME)) / CONFIG_FILENAME
+
+
+def load() -> dict[str, Any]:
+    """Return the parsed config, or an empty dict if none exists or is unreadable."""
+    path = config_path()
+    if not path.exists():
+        return {}
+    try:
+        with path.open("rb") as f:
+            return tomllib.load(f)
+    except Exception:  # noqa: BLE001 — bad config should never crash analysis
+        return {}
+
+
+def save(data: dict[str, Any]) -> Path:
+    """Write ``data`` to the config file, creating parent dirs if needed.
+
+    Uses a hand-rolled TOML writer to avoid pulling in another dep. Only
+    supports the flat [section]-of-scalars shape this app needs.
+    """
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    lines: list[str] = []
+    for section, values in sorted(data.items()):
+        if not isinstance(values, dict):
+            continue
+        lines.append(f"[{section}]")
+        for key, value in sorted(values.items()):
+            lines.append(f"{key} = {_toml_value(value)}")
+        lines.append("")
+
+    path.write_text("\n".join(lines).rstrip() + "\n", encoding="utf-8")
+    # Tighten perms on the file since it may hold a secret.
+    try:
+        path.chmod(0o600)
+    except OSError:
+        pass
+    return path
+
+
+def _toml_value(v: Any) -> str:
+    if isinstance(v, bool):
+        return "true" if v else "false"
+    if isinstance(v, (int, float)):
+        return repr(v)
+    # default: quoted string, TOML basic-string escaping
+    s = str(v).replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
+    return f'"{s}"'
+
+
+# ---------------------------------------------------------------------------
+# Accessors
+# ---------------------------------------------------------------------------
+
+def get(section: str, key: str, default: Optional[Any] = None) -> Any:
+    return (load().get(section) or {}).get(key, default)
+
+
+def set_value(section: str, key: str, value: Any) -> Path:
+    data = load()
+    data.setdefault(section, {})[key] = value
+    return save(data)
+
+
+def get_api_key() -> Optional[str]:
+    """NIM API key: env wins, then config file."""
+    env = os.getenv("NVIDIA_API_KEY") or os.getenv("NIM_API_KEY")
+    if env:
+        return env
+    return get("nvidia", "api_key")
+
+
+def set_api_key(value: str) -> Path:
+    return set_value("nvidia", "api_key", value)
+
+
+def clear_api_key() -> Optional[Path]:
+    data = load()
+    nvidia = data.get("nvidia") or {}
+    if "api_key" in nvidia:
+        nvidia.pop("api_key")
+        data["nvidia"] = nvidia
+        return save(data)
+    return None

src/qcal/data.py

@@ -0,0 +1,463 @@
+"""Input preprocessing for QCal Copilot.
+
+Normalizes user inputs — image, CSV/TSV, or raw numpy arrays from control
+hardware — into a :class:`CalibrationPayload` the analyzer can send to the
+vision-language model. For numpy input we also auto-fit standard calibration
+models (Rabi, Ramsey, T1, T2-echo) and attach the fit parameters as text
+context; Ising cross-references those numbers against the rendered plot,
+which is the single biggest quality lever in the pipeline.
+"""
+
+from __future__ import annotations
+
+import io
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional, Union
+
+import numpy as np
+import pandas as pd
+from PIL import Image
+
+from .fit import FitResult, autofit
+
+
+SUPPORTED_IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".bmp", ".tiff", ".webp"}
+SUPPORTED_TABLE_EXTS = {".csv", ".tsv"}
+SUPPORTED_ARRAY_EXTS = {".npy", ".npz"}
+
+# Experiment types this module knows how to render.
+EXPERIMENT_RENDERERS: dict[str, str] = {
+    "rabi": "line",
+    "ramsey": "line",
+    "t1": "line",
+    "t2": "line",
+    "t2_echo": "line",
+    "resonator_spec": "line",
+    "iq_trace": "line",
+    "rabi_chevron": "heatmap",
+    "readout_iq": "scatter",
+    "unknown": "line",
+}
+
+
+ArrayLike = Union[np.ndarray, "list[float]", "tuple[float, ...]"]
+
+
+@dataclass
+class CalibrationPayload:
+    """Container holding normalized calibration data for downstream analysis."""
+
+    image: Optional[Image.Image] = None
+    table: Optional[pd.DataFrame] = None
+    source_name: str = ""
+    kind: str = "unknown"  # "image" | "csv" | "array" | "unknown"
+    experiment_type: Optional[str] = None
+    fit: Optional[FitResult] = None
+    metadata: dict = field(default_factory=dict)
+    numeric_summary: str = ""
+
+    def summary(self) -> str:
+        if self.kind == "image" and self.image is not None:
+            w, h = self.image.size
+            return f"Image `{self.source_name}` ({w}x{h}, mode={self.image.mode})"
+        if self.kind == "csv" and self.table is not None:
+            rows, cols = self.table.shape
+            col_list = ", ".join(map(str, self.table.columns[:8]))
+            more = " …" if self.table.shape[1] > 8 else ""
+            return (
+                f"Table `{self.source_name}` ({rows} rows × {cols} cols). "
+                f"Columns: {col_list}{more}"
+            )
+        if self.kind == "array":
+            exp = self.experiment_type or "unknown"
+            return f"Array `{self.source_name}` (experiment={exp})"
+        return "No data provided."
+
+    def table_preview_markdown(self, max_rows: int = 10) -> str:
+        if self.table is None:
+            return ""
+        return self.table.head(max_rows).to_markdown(index=False)
+
+    def prompt_context(self) -> Optional[str]:
+        """Text appended to the VLM user prompt, if any."""
+        chunks: list[str] = []
+        if self.numeric_summary:
+            chunks.append(self.numeric_summary)
+        if self.fit is not None and self.fit.ok:
+            chunks.append(self.fit.summary_text())
+        if self.metadata:
+            chunks.append(
+                "Metadata: "
+                + ", ".join(f"{k}={v}" for k, v in self.metadata.items())
+            )
+        if self.table is not None:
+            chunks.append(
+                "Table preview (markdown):\n" + self.table_preview_markdown()
+            )
+        return "\n".join(chunks) if chunks else None
+
+
+# ---------------------------------------------------------------------------
+# Plot rendering helpers
+# ---------------------------------------------------------------------------
+
+def _render_table_as_image(df: pd.DataFrame) -> Image.Image:
+    """Render a small preview image of a table so the VLM can still see it."""
+    import matplotlib.pyplot as plt
+
+    preview = df.head(25)
+    fig, ax = plt.subplots(
+        figsize=(min(2 + 1.1 * len(preview.columns), 14), min(1 + 0.3 * len(preview), 10))
+    )
+    ax.axis("off")
+    tbl = ax.table(
+        cellText=preview.round(4).astype(str).values,
+        colLabels=[str(c) for c in preview.columns],
+        loc="center",
+        cellLoc="center",
+    )
+    tbl.auto_set_font_size(False)
+    tbl.set_fontsize(8)
+    tbl.scale(1, 1.2)
+    buf = io.BytesIO()
+    fig.savefig(buf, format="png", bbox_inches="tight", dpi=120)
+    plt.close(fig)
+    buf.seek(0)
+    return Image.open(buf).convert("RGB")
+
+
+def _fig_to_pil(fig) -> Image.Image:
+    import matplotlib.pyplot as plt
+
+    buf = io.BytesIO()
+    fig.savefig(buf, format="png", bbox_inches="tight", dpi=140)
+    plt.close(fig)
+    buf.seek(0)
+    return Image.open(buf).convert("RGB")
+
+
+def _render_line(
+    y: np.ndarray,
+    x: Optional[np.ndarray],
+    *,
+    experiment: str,
+    x_label: str,
+    y_label: str,
+    title: Optional[str],
+    fit: Optional[FitResult],
+) -> Image.Image:
+    import matplotlib.pyplot as plt
+
+    fig, ax = plt.subplots(figsize=(6.5, 4.0))
+    xs = x if x is not None else np.arange(y.size)
+    ax.plot(xs, y, marker="o", markersize=3, linewidth=1.0, color="#1f77b4", label="data")
+
+    # Overlay the fit curve when available.
+    if fit is not None and fit.ok:
+        try:
+            x_dense = np.linspace(float(xs.min()), float(xs.max()), 400)
+            y_fit = _evaluate_fit(fit, x_dense)
+            if y_fit is not None:
+                ax.plot(x_dense, y_fit, color="#d62728", linewidth=1.5, label="fit")
+        except Exception:  # noqa: BLE001 — fit overlay is best-effort
+            pass
+
+    ax.set_xlabel(x_label)
+    ax.set_ylabel(y_label)
+    ax.set_title(title or f"{experiment} sweep")
+    ax.grid(True, alpha=0.3)
+    ax.legend(loc="best", frameon=False)
+    return _fig_to_pil(fig)
+
+
+def _render_heatmap(
+    z: np.ndarray,
+    *,
+    experiment: str,
+    x_label: str,
+    y_label: str,
+    title: Optional[str],
+    extent: Optional[tuple[float, float, float, float]] = None,
+) -> Image.Image:
+    import matplotlib.pyplot as plt
+
+    fig, ax = plt.subplots(figsize=(6.5, 4.2))
+    im = ax.imshow(
+        z,
+        aspect="auto",
+        origin="lower",
+        cmap="viridis",
+        extent=extent,
+        interpolation="nearest",
+    )
+    fig.colorbar(im, ax=ax, label="signal")
+    ax.set_xlabel(x_label)
+    ax.set_ylabel(y_label)
+    ax.set_title(title or f"{experiment}")
+    return _fig_to_pil(fig)
+
+
+def _render_scatter(
+    iq: np.ndarray,
+    *,
+    title: Optional[str],
+) -> Image.Image:
+    """Scatter + marginal histograms for readout IQ shots (shape (N, 2))."""
+    import matplotlib.pyplot as plt
+
+    fig, ax = plt.subplots(figsize=(5.5, 5.2))
+    ax.scatter(iq[:, 0], iq[:, 1], s=4, alpha=0.5, color="#1f77b4")
+    ax.set_xlabel("I (a.u.)")
+    ax.set_ylabel("Q (a.u.)")
+    ax.set_title(title or "Readout IQ histogram")
+    ax.grid(True, alpha=0.3)
+    ax.set_aspect("equal", adjustable="datalim")
+    return _fig_to_pil(fig)
+
+
+def _evaluate_fit(fit: FitResult, x: np.ndarray) -> Optional[np.ndarray]:
+    """Recreate the fitted curve from stored parameters for overlay plotting."""
+    p = fit.params
+    if fit.model == "damped_sine":
+        A = p["amplitude"]
+        freq = next((v for k, v in p.items() if k.startswith("freq_per_")), 0.0)
+        tau = next((v for k, v in p.items() if k.startswith("tau_")), 1.0)
+        return (
+            A * np.exp(-x / tau) * np.sin(2 * np.pi * freq * x + p["phase_rad"])
+            + p["offset"]
+        )
+    if fit.model == "damped_cosine":
+        A = p["amplitude"]
+        freq = next((v for k, v in p.items() if k.startswith("detuning_per_")), 0.0)
+        tau = next((v for k, v in p.items() if k.startswith("t2star_")), 1.0)
+        return (
+            A * np.exp(-x / tau) * np.cos(2 * np.pi * freq * x + p["phase_rad"])
+            + p["offset"]
+        )
+    if fit.model == "exp_decay":
+        A = p["amplitude"]
+        tau = next((v for k, v in p.items() if k.startswith("tau_")), 1.0)
+        return A * np.exp(-x / tau) + p["offset"]
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Numeric summary
+# ---------------------------------------------------------------------------
+
+def _numeric_summary(arr: np.ndarray, experiment: str) -> str:
+    arr = np.asarray(arr)
+    shape = arr.shape
+    finite = arr[np.isfinite(arr)] if arr.dtype.kind in "fc" else arr.ravel()
+    if finite.size == 0:
+        return f"Numeric summary: shape={shape}, no finite values"
+    parts = [
+        f"Numeric summary for experiment `{experiment}`:",
+        f"- shape: {shape}, dtype: {arr.dtype}",
+        f"- range: [{float(finite.min()):.4g}, {float(finite.max()):.4g}]",
+        f"- mean: {float(finite.mean()):.4g}, std: {float(finite.std()):.4g}",
+    ]
+    if arr.ndim == 1:
+        parts.append(
+            f"- argmax index: {int(np.nanargmax(arr))}, argmin index: {int(np.nanargmin(arr))}"
+        )
+    return "\n".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# Public: from_array
+# ---------------------------------------------------------------------------
+
+def from_array(
+    array: ArrayLike,
+    experiment_type: str = "unknown",
+    *,
+    x: Optional[ArrayLike] = None,
+    x_unit: str = "us",
+    x_label: Optional[str] = None,
+    y_label: Optional[str] = None,
+    title: Optional[str] = None,
+    metadata: Optional[dict] = None,
+    fit: bool = True,
+    source_name: str = "array",
+) -> CalibrationPayload:
+    """Build a :class:`CalibrationPayload` from raw numpy data.
+
+    Parameters
+    ----------
+    array
+        The measurement. Shape depends on ``experiment_type``:
+          * 1-D sweep (``rabi``, ``ramsey``, ``t1``, ``t2``, ``t2_echo``,
+            ``resonator_spec``, ``iq_trace``)
+          * 2-D heatmap (``rabi_chevron``) — shape ``(len(y_axis), len(x_axis))``
+          * 2-D scatter (``readout_iq``) — shape ``(N, 2)`` for I/Q shots
+    experiment_type
+        One of :data:`EXPERIMENT_RENDERERS`; drives plot shape and fit model.
+    x
+        Independent variable for 1-D sweeps (times, amplitudes, frequencies).
+    x_unit
+        Unit label used in fit parameter keys and axis labels. Ignored for 2-D.
+    x_label, y_label, title
+        Optional axis overrides; sensible defaults per ``experiment_type``.
+    metadata
+        Free-form key/value pairs (qubit id, temperature, run id…) — appended
+        verbatim to the VLM prompt.
+    fit
+        If ``True``, auto-fit the curve for supported 1-D experiments and
+        attach :class:`~qcal.fit.FitResult` to the payload. Set ``False`` for
+        air-gapped installs without ``scipy`` or when the data isn't fittable.
+    source_name
+        Display name threaded into the summary and the VLM prompt.
+
+    Returns
+    -------
+    CalibrationPayload
+        Ready to pass to :func:`qcal.analyzer.analyze`.
+    """
+    arr = np.asarray(array)
+    md = dict(metadata or {})
+    kind_hint = EXPERIMENT_RENDERERS.get(experiment_type, "line")
+
+    # ------ render + optional fit ------
+    fit_result: Optional[FitResult] = None
+    if kind_hint == "line":
+        if arr.ndim != 1:
+            raise ValueError(
+                f"experiment_type '{experiment_type}' expects a 1-D array, "
+                f"got shape {arr.shape}"
+            )
+        x_arr = np.asarray(x, dtype=float) if x is not None else None
+        if fit:
+            fit_result = autofit(experiment_type, y=arr, x=x_arr, x_unit=x_unit)
+        img = _render_line(
+            arr,
+            x_arr,
+            experiment=experiment_type,
+            x_label=x_label or f"sweep ({x_unit})",
+            y_label=y_label or "signal (a.u.)",
+            title=title,
+            fit=fit_result,
+        )
+    elif kind_hint == "heatmap":
+        if arr.ndim != 2:
+            raise ValueError(
+                f"experiment_type '{experiment_type}' expects a 2-D array, "
+                f"got shape {arr.shape}"
+            )
+        img = _render_heatmap(
+            arr,
+            experiment=experiment_type,
+            x_label=x_label or "drive amp (a.u.)",
+            y_label=y_label or "drive freq (MHz)",
+            title=title,
+        )
+    elif kind_hint == "scatter":
+        if arr.ndim != 2 or arr.shape[1] != 2:
+            raise ValueError(
+                f"experiment_type '{experiment_type}' expects shape (N, 2), "
+                f"got {arr.shape}"
+            )
+        img = _render_scatter(arr, title=title)
+    else:
+        raise ValueError(f"Unknown experiment_type '{experiment_type}'")
+
+    return CalibrationPayload(
+        image=img,
+        source_name=source_name,
+        kind="array",
+        experiment_type=experiment_type,
+        fit=fit_result,
+        metadata=md,
+        numeric_summary=_numeric_summary(arr, experiment_type),
+    )
+
+
+def from_npy(
+    path: str | Path,
+    experiment_type: str = "unknown",
+    *,
+    x_path: Optional[str | Path] = None,
+    **kwargs,
+) -> CalibrationPayload:
+    """Load a ``.npy`` file and wrap it via :func:`from_array`.
+
+    For ``.npz``, use :func:`from_npz` — it understands multi-array archives.
+    """
+    p = Path(path)
+    arr = np.load(p, allow_pickle=False)
+    x_arr = np.load(x_path, allow_pickle=False) if x_path else None
+    return from_array(
+        arr,
+        experiment_type=experiment_type,
+        x=x_arr,
+        source_name=p.name,
+        **kwargs,
+    )
+
+
+def from_npz(
+    path: str | Path,
+    experiment_type: str = "unknown",
+    *,
+    y_key: str = "y",
+    x_key: Optional[str] = "x",
+    **kwargs,
+) -> CalibrationPayload:
+    """Load a ``.npz`` archive. Expects ``y`` (required) and ``x`` (optional)."""
+    p = Path(path)
+    with np.load(p, allow_pickle=False) as data:
+        if y_key not in data:
+            raise KeyError(
+                f"{p.name}: missing required key '{y_key}'. Keys present: {list(data.keys())}"
+            )
+        y = np.asarray(data[y_key])
+        x = np.asarray(data[x_key]) if x_key and x_key in data else None
+    return from_array(
+        y,
+        experiment_type=experiment_type,
+        x=x,
+        source_name=p.name,
+        **kwargs,
+    )
+
+
+# ---------------------------------------------------------------------------
+# File loader (existing callers)
+# ---------------------------------------------------------------------------
+
+def load_payload(
+    file_path: str | Path,
+    experiment_type: str = "unknown",
+    fit: bool = True,
+) -> CalibrationPayload:
+    """Load an uploaded file into a :class:`CalibrationPayload`.
+
+    Auto-dispatches by extension across image, CSV/TSV, and ``.npy``/``.npz``.
+    """
+    if file_path is None:
+        return CalibrationPayload()
+
+    path = Path(file_path)
+    ext = path.suffix.lower()
+    name = path.name
+
+    if ext in SUPPORTED_IMAGE_EXTS:
+        img = Image.open(path).convert("RGB")
+        return CalibrationPayload(image=img, source_name=name, kind="image")
+
+    if ext in SUPPORTED_TABLE_EXTS:
+        sep = "," if ext == ".csv" else "\t"
+        df = pd.read_csv(path, sep=sep)
+        img = _render_table_as_image(df)
+        return CalibrationPayload(image=img, table=df, source_name=name, kind="csv")
+
+    if ext == ".npy":
+        return from_npy(path, experiment_type=experiment_type, fit=fit)
+    if ext == ".npz":
+        return from_npz(path, experiment_type=experiment_type, fit=fit)
+
+    raise ValueError(
+        f"Unsupported file type '{ext}'. Accepted: "
+        f"{sorted(SUPPORTED_IMAGE_EXTS | SUPPORTED_TABLE_EXTS | SUPPORTED_ARRAY_EXTS)}"
+    )

src/qcal/decoder.py

@@ -0,0 +1,499 @@
+"""Ising 3D CNN surface-code pre-decoder stage.
+
+Runs one of the NVIDIA Ising Decoder 3D CNN pre-decoders on a noisy syndrome
+volume to *sparsify* it, then hands the cleaned volume to PyMatching for final
+MWPM correction. This is a drop-in stage that sits after the calibration
+analyzer — it never mutates calibration state.
+
+Two model variants are supported:
+
+  * "fast"     — nvidia/Ising-Decoder-SurfaceCode-1-Fast     (~912k params)
+  * "accurate" — nvidia/Ising-Decoder-SurfaceCode-1-Accurate (~1.79M params)
+
+When the Hugging Face weights can't be loaded (no access, no internet, no
+GPU), we fall back to a deterministic "neighbor-support" denoiser so the demo
+still runs and the architecture is exercised end-to-end.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+import numpy as np
+
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+VARIANT_FAST = "fast"
+VARIANT_ACCURATE = "accurate"
+VARIANTS = (VARIANT_FAST, VARIANT_ACCURATE)
+
+MODEL_IDS: dict[str, str] = {
+    VARIANT_FAST: os.getenv(
+        "QCAL_DECODER_FAST_ID", "nvidia/Ising-Decoder-SurfaceCode-1-Fast"
+    ),
+    VARIANT_ACCURATE: os.getenv(
+        "QCAL_DECODER_ACCURATE_ID", "nvidia/Ising-Decoder-SurfaceCode-1-Accurate"
+    ),
+}
+APPROX_PARAMS: dict[str, int] = {
+    VARIANT_FAST: 912_000,
+    VARIANT_ACCURATE: 1_790_000,
+}
+
+
+# ---------------------------------------------------------------------------
+# Result container
+# ---------------------------------------------------------------------------
+
+@dataclass
+class DecoderResult:
+    """Structured output of a full decoder run (CNN + optional MWPM)."""
+
+    variant: str
+    distance: int
+    rounds: int
+    n_shots: int
+    error_rate: float
+
+    density_before: float = 0.0
+    density_after: float = 0.0
+
+    inference_ms: float = 0.0
+    mwpm_ms_before: Optional[float] = None
+    mwpm_ms_after: Optional[float] = None
+
+    ler_proxy_before: float = 0.0
+    ler_proxy_after: float = 0.0
+
+    raw_example: np.ndarray = field(default_factory=lambda: np.zeros((0, 0)))
+    denoised_example: np.ndarray = field(default_factory=lambda: np.zeros((0, 0)))
+
+    backend_note: str = ""
+    model_id: str = ""
+    error: Optional[str] = None
+
+    @property
+    def ok(self) -> bool:
+        return self.error is None
+
+    @property
+    def density_reduction(self) -> float:
+        if self.density_before <= 0:
+            return 0.0
+        return 1.0 - (self.density_after / self.density_before)
+
+    @property
+    def ler_improvement(self) -> float:
+        if self.ler_proxy_after <= 0:
+            return float("inf") if self.ler_proxy_before > 0 else 1.0
+        return self.ler_proxy_before / self.ler_proxy_after
+
+    @property
+    def mwpm_speedup(self) -> Optional[float]:
+        if not self.mwpm_ms_before or not self.mwpm_ms_after:
+            return None
+        return self.mwpm_ms_before / max(self.mwpm_ms_after, 1e-6)
+
+    def markdown(self) -> str:
+        if self.error:
+            return f"**Decoder error:** {self.error}"
+        approx = APPROX_PARAMS.get(self.variant, 0)
+        lines = [
+            f"**Variant:** `{self.variant}` (~{approx/1e6:.2f}M params)",
+            f"**Model id:** `{self.model_id}`",
+            f"**Surface code:** distance = {self.distance}, rounds = {self.rounds}",
+            f"**Shots:** {self.n_shots}",
+            f"**Physical error rate (p):** {self.error_rate:.4f}",
+            "",
+            "**Syndrome density**",
+            f"- before CNN: {self.density_before:.4f}",
+            f"- after  CNN: {self.density_after:.4f}",
+            f"- reduction: **{self.density_reduction*100:.1f}%**",
+            "",
+            "**Timing**",
+            f"- CNN inference: {self.inference_ms:.2f} ms total"
+            f" ({self.inference_ms/max(self.n_shots,1):.3f} ms/shot)",
+        ]
+        if self.mwpm_ms_before is not None:
+            lines += [
+                f"- MWPM on raw syndromes: {self.mwpm_ms_before:.2f} ms",
+                f"- MWPM on denoised syndromes: {self.mwpm_ms_after:.2f} ms",
+            ]
+            speedup = self.mwpm_speedup
+            if speedup:
+                lines.append(f"- MWPM speedup: **{speedup:.2f}×**")
+        else:
+            lines.append("- MWPM stage: _skipped (pymatching not installed)_")
+        lines += [
+            "",
+            "**Logical-error-rate proxy** _(syndrome-weight threshold — demo only)_",
+            f"- before CNN: {self.ler_proxy_before:.4f}",
+            f"- after  CNN: {self.ler_proxy_after:.4f}",
+            f"- improvement: **{self.ler_improvement:.2f}×**",
+            "",
+            f"_{self.backend_note}_",
+        ]
+        return "\n".join(lines)
+
+    def _repr_markdown_(self) -> str:  # Jupyter renders this directly
+        return self.markdown()
+
+
+# ---------------------------------------------------------------------------
+# Synthetic syndrome generation
+# ---------------------------------------------------------------------------
+
+def generate_syndromes(
+    distance: int,
+    rounds: int,
+    error_rate: float,
+    n_shots: int,
+    seed: Optional[int] = 42,
+) -> np.ndarray:
+    """Generate synthetic syndrome volumes.
+
+    Shape: (n_shots, distance, distance, rounds) of uint8.
+
+    We sample each space-time cell independently from Bernoulli(p), then add
+    a small amount of spatial correlation (a 2-cell "chain" event per shot)
+    so the denoiser has structure to exploit. This mimics what a detector
+    error model produces for a depolarizing noise channel at low p.
+    """
+    if distance < 3:
+        raise ValueError("distance must be >= 3 for a meaningful demo")
+    if rounds < 1:
+        raise ValueError("rounds must be >= 1")
+    if not 0.0 <= error_rate <= 0.5:
+        raise ValueError("error_rate must be in [0, 0.5]")
+
+    rng = np.random.default_rng(seed)
+    shape = (n_shots, distance, distance, rounds)
+    volumes = (rng.random(shape) < error_rate).astype(np.uint8)
+
+    # Inject correlated 2-cell chains — realistic time-like errors.
+    n_chains = max(1, int(n_shots * rounds * error_rate * 0.5))
+    for _ in range(n_chains):
+        s = rng.integers(0, n_shots)
+        x = rng.integers(0, distance)
+        y = rng.integers(0, distance)
+        t = rng.integers(0, max(rounds - 1, 1))
+        volumes[s, x, y, t] = 1
+        if rounds > 1:
+            volumes[s, x, y, t + 1] = 1
+    return volumes
+
+
+# ---------------------------------------------------------------------------
+# Model loading (HF) and fallback
+# ---------------------------------------------------------------------------
+
+_MODEL_CACHE: dict[str, Any] = {}
+
+
+def _try_load_hf_decoder(variant: str) -> tuple[Any, str]:
+    """Attempt to load an Ising decoder via Hugging Face.
+
+    Returns (callable_or_None, backend_note).
+    """
+    model_id = MODEL_IDS[variant]
+    if model_id in _MODEL_CACHE:
+        return _MODEL_CACHE[model_id], f"Loaded `{model_id}` from cache."
+
+    try:
+        import torch
+        from transformers import AutoModel
+    except Exception as exc:  # noqa: BLE001
+        return None, f"PyTorch/transformers unavailable ({exc}); using fallback denoiser."
+
+    try:
+        device = "cuda" if torch.cuda.is_available() else "cpu"
+        dtype = torch.float32
+        model = AutoModel.from_pretrained(
+            model_id, trust_remote_code=True, torch_dtype=dtype
+        ).to(device)
+        model.eval()
+        _MODEL_CACHE[model_id] = (model, device)
+        return (model, device), f"Loaded `{model_id}` on {device}."
+    except Exception as exc:  # noqa: BLE001
+        return (
+            None,
+            f"Could not load `{model_id}` ({type(exc).__name__}: {exc}). "
+            "Falling back to built-in neighbor-support denoiser.",
+        )
+
+
+def _fallback_denoise(volumes: np.ndarray) -> np.ndarray:
+    """Drop any detection event with no 3D neighbor — a cheap sparsifier.
+
+    Isolated single-cell detections are almost always measurement noise at the
+    p-regimes the Ising CNNs target; neighborhood support indicates a real
+    error chain. This is a useful first-order stand-in when the HF weights
+    aren't available.
+    """
+    v = volumes.astype(np.int16)
+    neigh = np.zeros_like(v)
+    for dx in (-1, 0, 1):
+        for dy in (-1, 0, 1):
+            for dt in (-1, 0, 1):
+                if dx == dy == dt == 0:
+                    continue
+                shifted = np.roll(v, shift=(dx, dy, dt), axis=(1, 2, 3))
+                # zero out the wrap-around planes so boundaries don't leak
+                if dx == 1:
+                    shifted[:, 0, :, :] = 0
+                elif dx == -1:
+                    shifted[:, -1, :, :] = 0
+                if dy == 1:
+                    shifted[:, :, 0, :] = 0
+                elif dy == -1:
+                    shifted[:, :, -1, :] = 0
+                if dt == 1:
+                    shifted[:, :, :, 0] = 0
+                elif dt == -1:
+                    shifted[:, :, :, -1] = 0
+                neigh += shifted
+    return (v * (neigh >= 1)).astype(np.uint8)
+
+
+def _run_hf_inference(loaded: tuple[Any, str], volumes: np.ndarray) -> np.ndarray:
+    """Run the Ising decoder CNN on a stack of syndrome volumes.
+
+    We try the common Vision-style entrypoints; model authors expose different
+    call conventions, so we guard each attempt. On failure, raise so the
+    caller can fall back.
+    """
+    import torch
+
+    model, device = loaded
+    x = torch.from_numpy(volumes).float().unsqueeze(1).to(device)  # (N, 1, D, D, T)
+    with torch.no_grad():
+        try:
+            out = model(x)
+        except TypeError:
+            out = model(pixel_values=x)
+
+        if hasattr(out, "logits"):
+            out = out.logits
+        if isinstance(out, (tuple, list)):
+            out = out[0]
+
+        # The pre-decoder produces a per-cell "keep" probability; threshold it.
+        out = torch.sigmoid(out) if out.dtype.is_floating_point else out.float()
+        out = out.squeeze(1)  # (N, D, D, T)
+        mask = (out >= 0.5).to(torch.uint8)
+        # The CNN is a sparsifier, not a generator — never turn on new bits.
+        mask = mask * torch.from_numpy(volumes).to(mask.device)
+    return mask.cpu().numpy().astype(np.uint8)
+
+
+# ---------------------------------------------------------------------------
+# Optional MWPM stage
+# ---------------------------------------------------------------------------
+
+def _build_demo_matching(distance: int, rounds: int):
+    """Build a small PyMatching graph over the space-time volume.
+
+    NOTE: this is **not** a real surface-code detector error model. We connect
+    each cell to its 6-neighborhood so PyMatching has something MWPM-able;
+    real deployments should feed a `stim`-generated DEM.
+    """
+    import pymatching
+
+    m = pymatching.Matching()
+
+    def node(x: int, y: int, t: int) -> int:
+        return t * distance * distance + y * distance + x
+
+    bit_id = 0
+    for t in range(rounds):
+        for y in range(distance):
+            for x in range(distance):
+                if x + 1 < distance:
+                    m.add_edge(node(x, y, t), node(x + 1, y, t), fault_ids={bit_id}, weight=1.0)
+                    bit_id += 1
+                if y + 1 < distance:
+                    m.add_edge(node(x, y, t), node(x, y + 1, t), fault_ids={bit_id}, weight=1.0)
+                    bit_id += 1
+                if t + 1 < rounds:
+                    m.add_edge(node(x, y, t), node(x, y, t + 1), fault_ids={bit_id}, weight=1.5)
+                    bit_id += 1
+        # Boundary edges along the x=0 / x=d-1 columns let isolated detectors terminate.
+        for y in range(distance):
+            m.add_boundary_edge(node(0, y, t), fault_ids=set(), weight=2.0)
+            m.add_boundary_edge(node(distance - 1, y, t), fault_ids=set(), weight=2.0)
+    return m
+
+
+def _time_mwpm(volumes: np.ndarray, matching) -> float:
+    """Decode every shot and return total wall time in ms."""
+    flat = volumes.reshape(volumes.shape[0], -1)
+    t0 = time.perf_counter()
+    for row in flat:
+        matching.decode(row)
+    return (time.perf_counter() - t0) * 1000.0
+
+
+# ---------------------------------------------------------------------------
+# LER proxy
+# ---------------------------------------------------------------------------
+
+def _ler_proxy(volumes: np.ndarray, distance: int) -> float:
+    """Fraction of shots with syndrome weight above a distance-scaled threshold.
+
+    This isn't a real logical error rate — it's a first-order proxy used to
+    show the relative improvement from denoising in the UI.
+    """
+    if volumes.size == 0:
+        return 0.0
+    per_shot = volumes.reshape(volumes.shape[0], -1).sum(axis=1)
+    threshold = max(1, distance)
+    return float((per_shot > threshold).mean())
+
+
+# ---------------------------------------------------------------------------
+# Public entrypoint
+# ---------------------------------------------------------------------------
+
+def run_decoder(
+    variant: str = VARIANT_FAST,
+    distance: int = 5,
+    rounds: int = 5,
+    error_rate: float = 0.005,
+    n_shots: int = 128,
+    seed: Optional[int] = 42,
+) -> DecoderResult:
+    """Full pipeline: synthesize syndromes → CNN sparsify → (MWPM) → metrics."""
+    if variant not in VARIANTS:
+        return DecoderResult(
+            variant=variant,
+            distance=distance,
+            rounds=rounds,
+            n_shots=n_shots,
+            error_rate=error_rate,
+            error=f"Unknown variant '{variant}'. Choose one of {VARIANTS}.",
+        )
+
+    try:
+        raw = generate_syndromes(distance, rounds, error_rate, n_shots, seed=seed)
+    except Exception as exc:  # noqa: BLE001
+        return DecoderResult(
+            variant=variant, distance=distance, rounds=rounds,
+            n_shots=n_shots, error_rate=error_rate,
+            error=f"Syndrome generation failed: {exc}",
+        )
+
+    loaded, backend_note = _try_load_hf_decoder(variant)
+
+    t0 = time.perf_counter()
+    if loaded is not None:
+        try:
+            denoised = _run_hf_inference(loaded, raw)
+        except Exception as exc:  # noqa: BLE001
+            backend_note = (
+                f"HF model load succeeded but inference failed ({exc}); "
+                "falling back to neighbor-support denoiser."
+            )
+            denoised = _fallback_denoise(raw)
+    else:
+        denoised = _fallback_denoise(raw)
+    inference_ms = (time.perf_counter() - t0) * 1000.0
+
+    density_before = float(raw.mean())
+    density_after = float(denoised.mean())
+
+    # Optional MWPM stage
+    mwpm_before = mwpm_after = None
+    try:
+        import pymatching  # noqa: F401
+
+        matching = _build_demo_matching(distance, rounds)
+        mwpm_before = _time_mwpm(raw, matching)
+        mwpm_after = _time_mwpm(denoised, matching)
+    except ImportError:
+        backend_note += " (pymatching not installed — MWPM skipped)"
+    except Exception as exc:  # noqa: BLE001
+        backend_note += f" (MWPM stage failed: {exc})"
+
+    mid_t = rounds // 2
+    result = DecoderResult(
+        variant=variant,
+        distance=distance,
+        rounds=rounds,
+        n_shots=n_shots,
+        error_rate=error_rate,
+        density_before=density_before,
+        density_after=density_after,
+        inference_ms=inference_ms,
+        mwpm_ms_before=mwpm_before,
+        mwpm_ms_after=mwpm_after,
+        ler_proxy_before=_ler_proxy(raw, distance),
+        ler_proxy_after=_ler_proxy(denoised, distance),
+        raw_example=raw[0, :, :, mid_t].copy(),
+        denoised_example=denoised[0, :, :, mid_t].copy(),
+        backend_note=backend_note,
+        model_id=MODEL_IDS[variant],
+    )
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Visualization helper
+# ---------------------------------------------------------------------------
+
+def plot_comparison(result: DecoderResult):
+    """Return a matplotlib Figure comparing raw vs denoised syndrome slices."""
+    import matplotlib.pyplot as plt
+
+    fig, axes = plt.subplots(1, 3, figsize=(11, 3.6))
+    axes[0].imshow(result.raw_example, cmap="Reds", vmin=0, vmax=1, interpolation="nearest")
+    axes[0].set_title(f"Raw syndrome\n(shot 0, t={result.rounds // 2})")
+    axes[0].set_xticks([]); axes[0].set_yticks([])
+
+    axes[1].imshow(
+        result.denoised_example, cmap="Greens", vmin=0, vmax=1, interpolation="nearest"
+    )
+    axes[1].set_title(f"After {result.variant} CNN\n(sparsified)")
+    axes[1].set_xticks([]); axes[1].set_yticks([])
+
+    categories = ["density", "LER proxy"]
+    before = [result.density_before, result.ler_proxy_before]
+    after = [result.density_after, result.ler_proxy_after]
+    x = np.arange(len(categories))
+    width = 0.38
+    axes[2].bar(x - width / 2, before, width, label="raw", color="#d62728")
+    axes[2].bar(x + width / 2, after, width, label="denoised", color="#2ca02c")
+    axes[2].set_xticks(x)
+    axes[2].set_xticklabels(categories)
+    axes[2].set_title("Before vs After")
+    axes[2].legend()
+    axes[2].grid(True, axis="y", alpha=0.3)
+
+    fig.tight_layout()
+    return fig
+
+
+# ---------------------------------------------------------------------------
+# Helper: derive a sensible error rate from calibration analysis
+# ---------------------------------------------------------------------------
+
+def suggest_error_rate(analysis: Optional[dict]) -> float:
+    """Map a calibration analysis dict to a plausible physical error rate.
+
+    Rough heuristic: start at 1e-3 (good transmon) and inflate based on how
+    far the recommended drive amplitude deviates from a nominal 1.0.
+    """
+    if not analysis:
+        return 0.005
+    params = analysis.get("recommended_parameters") or {}
+    try:
+        amp = float(params.get("drive_amplitude", 1.0))
+    except (TypeError, ValueError):
+        amp = 1.0
+    deviation = abs(1.0 - amp)
+    return float(min(0.03, 0.001 + 0.01 * deviation))

src/qcal/fit.py

@@ -0,0 +1,351 @@
+"""Auto-fitting for common calibration experiments.
+
+Each fit returns a :class:`FitResult` with human-readable, unit-bearing
+parameters plus a normalized quality metric in ``[0, 1]``. These get woven
+into the VLM prompt so Ising can cross-check its vision analysis against
+hard numerical fits — the single biggest quality lever for the whole
+pipeline.
+
+Every fit is defensive: bad data returns ``FitResult.failed(reason=...)``
+instead of raising. Callers should always check ``result.ok``.
+
+Public entrypoints
+------------------
+* :func:`fit_rabi`     — damped sine (amplitude/duration sweep)
+* :func:`fit_ramsey`   — damped cosine with phase
+* :func:`fit_t1`       — exponential decay
+* :func:`fit_t2_echo`  — exponential decay (alias for T1 shape)
+* :func:`autofit`      — dispatch by experiment type
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from typing import Any, Callable, Optional
+
+import numpy as np
+
+
+@dataclass
+class FitResult:
+    """Structured fit output.
+
+    ``params`` uses named, unit-bearing keys (e.g. ``"tau_us"``,
+    ``"freq_mhz"``) so downstream code and the VLM prompt never have to
+    guess what each number means.
+    """
+
+    experiment: str
+    model: str
+    params: dict[str, float] = field(default_factory=dict)
+    fit_quality: float = 0.0  # R^2 in [0, 1]; 1 is perfect
+    residual_rms: float = 0.0
+    n_points: int = 0
+    ok: bool = True
+    reason: Optional[str] = None
+
+    @classmethod
+    def failed(cls, experiment: str, model: str, reason: str) -> "FitResult":
+        return cls(
+            experiment=experiment, model=model, ok=False, reason=reason
+        )
+
+    def summary_text(self) -> str:
+        """Compact one-line summary for injecting into the VLM prompt."""
+        if not self.ok:
+            return f"Fit ({self.experiment}, {self.model}) failed: {self.reason}"
+        bits = ", ".join(f"{k}={self._fmt(v)}" for k, v in self.params.items())
+        return (
+            f"Fit ({self.experiment} → {self.model}): {bits} "
+            f"| R²={self.fit_quality:.3f}, n={self.n_points}"
+        )
+
+    def markdown(self) -> str:
+        if not self.ok:
+            return f"**Fit failed** ({self.experiment}): {self.reason}"
+        lines = [
+            f"**Fit:** `{self.experiment}` → `{self.model}`",
+            f"- R² = {self.fit_quality:.4f} (RMS residual {self.residual_rms:.4g})",
+            f"- n = {self.n_points} points",
+            "",
+            "| param | value |",
+            "|---|---|",
+        ]
+        for k, v in self.params.items():
+            lines.append(f"| `{k}` | {self._fmt(v)} |")
+        return "\n".join(lines)
+
+    @staticmethod
+    def _fmt(v: float) -> str:
+        if not np.isfinite(v):
+            return "n/a"
+        av = abs(v)
+        if av >= 1e4 or (0 < av < 1e-3):
+            return f"{v:.3e}"
+        return f"{v:.4g}"
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _curve_fit(
+    model: Callable[..., np.ndarray],
+    x: np.ndarray,
+    y: np.ndarray,
+    p0: list[float],
+    bounds: Optional[tuple[list[float], list[float]]] = None,
+    maxfev: int = 5000,
+):
+    """Thin wrapper around ``scipy.optimize.curve_fit`` with kwargs filled."""
+    from scipy.optimize import curve_fit  # local import — scipy is optional-heavy
+
+    kwargs: dict[str, Any] = {"p0": p0, "maxfev": maxfev}
+    if bounds is not None:
+        kwargs["bounds"] = bounds
+    return curve_fit(model, x, y, **kwargs)
+
+
+def _prep(x: Optional[np.ndarray], y: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """Validate and coerce inputs to 1-D float arrays."""
+    y = np.asarray(y, dtype=float).ravel()
+    if y.size < 4:
+        raise ValueError("need at least 4 points to fit")
+    if x is None:
+        x = np.arange(y.size, dtype=float)
+    else:
+        x = np.asarray(x, dtype=float).ravel()
+    if x.shape != y.shape:
+        raise ValueError(f"x and y shape mismatch: {x.shape} vs {y.shape}")
+    mask = np.isfinite(x) & np.isfinite(y)
+    return x[mask], y[mask]
+
+
+def _r_squared(y: np.ndarray, y_hat: np.ndarray) -> float:
+    ss_res = float(np.sum((y - y_hat) ** 2))
+    ss_tot = float(np.sum((y - y.mean()) ** 2))
+    if ss_tot <= 0:
+        return 0.0
+    return max(0.0, 1.0 - ss_res / ss_tot)
+
+
+def _dominant_frequency(x: np.ndarray, y: np.ndarray) -> float:
+    """FFT-based seed for sinusoidal fits. Returns cycles per x-unit."""
+    if x.size < 4:
+        return 1.0
+    dx = float(np.median(np.diff(x)))
+    if dx <= 0:
+        return 1.0
+    y_centered = y - y.mean()
+    fft = np.fft.rfft(y_centered)
+    freqs = np.fft.rfftfreq(y.size, d=dx)
+    if freqs.size <= 1:
+        return 1.0
+    idx = int(np.argmax(np.abs(fft[1:])) + 1)  # skip DC
+    return float(freqs[idx])
+
+
+# ---------------------------------------------------------------------------
+# Rabi — damped sine
+# ---------------------------------------------------------------------------
+
+def _rabi_model(t, A, freq, tau, offset, phase):
+    return A * np.exp(-t / tau) * np.sin(2 * np.pi * freq * t + phase) + offset
+
+
+def fit_rabi(
+    y: np.ndarray,
+    x: Optional[np.ndarray] = None,
+    x_unit: str = "a.u.",
+) -> FitResult:
+    """Fit a Rabi oscillation: A·exp(-t/τ)·sin(2π·f·t + φ) + c.
+
+    Returned params keyed for readability:
+      ``amplitude``, ``freq`` (cycles per ``x_unit``), ``tau``
+      (in ``x_unit``), ``offset``, ``phase_rad``.
+    """
+    try:
+        x_, y_ = _prep(x, y)
+    except ValueError as exc:
+        return FitResult.failed("rabi", "damped_sine", str(exc))
+
+    try:
+        amp_seed = 0.5 * (y_.max() - y_.min())
+        off_seed = 0.5 * (y_.max() + y_.min())
+        freq_seed = _dominant_frequency(x_, y_)
+        tau_seed = max(float(x_.max() - x_.min()), 1e-9)
+        p0 = [amp_seed, freq_seed, tau_seed, off_seed, 0.0]
+        bounds = (
+            [0.0, 0.0, 1e-12, -np.inf, -2 * np.pi],
+            [np.inf, np.inf, np.inf, np.inf, 2 * np.pi],
+        )
+        popt, _ = _curve_fit(_rabi_model, x_, y_, p0=p0, bounds=bounds)
+        y_hat = _rabi_model(x_, *popt)
+        return FitResult(
+            experiment="rabi",
+            model="damped_sine",
+            params={
+                "amplitude": float(popt[0]),
+                f"freq_per_{x_unit}": float(popt[1]),
+                f"tau_{x_unit}": float(popt[2]),
+                "offset": float(popt[3]),
+                "phase_rad": float(popt[4]),
+            },
+            fit_quality=_r_squared(y_, y_hat),
+            residual_rms=float(np.sqrt(np.mean((y_ - y_hat) ** 2))),
+            n_points=int(y_.size),
+        )
+    except Exception as exc:  # noqa: BLE001
+        return FitResult.failed("rabi", "damped_sine", f"{type(exc).__name__}: {exc}")
+
+
+# ---------------------------------------------------------------------------
+# Ramsey — damped cosine with phase
+# ---------------------------------------------------------------------------
+
+def _ramsey_model(t, A, freq, tau, offset, phase):
+    return A * np.exp(-t / tau) * np.cos(2 * np.pi * freq * t + phase) + offset
+
+
+def fit_ramsey(
+    y: np.ndarray,
+    x: Optional[np.ndarray] = None,
+    x_unit: str = "us",
+) -> FitResult:
+    """Fit a Ramsey fringe: A·exp(-t/τ)·cos(2π·δf·t + φ) + c.
+
+    ``freq`` here is the detuning between drive and qubit frequency in
+    cycles per ``x_unit``.
+    """
+    try:
+        x_, y_ = _prep(x, y)
+    except ValueError as exc:
+        return FitResult.failed("ramsey", "damped_cosine", str(exc))
+
+    try:
+        amp_seed = 0.5 * (y_.max() - y_.min())
+        off_seed = 0.5 * (y_.max() + y_.min())
+        freq_seed = max(_dominant_frequency(x_, y_), 1e-6)
+        tau_seed = max(float(x_.max() - x_.min()), 1e-9)
+        p0 = [amp_seed, freq_seed, tau_seed, off_seed, 0.0]
+        bounds = (
+            [0.0, 0.0, 1e-12, -np.inf, -2 * np.pi],
+            [np.inf, np.inf, np.inf, np.inf, 2 * np.pi],
+        )
+        popt, _ = _curve_fit(_ramsey_model, x_, y_, p0=p0, bounds=bounds)
+        y_hat = _ramsey_model(x_, *popt)
+        return FitResult(
+            experiment="ramsey",
+            model="damped_cosine",
+            params={
+                "amplitude": float(popt[0]),
+                f"detuning_per_{x_unit}": float(popt[1]),
+                f"t2star_{x_unit}": float(popt[2]),
+                "offset": float(popt[3]),
+                "phase_rad": float(popt[4]),
+            },
+            fit_quality=_r_squared(y_, y_hat),
+            residual_rms=float(np.sqrt(np.mean((y_ - y_hat) ** 2))),
+            n_points=int(y_.size),
+        )
+    except Exception as exc:  # noqa: BLE001
+        return FitResult.failed("ramsey", "damped_cosine", f"{type(exc).__name__}: {exc}")
+
+
+# ---------------------------------------------------------------------------
+# T1 / T2 — exponential decay
+# ---------------------------------------------------------------------------
+
+def _exp_decay(t, A, tau, offset):
+    return A * np.exp(-t / tau) + offset
+
+
+def fit_t1(
+    y: np.ndarray,
+    x: Optional[np.ndarray] = None,
+    x_unit: str = "us",
+) -> FitResult:
+    """Fit T1 relaxation: A·exp(-t/τ) + c."""
+    try:
+        x_, y_ = _prep(x, y)
+    except ValueError as exc:
+        return FitResult.failed("t1", "exp_decay", str(exc))
+    return _fit_exp_decay(x_, y_, experiment="t1", x_unit=x_unit)
+
+
+def fit_t2_echo(
+    y: np.ndarray,
+    x: Optional[np.ndarray] = None,
+    x_unit: str = "us",
+) -> FitResult:
+    """Fit T2 (echo / Hahn) decay: A·exp(-t/τ) + c."""
+    try:
+        x_, y_ = _prep(x, y)
+    except ValueError as exc:
+        return FitResult.failed("t2_echo", "exp_decay", str(exc))
+    return _fit_exp_decay(x_, y_, experiment="t2_echo", x_unit=x_unit)
+
+
+def _fit_exp_decay(
+    x: np.ndarray, y: np.ndarray, experiment: str, x_unit: str
+) -> FitResult:
+    try:
+        sign = 1.0 if y[0] > y[-1] else -1.0
+        amp_seed = sign * (y[0] - y[-1])
+        off_seed = float(y[-1])
+        tau_seed = max(float(x.max() - x.min()) / 3.0, 1e-9)
+        p0 = [amp_seed, tau_seed, off_seed]
+        # tau must be positive; offset unconstrained; amplitude signed
+        bounds = (
+            [-np.inf, 1e-12, -np.inf],
+            [np.inf, np.inf, np.inf],
+        )
+        popt, _ = _curve_fit(_exp_decay, x, y, p0=p0, bounds=bounds)
+        y_hat = _exp_decay(x, *popt)
+        return FitResult(
+            experiment=experiment,
+            model="exp_decay",
+            params={
+                "amplitude": float(popt[0]),
+                f"tau_{x_unit}": float(popt[1]),
+                "offset": float(popt[2]),
+            },
+            fit_quality=_r_squared(y, y_hat),
+            residual_rms=float(np.sqrt(np.mean((y - y_hat) ** 2))),
+            n_points=int(y.size),
+        )
+    except Exception as exc:  # noqa: BLE001
+        return FitResult.failed(experiment, "exp_decay", f"{type(exc).__name__}: {exc}")
+
+
+# ---------------------------------------------------------------------------
+# Dispatch
+# ---------------------------------------------------------------------------
+
+_FIT_DISPATCH: dict[str, Callable[..., FitResult]] = {
+    "rabi": fit_rabi,
+    "ramsey": fit_ramsey,
+    "t1": fit_t1,
+    "t2": fit_t2_echo,
+    "t2_echo": fit_t2_echo,
+}
+
+
+def autofit(
+    experiment_type: str,
+    y: np.ndarray,
+    x: Optional[np.ndarray] = None,
+    **kwargs: Any,
+) -> Optional[FitResult]:
+    """Run the fit matching ``experiment_type``. Returns ``None`` if there
+    is no fitter registered for that experiment (e.g. 2D chevron data)."""
+    fn = _FIT_DISPATCH.get(experiment_type.lower())
+    if fn is None:
+        return None
+    return fn(y=y, x=x, **kwargs)
+
+
+def supported_experiments() -> list[str]:
+    """List experiment types that ``autofit`` can handle."""
+    return sorted(_FIT_DISPATCH.keys())