Telco Customer Churn Prediction System

Project Overview

This project implements a production-oriented customer churn prediction system for Telco customer data. The business goal is to identify customers who are likely to churn so retention teams can prioritize outreach before revenue is lost.

The project goes beyond a notebook-only machine learning experiment by separating the workflow into reusable Python modules, YAML-based configuration, pipeline entry points, persisted preprocessing and model artifacts, centralized logging, MLflow experiment tracking, and an inference-ready preprocessing path. This structure supports repeatable data processing, traceable training runs, saved artifacts, and future integration into a serving layer.

Key Engineering Highlights

• Modular data ingestion: DataIngestorCSV and DataIngestorExcel provide reusable ingestion classes, keeping file loading separate from transformation logic.
• Configuration-driven execution: config/config.yaml controls data paths, target columns, missing-value rules, feature binning, encoding, scaling, split settings, model parameters, and MLflow settings. This makes pipeline behavior easier to reproduce and change without editing core code.
• Missing-value handling strategies: The pipeline uses drop and fill strategies for configured columns, including median, mode, and constant fills. This matters because production datasets often contain incomplete or inconsistent values.
• Outlier processing: IQROutlierDetection detects numeric outliers in tenure, MonthlyCharges, and TotalCharges, and the pipeline removes rows with multiple outlier flags. This reduces the influence of extreme records during model training.
• Feature binning: CustomBinningStrategy groups tenure into lifecycle buckets such as new, established, and loyal customers. This converts raw tenure into a more interpretable customer maturity signal.
• Categorical encoding: Nominal features are one-hot encoded with unknown-category handling, while ordinal features such as Contract and Churn use explicit mapping rules. This keeps categorical preprocessing consistent between training and inference.
• Feature scaling with persisted artifacts: MinMaxScalingStrategy scales MonthlyCharges and TotalCharges and saves artifacts/scale/minmax_scaler.joblib plus scaling_metadata.json. Persisting the scaler is important because inference must apply the same transformation learned during training.
• Train-test splitting: The data pipeline saves X_train, X_test, Y_train, and Y_test under artifacts/data/, using a configured 80/20 split with random_state=42.
• Reusable strategy-based design: Ingestion, missing-value handling, outlier detection, binning, encoding, scaling, splitting, model building, training, evaluation, and inference are separated into classes and functions. This makes the code easier to test, extend, and debug.
• Centralized logging: config/logging.yaml configures console logging plus rotating application and error logs under logs/. This supports traceability during pipeline runs.
• MLflow experiment tracking: The data, training, and streaming inference pipelines create MLflow runs, log metrics, parameters, tags, datasets, models, and artifacts to a local SQLite-backed MLflow store.
• Model and dataset artifact logging: Processed CSV datasets, visualization artifacts, model metadata, training summaries, trained model files, and inference batches are logged locally for auditability.
• Inference readiness: src/inference/inference.py loads the trained model, applies the same configured feature transformations, aligns inference input to the model's expected feature order, and returns churn status with confidence.

Machine Learning Workflow

Raw Telco CSV data
-> Basic pipeline validation
-> Missing-value handling
-> IQR-based outlier processing
-> Tenure feature binning
-> Nominal and ordinal categorical encoding
-> MinMax scaling
-> Train-test split
-> Processed dataset artifact storage
-> XGBoost model training
-> Model evaluation
-> MLflow experiment tracking
-> Model, scaler, metadata, and visualization artifact storage
-> Streaming inference readiness

System Architecture

The architecture below shows the end-to-end flow from raw Telco customer data through preprocessing, model training, MLflow tracking, artifact persistence, and streaming inference readiness.

The data pipeline prepares reusable training and test datasets. The training pipeline consumes those artifacts, trains an XGBoost classifier, evaluates it, and logs results to MLflow. The inference module reuses the saved model, scaler, and configuration to preprocess new Telco customer records consistently with training.

Models and Evaluation

The reusable source code implements model builders for:

Model	Where Used
Random Forest	Implemented in src/model/model_building.py
XGBoost	Implemented and used by pipelines/training_pipeline.py

The exploratory notebook also experiments with Logistic Regression, Decision Tree, RandomForest, XGBoost, CatBoost, SMOTE, and GridSearchCV. The packaged training pipeline currently trains and saves an XGBoost model.

Latest saved XGBoost training summary:

Metric	Value
Training samples	5,634
Test samples	1,409
Features used	44
Accuracy	0.7871
Precision	0.6174
Recall	0.5147
F1-score	0.5614
ROC-AUC	0.8200
Training time	2.12 seconds

Accuracy is useful as a broad signal, but churn prediction often benefits from recall, F1-score, and ROC-AUC because churners are usually the more important class to detect. Recall shows how many actual churners the model catches, F1-score balances precision and recall, and ROC-AUC evaluates ranking quality across probability thresholds.

MLOps and Reproducibility

The project supports repeatable experiments through:

• MLflow runs for data processing, model training, and streaming inference.
• Parameter logging for model configuration, feature names, preprocessing steps, and run tags.
• Metric logging for dataset shapes, class counts, training metrics, ROC-AUC, inference latency, and prediction distributions.
• Dataset tracking through MLflow dataset inputs for raw and processed data.
• Model artifact logging through MLflow plus a local joblib model saved at artifacts/models/churn_analysis.joblib.
• Visualization artifacts including confusion matrix, ROC curve, feature importance, prediction distribution, and data visualizations.
• Preprocessing artifact persistence through saved MinMax scaler and scaler metadata.
• Configuration-based execution through config/config.yaml.
• Run-specific artifact directories under artifacts/mlflow_run_artifacts/ and artifacts/mlflow_training_artifacts/.
• Reproducible random states configured as 42 for splitting and model parameters.

