Skip to main content

Respectful Offers

CI PyPI Python Licence: MIT

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.

Discount spent per extra member kept, by policy and simulator variant: the bandit spends the least in every variant

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.

Walkthrough: the report's headline, every policy, the frontier chart, the respect audit, the off-policy check, the release gates, the local demo and the case study (all outcomes simulated)

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 results report: headline verdict, policy comparison chart and stamps saying the outcomes are simulated and the members are real

The demo: move the discount budget and the risk threshold, switch simulator variants, and watch members kept, discount spent and the live respect audit:

The demo page: sliders for budget and risk threshold, a variant switch, a card per policy and the live audit

How it works

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. Release gates, in EvalKit's format. offers metrics writes the results as EvalKit's metrics-1 file (results/kkbox/metrics.json), and CI gates every change on configs/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 own evalkit 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.
  7. Monitoring and challengers. Each period, offers monitor has 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 challenge tests 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)

Source distribution for respectful-offers 0.2.0
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)

Table of built distributions (wheels) for respectful-offers 0.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page