README.md

metadata

title: NeuroBridge Enterprise
emoji: 🧠
colorFrom: blue
colorTo: indigo
sdk: docker
app_file: src/frontend/app.py
app_port: 7860
pinned: false
license: mit
short_description: Living decision system for BBB, EEG, and MRI clinical ML

NeuroBridge Enterprise

Trust-engineered clinical-ML platform for neuroscience labs and health systems.

Executive Summary

1. Multi-site clinical ML pipelines fail in production because they assume clean data, single-site distributions, and black-box trust — all of which break in real labs. NeuroBridge Enterprise is the living decision system that closes those three gaps end-to-end across BBB drug-screening, EEG signal-cleaning, and MRI multi-site harmonization.

2. Three production pipelines (RDKit + Morgan, MNE+ICA, neuroHarmonize ComBat) sit behind one FastAPI surface and one Streamlit dashboard, with decision layers on top: a Random Forest BBB classifier today and an MRI image ONNX inference surface ready for an externally-trained volumetric deep-learning model. The agent surface can route a user request to exactly one pipeline tool, retrieve FAISS-backed context, and synthesize a cited answer.

3. Robustness is demoed live: a curated edge-case dropdown probes invalid SMILES, OOD molecules, and boundary inputs — the system never crashes, always degrades gracefully (HTTP 400 → recoverable warning, low confidence + lower drift score, calibration caption hedge).

4. Adapt-Over-Time is built in: each FastAPI worker keeps a rolling 100-prediction window; the trailing median is z-scored against the train-time confidence distribution and surfaced both in the API response and the UI ("trailing-100 confidence median is +1.42σ from training distribution — mild distribution shift").

5. Current verification: 330 passed, 2 skipped. Demo lifelines (NEUROBRIDGE_DISABLE_MLFLOW=1, NEUROBRIDGE_DISABLE_LLM=1, BBB_MODEL_PATH, MRI_MODEL_PATH, MRI_MODEL_PATH_2D, EEG_CLF_ARTIFACT, CLINICAL_RAG_INDEX_PATH) keep the system usable when MLflow, OpenRouter, or model artifacts are unavailable.

Status

Day	Modality	Pipeline	Status
1	Tabular (BBB / molecules)	bbb_pipeline.py	Shipped
2	Signal (EEG)	eeg_pipeline.py	Shipped
3	Image (MRI / fMRI)	mri_pipeline.py	Shipped
4	API + MLOps + Frontend	FastAPI + MLflow + Streamlit + Docker	Shipped
5	Decision Layer (Model + XAI + Interactive UI)	bbb_model.py — RandomForest + SHAP + POST /predict/bbb	Shipped
6	Final Polish & Demo Features (Edge cases + Calibration + ComBat viz)	Calibration metadata + edge-case probes + POST /pipeline/mri/diagnostics	Shipped
7	Final 5% (Drift, Traceability & Agents)	Per-worker drift z-score + MLflow provenance badge + POST /explain/bbb (LLM + template fallback) + AI Assistant tab	Shipped
8	Grand Finale (Multi-Modal Agents, Track 5 & Public Deploy)	Multi-modal explainers + experiments + deploy surface	Shipped
9	Agent/RAG hardening + MRI DL decision layer	Guarded orchestration + POST /predict/mri ONNX surface	Shipped — 242 passed, 2 skipped
10	Multi-modal fusion engine	POST /fusion/predict + run_fusion agent tool — MRI + EEG + clinical scores → per-disease confidence with attribution	Shipped — 295 passed, 1 skipped
11	External assets integration	2D resnet18 MRI Alzheimer's path · TF-IDF clinical RAG with TR query expansion · stub-able EEG pretrained classifier	Shipped — 330 passed, 2 skipped
12	DCE-MRI BBB bridge + drug-dose adjuster	POST /predict/bbb_permeability_map (heuristic_proxy or dce_onnx) + POST /research/drug_dose_adjustment + Researcher Streamlit tab + compute_bbb_leakage_score & adjust_drug_dose agent tools	Shipped

