treecf 0.3.1__tar.gz → 0.3.2__tar.gz

treecf-0.3.2/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: treecf
+Version: 0.3.2
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Dist: numpy>=1.24
+Requires-Dist: xgboost>=2.0 ; extra == 'all'
+Requires-Dist: lightgbm>=4.3 ; extra == 'all'
+Requires-Dist: catboost>=1.2 ; extra == 'all'
+Requires-Dist: scikit-learn>=1.4 ; extra == 'all'
+Requires-Dist: matplotlib>=3.8 ; extra == 'all'
+Requires-Dist: catboost>=1.2 ; extra == 'catboost'
+Requires-Dist: maturin>=1.7 ; extra == 'dev'
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0 ; extra == 'dev'
+Requires-Dist: hypothesis>=6.100 ; extra == 'dev'
+Requires-Dist: ruff>=0.5 ; extra == 'dev'
+Requires-Dist: mypy>=1.10 ; extra == 'dev'
+Requires-Dist: xgboost>=2.0 ; extra == 'dev'
+Requires-Dist: lightgbm>=4.3 ; extra == 'dev'
+Requires-Dist: catboost>=1.2 ; extra == 'dev'
+Requires-Dist: scikit-learn>=1.4 ; extra == 'dev'
+Requires-Dist: matplotlib>=3.8 ; extra == 'dev'
+Requires-Dist: probcal>=0.2 ; extra == 'dev'
+Requires-Dist: mkdocs>=1.6 ; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.5 ; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.27 ; extra == 'docs'
+Requires-Dist: pymdown-extensions>=10.9 ; extra == 'docs'
+Requires-Dist: mkdocs-jupyter>=0.24 ; extra == 'docs'
+Requires-Dist: ipykernel>=6.29 ; extra == 'docs'
+Requires-Dist: lightgbm>=4.3 ; extra == 'lightgbm'
+Requires-Dist: scikit-learn>=1.4 ; extra == 'sklearn'
+Requires-Dist: pytest>=8.0 ; extra == 'test'
+Requires-Dist: hypothesis>=6.100 ; extra == 'test'
+Requires-Dist: probcal>=0.2 ; extra == 'test'
+Requires-Dist: matplotlib>=3.8 ; extra == 'viz'
+Requires-Dist: xgboost>=2.0 ; extra == 'xgboost'
+Provides-Extra: all
+Provides-Extra: catboost
+Provides-Extra: dev
+Provides-Extra: docs
+Provides-Extra: lightgbm
+Provides-Extra: sklearn
+Provides-Extra: test
+Provides-Extra: viz
+Provides-Extra: xgboost
+License-File: LICENSE
+Summary: Constrained, threshold-aware counterfactual explanations for tree ensembles (XGBoost, LightGBM, CatBoost, sklearn) — fast Rust genetic search, exact optimality proofs, certified infeasibility, and recourse regions.
+Keywords: counterfactual,xai,interpretability,recourse,gbdt,xgboost,lightgbm,catboost,credit-risk
+Author-email: Daniel Wlazlo <wlazlo.daniel@gmail.com>
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/wlazlod/treecf/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://wlazlod.github.io/treecf/
+Project-URL: Homepage, https://github.com/wlazlod/treecf
+Project-URL: Issues, https://github.com/wlazlod/treecf/issues
+
+# treecf
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22069503.svg)](https://doi.org/10.5281/zenodo.22069503)
+[![PyPI](https://img.shields.io/pypi/v/treecf.svg)](https://pypi.org/project/treecf/)
+[![Python](https://img.shields.io/pypi/pyversions/treecf.svg)](https://pypi.org/project/treecf/)
+[![CI](https://github.com/wlazlod/treecf/actions/workflows/ci.yml/badge.svg)](https://github.com/wlazlod/treecf/actions/workflows/ci.yml)
+[![License](https://img.shields.io/pypi/l/treecf.svg)](LICENSE)
+
+**Constrained, threshold-aware counterfactual explanations for tree ensembles.**
+
+`treecf` answers the question: *"what is the minimal, feasible change to this instance such
+that the model's output lands in a target interval?"* — for XGBoost, LightGBM, CatBoost and
+scikit-learn tree ensembles.
+
+![Lever-set by feature matrix of a recourse menu: filled cells where a plan changes that lever, a square for a proved-optimal plan, a cross for a lever set certified unable to reach the target](https://raw.githubusercontent.com/wlazlod/treecf/main/docs/guide/img/plot_recourse_menu.png)
+
+> On [PyPI](https://pypi.org/project/treecf/). See the [documentation](https://wlazlod.github.io/treecf/) for concepts and tutorials.
+
+## Why another counterfactual package?
+
+- **Tree-native and fast.** Models are parsed into a shared tree IR and the constrained
+  search runs on a bundled Rust core, typically in milliseconds; every result is
+  float-verified against the parsed model before it is returned, and the parsers are
+  conformance-tested against the native library.
+- **Optional proofs, inside a measured envelope.** `backend="exact"` returns
+  `proof="optimal"` when no cheaper plan exists under the declared objective (weighted
+  distance, plus a per-feature term only if you set `sparsity_weight`), and a completed
+  search that finds nothing returns `Infeasible(proof="certified")`. Proofs scale with the
+  number of levers the search may move, not with the model's width: on the measured matrix
+  the refine search certifies up to 200 trees with 12 free features inside 60 s and no
+  20-feature model beyond the smallest one (50 trees at depth 3) — while on the 300-tree,
+  50-feature model a coalition of up to
+  three levers certifies in under half a second with `search="refine"`, so wide models get
+  proofs once the levers are restricted with `Freeze`, coalitions, or a `recourse_menu`. A
+  search that runs out of budget returns its best plan labelled `heuristic` and warns; it
+  never claims more.
+- **Recourse regions.** Any verified counterfactual widens into a certified box — "reduce
+  utilization below 0.40", not "to 0.3972" — with every point in the box provably in-target
+  and constraint-feasible; works with every backend.
+- **Real constraints.** Immutability, directionality, ranges, one-hot consistency, linear
+  inter-feature rules such as `max_dpd_30d <= max_dpd_12m`, and NaN as a legitimate value
+  with its own transition cost — declared once, enforced by every backend.
+- **Menus, diverse plans, certificates.** `recourse_menu` solves every lever set up to a
+  size and says which combinations provably cannot work; `explain_diverse` returns the
+  cheapest plans with distinct lever sets; `certificate` turns any result into a
+  self-contained JSON record a validator re-checks later.
+
+On a 120-tree model and 100 declined rows, treecf's plans cost a seventh of DiCE's at a fifth
+of the time; NICE is four times faster per instance, and its plans cost 2.7 times more and
+cannot take constraints. The measured tables and the honest reading are on the
+[benchmarks page](https://wlazlod.github.io/treecf/concepts/backends/#against-other-cf-libraries).
+
+Not for you if: the model is not a tree ensemble; you want sets of plans diverse by distance
+rather than by the levers they use (DiCE does that); you need a proof over dozens of free
+levers at once without restricting them (see the [proof envelope](https://wlazlod.github.io/treecf/concepts/certification/#the-proof-envelope-measured));
+or you need a frozen API — treecf is in beta, see
+[API stability](https://wlazlod.github.io/treecf/api-stability/).
+
+## Installation
+
+```bash
+pip install "treecf[xgboost,viz]"   # wheels for Linux, macOS, Windows; no Rust toolchain needed
+```
+
+numpy is the only Python dependency; the extras add a parser for your training library and
+the plots. JSON model dumps parse without the training library, so explanations can be
+generated on a scoring host that has neither it nor a solver.
+
+## Quick look
+
+`credit_demo()` returns a packaged credit model, background rows, and one declined
+applicant. It is new in this version; on an older installed package, substitute your own
+model, as the quickstart notebook does.
+
+```python
+from treecf import Explainer, Freeze, Monotone, Target
+from treecf.datasets import credit_demo
+
+model, X, x = credit_demo()
+target = Target.probability(range=(0.0, 0.05))
+exp = Explainer(
+    model, background=X,
+    constraints=[Freeze("occupation"), Monotone("tenure_months", "increase")],
+)
+
+res = exp.explain(x, target=target, seed=0)
+res.changes                          # {'income': (4678.0, 6932.4)}
+res.proof                            # 'heuristic'
+
+proved = exp.explain(x, target=target, backend="exact", region=True, seed=0)
+proved.proof                         # 'optimal'
+proved.region.describe()             # {'income': 'in [6.58e+03, 7.81e+03] (data-limited)',
+                                     #  'utilization': 'in [0.428, 0.541)', ...}
+
+menu = exp.recourse_menu(x, target=target, max_levers=2)
+menu.describe()["dpd_12m"]           # 'no acceptance is reachable by changing only dpd_12m'
+```
+
+## Learn more
+
+- [How it works](https://wlazlod.github.io/treecf/how-it-works/) — the pipeline from objective to verified answer.
+- [Certification](https://wlazlod.github.io/treecf/concepts/certification/) — what a proof covers and where it stops.
+- [Credit-risk walkthrough](https://wlazlod.github.io/treecf/notebooks/02-credit-risk-tutorial/) — a batch workflow end to end.
+- [probcal integration](https://wlazlod.github.io/treecf/guide/probcal/) — recourse against calibrated cutoffs.
+
+## Cite
+
+```bibtex
+@software{wlazlo_treecf,
+  author  = {Wlazło, Daniel},
+  title   = {treecf: constrained, threshold-aware counterfactual explanations for tree ensembles},
+  doi     = {10.5281/zenodo.22069503},
+  url     = {https://github.com/wlazlod/treecf},
+  license = {MIT}
+}
+```
+
+## Contributing and license
+
+MIT. See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, the test layers, and the
+project's hard invariants; report security issues privately per [SECURITY.md](SECURITY.md).
+

treecf-0.3.2/README.md

@@ -0,0 +1,121 @@
+# treecf
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22069503.svg)](https://doi.org/10.5281/zenodo.22069503)
+[![PyPI](https://img.shields.io/pypi/v/treecf.svg)](https://pypi.org/project/treecf/)
+[![Python](https://img.shields.io/pypi/pyversions/treecf.svg)](https://pypi.org/project/treecf/)
+[![CI](https://github.com/wlazlod/treecf/actions/workflows/ci.yml/badge.svg)](https://github.com/wlazlod/treecf/actions/workflows/ci.yml)
+[![License](https://img.shields.io/pypi/l/treecf.svg)](LICENSE)
+
+**Constrained, threshold-aware counterfactual explanations for tree ensembles.**
+
+`treecf` answers the question: *"what is the minimal, feasible change to this instance such
+that the model's output lands in a target interval?"* — for XGBoost, LightGBM, CatBoost and
+scikit-learn tree ensembles.
+
+![Lever-set by feature matrix of a recourse menu: filled cells where a plan changes that lever, a square for a proved-optimal plan, a cross for a lever set certified unable to reach the target](https://raw.githubusercontent.com/wlazlod/treecf/main/docs/guide/img/plot_recourse_menu.png)
+
+> On [PyPI](https://pypi.org/project/treecf/). See the [documentation](https://wlazlod.github.io/treecf/) for concepts and tutorials.
+
+## Why another counterfactual package?
+
+- **Tree-native and fast.** Models are parsed into a shared tree IR and the constrained
+  search runs on a bundled Rust core, typically in milliseconds; every result is
+  float-verified against the parsed model before it is returned, and the parsers are
+  conformance-tested against the native library.
+- **Optional proofs, inside a measured envelope.** `backend="exact"` returns
+  `proof="optimal"` when no cheaper plan exists under the declared objective (weighted
+  distance, plus a per-feature term only if you set `sparsity_weight`), and a completed
+  search that finds nothing returns `Infeasible(proof="certified")`. Proofs scale with the
+  number of levers the search may move, not with the model's width: on the measured matrix
+  the refine search certifies up to 200 trees with 12 free features inside 60 s and no
+  20-feature model beyond the smallest one (50 trees at depth 3) — while on the 300-tree,
+  50-feature model a coalition of up to
+  three levers certifies in under half a second with `search="refine"`, so wide models get
+  proofs once the levers are restricted with `Freeze`, coalitions, or a `recourse_menu`. A
+  search that runs out of budget returns its best plan labelled `heuristic` and warns; it
+  never claims more.
+- **Recourse regions.** Any verified counterfactual widens into a certified box — "reduce
+  utilization below 0.40", not "to 0.3972" — with every point in the box provably in-target
+  and constraint-feasible; works with every backend.
+- **Real constraints.** Immutability, directionality, ranges, one-hot consistency, linear
+  inter-feature rules such as `max_dpd_30d <= max_dpd_12m`, and NaN as a legitimate value
+  with its own transition cost — declared once, enforced by every backend.
+- **Menus, diverse plans, certificates.** `recourse_menu` solves every lever set up to a
+  size and says which combinations provably cannot work; `explain_diverse` returns the
+  cheapest plans with distinct lever sets; `certificate` turns any result into a
+  self-contained JSON record a validator re-checks later.
+
+On a 120-tree model and 100 declined rows, treecf's plans cost a seventh of DiCE's at a fifth
+of the time; NICE is four times faster per instance, and its plans cost 2.7 times more and
+cannot take constraints. The measured tables and the honest reading are on the
+[benchmarks page](https://wlazlod.github.io/treecf/concepts/backends/#against-other-cf-libraries).
+
+Not for you if: the model is not a tree ensemble; you want sets of plans diverse by distance
+rather than by the levers they use (DiCE does that); you need a proof over dozens of free
+levers at once without restricting them (see the [proof envelope](https://wlazlod.github.io/treecf/concepts/certification/#the-proof-envelope-measured));
+or you need a frozen API — treecf is in beta, see
+[API stability](https://wlazlod.github.io/treecf/api-stability/).
+
+## Installation
+
+```bash
+pip install "treecf[xgboost,viz]"   # wheels for Linux, macOS, Windows; no Rust toolchain needed
+```
+
+numpy is the only Python dependency; the extras add a parser for your training library and
+the plots. JSON model dumps parse without the training library, so explanations can be
+generated on a scoring host that has neither it nor a solver.
+
+## Quick look
+
+`credit_demo()` returns a packaged credit model, background rows, and one declined
+applicant. It is new in this version; on an older installed package, substitute your own
+model, as the quickstart notebook does.
+
+```python
+from treecf import Explainer, Freeze, Monotone, Target
+from treecf.datasets import credit_demo
+
+model, X, x = credit_demo()
+target = Target.probability(range=(0.0, 0.05))
+exp = Explainer(
+    model, background=X,
+    constraints=[Freeze("occupation"), Monotone("tenure_months", "increase")],
+)
+
+res = exp.explain(x, target=target, seed=0)
+res.changes                          # {'income': (4678.0, 6932.4)}
+res.proof                            # 'heuristic'
+
+proved = exp.explain(x, target=target, backend="exact", region=True, seed=0)
+proved.proof                         # 'optimal'
+proved.region.describe()             # {'income': 'in [6.58e+03, 7.81e+03] (data-limited)',
+                                     #  'utilization': 'in [0.428, 0.541)', ...}
+
+menu = exp.recourse_menu(x, target=target, max_levers=2)
+menu.describe()["dpd_12m"]           # 'no acceptance is reachable by changing only dpd_12m'
+```
+
+## Learn more
+
+- [How it works](https://wlazlod.github.io/treecf/how-it-works/) — the pipeline from objective to verified answer.
+- [Certification](https://wlazlod.github.io/treecf/concepts/certification/) — what a proof covers and where it stops.
+- [Credit-risk walkthrough](https://wlazlod.github.io/treecf/notebooks/02-credit-risk-tutorial/) — a batch workflow end to end.
+- [probcal integration](https://wlazlod.github.io/treecf/guide/probcal/) — recourse against calibrated cutoffs.
+
+## Cite
+
+```bibtex
+@software{wlazlo_treecf,
+  author  = {Wlazło, Daniel},
+  title   = {treecf: constrained, threshold-aware counterfactual explanations for tree ensembles},
+  doi     = {10.5281/zenodo.22069503},
+  url     = {https://github.com/wlazlod/treecf},
+  license = {MIT}
+}
+```
+
+## Contributing and license
+
+MIT. See [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, the test layers, and the
+project's hard invariants; report security issues privately per [SECURITY.md](SECURITY.md).

{treecf-0.3.1 → treecf-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "treecf"
-version = "0.3.1"
+version = "0.3.2"
 description = "Constrained, threshold-aware counterfactual explanations for tree ensembles (XGBoost, LightGBM, CatBoost, sklearn) — fast Rust genetic search, exact optimality proofs, certified infeasibility, and recourse regions."
 readme = "README.md"
 license = { text = "MIT" }

{treecf-0.3.1 → treecf-0.3.2}/rust/Cargo.lock

@@ -419,7 +419,7 @@ checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
 
 [[package]]
 name = "treecf-core"
-version = "0.3.1"
+version = "0.3.2"
 dependencies = [
  "numpy",
  "pyo3",

{treecf-0.3.1 → treecf-0.3.2}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "treecf-core"
-version = "0.3.1"
+version = "0.3.2"
 edition = "2021"
 # f64::next_down (cells.rs) stabilized in 1.86; pyo3 0.29 needs 1.83
 rust-version = "1.86"

{treecf-0.3.1 → treecf-0.3.2}/src/treecf/__init__.py

@@ -31,7 +31,7 @@ from treecf.plausibility import Plausibility
 from treecf.regions import RecourseRegion
 from treecf.targets import Target
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"
 
 __all__ = [
     "AllowMissing",

{treecf-0.3.1 → treecf-0.3.2}/src/treecf/_menu.py

@@ -42,7 +42,7 @@ _MODES = ("minimal", "all")
 _CRITERIA = ("levers", "coalitions")
 _MENU_OPTIONS: dict[str, Any] = {
     "backend": "exact",
-    "search": "classic",
+    "search": "refine",
     "seed": None,
     "time_budget_s": None,
     "total_budget_s": None,

{treecf-0.3.1 → treecf-0.3.2}/src/treecf/api.py

@@ -221,7 +221,7 @@ def _calibrated_readout(target: Target, score_raw: float) -> float | None:
 _DEFAULT_WARM_START = True
 _DEFAULT_NODE_BUDGET = 2_000_000
 _DEFAULT_GAP = 0.0
-_DEFAULT_SEARCH = "classic"
+_DEFAULT_SEARCH = "refine"
 _DEFAULT_TIME_BUDGET_S = 10.0
 _SEARCH_MODES = ("classic", "refine")
 
@@ -574,12 +574,13 @@ class Explainer:
         additive rather than deducted from the budget. ``gap`` lets the exact
         search settle for a counterfactual within that relative fraction of
         the true optimum, reported through ``proof="optimal_within_gap"``.
-        ``search`` picks the exact engine: ``"classic"`` (the default)
-        assigns one candidate value per feature at a time; ``"refine"``
+        ``search`` picks the exact engine: ``"refine"`` (the default)
         first holds each numeric feature to a range of routing cells and
-        descends only where the score bound forces it, which proves the same
-        optimum and the same infeasibility certificates — often in far fewer
-        nodes on models with many thresholds per feature — though the row it
+        descends only where the score bound forces it; ``"classic"``
+        assigns one candidate value per feature at a time. Both prove the
+        same optimum and the same infeasibility certificates — the refine
+        search often in far fewer nodes on models with many thresholds per
+        feature, which is why it is the default — though the row the two
         returns may be a different argmin of the same cost.
 
         An exact search can return a feasible row with ``proof="heuristic"``
@@ -1196,11 +1197,13 @@ class Explainer:
         elapsed = time.monotonic() - start
 
         if res.stats["completed"] is False:
-            # the size of the space is computed only on this path: it costs a
-            # domain build, cheap next to an exhausted search
+            # the size of the space is computed only on this path, and without
+            # the presolve pass: sizing the presolved space means bracketing
+            # every candidate state through every tree in Python, which on a
+            # wide, deep model costs seconds after the budget already ended
             log10_states: float | None = None
             if cast(int, res.stats["nodes_expanded"]) >= node_budget or elapsed >= time_budget_s:
-                log10_states = cast(float, self._search_profile(x, interval)["log10_states"])
+                log10_states = cast(float, self._search_profile(x, None)["log10_states"])
             degradation = _degradation_for(
                 res, node_budget, time_budget_s, elapsed, seed, log10_states
             )
@@ -1453,7 +1456,7 @@ class Explainer:
         max_levers: int = 3,
         mode: str = "minimal",
         backend: str = "exact",
-        search: str = "classic",
+        search: str = "refine",
         seed: int | None = None,
         time_budget_s: float | None = None,
         total_budget_s: float | None = None,
@@ -1502,7 +1505,7 @@ class Explainer:
         backend
             ``"exact"`` (certifies) or ``"genetic"``.
         search
-            Exact search mode, ``"classic"`` or ``"refine"``.
+            Exact search mode, ``"refine"`` (the default) or ``"classic"``.
         seed
             Passed to every solve.
         time_budget_s
@@ -1733,7 +1736,11 @@ class Explainer:
         ``seed``/``node_budget``/``gap``/``time_budget_s``/``warm_start``/
         ``search`` are recorded under ``solve.declared`` when given: the
         result object does not carry them, so they are caller-supplied, and
-        the block's name makes that provenance explicit.
+        the block's name makes that provenance explicit. ``search`` is the one
+        exception: an exact result reports the engine that ran in its own
+        ``solver_stats``, so it is recorded there even when not given, and a
+        certificate never depends on the default of the release that issued
+        it.
 
         Parameters
         ----------
@@ -1758,7 +1765,7 @@ class Explainer:
             The warm-start setting the solve ran with, likewise.
         search
             The exact search mode (``"classic"`` or ``"refine"``) the solve
-            ran with, likewise.
+            ran with; taken from the result's ``solver_stats`` when omitted.
 
         Returns
         -------

{treecf-0.3.1 → treecf-0.3.2}/src/treecf/audit.py

@@ -485,6 +485,11 @@ def build_certificate(
         declared["warm_start"] = warm_start
     if search is not None:
         declared["search"] = search
+    elif "search" in result.solver_stats:
+        # an exact solve reports which engine ran; record it, so a certificate
+        # never leaves the engine to be inferred from the issuing release's
+        # default
+        declared["search"] = str(result.solver_stats["search"])
     solve: dict[str, object] = {
         "backend": _backend_of(result.solver_stats),
         "proof": result.proof,

treecf-0.3.2/src/treecf/datasets/__init__.py

@@ -0,0 +1,59 @@
+"""A packaged credit-shaped demo: a committed model, a background sample, one declined row.
+
+Every example in the documentation starts from ``credit_demo()``, so it runs
+as written on a fresh install without a training library. The model is a
+committed LightGBM JSON dump of a small synthetic credit-risk classifier over
+five features — ``income``, ``utilization``, ``dpd_12m``, ``tenure_months``,
+and a native categorical ``occupation`` — and the background rows follow a
+fixed synthetic recipe, so a given seed always returns the same data.
+"""
+
+from __future__ import annotations
+
+from importlib import resources
+
+import numpy as np
+import numpy.typing as npt
+
+from treecf.ir.model import EnsembleIR, apply_categories
+from treecf.ir.parsers import parse_model
+
+FloatArray = npt.NDArray[np.float64]
+
+OCCUPATIONS = ("student", "clerk", "manager", "retired")
+"""Display names of the demo model's ``occupation`` codes, in code order."""
+
+
+def credit_demo(seed: int = 7, n: int = 400) -> tuple[EnsembleIR, FloatArray, FloatArray]:
+    """The demo model, a background sample, and one declined applicant.
+
+    Parameters
+    ----------
+    seed
+        Seed of the background sample; the model itself is fixed.
+    n
+        Number of background rows.
+
+    Returns
+    -------
+    ``(model, X, x)``: the parsed model (an ``EnsembleIR`` with the
+    occupation names installed, accepted by ``Explainer`` directly), an
+    ``(n, 5)`` background matrix, and its second row, an applicant the
+    model scores well above a 5% default probability.
+    """
+    with resources.as_file(resources.files(__name__).joinpath("credit_model.json")) as path:
+        model = apply_categories(parse_model(str(path)), {"occupation": OCCUPATIONS})
+    rng = np.random.default_rng(seed)
+    X = np.column_stack(
+        [
+            rng.normal(loc=4200.0, scale=1600.0, size=n),  # income
+            np.clip(rng.beta(2.0, 3.5, size=n), 0.0, 1.0),  # utilization
+            np.floor(rng.exponential(scale=6.0, size=n)),  # dpd_12m
+            np.floor(rng.uniform(3, 240, size=n)),  # tenure_months
+            rng.integers(0, 4, size=n).astype(np.float64),  # occupation codes
+        ]
+    )
+    return model, X, X[1].copy()
+
+
+__all__ = ["OCCUPATIONS", "credit_demo"]