fix(demo): wire every showcase path end-to-end with auto-resolved artifacts

Goal: every endpoint and every Streamlit tab must work in a 2-minute
hackathon demo without requiring the demoer to fetch external data.

Code fixes:
- src/api/routes.py + src/agents/tools.py: fix two stale references —
bbb_model.load (not load_model) and bbb_model.predict_with_proba (not
predict_one); also corrects the agent-side default BBB artifact path
from .pkl to .joblib so the auto-resolve in adjust_drug_dose works.
- src/api/routes.py: replace hard-coded _AGENT_DEFAULT_MODEL = google/
gemini-2.0-flash-exp:free (now 404 on OpenRouter) with a fallback
chain probed at orchestrator-build time. Picks the first model that
returns a non-404/429 ping. Override via NEUROBRIDGE_AGENT_MODEL
(single id) or NEUROBRIDGE_AGENT_MODEL_CHAIN (csv).
- src/llm/explainer.py: prepend openai/gpt-oss-20b:free (verified 2026-
05-02) to the explainer fallback chain so /explain/* doesn't fall
back to the deterministic template when free-tier ids churn.
- src/frontend/app.py: drop the env-var/'stub'/'demo' captions from the
EEG, MRI, and Researcher sections — feature copy only, no internals
exposed in the UI.

Demo smoke (TestClient, every showcase path):
18/18 passes — /health · /predict/{bbb,mri[volumetric+resnet18_2d],
eeg,bbb_permeability_map} · /fusion/predict ·
/research/drug_dose_adjustment · /pipeline/{bbb,eeg,mri,mri/diagnostics}
· /explain/{bbb,eeg,mri} · /experiments/runs · /diag/agent (7 tools)
· /agent/run live (auto-picked openai/gpt-oss-20b:free, BBB->RAG
trace, Turkish synthesis).

Test suite: 362 passed (orchestrator_live skipped — flaky on free tier).

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

.gitignore

@@ -45,3 +45,7 @@ data/processed/faiss_index/
 
 # Plan: external-assets-integration — clinical RAG corpus and pre-built TF-IDF index
 data/external_rag/
+
+# User-local files (presentations, Office lock files)
+*.pptx
+~$*

src/agents/tools.py

@@ -233,10 +233,10 @@ def _make_dose_adjuster_executor() -> Callable[[DrugDoseAdjustmentInput], DrugDo
             try:
                 from src.models import bbb_model
                 import os as _os
-                artifact = Path(_os.environ.get("BBB_MODEL_PATH", "data/processed/bbb_model.pkl"))
+                artifact = Path(_os.environ.get("BBB_MODEL_PATH", "data/processed/bbb_model.joblib"))
                 if artifact.exists():
-                    model = bbb_model.load_model(artifact)
-                    pred = bbb_model.predict_one(model, inp.smiles)
+                    model = bbb_model.load(artifact)
+                    pred = bbb_model.predict_with_proba(model, inp.smiles)
                     drug_permeable = bool(pred["label"] == 1)
             except (FileNotFoundError, ValueError, KeyError) as e:
                 logger.warning(

src/api/routes.py

@@ -374,8 +374,8 @@ def research_drug_dose_adjustment(req: DrugDoseAdjustmentRequest) -> DrugDoseAdj
         try:
             artifact = _bbb_model_path()
             if artifact.exists():
-                model = bbb_model.load_model(artifact)
-                bbb_pred = bbb_model.predict_one(model, req.smiles)
+                model = bbb_model.load(artifact)
+                bbb_pred = bbb_model.predict_with_proba(model, req.smiles)
                 drug_permeable = bool(bbb_pred["label"] == 1)
         except (FileNotFoundError, ValueError, KeyError) as e:
             logger.warning("could not auto-resolve BBB permeability for smiles=%s: %s", req.smiles, e)
@@ -710,7 +710,37 @@ agent_router = APIRouter(prefix="/agent")
 
 _DEFAULT_RAG_INDEX_DIR = Path("data/processed/faiss_index")
 _AGENT_MODEL_ENV = "NEUROBRIDGE_AGENT_MODEL"
-_AGENT_DEFAULT_MODEL = "google/gemini-2.0-flash-exp:free"
+_AGENT_DEFAULT_MODEL = "openai/gpt-oss-20b:free"
+# Fallback chain probed at orchestrator-build time. First model returning a
+# non-404/429 ping wins. Override via NEUROBRIDGE_AGENT_MODEL env (single id)
+# or NEUROBRIDGE_AGENT_MODEL_CHAIN (comma-separated).
+_AGENT_FALLBACK_CHAIN: tuple[str, ...] = (
+    "openai/gpt-oss-20b:free",
+    "minimax/minimax-m2.5:free",
+    "tencent/hy3-preview:free",
+    "inclusionai/ling-2.6-1t:free",
+    "nvidia/nemotron-3-super-120b-a12b:free",
+    "qwen/qwen3-next-80b-a3b-instruct:free",
+    "google/gemma-4-31b-it:free",
+    "meta-llama/llama-3.3-70b-instruct:free",
+)
+
+
+def _pick_working_agent_model(client: Any, candidates: tuple[str, ...]) -> str:
+    """Return the first candidate that responds to a tiny ping; else last one."""
+    for m in candidates:
+        try:
+            client.chat.completions.create(
+                model=m,
+                messages=[{"role": "user", "content": "OK"}],
+                max_tokens=4, temperature=0,
+            )
+            logger.info("agent model selected: %s", m)
+            return m
+        except Exception as e:
+            logger.info("agent model unavailable: %s (%s)", m, type(e).__name__)
+    logger.warning("no agent model responded; falling back to %s", candidates[-1])
+    return candidates[-1]
 
 
 def _build_orchestrator():
@@ -742,7 +772,20 @@ def _build_orchestrator():
         rag_index_dir=rag_dir,
         clinical_rag_index_path=clinical_idx if clinical_idx.exists() else None,
     )
-    model = os.environ.get(_AGENT_MODEL_ENV, _AGENT_DEFAULT_MODEL)
+    # Resolve agent model. NEUROBRIDGE_AGENT_MODEL overrides; otherwise probe
+    # the fallback chain (NEUROBRIDGE_AGENT_MODEL_CHAIN env to override the
+    # candidate list) and pick the first one that responds. Demo robustness:
+    # OpenRouter free-tier IDs churn; this avoids hard-coding a stale id.
+    explicit = os.environ.get(_AGENT_MODEL_ENV)
+    if explicit:
+        model = explicit
+    else:
+        chain_raw = os.environ.get("NEUROBRIDGE_AGENT_MODEL_CHAIN")
+        chain = (
+            tuple(s.strip() for s in chain_raw.split(",") if s.strip())
+            if chain_raw else _AGENT_FALLBACK_CHAIN
+        )
+        model = _pick_working_agent_model(client, chain)
     return Orchestrator(
         llm_client=client,
         tools=tools,

src/frontend/app.py

@@ -1208,10 +1208,7 @@ def _render_eeg_tab() -> None:
         "Input FIF/EDF path",
         "tests/fixtures/eeg_sample.fif",
         key="eeg_in",
-        help=(
-            "Defaults to the bundled EEG fixture so the demo runs out of "
-            "the box. Replace with your own .fif/.edf path on a real run."
-        ),
+        help="Path to a .fif/.edf EEG recording on the server filesystem.",
     )
     eeg_out = st.text_input(
         "Output Parquet path",
@@ -1320,10 +1317,6 @@ def _render_mri_tab() -> None:
 
     st.markdown("#### MRI Image Model")
     mri_kind = os.environ.get("MRI_MODEL_KIND", "volumetric_onnx")
-    st.caption(
-        f"Active backend: `{mri_kind}` — set `MRI_MODEL_KIND=resnet18_2d` "
-        "to switch to the 2D 4-class Alzheimer's classifier."
-    )
 
     if mri_kind == "resnet18_2d":
         mri_image = st.text_input(
@@ -1380,8 +1373,7 @@ def _render_mri_tab() -> None:
             "Resize W", min_value=1, max_value=256, value=64, step=1, key="mri_predict_w"
         )
         st.caption(
-            "Defaults to 64³ for production exports. Use 8³ when testing with the "
-            "dummy ONNX fixture from `tests/fixtures/build_dummy_mri_onnx.py`."
+            "Resize target as (D, H, W). Default 64³ matches typical model exports."
         )
         if st.button("Predict MRI image", key="mri_predict"):
             labels = [x.strip() for x in mri_labels.split(",") if x.strip()]
@@ -1416,9 +1408,8 @@ def _render_mri_tab() -> None:
 
     st.markdown("#### EEG Pretrained Classifier")
     st.caption(
-        "Stub-able for the demo: drop a sklearn `predict_proba` joblib at "
-        "`data/processed/eeg_clf.joblib` (or set `EEG_CLF_ARTIFACT`). Default "
-        "labels are `(control, alzheimers)` — override via `EEG_CLF_LABELS`."
+        "Pretrained sklearn classifier on EEG band-power features. "
+        "Output: per-class probabilities for `(control, alzheimers)`."
     )
     eeg_csv = st.text_area(
         "EEG features (comma-separated)",

src/llm/explainer.py

@@ -63,6 +63,7 @@ _LLM_TEMPERATURE = 0.3
 # Entries marked "currently 429" have valid IDs but were quota-exhausted at
 # probe time; kept because OpenRouter rate-limits are per-window and recover.
 _DEFAULT_FREE_MODEL_CHAIN: tuple[str, ...] = (
+    "openai/gpt-oss-20b:free",                             # 20B — verified OK 2026-05-02
     "inclusionai/ling-2.6-1t:free",                        # ~1T flagship — verified OK, returns content
     "nvidia/nemotron-3-super-120b-a12b:free",              # 120B — verified OK, returns content
     "minimax/minimax-m2.5:free",                           # MoE — verified OK, returns content