quantized-lab 0.8.0__py3-none-any.whl

quantized/routes/parsers.py

@@ -0,0 +1,281 @@
+"""Thin parser routes: import a file -> DataStruct JSON. No business logic.
+
+Two ways in: ``/import`` reads a path the server can already see (desktop / CLI
+use); ``/upload`` takes the file's bytes from the browser (the GUI file-picker
+and drag-drop). Both auto-detect format via ``io.import_auto``.
+"""
+
+from __future__ import annotations
+
+import os
+import struct
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, UploadFile
+from pydantic import BaseModel
+
+from quantized.datastruct import DataStruct
+from quantized.io import import_auto
+from quantized.io.origin_project import (
+    drop_empty_library_books,
+    drop_nonactionable_figures,
+    read_origin_project_all,
+)
+from quantized.io.origin_project.figures import extract_figures
+from quantized.io.origin_project.figures_opju import extract_figures_opju
+from quantized.io.origin_project.preview import decimate_datastruct
+from quantized.routes._bookcache import cache_project_books
+from quantized.routes._payload import datastruct_payload, jsonify
+from quantized.routes._uploadcache import stage_upload
+
+router = APIRouter(prefix="/api/parsers", tags=["parsers"])
+
+# Rows kept in a non-primary book's preview (Library sparkline resolution;
+# see io/origin_project/preview.decimate_datastruct).
+_PREVIEW_POINTS = 200
+
+
+class ImportRequest(BaseModel):
+    path: str
+    # Escape hatch (ORIGIN_FILE_DECODE_PLAN #38): request the pre-#38 full-
+    # inline "books": [payload, ...] shape instead of the lazy inventory. Used
+    # by tooling that reads every book's data immediately after import (e.g.
+    # tools/visual/origin_figures.mjs) and has no fetch-on-activate flow.
+    full_books: bool = False
+
+
+def _allowed_roots() -> tuple[str, ...]:
+    """Real (symlink-resolved) absolute paths ``/import`` may read from: the
+    user's home, the current working directory, and the system temp dir — widen
+    with the ``QZ_DATA_ROOTS`` env var (os.pathsep-separated)."""
+    raw = [Path.home(), Path.cwd(), Path(tempfile.gettempdir())]
+    raw += [Path(p) for p in os.environ.get("QZ_DATA_ROOTS", "").split(os.pathsep) if p.strip()]
+    roots: list[str] = []
+    for r in raw:
+        try:
+            roots.append(os.path.realpath(r))
+        except OSError:
+            continue
+    return tuple(roots)
+
+
+def _origin_book_id(ds: DataStruct) -> str:
+    return str(ds.metadata.get("origin_book", ""))
+
+
+def _slim_metadata(meta: Any) -> dict[str, Any]:
+    """Wire-payload metadata, minus ``origin_books`` — the full per-project
+    book inventory ``_build_book`` (io/origin_project/opj.py) embeds in
+    EVERY book's metadata. Grepped: nothing in routes/calc or the frontend
+    reads it back off the wire (``read_origin_books`` callers that DO use it
+    go through the pure Python API, untouched by this trim) — it duplicates
+    ~10-15 KB per book project-wide, which is material at PNR.opj's 122-book
+    scale (~1.4 MB of dead weight). Trimmed only here, at the HTTP boundary."""
+    return {k: v for k, v in dict(meta).items() if k != "origin_books"}
+
+
+def _book_payload(ds: DataStruct) -> dict[str, Any]:
+    """``datastruct_payload``, with ``_slim_metadata`` applied."""
+    payload = datastruct_payload(ds)
+    payload["metadata"] = _slim_metadata(payload["metadata"])
+    return payload
+
+
+def _book_primary_marker(ds: DataStruct) -> dict[str, Any]:
+    """The ``books[]`` entry for the book ALREADY returned in full at the
+    payload's top level — carries no ``time``/``values``/preview of its own
+    (nothing to duplicate): the frontend builds this book's Dataset from the
+    top-level payload instead of this entry. ``primary: true`` is its
+    discriminant (see ``_book_preview_payload``'s ``lazy: true`` sibling)."""
+    return {
+        "lazy": False,
+        "primary": True,
+        "id": _origin_book_id(ds),
+        "labels": list(ds.labels),
+        "units": list(ds.units),
+        "metadata": _slim_metadata(ds.metadata),
+        "rows": ds.n_points,
+        "cols": ds.n_channels,
+    }
+
+
+def _book_preview_payload(ds: DataStruct) -> dict[str, Any]:
+    """A non-primary book's lightweight inventory entry: real labels/units/
+    metadata (so the Library folder tree, tags, and book name all resolve
+    immediately) plus a downsampled preview time/values series (so a Library
+    sparkline renders without the full column data) — never the full
+    ``.time``/``.values``. ``lazy: true`` is the frontend's discriminant
+    between this shape and a full/primary entry."""
+    preview = decimate_datastruct(ds, target_points=_PREVIEW_POINTS)
+    return {
+        "lazy": True,
+        "id": _origin_book_id(ds),
+        "labels": list(ds.labels),
+        "units": list(ds.units),
+        "metadata": _slim_metadata(ds.metadata),
+        "rows": ds.n_points,
+        "cols": ds.n_channels,
+        # Just time/values (not a full datastruct_payload): labels/units/
+        # metadata above already describe this book, so nesting a second
+        # copy of them under `preview` would double the very weight this
+        # entry exists to avoid.
+        "preview": {"time": jsonify(preview.time), "values": jsonify(preview.values)},
+    }
+
+
+def _book_source_ref(path: Path, upload_token: str | None) -> dict[str, str]:
+    """A stable reference the frontend echoes back to ``/api/parsers/books/data``
+    to fetch one lazy book's full data later: an upload token when this import
+    came from ``/upload`` (its bytes are staged, not at a caller-visible path),
+    else the resolved path ``/import`` already validated."""
+    if upload_token is not None:
+        return {"kind": "upload", "token": upload_token}
+    return {"kind": "path", "path": str(path)}
+
+
+def _import_with_books(
+    path: Path, *, full_books: bool = False, upload_token: str | None = None
+) -> dict[str, Any]:
+    """Single-DataStruct payload; Origin projects also carry every workbook.
+
+    A multi-book project adds ``"books": [...]`` so the Library still lists
+    every workbook immediately (the locked import-all UX) — but, per
+    ORIGIN_FILE_DECODE_PLAN #38, the PRIMARY book (the one this function also
+    returns in full at the top level) gets a no-data MARKER entry
+    (``_book_primary_marker`` — nothing to duplicate), and every OTHER entry
+    is a lightweight inventory + downsampled preview (``_book_preview_payload``,
+    never the full ``.time``/``.values``); ``"book_source"`` is the reference
+    a later ``/api/parsers/books/data`` call uses to fetch one book's full
+    data on its first activation in the UI. Importing PNR.opj (122 books,
+    8.5M cells) this way shrinks the response from ~85 MB to ~2 MB (profiled
+    2026-07-09 perf-quick-wins follow-up). Pass ``full_books=True`` (the
+    pre-#38 behaviour, byte-for-byte: every book inline, no markers/preview)
+    to get every book's data inline instead — used by tooling with no
+    fetch-on-activate flow (see ``ImportRequest.full_books``'s docstring);
+    other formats are untouched either way.
+
+    Origin projects (``.opj``/``.opju``) are parsed ONCE via
+    ``read_origin_project_all``: the primary dataset and the full book list
+    used to come from two independent full-project parses (``import_auto`` ->
+    ``read_origin_project``, then a separate ``read_origin_books``), each
+    re-reading the file from disk and re-decoding every column; that
+    redundant parse dominated the ~4s round-trip on a 121.56 MB / 8.5M-cell
+    project (profiled 2026-07-09). The same already-read bytes are reused
+    below for the figures scan too, instead of a third disk read. When lazy,
+    the parsed book list is also handed to ``_bookcache`` so the common
+    "activate a book right after import" path never re-parses.
+    """
+    suffix = path.suffix.lower()
+    if suffix in (".opj", ".opju"):
+        raw = path.read_bytes()
+        ds, all_books = read_origin_project_all(path, raw=raw)
+        books = drop_empty_library_books(all_books)
+        if full_books:
+            # Byte-for-byte the pre-#38 shape: every book inline, top level
+            # unchanged (no metadata slimming — tooling built against the old
+            # response, e.g. tools/visual/origin_figures.mjs, gets exactly
+            # what it always got).
+            payload = datastruct_payload(ds)
+            if len(books) > 1:
+                payload["books"] = [datastruct_payload(b) for b in books]
+        else:
+            payload = _book_payload(ds)
+            if len(books) > 1:
+                primary_id = _origin_book_id(ds)
+                payload["books"] = [
+                    _book_primary_marker(b)
+                    if _origin_book_id(b) == primary_id
+                    else _book_preview_payload(b)
+                    for b in books
+                ]
+                payload["book_source"] = _book_source_ref(path, upload_token)
+                cache_project_books(path, books)
+        try:
+            if suffix == ".opj":
+                figs = extract_figures(raw)
+            else:
+                # Gate out non-actionable layer anchors (internal storage/thumbnail
+                # blocks with no bound curves and no source) so the Library's Figures
+                # section shows only restorable graphs, not dead "SYSTEM" rows.
+                figs = drop_nonactionable_figures(extract_figures_opju(raw))
+        except (IndexError, ValueError, KeyError, struct.error):
+            # Figures are an optional nicety; a decode hiccup on a malformed or
+            # truncated project must degrade to "no figures", never fail the
+            # whole import (the data books already succeeded above).
+            figs = []
+        if figs:
+            payload["figures"] = figs
+        return payload
+
+    ds = import_auto(path)
+    return datastruct_payload(ds)
+
+
+@router.post("/import")
+def import_file(req: ImportRequest) -> dict[str, Any]:
+    """Auto-detect format and import a local file path into a DataStruct.
+
+    ``/import`` reads a path the server can already see (local desktop / CLI
+    use). The path is ``os.path.realpath``-normalized (collapsing ``..`` and
+    symlinks) and confined to an allowed root (home / cwd / temp, widen via
+    ``QZ_DATA_ROOTS``) via ``os.path.commonpath`` before any filesystem access,
+    so the localhost API cannot be used to read system files (e.g.
+    ``/etc/passwd``) through path traversal.
+    """
+    try:
+        resolved = os.path.realpath(req.path)
+    except (OSError, ValueError) as exc:
+        raise HTTPException(status_code=400, detail="invalid path") from exc
+    # Inline containment guard (kept in this function so the static analyzer can
+    # see the path-traversal barrier sits between the taint and the sink).
+    within_allowed = False
+    for root in _allowed_roots():
+        try:
+            if os.path.commonpath((root, resolved)) == root:
+                within_allowed = True
+                break
+        except ValueError:
+            continue  # different drives (Windows) -> not under this root
+    if not within_allowed:
+        raise HTTPException(
+            status_code=403,
+            detail="path is outside the allowed roots (set QZ_DATA_ROOTS to widen)",
+        )
+    if not os.path.isfile(resolved):
+        raise HTTPException(status_code=404, detail=f"file not found: {req.path}")
+    try:
+        return _import_with_books(Path(resolved), full_books=req.full_books)
+    except (ValueError, KeyError, OSError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+@router.post("/upload")
+async def upload_file(file: UploadFile, full_books: bool = False) -> dict[str, Any]:
+    """Import an uploaded data file (browser file-picker / drag-drop).
+
+    The bytes are staged under the original *basename* (so the extension
+    still drives format dispatch, and ``..`` path parts can't escape). An
+    Origin project (``.opj``/``.opju``) is staged PERSISTENTLY (bounded LRU,
+    see ``_uploadcache``) instead of in an ephemeral temp dir, because a lazy
+    multi-book import (#38, the default — pass ``?full_books=true`` for the
+    old inline-everything behaviour) needs the bytes to still be around when
+    the browser later activates a non-primary book and fetches its full data
+    (``/api/parsers/books/data``). Every other upload keeps the ephemeral
+    temp dir: it's deleted before this handler returns, since nothing needs
+    it afterwards.
+    """
+    name = Path(file.filename or "upload.dat").name or "upload.dat"
+    content = await file.read()
+    suffix = Path(name).suffix.lower()
+    try:
+        if suffix in (".opj", ".opju"):
+            dest, token = stage_upload(name, content)
+            return _import_with_books(dest, full_books=full_books, upload_token=token)
+        with tempfile.TemporaryDirectory() as tmp:
+            dest = Path(tmp) / name
+            dest.write_bytes(content)
+            return _import_with_books(dest, full_books=full_books)
+    except (ValueError, KeyError, OSError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc

quantized/routes/peaks.py

@@ -0,0 +1,184 @@
+"""Thin peak routes. ``/find`` wraps ``calc.peaks.find_peaks_robust`` (golden vs
+MATLAB findPeaksRobust); ``/fit`` wraps ``calc.peak_fit.fit_single_peak`` (golden
+vs fitSinglePeak); ``/fit-multi`` wraps ``calc.peak_multifit.fit_multi_peak``
+(golden vs peakAnalysis.onFitSimultaneous). Validate -> call -> serialize; no
+business logic here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from quantized.calc.peak_batch import batch_integrate_peaks
+from quantized.calc.peak_fit import MODELS, fit_single_peak
+from quantized.calc.peak_integrate import integrate_peaks
+from quantized.calc.peak_multifit import fit_multi_peak
+from quantized.calc.peaks import find_peaks_robust
+from quantized.routes._payload import jsonify, to_jsonable
+
+# Models accepted by the simultaneous fit (compositeEval branches).
+MULTI_MODELS = ("Lorentzian", "Gaussian", "Pseudo-Voigt", "Split Pearson VII", "TCH-pV")
+LINK_MODES = ("None", "Shared FWHM", "Shared FWHM + eta")
+
+router = APIRouter(prefix="/api/peaks", tags=["peaks"])
+
+
+class FindPeaksRequest(BaseModel):
+    x: list[float]
+    y: list[float]
+    snr_threshold: float = 5.0
+    min_separation: float = 0.0
+    max_peaks: int = 50
+    max_window_deg: float = 2.0
+    min_width_deg: float = 0.01
+    max_width_deg: float = 10.0
+    min_prominence: float = 0.02
+    sensitivity: str = "medium"
+
+
+@router.post("/find")
+def find(req: FindPeaksRequest) -> dict[str, Any]:
+    """Find peaks in (x, y); returns the peak list + the estimated background."""
+    try:
+        peaks, background = find_peaks_robust(
+            req.x,
+            req.y,
+            snr_threshold=req.snr_threshold,
+            min_separation=req.min_separation,
+            max_peaks=req.max_peaks,
+            max_window_deg=req.max_window_deg,
+            min_width_deg=req.min_width_deg,
+            max_width_deg=req.max_width_deg,
+            min_prominence=req.min_prominence,
+            sensitivity=req.sensitivity,
+        )
+    except (ValueError, IndexError, KeyError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    return {"peaks": to_jsonable(peaks), "background": jsonify(background)}
+
+
+class FitPeakRequest(BaseModel):
+    x: list[float]
+    y: list[float]
+    x_lo: float
+    x_hi: float
+    seed_center: float
+    seed_fwhm: float | None = None
+    model: str = "Lorentzian"
+    snip_bg: list[float] | None = None
+
+
+@router.post("/fit")
+def fit(req: FitPeakRequest) -> dict[str, Any]:
+    """Fit one peak in [x_lo, x_hi] to ``model``; returns the fit result dict."""
+    if req.model not in MODELS:
+        raise HTTPException(status_code=422, detail=f"unknown model: {req.model}")
+    try:
+        result = fit_single_peak(
+            req.x, req.y, req.x_lo, req.x_hi,
+            seed_center=req.seed_center,
+            seed_fwhm=float("nan") if req.seed_fwhm is None else req.seed_fwhm,
+            model=req.model,
+            snip_bg=req.snip_bg,
+        )
+    except (ValueError, IndexError, KeyError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    out: dict[str, Any] = to_jsonable(result)
+    return out
+
+
+class PeakSeed(BaseModel):
+    center: float
+    fwhm: float
+    height: float
+    eta: float | None = None
+
+
+class FitMultiPeakRequest(BaseModel):
+    x: list[float]
+    y: list[float]
+    peaks: list[PeakSeed]
+    model: str = "Lorentzian"
+    bg_degree: int = 1
+    constrain: bool = False
+    link_mode: str = "None"
+
+
+@router.post("/fit-multi")
+def fit_multi(req: FitMultiPeakRequest) -> dict[str, Any]:
+    """Fit all ``peaks`` + a polynomial background simultaneously; returns the
+    global-fit result (fitted peaks, bg coeffs, R2/rmse)."""
+    if req.model not in MULTI_MODELS:
+        raise HTTPException(status_code=422, detail=f"unknown model: {req.model}")
+    if req.link_mode not in LINK_MODES:
+        raise HTTPException(status_code=422, detail=f"unknown link_mode: {req.link_mode}")
+    if not req.peaks:
+        raise HTTPException(status_code=422, detail="need at least one peak seed")
+    seeds = [p.model_dump(exclude_none=True) for p in req.peaks]
+    try:
+        result = fit_multi_peak(
+            req.x, req.y, seeds,
+            model=req.model, bg_degree=req.bg_degree,
+            constrain=req.constrain, link_mode=req.link_mode,
+        )
+    except (ValueError, IndexError, KeyError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+    out: dict[str, Any] = to_jsonable(result)
+    return out
+
+
+class IntegrateRequest(BaseModel):
+    x: list[float]
+    y: list[float]
+    regions: list[tuple[float, float]]
+    baseline: str = "linear"
+
+
+@router.post("/integrate")
+def integrate(req: IntegrateRequest) -> dict[str, Any]:
+    """Integrate-only peak analysis: area/centroid/FWHM/%-area per region."""
+    try:
+        return to_jsonable(  # type: ignore[no-any-return]
+            integrate_peaks(
+                np.asarray(req.x, dtype=float),
+                np.asarray(req.y, dtype=float),
+                [(float(a), float(b)) for a, b in req.regions],
+                baseline=req.baseline,
+            )
+        )
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+class BatchIntegrateRequest(BaseModel):
+    x: list[float]
+    spectra: list[list[float]]  # each same length as x
+    regions: list[tuple[float, float]]
+    baseline: str = "linear"
+    align: bool = False
+    reference: int = 0
+    labels: list[str] | None = None
+
+
+@router.post("/integrate-batch")
+def integrate_batch(req: BatchIntegrateRequest) -> dict[str, Any]:
+    """Integrate fixed regions across a spectra series (optional alignment).
+
+    Returns per-spectrum results + area/centroid/FWHM matrices for trend
+    plotting; a failing spectrum is flagged, not fatal."""
+    try:
+        return to_jsonable(  # type: ignore[no-any-return]
+            batch_integrate_peaks(
+                np.asarray(req.x, dtype=float),
+                [np.asarray(s, dtype=float) for s in req.spectra],
+                [(float(a), float(b)) for a, b in req.regions],
+                baseline=req.baseline, align=req.align,
+                reference=req.reference, labels=req.labels,
+            )
+        )
+    except (ValueError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc

quantized/routes/plot.py

@@ -0,0 +1,103 @@
+"""Thin plot route: DataStruct + selection -> uPlot column-oriented payload."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from quantized.calc.map import MapState, map_from_datastruct
+from quantized.calc.plotting import PlotState, build_series
+from quantized.datastruct import DataStruct
+from quantized.routes._payload import jsonify, to_jsonable
+
+router = APIRouter(prefix="/api/plot", tags=["plot"])
+
+
+class PlotRequest(BaseModel):
+    dataset: dict[str, Any]
+    x_key: int | str | None = None
+    y_keys: list[int | str] | None = None
+    y2_keys: list[int | str] | None = None
+    x_log: bool = False
+    y_log: bool = False
+
+
+@router.post("/series")
+def plot_series(req: PlotRequest) -> dict[str, Any]:
+    """Build uPlot-ready series from a posted DataStruct."""
+    try:
+        ds = DataStruct.from_dict(req.dataset)
+        state = PlotState(
+            x_key=req.x_key,
+            y_keys=tuple(req.y_keys) if req.y_keys is not None else None,
+            y2_keys=tuple(req.y2_keys) if req.y2_keys is not None else None,
+            x_log=req.x_log,
+            y_log=req.y_log,
+        )
+        plot = build_series(ds, state)
+    except (ValueError, KeyError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+    # uPlot wants column-oriented data: [xValues, series1Values, series2Values, ...]
+    data = [jsonify(plot.x)] + [jsonify(s.values) for s in plot.series]
+    return {
+        "data": data,
+        "series": [{"label": s.label, "unit": s.unit, "axis": s.axis} for s in plot.series],
+        "x": {"label": plot.x_label, "unit": plot.x_unit, "log": plot.x_log},
+        "y": {"log": plot.y_log},
+    }
+
+
+class MapRequest(BaseModel):
+    """Three channels of a (scattered) dataset -> a regular 2-D grid for heatmap."""
+
+    dataset: dict[str, Any]
+    x_key: int | str
+    y_key: int | str
+    z_key: int | str
+    method: str = "natural"
+    nx: int = Field(default=200, ge=2, le=2000)
+    ny: int = Field(default=200, ge=2, le=2000)
+    xlim: tuple[float, float] | None = None
+    ylim: tuple[float, float] | None = None
+    extrapolation: str = "none"
+    smoothing: float = 0.0
+    idw_power: float = 2.0
+
+
+@router.post("/map")
+def plot_map(req: MapRequest) -> dict[str, Any]:
+    """Regrid scattered (x, y, z) channels into a Canvas2D-ready heatmap grid."""
+    try:
+        ds = DataStruct.from_dict(req.dataset)
+        state = MapState(
+            method=req.method,
+            nx=req.nx,
+            ny=req.ny,
+            xlim=req.xlim,
+            ylim=req.ylim,
+            extrapolation=req.extrapolation,
+            smoothing=req.smoothing,
+            idw_power=req.idw_power,
+        )
+        m = map_from_datastruct(ds, req.x_key, req.y_key, req.z_key, state)
+    except (ValueError, KeyError, IndexError) as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+    # x_axis/y_axis are regular (finite by construction); z_grid has NaN gaps
+    # outside the convex hull -> jsonify maps those to null (a heatmap gap).
+    return {
+        "x_axis": jsonify(m.x_axis),
+        "y_axis": jsonify(m.y_axis),
+        "z_grid": jsonify(m.z_grid),
+        "x": {"label": m.x_label, "unit": m.x_unit},
+        "y": {"label": m.y_label, "unit": m.y_unit},
+        "z": {
+            "label": m.z_label,
+            "unit": m.z_unit,
+            "min": to_jsonable(m.z_min),
+            "max": to_jsonable(m.z_max),
+        },
+    }

quantized/routes/reductions.py

@@ -0,0 +1,121 @@
+"""Thin reductions route. Wraps ``calc.reductions`` (PORT_PLAN #19).
+
+Williamson-Hall size/strain separation, FFT film thickness (Laue fringes),
+reflectivity FFT (Kiessig fringes + superlattice analysis), and neutron
+spin asymmetry. All math lives in calc; this only validates + serializes.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+from quantized.calc.reductions import (
+    fft_thickness,
+    reflectivity_fft,
+    spin_asymmetry,
+    williamson_hall,
+)
+
+router = APIRouter(prefix="/api/reductions", tags=["reductions"])
+
+
+class WilliamsonHallRequest(BaseModel):
+    two_theta_deg: list[float]
+    fwhm_deg: list[float]
+    wavelength_a: float = 1.5406
+    k_factor: float = 0.9
+    instrumental_broadening_deg: float = 0.0
+
+
+@router.post("/williamson-hall")
+def williamson_hall_route(req: WilliamsonHallRequest) -> dict[str, Any]:
+    """Crystallite size + microstrain from XRD peak positions and widths."""
+    try:
+        return williamson_hall(
+            req.two_theta_deg,
+            req.fwhm_deg,
+            wavelength_a=req.wavelength_a,
+            k_factor=req.k_factor,
+            instrumental_broadening_deg=req.instrumental_broadening_deg,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+class FFTThicknessRequest(BaseModel):
+    two_theta_deg: list[float]
+    intensity: list[float]
+    wavelength_a: float
+    two_theta_min: float | None = None
+    two_theta_max: float | None = None
+    window: str = "hann"
+    max_thickness_nm: float = 200.0
+
+
+@router.post("/fft-thickness")
+def fft_thickness_route(req: FFTThicknessRequest) -> dict[str, Any]:
+    """Film thickness from Laue-fringe periodicity (XRD FFT)."""
+    try:
+        return fft_thickness(
+            req.two_theta_deg,
+            req.intensity,
+            req.wavelength_a,
+            two_theta_min=req.two_theta_min,
+            two_theta_max=req.two_theta_max,
+            window=req.window,
+            max_thickness_nm=req.max_thickness_nm,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+class ReflectivityFFTRequest(BaseModel):
+    x: list[float]
+    reflectivity: list[float]
+    is_neutron: bool = False
+    wavelength_a: float | None = None
+    x_min: float | None = None
+    x_max: float | None = None
+    window: str = "hann"
+    preprocess: str = "logR"
+    max_thickness_nm: float = 500.0
+    peak_prominence_threshold: float = 0.05
+
+
+@router.post("/reflectivity-fft")
+def reflectivity_fft_route(req: ReflectivityFFTRequest) -> dict[str, Any]:
+    """Kiessig-fringe FFT thickness(es) + superlattice analysis."""
+    try:
+        return reflectivity_fft(
+            req.x,
+            req.reflectivity,
+            is_neutron=req.is_neutron,
+            wavelength_a=req.wavelength_a,
+            x_min=req.x_min,
+            x_max=req.x_max,
+            window=req.window,
+            preprocess=req.preprocess,
+            max_thickness_nm=req.max_thickness_nm,
+            peak_prominence_threshold=req.peak_prominence_threshold,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc
+
+
+class SpinAsymmetryRequest(BaseModel):
+    r_pp: list[float]
+    r_mm: list[float]
+    dr_pp: list[float] | None = None
+    dr_mm: list[float] | None = None
+
+
+@router.post("/spin-asymmetry")
+def spin_asymmetry_route(req: SpinAsymmetryRequest) -> dict[str, Any]:
+    """Neutron spin asymmetry (R++ - R--)/(R++ + R--) with propagated error."""
+    try:
+        return spin_asymmetry(req.r_pp, req.r_mm, req.dr_pp, req.dr_mm)
+    except ValueError as exc:
+        raise HTTPException(status_code=422, detail=str(exc)) from exc