Fusion Engine

POST /fusion/predict (and the agent tool run_fusion) combines whichever of MRI, EEG, and clinical-test scores (MMSE, MoCA, UPDRS, gait, age) the doctor has uploaded into a per-disease confidence (Alzheimer's, Parkinson's, other) with full attribution showing how much each modality contributed. Missing modalities are skipped, not imputed — the engine renormalises onto whichever inputs are present so absence naturally lowers confidence rather than silently inflating it. Weights live in src/fusion/weights.py and are heuristic — adjust there. BBB is intentionally NOT a fusion modality: it is a researcher-side concern (drug permeability) and stays decoupled from disease classification.

MRI Deep-Learning Backends

The MRI prediction route supports two backends, selected via env at request time:

• MRI_MODEL_KIND=volumetric_onnx (default). Loads an ONNX volumetric model from MRI_MODEL_PATH (default data/processed/mri_model.onnx). Input: .nii / .nii.gz. Two-class output by default (control, abnormal).
• MRI_MODEL_KIND=resnet18_2d. Loads a PyTorch state_dict from MRI_MODEL_PATH_2D (default data/processed/mri_dl_2d/best_model.pt). Input: 2D image (.png / .jpg). 4-class Alzheimer's classifier: MildDemented, ModerateDemented, NonDemented, VeryMildDemented. Trainer's BEST_PARAMS bake in: image_size=160, ImageNet normalisation, resnet18 backbone with a 4-class head.

The Streamlit Predict tab auto-adapts its form to the active backend. Switch backends without restarting workers — env is read on each request.

Clinical Corpus (TF-IDF, Turkish + English)

A second RAG index covers 14 peer-reviewed PDFs (Alzheimer's, Parkinson's, lifestyle, nutrition, exercise) using TF-IDF + sklearn. Source PDFs at data/external_rag/clinical_pdfs/ (gitignored — copy from the team shared drive); pre-built index at data/external_rag/index/rag_index.pkl.

Agent invocation:

retrieve_context(query="egzersiz Alzheimer feedback", corpus="clinical", k=5)

Local CLI smoke:

python scripts/clinical_rag_smoke.py "egzersiz Alzheimer feedback"

The Turkish keywords alzheimer, parkinson, egzersiz, beslenme, tani, tedavi, risk, unutkanlik, titreme, demans auto-expand to English equivalents so Turkish queries hit English chunks.

DCE-MRI BBB Bridge + Drug-Dose Adjuster (Researcher persona)

Clinical fact: Dynamic Contrast-Enhanced (DCE) MRI measures BBB leakage by tracking gadolinium contrast washout. A leaky BBB lets drugs cross into the brain at unsafe levels, so concentrations need revising.

This is the only legitimate place where BBB and MRI couple in the platform — the Researcher lane only. The fusion engine's "BBB is NOT a diagnostic modality" rule is preserved.

POST /predict/bbb_permeability_map — two modes:

• heuristic_proxy (default, demo-ready): reuses the 2D resnet18 Alzheimer's classifier; score = 1 - P(NonDemented). Anchored in the published correlation between disease severity and BBB breakdown.
• dce_onnx (real DCE artifact, swap-in later): loads an ONNX model trained on 4D DCE-MRI data, emits a Ktrans map normalised to [0, 1]. Drop the artifact at data/processed/bbb_permeability_dce.onnx (or set BBB_PERMEABILITY_DCE_PATH).

POST /research/drug_dose_adjustment — pure-function logic:

BBB score	Drug BBB-permeable	Recommended dose
< 0.20 (intact)	any	100% of baseline (low risk)
≥ 0.20 (leaky)	yes	max(30%, 1 − 0.7·score) of baseline (moderate / high risk)
≥ 0.20 (leaky)	no	max(60%, 1 − 0.4·score) of baseline (moderate risk)
≥ 0.20 (leaky)	unknown	treated as permeable (safer assumption)

