Respectful Offers
A subscription retention policy that predicts churn risk, chooses offers with a Thompson sampling bandit, and obeys two respect rules: a declined offer stays declined, and members at risk see content before commerce. It is evaluated offline, against a holdout, on real KKBox member behaviour with simulated offer responses.
On 200,000 real KKBox members with simulated offer responses, the respectful bandit spent 97 NTD of discount per extra member kept, against 211 NTD for the rule-following baseline and 289 NTD for the status quo, which breaks both respect rules (central variant). That was the pre-registered claim, more members kept per 1,000 NTD of discount than the baseline, and it holds in all three simulator variants (central +5.57, conservative +1.74, optimistic +9.36 members per 1,000 NTD; Holm-adjusted). In absolute terms the bandit keeps fewer extra members than the baseline (7.8 against 10.8 per 1,000, central): it leans on free content nudges and a cheaper plan instead of half-price months.
Simulated. KKBox's data holds no offers. Members, features, churn labels and churn risk are real; how a member responds to an offer comes from a pre-registered simulator (
configs/simulator.yaml), and every result is reported under all three of its variants. Read the conclusions as conditional on those assumptions.
pip install respectful-offers
offers report --example # a full report from synthetic members, in seconds
offers data download && offers run --all # the published run (Kaggle token needed)
Data: WSDM Cup 2018, KKBox's churn prediction challenge on Kaggle, used under its rules for non-commercial research and education. No member data is in this repository.
Links
| Results report | biplob819.github.io/respectful-offers: every policy under every simulator variant, the respect audit, the holdout check, off-policy estimates beside the exact oracle, the churn model |
| Live demo | respectful-offers.streamlit.app: a policy simulator on an aggregates-only cube of the real run (passkey protected; run it locally without one, below) |
| Case study | The project in five short sections, with a walkthrough GIF of the key screens (shot list) |
| PR/FAQ | One page, working backwards (Markdown): what was built, the result, and what a real A/B test would add |
| Decision review | Real decisions, read end to end before any number was published |
| Published results | results/kkbox/: summary, audit, lineage, churn model card |
| Guides | Quickstart · Your own data · Writing a simulator · How the respect rules work · Reproduce the results · Monitoring and challengers · Privacy |
| Product and design | PRD · Tech Spec · Decision log · Lessons · Pre-registration · Data card · Changelog |
| Package | respectful-offers on PyPI: CLI offers, import respectful_offers |
What it looks like
The results report (static HTML, no scripts, every simulated figure labelled):
The demo: move the discount budget and the risk threshold, switch simulator variants, and watch members kept, discount spent and the live respect audit:
How it works
- Churn risk. A gradient-boosted model, calibrated, trained on February 2017 members and evaluated on March (AUC 0.84 on real labels). Age and gender never enter it; they are only audited.
- Respect filter. Before any policy chooses, the rules remove what it may not do: an action the member declined (R1), a commercial offer to an at-risk member who has not been offered content first (R2), anything for the holdout (R3). An independent auditor recomputes every rule from the decision log.
- Policies. No offer, the status quo (discount everyone at risk, ignoring the rules), a rule-following baseline, a Thompson sampling bandit, and a segment oracle as the ceiling, all under one discount budget.
- Simulator. Each member gets a hidden response segment (sure thing, persuadable, lost cause, sleeping dog) from a pre-registered mix that depends on their real features; three variants (conservative, central, optimistic) bracket the assumptions.
- Evaluation. Every policy is rolled out on the same 200,000 members with common random numbers, compared with paired block-bootstrap intervals and a Holm correction; off-policy estimates (IPS, SNIPS, doubly robust) are checked against the simulator's exact answer.
- Release gates, in EvalKit's format.
offers metricswrites the results as EvalKit'smetrics-1file (results/kkbox/metrics.json), and CI gates every change onconfigs/gates.yaml: zero respect violations for every respectful policy, the pre-registered claim in every variant and a clean holdout check must hold; age-band disparity, churn-model quality and off-policy coverage warn. CI runs EvalKit's ownevalkit gate(pip install 'respectful-offers[evalkit]'; the package itself never needs EvalKit), and EvalKit's downstream canary runs this repo's contract tests before every EvalKit release. - Monitoring and challengers. Each period,
offers monitorhas EvalKit 0.4 check the real inputs and the churn model's calibration for drift (they warn) and checks the outcomes the claim rests on (they fail).offers challengetests a retrained model and bandit against the champion under a promotion rule stated in advance, records it in EvalKit's experiment ledger and in the decision log. The first challenger was not promoted. See monitoring.
Quickstart
pip install respectful-offers # Python 3.11 to 3.13, any OS
offers doctor # checks Python, configs and data; prints no secrets
offers report --example # a complete report from synthetic members
Then run the whole pipeline on synthetic members, bring your own member table, or reproduce the published results. To run the demo locally (no passkey needed on your own machine):
git clone https://github.com/biplob819/respectful-offers && cd respectful-offers
pip install -e ".[demo]"
streamlit run src/respectful_offers/demo/app.py -- --cube demo/cube.json
How it was built
Node by node with a gated build harness: a node graph (docs/graph/), a capability catalog where every row is proven by named tests, twelve convergence gates per node, and a skeptical verifier that tries to disprove each node before it turns green. Every verifier finding and owner ruling is in the decision log; every mistake worth not repeating is in lessons. python scripts/status.py prints live progress. The longer story: how it was built.
Privacy
No telemetry. Nothing leaves your machine except the KKBox download you run yourself. KKBox data and member-level files are never committed; CI scans every push for them. See privacy and the data card.
Contributing
Issues and pull requests are welcome: see CONTRIBUTING, the code of conduct and, for vulnerabilities, SECURITY. Licence: MIT.
Glossary
- Simulated. KKBox's data holds no offers, so how a member responds to one comes from a stated, pre-registered simulator (
configs/simulator.yaml). Members, features, churn labels and churn risk are real; every outcome that depends on an offer is simulated. - Response segments. The simulator gives each member a hidden segment, as in uplift marketing. A sure thing is a member whose renewal an offer does not change: they still renew only at their own base rate (1 − churn risk), so "sure" does not mean "always renews", and a discount to them is wasted. A persuadable renews more when shown an offer; a lost cause leaves whatever you do; a sleeping dog is reminded to leave by an offer, even one they decline.
- At risk. Churn risk at or above the configured threshold (0.15).
- R1, R2. The respect rules: an action a member declined is not shown again (R1); members at risk see content before any commercial offer (R2).
- Pre-registered. The simulator's values were frozen by their sha256 before the real run (
docs/prereg.md); a run on real data refuses any other file.
Metadata
Release files for respectful-offers 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| respectful_offers-0.2.0.tar.gz | 173.8 kB | With provenance | Details for respectful_offers-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| respectful_offers-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for respectful_offers-0.2.0-py3-none-any.whl |
Total release size: 374.7 kB
Release files / respectful_offers-0.2.0.tar.gz
| Download URL | respectful_offers-0.2.0.tar.gz |
|---|---|
| Size | 173.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3c91e6f2f944d86a81b14afad8ca50f394967985316c0e10adb6e285e4ad66ee
|
|
BLAKE2b-256 checksum How to use checksums |
a8f0ab14c7b38ca3b40bf9b33e79727c4e04b5b25f322a2de357c0345ff19c1f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / respectful_offers-0.2.0-py3-none-any.whl
| Download URL | respectful_offers-0.2.0-py3-none-any.whl |
|---|---|
| Size | 200.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9d268e9d8d10e1aaf5ccb207b6d0d61f6bb3a9ace273be540af19d534edb97b8
|
|
BLAKE2b-256 checksum How to use checksums |
5b92f05f87d73b737fbc80799dd770b13429ec88ce8014b787dc55ae0139938b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for respectful-offers 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for respectful_offers-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.