rejectkit 0.3.0__tar.gz

rejectkit-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,28 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint
+        run: ruff check .
+      - name: Test
+        run: pytest -q

rejectkit-0.3.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+build/
+dist/
+.eggs/
+
+# Test / tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Notebooks
+.ipynb_checkpoints/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

rejectkit-0.3.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+The format follows [Keep a Changelog](https://keepachangelog.com/) and the
+project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.3.0] - 2026-06-27
+
+### Added
+- `SelfLearning` — semi-supervised self-training reject inference.
+- `HeckmanClassifier` — two-step control-function correction (inverse Mills ratio).
+- **Polars** support: all public entry points accept pandas, polars, or numpy.
+- `rejectkit.plotting` — `plot_benchmark`, `plot_score_distributions`, `plot_ks`
+  (optional, `pip install rejectkit[plot]`).
+- `diagnostics.feature_drift` (per-feature accept-vs-reject PSI) and
+  `diagnostics.swap_set` (swap-set analysis between two scorecards).
+- `MaskedRejectBenchmark` gains `selection="cutoff"` (realistic PD-cutoff policy)
+  and can benchmark `"heckman"` alongside the resampling methods.
+- Documentation site (`mkdocs` + Material).
+
+### Changed
+- `auc_recovery` now reports `NaN` when the oracle does not clearly beat the
+  naive model, instead of an unstable ratio around a near-zero denominator.
+
+## [0.2.0] - 2026-06-27
+
+### Added
+- `Reclassification` — iterative relabel-and-refit reject inference.
+- `Extrapolation` (alias `twins`) — nearest-neighbour label extrapolation.
+
+## [0.1.0] - 2026-06-26
+
+### Added
+- `BaseRejectInferencer` and the scikit-learn-style `fit` / `resample` /
+  `fit_resample` API.
+- Methods: `SimpleAugmentation`, `FuzzyAugmentation`, `Parcelling`, `Reweighting`.
+- `RejectInferenceClassifier` — wrap any classifier with reject inference.
+- `MaskedRejectBenchmark` — measure whether reject inference helps on your data.
+- Metrics: `auc`, `gini`, `ks_statistic`, `psi`.
+- Synthetic data generators `make_credit_data`, `make_accept_reject`.

