Deploy v2: multimodal ensemble router (Framingham tabular + ECG ResNet)

Dockerfile

@@ -1,18 +1,19 @@
-FROM python:3.11-slim
-
-WORKDIR /app
-
-# Install dependencies
-COPY requirements.txt .
-RUN pip install --no-cache-dir -r requirements.txt
-
-# Copy application files
-COPY app.py .
-COPY model.pkl .
-COPY static/ static/
-
-# Hugging Face Spaces expects port 7860
-EXPOSE 7860
-
-# Start the server
-CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]
+FROM python:3.11-slim
+
+WORKDIR /app
+
+# Install dependencies
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# Copy application files (v2 multimodal ensemble router)
+COPY app.py .
+COPY inference/ inference/
+COPY models/ models/
+COPY static/ static/
+
+# Hugging Face Spaces expects port 7860
+EXPOSE 7860
+
+# Start the server
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,432 +1,289 @@
----
-title: Heart Attack Risk Predictor
-emoji: 🫀
-colorFrom: blue
-colorTo: purple
-sdk: docker
-app_file: app.py
-pinned: false
----
-
-<h1 align="center">🫀 Heart Attack Risk Predictor</h1>
-
-<p align="center">
-  <strong>An AI-powered clinical decision-support tool that predicts a patient's heart attack risk level (High, Moderate, or Low) based on 8 vital signs and cardiac biomarkers, served as a real-time web application powered by a Random Forest classifier and FastAPI.</strong>
-</p>
-
-<p align="center">
-  <a href="https://huggingface.co/spaces/Shahd1sayed/heart-attack-risk-predictor"><strong>🔴 TRY THE LIVE DEMO ON HUGGING FACE SPACES 🔴</strong></a>
-</p>
-
----
-
-## 📑 Table of Contents
-
-- [Key Features](#-key-features)
-- [Medical Background](#-medical-background)
-- [Tech Stack](#-tech-stack)
-- [Machine Learning Pipeline](#-machine-learning-pipeline)
-- [Project Structure](#-project-structure)
-- [Getting Started](#-getting-started)
-- [Usage](#-usage)
-- [Model Performance](#-model-performance)
-- [Dataset Description](#-dataset-description)
-- [Feature Importance](#-feature-importance)
-- [Team Members](#-team-members)
-
----
-
-## ✨ Key Features
-
-- **Real-Time Risk Prediction** — Enter 8 patient vitals and receive an instant heart attack risk classification (High / Moderate / Low) with confidence probabilities.
-- **Production-Grade REST API** — Built with FastAPI, featuring automatic request validation via Pydantic schemas, interactive Swagger docs, and ASGI-based async performance.
-- **Modern UI** — A dark-themed, responsive frontend with animated gradient blobs, color-coded risk badges (🔴 High / 🟡 Moderate / 🟢 Low), and animated probability bars.
-- **Bundled Model Artifact** — The trained model, scaler, and label encoders are serialized into a single `model.pkl` for zero-configuration deployment.
-- **Clinically Interpretable** — Feature importance rankings show exactly which vitals drive predictions, aligning with established cardiology literature.
-
----
-
-## 🏥 Medical Background
-
-### What Is a Heart Attack?
-
-A **heart attack** (myocardial infarction, MI) occurs when blood flow to a section of the heart muscle is blocked for an extended period, causing the heart tissue to die. It is the leading cause of death globally, accounting for approximately **17.9 million deaths per year** according to the World Health Organization (WHO).
-
-### Clinical Biomarkers Used in This Model
-
-This application leverages the same vital signs and biomarkers that emergency physicians use to triage cardiac patients:
-
-| Biomarker | Clinical Significance | Normal Range |
-|---|---|---|
-| **Age** | Risk increases significantly after age 45 (men) and 55 (women). Aging contributes to arterial stiffness, plaque buildup, and decreased cardiac output. | N/A |
-| **Gender** | Men have a statistically higher risk of MI at younger ages. Post-menopausal women see a sharp increase in risk due to declining estrogen levels. | Male / Female |
-| **Heart Rate** | Resting tachycardia (>100 bpm) is associated with increased cardiovascular mortality. Bradycardia (<60 bpm) may indicate conduction abnormalities. | 60–100 bpm |
-| **Systolic Blood Pressure** | Elevated systolic BP (hypertension) is a primary modifiable risk factor. It places chronic stress on arterial walls, accelerating atherosclerosis. | 90–120 mmHg |
-| **Diastolic Blood Pressure** | Elevated diastolic BP reduces coronary perfusion pressure and is independently associated with increased MI risk, especially in younger adults. | 60–80 mmHg |
-| **Blood Sugar (Glucose)** | Hyperglycemia (diabetes) accelerates endothelial dysfunction and atherosclerotic plaque formation. Diabetic patients have a 2–4× higher risk of cardiovascular events. | 70–140 mg/dL |
-| **CK-MB (Creatine Kinase-MB)** | A cardiac enzyme released into the bloodstream when the heart muscle is damaged. Elevated CK-MB (>5 ng/mL) within 4–8 hours of chest pain is a strong indicator of myocardial injury. | 0–5 ng/mL |
-| **Troponin** | The **gold standard** biomarker for diagnosing acute MI. Cardiac troponins (cTnI / cTnT) are structural proteins released during myocardial necrosis. Even slight elevations (>0.04 ng/mL) are diagnostic. Troponin levels peak at 12–24 hours post-MI. | <0.04 ng/mL |
-
-### Why Troponin and CK-MB Dominate
-
-In our trained model, **Troponin** (43.3% importance) and **CK-MB** (20.7% importance) together account for **64%** of the model's decision-making. This is medically consistent — cardiologists rely heavily on these two biomarkers to diagnose and classify MI severity. The `Risk_Level` labels in the dataset are likely derived from clinical threshold rules applied to these biomarkers, which explains the model's exceptionally high accuracy (~98.6%).
-
----
-
-## 🛠️ Tech Stack
-
-| Layer | Technology | Purpose |
-|---|---|---|
-| **Backend** | [FastAPI](https://fastapi.tiangolo.com/) | High-performance ASGI web framework with automatic OpenAPI docs |
-| **Server** | [Uvicorn](https://www.uvicorn.org/) | Lightning-fast ASGI server for production HTTP serving |
-| **ML Model** | [scikit-learn](https://scikit-learn.org/) `RandomForestClassifier` | Ensemble learning method for multi-class classification |
-| **Preprocessing** | [scikit-learn](https://scikit-learn.org/) `StandardScaler`, `LabelEncoder` | Feature normalization and categorical encoding |
-| **Model Comparison** | [XGBoost](https://xgboost.readthedocs.io/) | Gradient boosting framework used for benchmarking |
-| **Data Handling** | [pandas](https://pandas.pydata.org/), [NumPy](https://numpy.org/) | DataFrame manipulation and numerical computation |
-| **Validation** | [Pydantic](https://docs.pydantic.dev/) | Data validation and serialization for API request/response |
-| **Serialization** | Python `pickle` | Model persistence and bundling |
-| **Frontend** | HTML5, CSS3, Vanilla JavaScript | Responsive single-page application with glassmorphism design |
-
----
-
-## 🔬 Exploratory Data Analysis (EDA)
-
-The `research_and_experiments/heart_attack.ipynb` notebook contains a complete clinical EDA. Before training models, we analyzed the dataset visually to understand the true drivers of prediction:
-
-1. **Target Distribution:** The dataset is heavily skewed towards "High" Risk (61%), indicating collection from an acute care setting rather than a general population screening.
-2. **Demographics & Vitals:** Analysis showed that Age, Gender, Blood Pressure, and Heart Rate distributions overlap heavily across all risk categories. They are very poor independent predictors in this dataset.
-3. **The Smoking Gun (Biomarkers):** Log-scale visualizations of **Troponin** and **CK-MB** revealed the true predictive signal. Every single "Low" risk patient is clustered at the bottom, while "Moderate" and "High" risk explode upward past clinical diagnostic cutoffs.
-4. **Conclusion:** A mathematical correlation heatmap proved that the targets (`Risk_Level`) were likely labeled using medical threshold rules applied directly to Troponin and CK-MB.
-
----
-
-## 🤖 Machine Learning Pipeline & Model Architecture
-
-The core of this application is a **Random Forest Classifier**. We chose this architecture because it is highly robust against overfitting, handles non-linear relationships well, and naturally provides feature importance rankings (which is critical for medical explainability).
-
-The training pipeline (`research_and_experiments/train_model.py`) follows a rigorous, multi-stage workflow:
-
-### Stage 1 — Data Loading & Inspection
-```
-Raw dataset: 1,319 rows × 11 columns
-Target variable: Risk_Level (High / Moderate / Low)
-```
-
-### Stage 2 — Outlier Cleaning & Physiological Bounding
-Before training, we applied strict physiological bounds to remove erroneous data entries that could skew the model's decision trees:
-
-| Feature | Valid Range | Outliers Removed |
-|---|---|---|
-| Heart rate | 20–300 bpm | 3 (e.g., one row had 1,111 bpm) |
-| Systolic BP | 50–300 mmHg | 1 |
-| Age | 1–120 years | 0 |
-| CK-MB | 0–500 ng/mL | 0 |
-| Troponin | 0–50 ng/mL | 0 |
-
-**Result:** 1,319 → 1,315 rows (4 outliers removed)
-
-### Stage 3 — Encoding & Feature Scaling
-Machine learning models perform best when numerical data is on a similar scale. We separated the data into features (`X`) and target (`y`), and applied the following transformations:
-1. **Categorical Encoding:** `LabelEncoder` converted Gender (Female → 0, Male → 1) and Risk_Level (High → 0, Low → 1, Moderate → 2).
-2. **Standardization:** We applied `scikit-learn`'s `StandardScaler` to all 8 feature columns. This forces each column to have a mean of `0` and a variance of `1`. 
-   > *Crucially, this exact `StandardScaler` object was fitted on the training data and saved into the final bundle, ensuring that real-time API requests are scaled using the exact same mathematical parameters.*
-
-### Stage 4 — Model Selection & Hyperparameter Tuning (5-Fold Stratified CV)
-We did not just assume Random Forest was the best. We rigorously tested four different model configurations using **5-Fold Stratified Cross-Validation**. Stratification ensures each of the 5 testing folds maintains the exact class distribution (61% High, 21% Low, 18% Moderate) as the entire dataset.
-
-| Model | Hyperparameters | Mean CV Accuracy | Std Dev |
-|---|---|---|---|
-| **Random Forest (default)** | `n_estimators=200`, `max_depth=None` | **98.63%** | ±0.52% |
-| Random Forest (balanced) | `class_weight='balanced'` | 98.48% | ±0.59% |
-| XGBoost (default) | `learning_rate=0.1`, `max_depth=6` | 98.48% | ±0.48% |
-| XGBoost (balanced) | Default + `sample_weight` computed | 98.63% | ±0.52% |
-
-### Stage 5 — Final Training & Bundle Export
-The winning model configuration (**Random Forest, 200 estimators, no strict class weighting**) was selected because it achieved the highest accuracy while naturally resisting the dataset's mild class imbalance through ensemble bagging.
-
-The model was retrained on the *entire* cleaned dataset. Finally, we used Python's `pickle` library to bundle four distinct objects into a single file (`model.pkl`):
-1. The trained `RandomForestClassifier`
-2. The fitted `StandardScaler`
-3. The `LabelEncoder` for Gender
-4. The `LabelEncoder` for Risk_Level
-
-By bundling them together, the FastAPI backend can flawlessly preprocess incoming API JSON requests identically to the training pipeline before running `model.predict()`.
-
----
-
-## 📁 Project Structure
-
-```
-heart-attack-risk-predictor/
-│
-├── app.py                          # FastAPI backend — loads model, serves predictions & frontend
-├── model.pkl                       # Serialized bundle: RF model + StandardScaler + LabelEncoders
-├── requirements.txt                # Production Python dependencies
-│
-├── static/                         # Frontend assets
-│   └── index.html                  # Single-page app with glassmorphism UI
-│
-└── research_and_experiments/       # Exploratory analysis & training (not needed for production)
-    ├── heart_attack.ipynb          # Jupyter notebook with EDA and visualizations
-    ├── Heart_Attack_Risk_Levels_Dataset.csv   # Raw dataset (1,319 patient records)
-    ├── deploy_to_hf.py             # Python script for pushing securely to HF Spaces via API
-    ├── train_model.py              # Full training pipeline with diagnostics
-    ├── save_as_pkl.py              # Script to bundle model artifacts into model.pkl
-    ├── output.txt                  # Training output logs
-    ├── random_forest_model.joblib  # Individual model artifact (legacy)
-    ├── label_encoder_gender.joblib # Individual encoder artifact (legacy)
-    └── label_encoder_risk_level.joblib  # Individual encoder artifact (legacy)
-```
-
-### File Descriptions
-
-| File | Size | Description |
-|---|---|---|
-| `app.py` | 3 KB | The core application server. Loads the model bundle at startup, exposes a `POST /predict` endpoint, and serves the static frontend at `/`. |
-| `model.pkl` | 2.6 MB | A Python pickle bundle containing four objects: the trained `RandomForestClassifier`, the fitted `StandardScaler`, the `LabelEncoder` for gender, and the `LabelEncoder` for risk level. |
-| `requirements.txt` | <1 KB | Pinned production dependencies: `fastapi`, `uvicorn`, `scikit-learn`, `numpy`, `pydantic`. |
-| `static/index.html` | ~9 KB | A self-contained HTML/CSS/JS frontend with dark theme, animated gradient background, input validation, and dynamic result rendering. |
-
----
-
-## 🚀 Getting Started
-
-### Prerequisites
-
-| Requirement | Minimum Version | Check Command |
-|---|---|---|
-| Python | 3.9+ | `python --version` |
-| pip | 21.0+ | `pip --version` |
-
-### Step-by-Step Installation
-
-**1. Clone the repository**
-```bash
-git clone https://github.com/Shahd1Sayed/heart-attack-risk-predictor.git
-```
-
-**2. Navigate to the project directory**
-```bash
-cd heart-attack-risk-predictor
-```
-
-**3. Create a virtual environment (recommended)**
-```bash
-# On Windows
-python -m venv .venv
-.venv\Scripts\activate
-
-# On macOS / Linux
-python3 -m venv .venv
-source .venv/bin/activate
-```
-
-**4. Install dependencies**
-```bash
-pip install -r requirements.txt
-```
-
-**5. Verify the model file exists**
-```bash
-# Ensure model.pkl is present in the root directory
-ls model.pkl        # macOS/Linux
-dir model.pkl       # Windows
-```
-
-> **Note:** If `model.pkl` is missing (e.g., excluded by `.gitignore` due to its size), you can regenerate it by running the training pipeline:
-> ```bash
-> cd research_and_experiments
-> pip install pandas xgboost   # additional training dependencies
-> python train_model.py
-> mv model.pkl ../             # move the generated model to root
-> cd ..
-> ```
-
----
-
-## ▶️ Usage
-
-### Start the server
-```bash
-python -m uvicorn app:app --host 127.0.0.1 --port 8000
-```
-
-### Access the application
-Open your browser and navigate to:
-```
-http://127.0.0.1:8000
-```
-
-### Using the Web Interface
-1. Fill in the 8 patient vitals in the form fields.
-2. Click **"Predict Risk Level"**.
-3. View the color-coded result badge and probability distribution bars.
-
-### Using the API directly (cURL)
-```bash
-curl -X POST http://127.0.0.1:8000/predict \
-  -H "Content-Type: application/json" \
-  -d '{
-    "age": 63,
-    "gender": "Male",
-    "heart_rate": 66,
-    "systolic_bp": 160,
-    "diastolic_bp": 83,
-    "blood_sugar": 160,
-    "ck_mb": 1.8,
-    "troponin": 0.012
-  }'
-```
-
-### Example Response
-```json
-{
-  "risk_level": "Moderate",
-  "probabilities": {
-    "High": 0.045,
-    "Moderate": 0.925,
-    "Low": 0.03
-  }
-}
-```
-
----
-
-### Endpoints
-
-#### `GET /`
-Serves the frontend HTML application.
-
-| Parameter | Value |
-|---|---|
-| **Method** | `GET` |
-| **Response** | `text/html` — The single-page application |
-| **Status** | `200 OK` |
-
----
-
-#### `POST /predict`
-Accepts patient vitals and returns the predicted heart attack risk level with class probabilities.
-
-**Request Body** (`application/json`):
-
-| Field | Type | Required | Description | Example |
-|---|---|---|---|---|
-| `age` | `integer` | ✅ | Patient's age in years | `63` |
-| `gender` | `string` | ✅ | `"Male"` or `"Female"` | `"Male"` |
-| `heart_rate` | `integer` | ✅ | Resting heart rate in bpm | `66` |
-| `systolic_bp` | `integer` | ✅ | Systolic blood pressure in mmHg | `160` |
-| `diastolic_bp` | `integer` | ✅ | Diastolic blood pressure in mmHg | `83` |
-| `blood_sugar` | `integer` | ✅ | Fasting blood sugar in mg/dL | `160` |
-| `ck_mb` | `float` | ✅ | CK-MB enzyme level in ng/mL | `1.8` |
-| `troponin` | `float` | ✅ | Cardiac troponin level in ng/mL | `0.012` |
-
-**Response Body** (`application/json`):
-
-| Field | Type | Description |
-|---|---|---|
-| `risk_level` | `string` | Predicted class: `"High"`, `"Moderate"`, or `"Low"` |
-| `probabilities` | `object` | Confidence scores for each class (sum to 1.0) |
-
-**Response Status Codes:**
-
-| Code | Meaning |
-|---|---|
-| `200 OK` | Prediction returned successfully |
-| `422 Unprocessable Entity` | Invalid or missing request fields (Pydantic validation error) |
-
----
-
-## 📊 Model Performance
-
-### Cross-Validation Results (5-Fold Stratified)
-
-| Metric | Value |
-|---|---|
-| **Best Model** | Random Forest (200 estimators) |
-| **Mean CV Accuracy** | 98.63% |
-| **Standard Deviation** | ±0.52% |
-| **Train Accuracy** | 100.00% |
-| **Train-Test Gap** | ~1.4% (minor overfitting) |
-
-### Class Distribution in Dataset
-
-| Risk Level | Count | Percentage |
-|---|---|---|
-| High | 809 | 61.5% |
-| Low | 275 | 20.9% |
-| Moderate | 231 | 17.6% |
-
-### Accuracy Transparency Note
-
-> ⚠️ **Important:** The high accuracy (~98.6%) is attributable to the dataset's construction. Analysis revealed that the `Risk_Level` labels are strongly correlated with — and likely derived from — clinical threshold rules applied to **Troponin** and **CK-MB** values. Removing these two features drops accuracy to **62.17%**. This means the model is effectively learning decision boundaries that mirror clinical diagnostic criteria, which is valid for a decision-support tool but should not be interpreted as the model discovering novel medical insights.
-
----
-
-## 📋 Dataset Description
-
-- **Source:** Heart Attack Risk Levels Dataset
-- **Records:** 1,319 patient observations (1,315 after outlier removal)
-- **Features:** 8 clinical input variables + 1 target variable
-- **Target Variable:** `Risk_Level` — a 3-class categorical label
-
-### Full Schema
-
-| Column | Data Type | Range / Values | Description |
-|---|---|---|---|
-| `Age` | Integer | 14–98 | Patient age in years |
-| `Gender` | Binary | 0 (Female), 1 (Male) | Biological sex |
-| `Heart rate` | Integer | 20–300 | Resting heart rate (bpm) |
-| `Systolic blood pressure` | Integer | 50–300 | Systolic BP (mmHg) |
-| `Diastolic blood pressure` | Integer | 20–200 | Diastolic BP (mmHg) |
-| `Blood sugar` | Integer | 20–700 | Fasting blood glucose (mg/dL) |
-| `CK-MB` | Float | 0–500 | Creatine Kinase-MB isoenzyme (ng/mL) |
-| `Troponin` | Float | 0–50 | Cardiac troponin concentration (ng/mL) |
-| `Risk_Level` | Categorical | High / Moderate / Low | **Target** — Heart attack risk classification |
-
----
-
-## 🔍 Feature Importance
-
-The following chart shows how much each feature contributes to the model's predictions (measured by Gini impurity decrease in the Random Forest):
-
-```
-Troponin                       ██████████████████████  43.3%
-CK-MB                          ██████████             20.7%
-Systolic blood pressure        ███████                13.4%
-Blood sugar                    ██████                 11.1%
-Age                            ██                      4.3%
-Diastolic blood pressure       ██                      4.0%
-Heart rate                     █                       2.5%
-Gender                         ▏                       0.7%
-```
-
-### Clinical Interpretation
-
-1. **Troponin (43.3%)** — Aligns with its role as the gold-standard biomarker for MI diagnosis. The European Society of Cardiology (ESC) guidelines classify MI severity primarily based on troponin thresholds.
-2. **CK-MB (20.7%)** — Historically the primary cardiac biomarker before high-sensitivity troponin assays became standard. Still used as a complementary marker.
-3. **Blood Pressure (17.4% combined)** — Hypertension is the single most prevalent modifiable risk factor for cardiovascular disease.
-4. **Blood Sugar (11.1%)** — Reflects the well-established link between diabetes/metabolic syndrome and cardiovascular risk.
-5. **Age (4.3%)** — A non-modifiable risk factor captured by the Framingham Risk Score.
-6. **Gender (0.7%)** — Low importance suggests the dataset may not fully capture sex-based cardiovascular differences.
-
----
-
-
-### Development Setup
-
-To work on the training pipeline, install the additional research dependencies:
-```bash
-pip install pandas xgboost jupyter matplotlib seaborn
-```
-
----
-
-## 👥 Team Members
-
-| Name | Role | GitHub |
-|---|---|---|
-| **Shahd Sayed** | Machine Learning Engineer | [@Shahd1Sayed](https://github.com/Shahd1Sayed) |
-| **Shahd Mohammed** | Full-Stack Developer | |
-
----
+---
+title: Heart Attack Risk Predictor
+emoji: 🫀
+colorFrom: blue
+colorTo: purple
+sdk: docker
+app_file: app.py
+pinned: false
+---
+
+<h1 align="center">🫀 Heart Attack Risk Predictor — Multimodal</h1>
+
+<p align="center">
+  <strong>An AI-powered clinical decision-support tool that estimates a patient's heart-attack risk from <em>tabular patient data</em>, an <em>ECG image</em>, or <em>both</em> — using an ensemble-router architecture with a tabular model, an ECG image model, and late-fusion of their scores.</strong>
+</p>
+
+<p align="center">
+  <a href="https://huggingface.co/spaces/Shahd1sayed/heart-attack-risk-predictor"><strong>🔴 TRY THE LIVE DEMO ON HUGGING FACE SPACES 🔴</strong></a>
+</p>
+
+<p align="center">
+  <em>⚠️ Educational / portfolio demo — <strong>not a medical device</strong>. Do not use for real clinical decisions.</em>
+</p>
+
+---
+
+## 📑 Table of Contents
+
+- [What's New in v2](#-whats-new-in-v2)
+- [Key Features](#-key-features)
+- [How It Works — Architecture](#-how-it-works--architecture)
+- [The Two Models](#-the-two-models)
+- [Tech Stack](#-tech-stack)
+- [Project Structure](#-project-structure)
+- [Getting Started](#-getting-started)
+- [Usage & API](#-usage--api)
+- [Model Performance](#-model-performance)
+- [Testing](#-testing)
+- [Limitations & Honesty](#-limitations--honesty)
+- [Team Members](#-team-members)
+
+---
+
+## 🆕 What's New in v2
+
+Version 1 was a single-model biomarker classifier (8 vitals → Random Forest). A
+leakage test showed its ~98% accuracy was largely a biomarker-threshold rule
+(accuracy fell to ~62% without Troponin & CK-MB). Version 2 re-architects the project
+into a **multimodal ensemble router**:
+
+- **Two models** instead of one — a **tabular** model and an **ECG image** model.
+- **A router** that picks the model(s) based on what the user submits, and **averages**
+  their scores when both are provided.
+- **Honest evaluation** — proper metrics (ROC-AUC for the imbalanced tabular task,
+  per-class metrics for the ECG task) and a clear statement of limitations.
+
+> The original v1 biomarker research is preserved in `research_and_experiments/`.
+
+---
+
+## ✨ Key Features
+
+- **Multimodal input** — enter patient data, upload an ECG image, or do both.
+- **Ensemble router** — one `POST /predict` endpoint routes to the right model(s):
+  tabular → Model A, ECG → Model B, both → averaged score.
+- **Missing-data friendly** — blank tabular fields are filled automatically by
+  **K-Nearest-Neighbours imputation**, so a partial form still works.
+- **Server-side validation** — out-of-range or non-numeric fields are rejected with a
+  clear message (HTTP 422).
+- **ECG confidence check** — low-confidence ECG predictions are flagged ("may not be a
+  clear 12-lead ECG").
+- **Transparent results** — the UI shows each model's score and, in "both" mode, the
+  combined average, so nothing is a black box.
+- **Modern UI** — dark glassmorphism theme, drag-and-drop ECG upload, color-coded risk
+  badges (🔴 High / 🟡 Moderate / 🟢 Low).
+
+---
+
+## 🧠 How It Works — Architecture
+
+```
+                 ┌──────────────── POST /predict (multipart/form-data) ────────────────┐
+   tabular only ─┤→ Model A (Framingham: KNN-impute → scale → RandomForest) → p_a ─┐    │
+                 │                                                                  ├─ both → average → p → band (Low/Mod/High)
+   ECG only ─────┤→ Model B (ResNet18 transfer learning on ECG images)      → p_b ─┘    │
+                 │                                                                       │
+   neither ──────┤→ HTTP 400                                                             │
+                 └───────────────────────────────────────────────────────────────────────┘
+```
+
+Each model outputs a scalar **risk probability** `p ∈ [0, 1]`. That value is mapped to
+a band — **Low** (`< 0.33`), **Moderate** (`0.33–0.66`), **High** (`> 0.66`) — and, when
+both models run, the two scores are combined by an equal-weight average.
+
+---
+
+## 🤖 The Two Models
+
+### Model A — Tabular (Framingham 10-year CHD)
+- **Data:** Framingham Heart Study (4,240 patients, 15 clinical features).
+- **Target:** `TenYearCHD` — probability of coronary heart disease within 10 years.
+- **Pipeline:** `StandardScaler → KNNImputer(k=5) → classifier`, saved as one artifact.
+- **Model selection:** RandomForest vs XGBoost by 5-fold CV ROC-AUC — **RandomForest
+  won (0.69 vs 0.67)**.
+- **Handles imbalance** (~15% positive) with class weighting; the app uses the
+  continuous probability, not a hard 0.5 cutoff.
+
+### Model B — ECG image (ResNet18)
+- **Data:** ECG Images Dataset of Cardiac Patients (928 images, 4 classes).
+- **Method:** **transfer learning** — a ResNet18 pretrained on ImageNet, with a new
+  4-class head; train the head, then fine-tune the last block.
+- **Classes → risk weight:** Normal `0.0`, abnormal heartbeat `0.5`, post-MI history
+  `0.8`, myocardial infarction `1.0`. The 4-class softmax is collapsed to one risk
+  score via these weights.
+
+---
+
+## 🛠️ Tech Stack
+
+| Layer | Technology | Purpose |
+|---|---|---|
+| **Backend** | [FastAPI](https://fastapi.tiangolo.com/) + [Uvicorn](https://www.uvicorn.org/) | Async web framework + ASGI server; multipart `/predict` router |
+| **Tabular ML** | [scikit-learn](https://scikit-learn.org/) (`RandomForest`, `KNNImputer`, `StandardScaler`), [XGBoost](https://xgboost.readthedocs.io/) | Model A pipeline + model comparison |
+| **Image ML** | [PyTorch](https://pytorch.org/) + [torchvision](https://pytorch.org/vision/) (ResNet18) | Model B transfer learning |
+| **Images / Uploads** | [Pillow](https://python-pillow.org/), `python-multipart` | ECG image decoding + file uploads |
+| **Data** | [pandas](https://pandas.pydata.org/), [NumPy](https://numpy.org/) | Data handling |
+| **Frontend** | HTML5, CSS3, Vanilla JS | Single-page glassmorphism UI with ECG drag-and-drop |
+| **Deployment** | Docker → Hugging Face Spaces | Containerized serving on port 7860 |
+
+---
+
+## 📁 Project Structure
+
+```
+heart-attack-risk-predictor/
+│
+├── app.py                       # FastAPI app + ensemble router (multipart /predict)
+├── requirements.txt             # Production dependencies
+├── Dockerfile                   # Container build (copies app, inference/, models/, static/)
+│
+├── inference/                   # Serving-time prediction package
+│   ├── fusion.py                # Risk bands + late-fusion (combine)
+│   ├── framingham.py            # Model A inference (with KNN imputation)
+│   ├── ecg.py                   # Model B inference (softmax → risk scalar)
+│   └── validation.py            # Server-side field validation
+│
+├── models/                      # Trained artifacts (Git LFS)
+│   ├── framingham_pipeline.joblib   # Model A bundle
+│   ├── ecg_resnet.pt                # Model B weights
+│   └── ecg_classes.json             # ECG class list + risk weights + preprocessing
+│
+├── train_framingham.py          # Trains Model A
+├── train_ecg.py                 # Trains Model B
+│
+├── static/index.html            # Frontend (form + ECG upload + per-branch results)
+│
+├── DOCUMENTATION.md             # Full technical documentation
+├── DEFENSE_GUIDE.md             # Beginner-friendly project defense guide
+│
+└── research_and_experiments/    # v1 biomarker research (notebook, dataset, old model)
+```
+
+---
+
+## 🚀 Getting Started
+
+### Prerequisites
+- Python **3.11+** (3.12 recommended)
+
+### Install
+```bash
+git clone https://github.com/Shahd1Sayed/heart-attack-risk-predictor.git
+cd heart-attack-risk-predictor
+pip install -r requirements.txt
+```
+
+### Data (only needed to (re)train — download from Kaggle)
+```
+data/framingham.csv                  # "Framingham Heart Study dataset"
+data/ecg_data/<class>/*.jpg          # "ECG Images Dataset of Cardiac Patients"
+```
+
+### Train (produces the files in models/)
+```bash
+python train_framingham.py
+python train_ecg.py
+```
+
+### Run
+```bash
+uvicorn app:app --host 127.0.0.1 --port 8000
+# open http://127.0.0.1:8000
+```
+The app boots even before models are trained; a branch needing an untrained model
+returns HTTP 503 with a hint.
+
+---
+
+## ▶️ Usage & API
+
+`POST /predict` accepts **multipart/form-data** with optional tabular fields and an
+optional `ecg` image file.
+
+```bash
+# tabular only
+curl -F age=61 -F male=1 -F sysBP=150 -F totChol=240 http://127.0.0.1:8000/predict
+
+# ECG only
+curl -F ecg=@some_ecg.jpg http://127.0.0.1:8000/predict
+
+# both (multimodal)
+curl -F age=61 -F sysBP=150 -F ecg=@some_ecg.jpg http://127.0.0.1:8000/predict
+```
+
+**Tabular fields:** `male, age, education, currentSmoker, cigsPerDay, BPMeds,
+prevalentStroke, prevalentHyp, diabetes, totChol, sysBP, diaBP, BMI, heartRate,
+glucose` (all optional; blanks are KNN-imputed).
+
+**Example response (multimodal):**
+```json
+{
+  "mode": "multimodal",
+  "risk_level": "High",
+  "p_risk": 0.7306,
+  "branches": {
+    "tabular": { "p_risk": 0.4825, "band": "Moderate",
+                 "detail": {"CHD": 0.4825, "No CHD": 0.5175}, "imputed_fields": ["glucose"] },
+    "ecg": { "p_risk": 0.9787, "band": "High", "ecg_class": "myocardial_infarction_ecg_images",
+             "confidence": 0.9587, "low_confidence": false, "warning": null }
+  }
+}
+```
+
+**Status codes:** `200` success · `400` no input / unreadable image · `422` invalid
+tabular field · `503` model not trained yet.
+
+---
+
+## 📊 Model Performance
+
+| Model | Metric | Value |
+|---|---|---|
+| **Model A — Framingham** | CV ROC-AUC | **0.69** |
+| | Hold-out ROC-AUC | 0.64 |
+| | Accuracy | 0.85 *(≈ all-negative baseline — see note)* |
+| **Model B — ECG ResNet18** | Test accuracy | **0.90** |
+| | Macro F1 | 0.90 |
+| | MI precision | 1.00 |
+
+> ⚠️ **Metric honesty:** Framingham is imbalanced (~15% positive), so 85% accuracy is
+> essentially the "always predict no-CHD" baseline — which is why we lead with **ROC-AUC**.
+> Predicting a decade ahead from basic clinical features is genuinely hard, so ~0.64–0.69
+> AUC is expected. The ECG numbers are strong for a small dataset but optimistic vs.
+> other acquisition setups (the images are photos of printed ECGs).
+
+---
+
+## 🧪 Testing
+
+The project ships with a test harness (router paths, response invariants, adversarial
+inputs, determinism, an ECG serving sweep, input validation, ECG confidence, and
+concurrency). **Result: 62/62 checks pass.** See `DOCUMENTATION.md` for details.
+
+---
+
+## ⚖️ Limitations & Honesty
+
+- **The two models predict different things** — Model A estimates 10-year *prognosis*;
+  Model B classifies the *current* ECG. They are trained on **different, unpaired
+  populations**, so the combined score is a **transparent heuristic demonstrating the
+  architecture, not a validated clinical measure**.
+- **The fusion weights are hand-set** (equal average) because no paired dataset exists
+  to learn/validate them. A learned fusion on paired data (e.g. PTB-XL) is future work.
+- **ECG images are photos of printouts** — a small, imbalanced dataset; the CNN may not
+  generalize to other setups.
+- **No out-of-distribution rejection** — a non-ECG image is still classified (now
+  flagged low-confidence, but not refused).
+- **Not for clinical use.**
+
+---
+
+## 👥 Team Members
+
+| Name | Role | GitHub |
+|---|---|---|
+| **Shahd Sayed** | Machine Learning Engineer | [@Shahd1Sayed](https://github.com/Shahd1Sayed) |
+| **Shahd Mohammed** | Full-Stack Developer | |
+
+---

app.py

@@ -1,82 +1,134 @@
-import pickle
-import numpy as np
-from pathlib import Path
-from fastapi import FastAPI
-from fastapi.staticfiles import StaticFiles
-from fastapi.responses import FileResponse
-from pydantic import BaseModel
-
-# ── Load model bundle ────────────────────────────────────────────────────────
-MODEL_PATH = Path(__file__).parent / "model.pkl"
-
-with open(MODEL_PATH, "rb") as f:
-    bundle = pickle.load(f)
-
-model     = bundle["model"]
-scaler    = bundle["scaler"]
-le_gender = bundle["le_gender"]
-le_target = bundle["le_target"]
-
-# ── FastAPI app ──────────────────────────────────────────────────────────────
-app = FastAPI(title="Heart Attack Risk Predictor")
-
-
-# ── Request schema ───────────────────────────────────────────────────────────
-class PatientVitals(BaseModel):
-    age: int
-    gender: str                 # "Male" or "Female"
-    heart_rate: int
-    systolic_bp: int
-    diastolic_bp: int
-    blood_sugar: int
-    ck_mb: float
-    troponin: float
-
-
-# ── POST /predict ────────────────────────────────────────────────────────────
-@app.post("/predict")
-def predict(vitals: PatientVitals):
-    # Encode gender: the dataset uses 0 = Female, 1 = Male
-    gender_encoded = le_gender.transform([int(vitals.gender)])[0] \
-        if vitals.gender.isdigit() \
-        else (1 if vitals.gender.strip().lower() == "male" else 0)
-
-    features = np.array([[
-        vitals.age,
-        gender_encoded,
-        vitals.heart_rate,
-        vitals.systolic_bp,
-        vitals.diastolic_bp,
-        vitals.blood_sugar,
-        vitals.ck_mb,
-        vitals.troponin,
-    ]])
-
-    features_scaled = scaler.transform(features)
-
-    prediction    = model.predict(features_scaled)[0]
-    probabilities = model.predict_proba(features_scaled)[0]
-    risk_label  = le_target.inverse_transform([prediction])[0]
-
-    # Map probabilities to class names
-    class_probs = {
-        le_target.inverse_transform([i])[0]: round(float(p), 4)
-        for i, p in enumerate(probabilities)
-    }
-
-    return {
-        "risk_level": risk_label,
-        "probabilities": class_probs,
-    }
-
-
-# ── Serve frontend ──────────────────────────────────────────────────────────
-STATIC_DIR = Path(__file__).parent / "static"
-STATIC_DIR.mkdir(exist_ok=True)
-
-app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")
-
-
-@app.get("/")
-def serve_frontend():
-    return FileResponse(str(STATIC_DIR / "index.html"))
+"""Multimodal heart-attack risk app — ensemble router.
+
+One ``POST /predict`` endpoint accepts multipart/form-data carrying *optional*
+Framingham tabular fields and an *optional* ECG image.  An internal router picks
+the path:
+
+    tabular only   -> Model A (Framingham CHD)
+    ECG only       -> Model B (ResNet ECG)
+    both           -> A + B, averaged
+    neither        -> HTTP 400
+
+The predictor modules are imported lazily so the app still boots (and serves the
+frontend) before the models have been trained.
+
+Run:  uvicorn app:app --reload
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+from fastapi import FastAPI, File, Form, HTTPException, UploadFile
+from fastapi.concurrency import run_in_threadpool
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+
+from inference.fusion import band_for, combine
+from inference.validation import validate_tabular
+
+# Canonical Framingham feature order (mirrors train_framingham.FEATURES).
+FEATURES = [
+    "male", "age", "education", "currentSmoker", "cigsPerDay", "BPMeds",
+    "prevalentStroke", "prevalentHyp", "diabetes", "totChol", "sysBP",
+    "diaBP", "BMI", "heartRate", "glucose",
+]
+
+app = FastAPI(title="Multimodal Heart Attack Risk — Ensemble Router")
+
+
+def _has_value(v: Optional[str]) -> bool:
+    return v is not None and str(v).strip() != ""
+
+
+@app.post("/predict")
+async def predict(
+    # ── Tabular branch (all optional → blanks are KNN-imputed) ───────────────
+    male: Optional[str] = Form(None),
+    age: Optional[str] = Form(None),
+    education: Optional[str] = Form(None),
+    currentSmoker: Optional[str] = Form(None),
+    cigsPerDay: Optional[str] = Form(None),
+    BPMeds: Optional[str] = Form(None),
+    prevalentStroke: Optional[str] = Form(None),
+    prevalentHyp: Optional[str] = Form(None),
+    diabetes: Optional[str] = Form(None),
+    totChol: Optional[str] = Form(None),
+    sysBP: Optional[str] = Form(None),
+    diaBP: Optional[str] = Form(None),
+    BMI: Optional[str] = Form(None),
+    heartRate: Optional[str] = Form(None),
+    glucose: Optional[str] = Form(None),
+    # ── Image branch (optional) ──────────────────────────────────────────────
+    ecg: Optional[UploadFile] = File(None),
+):
+    fields = {
+        "male": male, "age": age, "education": education,
+        "currentSmoker": currentSmoker, "cigsPerDay": cigsPerDay, "BPMeds": BPMeds,
+        "prevalentStroke": prevalentStroke, "prevalentHyp": prevalentHyp,
+        "diabetes": diabetes, "totChol": totChol, "sysBP": sysBP, "diaBP": diaBP,
+        "BMI": BMI, "heartRate": heartRate, "glucose": glucose,
+    }
+
+    has_tabular = any(_has_value(fields[f]) for f in FEATURES)
+    has_ecg = ecg is not None and bool(ecg.filename)
+
+    if not has_tabular and not has_ecg:
+        raise HTTPException(
+            status_code=400,
+            detail="Provide tabular patient data, an ECG image, or both.",
+        )
+
+    # Validate any provided tabular values (blanks are skipped → KNN-imputed).
+    if has_tabular:
+        errors = validate_tabular(fields)
+        if errors:
+            raise HTTPException(status_code=422, detail="; ".join(errors))
+
+    branches: dict = {}
+
+    # CPU-bound inference is offloaded to a threadpool so concurrent requests
+    # don't block the event loop (torch/sklearn release the GIL).
+    if has_tabular:
+        try:
+            from inference.framingham import predict_tabular
+            branches["tabular"] = await run_in_threadpool(predict_tabular, fields)
+        except FileNotFoundError as exc:
+            raise HTTPException(status_code=503, detail=str(exc)) from exc
+
+    if has_ecg:
+        image_bytes = await ecg.read()
+        try:
+            from inference.ecg import predict_ecg
+            branches["ecg"] = await run_in_threadpool(predict_ecg, image_bytes)
+        except FileNotFoundError as exc:
+            raise HTTPException(status_code=503, detail=str(exc)) from exc
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    # ── Fuse / select headline ───────────────────────────────────────────────
+    if has_tabular and has_ecg:
+        p = combine(branches["tabular"]["p_risk"], branches["ecg"]["p_risk"])
+        mode, p_head = "multimodal", p
+    elif has_tabular:
+        mode, p_head = "tabular", branches["tabular"]["p_risk"]
+    else:
+        mode, p_head = "ecg", branches["ecg"]["p_risk"]
+
+    return {
+        "mode": mode,
+        "risk_level": band_for(p_head),
+        "p_risk": round(p_head, 4),
+        "branches": branches,
+    }
+
+
+# ── Serve frontend ───────────────────────────────────────────────────────────
+STATIC_DIR = Path(__file__).parent / "static"
+STATIC_DIR.mkdir(exist_ok=True)
+app.mount("/static", StaticFiles(directory=str(STATIC_DIR)), name="static")
+
+
+@app.get("/")
+def serve_frontend():
+    return FileResponse(str(STATIC_DIR / "index.html"))

inference/__init__.py

@@ -0,0 +1 @@
+"""Inference package: per-modality predictors and the late-fusion router logic."""

inference/ecg.py

@@ -0,0 +1,97 @@
+"""Image branch (Model B) inference: ECG ResNet classifier.
+
+Loads the fine-tuned ResNet once and exposes ``predict_ecg``.  The 4-class
+softmax is collapsed into a single risk scalar via the per-class risk weights
+saved at train time (Normal≈0 … MI≈1).
+"""
+from __future__ import annotations
+
+import io
+import json
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+import torch
+import torch.nn as nn
+from PIL import Image
+from torchvision import models, transforms
+
+from .fusion import band_for
+
+MODELS_DIR = Path(__file__).resolve().parent.parent / "models"
+WEIGHTS_PATH = MODELS_DIR / "ecg_resnet.pt"
+CLASSES_PATH = MODELS_DIR / "ecg_classes.json"
+
+_DEVICE = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+# Pin intra-op parallelism to 1 thread per inference. The request-level
+# threadpool in app.py provides concurrency; without this pin, N concurrent
+# requests each spin up torch's multi-thread pools and oversubscribe the CPU
+# (measured: throughput dropped and tail latency exploded under load).
+torch.set_num_threads(1)
+
+# If the top class probability is below this, the image probably isn't a clear
+# 12-lead ECG (or is out-of-distribution) — flag it rather than trusting it.
+ECG_MIN_CONFIDENCE = 0.55
+
+_ARCH_BUILDERS = {
+    "resnet18": models.resnet18,
+    "resnet50": models.resnet50,
+}
+
+
+@lru_cache(maxsize=1)
+def _load():
+    if not WEIGHTS_PATH.exists() or not CLASSES_PATH.exists():
+        raise FileNotFoundError(
+            f"{WEIGHTS_PATH.name}/{CLASSES_PATH.name} not found in {MODELS_DIR} — "
+            f"run `python train_ecg.py` first."
+        )
+    meta = json.loads(CLASSES_PATH.read_text())
+    builder = _ARCH_BUILDERS.get(meta.get("arch", "resnet18"), models.resnet18)
+    model = builder(weights=None)
+    model.fc = nn.Linear(model.fc.in_features, len(meta["classes"]))
+    model.load_state_dict(torch.load(WEIGHTS_PATH, map_location=_DEVICE))
+    model.eval().to(_DEVICE)
+
+    tf = transforms.Compose([
+        transforms.Resize((meta["img_size"], meta["img_size"])),
+        transforms.ToTensor(),
+        transforms.Normalize(meta["mean"], meta["std"]),
+    ])
+    risk_weights = torch.tensor(meta["risk_weights"], dtype=torch.float32)
+    return model, tf, meta["classes"], risk_weights
+
+
+def predict_ecg(image_bytes: bytes) -> dict[str, Any]:
+    """Predict ECG risk from raw image bytes."""
+    model, tf, classes, risk_weights = _load()
+
+    try:
+        img = Image.open(io.BytesIO(image_bytes)).convert("RGB")
+    except Exception as exc:  # noqa: BLE001
+        raise ValueError(f"Could not read image: {exc}") from exc
+
+    x = tf(img).unsqueeze(0).to(_DEVICE)
+    with torch.no_grad():
+        probs = torch.softmax(model(x), dim=1)[0].cpu()
+
+    p_risk = float((probs * risk_weights).sum())
+    pred_idx = int(probs.argmax())
+    confidence = float(probs[pred_idx])
+    low_confidence = confidence < ECG_MIN_CONFIDENCE
+
+    return {
+        "p_risk": p_risk,
+        "band": band_for(p_risk),
+        "ecg_class": classes[pred_idx],
+        "confidence": round(confidence, 4),
+        "low_confidence": low_confidence,
+        "warning": (
+            "Low-confidence ECG classification — the image may not be a clear "
+            "12-lead ECG. Interpret with caution."
+            if low_confidence else None
+        ),
+        "detail": {c: round(float(p), 4) for c, p in zip(classes, probs)},
+    }

inference/framingham.py

@@ -0,0 +1,68 @@
+"""Tabular branch (Model A) inference: Framingham 10-year CHD risk.
+
+Loads the fitted pipeline once and exposes ``predict_tabular``.  Any field the
+caller leaves out (or sends as ``None``/blank) is passed to the pipeline as NaN
+and filled by the fitted ``KNNImputer`` — i.e. the user can submit a partial
+form and the model still runs.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+from pathlib import Path
+from typing import Any
+
+import joblib
+import numpy as np
+import pandas as pd
+
+from .fusion import band_for
+
+BUNDLE_PATH = Path(__file__).resolve().parent.parent / "models" / "framingham_pipeline.joblib"
+
+
+@lru_cache(maxsize=1)
+def _load() -> dict[str, Any]:
+    if not BUNDLE_PATH.exists():
+        raise FileNotFoundError(
+            f"{BUNDLE_PATH} not found — run `python train_framingham.py` first."
+        )
+    return joblib.load(BUNDLE_PATH)
+
+
+def feature_names() -> list[str]:
+    return list(_load()["features"])
+
+
+def _to_float(value: Any) -> float:
+    """Coerce a form value to float; blanks / None / '' become NaN (to impute)."""
+    if value is None:
+        return np.nan
+    if isinstance(value, str) and value.strip() == "":
+        return np.nan
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return np.nan
+
+
+def predict_tabular(fields: dict[str, Any]) -> dict[str, Any]:
+    """Predict CHD risk from a (possibly partial) dict of Framingham fields."""
+    bundle = _load()
+    pipeline = bundle["pipeline"]
+    features: list[str] = bundle["features"]
+
+    row = {f: _to_float(fields.get(f)) for f in features}
+    imputed = [f for f, v in row.items() if isinstance(v, float) and np.isnan(v)]
+    X = pd.DataFrame([row], columns=features)
+
+    classes = list(pipeline.classes_)
+    pos_idx = classes.index(1) if 1 in classes else len(classes) - 1
+    p_risk = float(pipeline.predict_proba(X)[0][pos_idx])
+
+    return {
+        "p_risk": p_risk,
+        "band": band_for(p_risk),
+        "detail": {"CHD": round(p_risk, 4), "No CHD": round(1 - p_risk, 4)},
+        "imputed_fields": imputed,
+        "model_name": bundle.get("model_name", "Framingham"),
+    }

inference/fusion.py

@@ -0,0 +1,44 @@
+"""Risk-band thresholds and late-fusion logic shared by every router path.
+
+Each model branch produces a single scalar risk probability ``p_risk`` in
+``[0, 1]``.  We map that to a 3-level band (to match the existing UI) and, when
+both modalities are present, combine the two branch scores.
+
+IMPORTANT (documented limitation): the tabular branch (Framingham) estimates the
+probability of coronary heart disease over the *next 10 years*, while the ECG
+branch estimates how abnormal the *current* ECG is.  These are different targets
+measured on different populations, so the combined score is a transparent
+heuristic, **not** a validated clinical measure.
+
+NOTE: with only two models, the *median* of ``{p_a, p_b}`` equals their *mean*,
+so "median" and "average" are identical here.  ``combine`` keeps the weights
+explicit so a confidence-weighting scheme can be dropped in later.
+"""
+from __future__ import annotations
+
+# ── Band thresholds on p_risk ∈ [0, 1] ───────────────────────────────────────
+LOW_MAX: float = 0.33
+MODERATE_MAX: float = 0.66
+
+BANDS = ("Low", "Moderate", "High")
+
+
+def band_for(p: float) -> str:
+    """Map a risk scalar to Low / Moderate / High."""
+    if p < LOW_MAX:
+        return "Low"
+    if p < MODERATE_MAX:
+        return "Moderate"
+    return "High"
+
+
+def combine(p_a: float, p_b: float, w_a: float = 0.5, w_b: float = 0.5) -> float:
+    """Late-fusion of two branch risk scores.
+
+    Defaults to an equal-weight mean (== median for two values).  Weights are
+    normalised so callers can pass relative confidences without pre-scaling.
+    """
+    total = w_a + w_b
+    if total <= 0:
+        raise ValueError("fusion weights must sum to a positive number")
+    return (w_a * p_a + w_b * p_b) / total

inference/validation.py

@@ -0,0 +1,49 @@
+"""Server-side range validation for the Framingham tabular fields.
+
+Blank / missing fields are skipped here (they get KNN-imputed downstream).
+Only *provided* values are checked: they must parse as numbers and fall inside
+clinically plausible bounds. Returns a list of human-readable error strings
+(empty == valid).
+"""
+from __future__ import annotations
+
+from typing import Any
+
+# Binary / categorical fields use "choices"; continuous fields use min/max.
+FIELD_SPECS: dict[str, dict[str, Any]] = {
+    "male":            {"choices": {0, 1}},
+    "age":             {"min": 1,  "max": 120},
+    "education":       {"choices": {1, 2, 3, 4}},
+    "currentSmoker":   {"choices": {0, 1}},
+    "cigsPerDay":      {"min": 0,  "max": 100},
+    "BPMeds":          {"choices": {0, 1}},
+    "prevalentStroke": {"choices": {0, 1}},
+    "prevalentHyp":    {"choices": {0, 1}},
+    "diabetes":        {"choices": {0, 1}},
+    "totChol":         {"min": 50, "max": 700},
+    "sysBP":           {"min": 50, "max": 300},
+    "diaBP":           {"min": 30, "max": 200},
+    "BMI":             {"min": 10, "max": 70},
+    "heartRate":       {"min": 20, "max": 300},
+    "glucose":         {"min": 20, "max": 700},
+}
+
+
+def validate_tabular(fields: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    for name, spec in FIELD_SPECS.items():
+        raw = fields.get(name)
+        if raw is None or str(raw).strip() == "":
+            continue  # blank -> imputed later, nothing to validate
+        try:
+            v = float(raw)
+        except (TypeError, ValueError):
+            errors.append(f"{name}: '{raw}' is not a number")
+            continue
+        if "choices" in spec and v not in spec["choices"]:
+            errors.append(f"{name}: must be one of {sorted(spec['choices'])} (got {raw})")
+        if "min" in spec and v < spec["min"]:
+            errors.append(f"{name}: must be >= {spec['min']} (got {raw})")
+        if "max" in spec and v > spec["max"]:
+            errors.append(f"{name}: must be <= {spec['max']} (got {raw})")
+    return errors

models/ecg_classes.json

@@ -0,0 +1,26 @@
+{
+  "arch": "resnet18",
+  "classes": [
+    "abnormal_heartbeat_ecg_images",
+    "myocardial_infarction_ecg_images",
+    "normal_ecg_images",
+    "post_mi_history_ecg_images"
+  ],
+  "risk_weights": [
+    0.5,
+    1.0,
+    0.0,
+    0.8
+  ],
+  "img_size": 224,
+  "mean": [
+    0.485,
+    0.456,
+    0.406
+  ],
+  "std": [
+    0.229,
+    0.224,
+    0.225
+  ]
+}

models/ecg_resnet.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a790e17387fa23a76dd1493335da7157f68dd1efec0c601405836484986db99e
+size 44792139

models/framingham_pipeline.joblib

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:19b04e7503707b319bbced0fb2c0bbbc191ccc6672eb1f2c41c90672d0ad13de
+size 45325835

requirements.txt

@@ -1,5 +1,18 @@
-fastapi
-uvicorn
-scikit-learn
-numpy
-pydantic
+--extra-index-url https://download.pytorch.org/whl/cpu
+# ── Web app (FastAPI, not Flask) ─────────────────────────────────────────────
+fastapi
+uvicorn[standard]
+python-multipart          # required for multipart/form-data file uploads
+pydantic
+
+# ── Model A — Framingham tabular (KNN-impute → scale → RF/XGB) ────────────────
+scikit-learn
+xgboost
+pandas
+numpy
+joblib
+
+# ── Model B — ECG image CNN (ResNet transfer learning) ───────────────────────
+torch
+torchvision
+pillow

static/index.html

@@ -1,429 +1,542 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>Heart Attack Risk Predictor</title>
-  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet" />
-  <style>
-    /* ── Reset & Base ─────────────────────────────────────────── */
-    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
-
-    :root {
-      --bg:        #0b0f1a;
-      --surface:   rgba(255,255,255,0.04);
-      --border:    rgba(255,255,255,0.08);
-      --text:      #e2e8f0;
-      --text-dim:  #8892a4;
-      --accent:    #6366f1;
-      --accent-g:  linear-gradient(135deg, #6366f1, #ec4899);
-      --high:      #ef4444;
-      --moderate:  #f59e0b;
-      --low:       #22c55e;
-      --radius:    14px;
-    }
-
-    body {
-      font-family: 'Inter', sans-serif;
-      background: var(--bg);
-      color: var(--text);
-      min-height: 100vh;
-      display: flex;
-      align-items: center;
-      justify-content: center;
-      padding: 2rem 1rem;
-      overflow-x: hidden;
-    }
-
-    /* Animated gradient blob */
-    body::before {
-      content: '';
-      position: fixed;
-      top: -40%; left: -10%;
-      width: 60vw; height: 60vw;
-      background: radial-gradient(circle, rgba(99,102,241,0.18), transparent 70%);
-      filter: blur(80px);
-      animation: float 8s ease-in-out infinite alternate;
-      pointer-events: none;
-      z-index: 0;
-    }
-    body::after {
-      content: '';
-      position: fixed;
-      bottom: -30%; right: -10%;
-      width: 50vw; height: 50vw;
-      background: radial-gradient(circle, rgba(236,72,153,0.14), transparent 70%);
-      filter: blur(80px);
-      animation: float 10s ease-in-out infinite alternate-reverse;
-      pointer-events: none;
-      z-index: 0;
-    }
-    @keyframes float { to { transform: translate(40px, -30px) scale(1.05); } }
-
-    /* ── Card ─────────────────────────────────────────────────── */
-    .card {
-      position: relative; z-index: 1;
-      width: 100%; max-width: 520px;
-      background: var(--surface);
-      backdrop-filter: blur(24px) saturate(140%);
-      -webkit-backdrop-filter: blur(24px) saturate(140%);
-      border: 1px solid var(--border);
-      border-radius: var(--radius);
-      padding: 2.5rem 2rem 2rem;
-    }
-
-    /* ── Header ───────────────────────────────────────────────── */
-    .header { text-align: center; margin-bottom: 2rem; }
-    .header .icon {
-      width: 56px; height: 56px;
-      margin: 0 auto .75rem;
-      background: var(--accent-g);
-      border-radius: 16px;
-      display: grid; place-items: center;
-      font-size: 28px;
-      box-shadow: 0 4px 20px rgba(99,102,241,0.35);
-    }
-    .header h1 {
-      font-size: 1.35rem; font-weight: 700;
-      background: var(--accent-g);
-      -webkit-background-clip: text;
-      -webkit-text-fill-color: transparent;
-    }
-    .header p { font-size: .82rem; color: var(--text-dim); margin-top: .3rem; }
-
-    /* ── Form grid ────────────────────────────────────────────── */
-    .form-grid { display: grid; grid-template-columns: 1fr 1fr; gap: .85rem; }
-
-    .field { display: flex; flex-direction: column; }
-    .field.full { grid-column: 1 / -1; }
-
-    label {
-      font-size: .72rem; font-weight: 500;
-      color: var(--text-dim);
-      text-transform: uppercase;
-      letter-spacing: .06em;
-      margin-bottom: .3rem;
-    }
-
-    input, select {
-      background: rgba(255,255,255,0.05);
-      border: 1px solid var(--border);
-      border-radius: 10px;
-      padding: .65rem .85rem;
-      color: var(--text);
-      font-family: inherit;
-      font-size: .88rem;
-      outline: none;
-      transition: border-color .2s, box-shadow .2s;
-    }
-    input:focus, select:focus {
-      border-color: var(--accent);
-      box-shadow: 0 0 0 3px rgba(99,102,241,0.2);
-    }
-    input::placeholder { color: rgba(255,255,255,0.2); }
-    select option { background: #1e1e2e; color: var(--text); }
-
-    /* ── Button ───────────────────────────────────────────────── */
-    .btn {
-      grid-column: 1 / -1;
-      margin-top: .5rem;
-      padding: .8rem;
-      border: none;
-      border-radius: 10px;
-      background: var(--accent-g);
-      color: #fff;
-      font-family: inherit;
-      font-size: .92rem;
-      font-weight: 600;
-      cursor: pointer;
-      transition: transform .15s, box-shadow .25s;
-      box-shadow: 0 4px 20px rgba(99,102,241,0.3);
-    }
-    .btn:hover { transform: translateY(-1px); box-shadow: 0 6px 28px rgba(99,102,241,0.45); }
-    .btn:active { transform: scale(.98); }
-    .btn:disabled { opacity: .55; cursor: not-allowed; transform: none; }
-
-    /* ── Spinner ──────────────────────────────────────────────── */
-    .spinner {
-      display: none;
-      width: 18px; height: 18px;
-      border: 2px solid rgba(255,255,255,.3);
-      border-top-color: #fff;
-      border-radius: 50%;
-      animation: spin .6s linear infinite;
-      margin: 0 auto;
-    }
-    .btn.loading .spinner { display: inline-block; }
-    .btn.loading .btn-text { display: none; }
-    @keyframes spin { to { transform: rotate(360deg); } }
-
-    /* ── Result panel ─────────────────────────────────────────── */
-    .result {
-      margin-top: 1.5rem;
-      border-radius: 12px;
-      overflow: hidden;
-      opacity: 0;
-      transform: translateY(10px);
-      transition: opacity .4s, transform .4s;
-    }
-    .result.show { opacity: 1; transform: translateY(0); }
-
-    .result-header {
-      padding: 1rem 1.25rem;
-      display: flex;
-      align-items: center;
-      gap: .75rem;
-    }
-    .result-header .badge {
-      font-size: .7rem;
-      font-weight: 600;
-      text-transform: uppercase;
-      letter-spacing: .08em;
-      padding: .25rem .65rem;
-      border-radius: 6px;
-    }
-    .result-header .risk-text {
-      font-size: 1.15rem;
-      font-weight: 700;
-    }
-
-    .result.high   .result-header { background: rgba(239,68,68,0.12); }
-    .result.high   .badge         { background: var(--high); color: #fff; }
-    .result.high   .risk-text     { color: var(--high); }
-
-    .result.moderate .result-header { background: rgba(245,158,11,0.12); }
-    .result.moderate .badge         { background: var(--moderate); color: #1a1a1a; }
-    .result.moderate .risk-text     { color: var(--moderate); }
-
-    .result.low    .result-header { background: rgba(34,197,94,0.12); }
-    .result.low    .badge         { background: var(--low); color: #1a1a1a; }
-    .result.low    .risk-text     { color: var(--low); }
-
-    /* Probability bars */
-    .prob-bars { padding: .75rem 1.25rem 1rem; }
-    .prob-row {
-      display: flex; align-items: center; gap: .6rem;
-      margin-bottom: .5rem;
-    }
-    .prob-row:last-child { margin-bottom: 0; }
-    .prob-label {
-      width: 70px;
-      font-size: .72rem;
-      font-weight: 500;
-      color: var(--text-dim);
-    }
-    .prob-track {
-      flex: 1;
-      height: 8px;
-      background: rgba(255,255,255,0.06);
-      border-radius: 4px;
-      overflow: hidden;
-    }
-    .prob-fill {
-      height: 100%;
-      border-radius: 4px;
-      transition: width .6s cubic-bezier(.4,0,.2,1);
-    }
-    .prob-fill.high     { background: var(--high); }
-    .prob-fill.moderate { background: var(--moderate); }
-    .prob-fill.low      { background: var(--low); }
-    .prob-value {
-      width: 44px;
-      text-align: right;
-      font-size: .75rem;
-      font-weight: 600;
-      color: var(--text);
-    }
-
-    /* ── Error ────────────────────────────────────────────────── */
-    .error-msg {
-      margin-top: 1rem;
-      padding: .75rem 1rem;
-      background: rgba(239,68,68,0.1);
-      border: 1px solid rgba(239,68,68,0.25);
-      border-radius: 10px;
-      color: var(--high);
-      font-size: .82rem;
-      display: none;
-    }
-    .error-msg.show { display: block; }
-
-    /* ── Responsive ───────────────────────────────────────────── */
-    @media (max-width: 480px) {
-      .form-grid { grid-template-columns: 1fr; }
-      .card { padding: 2rem 1.25rem 1.5rem; }
-    }
-  </style>
-</head>
-<body>
-  <div class="card">
-    <!-- Header -->
-    <div class="header">
-      <div class="icon">&#x1F9E0;</div>
-      <h1>Heart Attack Risk Predictor</h1>
-      <p>Enter patient vitals to assess cardiac risk level</p>
-    </div>
-
-    <!-- Form -->
-    <form id="predictForm" class="form-grid" autocomplete="off">
-
-      <div class="field">
-        <label for="age">Age</label>
-        <input id="age" type="number" placeholder="e.g. 55" min="1" max="120" required />
-      </div>
-
-      <div class="field">
-        <label for="gender">Gender</label>
-        <select id="gender" required>
-          <option value="" disabled selected>Select</option>
-          <option value="Male">Male</option>
-          <option value="Female">Female</option>
-        </select>
-      </div>
-
-      <div class="field">
-        <label for="heart_rate">Heart Rate (bpm)</label>
-        <input id="heart_rate" type="number" placeholder="e.g. 72" min="20" max="300" required />
-      </div>
-
-      <div class="field">
-        <label for="systolic_bp">Systolic BP (mmHg)</label>
-        <input id="systolic_bp" type="number" placeholder="e.g. 120" min="50" max="300" required />
-      </div>
-
-      <div class="field">
-        <label for="diastolic_bp">Diastolic BP (mmHg)</label>
-        <input id="diastolic_bp" type="number" placeholder="e.g. 80" min="30" max="200" required />
-      </div>
-
-      <div class="field">
-        <label for="blood_sugar">Blood Sugar (mg/dL)</label>
-        <input id="blood_sugar" type="number" placeholder="e.g. 100" min="30" max="700" required />
-      </div>
-
-      <div class="field">
-        <label for="ck_mb">CK-MB (ng/mL)</label>
-        <input id="ck_mb" type="number" step="any" placeholder="e.g. 2.5" min="0" required />
-      </div>
-
-      <div class="field">
-        <label for="troponin">Troponin (ng/mL)</label>
-        <input id="troponin" type="number" step="any" placeholder="e.g. 0.01" min="0" required />
-      </div>
-
-      <button type="submit" class="btn" id="submitBtn">
-        <span class="btn-text">Predict Risk Level</span>
-        <span class="spinner"></span>
-      </button>
-    </form>
-
-    <!-- Error -->
-    <div class="error-msg" id="errorMsg"></div>
-
-    <!-- Result -->
-    <div class="result" id="resultPanel">
-      <div class="result-header">
-        <span class="badge" id="badge"></span>
-        <span class="risk-text" id="riskText"></span>
-      </div>
-      <div class="prob-bars" id="probBars"></div>
-    </div>
-  </div>
-
-  <script>
-    const form     = document.getElementById('predictForm');
-    const btn      = document.getElementById('submitBtn');
-    const errDiv   = document.getElementById('errorMsg');
-    const result   = document.getElementById('resultPanel');
-    const badge    = document.getElementById('badge');
-    const riskText = document.getElementById('riskText');
-    const probBars = document.getElementById('probBars');
-
-    const riskMessages = {
-      High:     'Immediate medical attention recommended',
-      Moderate: 'Monitor closely and consult a doctor',
-      Low:      'Maintain a healthy lifestyle',
-    };
-
-    form.addEventListener('submit', async (e) => {
-      e.preventDefault();
-      errDiv.classList.remove('show');
-      result.classList.remove('show', 'high', 'moderate', 'low');
-
-      const payload = {
-        age:          +document.getElementById('age').value,
-        gender:       document.getElementById('gender').value,
-        heart_rate:   +document.getElementById('heart_rate').value,
-        systolic_bp:  +document.getElementById('systolic_bp').value,
-        diastolic_bp: +document.getElementById('diastolic_bp').value,
-        blood_sugar:  +document.getElementById('blood_sugar').value,
-        ck_mb:        +document.getElementById('ck_mb').value,
-        troponin:     +document.getElementById('troponin').value,
-      };
-
-      btn.classList.add('loading');
-      btn.disabled = true;
-
-      try {
-        const res = await fetch('/predict', {
-          method: 'POST',
-          headers: { 'Content-Type': 'application/json' },
-          body: JSON.stringify(payload),
-        });
-
-        if (!res.ok) {
-          const err = await res.json();
-          throw new Error(err.detail || 'Server error');
-        }
-
-        const data = await res.json();
-        showResult(data);
-      } catch (err) {
-        errDiv.textContent = err.message || 'Failed to reach the server.';
-        errDiv.classList.add('show');
-      } finally {
-        btn.classList.remove('loading');
-        btn.disabled = false;
-      }
-    });
-
-    function showResult(data) {
-      const level = data.risk_level;   // "High" | "Moderate" | "Low"
-      const cls   = level.toLowerCase();
-
-      result.className = 'result ' + cls;
-      badge.textContent   = level + ' risk';
-      riskText.textContent = riskMessages[level] || level;
-
-      // Build probability bars
-      probBars.innerHTML = '';
-      const order = ['High', 'Moderate', 'Low'];
-
-      for (const key of order) {
-        const pct = ((data.probabilities[key] || 0) * 100).toFixed(1);
-        const row = document.createElement('div');
-        row.className = 'prob-row';
-        row.innerHTML = `
-          <span class="prob-label">${key}</span>
-          <div class="prob-track">
-            <div class="prob-fill ${key.toLowerCase()}" style="width:0%"></div>
-          </div>
-          <span class="prob-value">${pct}%</span>
-        `;
-        probBars.appendChild(row);
-      }
-
-      // Animate
-      requestAnimationFrame(() => {
-        result.classList.add('show');
-        setTimeout(() => {
-          probBars.querySelectorAll('.prob-fill').forEach((bar, i) => {
-            const pct = ((data.probabilities[order[i]] || 0) * 100).toFixed(1);
-            bar.style.width = pct + '%';
-          });
-        }, 100);
-      });
-    }
-  </script>
-</body>
-</html>
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>Multimodal Heart Attack Risk</title>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&display=swap" rel="stylesheet" />
+  <style>
+    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+
+    :root {
+      --bg:        #0b0f1a;
+      --surface:   rgba(255,255,255,0.04);
+      --surface-2: rgba(255,255,255,0.06);
+      --border:    rgba(255,255,255,0.08);
+      --text:      #e2e8f0;
+      --text-dim:  #8892a4;
+      --accent:    #6366f1;
+      --accent-g:  linear-gradient(135deg, #6366f1, #ec4899);
+      --high:      #ef4444;
+      --moderate:  #f59e0b;
+      --low:       #22c55e;
+      --radius:    14px;
+    }
+
+    body {
+      font-family: 'Inter', sans-serif;
+      background: var(--bg);
+      color: var(--text);
+      min-height: 100vh;
+      display: flex;
+      align-items: flex-start;
+      justify-content: center;
+      padding: 2.5rem 1rem;
+      overflow-x: hidden;
+    }
+
+    body::before, body::after {
+      content: ''; position: fixed; pointer-events: none; z-index: 0;
+      filter: blur(80px);
+    }
+    body::before {
+      top: -40%; left: -10%; width: 60vw; height: 60vw;
+      background: radial-gradient(circle, rgba(99,102,241,0.18), transparent 70%);
+      animation: float 8s ease-in-out infinite alternate;
+    }
+    body::after {
+      bottom: -30%; right: -10%; width: 50vw; height: 50vw;
+      background: radial-gradient(circle, rgba(236,72,153,0.14), transparent 70%);
+      animation: float 10s ease-in-out infinite alternate-reverse;
+    }
+    @keyframes float { to { transform: translate(40px, -30px) scale(1.05); } }
+
+    .card {
+      position: relative; z-index: 1;
+      width: 100%; max-width: 600px;
+      background: var(--surface);
+      backdrop-filter: blur(24px) saturate(140%);
+      -webkit-backdrop-filter: blur(24px) saturate(140%);
+      border: 1px solid var(--border);
+      border-radius: var(--radius);
+      padding: 2.5rem 2rem 2rem;
+    }
+
+    .header { text-align: center; margin-bottom: 1.75rem; }
+    .header .icon {
+      width: 56px; height: 56px; margin: 0 auto .75rem;
+      background: var(--accent-g); border-radius: 16px;
+      display: grid; place-items: center; font-size: 28px;
+      box-shadow: 0 4px 20px rgba(99,102,241,0.35);
+    }
+    .header h1 {
+      font-size: 1.35rem; font-weight: 700;
+      background: var(--accent-g);
+      -webkit-background-clip: text; -webkit-text-fill-color: transparent;
+    }
+    .header p { font-size: .82rem; color: var(--text-dim); margin-top: .3rem; }
+
+    .section-title {
+      font-size: .7rem; font-weight: 600; letter-spacing: .08em;
+      text-transform: uppercase; color: var(--text-dim);
+      margin: 1.5rem 0 .75rem; display: flex; align-items: center; gap: .5rem;
+    }
+    .section-title::after { content: ''; flex: 1; height: 1px; background: var(--border); }
+
+    .form-grid { display: grid; grid-template-columns: 1fr 1fr; gap: .85rem; }
+    .field { display: flex; flex-direction: column; }
+    .field.full { grid-column: 1 / -1; }
+
+    label {
+      font-size: .72rem; font-weight: 500; color: var(--text-dim);
+      text-transform: uppercase; letter-spacing: .05em; margin-bottom: .3rem;
+      display: flex; gap: .4rem; align-items: baseline;
+    }
+    label .opt { font-size: .62rem; color: var(--accent); text-transform: none; letter-spacing: 0; }
+
+    input, select {
+      background: rgba(255,255,255,0.05); border: 1px solid var(--border);
+      border-radius: 10px; padding: .6rem .8rem; color: var(--text);
+      font-family: inherit; font-size: .88rem; outline: none;
+      transition: border-color .2s, box-shadow .2s;
+    }
+    input:focus, select:focus {
+      border-color: var(--accent); box-shadow: 0 0 0 3px rgba(99,102,241,0.2);
+    }
+    input::placeholder { color: rgba(255,255,255,0.2); }
+    select option { background: #1e1e2e; color: var(--text); }
+
+    /* ECG drop zone */
+    .drop {
+      border: 1.5px dashed var(--border); border-radius: 12px;
+      padding: 1.25rem; text-align: center; cursor: pointer;
+      transition: border-color .2s, background .2s; color: var(--text-dim);
+      font-size: .85rem;
+    }
+    .drop:hover, .drop.drag { border-color: var(--accent); background: rgba(99,102,241,0.06); }
+    .drop input { display: none; }
+    .drop .preview { max-height: 150px; max-width: 100%; border-radius: 8px; margin-top: .5rem; }
+    .drop .filename { color: var(--text); font-weight: 500; margin-top: .4rem; word-break: break-all; }
+
+    /* Mode indicator */
+    .mode {
+      margin: 1.1rem 0 .25rem; font-size: .78rem; text-align: center;
+      color: var(--text-dim);
+    }
+    .mode b { color: var(--accent); }
+
+    .btn {
+      width: 100%; margin-top: .75rem; padding: .8rem; border: none;
+      border-radius: 10px; background: var(--accent-g); color: #fff;
+      font-family: inherit; font-size: .92rem; font-weight: 600; cursor: pointer;
+      transition: transform .15s, box-shadow .25s, opacity .2s;
+      box-shadow: 0 4px 20px rgba(99,102,241,0.3);
+    }
+    .btn:hover:not(:disabled) { transform: translateY(-1px); box-shadow: 0 6px 28px rgba(99,102,241,0.45); }
+    .btn:active { transform: scale(.98); }
+    .btn:disabled { opacity: .55; cursor: not-allowed; }
+    .btn.loading .btn-text { opacity: .5; }
+
+    .error-msg {
+      margin-top: 1rem; padding: .75rem 1rem; background: rgba(239,68,68,0.1);
+      border: 1px solid rgba(239,68,68,0.25); border-radius: 10px;
+      color: var(--high); font-size: .82rem; display: none;
+    }
+    .error-msg.show { display: block; }
+
+    /* Result */
+    .result { margin-top: 1.5rem; opacity: 0; transform: translateY(10px);
+      transition: opacity .4s, transform .4s; display: none; }
+    .result.show { opacity: 1; transform: translateY(0); display: block; }
+
+    .headline {
+      border-radius: 12px; padding: 1.1rem 1.25rem; display: flex;
+      align-items: center; gap: 1rem;
+    }
+    .headline .badge {
+      font-size: .7rem; font-weight: 700; text-transform: uppercase;
+      letter-spacing: .08em; padding: .3rem .7rem; border-radius: 6px;
+    }
+    .headline .pct { font-size: 1.9rem; font-weight: 700; margin-left: auto; }
+    .headline .msg { font-size: .82rem; color: var(--text-dim); }
+    .headline .label-wrap { display: flex; flex-direction: column; gap: .3rem; }
+
+    .result.high   .headline { background: rgba(239,68,68,0.12); }
+    .result.high   .badge, .result.high   .pct { color: var(--high); }
+    .result.high   .badge { background: var(--high); color: #fff; }
+    .result.moderate .headline { background: rgba(245,158,11,0.12); }
+    .result.moderate .badge, .result.moderate .pct { color: var(--moderate); }
+    .result.moderate .badge { background: var(--moderate); color: #1a1a1a; }
+    .result.low    .headline { background: rgba(34,197,94,0.12); }
+    .result.low    .badge, .result.low    .pct { color: var(--low); }
+    .result.low    .badge { background: var(--low); color: #1a1a1a; }
+
+    .branches { margin-top: 1rem; display: flex; flex-direction: column; gap: .75rem; }
+    .branch {
+      background: var(--surface-2); border: 1px solid var(--border);
+      border-radius: 10px; padding: .85rem 1rem;
+    }
+    .branch h4 { font-size: .8rem; font-weight: 600; display: flex; justify-content: space-between; }
+    .branch h4 .b-pct { color: var(--text-dim); font-weight: 500; }
+    .branch .sub { font-size: .72rem; color: var(--text-dim); margin-top: .15rem; }
+
+    .prob-row { display: flex; align-items: center; gap: .6rem; margin-top: .45rem; }
+    .prob-label { width: 130px; font-size: .68rem; color: var(--text-dim); white-space: nowrap;
+      overflow: hidden; text-overflow: ellipsis; }
+    .prob-track { flex: 1; height: 7px; background: rgba(255,255,255,0.06); border-radius: 4px; overflow: hidden; }
+    .prob-fill { height: 100%; border-radius: 4px; background: var(--accent);
+      width: 0; transition: width .6s cubic-bezier(.4,0,.2,1); }
+    .prob-fill.high { background: var(--high); }
+    .prob-fill.moderate { background: var(--moderate); }
+    .prob-fill.low { background: var(--low); }
+    .prob-value { width: 42px; text-align: right; font-size: .72rem; font-weight: 600; }
+
+    .combined-note { font-size: .7rem; color: var(--text-dim); text-align: center; margin-top: .6rem; font-style: italic; }
+    .branch .warn {
+      margin-top: .5rem; padding: .45rem .6rem; border-radius: 7px;
+      background: rgba(245,158,11,0.12); border: 1px solid rgba(245,158,11,0.3);
+      color: var(--moderate); font-size: .7rem; line-height: 1.4;
+    }
+
+    .disclaimer {
+      margin-top: 1.25rem; padding: .7rem .9rem; border-radius: 8px;
+      background: rgba(255,255,255,0.03); border: 1px solid var(--border);
+      font-size: .68rem; line-height: 1.5; color: var(--text-dim);
+    }
+    .disclaimer b { color: var(--text); }
+
+    @media (max-width: 520px) {
+      .form-grid { grid-template-columns: 1fr; }
+      .card { padding: 2rem 1.25rem 1.5rem; }
+      .headline { flex-wrap: wrap; }
+      .headline .pct { margin-left: 0; }
+    }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <div class="header">
+      <div class="icon">&#x1FAC0;</div>
+      <h1>Multimodal Heart Attack Risk</h1>
+      <p>Enter patient data, upload an ECG image, or both — the router picks the model(s)</p>
+    </div>
+
+    <form id="predictForm" autocomplete="off">
+      <!-- ── Tabular (Framingham) ─────────────────────────────────────── -->
+      <div class="section-title">Patient data &nbsp;<span style="text-transform:none;letter-spacing:0;color:var(--text-dim)">(Framingham)</span></div>
+      <div class="form-grid">
+        <div class="field">
+          <label for="male">Sex</label>
+          <select id="male" name="male">
+            <option value="" selected>—</option>
+            <option value="1">Male</option>
+            <option value="0">Female</option>
+          </select>
+        </div>
+        <div class="field">
+          <label for="age">Age</label>
+          <input id="age" name="age" type="number" min="1" max="120" placeholder="e.g. 55" />
+        </div>
+        <div class="field">
+          <label for="education">Education <span class="opt">· optional</span></label>
+          <select id="education" name="education">
+            <option value="" selected>—</option>
+            <option value="1">1 (lowest)</option>
+            <option value="2">2</option>
+            <option value="3">3</option>
+            <option value="4">4 (highest)</option>
+          </select>
+        </div>
+        <div class="field">
+          <label for="currentSmoker">Current smoker</label>
+          <select id="currentSmoker" name="currentSmoker">
+            <option value="" selected>—</option>
+            <option value="1">Yes</option>
+            <option value="0">No</option>
+          </select>
+        </div>
+        <div class="field">
+          <label for="cigsPerDay">Cigarettes / day <span class="opt">· auto-filled</span></label>
+          <input id="cigsPerDay" name="cigsPerDay" type="number" min="0" max="100" placeholder="e.g. 0" />
+        </div>
+        <div class="field">
+          <label for="BPMeds">On BP meds <span class="opt">· auto-filled</span></label>
+          <select id="BPMeds" name="BPMeds">
+            <option value="" selected>—</option>
+            <option value="1">Yes</option>
+            <option value="0">No</option>
+          </select>
+        </div>
+        <div class="field">
+          <label for="prevalentStroke">Prior stroke</label>
+          <select id="prevalentStroke" name="prevalentStroke">
+            <option value="" selected>—</option>
+            <option value="1">Yes</option>
+            <option value="0">No</option>
+          </select>
+        </div>
+        <div class="field">
+          <label for="prevalentHyp">Hypertension</label>
+          <select id="prevalentHyp" name="prevalentHyp">
+            <option value="" selected>—</option>
+            <option value="1">Yes</option>
+            <option value="0">No</option>
+          </select>
+        </div>
+        <div class="field">
+          <label for="diabetes">Diabetes</label>
+          <select id="diabetes" name="diabetes">
+            <option value="" selected>—</option>
+            <option value="1">Yes</option>
+            <option value="0">No</option>
+          </select>
+        </div>
+        <div class="field">
+          <label for="totChol">Total cholesterol <span class="opt">· auto-filled</span></label>
+          <input id="totChol" name="totChol" type="number" step="any" min="0" placeholder="mg/dL" />
+        </div>
+        <div class="field">
+          <label for="sysBP">Systolic BP</label>
+          <input id="sysBP" name="sysBP" type="number" step="any" min="0" placeholder="mmHg" />
+        </div>
+        <div class="field">
+          <label for="diaBP">Diastolic BP</label>
+          <input id="diaBP" name="diaBP" type="number" step="any" min="0" placeholder="mmHg" />
+        </div>
+        <div class="field">
+          <label for="BMI">BMI <span class="opt">· auto-filled</span></label>
+          <input id="BMI" name="BMI" type="number" step="any" min="0" placeholder="kg/m²" />
+        </div>
+        <div class="field">
+          <label for="heartRate">Heart rate <span class="opt">· auto-filled</span></label>
+          <input id="heartRate" name="heartRate" type="number" step="any" min="0" placeholder="bpm" />
+        </div>
+        <div class="field">
+          <label for="glucose">Glucose <span class="opt">· auto-filled</span></label>
+          <input id="glucose" name="glucose" type="number" step="any" min="0" placeholder="mg/dL" />
+        </div>
+      </div>
+
+      <!-- ── ECG image ─────────────────────────────────────────────────── -->
+      <div class="section-title">ECG image &nbsp;<span style="text-transform:none;letter-spacing:0;color:var(--text-dim)">(optional)</span></div>
+      <div class="field full">
+        <label class="drop" id="dropZone" for="ecg">
+          <input id="ecg" name="ecg" type="file" accept="image/*" />
+          <span id="dropText">Click or drop a 12-lead ECG image here</span>
+          <img class="preview" id="preview" alt="" hidden />
+          <div class="filename" id="filename"></div>
+        </label>
+      </div>
+
+      <div class="mode" id="modeIndicator">Will run: <b>—</b></div>
+
+      <button type="submit" class="btn" id="submitBtn">
+        <span class="btn-text">Assess Risk</span>
+      </button>
+    </form>
+
+    <div class="error-msg" id="errorMsg"></div>
+
+    <!-- Result -->
+    <div class="result" id="resultPanel">
+      <div class="headline">
+        <div class="label-wrap">
+          <span class="badge" id="badge"></span>
+          <span class="msg" id="riskMsg"></span>
+        </div>
+        <span class="pct" id="riskPct"></span>
+      </div>
+      <div class="branches" id="branches"></div>
+      <div class="combined-note" id="combinedNote" hidden></div>
+    </div>
+
+    <div class="disclaimer">
+      <b>Research / educational demo — not for clinical use.</b> The tabular model
+      (Framingham) estimates 10-year coronary-heart-disease risk; the ECG model
+      classifies the current ECG. They are trained on different populations with
+      no shared patients, so the combined score is a simple average (a transparent
+      heuristic), not a validated clinical measurement.
+    </div>
+  </div>
+
+  <script>
+    const form    = document.getElementById('predictForm');
+    const btn     = document.getElementById('submitBtn');
+    const errDiv  = document.getElementById('errorMsg');
+    const result  = document.getElementById('resultPanel');
+    const badge   = document.getElementById('badge');
+    const riskMsg = document.getElementById('riskMsg');
+    const riskPct = document.getElementById('riskPct');
+    const branchesEl = document.getElementById('branches');
+    const combinedNote = document.getElementById('combinedNote');
+    const modeInd = document.getElementById('modeIndicator');
+
+    const TABULAR_FIELDS = ['male','age','education','currentSmoker','cigsPerDay',
+      'BPMeds','prevalentStroke','prevalentHyp','diabetes','totChol','sysBP',
+      'diaBP','BMI','heartRate','glucose'];
+
+    const MESSAGES = {
+      High:     'Elevated risk — recommend clinical evaluation',
+      Moderate: 'Borderline — monitor and consult a clinician',
+      Low:      'Lower risk — maintain healthy habits',
+    };
+
+    // ── ECG upload preview ────────────────────────────────────────────
+    const ecgInput = document.getElementById('ecg');
+    const dropZone = document.getElementById('dropZone');
+    const dropText = document.getElementById('dropText');
+    const preview  = document.getElementById('preview');
+    const filename = document.getElementById('filename');
+
+    ecgInput.addEventListener('change', () => showEcg(ecgInput.files[0]));
+    ['dragover','dragenter'].forEach(ev => dropZone.addEventListener(ev, e => {
+      e.preventDefault(); dropZone.classList.add('drag');
+    }));
+    ['dragleave','drop'].forEach(ev => dropZone.addEventListener(ev, e => {
+      e.preventDefault(); dropZone.classList.remove('drag');
+    }));
+    dropZone.addEventListener('drop', e => {
+      if (e.dataTransfer.files.length) { ecgInput.files = e.dataTransfer.files; showEcg(ecgInput.files[0]); }
+    });
+
+    function showEcg(file) {
+      if (!file) return;
+      filename.textContent = file.name;
+      dropText.hidden = true;
+      preview.hidden = false;
+      preview.src = URL.createObjectURL(file);
+      updateMode();
+    }
+
+    // ── Mode indicator ────────────────────────────────────────────────
+    function hasTabular() {
+      return TABULAR_FIELDS.some(f => {
+        const el = document.getElementById(f);
+        return el && el.value.trim() !== '';
+      });
+    }
+    function hasEcg() { return ecgInput.files.length > 0; }
+
+    function updateMode() {
+      const t = hasTabular(), e = hasEcg();
+      let m = '—';
+      if (t && e) m = 'Both → averaged';
+      else if (t) m = 'Tabular (Framingham)';
+      else if (e) m = 'ECG (ResNet)';
+      modeInd.innerHTML = 'Will run: <b>' + m + '</b>';
+    }
+    form.addEventListener('input', updateMode);
+    updateMode();
+
+    // ── Submit ────────────────────────────────────────────────────────
+    form.addEventListener('submit', async (e) => {
+      e.preventDefault();
+      errDiv.classList.remove('show');
+      result.classList.remove('show', 'high', 'moderate', 'low');
+
+      if (!hasTabular() && !hasEcg()) {
+        return showError('Enter at least one patient field or upload an ECG image.');
+      }
+
+      // Build multipart payload: only non-empty fields (blanks → KNN-imputed server-side)
+      const fd = new FormData();
+      TABULAR_FIELDS.forEach(f => {
+        const v = document.getElementById(f).value.trim();
+        if (v !== '') fd.append(f, v);
+      });
+      if (hasEcg()) fd.append('ecg', ecgInput.files[0]);
+
+      btn.classList.add('loading');
+      btn.disabled = true;
+      try {
+        const res = await fetch('/predict', { method: 'POST', body: fd });
+        const data = await res.json();
+        if (!res.ok) throw new Error(data.detail || 'Server error');
+        showResult(data);
+      } catch (err) {
+        showError(err.message || 'Failed to reach the server.');
+      } finally {
+        btn.classList.remove('loading');
+        btn.disabled = false;
+      }
+    });
+
+    function showError(msg) {
+      errDiv.textContent = msg;
+      errDiv.classList.add('show');
+    }
+
+    // ── Render result ─────────────────────────────────────────────────
+    function pctStr(p) { return (p * 100).toFixed(1) + '%'; }
+    function pretty(c) {
+      return c.replace(/_ecg_images$/, '').replace(/_/g, ' ')
+              .replace(/\bmi\b/gi, 'MI')
+              .replace(/\b\w/g, m => m.toUpperCase());
+    }
+
+    function showResult(data) {
+      const level = data.risk_level;
+      result.className = 'result ' + level.toLowerCase();
+      badge.textContent = level + ' risk';
+      riskMsg.textContent = MESSAGES[level] || '';
+      riskPct.textContent = pctStr(data.p_risk);
+
+      branchesEl.innerHTML = '';
+      const b = data.branches || {};
+
+      if (b.tabular) {
+        const t = b.tabular;
+        const imp = (t.imputed_fields && t.imputed_fields.length)
+          ? `KNN-imputed: ${t.imputed_fields.join(', ')}` : 'No fields imputed';
+        branchesEl.appendChild(branchCard(
+          'Tabular · Framingham 10-yr CHD', t.p_risk, t.band,
+          [['P(CHD)', t.detail['CHD']]], imp));
+      }
+      if (b.ecg) {
+        const ec = b.ecg;
+        const rows = Object.entries(ec.detail).map(([k, v]) => [pretty(k), v]);
+        const conf = (ec.confidence != null)
+          ? `  ·  confidence ${(ec.confidence * 100).toFixed(1)}%` : '';
+        branchesEl.appendChild(branchCard(
+          'ECG · ResNet', ec.p_risk, ec.band, rows,
+          'Predicted: ' + pretty(ec.ecg_class) + conf, ec.warning));
+      }
+
+      if (data.mode === 'multimodal') {
+        combinedNote.hidden = false;
+        combinedNote.textContent =
+          `Combined = average of tabular (${pctStr(b.tabular.p_risk)}) and ECG (${pctStr(b.ecg.p_risk)})`;
+      } else {
+        combinedNote.hidden = true;
+      }
+
+      requestAnimationFrame(() => {
+        result.classList.add('show');
+        setTimeout(() => {
+          result.querySelectorAll('.prob-fill').forEach(el => {
+            el.style.width = el.dataset.w + '%';
+          });
+        }, 80);
+      });
+    }
+
+    function branchCard(title, pRisk, band, rows, subtitle, warning) {
+      const card = document.createElement('div');
+      card.className = 'branch';
+      const header = `<h4>${title}<span class="b-pct">${pctStr(pRisk)} · ${band}</span></h4>`;
+      const sub = subtitle ? `<div class="sub">${subtitle}</div>` : '';
+      const bars = rows.map(([label, val]) => {
+        const w = (val * 100).toFixed(1);
+        return `<div class="prob-row">
+            <span class="prob-label" title="${label}">${label}</span>
+            <div class="prob-track"><div class="prob-fill" data-w="${w}"></div></div>
+            <span class="prob-value">${w}%</span>
+          </div>`;
+      }).join('');
+      const warn = warning ? `<div class="warn">&#9888; ${warning}</div>` : '';
+      card.innerHTML = header + sub + bars + warn;
+      return card;
+    }
+  </script>
+</body>
+</html>