Churn Business Analyst

Production‑grade Streamlit app for churn risk and ticket sentiment analysis with clean engineering hygiene (CI, Docker, tests). Surfaces at‑risk customers, explains “why” with SHAP, and helps prioritize save actions.

Why it matters (Business impact)

• Reduce churn: flags accounts likely to cancel before they do.
• Protect MRR: prioritizes outreach by risk and potential revenue impact.
• Explainable insights: SHAP and sentiment show exactly what to fix.
• Faster loops: weekly churn scoring + ongoing ticket sentiment to drive playbooks.

Tech stack

• Language: Python 3.12
• Core DS/ML: pandas, numpy, scikit‑learn, imbalanced‑learn, XGBoost, LightGBM
• Explainability: SHAP
• NLP: VADER Sentiment
• UI: Streamlit
• Tooling: pytest, Makefile, Docker, GitHub Actions CI
• Notebooks: Jupyter (EDA, experimentation)

Features

• Weekly churn scoring (weekly_scoring.py)
• Bulk ticket sentiment (paste and analyze)
• SHAP explanations for model‑driven decisions
• Simple auto‑training pipeline and feature engineering utilities
• Outcome tracking helpers for save playbooks
• CI on push/PR and a reproducible Docker image

Quickstart (run locally)

• Clone the repo (includes pre-trained Telco model in models/).
• Install: pip install -r requirements.txt (Python 3.12 recommended).
• Run UI: streamlit run app.py → open http://localhost:8501
• Tests: pytest -q
• Make targets: make install / make run / make test / make clean

To retrain the model (e.g. after changing data): python train_telco_model.py — writes models/telco_churn_model_v1.0.pkl.

Docker

• Build: docker build -t churn-analyst .
• Run: docker run -p 8501:8501 churn-analyst

How it works

1. Ingest + preprocess customer data (src/data/preprocessing.py).
2. Train/score via src/pipeline/auto_trainer.py and weekly_scoring.py.
3. Explain predictions with SHAP (src/intelligence/explainer.py).
4. Paste support tickets → sentiment + reasons (src/intelligence/sentiment_analyzer.py).
5. Act with playbooks; log outcomes (src/actions/playbook_engine.py, src/feedback/outcome_tracker.py).

Project structure

• app.py — Streamlit UI
• train_telco_model.py — train and save Telco churn model (optional; pre-trained model included)
• .streamlit/config.toml — Streamlit theme and server config
• src/
  • data/ — preprocessing utilities
  • intelligence/ — churn labeler, SHAP explainer, sentiment analyzer
  • pipeline/ — auto trainer
  • models/ — prediction helpers
  • feedback/ — outcome tracking, auto‑retrainer scaffold
  • actions/ — playbook engine
• weekly_scoring.py — batch scoring entrypoint
• tests/ — unit tests for core components
• models/ — example trained model + metadata
• notebooks/ — EDA/prototyping (Telco churn example)
• Dockerfile, Makefile, pytest.ini, requirements.txt, LICENSE

Example weekly workflow

• Monday: run python weekly_scoring.py → review top‑risk accounts.
• Mid‑week: paste new support tickets → watch sentiment shifts.
• Friday: review outcomes, iterate playbooks, retrain if needed.

Suggested metrics

• Save rate (% high‑risk accounts retained)
• Retained MRR ($ saved per week)
• Time‑to‑first‑contact (from flag → outreach)
• Top churn drivers (pricing, support delays, missing features, etc.)

Roadmap

• CSV/PDF export of save lists and summaries
• API ingestion from helpdesk/CRM sources
• Playbook automation + richer outcome analytics
• Agent/MCP integration to assist outreach

License

MIT — see LICENSE.