🫀 CardioSense AI

AI-Powered Cardiovascular Risk Prediction API

Production-grade heart disease risk assessment using Machine Learning, SHAP explainability, and LLM-powered patient consultation.

---

📖 Overview

CardioSense AI is a production-ready REST API backend for cardiovascular risk prediction, combining the power of XGBoost machine learning, SHAP explainability, and an LLM-powered chatbot (CardioBot) to deliver personalised heart health insights.

Built with a healthcare-first mindset — every prediction comes with:

• ✅ A calibrated risk score (0–100%) backed by isotonic regression
• ✅ The top SHAP-ranked factors driving that specific patient's risk
• ✅ Personalised, rule-based clinical recommendations
• ✅ An AI assistant (CardioBot) that can answer patient questions in context

Disclaimer: CardioSense is a portfolio/research project and is not a certified medical device. Always consult a qualified healthcare professional for medical decisions.

---

✨ Features

Feature	Details
🤖 ML Risk Prediction	XGBoost trained on 29 clinical + lifestyle features with Optuna hyperparameter optimisation
📊 Calibrated Probabilities	Isotonic regression calibration — risk scores are statistically meaningful
🔍 SHAP Explainability	Per-patient feature attribution surfacing the top drivers of risk
💬 LLM Chatbot Proxy	Secure server-side proxy to Anthropic Claude / OpenRouter — API key never exposed to browser
🔒 Production Security	Rate limiting (slowapi), CORS lockdown, file upload size cap, MIME type validation
📋 Medical Report Upload	PDF/image upload with regex-based clinical value extraction
⚡ API Versioning	All routes under /api/v1/ for non-breaking upgrades
🐳 Docker Ready	Multi-stage Dockerfile + docker-compose for one-command deployment
🧪 Full Test Suite	18 pytest tests covering happy paths, validation, edge cases, mocks
📈 MLflow Tracking	Experiment logging for hyperparameters, metrics, and model artefacts

---

🏗️ Project Structure

cardiosense/
│
├── 📁 backend/
│   ├── 📁 api/
│   │   ├── 📁 ml/
│   │   │   └── train.py              # Optuna + XGBoost training pipeline
│   │   ├── 📁 routers/
│   │   │   ├── chat_router.py        # POST /api/v1/chat  — LLM proxy (API key stays server-side)
│   │   │   ├── predict_router.py     # POST /api/v1/predict — risk prediction + SHAP
│   │   │   └── upload_router.py      # POST /api/v1/upload-report — PDF/image parser
│   │   ├── 📁 schemas/
│   │   │   └── patient.py            # Pydantic request/response models with field validation
│   │   ├── 📁 services/
│   │   │   ├── llm.py                # Anthropic + OpenRouter client singleton
│   │   │   └── predictor.py          # ML inference, SHAP, recommendations
│   │   ├── __init__.py
│   │   ├── config.py                 # Pydantic-settings — single typed config from .env
│   │   └── main.py                   # FastAPI app factory + lifespan event handler
│   │
│   ├── 📁 data/
│   │   └── heart.csv                 # UCI Heart Disease dataset (303 records)
│   │
│   ├── 📁 frontend/
│   │   └── src/
│   │       └── cardiobot_secure.js   # Secure chat widget — calls backend proxy, no keys in browser
│   │
│   ├── 📁 models/                    # Generated by training (gitignored)
│   │   └── heart_model.pkl           # Serialised pipeline: model + scaler + metadata
│   │
│   └── 📁 tests/
│       ├── __init__.py
│       └── test_api.py               # 18 pytest tests with mocked ML model
│
├── .env                              # Local secrets (never commit)
├── .env.example                      # Template — copy this to .env
├── .ci.yml                           # GitHub Actions CI: lint → test → Docker build
├── docker-compose.yml                # Backend + Nginx full-stack compose
├── Dockerfile                        # Multi-stage build (~200MB final image)
└── requirements_v2.txt               # Pinned production dependencies

---

🧠 ML Model Architecture

