Metadata-Version: 2.4
Name: treecf
Version: 0.0.1
Classifier: Development Status :: 3 - Alpha
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: 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: 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: viz
Provides-Extra: xgboost
License-File: LICENSE
Summary: Constrained, threshold-aware counterfactual explanations for tree ensembles (XGBoost, LightGBM, CatBoost, sklearn) on a bundled Rust genetic engine.
Keywords: counterfactual,xai,interpretability,recourse,gbdt,xgboost,lightgbm,catboost,cp-sat,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

**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 raw output lands in a target interval?"* — for XGBoost, LightGBM, CatBoost
and scikit-learn tree ensembles.

> Status: pre-release (v0.1). 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; the constrained
  genetic search runs on a bundled **Rust core** 44–58× faster than the equivalent numpy
  implementation (see the "Backends and proofs" docs page; the pure-Python engine remains
  available as `backend="python"`), and every result is float-verified against the IR
  before it is returned.
- **Decision thresholds are first-class.** Targets are intervals on the raw model output —
  custom probability cutoffs, regression targets, and whole rating-grade ladders in one call.
- **Real-world constraints.** Declarative layer for immutability, directionality, ranges,
  one-hot consistency, and arbitrary linear inter-feature constraints such as
  `max_dpd_30d <= max_dpd_12m` — compiled once, enforced by every backend.
- **Missing values are values.** NaN can be a legitimate counterfactual state, with
  per-feature opt-in and explicit transition costs.
- **Constraint mining.** Candidate invariants are mined from data and presented for human
  review — never auto-applied.

## Installation

```bash
pip install treecf              # bundled Rust engine; numpy is the only Python dep
pip install "treecf[xgboost]"   # model parsers as extras; JSON dumps work without them
pip install "treecf[viz]"       # matplotlib plots
```

## Quick look

```python
from treecf import Explainer, Target, constraint, Freeze

exp = Explainer(
    model="model.json",                       # native object or dump file
    background=X_train_sample,
    constraints=[
        constraint("max_dpd_30d <= max_dpd_12m"),
        Freeze("age_of_bureau_file"),
    ],
)
res = exp.explain(x, target=Target.probability(range=(0.0, 0.04)), seed=0)
```

## License

MIT

