feat(api): POST /pipeline/mri/diagnostics — pre/post ComBat KPIs + long-format rows

- Adds MRIDiagnosticsRequest/HarmonizationRow/MRIDiagnosticsResponse
schemas. The response carries the long-format rows plus 3 KPIs:
site_gap_pre, site_gap_post, reduction_factor (= pre/max(post,eps)).
- Site-gap is computed on the first feature's per-site means
(max - min). reduction_factor uses 1e-9 epsilon to avoid div-by-zero
when ComBat collapses the gap to numerical zero.
- Empty-volume input returns an empty rows list with zero KPIs (no
exception). FileNotFoundError → 404, KeyError → 400.
- 2 new tests: 200 happy path on the synthetic fixture (must pin
reduction_factor >= 1.0) and 404 on missing input_dir.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/api/routes.py

@@ -23,6 +23,9 @@ from src.api.schemas import (
     CalibrationContext,
     EEGRequest,
     FeatureAttribution,
+    HarmonizationRow,
+    MRIDiagnosticsRequest,
+    MRIDiagnosticsResponse,
     MRIRequest,
     PipelineResponse,
 )
@@ -184,3 +187,47 @@ def predict_bbb(req: BBBPredictRequest) -> BBBPredictResponse:
         top_features=[FeatureAttribution(**a) for a in attributions],
         calibration=calibration,
     )
+
+
+@router.post("/mri/diagnostics", response_model=MRIDiagnosticsResponse)
+def mri_diagnostics(req: MRIDiagnosticsRequest) -> MRIDiagnosticsResponse:
+    """Run the MRI pipeline twice and return pre/post ComBat data + site-gap KPIs."""
+    input_dir = Path(req.input_dir)
+    sites_csv = Path(req.sites_csv)
+    try:
+        df = mri_pipeline.compute_harmonization_diagnostics(
+            input_dir=input_dir, sites_csv=sites_csv,
+        )
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except KeyError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    if df.empty:
+        return MRIDiagnosticsResponse(
+            rows=[], site_gap_pre=0.0, site_gap_post=0.0, reduction_factor=0.0,
+        )
+
+    # Site-gap KPI on the first feature, averaged per site
+    feat = df["feature"].iloc[0]
+    feat_df = df[df["feature"] == feat]
+    pre_means = feat_df[feat_df["harmonization_state"] == "Pre-ComBat"].groupby(
+        "site"
+    )["feature_value"].mean()
+    post_means = feat_df[feat_df["harmonization_state"] == "Post-ComBat"].groupby(
+        "site"
+    )["feature_value"].mean()
+    site_gap_pre = float(pre_means.max() - pre_means.min())
+    site_gap_post = float(post_means.max() - post_means.min())
+    eps = 1e-9
+    reduction_factor = site_gap_pre / max(site_gap_post, eps)
+
+    rows = [
+        HarmonizationRow(**rec) for rec in df.to_dict(orient="records")
+    ]
+    return MRIDiagnosticsResponse(
+        rows=rows,
+        site_gap_pre=site_gap_pre,
+        site_gap_post=site_gap_post,
+        reduction_factor=reduction_factor,
+    )

src/api/schemas.py

@@ -80,3 +80,25 @@ class BBBPredictResponse(BaseModel):
         None,
         description="Statistical context: how often the model is right when this confident on held-out data.",
     )
+
+
+class MRIDiagnosticsRequest(BaseModel):
+    """Request body for /pipeline/mri/diagnostics — same as MRIRequest minus output_path."""
+    input_dir: str = Field(..., description="Directory of .nii.gz files")
+    sites_csv: str = Field(..., description="CSV mapping subject_id → site")
+
+
+class HarmonizationRow(BaseModel):
+    subject_id: str
+    site: str
+    feature: str
+    feature_value: float
+    harmonization_state: str
+
+
+class MRIDiagnosticsResponse(BaseModel):
+    """Long-format pre/post ComBat data for visualization."""
+    rows: list[HarmonizationRow]
+    site_gap_pre: float = Field(..., description="Range of per-site means before ComBat")
+    site_gap_post: float = Field(..., description="Range of per-site means after ComBat")
+    reduction_factor: float = Field(..., description="site_gap_pre / max(site_gap_post, eps)")

tests/api/test_routes.py

@@ -137,3 +137,35 @@ class TestBBBPredictRoute:
             json={"smiles": "CCO", "top_k": 5},
         )
         assert resp.status_code == 503
+
+
+class TestMRIDiagnosticsRoute:
+    def test_returns_200_with_pre_and_post_data(self, tmp_path: Path):
+        from tests.fixtures.build_mri_fixture import build as build_mri
+        fixture_dir = build_mri(out_dir=tmp_path / "mri")
+        resp = client.post(
+            "/pipeline/mri/diagnostics",
+            json={
+                "input_dir": str(fixture_dir),
+                "sites_csv": str(fixture_dir / "sites.csv"),
+            },
+        )
+        assert resp.status_code == 200
+        body = resp.json()
+        assert len(body["rows"]) > 0
+        assert body["site_gap_pre"] >= 0.0
+        assert body["site_gap_post"] >= 0.0
+        # Reduction factor is the headline KPI
+        assert body["reduction_factor"] >= 1.0  # ComBat must reduce, not amplify
+        states = {r["harmonization_state"] for r in body["rows"]}
+        assert states == {"Pre-ComBat", "Post-ComBat"}
+
+    def test_returns_404_when_input_dir_missing(self, tmp_path: Path):
+        resp = client.post(
+            "/pipeline/mri/diagnostics",
+            json={
+                "input_dir": str(tmp_path / "does_not_exist"),
+                "sites_csv": str(tmp_path / "sites.csv"),
+            },
+        )
+        assert resp.status_code == 404