Raw Patient Data (29 features)
         │
         ▼
┌─────────────────────────────┐
│   Feature Engineering       │
│  • pulse_pressure           │
│  • age_sex_interaction      │
│  • metabolic_syndrome       │
│  • tachycardia_flag         │
│  • chol_age_ratio           │
└────────────┬────────────────┘
             │
             ▼
┌─────────────────────────────┐
│   StandardScaler            │  ← fitted on train set, saved in pipeline
└────────────┬────────────────┘
             │
             ▼
┌─────────────────────────────┐
│   XGBoost Classifier        │  ← Optuna-tuned (40 Bayesian trials)
│   scale_pos_weight = auto   │  ← handles class imbalance
└────────────┬────────────────┘
             │
             ▼
┌─────────────────────────────┐
│  CalibratedClassifierCV     │  ← isotonic regression calibration
│  method = isotonic, cv = 5  │  ← makes probability scores trustworthy
└────────────┬────────────────┘
             │
        ┌────┴─────┐
        ▼          ▼
  Risk Score    SHAP Values
   (0–100%)    (top 8 factors)

Model Metrics (UCI Heart Disease dataset)

Metric	Score
ROC-AUC	0.89
Accuracy	0.84
Brier Score	0.14 (lower = better calibration)
Average Precision	0.88

Features span 13 core UCI clinical variables + 16 synthetic lifestyle/symptom placeholders (BMI, smoking, stress, etc.) designed for a real patient intake form.

---

🛠️ Tech Stack

Layer	Technology	Purpose
API Framework	FastAPI 0.111	Async REST API with auto-generated OpenAPI docs
ML Engine	XGBoost 2.0 + scikit-learn	Risk prediction model
Explainability	SHAP 0.45	Per-patient feature attribution
Hyperparameter Search	Optuna 3.6	Bayesian optimisation (replaces GridSearchCV)
Calibration	sklearn CalibratedClassifierCV	True probability outputs
LLM Integration	Anthropic Claude / OpenRouter	CardioBot patient assistant
Config Management	pydantic-settings	Typed, validated environment variables
Rate Limiting	slowapi	Per-IP limits on all endpoints
Experiment Tracking	MLflow	Training run history and model registry
Containerisation	Docker + docker-compose	Reproducible deployment
Testing	Pytest 8.2	18 tests with mocked ML dependencies
CI/CD	GitHub Actions	Lint → Test → Docker build on every push

---

🚀 Getting Started

Prerequisites

• Python 3.11+
• pip package manager
• At least one API key: Anthropic Console or OpenRouter
• heart.csv dataset — download from UCI ML Repository

---

1. Clone the Repository

git clone https://github.com/yourusername/cardiosense.git
cd cardiosense

---

2. Create a Virtual Environment

macOS / Linux

python3 -m venv venv
source venv/bin/activate

Windows PowerShell

python -m venv venv
.\venv\Scripts\Activate.ps1

Windows Command Prompt

python -m venv venv
venv\Scripts\activate.bat

---

3. Install Dependencies

pip install -r requirements_v2.txt

Verify the key packages installed correctly:

python -c "import fastapi, xgboost, shap, optuna, slowapi; print('All packages OK ✓')"

---

4. Configure Environment Variables

# Copy the template
cp .env.example .env

Open .env and fill in your values:

# Required — at least one LLM key
ANTHROPIC_API_KEY=sk-ant-your-key-here
OPENROUTER_API_KEY=sk-or-your-key-here      # alternative to Anthropic

# Model
MODEL_PATH=models/heart_model.pkl
MODEL_VERSION=2.0.0

# Security — set to your frontend URL in production
ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173

# Rate limits
RATE_LIMIT_PREDICT=30/minute
RATE_LIMIT_CHAT=10/minute
RATE_LIMIT_UPLOAD=5/minute

# Logging
LOG_LEVEL=INFO
LOG_PREDICTIONS=true

# LLM
LLM_MODEL=claude-sonnet-4-20250514
LLM_MAX_TOKENS=800

---

