Add README.md with Hugging Face Spaces configuration

README.md

@@ -1,38 +1,74 @@
-# Streamlit Inference App
+---
+title: Heart Attack Risk Prediction
+emoji: ❤️
+colorFrom: red
+colorTo: pink
+sdk: docker
+sdk_version: "4.44.0"
+app_file: streamlit_app.py
+pinned: false
+---
 
-This app loads your trained models (CatBoost/XGBoost/LightGBM) and optional sklearn preprocessor, then serves batch CSV inference with an optional simple ensemble. No dataset is required at deploy time; users upload CSVs.
+# ❤️ Heart Attack Risk Prediction: An Ensemble Modeling Approach
 
-## Project Layout
+Advanced machine learning ensemble combining XGBoost, CatBoost, and LightGBM for accurate cardiovascular risk assessment.
 
-- `streamlit_app.py` – main app
-- `requirements.txt` – dependencies (installed on Streamlit Cloud)
-- `.streamlit/config.toml` – dark theme
-- `model_assets/` – place your artifacts here:
-  - `CatBoost.joblib` / `XGBoost.joblib` / `LightGBM.joblib` (or any of the alternative names used in the notebook)
-  - `preprocessor.joblib` (recommended)
-  - optional: `feature_names.json`, `hybrid_metrics.csv`, `model_metrics_summary.csv`
+## 🎯 Features
 
-## Local Preview (optional)
+- **Ensemble Model**: Combines XGBoost (5%), CatBoost (85%), and LightGBM (10%) for optimal performance
+- **High Accuracy**: ~80.77% accuracy with ~93.27% recall
+- **Comprehensive Risk Assessment**: Analyzes multiple health factors including:
+  - Demographics (Age, Gender, Height, Weight)
+  - Blood Pressure and Cholesterol levels
+  - Lifestyle factors (Smoking, Alcohol, Physical Activity)
+  - Derived health metrics (BMI, BP categories)
 
-If you want to run locally without installing ML libs on your laptop, skip. Otherwise:
+## 📊 Model Performance
 
-```bash
-pip install -r requirements.txt
-streamlit run streamlit_app.py
+- **Accuracy**: 80.77%
+- **Recall**: 93.27%
+- **ROC-AUC**: 92.50%
+
+## 🚀 Usage
+
+1. Enter your health information in the input form
+2. Click "Predict Heart Attack Risk"
+3. View your personalized risk assessment with:
+   - Overall risk percentage
+   - Individual model predictions
+   - Key risk factors identified
+   - Detailed model breakdown
+
+## 🔬 Technical Details
+
+### Models Used
+- **XGBoost**: Gradient boosting with optimized hyperparameters
+- **CatBoost**: Categorical boosting with balanced class weights
+- **LightGBM**: Light gradient boosting machine
+- **Ensemble**: Weighted combination of all three models
+
+### Optimization
+- Multi-objective optimization for accuracy and recall
+- Threshold optimization for optimal performance
+- Feature engineering with derived health metrics
+
+## 📝 Citation
+
+If you use this model in your research, please cite:
+
+```
+Heart Attack Risk Prediction: An Ensemble Modeling Approach
+Using XGBoost, CatBoost, and LightGBM
 ```
 
-## Deploy to Streamlit Cloud
+## ⚠️ Disclaimer
 
-1. Push this folder to a public GitHub repo.
-2. On Streamlit Cloud, create a new app pointing to that repo, file `streamlit_app.py`.
-3. In the repo, put your artifacts inside `model_assets/`.
+This tool is for educational and research purposes only. It is not a substitute for professional medical advice, diagnosis, or treatment. Always seek the advice of your physician or other qualified health provider with any questions you may have regarding a medical condition.
 
-## Preparing Artifacts in Colab
+## 📧 Contact
 
-Artifacts the app can use (any subset works):
-- Models: `CatBoost.joblib`, `XGBoost.joblib`, `LightGBM.joblib` (supports common alt names)
-- Preprocessor: `preprocessor.joblib`
-- Optional: `feature_names.json`, `hybrid_metrics.csv`, `model_metrics_summary.csv`
+For questions or issues, please open an issue on the repository.
 
-The app auto-detects assets and displays metrics if the CSVs are present.
+---
 
+**Built with ❤️ using Streamlit, XGBoost, CatBoost, and LightGBM**