treecf 0.3.0__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.0 → treecf-0.3.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "treecf"
-version = "0.3.0"
+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.0 → treecf-0.3.2}/rust/Cargo.lock

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

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

@@ -1,6 +1,6 @@
 [package]
 name = "treecf-core"
-version = "0.3.0"
+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.0 → treecf-0.3.2}/rust/src/exact/domains.rs

@@ -12,7 +12,7 @@ use crate::ir::Ensemble;
 /// Python's `<`-based ordering: `-0.0` and `0.0` compare equal, so a stable sort
 /// leaves them in insertion order. Costs and sort values are never NaN here.
 #[inline]
-fn py_cmp(a: f64, b: f64) -> std::cmp::Ordering {
+pub(crate) fn py_cmp(a: f64, b: f64) -> std::cmp::Ordering {
     use std::cmp::Ordering;
     if a < b {
         Ordering::Less

{treecf-0.3.0 → treecf-0.3.2}/rust/src/exact/mod.rs

@@ -11,6 +11,8 @@
 //! | `treecf.backends._exact_domains` (+ the `treecf.api._snap` it calls) | `domains` |
 //! | `treecf.backends._exact_propagation` | `propagation` |
 //! | `treecf.backends._exact_orderpairs` | `orderpairs` |
+//! | `treecf.backends._exact_refine` | `refine` |
+//! | `treecf.backends._exact_trace` | `trace` |
 //!
 //! Those five Python files carry the bit-parity contract in their own headers;
 //! every module here follows its counterpart line for line, so the operation
@@ -72,13 +74,16 @@
 pub(crate) mod domains;
 pub(crate) mod orderpairs;
 pub(crate) mod propagation;
+pub(crate) mod refine;
 pub(crate) mod search;
 #[cfg(test)]
 pub(crate) mod test_support;
+pub(crate) mod trace;
 
 pub use crate::interrupt::SearchOutcome;
 pub use domains::constraint_cells;
-pub use search::{solve_exact, ExactParams, ExactResult, ExactStats};
+pub use search::{solve_exact, ExactParams, ExactResult, ExactStats, SearchMode};
+pub use trace::TraceSample;
 
 /// Per-feature snapping rule for values that move. Mirrors `treecf.api.ValuePolicy`
 /// minus the callable case (rejected before marshaling) and minus `"raw"` (`None`).

{treecf-0.3.0 → treecf-0.3.2}/rust/src/exact/propagation.rs

@@ -2,6 +2,7 @@
 //! port of `treecf.backends._exact_propagation`. Parity rules in the module
 //! header of `super` govern this file too.
 
+use crate::cells::Cell;
 use crate::constraints::Constraints;
 use crate::exact::domains::State;
 
@@ -29,15 +30,30 @@ pub(crate) struct Propagation<'a> {
     pub(crate) zeros: Vec<usize>,
 }
 
+/// Whether a demanded value can still be met inside an interval; a missing
+/// value never can, since an interval holds numbers only.
+fn range_contains(rng: &Cell, value: f64) -> bool {
+    !value.is_nan() && rng.contains(value)
+}
+
+/// A feature held to a whole interval (`ranges[f]` set) has no value to compare
+/// a demand against: the demand is checked for containment and then recorded,
+/// exactly as for an undecided feature, so the point the feature is later
+/// narrowed to is held to it.
 fn force(
     forced_value: &mut [Option<f64>],
     frame: &mut PropFrame,
     assigned: &[bool],
     values: &[f64],
+    ranges: &[Option<Cell>],
     f: usize,
     value: f64,
 ) -> bool {
-    if assigned[f] {
+    if let Some(rng) = ranges.get(f).copied().flatten() {
+        if !range_contains(&rng, value) {
+            return false;
+        }
+    } else if assigned[f] {
         return values[f] == value;
     }
     if let Some(current) = forced_value[f] {
@@ -82,6 +98,19 @@ impl<'a> Propagation<'a> {
         v: f64,
         assigned: &[bool],
         values: &[f64],
+    ) -> (PropFrame, bool) {
+        self.apply_with(j, v, assigned, values, &[])
+    }
+
+    /// `apply` for a search that also holds features to whole intervals; an
+    /// empty `ranges` slice is what the classic search passes.
+    pub(crate) fn apply_with(
+        &mut self,
+        j: usize,
+        v: f64,
+        assigned: &[bool],
+        values: &[f64],
+        ranges: &[Option<Cell>],
     ) -> (PropFrame, bool) {
         let mut frame = PropFrame::default();
         if let Some(forced) = self.forced_value[j] {
@@ -117,6 +146,7 @@ impl<'a> Propagation<'a> {
                     &mut frame,
                     assigned,
                     values,
+                    ranges,
                     last,
                     1.0,
                 ) {
@@ -132,6 +162,7 @@ impl<'a> Propagation<'a> {
                     &mut frame,
                     assigned,
                     values,
+                    ranges,
                     cons_index as usize,
                     cons_value,
                 )