5. Create __init__.py Files

Python needs these to treat each folder as an importable package:

macOS / Linux

touch backend/__init__.py \
      backend/api/__init__.py \
      backend/api/routers/__init__.py \
      backend/services/__init__.py \
      backend/schemas/__init__.py \
      backend/ml/__init__.py \
      tests/__init__.py

Windows PowerShell

@(
  "backend/__init__.py",
  "backend/api/__init__.py",
  "backend/api/routers/__init__.py",
  "backend/services/__init__.py",
  "backend/schemas/__init__.py",
  "backend/ml/__init__.py",
  "tests/__init__.py"
) | ForEach-Object { New-Item -Force -ItemType File $_ }

---

6. Place the Dataset and Train the Model

# Create required folders
mkdir -p data models

# Copy your UCI heart.csv into data/
cp /path/to/heart.csv data/

# Train — runs Optuna optimisation, calibration, saves heart_model.pkl
python -m backend.ml.train

Expected output:

============================================================
  CardioSense ML Training Pipeline v2.0
============================================================
Loaded 303 records from data/heart.csv
Train: 242 | Test: 61
Training XGBoost with Optuna hyperparameter search...
  Best Optuna AUC: 0.9124
  Calibrating probability outputs...
Pipeline saved → models/heart_model.pkl
SHAP plot saved → models/shap_XGBoost.png
Training complete in 87.3s

---

7. Start the Backend Server

Development (with auto-reload)

uvicorn backend.api.main:app --reload --port 8000

Windows PowerShell

uvicorn backend.api.main:app --reload --port 8000

Production (multiple workers)

gunicorn backend.api.main:app -w 2 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

Confirm everything is working:

curl http://localhost:8000/health

Expected response:

{
  "status": "healthy",
  "model_loaded": true,
  "model_name": "XGBoost (Optuna + Calibrated)",
  "model_version": "2.0.0",
  "features": 34
}

---

🐳 Docker Setup

Build and Run with Docker

# Build the image
docker build -t cardiosense:v2 .

# Run the container
docker run -p 8000:8000 \
  -e ANTHROPIC_API_KEY=your-key \
  -e ALLOWED_ORIGINS=http://localhost:3000 \
  -v $(pwd)/models:/app/models:ro \
  cardiosense:v2

Windows PowerShell

docker run -p 8000:8000 `
  -e ANTHROPIC_API_KEY=your-key `
  -e ALLOWED_ORIGINS=http://localhost:3000 `
  -v ${PWD}/models:/app/models:ro `
  cardiosense:v2

Full Stack with docker-compose

# Start backend + Nginx (serves frontend static files)
docker-compose up --build

# Stop everything
docker-compose down

---

📡 API Reference

Base URL

http://localhost:8000/api/v1

Endpoints

Method	Endpoint	Description	Rate Limit
GET	/health	Server and model status	—
POST	/api/v1/predict	Heart risk prediction + SHAP	30/min
POST	/api/v1/chat	CardioBot LLM assistant	10/min
POST	/api/v1/upload-report	Parse medical PDF/image	5/min

---

POST /api/v1/predict

Accepts a patient profile and returns a calibrated risk score with SHAP explanations.

Request

curl -X POST http://localhost:8000/api/v1/predict \
  -H "Content-Type: application/json" \
  -d '{
    "age": 55,
    "sex": 1,
    "cp": 2,
    "trestbps": 140,
    "chol": 265,
    "fbs": 0,
    "restecg": 1,
    "thalach": 145,
    "exang": 0,
    "oldpeak": 1.8,
    "slope": 1,
    "ca": 1,
    "thal": 2,
    "bmi": 29.5,
    "smoking_score": 2,
    "alcohol_score": 1,
    "activity_score": 2,
    "sleep_score": 2,
    "stress_level": 7,
    "diet_score": 4,
    "family_hx": 1,
    "hypertension": 1,
    "diabetes": 0,
    "prev_heart_disease": 0,
    "high_cholesterol": 1,
    "anxiety_depression": 0,
    "symptom_chest_pain": 1,
    "symptom_shortness_breath": 0,
    "symptom_dizziness": 0,
    "symptom_fatigue": 1,
    "alcohol_score": 1
  }'

Windows PowerShell

Invoke-RestMethod -Uri "http://localhost:8000/api/v1/predict" `
  -Method POST `
  -ContentType "application/json" `
  -Body '{"age":55,"sex":1,"cp":2,"trestbps":140,"chol":265,"fbs":0,"restecg":1,"thalach":145,"exang":0,"oldpeak":1.8,"slope":1,"ca":1,"thal":2,"bmi":29.5,"smoking_score":2,"alcohol_score":1,"activity_score":2,"sleep_score":2,"stress_level":7,"diet_score":4,"family_hx":1,"hypertension":1,"diabetes":0,"prev_heart_disease":0,"high_cholesterol":1,"anxiety_depression":0,"symptom_chest_pain":1,"symptom_shortness_breath":0,"symptom_dizziness":0,"symptom_fatigue":1}'

