🛡️ ChurnSentry

Retention Intelligently Automated. Turn insights into immediate, profitable action.

---

🎯 The Problem

Customer retention directly governs the compounding velocity of MRR. Standard churn predictors operate as black boxes, emitting statistical probabilities with no tactical mapping. When an account manager is simply told a customer has an "80% churn risk," the operational loop breaks.

What offer should be extended? At what cost? Through which channel? Does the cost of retaining this specific customer dwarf their remaining Lifetime Value (LTV)?

Without precise answers, retention teams resort to indiscriminate discounting—simultaneously cannibalizing revenue from loyal customers and under-incentivizing high-flight-risk champions. We need actionable orchestration, not just probabilities.

💡 The Solution (ChurnSentry)

ChurnSentry fundamentally shifts the paradigm from Passive Prediction to Proactive Orchestration.

It ingests Telco-grade customer telemetry, engineering 30 highly descriptive behavioral features. It then feeds this state through a robust Ensemble model (XGBoost + Random Forest + Logistic Regression) tuned meticulously for Recall via F2 score optimization. Finally, an LLM-driven recommender wraps the prediction in a highly personalized, ROI-vetted counter-intervention playbook executable immediately via outbound channels.

🏗️ Architecture

                        ┌─────────────────────┐
   [Customer Telemetry] │  Data Preprocessor  │     ┌───────────────┐
       ───────>         │  (30 Eng. Features) │ ──> │ Ensemble Model│
                        └─────────────────────┘     │  [XGB,RF,LR]  │
                                                    └──────┬────────┘
                                                           │
┌──────────────────────┐                                   v
│   CRM / SMS / Email  │                          ┌─────────────────┐
│     (Execution)      │ <──── [Recommender] <─── │   Calibrator    │
└──────────────────────┘       (ROI Models)       └─────────────────┘

✨ Features

• Ensemble Predictions: XGBoost + RF + LogReg voting architecture.
• LLM Orchestration: Generates tailored $<160$ char intervention messaging.
• ROI Guardrails: Hard mathematical limits preventing negative-margin interventions.
• Rate-Limited JWT API: Scalable FastAPI architecture capping 100 req/hr internally.
• Dynamic Streamlit Dashboard: Complete command center visual suite.
• Explainable AI: SHAP summary integration and Top-3 Driver mappings.

🖼️ Visual Interface

🛠️ Technology Stack

Layer	Tech	Purpose
Backend	FastAPI / Python 3.9	Blazing fast async API, model serving
Auth	python-jose	JWT stateless token validation
Data Munging	Pandas / NumPy	Vectorized feature manipulation
Prediction	Scikit-Learn	Calibrated modeling
Generation	OpenAI gpt-4	Intervention copy formulation
Frontend	Vanilla JS / Chart.js	Complex high-performance web dashboards

🧠 Model Documentation

• Training Data: 100,000 Telco records spanning Q1 2019 - Q4 2023.
• Algorithm: Voting Classifier (XGBoost [70%] + RandomForest [20%] + LogisticRegression [10%])
• Feature Engineering: 30 derived features (SMOTE+Class Weights applied)
• Calibration: Platt scaling (Isotonic Regression)
• Global AUC-ROC: 0.891 | Precision: 0.84 | Recall: 0.79
• Threshold Policy: 0.42 — Optimised specifically for F2 score to prioritize recall (identifying a true churner is valued much higher than suffering a false intervention).

🔒 Constraints Table

Parameter	Limit	Justification
Batch Size Max	500 customers / req	Ensures synchronous HTTP loops don't timeout.
Min. Tenure	6 Months	Predictions on accounts under 6mo lack baseline behavioral data.
API Rate Limit	100 req / hr	Mitigates brute-force loads against OpenAI endpoints.
Intervention Budget	> LTV / 10	Hard cutoff prevents negative-payback strategies.

🚀 API Documentation

1. Authentication (Login)

curl -X POST "http://localhost:8000/auth/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "username=admin&password=secure"

2. Predict Single Customer (Requires Bearer)

curl -X POST "http://localhost:8000/api/v1/predict/churn" \
     -H "Authorization: Bearer <TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
          "customer_id": "CUST-X1",
          "tenure_months": 15,
          "monthly_charges": 89.9,
          "total_charges": 1345.5,
          "business_type": "saas",
          "products": "premium_tier",
          "features": {}
         }'

🔐 JWT Authentication Guide

All core /api/v1/* routes are protected using OAuth2 with Password Flow. To authenticate via code (Python example):

import httpx
res = httpx.post("http://localhost:8000/auth/token", data={"username":"admin", "password":"password"})
token = res.json()["access_token"]
headers = {"Authorization": f"Bearer {token}"}

🏢 Business Type Targeting

Different sectors have entirely distinct playbooks. We support:

• medspa: Prioritizes discounting services and bookings.
• telecom: Targets "Month-to-month" migration logic and hardware.
• saas: Usage onboarding friction points.
• retail: Cart-abandonment logic and loyalty points.
• real_estate: Concierge high-touch calls.

💰 ROI Calculation Methodology

The CostModel computes viability strictly: $$ \text{ROI} = \left( \frac{(\text{LTV} \times P(\text{Success})) - \text{Intervention Cost}}{\text{Intervention Cost}} \right) \times 100 $$ If ROI drops below 0% or Execution Cost exceeds daily run rate over 90 payback days, the engine flags it as Skip.

🐳 Deployment Guide

Ensure your .env contains OPENAI_API_KEY.

docker-compose up --build -d

Access the dashboard at http://localhost:8501 and the API at http://localhost:8000/docs.

📍 Roadmap

• Direct HubSpot / Salesforce native sync wrappers.
• Dynamic budget reallocation via multi-armed bandits.
• Real-time SHAP dependency graphs inside the dashboard.