Customer Churn Predictor
Predicts which customers are likely to cancel, using behavioral and account
data. Built for SaaS, subscription, telecom, and retail businesses with
recurring customers.
This is the free version. It gives you a single-customer churn
probability and a risk band (low / medium / high) — useful for evaluating
model quality before you commit to anything.
Why this matters
Losing a customer costs more than most teams think — replacing one is far
more expensive than retaining one. A model that flags at-risk customers
before they cancel lets you act while there's still time, instead of
finding out from a cancellation email.
What's in the free version
- Trained XGBoost model (
xgb_churn_model.pkl)
- Single-customer prediction script (
predict.py)
- Output:
churn_probability (0–1) + risk_band (low/medium/high)
- Runs entirely on your machine — no API calls, no data leaves your environment
What's NOT in the free version
- Batch CSV scoring — score your whole customer base at once
- SHAP explainability — why each customer is flagged (the actual
reason this model is useful to a business, not just a score)
- Docker + FastAPI wrapper — production-ready service you can drop into
your stack
- Schema customization guide — adapt the model to your own data columns
- Retraining support — fit the model to your specific customer base
→
Get the full version on Gumroad —
SHAP explainability, batch scoring, Docker package, and docs included.
Quick start
1pip install -r requirements.txt
2python predict.py
Edit the customer dict in predict.py with your own customer's data, or
import predict_churn() into your own script:
1from predict import predict_churn
2
3result = predict_churn({
4 "gender": "Female",
5 "SeniorCitizen": 0,
6 "Partner": "Yes",
7 "Dependents": "No",
8 "tenure": 2,
9 "PhoneService": "Yes",
10 "MultipleLines": "No",
11 "InternetService": "Fiber optic",
12 "OnlineSecurity": "No",
13 "OnlineBackup": "No",
14 "DeviceProtection": "No",
15 "TechSupport": "No",
16 "StreamingTV": "No",
17 "StreamingMovies": "No",
18 "Contract": "Month-to-month",
19 "PaperlessBilling": "Yes",
20 "PaymentMethod": "Electronic check",
21 "MonthlyCharges": 85.5,
22 "TotalCharges": 171.0,
23})
24# {'churn_probability': 0.8845, 'risk_band': 'high'}
See schema.json for the full list of accepted fields and their valid
values.
Performance
Trained and evaluated on the IBM Telco Customer Churn dataset (7,043
customers). Evaluated on imbalanced-aware metrics, not raw accuracy, since
churners are the minority class.
| Metric | Score |
|---|
| ROC-AUC | 0.841 |
| PR-AUC | 0.658 |
| Recall (churners caught) | 78% |
| Precision (at default threshold) | 52% |
Model details
- Algorithm: XGBoost (gradient boosted trees)
- Imbalance handling:
scale_pos_weight tuned to class ratio
- Input: per-customer tenure, contract type, billing info, service
usage (see
schema.json)
- Output: churn probability + risk band
License
MIT. Free for personal and commercial use. For batch scoring, explainable
output, and a production-ready package, see the paid version linked above.
