feat(api): GET /experiments/runs + POST /experiments/diff (Track 5)

- New experiments_router (prefix /experiments) hosts two endpoints:
GET /runs lists MLflow runs across all 3 experiments (bbb / eeg /
mri), POST /diff returns a side-by-side metric+param diff for two
given run ids.
- NEUROBRIDGE_DISABLE_MLFLOW=1 short-circuits both to empty
responses (no exception). Unknown run ids → 404 with detail.
- 5 new schemas: MLflowRunSummary, MLflowRunsResponse, RunDiffRequest,
RunDiffRow, RunDiffResponse.
- 2 new tests covering the empty-list and unknown-id paths.

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

src/api/main.py

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

src/api/routes.py

@@ -29,6 +29,8 @@ from src.api.schemas import (
     EEGRequest,
     FeatureAttribution,
     HarmonizationRow,
+    MLflowRunsResponse,
+    MLflowRunSummary,
     ModelProvenance,
     MRIDiagnosticsRequest,
     MRIDiagnosticsResponse,
@@ -36,6 +38,9 @@ from src.api.schemas import (
     MRIExplainResponse,
     MRIRequest,
     PipelineResponse,
+    RunDiffRequest,
+    RunDiffResponse,
+    RunDiffRow,
 )
 from src.core.logger import get_logger
 from src.llm import explainer as llm_explainer
@@ -46,6 +51,7 @@ logger = get_logger(__name__)
 router = APIRouter(prefix="/pipeline")
 predict_router = APIRouter(prefix="/predict")
 explain_router = APIRouter(prefix="/explain")
+experiments_router = APIRouter(prefix="/experiments")
 
 
 def _wrap(
@@ -402,3 +408,95 @@ def explain_mri(req: MRIExplainRequest) -> MRIExplainResponse:
         source=result["source"],
         model=result["model"],
     )
+
+
+@experiments_router.get("/runs", response_model=MLflowRunsResponse)
+def list_runs(limit: int = 50) -> MLflowRunsResponse:
+    """List recent MLflow runs across known experiments.
+
+    Returns an empty list when MLflow is disabled or unreachable.
+    """
+    if os.environ.get("NEUROBRIDGE_DISABLE_MLFLOW") == "1":
+        return MLflowRunsResponse(runs=[])
+
+    summaries: list[MLflowRunSummary] = []
+    for exp_name in ("bbb_pipeline", "eeg_pipeline", "mri_pipeline"):
+        try:
+            df = mlflow.search_runs(
+                experiment_names=[exp_name],
+                max_results=limit,
+                order_by=["start_time DESC"],
+            )
+        except Exception as e:  # broad: MLflow store unreachable / not found
+            logger.warning("MLflow lookup failed for %s: %s", exp_name, e)
+            continue
+        for _, row in df.iterrows():
+            metrics = {
+                col[len("metrics."):]: float(row[col])
+                for col in df.columns
+                if col.startswith("metrics.") and pd.notna(row[col])
+            }
+            params = {
+                col[len("params."):]: str(row[col])
+                for col in df.columns
+                if col.startswith("params.") and pd.notna(row[col])
+            }
+            summaries.append(
+                MLflowRunSummary(
+                    run_id=str(row["run_id"]),
+                    experiment_name=exp_name,
+                    start_time=str(pd.Timestamp(row["start_time"]).isoformat())
+                    if pd.notna(row.get("start_time"))
+                    else "",
+                    status=str(row.get("status", "UNKNOWN")),
+                    metrics=metrics,
+                    params=params,
+                )
+            )
+    summaries.sort(key=lambda s: s.start_time, reverse=True)
+    return MLflowRunsResponse(runs=summaries[:limit])
+
+
+@experiments_router.post("/diff", response_model=RunDiffResponse)
+def diff_runs(req: RunDiffRequest) -> RunDiffResponse:
+    """Side-by-side diff of two MLflow runs (metrics + params).
+
+    Returns 404 if either run id is not found in the local MLflow store.
+    Returns 200 with an empty rows list when MLflow is disabled.
+    """
+    if os.environ.get("NEUROBRIDGE_DISABLE_MLFLOW") == "1":
+        return RunDiffResponse(rows=[])
+
+    try:
+        run_a = mlflow.get_run(req.run_id_a)
+        run_b = mlflow.get_run(req.run_id_b)
+    except Exception as e:
+        raise HTTPException(status_code=404, detail=f"Run not found: {e}")
+
+    metrics_a = run_a.data.metrics
+    metrics_b = run_b.data.metrics
+    params_a = run_a.data.params
+    params_b = run_b.data.params
+
+    rows: list[RunDiffRow] = []
+    for key in sorted(set(metrics_a) | set(metrics_b)):
+        va = metrics_a.get(key)
+        vb = metrics_b.get(key)
+        rows.append(
+            RunDiffRow(
+                key=key, kind="metric",
+                value_a=None if va is None else f"{va:.6g}",
+                value_b=None if vb is None else f"{vb:.6g}",
+                differs=(va != vb),
+            )
+        )
+    for key in sorted(set(params_a) | set(params_b)):
+        va = params_a.get(key)
+        vb = params_b.get(key)
+        rows.append(
+            RunDiffRow(
+                key=key, kind="param",
+                value_a=va, value_b=vb, differs=(va != vb),
+            )
+        )
+    return RunDiffResponse(rows=rows)

src/api/schemas.py

@@ -193,3 +193,38 @@ class MRIExplainResponse(BaseModel):
     rationale: str
     source: str
     model: str | None = None
+
+
+class MLflowRunSummary(BaseModel):
+    """One MLflow run row for the Experiments tab table."""
+    run_id: str
+    experiment_name: str
+    start_time: str  # ISO 8601
+    status: str
+    metrics: dict[str, float] = Field(default_factory=dict)
+    params: dict[str, str] = Field(default_factory=dict)
+
+
+class MLflowRunsResponse(BaseModel):
+    """Response for GET /experiments/runs."""
+    runs: list[MLflowRunSummary]
+
+
+class RunDiffRequest(BaseModel):
+    """Request body for POST /experiments/diff."""
+    run_id_a: str
+    run_id_b: str
+
+
+class RunDiffRow(BaseModel):
+    """One row of a run-vs-run diff: metric/param key + value pair."""
+    key: str
+    kind: str  # "metric" | "param"
+    value_a: str | None
+    value_b: str | None
+    differs: bool
+
+
+class RunDiffResponse(BaseModel):
+    """Response for POST /experiments/diff: side-by-side metric/param diff."""
+    rows: list[RunDiffRow]

tests/api/test_routes.py

@@ -300,3 +300,34 @@ class TestExplainMRIRoute:
         assert out["source"] == "template"
         assert "3290" in out["rationale"]
         assert "6" in out["rationale"]
+
+
+class TestExperimentsRoutes:
+    """Day-8 T2A: GET /experiments/runs and POST /experiments/diff."""
+
+    def test_runs_endpoint_returns_list(self):
+        """GET /experiments/runs returns a runs list (may be empty if no MLflow data)."""
+        resp = client.get("/experiments/runs")
+        assert resp.status_code == 200, resp.text
+        body = resp.json()
+        assert "runs" in body
+        assert isinstance(body["runs"], list)
+        # If any runs exist, each must have the expected keys
+        for run in body["runs"]:
+            for key in ("run_id", "experiment_name", "start_time", "status", "metrics", "params"):
+                assert key in run
+
+    def test_diff_endpoint_handles_unknown_runs_gracefully(self):
+        """POST /experiments/diff with bogus run ids returns 404 (not 500)."""
+        resp = client.post(
+            "/experiments/diff",
+            json={"run_id_a": "nonexistent_aaa", "run_id_b": "nonexistent_bbb"},
+        )
+        assert resp.status_code in (404, 200), (
+            f"unexpected status {resp.status_code}: {resp.text}"
+        )
+        # 404 is the documented contract; 200 with empty rows is acceptable too
+        # because some MLflow stores treat unknown ids as "empty result".
+        body = resp.json()
+        if resp.status_code == 200:
+            assert body.get("rows", []) == []