feat(api): POST /explain/bbb — natural-language rationale endpoint

- New explain_router with /explain prefix; symmetric with /predict/bbb
and reserves /explain/eeg, /explain/mri for future expansion.
- BBBExplainRequest carries the prediction snapshot + optional
user_question. top_features is required and must be non-empty
(Pydantic min_length=1 → 422 on empty).
- BBBExplainResponse: {rationale, source, model}. Always 200 because
the explainer's template fallback never raises.
- 1 new test: 200 + source='template' under NEUROBRIDGE_DISABLE_LLM=1
with full SHAP + calibration + drift payload.

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

src/api/main.py

@@ -6,7 +6,7 @@ from __future__ import annotations
 
 from fastapi import FastAPI
 
-from src.api.routes import router as pipeline_router, predict_router
+from src.api.routes import router as pipeline_router, predict_router, explain_router
 from src.api.schemas import HealthResponse
 
 app = FastAPI(
@@ -17,6 +17,7 @@ app = FastAPI(
 
 app.include_router(pipeline_router)
 app.include_router(predict_router)
+app.include_router(explain_router)
 
 
 @app.get("/health", response_model=HealthResponse)

src/api/routes.py

@@ -18,6 +18,8 @@ import pandas as pd
 from fastapi import APIRouter, HTTPException
 
 from src.api.schemas import (
+    BBBExplainRequest,
+    BBBExplainResponse,
     BBBPredictRequest,
     BBBPredictResponse,
     BBBRequest,
@@ -32,12 +34,14 @@ from src.api.schemas import (
     PipelineResponse,
 )
 from src.core.logger import get_logger
+from src.llm import explainer as llm_explainer
 from src.models import bbb_model
 from src.pipelines import bbb_pipeline, eeg_pipeline, mri_pipeline
 
 logger = get_logger(__name__)
 router = APIRouter(prefix="/pipeline")
 predict_router = APIRouter(prefix="/predict")
+explain_router = APIRouter(prefix="/explain")
 
 
 def _wrap(
@@ -320,3 +324,41 @@ def mri_diagnostics(req: MRIDiagnosticsRequest) -> MRIDiagnosticsResponse:
         site_gap_post=site_gap_post,
         reduction_factor=reduction_factor,
     )
+
+
+@explain_router.post("/bbb", response_model=BBBExplainResponse)
+def explain_bbb(req: BBBExplainRequest) -> BBBExplainResponse:
+    """Natural-language rationale for a single BBB prediction.
+
+    Always returns 200 — the explainer is guaranteed to produce a
+    rationale via deterministic-template fallback. Pydantic enforces
+    a non-empty top_features list; an empty list returns 422 from
+    FastAPI before this handler runs.
+    """
+    payload: llm_explainer.ExplainPayload = {
+        "smiles": req.smiles,
+        "label": req.label,
+        "label_text": req.label_text,
+        "confidence": req.confidence,
+        "top_features": [
+            {"feature": f.feature, "shap_value": f.shap_value}
+            for f in req.top_features
+        ],
+        "calibration": (
+            None
+            if req.calibration is None
+            else {
+                "threshold": req.calibration.threshold,
+                "precision": req.calibration.precision,
+                "support": req.calibration.support,
+            }
+        ),
+        "drift_z": req.drift_z,
+        "user_question": req.user_question or "",
+    }
+    result = llm_explainer.explain(payload)
+    return BBBExplainResponse(
+        rationale=result["rationale"],
+        source=result["source"],
+        model=result["model"],
+    )

src/api/schemas.py

@@ -133,3 +133,31 @@ class MRIDiagnosticsResponse(BaseModel):
     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)")
+
+
+class BBBExplainRequest(BaseModel):
+    """Day-7 T3B: payload for POST /explain/bbb (chat-style explainer)."""
+    smiles: str = Field(..., description="SMILES string of the molecule")
+    label: int = Field(..., description="Predicted label (0 = non-permeable, 1 = permeable)")
+    label_text: str = Field(..., description="'permeable' or 'non-permeable'")
+    confidence: float = Field(..., ge=0.0, le=1.0)
+    top_features: list[FeatureAttribution] = Field(
+        ..., min_length=1,
+        description="Non-empty list of SHAP attributions; an empty list returns 400.",
+    )
+    calibration: CalibrationContext | None = None
+    drift_z: float | None = None
+    user_question: str | None = Field(
+        None,
+        description="Optional question from the user; passed to the LLM prompt only.",
+    )
+
+
+class BBBExplainResponse(BaseModel):
+    """Day-7 T3B: response from POST /explain/bbb."""
+    rationale: str = Field(..., description="2-4 sentence natural-language explanation")
+    source: str = Field(..., description="'llm' or 'template'")
+    model: str | None = Field(
+        None,
+        description="LLM model name when source='llm'; None when source='template'",
+    )

tests/api/test_routes.py

@@ -228,3 +228,34 @@ class TestMRIDiagnosticsRoute:
             },
         )
         assert resp.status_code == 404
+
+
+class TestExplainBBBRoute:
+    """Day-7 T3B: POST /explain/bbb."""
+
+    def test_returns_200_with_template_source(self, monkeypatch):
+        """Kill-switch on → /explain/bbb returns rationale with source=template."""
+        monkeypatch.setenv("NEUROBRIDGE_DISABLE_LLM", "1")
+        body = {
+            "smiles": "CCO",
+            "label": 1,
+            "label_text": "permeable",
+            "confidence": 0.82,
+            "top_features": [
+                {"feature": "fp_341", "shap_value": 0.045},
+                {"feature": "fp_902", "shap_value": -0.031},
+                {"feature": "fp_77", "shap_value": 0.022},
+            ],
+            "calibration": {"threshold": 0.80, "precision": 0.92, "support": 18},
+            "drift_z": 0.42,
+            "user_question": "Why permeable?",
+        }
+        resp = client.post("/explain/bbb", json=body)
+        assert resp.status_code == 200, resp.text
+        out = resp.json()
+        assert out["source"] == "template"
+        assert out["model"] is None
+        # Template must mention all three features
+        for feat in ("fp_341", "fp_902", "fp_77"):
+            assert feat in out["rationale"]
+        assert "permeable" in out["rationale"]