Download README.md from stargazer791/Customer-Retention-Engine: direct link, hf CLI and curl.
- Browser
- Download file 6.09 kB
-
https://huggingface.co/spaces/stargazer791/Customer-Retention-Engine/resolve/main/README.md
- Command line
-
hf download hf://spaces/stargazer791/Customer-Retention-Engine/README.md
-
curl -L -o README.md https://huggingface.co/spaces/stargazer791/Customer-Retention-Engine/resolve/main/README.md
title: Customer Retention Engine
emoji: 📈
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
Customer Retention Engine: Telecom Churn Prediction
This project builds a telecom churn prediction pipeline to identify customers at high risk of leaving, using demographic, service, contract, and billing data to support retention targeting.
It compares Logistic Regression and XGBoost, applies class-imbalance handling, tunes the classification threshold with 5-Fold Stratified Cross-Validation, and saves a final model that can be used to score unseen customers.
The project includes a FastAPI prediction API and an interactive browser-based interface for scoring individual customers, deployed with Docker and CI/CD.
It also contains deep EDA with insights:
Problem
Customer churn is expensive because every preventable cancellation represents lost recurring revenue and higher reacquisition cost. The objective here is to identify likely churners early enough for a retention team to intervene.
Dataset
train.csv: 594,194 labeled customerstest.csv: 254,655 unlabeled customers- Features: demographics, service configuration, contract type, billing behavior, and charges
- Target:
Churn(Yes/No)
The notebooks in this repository contain the original EDA and first-pass modeling work:
EDA_SeniorCitizens.ipynbEDA_High_payers_analysis.ipynbchurn_pred_log_reg.ipynbchurn_pred_xgboost.ipynb
Project Structure
The repository includes:
train.py: trains baseline models, tunes thresholds with cross-validation, evaluates on a holdout set, and saves artifactspredict.py: loads the best saved model and scorestest.csvsrc/churn_predictor/: reusable data loading and modeling utilitiesreports/: generated model comparison tables and summariesmodels/: serialized model artifacts
The notebooks are kept as the original exploratory and baseline modeling work, while the Python scripts provide a cleaner and reproducible training flow.
Relevant docs:
- scikit-learn threshold tuning: https://scikit-learn.org/stable/modules/classification_threshold.html
- scikit-learn
TunedThresholdClassifierCV: https://scikit-learn.org/dev/modules/generated/sklearn.model_selection.TunedThresholdClassifierCV.html - XGBoost parameters: https://xgboost.readthedocs.io/en/latest/parameter.html
Modeling Approach
Two supervised baselines are trained and compared:
- Logistic regression with class balancing
- XGBoost with imbalance-aware
scale_pos_weight
Shared preprocessing:
- Convert
TotalChargesto numeric safely - Convert
SeniorCitizento categorical labels for one-hot encoding - Median imputation for numeric features
- Most-frequent imputation for categorical features
- Standard scaling for numeric features
- One-hot encoding for categorical features
Evaluation design:
- Split labeled data into development and holdout sets using stratified sampling
- Train each model on the development set
- Tune the probability threshold with internal cross-validation (5-Fold) on the development set
- Report final holdout metrics: F1, precision, recall, accuracy, ROC-AUC, and PR-AUC
- Retrain the winning model on all labeled rows
- Save the final full-data model artifact
Results
On the 118,839-row holdout set, XGBoost performed better than logistic regression across every reported metric and was selected as the final model.
- XGBoost: F1
0.701, precision0.631, recall0.789, accuracy0.849, ROC-AUC0.916, PR-AUC0.752 - Logistic regression: F1
0.689, precision0.617, recall0.781, accuracy0.841, ROC-AUC0.908, PR-AUC0.726
The final saved model in models/best_model.joblib is the XGBoost pipeline retrained on all 594,194 labeled rows after model selection.
| Model | Best Threshold | F1 | Precision | Recall | Accuracy | ROC-AUC | PR-AUC |
|---|---|---|---|---|---|---|---|
| XGBoost | 0.654 | 0.701 | 0.631 | 0.789 | 0.849 | 0.916 | 0.752 |
| Logistic Regression | 0.672 | 0.689 | 0.617 | 0.781 | 0.841 | 0.908 | 0.726 |
What This Project Demonstrates
This project is designed to show:
- structured feature preprocessing with
PipelineandColumnTransformer - appropriate handling of class imbalance for churn prediction
- correct separation of training, threshold tuning, and final evaluation
- model comparison instead of single-model reporting
- retraining the selected model on all labeled rows after evaluation
- reproducible code beyond notebooks
- business-oriented framing for retention use cases
How To Run
Create an environment and install dependencies:
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
Train models and generate reports:
PYTHONPATH=src python3 train.py
Quick smoke test on a smaller sample:
PYTHONPATH=src python3 train.py --sample-rows 10000
Score the unlabeled test set:
PYTHONPATH=src python3 predict.py
Run the local API and web app:
PYTHONPATH=src uvicorn app:app --reload
Then open http://127.0.0.1:8000 in your browser. The page sends customer inputs to POST /predict and displays churn probability and the predicted label.
Outputs
After training, the project writes local artifacts to:
models/best_model.joblibmodels/logistic_regression.joblibmodels/xgboost.joblibreports/model_comparison.csvreports/metrics.jsonreports/summary.mdreports/*_feature_importance.csv
The local deployment layer includes:
app.py: FastAPI app for health checks and predictionweb/index.html: simple browser UI for scoring one customer at a time
Future Work
- Add probability calibration analysis for decision support (right now we use best f1)