---
title: Customer Churn API
emoji: 📉
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860
pinned: false
---

# Customer Churn Prediction API

FastAPI service that scores telecom customers for churn risk.
Loads a calibrated XGBoost champion from a DagsHub-hosted MLflow registry at startup.
Optionally generates SHAP-grounded LLM explanations via Gemini (Groq fallback).

## Endpoints

| Endpoint | Method | Description |
|---|---|---|
| `/health` | GET | Service status + model load flag |
| `/predict` | POST | Churn probability + binary prediction at cost-optimal threshold |
| `/explain` | POST | SHAP top-5 drivers + RAG playbook context + LLM narrative |
| `/stats` | GET | Prediction-log aggregates (count, latency p50/p95, avg prob) |
| `/docs` | GET | Interactive Swagger UI |

## Required Space Secrets

Set these under **Settings → Repository secrets** in the HF Space panel.

| Secret | Required | Value |
|---|---|---|
| `MLFLOW_TRACKING_URI` | **Yes** | `https://dagshub.com/<dagshub-user>/customer-churn-mlops.mlflow` |
| `MLFLOW_TRACKING_USERNAME` | **Yes** | Your DagsHub username |
| `MLFLOW_TRACKING_PASSWORD` | **Yes** | Your DagsHub access token |
| `GEMINI_API_KEY` | Optional | Enables `/explain` with `gemini-2.5-flash-lite` |
| `GROQ_API_KEY` | Optional | Groq fallback LLM for `/explain` |

If no LLM key is set, `/explain` returns a deterministic rule-based explanation (`provider: fallback`).

## Known limitations (free tier)

- **Cold start**: Space sleeps after 48 h of inactivity; restart re-downloads the champion
  from DagsHub MLflow (~30 s).
- **Prediction log**: SQLite resets on container restart — fine for a demo.
- **`/explain` SHAP**: requires `data/raw/telco_churn.csv` in the build context
  (see [deploy/HF_DEPLOY.md](../../deploy/HF_DEPLOY.md) optional step).

## Source

GitHub: [brej-29/customer-churn-mlops](https://github.com/brej-29/customer-churn-mlops)
Branch: `tier3-deployment`