feat(api): POST /explain/eeg + /explain/mri — full-stack Track-1 coverage

- EEGExplainRequest carries pipeline metrics (rows / columns /
duration_sec / mlflow_run_id). MRIExplainRequest carries ComBat KPIs
(site_gap_pre / site_gap_post / reduction_factor / n_subjects).
- Both routes mounted on explain_router (prefix /explain). Use the
Day-7 explainer with modality='eeg' or 'mri' — same hybrid LLM /
template / kill-switch contract.
- 2 new tests with NEUROBRIDGE_DISABLE_LLM=1 force-deterministic.

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

src/api/routes.py

@@ -24,12 +24,16 @@ from src.api.schemas import (
     BBBPredictResponse,
     BBBRequest,
     CalibrationContext,
+    EEGExplainRequest,
+    EEGExplainResponse,
     EEGRequest,
     FeatureAttribution,
     HarmonizationRow,
     ModelProvenance,
     MRIDiagnosticsRequest,
     MRIDiagnosticsResponse,
+    MRIExplainRequest,
+    MRIExplainResponse,
     MRIRequest,
     PipelineResponse,
 )
@@ -362,3 +366,39 @@ def explain_bbb(req: BBBExplainRequest) -> BBBExplainResponse:
         source=result["source"],
         model=result["model"],
     )
+
+
+@explain_router.post("/eeg", response_model=EEGExplainResponse)
+def explain_eeg(req: EEGExplainRequest) -> EEGExplainResponse:
+    """Natural-language rationale for an EEG pipeline run."""
+    payload = {
+        "rows": req.rows,
+        "columns": req.columns,
+        "duration_sec": req.duration_sec,
+        "mlflow_run_id": req.mlflow_run_id,
+        "user_question": req.user_question or "",
+    }
+    result = llm_explainer.explain(payload, modality="eeg")
+    return EEGExplainResponse(
+        rationale=result["rationale"],
+        source=result["source"],
+        model=result["model"],
+    )
+
+
+@explain_router.post("/mri", response_model=MRIExplainResponse)
+def explain_mri(req: MRIExplainRequest) -> MRIExplainResponse:
+    """Natural-language rationale for an MRI ComBat diagnostic run."""
+    payload = {
+        "site_gap_pre": req.site_gap_pre,
+        "site_gap_post": req.site_gap_post,
+        "reduction_factor": req.reduction_factor,
+        "n_subjects": req.n_subjects,
+        "user_question": req.user_question or "",
+    }
+    result = llm_explainer.explain(payload, modality="mri")
+    return MRIExplainResponse(
+        rationale=result["rationale"],
+        source=result["source"],
+        model=result["model"],
+    )

src/api/schemas.py

@@ -161,3 +161,35 @@ class BBBExplainResponse(BaseModel):
         None,
         description="LLM model name when source='llm'; None when source='template'",
     )
+
+
+class EEGExplainRequest(BaseModel):
+    """Day-8 T1B: payload for POST /explain/eeg."""
+    rows: int = Field(..., ge=0, description="Number of epochs produced")
+    columns: int = Field(..., ge=0, description="Number of features per epoch")
+    duration_sec: float = Field(..., ge=0.0, description="Pipeline wall-clock seconds")
+    mlflow_run_id: str | None = Field(None, description="MLflow run id, if available")
+    user_question: str | None = Field(None, description="Optional user question for the LLM prompt")
+
+
+class EEGExplainResponse(BaseModel):
+    """Day-8 T1B: response from POST /explain/eeg."""
+    rationale: str
+    source: str
+    model: str | None = None
+
+
+class MRIExplainRequest(BaseModel):
+    """Day-8 T1B: payload for POST /explain/mri."""
+    site_gap_pre: float = Field(..., ge=0.0)
+    site_gap_post: float = Field(..., ge=0.0)
+    reduction_factor: float = Field(..., ge=0.0)
+    n_subjects: int = Field(..., ge=0)
+    user_question: str | None = None
+
+
+class MRIExplainResponse(BaseModel):
+    """Day-8 T1B: response from POST /explain/mri."""
+    rationale: str
+    source: str
+    model: str | None = None

tests/api/test_routes.py

@@ -259,3 +259,44 @@ class TestExplainBBBRoute:
         for feat in ("fp_341", "fp_902", "fp_77"):
             assert feat in out["rationale"]
         assert "permeable" in out["rationale"]
+
+
+class TestExplainEEGRoute:
+    """Day-8 T1B: POST /explain/eeg."""
+
+    def test_returns_200_with_template_source(self, monkeypatch):
+        monkeypatch.setenv("NEUROBRIDGE_DISABLE_LLM", "1")
+        body = {
+            "rows": 30,
+            "columns": 95,
+            "duration_sec": 4.32,
+            "mlflow_run_id": "abc12345",
+            "user_question": "Why were epochs dropped?",
+        }
+        resp = client.post("/explain/eeg", json=body)
+        assert resp.status_code == 200, resp.text
+        out = resp.json()
+        assert out["source"] == "template"
+        assert out["model"] is None
+        assert "30" in out["rationale"]
+        assert "95" in out["rationale"]
+
+
+class TestExplainMRIRoute:
+    """Day-8 T1B: POST /explain/mri."""
+
+    def test_returns_200_with_template_source(self, monkeypatch):
+        monkeypatch.setenv("NEUROBRIDGE_DISABLE_LLM", "1")
+        body = {
+            "site_gap_pre": 5.0004,
+            "site_gap_post": 0.0015,
+            "reduction_factor": 3290.0,
+            "n_subjects": 6,
+            "user_question": "Why does ComBat matter?",
+        }
+        resp = client.post("/explain/mri", json=body)
+        assert resp.status_code == 200, resp.text
+        out = resp.json()
+        assert out["source"] == "template"
+        assert "3290" in out["rationale"]
+        assert "6" in out["rationale"]