When smiles is supplied, the BBB classifier auto-resolves the drug's permeability — closes the researcher loop end-to-end. The rationale always includes the sentence "Research suggestion, not medical advice."

Streamlit Researcher tab combines both into a single 2-column flow: left side picks an MRI image and runs the leakage scorer; right side takes a SMILES + baseline dose and computes a revised dose with risk badge and rationale card.

Agent tools (orchestrator-callable):

• compute_bbb_leakage_score — wraps /predict/bbb_permeability_map.
• adjust_drug_dose — wraps /research/drug_dose_adjustment.

EEG Pretrained Classifier (stub-able for demo)

POST /predict/eeg runs an sklearn-style classifier (any predict_proba interface) on a feature vector and returns probability + attribution. The artifact loads from data/processed/eeg_clf.joblib (override via EEG_CLF_ARTIFACT). Default labels are (control, alzheimers) — override via EEG_CLF_LABELS=label0,label1,....

For the hackathon demo a synthetic stub (tests/fixtures/build_dummy_eeg_clf.py) is acceptable — drop the real .joblib at the artifact path to swap in production weights with zero code changes. The fusion engine consumes this prediction as the eeg modality automatically.

Quick Start

Prerequisite: Python 3.10–3.12. The pinned requirements.txt has no cp313+ wheels; .python-version pins to 3.12.

# 1. Create venv and install
python3.12 -m venv .venv312 && source .venv312/bin/activate && pip install -r requirements.txt

# 2. Verify — current full suite: 330 passed, 2 skipped
pytest -v

# 3. Smoke run with the bundled 6-row fixture
mkdir -p data/raw && cp tests/fixtures/bbbp_sample.csv data/raw/bbbp.csv
python -m src.pipelines.bbb_pipeline

# 4. Inspect the output at data/processed/bbbp_features.parquet
python -c "import pandas as pd; df = pd.read_parquet('data/processed/bbbp_features.parquet'); print(df.shape, df.dtypes.head())"

Result lives at data/processed/bbbp_features.parquet.

# Smoke-test the EEG pipeline with the bundled fixture (5 ch synthetic .fif)
mkdir -p data/raw
cp tests/fixtures/eeg_sample.fif data/raw/eeg.fif
python -m src.pipelines.eeg_pipeline

Result lives at data/processed/eeg_features.parquet.

