How aashnology/churn-gauge works
Churn Gauge is a SaaS churn-risk predictor and action recommender. Its principal workflow is user selection in the adaptive Streamlit launcher, account selection from sample data, model scoring, risk-driver identification, and recommended actions. A separate model-development path generates synthetic datasets, engineers features for v3, trains logistic-regression and XGBoost models, and produces interpretation artifacts including SHAP rankings and partial-dependence results. The README also describes adaptive host recommendations and future CSV uploads behind a quality gate. Some source excerpts are partial, so uncertain internal wiring is omitted.
Main entry points: adaptive_launcher.py Adaptive launcher · synthetic Synthetic datasets · models Model artifacts · churn_gauge_v3_engineered.csv Engineered dataset
Components 21
Prediction experience
- Adaptive launcher
apps/adaptive_launcher.py - Sample account data
data/synthetic/churn_gauge_v2_medium_9000.csv - Scoring model
models/xgb_shap_v2_medium.joblib - Host recommendation
apps/adaptive_launcher.py
Data preparation
- Clean data generator
src/data/generate_synthetic_v1.py - Medium data generator
src/data/generate_synthetic_v2.py - Messy data generator
src/data/generate_synthetic_v3.py - Synthetic datasets
data/synthetic - Feature engineering
src/features/engineer.py - Engineered dataset
data/processed/churn_gauge_v3_engineered.csv
Risk modeling
- Logistic training
src/models/train_logreg_v2.py - XGBoost and SHAP training
src/models/train_xgb_shap_v2.py - Engineered model comparison
src/models/train_engineered_v3.py - Model artifacts
models
Interpretation and actions
- Risk drivers
apps/adaptive_launcher.py - Action recommender
src/actions/recommender.py - Recommended actions
src/actions/recommender.py - Partial dependence analysis
evaluation/partial_dependence.py - PDP results
evaluation/pdp/pdp_values.json - Action catalogue
docs/ACTION_CATALOGUE.md
Other components
- SaaS user
Connections 22
- SaaS user → Adaptive launcher: uses
- Adaptive launcher → Host recommendation: recommends host
- Adaptive launcher → Sample account data: loads sample
- Adaptive launcher → Scoring model: loads model
- Adaptive launcher → Risk drivers: derives drivers
- Adaptive launcher → Action recommender: requests actions
- Action recommender → Recommended actions: returns actions
- Clean data generator → Synthetic datasets: generates clean
- Medium data generator → Synthetic datasets: generates medium
- Messy data generator → Synthetic datasets: generates messy
- Synthetic datasets → Feature engineering: engineers v3
- Feature engineering → Engineered dataset: writes features
- Synthetic datasets → Logistic training: trains on v2
- Synthetic datasets → XGBoost and SHAP training: trains on v2
- Engineered dataset → Engineered model comparison: trains and compares
- Logistic training → Model artifacts: saves model
- XGBoost and SHAP training → Model artifacts: saves model and SHAP
- Engineered model comparison → Model artifacts: saves models
- Model artifacts → Scoring model: includes scoring model
- Engineered dataset → Partial dependence analysis: supplies analysis data
- Model artifacts → Partial dependence analysis: supplies model
- Partial dependence analysis → PDP results: writes PDP values