How vishnutpillai/telecom_churn_prediction works
Purpose and Runtime
This repository is a telecom customer churn prediction project. It trains/evaluates ML classifiers offline and exposes real-time churn predictions through a Streamlit application. Primary runtime entry point: app.py; training and analysis are represented by Telecom_churn_prediction.ipynb.
Offline Data and ML Workflow
The source dataset is telecom_churn.csv, containing customer account, service, billing, support, and churn-label data. The notebook Telecom_churn_prediction.ipynb is the authoritative offline workflow for cleaning, exploratory analysis, feature engineering, scaling, class-imbalance handling with SMOTE, model selection, and evaluation.
Model Selection and Training Boundary
Training compares Logistic Regression, Random Forest, and XGBoost models, with GridSearchCV used for hyperparameter selection. SMOTE and scaling are part of the intended ML pipeline, separating training-time preprocessing from raw source-data handling. The notebook produces deployable serialized artifacts rather than retraining during application requests: Telecom_churn_prediction.ipynb, Best_model.pkl.
Serialized Inference Contract
Best_model.pkl stores the selected trained model/pipeline used by the serving layer. Column_order.pkl defines the feature-column ordering expected by that model. Together they form the key inference contract: UI-entered customer attributes must be transformed into the exact trained feature schema and order before prediction.
Streamlit Serving Layer
app.py is the interactive deployment boundary. It collects customer inputs, applies the application-side input preparation needed to satisfy the artifact contract, loads Best_model.pkl and Column_order.pkl, and returns churn classification and probability-oriented output to the user. It is a synchronous local Streamlit service, not a separate API backend.
Control and Data Flow
1. Offline workflow reads telecom_churn.csv in Telecom_churn_prediction.ipynb.
2. Data is cleaned, encoded/engineered, scaled, and balanced; candidate models are tuned and evaluated.
3. The chosen model and expected feature ordering are persisted as Best_model.pkl and Column_order.pkl.
4. app.py accepts real-time customer values, aligns them to Column_order.pkl, invokes the loaded model, and presents churn risk.
Dependencies and External Surface
Python is the implementation runtime. Core libraries include pandas/NumPy, scikit-learn, imbalanced-learn, XGBoost, joblib, and Streamlit, declared in requirements.txt. The deployment target is Streamlit, including the linked hosted Streamlit demo; no database, message broker, or external prediction service is represented in the repository.
Main entry points: Telecom_churn_prediction.ipynb Feature preparation · Best_model.pkl Selected model · app.py Streamlit app · requirements.txt Python dependencies
Components 12
Offline ML workflow
- Telecom churn data · Customer attributes and churn labels.
telecom_churn.csv - Training notebook · Authoritative training, analysis, and evaluation workflow.
Telecom_churn_prediction.ipynb - Feature preparation · Cleans, encodes, and scales source features.
Telecom_churn_prediction.ipynb - Class balancing · Balances churn classes during training.
Telecom_churn_prediction.ipynb - Model selection · Compares Logistic Regression, Random Forest, and XGBoost.
Telecom_churn_prediction.ipynb
Inference artifacts
- Selected model · Deployable trained inference model.
Best_model.pkl - Feature schema · Required model input feature ordering.
Column_order.pkl
Streamlit serving
- Streamlit app · Synchronous local real-time prediction service.
app.py - Input alignment · Transforms UI values into the trained feature schema.
app.py - Churn risk result
app.py - Customer input
app.py
Other components
- Python dependencies · Includes Streamlit, pandas, scikit-learn, imbalanced-learn, XGBoost, and joblib.
requirements.txt
Connections 14
- Telecom churn data → Training notebook: read by
- Training notebook → Feature preparation: prepares data
- Feature preparation → Class balancing: training features
- Class balancing → Model selection: balanced training data
- Model selection → Selected model: persists winner
- Feature preparation → Feature schema: defines feature order
- Customer input → Streamlit app: enters customer values
- Streamlit app → Input alignment: prepares request
- Feature schema → Input alignment: aligns columns
- Input alignment → Selected model: model-ready features
- Selected model → Churn risk result: classification and probability
- Churn risk result → Customer input: presents churn risk
- Python dependencies → Training notebook: offline libraries
- Python dependencies → Streamlit app: serving libraries