rejectkit-0.3.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Han
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rejectkit-0.3.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: rejectkit
+Version: 0.3.0
+Summary: Reject inference for credit scoring — 8 scikit-learn-compatible methods plus an honest benchmark that tells you whether it actually helps.
+Project-URL: Homepage, https://github.com/HangilKim11/rejectkit
+Project-URL: Repository, https://github.com/HangilKim11/rejectkit
+Project-URL: Issues, https://github.com/HangilKim11/rejectkit/issues
+Author-email: Han <kim.hangil.ds@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: credit-scoring,machine-learning,reject-inference,risk,sample-selection-bias,scikit-learn,scorecard
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Requires-Dist: numpy>=1.21
+Requires-Dist: pandas>=1.3
+Requires-Dist: scikit-learn>=1.0
+Provides-Extra: dev
+Requires-Dist: matplotlib>=3.4; extra == 'dev'
+Requires-Dist: mkdocs-material>=9.0; extra == 'dev'
+Requires-Dist: mkdocs>=1.5; extra == 'dev'
+Requires-Dist: polars>=0.20; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.0; extra == 'docs'
+Requires-Dist: mkdocs>=1.5; extra == 'docs'
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.4; extra == 'plot'
+Provides-Extra: polars
+Requires-Dist: polars>=0.20; extra == 'polars'
+Description-Content-Type: text/markdown
+
+# rejectkit
+
+**Reject inference for credit scoring — scikit-learn-compatible methods, plus an honest benchmark that tells you whether reject inference actually helps on your data.**
+
+![python](https://img.shields.io/badge/python-3.9%2B-blue)
+![license](https://img.shields.io/badge/license-MIT-green)
+![status](https://img.shields.io/badge/status-beta-orange)
+
+<details>
+<summary><b>한국어 요약 (Korean)</b></summary>
+
+<br>
+
+신용 모델은 **승인된 신청자**(나중에 good/bad 결과를 아는 사람)로만 학습하지만, 실제로는 **거절자를 포함한 전체 신청자**를 평가해야 한다 — 이 표본 선택 편향을 바로잡는 기법이 **reject inference**다. `rejectkit`은 이 고전 기법 8가지를 scikit-learn 스타일의 한 API로 묶고, **"그 보정이 내 데이터에서 실제로 도움이 되는지"** 재는 벤치마크(`MaskedRejectBenchmark`)까지 제공한다. 입력은 pandas·polars·numpy 모두 지원. 자세한 한·영·일 설명은 [docs/explainer.md](docs/explainer.md), 실데이터 예제는 [examples/real_data_home_credit.ipynb](examples/real_data_home_credit.ipynb) 참고.
+
+</details>
+
+<details>
+<summary><b>日本語要約 (Japanese)</b></summary>
+
+<br>
+
+与信モデルは**承認された申込者**（後で good/bad の結果が分かる人）だけで学習するが、実際には**否認者を含む全申込者**を評価しなければならない — この標本選択バイアスを補正する手法が **reject inference**。`rejectkit` はこの古典的手法8種を scikit-learn 風の単一 API にまとめ、**「その補正が自分のデータで実際に役立つか」**を測るベンチマーク（`MaskedRejectBenchmark`）まで備える。入力は pandas・polars・numpy に対応。詳しい3言語解説は [docs/explainer.md](docs/explainer.md)、実データ例は [examples/real_data_home_credit.ipynb](examples/real_data_home_credit.ipynb) を参照。
+
+</details>
+
+---
+
+## Why this exists
+
+A credit model is trained on **accepted** applicants, whose good/bad outcome you eventually observe. But the model has to score the **whole** through-the-door population — including the applicants you **rejected**, who never get an outcome. Training on accepts only is a textbook case of sample-selection bias. *Reject inference* is the family of techniques that tries to correct it.
+
+These methods are standard in the credit-risk world, yet the Python tooling is missing:
+
+- **R** has [`scoringTools`](https://github.com/adimajo/scoringTools) (`augmentation`, `fuzzy_augmentation`, `parcelling`, `reclassification`, `twins`) — GitHub only.
+- **Python** scorecard libraries — `scorecardpy`, `optbinning`, `scorecardbundle` — do WOE/IV binning and logistic scorecards but **skip reject inference entirely**.
+- What's left online is one-off research code, not a packaged, tested library.
+
+`rejectkit` fills that gap: eight reject inference methods behind one scikit-learn-style API, a benchmark harness even `scoringTools` lacks, plus drift diagnostics and plotting.
+
+## Install
+
+```bash
+pip install -e .              # core: numpy, pandas, scikit-learn
+pip install -e ".[plot]"      # + matplotlib plotting helpers
+pip install -e ".[polars]"    # + polars input support
+```
+
+## Quickstart
+
+```python
+from sklearn.linear_model import LogisticRegression
+from rejectkit import RejectInferenceClassifier
+
+# X_accept, y_accept: accepted applicants and their good(0)/bad(1) outcomes
+# X_reject:           rejected applicants — features only, no labels
+clf = RejectInferenceClassifier(
+    estimator=LogisticRegression(max_iter=1000),
+    method="parcelling",
+    method_params={"uplift": 1.3},   # assume rejects are ~30% worse per score band
+)
+clf.fit(X_accept, y_accept, X_reject)
+pd_bad = clf.predict_proba(X_new)[:, 1]
+```
+
+Just want the augmented training sample for your own pipeline?
+
+```python
+from rejectkit import FuzzyAugmentation
+
+X_aug, y_aug, sample_weight = (
+    FuzzyAugmentation(LogisticRegression(max_iter=1000))
+    .fit_resample(X_accept, y_accept, X_reject)
+)
+```
+
+Inputs may be **pandas, polars, or numpy**.
+
+## Methods
+
+| Method | Class | Core idea | Assumption |
+|---|---|---|---|
+| Simple augmentation | `SimpleAugmentation` | Hard 0/1 label by score cutoff | Accept model ranks rejects |
+| Fuzzy augmentation | `FuzzyAugmentation` | Two weighted rows per reject (P(bad), P(good)) | MAR; smooth labels |
+| Parcelling | `Parcelling` | Per-score-band bad rate × `uplift` | Rejects worse by a fixed factor |
+| Reclassification | `Reclassification` | Iteratively relabel & refit | Labels converge |
+| Extrapolation / twins | `Extrapolation` | Local bad rate of nearest accepts | Similar applicants behave alike |
+| Inverse-propensity reweighting | `Reweighting` | Reweight accepts by `1/P(accept)` | MAR; invents no labels |
+| Self-training | `SelfLearning` | Pseudo-label only confident rejects | MAR; confident labels reliable |
+| Heckman control function | `HeckmanClassifier` | Add inverse Mills ratio as a feature | Gaussian selection latent |
+
+All resamplers share `fit(X_accept, y_accept, X_reject)` → `resample()` returning `(X, y, sample_weight)`. `HeckmanClassifier` augments the feature space, so it is a standalone classifier rather than a resampler.
+
+## Does reject inference actually help? Measure it.
+
+You can never validate reject inference directly, because rejects have no outcome — the literature is genuinely split on whether it helps at all. `MaskedRejectBenchmark` settles the question **on your own data**: it hides the labels of a synthetically "rejected" subset of a labelled dataset and checks how well each method recovers a model close to the *oracle* (trained on the full population) versus the *naive* accepts-only baseline.
+
+```python
+from rejectkit import MaskedRejectBenchmark
+from rejectkit.datasets import make_credit_data
+
+X, y = make_credit_data(n_samples=4000, random_state=0)
+bench = MaskedRejectBenchmark(selection="mnar", accept_rate=0.6, random_state=0)
+print(bench.compare(
+    ["fuzzy", "parcelling", "reweighting", "extrapolation", "selflearning", "heckman"],
+    X, y,
+).round(4))
+```
+
+```
+                     auc      ks    gini  auc_recovery
+oracle            0.8203  0.4911  0.6406        1.0000
+naive             0.7488  0.3651  0.4975        0.0000
+fuzzy             0.7488  0.3663  0.4977        0.0010
+parcelling        0.7404  0.3468  0.4809       -0.1161
+reweighting       0.7249  0.3290  0.4498       -0.3334
+extrapolation     0.6989  0.2889  0.3977       -0.6973
+selflearning      0.7124  0.3093  0.4248       -0.5080
+heckman           0.7457  0.3559  0.4914       -0.0424
+```
+
+`auc_recovery`: `0` = no better than the naive accepts-only model, `1` = matches the full-data oracle.
+
+Read this honestly. Selection here is **MNAR** (acceptance depends on the hidden outcome), so naive is badly biased (0.749 vs the 0.820 oracle) — yet the augmentation methods barely move it and several *hurt*; only Heckman nearly holds the naive line. That is what theory predicts when selection depends on the outcome: **reject inference is not a free lunch.** Switch to `selection="mar"` or `selection="cutoff"` and the verdict often flips the other way — frequently the naive model is *already* at the oracle, so `auc_recovery` returns `NaN` (no gap to recover) and reject inference is simply unnecessary. The harness exists so you find out *before* you ship it.
+
+Selection mechanisms: `"mar"` (features only), `"mnar"` (features + hidden outcome), `"cutoff"` (accept the lowest-PD fraction — a realistic credit policy).
+
+## Diagnostics & plotting
+
+```python
+from rejectkit.diagnostics import feature_drift, swap_set, psi
+feature_drift(X_accept, X_reject)        # per-feature accept-vs-reject PSI, worst first
+swap_set(y, score_old, score_new, c_old, c_new)   # who a new scorecard swaps in/out
+
+from rejectkit import plotting            # needs [plot]
+plotting.plot_benchmark(results)
+plotting.plot_score_distributions(score_accept, score_reject)
+plotting.plot_ks(y_true, y_score)
+```
+
+## Caveats
+
+- Augmentation methods infer reject labels from a model fitted on the (biased) accepts, so they cannot escape strong **MNAR** selection on their own.
+- Reject inference often affects **calibration** more than **ranking** (AUC). Evaluate the metric you care about.
+- Always benchmark before adopting. `rejectkit` makes that one function call.
+
+## Documentation
+
+Build the docs site locally:
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+
+## Examples
+
+- `examples/quickstart.py` — 60-second tour (single model + benchmark).
+- `examples/walkthrough.ipynb` — every function on sample data (trilingual KO/EN/JA, executed).
+- `examples/real_data_home_credit.ipynb` — **applied to the real Kaggle Home Credit dataset**: under MNAR selection the naive model collapses (AUC 0.74 → 0.57) and reject inference recovers ~7–8% of the gap; under MAR/cutoff it is unnecessary (trilingual, executed).
+
+## Roadmap
+
+- **v0.1** — core augmentation/parcelling/reweighting, `RejectInferenceClassifier`, benchmark. ✅
+- **v0.2** — reclassification, extrapolation / twins. ✅
+- **v0.3** — self-training, Heckman, polars, plotting, drift diagnostics, docs. ✅
+- **Next** — calibration-focused benchmark metrics, deep generative reject inference (optional extra), PyPI release.
+
+## References
+
+- Hand & Henley (1993), *Can reject inference ever work?*
+- Crook & Banasik (2004), *Does reject inference really improve the performance of application scoring models?*
+- Lopes, *Should we "reject" Reject Inference? An empirical study.*
+- `scoringTools` (R): https://github.com/adimajo/scoringTools
+
+## License
+
+MIT — see [LICENSE](LICENSE).

rejectkit-0.3.0/PUBLISHING.md

@@ -0,0 +1,66 @@
+# Publishing rejectkit to PyPI
+
+Once published, anyone can `pip install rejectkit`. The package name `rejectkit`
+was free on PyPI at the time of writing.
+
+## 0. One-time setup
+- Create a PyPI account: https://pypi.org/account/register/
+- Create an API token (Account settings → API tokens). It looks like `pypi-AgE…`.
+- Install the tooling:
+
+```bash
+pip install build twine
+```
+
+## 1. Before each release
+- Fill in the real values in `pyproject.toml` (`authors`, `[project.urls]`) and
+  `LICENSE` (copyright holder).
+- Bump `version` in `pyproject.toml` (e.g. `0.3.0` → `0.3.1`) and add a
+  `CHANGELOG.md` entry. **PyPI will not let you re-upload an existing version.**
+- (Optional) Remove the hard-coded data path in
+  `examples/real_data_home_credit.ipynb` before publishing.
+
+## 2. Build the distributions
+
+```bash
+rm -rf dist build
+python -m build          # creates dist/*.whl and dist/*.tar.gz
+python -m twine check dist/*   # must say PASSED
+```
+
+## 3. (Recommended) Test on TestPyPI first
+
+```bash
+python -m twine upload --repository testpypi dist/*
+# then, in a fresh virtualenv:
+pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ rejectkit
+```
+
+## 4. Publish to the real PyPI
+
+```bash
+python -m twine upload dist/*
+# username: __token__
+# password: your pypi-… API token
+```
+
+Or non-interactively:
+
+```bash
+TWINE_USERNAME=__token__ TWINE_PASSWORD=pypi-XXXX python -m twine upload dist/*
+```
+
+## 5. Verify
+
+```bash
+pip install rejectkit
+python -c "import rejectkit; print(rejectkit.__version__)"
+```
+
+## Notes
+- The wheel ships **only the `rejectkit` package code** (verified). Example data
+  (Home Credit, etc.) is **not** included — users bring their own; the synthetic
+  `rejectkit.datasets.make_credit_data` is bundled so they can try it immediately.
+- Optional extras install with `pip install "rejectkit[plot]"`, `"[polars]"`, `"[docs]"`, `"[dev]"`.
+- Publishing a version to PyPI is effectively permanent; you can *yank* a bad
+  release but not silently replace it. Get the metadata right first.

rejectkit-0.3.0/README.md

@@ -0,0 +1,178 @@
+# rejectkit
+
+**Reject inference for credit scoring — scikit-learn-compatible methods, plus an honest benchmark that tells you whether reject inference actually helps on your data.**
+
+![python](https://img.shields.io/badge/python-3.9%2B-blue)
+![license](https://img.shields.io/badge/license-MIT-green)
+![status](https://img.shields.io/badge/status-beta-orange)
+
+<details>
+<summary><b>한국어 요약 (Korean)</b></summary>
+
+<br>
+
+신용 모델은 **승인된 신청자**(나중에 good/bad 결과를 아는 사람)로만 학습하지만, 실제로는 **거절자를 포함한 전체 신청자**를 평가해야 한다 — 이 표본 선택 편향을 바로잡는 기법이 **reject inference**다. `rejectkit`은 이 고전 기법 8가지를 scikit-learn 스타일의 한 API로 묶고, **"그 보정이 내 데이터에서 실제로 도움이 되는지"** 재는 벤치마크(`MaskedRejectBenchmark`)까지 제공한다. 입력은 pandas·polars·numpy 모두 지원. 자세한 한·영·일 설명은 [docs/explainer.md](docs/explainer.md), 실데이터 예제는 [examples/real_data_home_credit.ipynb](examples/real_data_home_credit.ipynb) 참고.
+
+</details>
+
+<details>
+<summary><b>日本語要約 (Japanese)</b></summary>
+
+<br>
+
+与信モデルは**承認された申込者**（後で good/bad の結果が分かる人）だけで学習するが、実際には**否認者を含む全申込者**を評価しなければならない — この標本選択バイアスを補正する手法が **reject inference**。`rejectkit` はこの古典的手法8種を scikit-learn 風の単一 API にまとめ、**「その補正が自分のデータで実際に役立つか」**を測るベンチマーク（`MaskedRejectBenchmark`）まで備える。入力は pandas・polars・numpy に対応。詳しい3言語解説は [docs/explainer.md](docs/explainer.md)、実データ例は [examples/real_data_home_credit.ipynb](examples/real_data_home_credit.ipynb) を参照。
+
+</details>
+
+---
+
+## Why this exists
+
+A credit model is trained on **accepted** applicants, whose good/bad outcome you eventually observe. But the model has to score the **whole** through-the-door population — including the applicants you **rejected**, who never get an outcome. Training on accepts only is a textbook case of sample-selection bias. *Reject inference* is the family of techniques that tries to correct it.
+
+These methods are standard in the credit-risk world, yet the Python tooling is missing:
+
+- **R** has [`scoringTools`](https://github.com/adimajo/scoringTools) (`augmentation`, `fuzzy_augmentation`, `parcelling`, `reclassification`, `twins`) — GitHub only.
+- **Python** scorecard libraries — `scorecardpy`, `optbinning`, `scorecardbundle` — do WOE/IV binning and logistic scorecards but **skip reject inference entirely**.
+- What's left online is one-off research code, not a packaged, tested library.
+
+`rejectkit` fills that gap: eight reject inference methods behind one scikit-learn-style API, a benchmark harness even `scoringTools` lacks, plus drift diagnostics and plotting.
+
+## Install
+
+```bash
+pip install -e .              # core: numpy, pandas, scikit-learn
+pip install -e ".[plot]"      # + matplotlib plotting helpers
+pip install -e ".[polars]"    # + polars input support
+```
+
+## Quickstart
+
+```python
+from sklearn.linear_model import LogisticRegression
+from rejectkit import RejectInferenceClassifier
+
+# X_accept, y_accept: accepted applicants and their good(0)/bad(1) outcomes
+# X_reject:           rejected applicants — features only, no labels
+clf = RejectInferenceClassifier(
+    estimator=LogisticRegression(max_iter=1000),
+    method="parcelling",
+    method_params={"uplift": 1.3},   # assume rejects are ~30% worse per score band
+)
+clf.fit(X_accept, y_accept, X_reject)
+pd_bad = clf.predict_proba(X_new)[:, 1]
+```
+
+Just want the augmented training sample for your own pipeline?
+
+```python
+from rejectkit import FuzzyAugmentation
+
+X_aug, y_aug, sample_weight = (
+    FuzzyAugmentation(LogisticRegression(max_iter=1000))
+    .fit_resample(X_accept, y_accept, X_reject)
+)
+```
+
+Inputs may be **pandas, polars, or numpy**.
+
+## Methods
+
+| Method | Class | Core idea | Assumption |
+|---|---|---|---|
+| Simple augmentation | `SimpleAugmentation` | Hard 0/1 label by score cutoff | Accept model ranks rejects |
+| Fuzzy augmentation | `FuzzyAugmentation` | Two weighted rows per reject (P(bad), P(good)) | MAR; smooth labels |
+| Parcelling | `Parcelling` | Per-score-band bad rate × `uplift` | Rejects worse by a fixed factor |
+| Reclassification | `Reclassification` | Iteratively relabel & refit | Labels converge |
+| Extrapolation / twins | `Extrapolation` | Local bad rate of nearest accepts | Similar applicants behave alike |
+| Inverse-propensity reweighting | `Reweighting` | Reweight accepts by `1/P(accept)` | MAR; invents no labels |
+| Self-training | `SelfLearning` | Pseudo-label only confident rejects | MAR; confident labels reliable |
+| Heckman control function | `HeckmanClassifier` | Add inverse Mills ratio as a feature | Gaussian selection latent |
+
+All resamplers share `fit(X_accept, y_accept, X_reject)` → `resample()` returning `(X, y, sample_weight)`. `HeckmanClassifier` augments the feature space, so it is a standalone classifier rather than a resampler.
+
+## Does reject inference actually help? Measure it.
+
+You can never validate reject inference directly, because rejects have no outcome — the literature is genuinely split on whether it helps at all. `MaskedRejectBenchmark` settles the question **on your own data**: it hides the labels of a synthetically "rejected" subset of a labelled dataset and checks how well each method recovers a model close to the *oracle* (trained on the full population) versus the *naive* accepts-only baseline.
+
+```python
+from rejectkit import MaskedRejectBenchmark
+from rejectkit.datasets import make_credit_data
+
+X, y = make_credit_data(n_samples=4000, random_state=0)
+bench = MaskedRejectBenchmark(selection="mnar", accept_rate=0.6, random_state=0)
+print(bench.compare(
+    ["fuzzy", "parcelling", "reweighting", "extrapolation", "selflearning", "heckman"],
+    X, y,
+).round(4))
+```
+
+```
+                     auc      ks    gini  auc_recovery
+oracle            0.8203  0.4911  0.6406        1.0000
+naive             0.7488  0.3651  0.4975        0.0000
+fuzzy             0.7488  0.3663  0.4977        0.0010
+parcelling        0.7404  0.3468  0.4809       -0.1161
+reweighting       0.7249  0.3290  0.4498       -0.3334
+extrapolation     0.6989  0.2889  0.3977       -0.6973
+selflearning      0.7124  0.3093  0.4248       -0.5080
+heckman           0.7457  0.3559  0.4914       -0.0424
+```
+
+`auc_recovery`: `0` = no better than the naive accepts-only model, `1` = matches the full-data oracle.
+
+Read this honestly. Selection here is **MNAR** (acceptance depends on the hidden outcome), so naive is badly biased (0.749 vs the 0.820 oracle) — yet the augmentation methods barely move it and several *hurt*; only Heckman nearly holds the naive line. That is what theory predicts when selection depends on the outcome: **reject inference is not a free lunch.** Switch to `selection="mar"` or `selection="cutoff"` and the verdict often flips the other way — frequently the naive model is *already* at the oracle, so `auc_recovery` returns `NaN` (no gap to recover) and reject inference is simply unnecessary. The harness exists so you find out *before* you ship it.
+
+Selection mechanisms: `"mar"` (features only), `"mnar"` (features + hidden outcome), `"cutoff"` (accept the lowest-PD fraction — a realistic credit policy).
+
+## Diagnostics & plotting
+
+```python
+from rejectkit.diagnostics import feature_drift, swap_set, psi
+feature_drift(X_accept, X_reject)        # per-feature accept-vs-reject PSI, worst first
+swap_set(y, score_old, score_new, c_old, c_new)   # who a new scorecard swaps in/out
+
+from rejectkit import plotting            # needs [plot]
+plotting.plot_benchmark(results)
+plotting.plot_score_distributions(score_accept, score_reject)
+plotting.plot_ks(y_true, y_score)
+```
+
+## Caveats
+
+- Augmentation methods infer reject labels from a model fitted on the (biased) accepts, so they cannot escape strong **MNAR** selection on their own.
+- Reject inference often affects **calibration** more than **ranking** (AUC). Evaluate the metric you care about.
+- Always benchmark before adopting. `rejectkit` makes that one function call.
+
+## Documentation
+
+Build the docs site locally:
+
+```bash
+pip install -e ".[docs]"
+mkdocs serve
+```
+
+## Examples
+
+- `examples/quickstart.py` — 60-second tour (single model + benchmark).
+- `examples/walkthrough.ipynb` — every function on sample data (trilingual KO/EN/JA, executed).
+- `examples/real_data_home_credit.ipynb` — **applied to the real Kaggle Home Credit dataset**: under MNAR selection the naive model collapses (AUC 0.74 → 0.57) and reject inference recovers ~7–8% of the gap; under MAR/cutoff it is unnecessary (trilingual, executed).
+
+## Roadmap
+
+- **v0.1** — core augmentation/parcelling/reweighting, `RejectInferenceClassifier`, benchmark. ✅
+- **v0.2** — reclassification, extrapolation / twins. ✅
+- **v0.3** — self-training, Heckman, polars, plotting, drift diagnostics, docs. ✅
+- **Next** — calibration-focused benchmark metrics, deep generative reject inference (optional extra), PyPI release.
+
+## References
+
+- Hand & Henley (1993), *Can reject inference ever work?*
+- Crook & Banasik (2004), *Does reject inference really improve the performance of application scoring models?*
+- Lopes, *Should we "reject" Reject Inference? An empirical study.*
+- `scoringTools` (R): https://github.com/adimajo/scoringTools
+
+## License
+
+MIT — see [LICENSE](LICENSE).

rejectkit-0.3.0/docs/api.md

@@ -0,0 +1,27 @@
+# API reference
+
+## Estimators
+
+- **`RejectInferenceClassifier(estimator=None, method="fuzzy", base_scorer=None, method_params=None)`**
+  Wrap any classifier with reject inference. `fit(X_accept, y_accept, X_reject)`, then `predict` / `predict_proba`.
+- **`HeckmanClassifier(selection_estimator=None, outcome_estimator=None)`**
+  Two-step control-function correction. `fit(X_accept, y_accept, X_reject)`, then `predict_proba`.
+- **`get_inferencer(method, base_estimator=None, **params)`** — factory for the resampler classes.
+
+## Reject inference methods (resamplers)
+
+All subclass `BaseRejectInferencer` and expose `fit`, `resample`, `fit_resample`:
+
+`SimpleAugmentation`, `FuzzyAugmentation`, `Parcelling`, `Reclassification`,
+`Extrapolation`, `Reweighting`, `SelfLearning`.
+
+## Benchmark
+
+- **`MaskedRejectBenchmark(selection="mnar", accept_rate=0.6, test_size=0.3, selection_strength=2.0, random_state=0)`**
+  `.compare(methods, X, y, estimator=None, method_params=None) -> DataFrame`.
+
+## Data & diagnostics
+
+- `datasets.make_credit_data(...)`, `datasets.make_accept_reject(...)`
+- `diagnostics.auc / gini / ks_statistic / psi / feature_drift / swap_set`
+- `plotting.plot_benchmark / plot_score_distributions / plot_ks`

rejectkit-0.3.0/docs/benchmark.md

@@ -0,0 +1,41 @@
+# Benchmark
+
+You can never validate reject inference directly, because rejects have no outcome. `MaskedRejectBenchmark` settles the question **on your own data**: it takes a fully labelled dataset, hides the labels of a synthetically "rejected" subset, and measures how well each method recovers a model close to the *oracle* (trained on the full population) versus the *naive* accepts-only baseline.
+
+```python
+from rejectkit import MaskedRejectBenchmark
+from rejectkit.datasets import make_credit_data
+
+X, y = make_credit_data(n_samples=4000, random_state=0)
+bench = MaskedRejectBenchmark(selection="cutoff", accept_rate=0.6, random_state=0)
+print(bench.compare(
+    ["simple", "fuzzy", "parcelling", "reweighting",
+     "reclassification", "extrapolation", "selflearning", "heckman"],
+    X, y,
+).round(4))
+```
+
+`auc_recovery`: `0` = no better than the naive accepts-only model, `1` = matches the full-data oracle.
+
+## Selection mechanisms
+
+| `selection` | Acceptance depends on | Use it to model |
+|---|---|---|
+| `"mar"` | observed features only | missing-at-random selection |
+| `"mnar"` | features **and** the hidden outcome | the hard case; naive is most biased |
+| `"cutoff"` | predicted PD (accept lowest-risk fraction) | a realistic credit policy cutoff |
+
+## How the accept/reject split is simulated
+
+Real labelled data has an outcome for every row, so the harness *creates* rejects:
+
+1. Score each applicant: `acceptance = f(features) (+ outcome term under MNAR) + noise`.
+2. Accept the top `accept_rate` fraction; reject the rest.
+3. Hide the rejected rows' labels (the *"Masked"* in the name).
+4. Train each model on accepts (+ inferred rejects) and score it against the **held-out, fully-labelled** test set.
+
+The rejects are therefore not real declined applicants but labelled rows whose outcome was deliberately hidden — the only way to *measure* recovery, since genuine rejects have no outcome to check against.
+
+## Reading the result honestly
+
+Reject inference is **not** a free lunch. Under pure **MNAR** selection, augmentation methods inherit the accept model's bias and often fail to beat naive — exactly what theory predicts. Under **MAR** and **cutoff** selection, methods such as parcelling and extrapolation can recover a meaningful share of the oracle gap. The point of the harness is to let you discover which regime you are in *before* shipping reject inference on faith.