rr-app 1.5.0__py3-none-any.whl

rr_app/__init__.py

@@ -0,0 +1,36 @@
+"""RR App PyQt6 application (clean rewrite).
+
+Run with:
+    python -m rr_app
+"""
+
+from __future__ import annotations
+
+import sys
+
+__all__ = ["__version__"]
+
+# Safety: never write __pycache__/bytecode into the checked-out repo / installed package.
+# This avoids "accidental updates" to a git checkout when running `rr` or `python -m rr_app`.
+sys.dont_write_bytecode = True
+
+__version__ = "1.5.0"
+
+"""
+ v1.4.0:
+   - Added Signals preset profile (save/load)
+   - Updated Settings prompt button grid
+
+ v1.4.1:
+   - Added mutlilingual translation selector support
+
+ v1.4.3:
+   - Fixed data recording CSV format
+
+ v1.4.9:
+   - Can read new CPM telemetry (for remaining time)
+
+ v1.5.0:
+   - Fixed CPM target_deg to _rad; refactored the rr_app
+
+"""

rr_app/__main__.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+
+if __name__ == "__main__":
+    try:
+        from .cli import main
+    except ImportError:
+        from rr_app.cli import main
+
+    raise SystemExit(main())
+

rr_app/analysis/__init__.py

@@ -0,0 +1,9 @@
+"""Signal processing and modeling utilities (offline).
+
+This package is intentionally GUI-agnostic so it can be used for:
+- offline feature extraction / training
+- lightweight runtime inference (optional)
+"""
+
+from __future__ import annotations
+

rr_app/analysis/emg_features.py

