Ship qcal-copilot pip package (Phase 1)

Reshape the repo into a src/qcal pip package so real calibration engineers
can drop qcal into their workflow without cloning the HF Space. The existing
Gradio app and decoder stage keep working as-is.

* src/ layout + pyproject.toml with [ml], [decoder], [gui], [all] extras and
a `qcal = qcal.cli:app` console script.
* qcal.fit: scipy.optimize curve fits for Rabi (damped sine), Ramsey (damped
cosine w/ detuning), T1 / T2-echo (exp decay). All return a FitResult
dataclass with R^2; recover synthesized params with R^2≈1.0.
* qcal.data: from_array / from_npy / from_npz adapters. Render matplotlib
plots (line / heatmap / scatter) per experiment type, overlay the fit
curve, and wire numeric summaries + fit summaries into the VLM prompt.
* qcal.analyzer: new analyze_payload() convenience wrapper; AnalysisResult
now carries fit_params, fit, and source, and exposes _repr_markdown_.
* qcal.decoder: _repr_markdown_ on DecoderResult for Jupyter.
* qcal.config: TOML-backed config under ~/.config/qcal/config.toml (0600)
with env-var precedence (NVIDIA_API_KEY / NIM_API_KEY).
* qcal.cli: Typer app — analyze, decode, generate, serve, login, logout,
config, version. Deferred imports keep `qcal --help` snappy. --no-fit
supports air-gapped installs without scipy.
* examples/: rabi, ramsey-drift, and readout-iq notebooks.
* requirements.txt: editable install (-e .[decoder,gui]) so the HF Space
picks up the src/ layout.

README.md

@@ -11,12 +11,18 @@ license: mit
 short_description: AI-assisted quantum calibration + CUDA-Q + Ising decoder
 ---
 
-# QCal Copilot — MVP
+# QCal Copilot
 
-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.
+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.
 
 ```
 ┌─────────┐   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
@@ -35,18 +41,76 @@ on the local `cudaq` simulator.
 
 ```
 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
@@ -191,9 +255,27 @@ sampler.
 | `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

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,16 +1,15 @@
-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
-# Decoder stage — MWPM on the denoised syndrome volume:
-pymatching>=2.2.0
-# CUDA-Q is installed separately (see README). Pin here if wheels are available:
-# cudaq>=0.8.0
+# HF Space / quick-start requirements. Installs qcal-copilot from this repo
+# in editable mode plus the extras the Gradio app needs.
+#
+# For a lighter install (CLI + NIM only, no local VLM weights), use:
+#   pip install .[decoder]
+-e .[decoder,gui]
+
+# Extras pulled in via the editable install above:
+#   numpy, pandas, matplotlib, pillow, requests, scipy, typer, platformdirs
+#   gradio (via [gui]), pymatching (via [decoder])
+#
+# Add [ml] to also install torch + transformers for local Ising VLM weights:
+#   -e .[ml,decoder,gui]
+#
+# CUDA-Q is installed separately (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()

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)}"
+    )

{qcal → src/qcal}/decoder.py

@@ -141,6 +141,9 @@ class DecoderResult:
         ]
         return "\n".join(lines)
 
+    def _repr_markdown_(self) -> str:  # Jupyter renders this directly
+        return self.markdown()
+
 
 # ---------------------------------------------------------------------------
 # Synthetic syndrome generation

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())