Overview

flightrisk builds three honest churn-modelling stacks side by side and ends with a campaign ROI simulator that compares them in dollars.

The three tracks

Track	Question	Output	Trained on
A — Risk	Will this customer churn?	P(churn) calibrated to the population	KKBox
B — Survival	When will they churn?	Full S(t) and per-horizon hazard	KKBox
C — Uplift	Will my offer change the outcome?	τ(x) per customer	Orange Belgium RCT

Why uplift, not just risk

Most public churn projects train Track A and stop. Retention budgets actually need who will stay if I intervene minus who would have stayed anyway — that’s uplift, not risk. The bundled simulator targets the same population three ways (top-k by risk, top-k by uplift, uniformly random), realises retention with a fixed treatment lift, and reports net revenue with bootstrapped confidence intervals. Uplift consistently dominates risk on unsaturated budgets when the “persuadable” segment is non-empty.

Reading the API reference

Each subpackage is documented in the API section. Modules favour:

• typed dataclasses for hyperparameters and result bundles

• explicit no-future-leakage cutoffs in feature builders

• result objects with as_dict() for direct MLflow logging

• thin wrappers around well-known libraries (LightGBM, lifelines, scikit-survival, econml) so the contract is obvious

For a runnable end-to-end tour see the walkthrough notebook (notebooks/00_walkthrough.ipynb).