Deploy v0.0.1 from GitHub Actions

.env.example

@@ -0,0 +1,6 @@
+MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/
+DATABASE_NAME=cardiac_monitor
+JWT_SECRET=change-this-to-a-random-secret-key
+JWT_ALGORITHM=HS256
+JWT_EXPIRY_HOURS=24
+API_KEY=your-device-api-key-here

.gitattributes

@@ -1,35 +0,0 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -13,16 +13,21 @@ RUN pip install --no-cache-dir -r requirements.txt
 COPY app/ app/
 COPY ml_src/ ml_src/
 
-# Download ML models from GitHub LFS (avoids LFS issues on HF Spaces)
-RUN mkdir -p ml_models && \
-    apt-get update && apt-get install -y --no-install-recommends curl && \
-    curl -L -o ml_models/ecgfounder_best.pt \
-      "https://media.githubusercontent.com/media/Sanuka23/cardiac-monitor/main/backend/ml_models/ecgfounder_best.pt" && \
-    curl -L -o ml_models/xgboost_cardiac.joblib \
-      "https://media.githubusercontent.com/media/Sanuka23/cardiac-monitor/main/backend/ml_models/xgboost_cardiac.joblib" && \
-    apt-get purge -y curl && apt-get autoremove -y && rm -rf /var/lib/apt/lists/* && \
-    echo "Model sizes:" && ls -lh ml_models/
+# Copy model files — if they're Git LFS pointers, download the real files from GitHub
+COPY ml_models/ ml_models/
+RUN MODEL_SIZE=$(wc -c < ml_models/ecgfounder_best.pt) && \
+    if [ "$MODEL_SIZE" -lt 1000 ]; then \
+        echo "Detected LFS pointers — downloading real model files from GitHub..." && \
+        apt-get update && apt-get install -y --no-install-recommends curl && \
+        curl -L -o ml_models/ecgfounder_best.pt \
+          "https://media.githubusercontent.com/media/Sanuka23/cardiac-monitor/main/backend/ml_models/ecgfounder_best.pt" && \
+        curl -L -o ml_models/xgboost_cardiac.joblib \
+          "https://media.githubusercontent.com/media/Sanuka23/cardiac-monitor/main/backend/ml_models/xgboost_cardiac.joblib" && \
+        apt-get purge -y curl && apt-get autoremove -y && rm -rf /var/lib/apt/lists/*; \
+    else \
+        echo "Model files are real (not LFS pointers) — no download needed"; \
+    fi
 
 EXPOSE 7860
 
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "7860"]
+CMD uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-7860}

README.md

@@ -12,12 +12,139 @@ short_description: Cardiac monitoring API with ML risk prediction
 
 # Cardiac Monitor API
 
-FastAPI backend for ESP32 Heart Rate, SpO2 & ECG cardiac monitoring system with ML-based risk prediction.
+FastAPI backend for the ESP32 cardiac monitoring system. Handles user authentication, device management, vitals storage, and ML-based cardiac risk prediction.
 
-## Endpoints
+## Live Deployment
 
-- `GET /api/v1/health` — Health check
-- `POST /api/v1/auth/register` — Register
-- `POST /api/v1/auth/login` — Login (JWT)
-- `GET /api/v1/vitals/{device_id}` — Vitals history
-- `GET /api/v1/predictions/{device_id}` — Risk predictions
+**URL**: `https://sanuka0523-cardiac-monitor-api.hf.space`
+
+Hosted on Hugging Face Spaces (Docker SDK). The API docs are available at `/docs` (Swagger UI).
+
+## Tech Stack
+
+- **Framework**: FastAPI 0.115
+- **Database**: MongoDB Atlas via Motor (async)
+- **Auth**: JWT (python-jose) + bcrypt password hashing
+- **ML**: PyTorch (ECGFounder) + XGBoost ensemble
+- **Signal Processing**: NeuroKit2, SciPy
+
+## API Reference
+
+### Authentication
+
+| Method | Path | Body | Response |
+|--------|------|------|----------|
+| POST | `/api/v1/auth/register` | `{email, password, name}` | `{access_token, token_type}` |
+| POST | `/api/v1/auth/login` | Form: `username, password` | `{access_token, token_type}` |
+| GET | `/api/v1/auth/me` | — | User object |
+| PUT | `/api/v1/auth/profile` | `{health_profile: {...}}` | Updated user |
+
+### Devices
+
+| Method | Path | Body | Response |
+|--------|------|------|----------|
+| POST | `/api/v1/devices/register` | `{device_id}` | Device object |
+| GET | `/api/v1/devices` | — | List of devices |
+
+### Vitals (ESP32 uploads)
+
+| Method | Path | Auth | Body |
+|--------|------|------|------|
+| POST | `/api/v1/vitals` | API Key | `{device_id, timestamp, ecg_samples, heart_rate_bpm, spo2_percent, ...}` |
+| GET | `/api/v1/vitals/{device_id}` | JWT | Vitals history (paginated) |
+| GET | `/api/v1/vitals/{device_id}/latest` | JWT | Latest vitals reading |
+
+### Predictions
+
+| Method | Path | Auth | Response |
+|--------|------|------|----------|
+| GET | `/api/v1/predictions/{device_id}/latest` | JWT | Latest risk prediction |
+| GET | `/api/v1/predictions/{device_id}` | JWT | Prediction history |
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `MONGODB_URI` | MongoDB Atlas connection string | Yes |
+| `DATABASE_NAME` | Database name (default: `cardiac_monitor`) | No |
+| `JWT_SECRET` | Secret key for JWT signing | Yes |
+| `API_KEY` | API key for ESP32 device auth | Yes |
+
+## Database Collections
+
+| Collection | Purpose | Key Fields |
+|------------|---------|------------|
+| `users` | User accounts + health profiles | email, password_hash, health_profile |
+| `devices` | Registered ESP32 devices | device_id, owner_user_id |
+| `vitals` | Raw vitals readings | device_id, timestamp, ecg_samples, heart_rate_bpm |
+| `predictions` | ML risk predictions | vitals_id, risk_score, risk_label, confidence |
+
+## ML Pipeline
+
+On each vitals upload, the backend runs an ensemble prediction:
+
+1. **ECGFounder** (PyTorch): Deep learning model extracts features from raw ECG waveform
+2. **Feature Engineering**: 14 clinical features (HRV, QRS duration, signal quality, etc.)
+3. **XGBoost**: Gradient-boosted classifier on combined features
+4. **Ensemble**: Weighted combination produces final risk score (0.0-1.0) and label
+
+Risk labels: `normal`, `low`, `moderate`, `elevated`, `high`
+
+## Local Development
+
+```bash
+cd backend
+pip install -r requirements.txt
+
+# Set environment variables
+export MONGODB_URI="mongodb+srv://..."
+export JWT_SECRET="your-secret"
+export API_KEY="your-api-key"
+
+# Run
+uvicorn app.main:app --reload --port 8000
+```
+
+## Docker Deployment
+
+```bash
+docker build -t cardiac-api .
+docker run -p 7860:7860 \
+  -e MONGODB_URI="..." \
+  -e JWT_SECRET="..." \
+  -e API_KEY="..." \
+  cardiac-api
+```
+
+## Project Structure
+
+```
+backend/
+├── app/
+│   ├── main.py              # FastAPI app, CORS, router mounting
+│   ├── config.py            # Pydantic settings (env vars)
+│   ├── database.py          # Motor client, index creation
+│   ├── middleware/
+│   │   └── auth.py          # JWT + API key verification
+│   ├── models/              # Pydantic request/response models
+│   │   ├── user.py
+│   │   ├── device.py
+│   │   ├── vitals.py
+│   │   └── prediction.py
+│   ├── routes/              # API endpoint handlers
+│   │   ├── auth.py
+│   │   ├── devices.py
+│   │   ├── health.py
+│   │   ├── vitals.py
+│   │   └── predictions.py
+│   └── services/
+│       └── ml_service.py    # ML model loading + prediction
+├── ml_src/
+│   ├── ecg_foundation.py    # ECGFounder model definition
+│   └── feature_engineer.py  # Clinical feature extraction
+├── ml_models/               # Trained model files (LFS)
+│   ├── ecgfounder_best.pt
+│   └── xgboost_cardiac.joblib
+├── Dockerfile
+└── requirements.txt
+```

app/database.py

@@ -27,7 +27,6 @@ async def connect_db(uri: str, db_name: str):
 
 
 async def close_db():
-    global client
     if client:
         client.close()
 

app/main.py

@@ -40,6 +40,7 @@ app.add_middleware(
     allow_headers=["*"],
 )
 
+
 @app.get("/", include_in_schema=False)
 async def root():
     return RedirectResponse(url="/docs")

app/models/prediction.py

@@ -1,5 +1,4 @@
 from pydantic import BaseModel, Field
-from typing import Optional
 from datetime import datetime
 
 

app/models/user.py

@@ -1,4 +1,4 @@
-from pydantic import BaseModel, EmailStr, Field
+from pydantic import BaseModel, Field
 from typing import List, Optional
 from datetime import datetime
 

app/services/feature_extractor.py

@@ -10,7 +10,7 @@ import sys
 ML_SRC = os.path.join(os.path.dirname(__file__), "..", "..", "ml_src")
 sys.path.insert(0, ML_SRC)
 
-from feature_extractor import (
+from feature_extractor import (  # noqa: E402
     extract_ecg_features,
     features_to_array,
     FEATURE_NAMES,

app/services/ml_service.py

@@ -15,8 +15,8 @@ BACKEND_ROOT = os.path.join(os.path.dirname(__file__), "..", "..")
 ML_SRC = os.path.join(BACKEND_ROOT, "ml_src")
 sys.path.insert(0, ML_SRC)
 
-from net1d import Net1D
-from feature_extractor import extract_ecg_features, features_to_array, FEATURE_NAMES
+from net1d import Net1D  # noqa: E402
+from feature_extractor import extract_ecg_features, features_to_array, FEATURE_NAMES  # noqa: E402
 
 # Model paths — bundled in backend/ml_models/
 MODEL_DIR = os.path.join(BACKEND_ROOT, "ml_models")
@@ -83,7 +83,7 @@ def load_models():
                 use_do=False,
                 n_classes=1,
             )
-            state_dict = torch.load(ecg_path, map_location=_device, weights_only=False)
+            state_dict = torch.load(ecg_path, map_location=_device, weights_only=False)  # nosec B614
             _ecg_model.load_state_dict(state_dict)
             _ecg_model.to(_device)
             _ecg_model.eval()

ml_models/ecgfounder_best.pt

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

ml_models/xgboost_cardiac.joblib

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

ml_src/README.md

@@ -0,0 +1,97 @@
+# ML Pipeline
+
+Cardiac risk prediction using an ensemble of ECGFounder (deep learning) and XGBoost (gradient boosting).
+
+## Model Architecture
+
+```
+Raw ECG (1000 samples @ 100Hz)
+        │
+        ├──> ECGFounder (1D CNN)──> 128-dim embedding
+        │                                │
+        ├──> Feature Engineering ────────>├──> 14 clinical features
+        │    (NeuroKit2 + SciPy)         │
+        │                                v
+        │                          XGBoost Classifier
+        │                                │
+        └── Ensemble ────────────────────>│──> Risk Score (0.0-1.0)
+             (weighted average)               Risk Label
+```
+
+### ECGFounder
+
+- **Architecture**: 1D convolutional neural network (`net1d.py`)
+- **Input**: 1000 ECG samples (10s window at 100Hz), bandpass filtered 0.5-40Hz
+- **Output**: 128-dimensional feature embedding
+- **Model file**: `ml_models/ecgfounder_best.pt` (117 MB)
+
+### XGBoost Classifier
+
+- **Input**: 14 features (ECG embedding + clinical features)
+- **Output**: Binary risk probability
+- **Model file**: `ml_models/xgboost_cardiac.joblib` (752 KB)
+
+## Feature Engineering
+
+The `feature_extractor.py` module computes clinical features from raw ECG:
+
+| Feature | Source | Description |
+|---------|--------|-------------|
+| Heart Rate | Input | BPM from MAX30100 |
+| SpO2 | Input | Blood oxygen percentage |
+| HRV (SDNN) | NeuroKit2 | Heart rate variability |
+| HRV (RMSSD) | NeuroKit2 | Root mean square of successive RR differences |
+| QRS Duration | NeuroKit2 | Ventricular depolarization time |
+| PR Interval | NeuroKit2 | Atrial-ventricular conduction |
+| Signal Quality | SciPy | SNR estimate of ECG signal |
+| Mean RR | Computed | Average R-R interval |
+| RR Irregularity | Computed | Coefficient of variation of RR |
+| Age | Profile | User age (if available) |
+| Sex | Profile | Binary encoded |
+| BMI | Profile | Computed from height/weight |
+| Comorbidity Score | Profile | Count of risk factors |
+| HR Deviation | History | Z-score vs 24h baseline |
+
+## Inference Flow
+
+1. Vitals uploaded to `POST /api/v1/vitals`
+2. If ECG leads are connected and >= 100 samples:
+   a. Load user health profile from database
+   b. Compute 24h and 7d historical baselines
+   c. Extract features from ECG waveform
+   d. Run ECGFounder for deep features
+   e. Combine and run XGBoost
+   f. Store prediction in `predictions` collection
+3. Return vitals + prediction in API response
+
+## Risk Labels
+
+| Score Range | Label | Description |
+|-------------|-------|-------------|
+| 0.00 - 0.20 | normal | No concerning patterns |
+| 0.20 - 0.40 | low | Minor irregularities |
+| 0.40 - 0.60 | moderate | Some risk indicators |
+| 0.60 - 0.80 | elevated | Multiple risk factors |
+| 0.80 - 1.00 | high | Significant cardiac risk |
+
+## Files
+
+```
+ml_src/
+├── __init__.py
+├── net1d.py               # ECGFounder 1D CNN model definition
+└── feature_extractor.py   # Clinical feature extraction
+
+ml_models/
+├── ecgfounder_best.pt     # Trained ECGFounder weights (Git LFS)
+└── xgboost_cardiac.joblib # Trained XGBoost model (Git LFS)
+```
+
+## Dependencies
+
+- `torch` (CPU-only, installed from pytorch.org/whl/cpu)
+- `xgboost >= 2.0.0`
+- `neurokit2 >= 0.2.7`
+- `scipy >= 1.14.1`
+- `numpy >= 1.26.4`
+- `joblib >= 1.3.0`

render.yaml

@@ -0,0 +1,21 @@
+services:
+  - type: web
+    name: cardiac-monitor-api
+    runtime: docker
+    dockerfilePath: ./Dockerfile
+    plan: starter
+    region: oregon
+    healthCheckPath: /api/v1/health
+    envVars:
+      - key: MONGODB_URI
+        sync: false
+      - key: DATABASE_NAME
+        value: cardiac_monitor
+      - key: JWT_SECRET
+        sync: false
+      - key: JWT_ALGORITHM
+        value: HS256
+      - key: JWT_EXPIRY_HOURS
+        value: "24"
+      - key: API_KEY
+        sync: false

requirements.txt

@@ -1,15 +1,15 @@
-fastapi==0.115.6
-uvicorn[standard]==0.34.0
-motor==3.6.0
+fastapi>=0.115.6
+uvicorn[standard]>=0.34.0
+motor>=3.6.0
 pymongo>=4.9,<4.10
-pydantic==2.10.0
-pydantic-settings==2.7.0
-python-jose[cryptography]==3.3.0
-bcrypt==4.2.0
-python-multipart==0.0.18
+pydantic>=2.10.0
+pydantic-settings>=2.7.0
+python-jose[cryptography]>=3.5.0
+bcrypt>=4.2.0
+python-multipart>=0.0.22
 numpy==1.26.4
 scipy==1.14.1
-httpx==0.28.1
+httpx>=0.28.1
 xgboost>=2.0.0
 neurokit2>=0.2.7
 joblib>=1.3.0