feat(api): add POST /predict/eeg route (stub-able for demo)

src/api/routes.py

@@ -27,7 +27,10 @@ from src.api.schemas import (
     BBBPredictResponse,
     BBBRequest,
     CalibrationContext,
+    EEGClassProbability,
     EEGExplainRequest,
+    EEGPredictRequest,
+    EEGPredictResponse,
     FusionRequest,
     FusionResponse,
     EEGExplainResponse,
@@ -317,6 +320,43 @@ def predict_bbb(req: BBBPredictRequest) -> BBBPredictResponse:
     )
 
 
+@predict_router.post("/eeg", response_model=EEGPredictResponse)
+def predict_eeg(req: EEGPredictRequest) -> EEGPredictResponse:
+    """Predict from EEG features using an externally-trained sklearn classifier.
+
+    Real artifact lands at data/processed/eeg_clf.joblib (override via
+    EEG_CLF_ARTIFACT). For the demo a stub fixture (RandomForestClassifier
+    on synthetic features) is acceptable — the response shape stays stable.
+    """
+    import numpy as np
+    from src.models import eeg_model
+
+    artifact = Path(os.environ.get("EEG_CLF_ARTIFACT", "data/processed/eeg_clf.joblib"))
+    if not artifact.exists():
+        raise HTTPException(
+            status_code=503,
+            detail=(
+                f"EEG model artifact not available at {artifact}. "
+                "Drop the trained joblib at this path or set EEG_CLF_ARTIFACT."
+            ),
+        )
+    try:
+        clf = eeg_model.load(artifact)
+        features = np.asarray(req.features, dtype=np.float32)
+        out = eeg_model.predict_features(clf, features)
+    except FileNotFoundError as e:
+        raise HTTPException(status_code=404, detail=str(e))
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=str(e))
+
+    return EEGPredictResponse(
+        label=int(out["label"]),
+        label_text=str(out["label_text"]),
+        confidence=float(out["confidence"]),
+        probabilities=[EEGClassProbability(**p) for p in out["probabilities"]],
+    )
+
+
 @predict_router.post("/mri", response_model=MRIPredictResponse)
 def predict_mri(req: MRIPredictRequest) -> MRIPredictResponse:
     """Predict from one MRI image. Backend selected by MRI_MODEL_KIND env.

src/api/schemas.py

@@ -113,6 +113,29 @@ class BBBPredictResponse(BaseModel):
     )
 
 
+class EEGPredictRequest(BaseModel):
+    """Single-subject EEG-features prediction request."""
+    features: list[float] = Field(
+        ..., min_length=1,
+        description="EEG features matching the classifier's training-time feature count.",
+    )
+
+
+class EEGClassProbability(BaseModel):
+    """One EEG model class probability."""
+    label: int
+    label_text: str
+    probability: float
+
+
+class EEGPredictResponse(BaseModel):
+    """EEG prediction payload — same shape as MRIPredictResponse minus model_path."""
+    label: int
+    label_text: str
+    confidence: float
+    probabilities: list[EEGClassProbability]
+
+
 class MRIPredictRequest(BaseModel):
     """Single-subject MRI image prediction request."""
     input_path: str = Field(

tests/api/test_eeg_predict_route.py

@@ -0,0 +1,46 @@
+"""Integration: POST /predict/eeg."""
+from __future__ import annotations
+
+import pytest
+from fastapi.testclient import TestClient
+
+from src.api.main import app
+from tests.fixtures.build_dummy_eeg_clf import build as build_dummy_eeg
+
+
+@pytest.fixture()
+def client(monkeypatch, tmp_path):
+    artifact = build_dummy_eeg(tmp_path / "eeg.joblib", n_features=16)
+    monkeypatch.setenv("EEG_CLF_ARTIFACT", str(artifact))
+    return TestClient(app)
+
+
+def test_predict_eeg_happy_path(client):
+    body = {"features": [0.0] * 16}
+    r = client.post("/predict/eeg", json=body)
+    assert r.status_code == 200, r.text
+    data = r.json()
+    assert data["label_text"] in {"control", "alzheimers"}
+    assert 0.0 <= data["confidence"] <= 1.0
+    assert len(data["probabilities"]) == 2
+
+
+def test_predict_eeg_alzheimers_profile(client):
+    body = {"features": [2.0] * 16}
+    r = client.post("/predict/eeg", json=body)
+    assert r.status_code == 200, r.text
+    data = r.json()
+    assert data["label_text"] == "alzheimers"
+
+
+def test_predict_eeg_feature_mismatch_returns_400(client):
+    body = {"features": [0.0] * 8}
+    r = client.post("/predict/eeg", json=body)
+    assert r.status_code == 400
+
+
+def test_predict_eeg_missing_artifact_returns_503(monkeypatch, tmp_path):
+    monkeypatch.setenv("EEG_CLF_ARTIFACT", str(tmp_path / "missing.joblib"))
+    client = TestClient(app)
+    r = client.post("/predict/eeg", json={"features": [0.0] * 16})
+    assert r.status_code == 503