Docker, CI/CD, Terraform, cloud artifact storage, scheduled retraining, and an API serving layer are not currently implemented in the repository.

Project Structure

.
|-- artifacts/
|   |-- data/
|   |-- inference_batches/
|   |-- mlflow_run_artifacts/
|   |-- mlflow_training_artifacts/
|   |-- models/
|   `-- scale/
|-- config/
|   |-- config.yaml
|   `-- logging.yaml
|-- data/
|   `-- raw/
|       `-- telcodata.csv
|-- experiments/
|   |-- eda.ipynb
|   `-- model_pipeline.ipynb
|-- infrastructure/
|-- logs/
|-- pipelines/
|   |-- data_pipeline.py
|   |-- streaming_inference_pipeline.py
|   `-- training_pipeline.py
|-- readmeassets/
|   |-- confusion_matrix_XGboost.png
|   |-- data_pipeline_1.png
|   |-- data_pieline_with_dataset_metadata.png
|   |-- feature_importance_XGboost.png
|   |-- mlflow_runs.png
|   |-- model_artifacts.png
|   |-- roc_curve_XGboost.png
|   |-- systemarchitecture.png
|   `-- training_pipeline_artifacts.png
|-- src/
|   |-- features/
|   |-- inference/
|   |-- logger/
|   `-- model/
|-- utils/
|-- mlflow.db
|-- pyproject.toml
`-- requirements.txt

• src/: Core reusable source code for feature processing, model building, training, evaluation, inference, and logging.
• config/: YAML configuration for pipeline behavior and logging.
• utils/: Config loading helpers and MLflow tracking utilities.
• pipelines/: Executable data, training, and streaming inference workflows.
• artifacts/: Generated datasets, models, scaler artifacts, MLflow run artifacts, and inference batches.
• experiments/: EDA and model experimentation notebooks.
• readmeassets/: README-ready screenshots showing MLflow runs, artifacts, datasets, and model tracking.
• infrastructure/: Present as a directory, but no infrastructure files are currently implemented.
• logs/: Runtime application and error logs.
• tests/: No test directory is currently present.

Skills Demonstrated

• Python software development with modular packages.
• Object-oriented design using reusable strategy classes.
• Configuration management with YAML.
• Data ingestion and preprocessing pipeline development.
• Missing-value handling and outlier processing.
• Feature engineering through binning, encoding, and scaling.
• Supervised machine learning with XGBoost and RandomForest implementation support.
• Exploratory model comparison and hyperparameter tuning in notebooks.
• Model evaluation using accuracy, precision, recall, F1-score, ROC-AUC, and confusion matrix.
• MLflow experiment tracking, model logging, dataset tracking, and artifact management.
• Logging and error handling for pipeline observability.
• Reproducible train-test splitting and model configuration.
• Inference-oriented preprocessing with saved scaler artifacts and expected feature alignment.
• Git-friendly project organization with generated outputs excluded in .gitignore.

Visual Results

MLflow Run Tracking

The MLflow run list shows data pipeline, training pipeline, and streaming inference runs tracked under the Telco Customer Churn Prediction experiment.

Data Pipeline Metadata

The data pipeline logs processed train/test datasets, dataset metadata, feature names, row counts, and artifact outputs.

Training Artifacts

The training run stores model metadata, confusion matrix, feature importance, prediction distribution, ROC curve, trained model file, and training summary.

Confusion Matrix

The confusion matrix shows how the XGBoost model separates retained customers from churned customers on the held-out test set. It makes the tradeoff between missed churners and false churn alerts visible.

ROC Curve

The ROC curve summarizes how well the model ranks churn risk across classification thresholds. The logged XGBoost run reports ROC-AUC of 0.8200.

Feature Importance

The feature importance chart shows the strongest model signals. In the saved XGBoost run, InternetService_Fiber optic and contract_encoded are the most influential features.

Model Artifact Tracking

The MLflow model view shows logged model entries and the registered churn_prediction model version created by the training pipeline.

How to Run the Project

Recommended Python version: Python 3.11.

python -m venv .venv

Activate the environment:

# Windows PowerShell
.\.venv\Scripts\Activate.ps1

# macOS/Linux
source .venv/bin/activate

Install dependencies:

python -m pip install -r requirements.txt
python -m pip install -e .

Place the raw dataset at:

data/raw/telcodata.csv

Review or update pipeline settings in:

config/config.yaml

Run the data pipeline:

python -m pipelines.data_pipeline

Or, after installing the package in editable mode:

data-pipeline

Run the training pipeline:

python -m pipelines.training_pipeline

Run a sample streaming inference request:

python -m pipelines.streaming_inference_pipeline

Start the local MLflow UI:

mlflow ui --backend-store-uri sqlite:///mlflow.db

Then open the MLflow UI in the browser, usually at:

http://127.0.0.1:5000

Future Improvements

• Add schema validation for raw and inference input data.
• Add automated unit and integration tests.
• Add CI/CD checks for formatting, tests, and pipeline execution.
• Add a model serving API with FastAPI.
• Add Docker packaging for reproducible runtime environments.
• Add cloud artifact storage for models, datasets, and MLflow artifacts.
• Add infrastructure as code if cloud deployment is introduced.
• Add scheduled retraining workflows.
• Add data drift and model performance monitoring.
• Add a feature store or stricter training/inference feature contract.
• Extend the production pipeline to support configurable model comparison and hyperparameter tuning.