Response

{
  "prediction": 1,
  "probability": 0.7243,
  "risk_level": "High",
  "risk_score": 72,
  "model_name": "XGBoost (Optuna + Calibrated)",
  "model_version": "2.0.0",
  "message": "High risk detected. Please schedule a cardiology consultation soon.",
  "top_factors": [
    {
      "feature": "ca",
      "label": "Major Vessels",
      "shap_value": 0.4821,
      "direction": "increases",
      "value": 1.0
    },
    {
      "feature": "thal",
      "label": "Thalassemia",
      "shap_value": 0.3104,
      "direction": "increases",
      "value": 2.0
    },
    {
      "feature": "cp",
      "label": "Chest Pain Type",
      "shap_value": 0.2897,
      "direction": "increases",
      "value": 2.0
    },
    {
      "feature": "activity_score",
      "label": "Activity Level",
      "shap_value": -0.1823,
      "direction": "decreases",
      "value": 2.0
    },
    {
      "feature": "oldpeak",
      "label": "ST Depression",
      "shap_value": 0.1654,
      "direction": "increases",
      "value": 1.8
    }
  ],
  "recommendations": [
    {
      "title": "Control Blood Pressure",
      "text": "BP 140 mmHg is elevated. Reduce salt intake, exercise regularly, and consult a doctor.",
      "urgency": "urgent"
    },
    {
      "title": "Quit Smoking",
      "text": "Smoking significantly raises heart attack risk. Seek cessation support.",
      "urgency": "urgent"
    },
    {
      "title": "See a Cardiologist",
      "text": "Given your risk profile, a specialist visit is strongly recommended.",
      "urgency": "urgent"
    }
  ]
}

---

POST /api/v1/chat

Sends a message to CardioBot. The patient profile and risk result are injected into the system prompt server-side for personalised responses.

curl -X POST http://localhost:8000/api/v1/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What does my cholesterol level mean for my heart risk?",
    "history": [],
    "patient_data": { "chol": 265, "age": 55 },
    "prediction_data": { "risk_score": 72, "risk_level": "High" }
  }'

Response

{
  "reply": "Your cholesterol of 265 mg/dL is above the high-risk threshold of 240 mg/dL, which contributes to plaque buildup in your arteries — a key factor in your elevated risk score. Combined with your age and blood pressure, reducing saturated fat intake and discussing statin therapy with your doctor would be a sensible next step. Consult a doctor for personalised diagnosis."
}

---

GET /health

curl http://localhost:8000/health

{
  "status": "healthy",
  "model_loaded": true,
  "model_name": "XGBoost (Optuna + Calibrated)",
  "model_version": "2.0.0",
  "features": 34
}

---

POST /api/v1/upload-report

Upload a medical report PDF or image. Returns extracted clinical values.

curl -X POST http://localhost:8000/api/v1/upload-report \
  -F "file=@/path/to/report.pdf"

