A clinical-grade AI system that predicts heart disease risk with 94.1% accuracy — and explains every decision in plain clinical language.
Clinical AI tools today often behave as black boxes — a model outputs a risk score, but clinicians have no way to understand why. This erodes trust, prevents adoption, and creates liability in high-stakes environments.
ExplainableAI Heart Disease Predictor bridges this gap: it combines state-of-the-art predictive performance (94.1% accuracy, 0.967 AUC) with full SHAP + LIME explainability, so every prediction comes with a human-readable clinical rationale — not just a number.
| Metric | Clinical Standard | Our Performance | Improvement |
|---|---|---|---|
| Accuracy | 85–90% | 94.1% | +4.1% to +9.1% |
| AUC Score | 0.85–0.92 | 0.967 | +0.047 to +0.117 |
| Explainability | Limited | 100% Coverage | Full Transparency |
| Federated Learning | Rare | 85.9% FL Accuracy | Privacy-Preserving |
| Response Latency | Varies | < 100ms | Real-time Clinical Use |
- 🔬 Dual Explainability (SHAP + LIME) — Every prediction generates both global and local explanations, giving clinicians feature-level insight into risk factors driving each diagnosis.
- 📊 94.1% Predictive Accuracy — Validated performance exceeding typical clinical decision-support benchmarks, with 0.967 ROC-AUC on held-out test data.
- 🔒 Federated Learning Support — Train across distributed clinical sites without sharing raw patient data — GDPR/HIPAA-aligned by design (85.9% FL accuracy).
- ⚡ Production FastAPI Backend — REST API with sub-100ms inference latency, ready for EHR system integration and clinical workflow embedding.
- 📈 Enterprise MLOps via MLflow — Full experiment tracking, model versioning, artifact logging, and reproducible training pipelines.
- 🖥️ Interactive Gradio Dashboard — A professional, no-code UI for clinicians to input patient data and receive annotated risk assessments in real time.
- ☁️ Cloud-Ready Deployment — One-command deploy to Hugging Face Spaces, Streamlit Cloud, or Render — no DevOps expertise required.
Validation Results — 94.1% Accuracy
Professional Medical AI Dashboard
Click the image above to launch the live demo on Hugging Face Spaces
- Python 3.9+
- pip or conda
# 1. Clone the repository
git clone https://github.com/Ariyan-Pro/ExplainableAI-HeartDisease.git
cd ExplainableAI-HeartDisease
# 2. Install dependencies
pip install -r requirements.txt
# 3. Launch the dashboard
python dashboard/app.pyThe Gradio interface will be available at http://localhost:7860
# Start the REST API
uvicorn healthcare_model.api:app --reload --port 8000API docs auto-generated at http://localhost:8000/docs
from healthcare_model import HeartDiseasePredictor
predictor = HeartDiseasePredictor()
patient = {
"age": 55,
"sex": 1,
"cp": 2, # Chest pain type
"trestbps": 140, # Resting blood pressure
"chol": 250, # Serum cholesterol
"fbs": 0,
"restecg": 1,
"thalach": 150, # Max heart rate achieved
"exang": 0,
"oldpeak": 1.5,
"slope": 2,
"ca": 0,
"thal": 2
}
result = predictor.predict(patient)
print(result["risk_score"]) # → 0.82 (high risk)
print(result["explanation"]) # → SHAP + LIME feature breakdownEnterprise-Grade Four-Layer Architecture
The system is organized into four layers:
| Layer | Components | Role |
|---|---|---|
| Interface | Gradio Dashboard, FastAPI REST | User interaction & external integrations |
| Explainability | SHAP Engine, LIME Engine | Post-hoc explanation generation |
| ML Core | Trained Classifier, Federated Client | Prediction & privacy-preserving training |
| MLOps | MLflow Tracking, Artifact Store | Experiment management & reproducibility |
SHAP Global Feature Importance
This project implements two complementary explanation strategies:
-
SHAP (SHapley Additive exPlanations) — Provides global model interpretability by attributing each feature's contribution to predictions across the entire dataset. Clinicians can identify which biomarkers most consistently drive risk scores.
-
LIME (Local Interpretable Model-Agnostic Explanations) — Generates patient-level, instance-specific explanations by approximating the model locally. Each prediction comes with a ranked list of contributing factors for that individual.
Together, they provide 100% prediction coverage with no unexplained outputs.
This project uses machine learning components. In the interest of clinical trust and EU AI Act alignment:
- Model Type: Supervised classification (gradient-boosted ensemble — inference from codebase)
- Training Data: Cleveland Heart Disease dataset (UCI ML Repository, publicly available)
- External APIs: None — all inference runs locally
- Determinism: Predictions are deterministic given fixed model weights; SHAP/LIME outputs may vary slightly with sampling configurations
- Known Limitations: Trained primarily on the Cleveland dataset; performance may vary on populations significantly different from the training distribution. Not a substitute for clinical diagnosis.
- Federated Learning: Implemented for privacy-preserving multi-site training; FL accuracy is 85.9% vs. 94.1% centralized — this trade-off is expected and disclosed.
- User Data: No patient data is stored, transmitted, or used for retraining in the deployed demo.
Disclosure: Portions of this project's documentation were assisted by AI writing tools.
docker build -t heart-disease-ai .
docker run -p 7860:7860 heart-disease-ai| Variable | Default | Description |
|---|---|---|
MODEL_PATH |
healthcare_model/ |
Path to trained model artifacts |
MLFLOW_TRACKING_URI |
./mlruns |
MLflow experiment tracking directory |
LOG_LEVEL |
INFO |
Logging verbosity (DEBUG, INFO, WARNING) |
PORT |
7860 |
Dashboard server port |
# View experiment results in MLflow UI
mlflow ui --port 5000
# Navigate to http://localhost:5000Contributions are welcome from clinicians, ML engineers, and healthcare AI researchers alike. Please read CONTRIBUTING.md before opening a PR.
git clone https://github.com/Ariyan-Pro/ExplainableAI-HeartDisease.git
cd ExplainableAI-HeartDisease
pip install -r requirements.txt- Fork the repo and create your branch:
git checkout -b feat/your-feature - Make your changes and add tests where applicable
- Verify nothing is broken:
python -m pytest - Open a PR — describe what you changed and why, not just what
- Additional dataset support (MIMIC-III, Framingham)
- New explainability backends (Integrated Gradients, Captum)
- Multilingual dashboard support
- EHR integration connectors (FHIR, HL7)
Please do not open public GitHub issues for security vulnerabilities. Instead, report them privately by emailing the repository maintainer or opening a private security advisory via GitHub's security tab.
MIT © 2024 Ariyan Pro
You are free to use, modify, and distribute this software for any purpose, including commercial clinical research, with attribution.
- UCI ML Repository — Cleveland Heart Disease Dataset
- SHAP — Lundberg & Lee, NeurIPS 2017
- LIME — Ribeiro et al., KDD 2016
- MLflow — Experiment tracking infrastructure
- Gradio — Interactive demo interface
- FastAPI — Production API framework
| Resource | Link |
|---|---|
| 🤗 Live Demo | Hugging Face Spaces |
| 📖 Documentation | ./docs |
| 🐛 Issue Tracker | GitHub Issues |
| 🤝 Contributing Guide | CONTRIBUTING.md |
Built with ❤️ for Clinical AI Transparency
If this project helps your research or clinical work, consider starring ⭐ the repository.