treecf

DOI

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.

On PyPI. See the documentation 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.
  • Optional optimality proof. backend="exact" branch-and-bounds the same candidate grid; on the standard bench model (30-tree/8-feature XGBoost) it proves the cheapest counterfactual in a median 0.24s versus 0.005s for the genetic heuristic, closing a median 14.33% cost gap the heuristic leaves on the table — measured on a 4-core dev machine (scripts/bench_exact.py).
  • Certified "no". A completed exact search returns Infeasible(proof="certified") — "no recourse exists within these constraints" becomes a provable statement, not a shrug after a timeout.
  • Recourse regions. Any verified counterfactual widens into a certified box — "reduce utilization to ≤ 0.40", not "to 0.3972" — with every point in the box provably in-target and constraint-feasible; works with every backend.
  • 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

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

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)

proved = exp.explain(x, target=t, backend="exact")      # proof="optimal", a certified "no", or a warned degrade
boxed = exp.explain(x, target=t, region=True)            # res.region.describe() -> "utilization <= 0.4"

Contributing

See CONTRIBUTING.md for dev setup, the test layers, and the project's hard invariants; report security issues privately per SECURITY.md.

License

MIT

Project links

Data verified by PyPI on Sep 6, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for wlazlod from gravatar.com wlazlod

Credits

Author: Daniel Wlazlo

GitHub Statistics

Data verified by PyPI on Sep 6, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.11

Provides Extra

all catboost dev docs lightgbm sklearn test viz xgboost

Tags

counterfactual xai interpretability recourse gbdt xgboost lightgbm catboost credit-risk

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

treecf-0.3.1.tar.gz (279.4 kB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

treecf-0.3.1-cp311-abi3-win_amd64.whl (654.3 kB view details)

Uploaded CPython 3.11+Windows x86-64

treecf-0.3.1-cp311-abi3-musllinux_1_2_x86_64.whl (970.2 kB view details)

Uploaded CPython 3.11+musllinux: musl 1.2+ x86-64

treecf-0.3.1-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (758.3 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ x86-64

treecf-0.3.1-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (731.8 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

treecf-0.3.1-cp311-abi3-macosx_11_0_arm64.whl (694.2 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

treecf-0.3.1-cp311-abi3-macosx_10_12_x86_64.whl (718.3 kB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

Details for the file treecf-0.3.1.tar.gz.

File metadata

  • Download URL: treecf-0.3.1.tar.gz
  • Upload date:
  • Size: 279.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for treecf-0.3.1.tar.gz
Algorithm Hash digest
SHA256 72b209f1b13dff7bf072a2ab15d4f1a9e3e7bf821285e4c5e550d92c75e3cd87
MD5 b719cbfed1552b91082da9f8ce0ce987
BLAKE2b-256 40a674db479cccecec62103580da505ae109068915181b75d833788f5e2cd4e2

See more details on using hashes here.

Provenance

The following attestation bundles were made for treecf-0.3.1.tar.gz:

Publisher: release.yml on wlazlod/treecf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treecf-0.3.1-cp311-abi3-win_amd64.whl.

File metadata

  • Download URL: treecf-0.3.1-cp311-abi3-win_amd64.whl
  • Upload date:
  • Size: 654.3 kB
  • Tags: CPython 3.11+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for treecf-0.3.1-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 c6625915dc60b5ed5de3e7374cabe13e4a1d69d337252180ffeb41179e9ad5af
MD5 bff09facdb07f9c904b8de42fc531be1
BLAKE2b-256 5cdd789259257a6ddfb6426be614fc151a0fb9da0872aa77b5aee08f8c78f6c6

See more details on using hashes here.

Provenance

The following attestation bundles were made for treecf-0.3.1-cp311-abi3-win_amd64.whl:

Publisher: release.yml on wlazlod/treecf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treecf-0.3.1-cp311-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for treecf-0.3.1-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 1c834132d5f85369516f65ecfec9f171015da5c494733ccaa2787f95b318cad4
MD5 d1dc3bc2b95d8f7bbe3d36b5e403fadc
BLAKE2b-256 9a32275091e8dd948d3b961934bd174aeaaadfd6e2f1eae8ca2442935206cc1a

See more details on using hashes here.

Provenance

The following attestation bundles were made for treecf-0.3.1-cp311-abi3-musllinux_1_2_x86_64.whl:

Publisher: release.yml on wlazlod/treecf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treecf-0.3.1-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for treecf-0.3.1-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 be4ec9ee9a7f7105c2b8b836013d4b8c91019d2c8c66db0fcbeb6313d704d0b3
MD5 bf24ce1a5f508c6563bec04240c4a6c5
BLAKE2b-256 0e51c3165fcb7859cdc3ac3e115efdef5eee6a21c108b261958e56eb1f119151

See more details on using hashes here.

Provenance

The following attestation bundles were made for treecf-0.3.1-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on wlazlod/treecf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treecf-0.3.1-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for treecf-0.3.1-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 daa96050160e6fca7467209af0b4acf5d95f3f94b60f06695cdc23d900751c95
MD5 98de5996a8567c5a8fc2a99cd6acd9da
BLAKE2b-256 f3543157498fd4b6e7cc3fe73e6d9eb0e1aa1ed0977f8f1ace4b036db8d9071a

See more details on using hashes here.

Provenance

The following attestation bundles were made for treecf-0.3.1-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on wlazlod/treecf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treecf-0.3.1-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for treecf-0.3.1-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 4ad191147059aef75dcfc7d3b3d7786730d3c9dcc33f66dedf933880bce63d23
MD5 7fe8da65cb7b99c47df6e7809634dbb1
BLAKE2b-256 e07f5d95d2035ae1ccfe59d7181cb16a806cc39119bb386f9f494962c0988641

See more details on using hashes here.

Provenance

The following attestation bundles were made for treecf-0.3.1-cp311-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on wlazlod/treecf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file treecf-0.3.1-cp311-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for treecf-0.3.1-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 fec754bdfe9362031a6b09e3ac471505956a70b696c89edfea477b29d811aa0f
MD5 6cffa9c6e8b38f6af27998b4015755b9
BLAKE2b-256 80fd8cee42bc8780b851fadff9b0a82940329192459d73c4e957d52c11dea853

See more details on using hashes here.

Provenance

The following attestation bundles were made for treecf-0.3.1-cp311-abi3-macosx_10_12_x86_64.whl:

Publisher: release.yml on wlazlod/treecf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.3.1 This release

7 files

0.3.0

7 files

0.2.4

7 files

0.2.3

7 files

0.2.2

7 files

0.2.1

7 files

0.2.0

7 files

0.1.1

7 files

0.1.0

7 files

0.0.1

7 files

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