🔄 Hybrid Customer Churn Prediction & Retention Intelligence System

A production-ready Final Year CSE project combining Traditional ML, Deep Learning (Bidirectional LSTM), and Hybrid models for customer churn prediction — with SHAP explainability, K-Means segmentation, and an interactive Streamlit dashboard.

---

🎯 Project Highlights

• 6 Models trained and compared — Logistic Regression, Random Forest, XGBoost, Bi-LSTM, Hybrid Weighted, Hybrid Stacking
• Best ROC-AUC: 0.8416 (Logistic Regression) on Telco Customer Churn dataset
• SHAP Explainability — identifies top features driving churn per customer
• K-Means Customer Segmentation — clusters customers into behavioral groups with targeted retention strategies
• ROC Curves + Confusion Matrices + Precision-Recall Curves for all 6 models
• Rule-based Retention Engine — personalized recommendations per customer
• Interactive Streamlit Dashboard — 6 fully functional tabs

---

📊 Model Performance Results

Model	Accuracy	ROC-AUC	Precision	Recall	F1-Score
Logistic Regression	0.8070	0.8416	0.6584	0.5668	0.6092
Random Forest	0.7871	0.8169	0.6203	0.5241	0.5681
XGBoost	0.7736	0.8217	0.5868	0.4973	0.5384
Bidirectional LSTM	0.7878	0.8381	0.6364	0.4679	0.5393
Hybrid Weighted	0.7970	0.8399	0.6538	0.5000	0.5667
Hybrid Stacking	0.7828	0.8105	0.6090	0.5080	0.5539

Dataset: Telco Customer Churn — 7,043 customers, 26.54% churn rate

---

🖥️ Dashboard — 6 Tabs

🏠 Home

Project overview, system architecture table, and model readiness status.

📁 Batch Prediction

• Upload any Telco-format CSV
• Runs all 6 models instantly
• KPI cards: Total / High / Medium / Low risk counts
• Churn probability distribution histogram
• Risk level pie chart
• Expandable retention recommendations per high-risk customer
• Download predictions as CSV

👤 Single Customer

• Manual input form (demographics, services, billing)
• Prediction from all 6 models shown as metrics
• Interactive churn gauge chart (Hybrid Stacking)
• Personalized retention recommendations

📈 Model Comparison

• Full metrics table with green highlights for best scores
• Grouped bar chart (Accuracy, ROC-AUC, F1-Score)
• ROC Curves — all 6 models overlaid on one chart with AUC scores
• Confusion Matrices — all 6 models in a 3-column grid
• Precision-Recall Curves — better for imbalanced churn data

🔍 Explainability (SHAP)

• SHAP Summary Dot Plot — feature impact direction per customer
• SHAP Bar Chart — average feature importance ranking
• Top 10 features table with churn impact direction
• Interactive Plotly bar chart colored by churn direction

Top Churn Drivers found by SHAP:

1. Contract_Month-to-month (0.8402) — strongest churn signal
2. tenure (0.7148) — lower tenure = higher risk
3. MonthlyCharges (0.4244)
4. TotalCharges (0.4041)
5. InternetService_Fiber optic (0.3264)

🗂️ Customer Segmentation

• Elbow Method chart to find optimal K
• PCA 2D Scatter — customers plotted as colored segments
• Cluster Profile Table — avg tenure, charges, churn risk per segment
• Churn Risk Bar Chart per segment
• Radar Chart — normalized feature comparison across segments
• Retention Strategy — specific action plan per segment (High/Medium/Low)
• Download segmented customer list as CSV

📸 Screenshots

---

📁 Project Structure

churn_project/
├── data/
│   └── WA_Fn-UseC_-Telco-Customer-Churn.csv   ← Download from Kaggle
├── models/                                      ← Auto-created after training
│   ├── logistic_regression.pkl
│   ├── random_forest.pkl
│   ├── xgboost.pkl
│   ├── lstm_model.h5
│   ├── meta_model.pkl
│   ├── scaler.pkl
│   ├── feature_names.pkl
│   ├── shap_summary.png
│   └── shap_bar.png
├── scripts/
│   ├── preprocess.py        ← Data cleaning & feature engineering
│   ├── train_ml.py          ← Logistic Regression, Random Forest, XGBoost
│   ├── train_lstm.py        ← Bidirectional LSTM (TensorFlow/Keras)
│   ├── hybrid_model.py      ← Weighted Average + Stacking hybrid
│   ├── explainability.py    ← SHAP TreeExplainer analysis & plots
│   └── recommendation.py   ← Rule-based retention engine
├── app.py                   ← Streamlit dashboard (6 tabs)
├── train_all.py             ← Master script — trains all models in order
├── requirements.txt
└── README.md

---

⚙️ Setup Instructions

Step 1 — Clone the repo

git clone https://github.com/nithinrbharadwaj/Hybrid-Churn-Prediction-System.git
cd Hybrid-Churn-Prediction-System

Step 2 — Create virtual environment (Python 3.12 recommended)

py -3.12 -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # Mac/Linux

Step 3 — Install dependencies

pip install -r requirements.txt

Step 4 — Download the dataset

1. Go to: https://www.kaggle.com/datasets/blastchar/telco-customer-churn
2. Download WA_Fn-UseC_-Telco-Customer-Churn.csv
3. Place it inside the data/ folder

Step 5 — Train all models (one command)

python train_all.py

Training phases:

• ✅ Phase 1: ML Models (Logistic Regression, Random Forest, XGBoost)
• ✅ Phase 2: Bidirectional LSTM Deep Learning model
• ✅ Phase 3: Hybrid models (Weighted Average + Meta-Learner Stacking)
• ✅ Phase 4: SHAP explainability plots

Step 6 — Launch the dashboard

streamlit run app.py

Open: http://localhost:8501

---

🧠 Tech Stack

Category	Libraries
Data Processing	Python 3.12, Pandas, NumPy
Machine Learning	Scikit-learn, XGBoost
Deep Learning	TensorFlow 2.17, Keras (Bidirectional LSTM)
Explainability	SHAP (TreeExplainer)
Clustering	Scikit-learn KMeans, PCA
Dashboard	Streamlit, Plotly
Visualization	Matplotlib, Seaborn, Plotly

---

🏗️ System Architecture

Raw CSV Data
     │
     ▼
Preprocessing (Label Encoding, One-Hot, StandardScaler)
     │
     ├──► Traditional ML ──► LR / RF / XGBoost
     │
     ├──► Deep Learning  ──► Bidirectional LSTM
     │
     ├──► Hybrid         ──► Weighted Avg / Stacking
     │
     ├──► Explainability ──► SHAP TreeExplainer
     │
     ├──► Segmentation   ──► K-Means + PCA
     │
     └──► Dashboard      ──► Streamlit (6 tabs)

---

📌 Notes

• All trained models are saved to models/ automatically
• The data/ folder must contain the Kaggle CSV before running train_all.py
• SHAP PNG plots are saved to models/ and displayed in the Explainability tab
• The retention engine is rule-based — no extra training needed
• For segmentation, upload the same CSV in the Segmentation tab

---

🚀 Future Improvements

• SMOTE for class imbalance handling
• Hyperparameter tuning with Optuna
• FastAPI real-time prediction endpoint
• What-If simulator (change features, see new risk score)
• PDF report generator
• Docker containerization
• Streamlit Cloud deployment
• Survival Analysis (predict when customer will churn)

---

👨‍💻 Author

Nithin R Bharadwaj Final Year CSE — Hybrid Churn Prediction System