customer-churn-predictor

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

pip install -r requirements.txt
python predict.py

Edit the customer dict in predict.py with your own customer's data, or import predict_churn() into your own script:

from predict import predict_churn

result = predict_churn({
    "gender": "Female",
    "SeniorCitizen": 0,
    "Partner": "Yes",
    "Dependents": "No",
    "tenure": 2,
    "PhoneService": "Yes",
    "MultipleLines": "No",
    "InternetService": "Fiber optic",
    "OnlineSecurity": "No",
    "OnlineBackup": "No",
    "DeviceProtection": "No",
    "TechSupport": "No",
    "StreamingTV": "No",
    "StreamingMovies": "No",
    "Contract": "Month-to-month",
    "PaperlessBilling": "Yes",
    "PaymentMethod": "Electronic check",
    "MonthlyCharges": 85.5,
    "TotalCharges": 171.0,
})
# {'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.

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.