a-dera/nps-prediction-engine

Customer NPS Prediction for a Pan-African Telecom Operator # NPS Prediction Engine **Customer NPS Prediction for a Pan-African Telecom Operator** This repository implements an end-to-end machine learning system that predicts customer Net Promoter Score (NPS) categories -- Detractor, Passive, Promoter -- from the IBM Telco Customer Churn dataset. The system feeds a retention workflow that prioritises detractors for proactive outreach and explains the main drivers of customer detraction. - **Author**: Amédée DERA - **Challenge**: Artefact Cote d'Ivoire -- Senior Data Scientist, May 2026 - **Python**: 3.11+ (tested on 3.13.1) - **Final model**: XGBoost + isotonic calibration, threshold t\* = 0.625, macro-F1 = 0.439 (val) at 39.9% alert rate --- ## What you'll find here This is a complete end-to-end machine learning system, not a notebook prototype. The deliverable includes: - **A production-ready model** - calibrated XGBoost with a business-tuned decision threshold (t* = 0.625). Recall 50.3% of true Detractors while alerting on only 39.9% of the customer base. - **A reproducible pipeline** - 8 numbered notebooks runnable end-to-end from raw data to predictions, plus a Streamlit retention manager UI. - **A 6-page write-up** for a Customer Experience Director (`reports/final_writeup.md`). - **An append-only decision log** documenting every non-trivial choice (`reports/decisions.md`). - **79 unit tests passing** covering label construction, feature engineering, split strategy, and pipeline integrity. - **Demo of the Streamlit app** ### Headline metrics (test split) | Metric | Value | |---|---| | Macro-F1 | 0.434 | | Quadratic Weighted Kappa | 0.252 | | Detractor recall (at business threshold) | 50.3% | | Detractor precision (at business threshold) | 76.2% | | Alert rate (at business threshold) | 39.9% | ### Reading order for evaluators 1. `reports/final_writeup.md` - 6-page business-oriented report 2. `reports/decisions.md` - append-only decision log 3. `notebooks/01_eda.ipynb` to `08_drivers_analysis.ipynb` - full pip …