{
  "extracted_fields": {
    "chol": 265,
    "trestbps": 140,
    "thalach": 145,
    "bmi": 29.5
  },
  "fields_found": 4,
  "message": "Extracted 4 field(s) from your report.",
  "filename": "report.pdf"
}

---

🧪 Running Tests

# Run all 18 tests
pytest tests/ -v

# Run a specific test class
pytest tests/ -v -k "predict"

# Run with coverage report
pip install pytest-cov
pytest tests/ --cov=backend --cov-report=term-missing

# Short tracebacks (cleaner output)
pytest tests/ -v --tb=short

Expected output:

tests/test_api.py::TestHealth::test_health_returns_200          PASSED
tests/test_api.py::TestHealth::test_health_shows_model_loaded   PASSED
tests/test_api.py::TestHealth::test_root_returns_ok             PASSED
tests/test_api.py::TestPredict::test_predict_valid_patient      PASSED
tests/test_api.py::TestPredict::test_predict_response_has_required_fields  PASSED
tests/test_api.py::TestPredict::test_predict_risk_score_in_range           PASSED
tests/test_api.py::TestPredict::test_predict_probability_in_range          PASSED
tests/test_api.py::TestPredict::test_predict_risk_level_valid              PASSED
tests/test_api.py::TestPredict::test_predict_rejects_invalid_age           PASSED
tests/test_api.py::TestPredict::test_predict_rejects_negative_cholesterol  PASSED
...

18 passed in 2.34s

---

🔐 Environment Variables

Variable	Required	Default	Description
ANTHROPIC_API_KEY	✅ one of	—	Claude API key from console.anthropic.com
OPENROUTER_API_KEY	✅ one of	—	OpenRouter key (alternative to Anthropic)
MODEL_PATH	No	models/heart_model.pkl	Path to trained model file
MODEL_VERSION	No	2.0.0	Logged in /health response
ALLOWED_ORIGINS	No	http://localhost:3000	Comma-separated CORS allowed origins
RATE_LIMIT_PREDICT	No	30/minute	Per-IP rate limit on /predict
RATE_LIMIT_CHAT	No	10/minute	Per-IP rate limit on /chat
RATE_LIMIT_UPLOAD	No	5/minute	Per-IP rate limit on /upload-report
LOG_LEVEL	No	INFO	DEBUG / INFO / WARNING
LOG_PREDICTIONS	No	true	Log risk score + latency per request
LLM_PROVIDER	No	anthropic	anthropic or openrouter
LLM_MODEL	No	claude-sonnet-4-20250514	Model string for LLM calls
LLM_MAX_TOKENS	No	800	Max tokens in CardioBot replies
MAX_UPLOAD_BYTES	No	5242880	Max file upload size (5 MB)

---

🔮 Future Improvements

• PostgreSQL integration — persist predictions and chat history per patient session
• JWT authentication — secure endpoints with token-based auth for multi-user support
• Real lifestyle data — replace synthetic features with a validated patient intake form
• FHIR / HL7 support — ingest structured medical records from hospital systems
• Drift detection — Evidently-powered alerts when incoming data distribution shifts from training data
• Model retraining pipeline — automated weekly retraining triggered by drift alerts
• React frontend — migrate from single HTML file to a component-based Vite + React UI
• Websocket chat — real-time streaming CardioBot responses instead of request/response
• Multi-language support — i18n for patient-facing recommendations and chatbot replies
• A/B model serving — shadow testing of new models against production traffic

---

🤝 Contributing

Contributions are welcome. Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Write tests for any new behaviour (maintain 100% test pass rate)
4. Lint your code: ruff check backend/
5. Commit with a clear message: git commit -m "feat: add JWT authentication middleware"
6. Push to your fork: git push origin feature/your-feature-name
7. Open a Pull Request — describe what you changed and why

Please ensure all 18 existing tests still pass before opening a PR.

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

MIT License

Copyright (c) 2025 [Your Name]

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.

---

👤 Author

Sukumar

)

Built with ❤️ as a production-grade ML portfolio project

---

⭐ Star this repo if you found it useful — it helps others discover the project