@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Iterable, Iterator
+
+import numpy as np
+
+
+def _require_scipy() -> "object":
+    try:
+        import scipy.signal  # type: ignore
+    except ModuleNotFoundError as e:  # pragma: no cover
+        raise ModuleNotFoundError(
+            "scipy is required for EMG filtering/PSD. Install with: pip install -r requirements.txt"
+        ) from e
+    return scipy.signal
+
+
+@dataclass(frozen=True, slots=True)
+class EmgPreprocessConfig:
+    fs_hz: float = 1000.0
+    bandpass_hz: tuple[float, float] | None = (20.0, 450.0)
+    notch_hz: float | None = None  # e.g. 50 or 60
+    notch_q: float = 30.0
+    detrend: bool = True
+
+
+def preprocess_emg(x: np.ndarray, cfg: EmgPreprocessConfig) -> np.ndarray:
+    """Basic EMG preprocessing (typical surface EMG defaults).
+
+    Notes:
+    - Keep this conservative: the goal is repeatable features, not maximal denoising.
+    - If you already have a clean pipeline, you can skip this and only use feature extraction.
+    """
+    scipy_signal = _require_scipy()
+
+    x = np.asarray(x, dtype=float).copy()
+    if x.ndim != 1:
+        raise ValueError(f"preprocess_emg expects 1D signal, got shape={x.shape}")
+
+    if cfg.detrend:
+        x = x - float(np.mean(x))
+
+    fs = float(cfg.fs_hz)
+
+    if cfg.notch_hz is not None:
+        w0 = float(cfg.notch_hz) / (fs / 2.0)
+        if 0.0 < w0 < 1.0:
+            b, a = scipy_signal.iirnotch(w0=w0, Q=float(cfg.notch_q))
+            x = scipy_signal.filtfilt(b, a, x, method="pad")
+
+    if cfg.bandpass_hz is not None:
+        lo, hi = cfg.bandpass_hz
+        lo = float(lo)
+        hi = float(hi)
+        if lo <= 0.0 or hi <= 0.0 or hi <= lo:
+            raise ValueError(f"Invalid bandpass_hz={cfg.bandpass_hz}")
+        wn = (lo / (fs / 2.0), hi / (fs / 2.0))
+        b, a = scipy_signal.butter(4, wn, btype="bandpass")
+        x = scipy_signal.filtfilt(b, a, x, method="pad")
+
+    return x
+
+
+@dataclass(frozen=True, slots=True)
+class WindowConfig:
+    fs_hz: float = 1000.0
+    window_s: float = 0.250
+    hop_s: float = 0.050
+
+    def window_n(self) -> int:
+        return max(8, int(round(float(self.window_s) * float(self.fs_hz))))
+
+    def hop_n(self) -> int:
+        return max(1, int(round(float(self.hop_s) * float(self.fs_hz))))
+
+
+def iterate_windows(x: np.ndarray, cfg: WindowConfig) -> Iterator[tuple[int, int, np.ndarray]]:
+    """Yield (start_idx, end_idx, window_signal)."""
+    x = np.asarray(x, dtype=float)
+    if x.ndim != 1:
+        raise ValueError(f"iterate_windows expects 1D signal, got shape={x.shape}")
+
+    n = int(x.size)
+    w = int(cfg.window_n())
+    hop = int(cfg.hop_n())
+    if n < w:
+        return
+    for start in range(0, n - w + 1, hop):
+        end = start + w
+        yield start, end, x[start:end]
+
+
+def _zc(x: np.ndarray, *, threshold: float = 0.0) -> float:
+    """Zero crossings count with dead-zone threshold."""
+    x = np.asarray(x, dtype=float)
+    if x.size < 2:
+        return 0.0
+    # Apply dead-zone
+    x1 = np.where(np.abs(x) < float(threshold), 0.0, x)
+    s = np.sign(x1)
+    return float(np.sum((s[1:] * s[:-1]) < 0))
+
+
+def _wamp(x: np.ndarray, *, threshold: float) -> float:
+    """Willison amplitude: count of |x[n]-x[n-1]| >= threshold."""
+    x = np.asarray(x, dtype=float)
+    if x.size < 2:
+        return 0.0
+    d = np.abs(np.diff(x))
+    return float(np.sum(d >= float(threshold)))
+
+
+def _waveform_length(x: np.ndarray) -> float:
+    x = np.asarray(x, dtype=float)
+    if x.size < 2:
+        return 0.0
+    return float(np.sum(np.abs(np.diff(x))))
+
+
+@dataclass(frozen=True, slots=True)
+class WelchConfig:
+    fs_hz: float = 1000.0
+    nperseg: int = 256
+    noverlap: int = 128
+    window: str = "hann"
+
+
+def welch_psd(x: np.ndarray, cfg: WelchConfig) -> tuple[np.ndarray, np.ndarray]:
+    """Welch PSD estimate (nonnegative) in units of power/Hz."""
+    scipy_signal = _require_scipy()
+    x = np.asarray(x, dtype=float)
+    if x.ndim != 1:
+        raise ValueError(f"welch_psd expects 1D signal, got shape={x.shape}")
+    f, pxx = scipy_signal.welch(
+        x,
+        fs=float(cfg.fs_hz),
+        window=str(cfg.window),
+        nperseg=int(cfg.nperseg),
+        noverlap=int(cfg.noverlap),
+        detrend=False,
+        scaling="density",
+        return_onesided=True,
+    )
+    return np.asarray(f, dtype=float), np.asarray(pxx, dtype=float)
+
+
+def spectral_features_from_psd(f_hz: np.ndarray, pxx: np.ndarray) -> dict[str, float]:
+    """Compute common fatigue-related spectral features from a PSD."""
+    f = np.asarray(f_hz, dtype=float)
+    p = np.asarray(pxx, dtype=float)
+    if f.size == 0 or p.size == 0 or f.size != p.size:
+        return {"mnf_hz": 0.0, "mdf_hz": 0.0, "tot_power": 0.0}
+
+    # Drop DC for fatigue features (EMG often has DC/artifact content).
+    if f.size > 1:
+        f = f[1:]
+        p = p[1:]
+
+    p = np.maximum(p, 0.0)
+    tot = float(np.trapezoid(p, f))
+    if not math.isfinite(tot) or tot <= 0.0:
+        return {"mnf_hz": 0.0, "mdf_hz": 0.0, "tot_power": 0.0}
+
+    # Mean frequency (MNF): first moment / total power.
+    mnf = float(np.trapezoid(f * p, f) / tot)
+
+    # Median frequency (MDF): frequency where cumulative power reaches 50%.
+    # Use cumulative trapezoid integration for robustness.
+    c = np.cumsum((p[1:] + p[:-1]) * (f[1:] - f[:-1]) * 0.5)
+    if c.size == 0:
+        mdf = float(f[0])
+    else:
+        idx = int(np.searchsorted(c, 0.5 * float(c[-1]), side="left"))
+        idx = max(0, min(idx, int(f.size - 2)))
+        mdf = float(f[idx + 1])
+
+    return {
+        "mnf_hz": float(mnf),
+        "mdf_hz": float(mdf),
+        "tot_power": float(tot),
+    }
+
+
+def bandpower(f_hz: np.ndarray, pxx: np.ndarray, band_hz: tuple[float, float]) -> float:
+    f = np.asarray(f_hz, dtype=float)
+    p = np.asarray(pxx, dtype=float)
+    lo, hi = float(band_hz[0]), float(band_hz[1])
+    if f.size == 0 or p.size == 0:
+        return 0.0
+    m = (f >= lo) & (f <= hi)
+    if not np.any(m):
+        return 0.0
+    return float(np.trapezoid(np.maximum(p[m], 0.0), f[m]))
+
+
+def time_features(x: np.ndarray, *, wamp_thresh: float | None = None, zc_thresh: float = 0.0) -> dict[str, float]:
+    x = np.asarray(x, dtype=float)
+    if x.size == 0:
+        return {"rms": 0.0, "iemg": 0.0, "wl": 0.0, "zc": 0.0, "wamp": 0.0}
+
+    rms = float(math.sqrt(max(0.0, float(np.mean(x * x)))))
+    iemg = float(np.sum(np.abs(x)))
+    wl = _waveform_length(x)
+    zc = _zc(x, threshold=float(zc_thresh))
+
+    if wamp_thresh is None:
+        # Common heuristic: threshold relative to signal scale (10% of RMS).
+        wamp_thresh = 0.1 * rms
+    wamp = _wamp(x, threshold=float(wamp_thresh))
+
+    return {"rms": rms, "iemg": iemg, "wl": wl, "zc": zc, "wamp": wamp}
+
+
+def extract_feature_rows(
+    x: np.ndarray,
+    *,
+    preprocess: EmgPreprocessConfig | None = None,
+    window: WindowConfig,
+    welch: WelchConfig | None = None,
+    bandpowers_hz: Iterable[tuple[str, tuple[float, float]]] = (("bp_20_60", (20.0, 60.0)), ("bp_60_150", (60.0, 150.0)), ("bp_150_300", (150.0, 300.0))),
+) -> tuple[np.ndarray, list[str], np.ndarray]:
+    """Return (X, feature_names, t_center_s) for a single recording.
+
+    X rows correspond to windows. t_center_s is window center time in seconds.
+    """
+    x_in = np.asarray(x, dtype=float)
+    if x_in.ndim != 1:
+        raise ValueError(f"extract_feature_rows expects 1D signal, got shape={x_in.shape}")
+
+    cfg_p = preprocess or EmgPreprocessConfig(fs_hz=float(window.fs_hz))
+    x0 = preprocess_emg(x_in, cfg_p) if preprocess is not None else x_in.astype(float)
+
+    cfg_welch = welch or WelchConfig(fs_hz=float(window.fs_hz), nperseg=min(256, window.window_n()), noverlap=min(128, max(0, window.window_n() // 2)))
+    names: list[str] = []
+    rows: list[list[float]] = []
+    t_centers: list[float] = []
+
+    for start, end, seg in iterate_windows(x0, window):
+        tf = time_features(seg)
+        f, pxx = welch_psd(seg, cfg_welch)
+        sf = spectral_features_from_psd(f, pxx)
+        bp: dict[str, float] = {name: bandpower(f, pxx, band) for name, band in bandpowers_hz}
+
+        feat: dict[str, float] = {}
+        feat.update(tf)
+        feat.update(sf)
+        feat.update(bp)
+
+        if not names:
+            names = list(feat.keys())
+        rows.append([float(feat[k]) for k in names])
+
+        t_center = (float(start) + float(end)) * 0.5 / float(window.fs_hz)
+        t_centers.append(float(t_center))
+
+    if not rows:
+        return np.zeros((0, 0), dtype=float), [], np.zeros((0,), dtype=float)
+    return np.asarray(rows, dtype=float), names, np.asarray(t_centers, dtype=float)
+

rr_app/analysis/fatigue_index.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass(frozen=True, slots=True)
+class FatigueIndexConfig:
+    """Unsupervised fatigue score configuration (no ground truth required)."""
+
+    baseline_s: float = 10.0  # use early windows as baseline
+    w_mdf: float = 0.7
+    w_rms: float = 0.3
+
+
+def _clip01(x: np.ndarray) -> np.ndarray:
+    return np.clip(np.asarray(x, dtype=float), 0.0, 1.0)
+
+
+def fatigue_index_unsupervised(
+    t_s: np.ndarray,
+    *,
+    rms: np.ndarray,
+    mdf_hz: np.ndarray,
+    cfg: FatigueIndexConfig = FatigueIndexConfig(),
+) -> tuple[np.ndarray, np.ndarray]:
+    """Compute (fatigue_score_0to1, confidence_0to1) from feature trends.
+
+    This is NOT a calibrated probability. It's a heuristic score that tends to increase when:
+    - MDF decreases (classic fatigue marker)
+    - RMS increases (often, but not always)
+    """
+    t = np.asarray(t_s, dtype=float).reshape(-1)
+    rms = np.asarray(rms, dtype=float).reshape(-1)
+    mdf = np.asarray(mdf_hz, dtype=float).reshape(-1)
+    n = int(min(t.size, rms.size, mdf.size))
+    if n <= 0:
+        return np.zeros((0,), dtype=float), np.zeros((0,), dtype=float)
+
+    t = t[:n]
+    rms = rms[:n]
+    mdf = mdf[:n]
+
+    # Baseline = early segment (by time).
+    t0 = float(np.min(t))
+    t1 = t0 + float(cfg.baseline_s)
+    base_mask = t <= t1
+    if not np.any(base_mask):
+        base_mask = np.arange(n) < max(1, n // 10)
+
+    mdf0 = float(np.nanmedian(mdf[base_mask]))
+    rms0 = float(np.nanmedian(rms[base_mask]))
+    if not math.isfinite(mdf0) or mdf0 <= 0:
+        mdf0 = float(np.nanmedian(mdf)) if np.nanmedian(mdf) > 0 else 1.0
+    if not math.isfinite(rms0) or rms0 <= 0:
+        rms0 = float(np.nanmedian(rms)) if np.nanmedian(rms) > 0 else 1.0
+
+    # Components
+    mdf_drop = _clip01((mdf0 - mdf) / (mdf0 + 1e-9))
+    rms_rise = _clip01((rms - rms0) / (rms0 + 1e-9))
+    score = _clip01(float(cfg.w_mdf) * mdf_drop + float(cfg.w_rms) * rms_rise)
+
+    # Confidence heuristic: higher when MDF trend is consistently decreasing.
+    conf = np.zeros_like(score, dtype=float)
+    try:
+        from scipy.stats import spearmanr  # type: ignore
+
+        # Trend over time: fatigue implies mdf decreases, so corr(t, -mdf) should be positive.
+        rho, _p = spearmanr(t, -mdf, nan_policy="omit")
+        rho = 0.0 if not math.isfinite(float(rho)) else float(rho)
+        # Map rho in [-1..1] to [0..1] with some floor.
+        trend_conf = _clip01((rho + 1.0) / 2.0)
+        conf = 0.2 + 0.8 * float(trend_conf)
+    except Exception:
+        # Fallback: use monotonicity of MDF (fraction of steps that go down).
+        if n >= 2:
+            down = float(np.mean(np.diff(mdf) < 0))
+            conf = 0.2 + 0.8 * float(_clip01(down))
+        else:
+            conf = np.ones_like(score, dtype=float) * 0.2
+
+    return score, _clip01(conf)
+

rr_app/analysis/fatigue_labels.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import numpy as np
+
+
+def _clip01(x: np.ndarray) -> np.ndarray:
+    return np.clip(np.asarray(x, dtype=float), 0.0, 1.0)
+
+
+def fatigue_score_from_time_to_failure(t_s: np.ndarray, *, t_fail_s: float, t_start_s: float | None = None) -> np.ndarray:
+    """Weak label: normalize time into a fatigue score in [0..1].
+
+    - 0.0 at t_start_s (default: min(t_s))
+    - 1.0 at t_fail_s
+    """
+    t = np.asarray(t_s, dtype=float)
+    if t.size == 0:
+        return np.zeros((0,), dtype=float)
+    tf = float(t_fail_s)
+    if not math.isfinite(tf) or tf <= 0:
+        raise ValueError(f"Invalid t_fail_s={t_fail_s}")
+    t0 = float(np.min(t)) if t_start_s is None else float(t_start_s)
+    denom = max(1e-9, tf - t0)
+    y = (t - t0) / denom
+    return _clip01(y)
+
+
+def fatigue_score_from_force(force: np.ndarray, *, baseline_force: float | None = None) -> np.ndarray:
+    """Weak label: map force drop into fatigue score in [0..1].
+
+    score(t) = (baseline - force(t)) / baseline, clipped to [0..1]
+    """
+    f = np.asarray(force, dtype=float)
+    if f.size == 0:
+        return np.zeros((0,), dtype=float)
+    base = float(np.nanmedian(f[: max(1, min(200, f.size))])) if baseline_force is None else float(baseline_force)
+    if not math.isfinite(base) or base <= 0:
+        raise ValueError(f"Invalid baseline_force={baseline_force}")
+    y = (base - f) / base
+    y = np.nan_to_num(y, nan=0.0, posinf=1.0, neginf=0.0)
+    return _clip01(y)
+
+
+def fatigue_score_from_rpe(t_s: np.ndarray, rpe_times_s: np.ndarray, rpe_values: np.ndarray, *, rpe_min: float = 6.0, rpe_max: float = 20.0) -> np.ndarray:
+    """Weak label: interpolate RPE (Borg 6–20) into a continuous fatigue score in [0..1]."""
+    t = np.asarray(t_s, dtype=float)
+    rt = np.asarray(rpe_times_s, dtype=float)
+    rv = np.asarray(rpe_values, dtype=float)
+    if t.size == 0:
+        return np.zeros((0,), dtype=float)
+    if rt.size == 0 or rv.size == 0 or rt.size != rv.size:
+        raise ValueError("rpe_times_s and rpe_values must be same nonzero length")
+    # Sort RPE points by time.
+    order = np.argsort(rt)
+    rt = rt[order]
+    rv = rv[order]
+    # Interpolate with flat extrapolation.
+    v = np.interp(t, rt, rv, left=float(rv[0]), right=float(rv[-1]))
+    denom = max(1e-9, float(rpe_max) - float(rpe_min))
+    y = (v - float(rpe_min)) / denom
+    return _clip01(y)
+
+
+def bin_fatigue_score(y01: np.ndarray, *, edges: tuple[float, float] = (0.33, 0.66)) -> np.ndarray:
+    """Convert continuous [0..1] score to 3 ordinal levels: 0/1/2."""
+    y = _clip01(y01)
+    e0, e1 = float(edges[0]), float(edges[1])
+    if not (0.0 < e0 < e1 < 1.0):
+        raise ValueError(f"Invalid edges={edges}")
+    out = np.zeros_like(y, dtype=int)
+    out[y >= e0] = 1
+    out[y >= e1] = 2
+    return out
+
+
+@dataclass(frozen=True, slots=True)
+class FatigueLabelSpec:
+    """Configuration for weak labels."""
+
+    kind: str  # "time_to_failure" | "force_drop" | "rpe" | "provided_score"
+    edges: tuple[float, float] = (0.33, 0.66)
+

rr_app/analysis/fatigue_model.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import json
+import math
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+
+def _require_sklearn() -> "object":
+    try:
+        import sklearn  # type: ignore
+    except ModuleNotFoundError as e:  # pragma: no cover
+        raise ModuleNotFoundError(
+            "scikit-learn is required for training/calibration. Install with: pip install -r requirements.txt"
+        ) from e
+    return sklearn
+
+
+@dataclass(frozen=True, slots=True)
+class TrainConfig:
+    model: str = "logreg"  # "logreg" | "gbdt"
+    calibrate: str = "sigmoid"  # "sigmoid" | "isotonic" | "none"
+    random_state: int = 1337
+    max_iter: int = 2000
+    # Conformal prediction set coverage (1-alpha). alpha=0.1 -> 90% sets.
+    conformal_alpha: float = 0.1
+
+
+def build_classifier(cfg: TrainConfig) -> Any:
+    _require_sklearn()
+    from sklearn.linear_model import LogisticRegression
+    from sklearn.ensemble import HistGradientBoostingClassifier
+    from sklearn.pipeline import Pipeline
+    from sklearn.preprocessing import StandardScaler
+
+    model = str(cfg.model).lower()
+    if model == "logreg":
+        clf = LogisticRegression(
+            penalty="l2",
+            C=1.0,
+            max_iter=int(cfg.max_iter),
+            multi_class="multinomial",
+            solver="lbfgs",
+            random_state=int(cfg.random_state),
+        )
+        # Logistic regression benefits from standardization.
+        return Pipeline([("scaler", StandardScaler()), ("clf", clf)])
+    if model == "gbdt":
+        clf = HistGradientBoostingClassifier(random_state=int(cfg.random_state))
+        return Pipeline([("clf", clf)])
+    raise ValueError(f"Unknown model={cfg.model!r}")
+
+
+def maybe_calibrate(estimator: Any, *, method: str, cv: int = 3) -> Any:
+    _require_sklearn()
+    from sklearn.calibration import CalibratedClassifierCV
+
+    method = str(method).lower()
+    if method in ("none", "", "false", "0"):
+        return estimator
+    if method not in ("sigmoid", "isotonic"):
+        raise ValueError(f"Unknown calibrate method={method!r}")
+    return CalibratedClassifierCV(estimator, method=method, cv=int(cv))
+
+
+def groupwise_cv_metrics(X: np.ndarray, y: np.ndarray, groups: np.ndarray, *, cfg: TrainConfig) -> dict[str, float]:
+    """Subject-wise validation metrics (macro F1 + log loss + Brier)."""
+    _require_sklearn()
+    from sklearn.model_selection import GroupKFold
+    from sklearn.metrics import f1_score, accuracy_score, log_loss
+
+    X = np.asarray(X, dtype=float)
+    y = np.asarray(y, dtype=int)
+    g = np.asarray(groups)
+
+    uniq = np.unique(g)
+    n_groups = int(uniq.size)
+    if n_groups < 2:
+        raise ValueError("Need at least 2 groups for subject-wise validation")
+
+    n_splits = min(5, n_groups)
+    cv = GroupKFold(n_splits=n_splits)
+
+    f1s: list[float] = []
+    accs: list[float] = []
+    lls: list[float] = []
+    briers: list[float] = []
+
+    classes = np.unique(y)
+    n_classes = int(classes.size)
+
+    for tr, te in cv.split(X, y, groups=g):
+        est = build_classifier(cfg)
+        est = maybe_calibrate(est, method=cfg.calibrate, cv=3)
+        est.fit(X[tr], y[tr])
+        y_hat = est.predict(X[te])
+        f1s.append(float(f1_score(y[te], y_hat, average="macro")))
+        accs.append(float(accuracy_score(y[te], y_hat)))
+
+        # Probabilistic metrics
+        if hasattr(est, "predict_proba"):
+            p = est.predict_proba(X[te])
+            # Ensure columns correspond to class labels 0..K-1 if needed.
+            try:
+                lls.append(float(log_loss(y[te], p, labels=list(range(n_classes)))))
+            except Exception:
+                # Fallback: compute log loss with inferred labels.
+                lls.append(float(log_loss(y[te], p)))
+            # Multi-class Brier: mean sum_k (p_k - 1[y=k])^2
+            y_onehot = np.eye(n_classes, dtype=float)[y[te]]
+            briers.append(float(np.mean(np.sum((p - y_onehot) ** 2, axis=1))))
+
+    return {
+        "cv_groups": float(n_groups),
+        "cv_splits": float(n_splits),
+        "accuracy_mean": float(np.mean(accs)),
+        "f1_macro_mean": float(np.mean(f1s)),
+        "log_loss_mean": float(np.mean(lls)) if lls else float("nan"),
+        "brier_mean": float(np.mean(briers)) if briers else float("nan"),
+    }
+
+
+def fit_final_model(X: np.ndarray, y: np.ndarray, *, cfg: TrainConfig) -> Any:
+    est = build_classifier(cfg)
+    est = maybe_calibrate(est, method=cfg.calibrate, cv=3)
+    est.fit(np.asarray(X, dtype=float), np.asarray(y, dtype=int))
+    return est
+
+
+def predict_with_confidence(estimator: Any, X: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """Return (y_pred, p_pred) where p_pred is max class probability."""
+    X = np.asarray(X, dtype=float)
+    if hasattr(estimator, "predict_proba"):
+        p = estimator.predict_proba(X)
+        y = np.argmax(p, axis=1).astype(int)
+        conf = np.max(p, axis=1).astype(float)
+        return y, conf
+    # Fallback: hard predictions only
+    y = estimator.predict(X).astype(int)
+    return y, np.ones((y.size,), dtype=float)
+
+
+def conformal_threshold_from_calibration_probs(p_calib: np.ndarray, y_calib: np.ndarray, *, alpha: float = 0.1) -> float:
+    """Compute split-conformal threshold for prediction sets.
+
+    Nonconformity score s = 1 - p_true. Then choose q = quantile_{ceil((n+1)*(1-alpha))/n}.
+    A class k is included in the set if 1 - p_k <= q  <=>  p_k >= 1 - q.
+    """
+    p = np.asarray(p_calib, dtype=float)
+    y = np.asarray(y_calib, dtype=int)
+    if p.ndim != 2:
+        raise ValueError("p_calib must be 2D (n_samples, n_classes)")
+    if y.size != p.shape[0]:
+        raise ValueError("y_calib length must match p_calib rows")
+
+    alpha = float(alpha)
+    if not (0.0 < alpha < 1.0):
+        raise ValueError(f"alpha must be in (0,1), got {alpha}")
+
+    p_true = p[np.arange(y.size), y]
+    s = 1.0 - np.clip(p_true, 0.0, 1.0)
+    n = float(s.size)
+    # Conformal quantile with (n+1)(1-alpha) rule.
+    q_level = math.ceil((n + 1.0) * (1.0 - alpha)) / n
+    q_level = min(1.0, max(0.0, q_level))
+    q = float(np.quantile(s, q_level, method="higher"))
+    return q
+
+
+def prediction_set_from_probs(p: np.ndarray, *, q: float) -> list[list[int]]:
+    """Return a prediction set (list of class indices) per sample."""
+    p = np.asarray(p, dtype=float)
+    q = float(q)
+    thr = 1.0 - q
+    out: list[list[int]] = []
+    for i in range(p.shape[0]):
+        cls = [int(k) for k in range(p.shape[1]) if float(p[i, k]) >= thr]
+        if not cls:
+            cls = [int(np.argmax(p[i]))]
+        out.append(cls)
+    return out
+
+
+def save_model(path: str | Path, *, estimator: Any, cfg: TrainConfig, feature_names: list[str], meta: dict[str, Any] | None = None) -> None:
+    _require_sklearn()
+    import joblib  # type: ignore
+
+    payload = {
+        "estimator": estimator,
+        "train_config": asdict(cfg),
+        "feature_names": list(feature_names),
+        "meta": meta or {},
+    }
+    joblib.dump(payload, str(path))
+
+
+def load_model(path: str | Path) -> dict[str, Any]:
+    _require_sklearn()
+    import joblib  # type: ignore
+
+    payload = joblib.load(str(path))
+    if not isinstance(payload, dict) or "estimator" not in payload:
+        raise ValueError("Invalid model file format")
+    return payload
+
+
+def save_metrics_json(path: str | Path, metrics: dict[str, float]) -> None:
+    Path(path).write_text(json.dumps(metrics, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+