Building a heart disease prediction model
A machine learning pipeline from preprocessing and XGBoost to a FastAPI prediction service.
Training a model is only one part of an applied machine learning project. The input needs to be prepared consistently, the model needs to be evaluated, and a service needs to validate requests before returning predictions. This project brings those pieces together in a heart-disease classification pipeline.
It uses XGBoost for the model, scikit-learn for preprocessing and selection, and FastAPI for inference. The focus is an educational implementation of the full path from tabular data to a usable prediction API.
Preparing mixed clinical features
The project describes 11 clinical and physiological inputs, including age, blood pressure, cholesterol, chest pain type, maximum heart rate and exercise-related measurements. Numerical inputs are scaled with StandardScaler. Categorical values are transformed with OneHotEncoder, and a ColumnTransformer brings both paths together. Keeping the fitted preprocessor with the model helps the API apply the same transformations used during training.
Training and tuning XGBoost
The documented workflow uses an 80/20 train-test split with a fixed random seed. GridSearchCV evaluates hyperparameters with five-fold cross-validation, including learning rate, tree depth, estimator count and sampling settings. The selected configuration uses 200 estimators, a learning rate of 0.05 and a maximum depth of five. Cross-validation supports model selection; the held-out test set serves a different purpose, assessing the selected model on unseen examples.
Beyond the headline accuracy
The repository reports 87.5% test accuracy and a best cross-validation score of 88.15%. It also includes class-level precision, recall and F1 scores. Those measures matter because accuracy alone does not show the balance between missed positive cases and false alarms. These are repository-reported experimental results, not evidence of clinical validation or reliable performance across populations.
Turning the model into a service
The FastAPI layer defines request and response models with Pydantic. It exposes a health check, single predictions and batch predictions. The trained model is stored in XGBoost’s JSON format, while the fitted preprocessor is loaded separately. The health endpoint checks that the service can access the model, and validation catches malformed inputs before inference.
- GET /health checks model loading and service status.
- POST /predict accepts one record and returns a prediction and class probabilities.
- POST /predict/batch handles multiple records.
- Interactive API documentation is provided by FastAPI.
Exploring the implementation
The repository includes a training notebook, the inference service, saved model artefacts and the preprocessor. To study it locally, install the project’s dependencies in a Python environment, inspect the training and preprocessing code, and run the inference service. Only load serialised model files from a source you trust.
python deployment_inference.py
# Once the local service is running:
# http://localhost:8000/docs
# http://localhost:8000/healthWhere this project stops
This is a research and educational project, not a diagnostic tool. A test-set score does not establish clinical safety, calibration or generalisation to another patient population. Future engineering work could include model versioning, monitoring and more detailed interpretability. Any clinical use would require appropriate validation and expert oversight beyond the scope of this repository.