ChurnGuard | Explainable AI for Telecom Retention

ChurnGuard is an end-to-end machine learning application built with Streamlit and XGBoost. It predicts telecom customer churn and, crucially, explains why a customer is at risk using plain-English summaries and interactive SHAP (SHapley Additive exPlanations) visualizations — empowering retention teams to take immediate, data-driven action.

---

Table of Contents

• Features
• Data Source
• Project Structure
• Requirements
• Setup & Installation
  • 1. Clone the repository
  • 2. Create and activate a virtual environment
  • 3. Download the dataset
  • 4. Install dependencies
  • 5. Train and evaluate the model
  • 6. Run the application
• Model Performance
• Quality Assurance
• Platform Notes
• License

---

Features

• Business-Optimized ML — The XGBoost model is tuned via GridSearchCV and class-weight dampening to balance Precision and Recall, drastically reducing False Positives (unnecessary retention discounts) compared to standard high-recall baselines.
• Explainable AI (XAI) — Raw log-odds are translated into an intuitive SHAP waterfall plot, color-coded for business users. Red bars signal flight risk; blue bars signal loyalty anchors.
• Dynamic NLP Translator — A custom logic engine scans SHAP outputs and generates a plain-English Executive Summary (e.g., "Contract: Month-to-month is the strongest force pushing them to leave, but Tech Support acts as a safety net...").
• Defensive UI — Forced-validation gates, programmatic slider snapping, and impossible-state prevention ensure the model never receives conflicting data (e.g., internet-dependent features are zeroed automatically if the customer has no internet service).
• Automated ML Pipeline — A Makefile covers environment setup, model training, performance evaluation, and app deployment in a single workflow.
• Cross-platform — Runs on Windows, macOS, and Linux.

---

Data Source

The model is trained on the Telco Customer Churn dataset. To keep the repository clean, the raw data is not tracked in version control.

Download the dataset from Kaggle and place it in the data/ directory:

🔗 Telco Customer Churn Dataset (Kaggle)

Ensure the file is named exactly ChurnGuard_data.csv.

---

Project Structure

ChurnGuard/
├── app/
│   └── app.py                  # Streamlit frontend & SHAP UI logic
├── data/
│   └── ChurnGuard_data.csv     # Raw dataset (download from Kaggle)
├── models/                     # Auto-generated during training
│   ├── preprocessor.joblib     # Scikit-Learn ColumnTransformer
│   └── xgboost_model.joblib    # Tuned XGBoost classifier
├── reports/                    # Auto-generated during evaluation
│   └── confusion_matrix.png    # Visual TP / FP / TN / FN breakdown
├── src/
│   ├── evaluate.py             # Generates industry-standard ML metrics
│   └── train.py                # GridSearchCV hyperparameter tuning pipeline
├── .gitignore
├── Makefile                    # Automation commands (Linux / macOS)
└── requirements.txt            # Python dependencies

---

Requirements

• Python 3.9+
• pip

Dependencies (installed via requirements.txt):

Package	Version
streamlit	1.55.0
pandas	2.3.3
scikit-learn	1.8.0
xgboost	3.2.0
shap	0.51.0
matplotlib	3.10.8
joblib	1.5.3
seaborn	0.13.2

---

Setup & Installation

1. Clone the repository

git clone https://github.com/Alfin-Abraham/ChurnGuard.git
cd ChurnGuard

2. Create and activate a virtual environment

Windows:

python -m venv venv/ --prompt ChurnGuard
venv\Scripts\Activate.ps1
python.exe -m pip install --upgrade pip

macOS / Linux:

python -m venv venv/ --prompt ChurnGuard
source venv/bin/activate
python -m pip install --upgrade pip

Your terminal prompt will change to (ChurnGuard) confirming the environment is active.

3. Download the dataset

Download the dataset from the Kaggle link above, extract it, and place the file in the data/ directory. Ensure it is named ChurnGuard_data.csv.

4. Install dependencies

Linux / macOS (via Makefile):

make install

Windows (or without Make):

pip install -r requirements.txt

5. Train and evaluate the model

This step generates the .joblib model artifacts and prints performance metrics.

Linux / macOS:

make train
make evaluate

Windows:

python src/train.py
python src/evaluate.py

6. Run the application

Linux / macOS:

make app

Windows:

streamlit run app/app.py

The application will launch automatically in your default browser at http://localhost:8501.

---

Model Performance

The model was evaluated on a 20% holdout test set (1,409 customers) with the following optimized hyperparameters: max_depth: 3, n_estimators: 75, learning_rate: 0.07, subsample: 0.75.

Metric	Score	Note
ROC-AUC	0.8474	Exceeds the industry standard for tabular behavioral data
Accuracy	79.42%	Strong baseline separation
Precision	0.61	Tuned to reduce False Positives and wasted retention spend
Recall	0.60	Balanced against Precision for maximum business ROI

---

Quality Assurance

The application was stress-tested across the full churn probability spectrum to verify the UI, XGBoost engine, SHAP mathematics, and NLP translator work in unison.

Profile	Risk	Scenario Verified
🟢 The Ironclad Lifer	1.4%	Zero Red Bar handling; long-term contracts and bundled services correctly identified as unbreakable loyalty anchors.
🟡 The Safe Crossroads	17.5%	Minor flight risks (e.g., lack of online security) accurately weighed against major safety nets (1-year contract).
🟠 The Danger Zone	76.2%	Asymmetric profiles where financial friction (expensive fiber, manual payment) overwhelms safety nets like Tech Support.
🔴 The Code Red	91.0%	Zero Blue Bar fail-safe; Executive Summary generated for new customers with high-friction payments and no anchors.

---

Platform Notes

Linux / macOS — Fully supported via the included Makefile. Use make install, make train, make evaluate, and make app for end-to-end deployment.

Windows — Native make commands are unavailable by default. Run the equivalent Python commands directly (e.g., python src/train.py). Alternatively, install GNU Make via Chocolatey or use WSL.

---

License

MIT License

Copyright (c) 2026 Alfin-Abraham

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.