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.

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)
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 · 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.

Quickstart

Until v0.1.0 reaches PyPI, install from a clone instead: pip install -e . in this repository.

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.1.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.1.0
File Size Uploaded Provenance Actions
respectful_offers-0.1.0.tar.gz 151.7 kB With provenance Details for respectful_offers-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for respectful-offers 0.1.0
File Interpreter ABI Platform Actions
respectful_offers-0.1.0-py3-none-any.whl Python 3 none any Details for respectful_offers-0.1.0-py3-none-any.whl

Total release size: 330.6 kB

Release files / respectful_offers-0.1.0.tar.gz

Download URL respectful_offers-0.1.0.tar.gz
Size 151.7 kB
Tags Source
SHA-256 checksum
How to use checksums
e15df23e822834aa8c45ab85bf12a60476a12b4008c6780338344b54bbe30304
BLAKE2b-256 checksum
How to use checksums
2f836bce625b21f3e00a6a7e6369cd5eb523a035fc1572986d2239d1e3cc5f93
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 16, 2026.

Transparency log

Release files / respectful_offers-0.1.0-py3-none-any.whl

Download URL respectful_offers-0.1.0-py3-none-any.whl
Size 178.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5df9e00370430bbfd4e880dbe2e6f0c770047f1675ecd9cd438ab39b112932c5
BLAKE2b-256 checksum
How to use checksums
f9b30d0bce3fbfc2771bf4a776bdf74a3394474a110dd2f756e410d68c2eedd2
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 16, 2026.

Transparency log

Security for respectful-offers 0.1.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.1.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 16, 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.1.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