EHR Risk Framework

Architecture

Package openhealth · CLI ehr-ai · Angular workbench · FastAPI. Research / education prototype — not a medical device.

System context

Entry surfaces share one FastAPI layer and ML core; artifacts stay on the host filesystem.

Researcher or developer reaches FastAPI via browser (:8080), CLI (ehr-ai), or OpenAPI (:8000). The API routes jobs, datasets, predict, and config into the ML core (feature engineering, training, models, explainability, fairness), which reads and writes artifacts such as model.pkl, reports/, config/workspace.yaml, data/raw, and data/uploads.

Docker topology

docker compose up --build starts prepare, then API and web side by side.

Compose builds prepare (trains model.pkl if missing), api on :8000 (ehr-risk-api:local), and web on :8080 (ehr-risk-web:local); nginx proxies /v1 to the API.

ML pipeline

  1. Ingest — demo CSV / upload / form / SQL / map
  2. Health — readiness blockers & warnings
  3. Features — multi-window aggregates truncated at index time
  4. Train / compare — calibrated models, manifests, runs
  5. Trust — leakage audit, SHAP, calibration plots
  6. Serve — schema + predict + workbench

Key paths

AreaPath
Frameworkopenhealth/, tasks/, config/
MLtraining/, feature_engineering/, models/
API / jobsapi/
UIweb/
Trust scriptsscripts/leakage_audit.py, explain_shap.py
This sitedocs/

Canonical long-form: repository ARCHITECTURE.md. Visual diagrams: Diagrams. Model iteration: Fine-tuning.