project_explanation.md

ChurnShield Project & Model Explanation

Overview of Models Used

The ChurnShield application primarily relies on Ensemble Tree-Based Classifiers to predict customer churn. Specifically, two main algorithms have presence in the repository:

1. XGBoost (eXtreme Gradient Boosting) - Primary
   • Artifact: models/xgboost_churn.json
   • Usage: This is the winning model for high-performance and accurate predictions. XGBoost natively exports its entire tree structure, leaf weights, and configuration into a lightweight JSON file. The backend loads this directly using XGBoost's Booster without the need for traditional Python pickle objects.
2. Random Forest Classifier - Legacy / Fallback
   • Artifact: model/churn_model.pkl (generated by model/train_model.py)
   • Usage: Used as a baseline or fallback ensemble model. The Random Forest builds trees in parallel rather than sequentially and relies on Python's joblib and pickle for serialization. churn_encoder.pkl contains its corresponding data transformation rules.

---

1. XGBoost: Formula and Logic

Where the logic lies

In this repository, the XGBoost logic is separated into two domains:

1. Training (Offline): Handled in the src/ directory (like src/train.py and src/anchor_calibrate.py). This is where the model learns from the data, establishes the optimal splits, and saves its state as serialized artifacts.
2. Inference (Online): Handled in backend/predictor.py. Here, the saved model acts as a decision engine. The backend scripts don't train the model; they simply load the XGBoost trees (xgboost_churn.json) and pass formatted input vectors through them to get the probability of churn via .predict_proba(X).

The Formula

XGBoost is an ensemble learning method built on decision trees. Its prediction formula is additive:

$$ \hat{y}_i = \sum_{k=1}^K f_k(x_i) $$

Where:

• $\hat{y}_i$ is the predicted probability for the $i$-th customer.
• $K$ is the total number of trees.
• $f_k$ represents an independent classification tree.
• $x_i$ is the feature vector of the customer.

XGBoost optimizes the following objective function during training:

$$ \text{Obj} = \sum_{i=1}^n l(y_i, \hat{y}_i) + \sum_{k=1}^K \Omega(f_k) $$

• $l(y_i, \hat{y}_i)$ is a differentiable loss function (e.g., Log Loss for binary classification) measuring the difference between the true churn label $y_i$ and the predicted label.
• $\Omega(f_k) = \gamma T + \frac{1}{2}\lambda||w||^2$ is the regularization term to penalize complexity (preventing overfitting), where $T$ is the number of leaves in the tree and $w$ represents the leaf weights.

---

2. Training and Calibration Files Used

• model/train_model.py: The legacy or baseline ML training pipeline script. It reads the raw dataset, imputes missing values strictly based on training data to prevent leakage, fits a Random Forest, and outputs churn_model.pkl and churn_encoder.pkl.

• models/xgboost_churn.json: The serialized state of the primary XGBoost model. By holding the configuration and forest structure in JSON, the backend can instantly reconstitute the model via xgboost.Booster() without executing retraining workloads.

• models/anchor_calibration.json: A "Residual Correction" rulebook. When building models for strict business logic, you sometimes want specific personas (e.g., highly engaged users vs. clearly risky users) to land in predetermined probability bands. This file holds the raw probabilities vs. target probabilities to intelligently skew or "nudge" edge cases.

• src/anchor_calibrate.py: The script responsible for generating the anchor_calibration.json configuration by calculating the necessary adjustments (deltas) on standard validation profiles.

---

3. Backend Implementation Files

File: backend/predictor.py

Purpose: This is the Machine Learning inference engine for the backend. It sits between the API and the model outputs. Key Responsibilities:

• Data Preprocessing (_encode_input): Prevents data leakage by strictly applying training-set rules stored in churn_encoder.pkl (e.g., median filling or clipping outliers). Maps missing or unseen categorical values safely and ensures column order strictly aligns with what the model expects.
• Single / Bulk Prediction: Ingests Python dictionaries or an entire Pandas DataFrame (e.g. from an uploaded CSV). Efficiently vectorizes data imputations and routes inputs through the model, returning an attached Churn_Probability, a Risk_Level (High/Medium/Low based on 30% and 60% thresholds), and a Suggested_Action.

File: backend/analytics.py

Purpose: This file acts as an aggregation and OLAP (Online Analytical Processing) layer. It calculates Key Performance Indicators (KPIs) and groups data for the Live Analytics Dashboard. Key Responsibilities:

• Data Aggregations: Uses Pandas grouping for macro stats (compute_overview(), compute_churn_by_group()). Excludes synthetic testing rows.
• A/B KPI Comparisons (compute_kpi_comparison): Slices the dataset into "Churned" vs "Stayed" groups to highlight behavioral differences (e.g., average orders, return rates).
• Time-Series Logic (compute_monthly_trend): Treats Tenure as the lifecyle axis to build an accurate retention curve to find the "peak churn month", applying rolling averages for smoothing.
• Model Transparency: Surfaces model accuracy, F1 scores, ROC AUC, and Feature Importance directly to the dashboard from logged metrics files outputted during training.

File: backend/main.py

Purpose: The entry point to the backend web application via the FastAPI framework. It handles HTTP requests, dependency injection, and data formatting. Key Responsibilities:

• API Routing: Exposes endpoints like /predict, /predict/bulk, /analytics, /revenue, and /suggest.
• Data Caching: Uses an in-memory Pandas dataframe _df_cache reading from ecommerce_churn_enhanced.csv loaded exactly once when the server starts up, making dashboard routing extremely fast.
• Excel Formatting (_style_predictions_sheet, _write_summary_sheet): The bulk endpoints allow exporting to Excel format. These loops dynamically color-code rows based on risk level (Red for High Risk, Green for Low Risk) using the openpyxl library to provide polished spreadsheets to users.