# Smoke-test the MRI pipeline with the bundled fixture (6 subjects × 2 sites)
mkdir -p data/raw/mri
cp tests/fixtures/mri_sample/* data/raw/mri/
python -m src.pipelines.mri_pipeline

Result lives at data/processed/mri_features.parquet (48 ROI features per subject, ComBat-harmonized across sites).

Real BBBP data: not bundled (gitignored). Download from Kaggle or MoleculeNet; place as data/raw/bbbp.csv.

Train the downstream BBB model (one-time)

python -m src.pipelines.bbb_pipeline   # produces data/processed/bbbp_features.parquet
python -m src.models.bbb_model          # produces data/processed/bbb_model.joblib

Then POST /predict/bbb (and the Streamlit BBB tab) become live. Try:

curl -s -X POST http://localhost:8000/predict/bbb \
  -H 'Content-Type: application/json' \
  -d '{"smiles": "CCO", "top_k": 5}' | python3 -m json.tool

Add the MRI image deep-learning model

MRI deep-learning training happens outside this repository. Export the trained volumetric model to ONNX and place it at:

data/processed/mri_model.onnx

The runtime contract is:

• Input file: one .nii / .nii.gz MRI volume.
• Preprocess: trilinear resize to target_shape (default [64, 64, 64]), z-score normalization over non-zero voxels, then tensor shape [1, 1, D, H, W].
• ONNX output: one class vector [1, C], either logits or probabilities.
• Override artifact path with MRI_MODEL_PATH=/path/to/model.onnx.

Try the endpoint after adding the artifact:

curl -s -X POST http://localhost:8000/predict/mri \
  -H 'Content-Type: application/json' \
  -d '{
    "input_path": "tests/fixtures/mri_sample/subject_0.nii.gz",
    "target_shape": [64, 64, 64],
    "label_names": ["control", "abnormal"]
  }' | python3 -m json.tool

If the ONNX artifact is missing, the endpoint returns HTTP 503 with a remediation hint instead of crashing.

Run the full stack with Docker

docker compose up

Then browse to:

• FastAPI Swagger — http://localhost:8000/docs
• Streamlit dashboard — streamlit run src/frontend/app.py (port 8501; not in compose by default)
• MLflow UI — http://localhost:5000

Live-demo robustness: if the MLflow service is unreachable, set NEUROBRIDGE_DISABLE_MLFLOW=1 to make the pipelines run without tracking.

The container startup script also protects local demos with a mounted ./data directory: if the host volume is empty, it seeds fixture data, trains the BBB model artifact, and builds the RAG FAISS index before launching the app.

Runtime Configuration

Variable	Purpose
BBB_MODEL_PATH	Override the BBB joblib artifact path (data/processed/bbb_model.joblib).
MRI_MODEL_PATH	Override the MRI ONNX artifact path (data/processed/mri_model.onnx).
OPENROUTER_API_KEY	Enables LLM explainer and orchestrator agent calls through OpenRouter.
OPENROUTER_FREE_MODELS	Optional comma-separated fallback chain for the explainer.
NEUROBRIDGE_AGENT_MODEL	OpenRouter model id for /agent/run.
NEUROBRIDGE_DISABLE_LLM=1	Forces deterministic template explanations.
NEUROBRIDGE_DISABLE_MLFLOW=1	Skips MLflow tracking/lookups when the tracking service is unavailable.

Repository Layout

.
├── AGENTS.md                 # Project contract (vision, layout, code & data rules) — read first
├── README.md                 # this file
├── requirements.txt          # Pinned deps; Python 3.10–3.12 only
├── .python-version           # 3.12
├── pytest.ini
├── data/
│   ├── raw/                  # vendor inputs (CSV / EDF / NIfTI); gitignored
│   └── processed/            # Parquet outputs from pipelines; gitignored
├── docs/superpowers/plans/   # Per-day implementation plans
├── src/
│   ├── core/                 # logger, deterministic storage, MLflow tracking
│   ├── pipelines/
│   │   ├── bbb_pipeline.py   # Day-1 pipeline (4 public funcs + CLI entry)
│   │   ├── eeg_pipeline.py   # Day-2 pipeline (6 public funcs + CLI entry)
│   │   └── mri_pipeline.py   # Day-3 pipeline (5 public funcs + CLI entry)
│   ├── models/
│   │   ├── bbb_model.py      # RandomForest BBB classifier + SHAP
│   │   └── mri_model.py      # External ONNX MRI inference surface
│   ├── rag/                  # fastembed + FAISS ingest/retrieve layer
│   ├── agents/               # OpenRouter orchestrator + guarded routing + tools
│   ├── llm/                  # LLM/template explanation surface
│   ├── api/                  # FastAPI routes + schemas
│   └── frontend/             # Streamlit dashboard
└── tests/
    ├── core/, pipelines/, models/, rag/, agents/
    └── fixtures/          # bbbp_sample.csv, eeg_sample.fif, mri_sample/ + build_*.py

BBB Pipeline (Day 1)

Function	Purpose
is_valid_smiles(smiles)	Returns True iff the input is a non-empty SMILES that RDKit can parse. Handles None, NaN, and garbage strings.
compute_morgan_fingerprint(smiles, n_bits, radius)	Returns a (n_bits,) uint8 numpy array using the modern MorganGenerator API.
extract_features_from_dataframe(df, smiles_col, n_bits, radius)	Drops invalid rows (logged WARNING with truncated index list), expands fingerprints into fp_0..fp_{n-1} columns, preserves metadata. Returns a model-ready pd.DataFrame.
run_pipeline(input_path, output_path, smiles_col, n_bits, radius)	End-to-end CSV → Parquet orchestrator. Idempotent; raises on missing input or directory output.

All four functions log via src.core.logger.get_logger(__name__) per AGENTS.md §3 and satisfy the §4 Data Readiness contract (5 invariants: schema validity, domain validity, determinism, traceability, idempotence).

EEG Pipeline (Day 2)

Function	Purpose
is_valid_epoch(epoch)	Returns True iff the input is a finite, numeric, non-empty 2-D array. Rejects NaN/inf, non-numeric dtypes, lists/scalars.
bandpass_filter(raw, l_freq, h_freq)	Non-mutating MNE bandpass (default 1–40 Hz). Raises ValueError on inverted frequency range.
remove_artifacts_with_ica(raw, eog_ch_name, n_components, random_state)	Seeded ICA + correlation-based EOG component rejection. Skips gracefully (no-op + WARNING) on missing/typo EOG channel or NaN-contaminated data.
compute_features_from_epoch(epoch, sfreq)	Per-channel PSD bands (delta/theta/alpha/beta/gamma) + 5 statistical moments (mean/std/var/skew/kurtosis). Constant-channel safe (NaN-cleaned).
extract_features_from_recording(raw, epoch_duration_s, eog_ch_name, n_components, random_state)	Chains filter → ICA → epoching → feature extraction. Drops invalid epochs (logged WARNING with truncated index list). Returns 2-D pd.DataFrame with deterministic feat_<channel>_psd_<band> and feat_<channel>_<stat> columns.
run_pipeline(input_path, output_path, ...)	End-to-end FIF/EDF → Parquet orchestrator. Idempotent; raises on missing input or directory output.

The pipeline is seeded (random_state=97) and produces byte-identical Parquet output for the same input — satisfying the §4 Determinism contract. Output is float64, preserved through the Parquet round-trip.

MRI Pipeline (Day 3)

Function	Purpose
is_valid_volume(volume)	Returns True iff input is a finite, numeric, non-empty 3-D ndarray. Rejects NaN/inf, non-numeric dtypes, lists/scalars.
mask_brain(volume, intensity_threshold)	Two-step brain mask: intensity threshold (default = volume mean) + 6-connectivity morphological opening to drop isolated noise voxels. WARNs if mask is empty.
extract_features_from_volume(volume, mask, n_roi_axes)	Partitions the masked volume into prod(n_roi_axes) axis-aligned octants (default 2×2×2 = 8) and emits 6 stats per ROI: mean / std / p10 / p50 / p90 / voxel_count. Empty ROIs → 0.0 (no NaN). Single source of truth via _ROI_STATS_FUNCS.
harmonize_combat(features, sites, feature_cols)	Wraps neuroHarmonize.harmonizationLearn with np.round(14) defensive determinism boundary. Removes site-level domain shift on the named columns. Raises if <2 sites or empty feature_cols or row/site length mismatch.
run_pipeline(input_dir, sites_csv, output_path, ...)	End-to-end NIfTI directory → ComBat-harmonized Parquet orchestrator. Drops invalid volumes with logged WARNING. Splits feature columns on a _MIN_VAR_THRESHOLD = 1e-8 variance floor (constant columns bypass ComBat to avoid NaN). Idempotent; raises on missing input or directory output.

Output schema: one row per surviving subject with columns subject_id, site, feat_roi{i}_<stat> (8 ROIs × 6 stats = 48 features). All feat_* are float64 (preserved through the Parquet round-trip).

MRI Image Model

src/models/mri_model.py is intentionally separate from mri_pipeline.py. The pipeline remains the deterministic ComBat feature-preparation surface. The image model is a decision layer for externally-trained volumetric DL models:

Function	Purpose
load(path)	Loads an ONNX artifact with onnxruntime CPU execution.
load_nifti_volume(path)	Reads one .nii / .nii.gz volume as float32.
preprocess_volume(volume, target_shape)	Validates 3-D finite data, resizes, z-scores, returns [1, 1, D, H, W].
predict_nifti(model, input_path, target_shape, label_names)	Runs preprocessing + ONNX inference and returns label, confidence, probabilities.

Public API: POST /predict/mri. Streamlit exposes it in the Image tab under "MRI Image Model". The trained artifact is not committed; put it in data/processed/mri_model.onnx or set MRI_MODEL_PATH.

Storage Format

Pipeline outputs are written as Parquet files using the pyarrow engine with snappy compression. This preserves dtypes (uint8 fingerprint columns stay uint8 instead of widening to int64 as CSV would do) and yields ~10× smaller files than CSV — material for the float64 EEG features Day 2 produces. See AGENTS.md §6.

Testing & TDD

All pipeline functions and the shared logger were built TDD-first across Days 1–3 (RED → GREEN → REFACTOR). Each task ended in a green commit; review-and-fix loops landed as separate commits with fix: / refactor: prefixes. Run pytest -v at any time. Current verification on Windows/Python 3.11: 242 passed, 2 skipped.

Roadmap

• Day 2 (shipped): eeg_pipeline.py — bandpass + MNE ICA artifact removal + PSD + statistical features → Parquet.
• Day 3 (shipped): mri_pipeline.py — NIfTI volume loading, brain masking, ROI feature extraction, ComBat harmonization (neuroHarmonize) for site-level domain shift → Parquet.
• Day 4 (shipped): FastAPI surface in src/api/ (POST /pipeline/{bbb,eeg,mri} + /health), MLflow experiment tracking via src.core.tracking (see AGENTS.md §7), Streamlit dashboard at src/frontend/app.py, and Docker / docker-compose.yml for the api + MLflow stack.
• Day 5 (shipped): Decision layer in src/models/bbb_model.py — RandomForest BBB classifier on Morgan fingerprints, SHAP top-k explanations, POST /predict/bbb endpoint, interactive Streamlit BBB tab with SMILES input + decision card + SHAP bar chart, and trainer CLI (python -m src.models.bbb_model). See AGENTS.md §8.
• Day 6 (shipped): Final polish & demo features — calibration metadata bins on the BBB classifier (precision-at-confidence in BBBPredictResponse.calibration), edge-case dropdown in the Streamlit BBB tab (5 curated robustness probes), trust caption on the decision card, and POST /pipeline/mri/diagnostics returning Pre/Post ComBat long-format data + site-gap KPIs visualized as a faceted altair KDE in the MRI tab. See AGENTS.md §8 (calibration) + §9 (demo features).
• Post-Day-8 hardening (shipped): Orchestrator workflow guard enforces pipeline → RAG → synthesis even when the LLM skips tool calls; Docker startup guard rebuilds missing demo artifacts behind a mounted data/; Windows-safe MLflow test URI; MRI ONNX image decision layer at POST /predict/mri — 242 passed, 2 skipped.

Where to Look

• Project rules (mandatory reading for any agent): AGENTS.md
• Day-1 plan (full TDD task breakdown): docs/superpowers/plans/2026-04-29-neurobridge-day1-bootstrap-bbb-pipeline.md
• Day-2 plan (full TDD task breakdown): docs/superpowers/plans/2026-04-30-day2-eeg-mne-ica-pipeline.md
• Logger contract: src/core/logger.py + tests/core/test_logger.py
• BBB pipeline: src/pipelines/bbb_pipeline.py + tests/pipelines/test_bbb_pipeline.py
• EEG pipeline: src/pipelines/eeg_pipeline.py + tests/pipelines/test_eeg_pipeline.py
• Day-3 plan (full TDD task breakdown): docs/superpowers/plans/2026-05-01-day3-mri-combat-pipeline.md
• MRI pipeline: src/pipelines/mri_pipeline.py + tests/pipelines/test_mri_pipeline.py
• Day-4 plan (full TDD task breakdown): docs/superpowers/plans/2026-05-02-day4-api-mlops-frontend.md
• Shared core helpers: src/core/determinism.py, src/core/storage.py, src/core/tracking.py
• FastAPI surface: src/api/main.py, src/api/routes.py, src/api/schemas.py
• Streamlit dashboard: src/frontend/app.py
• Container stack: Dockerfile, docker-compose.yml
• Day-4 tests: tests/api/, tests/frontend/, tests/pipelines/test_cross_pipeline_smoke.py
• Day-5 plan (full TDD task breakdown): docs/superpowers/plans/2026-05-03-day5-downstream-model-xai-interactive.md
• BBB downstream model (classifier + SHAP explainer + trainer CLI): src/models/bbb_model.py + tests/models/test_bbb_model.py
• MRI image DL decision layer: src/models/mri_model.py + tests/models/test_mri_model.py; POST /predict/mri consumes an externally-trained ONNX artifact at data/processed/mri_model.onnx (MRI_MODEL_PATH override).
• Day-6 plan (full TDD task breakdown): docs/superpowers/plans/2026-05-04-day6-final-polish-demo-features.md
• MRI ComBat diagnostics surface (pre/post site-gap KPIs): POST /pipeline/mri/diagnostics — see src/api/routes.py + src/pipelines/mri_pipeline.py
• Day-7 design spec: docs/superpowers/specs/2026-05-05-day7-drift-traceability-agents-design.md
• Day-7 plan (full TDD task breakdown): docs/superpowers/plans/2026-05-05-day7-drift-traceability-agents.md
• New surface: POST /explain/bbb — natural-language rationale (LLM + deterministic fallback)
• New surface: drift_z / rolling_n / provenance fields in POST /predict/bbb response
• Day-8 plan (full TDD task breakdown): docs/superpowers/plans/2026-05-06-day8-grand-finale.md
• New surfaces: POST /explain/eeg, POST /explain/mri, GET /experiments/runs, POST /experiments/diff
• New deploy artifacts: Dockerfile.hf, supervisord.conf
• LLM hardening (post-Day 8): real OpenRouter LLM is now the default in deployed Spaces — Dockerfile/Dockerfile.hf no longer hard-code NEUROBRIDGE_DISABLE_LLM=1. Free-tier fallback chain (10 models, smartest → smallest) in src/llm/explainer.py, 401/400 status classification, and language-matching / intent-split prompt. Diagnostic endpoint GET /diag/openrouter (src/api/main.py) + Streamlit sidebar "🔧 Diagnose LLM" button. Live verification helper: scripts/diagnose_openrouter.py.
• Orchestrator agent (Task 13): src/agents/orchestrator.py, src/agents/routing.py, src/agents/tools.py, src/agents/prompts.py. Guarded workflow enforces one pipeline tool, then retrieve_context, then final synthesis.
• RAG layer: src/rag/ — chunker, embedder (fastembed), FAISS store, retriever, ingest CLI
• Agent endpoint: POST /agent/run (orchestrator + RAG); diagnostic at GET /diag/agent
• Streamlit Agent tab: "🤖 Agent" tab in src/frontend/app.py — input box + optional MRI sites_csv + decision-trace expander.
• RAG knowledge base: drop .md/.pdf into data/knowledge_base/ — see its README

Day 7 — Demo Recipe

Pre-flight (one terminal):

# Start API. With OPENROUTER_API_KEY set in your shell or .env,
# /explain/* hits the real LLM via the free-tier fallback chain
# (10 models, smartest → smallest — see AGENTS.md §11). Without
# a key, falls back to the deterministic template.
BBB_MODEL_PATH=data/processed/bbb_model.joblib \
  uvicorn src.api.main:app --port 8000

# Force the deterministic template path (no network, fully reproducible):
#   NEUROBRIDGE_DISABLE_LLM=1 BBB_MODEL_PATH=... uvicorn ...

Predict + explain (other terminal):

# 1) Predict — body now carries drift_z, rolling_n, provenance
curl -s -X POST http://localhost:8000/predict/bbb \
  -H "Content-Type: application/json" \
  -d '{"smiles": "CCO", "top_k": 5}' | jq

# 2) Explain — feed the predict response back as the explain payload.
#    user_question drives the prompt: question language is mirrored
#    (Turkish question → Turkish answer), and the model answers the
#    question directly instead of returning a canned paper summary.
curl -s -X POST http://localhost:8000/explain/bbb \
  -H "Content-Type: application/json" \
  -d '{
    "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}
    ],
    "drift_z": 0.42,
    "user_question": "Why permeable?"
  }' | jq
# With a valid key: expect "source": "llm" + a model id from the chain.
# Without:          expect "source": "template" + "model": null.

# 3) Diagnose OpenRouter reachability from inside the running API
#    (key presence, chain head, 8-token probe). Surfaced in Streamlit
#    as the sidebar "🔧 Diagnose LLM" button.
curl -s http://localhost:8000/diag/openrouter | jq

Streamlit demo: streamlit run src/frontend/app.py → BBB tab → Predict → AI Assistant tab → ask a preset question.

Drift demo: refresh the BBB tab and predict 10+ times in a row — the drift caption transitions from "warming up" to a numeric z-score.

Demo Scripts

90-Second Jury Tour

Choreography for the live demo. Click order matters; every claim has a numeric receipt visible on screen.

t	Tab	Action	Talking point
0:00	(open)	streamlit run src/frontend/app.py already launched	"This is NeuroBridge Enterprise — three modalities behind one decision system."
0:05	BBB	Pick "Custom input" → enter CCO → click Predict	Show label + 82% confidence progress bar.
0:15	(same)	Read calibration caption	"Predictions ≥80% confident are correct 92% of the time on held-out data — n=18."
0:22	(same)	Read drift caption	"Trailing-100 confidence median is +0.42σ from train — within expected range."
0:30	(same)	Read provenance badge	"MLflow run abc123, Model v1, n=1640 examples — full audit trail."
0:35	(same)	Switch to "Massive OOD: cyclosporine-like macrocycle" → Predict	"Cyclosporine has 11 residues, ~1.2 kDa — way outside training distribution."
0:45	(same)	Read confidence + drift	"System knows what it doesn't know — confidence drops, drift signal flags it."
0:55	AI Assistant	Pick preset "Why was this molecule predicted as permeable?" → Ask	"LLM rationale uses SHAP attributions + drift context — auditable source label."
1:10	MRI	Click "Run ComBat diagnostics"	Show 3-metric strip: Pre 5.0 → Post 0.0015 → 3290× reduction.
1:20	(same)	Point to faceted KDE	"Each color is a hospital. Pre-ComBat panels diverge; Post panels converge."
1:30	Experiments	Switch tabs, show MLflow runs table	"Every train run is logged; pick any two for a metric/param diff."

30-Second Drift Detection Show

Standalone demo of the "Adapt Over Time" capability.

t	Action	What jury sees
0:00	Open BBB tab.	Drift caption shows "warming up (0/10 predictions buffered)".
0:05	Hit Predict 10× rapidly with the same SMILES (CCO).	After predict #10, drift caption switches to a numeric z-score.
0:18	Switch to "Cyclosporine OOD" → predict 3× more.	Drift z-score rises in magnitude; if `
0:30	Conclude.	"The system is online-aware — it doesn't just predict, it tells you when its own predictions are drifting from the world it was trained on."