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.

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"

License

MIT

Project links

Data verified by PyPI on Aug 18, 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:
Newer release available (0.3.1)

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 Aug 18, 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 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.2.2.tar.gz (183.2 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.2.2-cp311-abi3-win_amd64.whl (491.5 kB view details)

Uploaded CPython 3.11+Windows x86-64

treecf-0.2.2-cp311-abi3-musllinux_1_2_x86_64.whl (816.2 kB view details)

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

treecf-0.2.2-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (604.6 kB view details)

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

treecf-0.2.2-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (585.6 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

treecf-0.2.2-cp311-abi3-macosx_11_0_arm64.whl (550.1 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

treecf-0.2.2-cp311-abi3-macosx_10_12_x86_64.whl (566.2 kB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

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

File metadata

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

File hashes

Hashes for treecf-0.2.2.tar.gz
Algorithm Hash digest
SHA256 6af125808d22292cf9c43fbeea40680f6989bea18da4215b633942a7d67609df
MD5 379e75bb8f1cf5b03a94e84c3a468215
BLAKE2b-256 899c32a8a72ba1c9ad5a53fa6712302a905917b907ba3870eb489719534654ca

See more details on using hashes here.

Provenance

The following attestation bundles were made for treecf-0.2.2.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.2.2-cp311-abi3-win_amd64.whl.

File metadata

  • Download URL: treecf-0.2.2-cp311-abi3-win_amd64.whl
  • Upload date:
  • Size: 491.5 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.2.2-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 e889dab7aac97dc4af20423c1138d9ec4b07646aae296f34ca6b2da6130e3644
MD5 f0607b774ccf28db9ebdec5deaad7307
BLAKE2b-256 358fbbfc2af21cf21d763f70fd0b18619d0b52ea0c9cd00c2173923ec0c7de55

See more details on using hashes here.

Provenance

The following attestation bundles were made for treecf-0.2.2-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.2.2-cp311-abi3-musllinux_1_2_x86_64.whl.

File metadata

File hashes

Hashes for treecf-0.2.2-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 b9bbeb9cbc15f2e3148390672e987f1267d321c355fc21e3fdcc28f3f4b8cb70
MD5 2528b12b791e8b8383e9ad83ed5f7687
BLAKE2b-256 3995a0f8057c6bde828a877c6008b2ff593786ecd80a6da6ad6e58027bb24f7c

See more details on using hashes here.

Provenance

The following attestation bundles were made for treecf-0.2.2-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.2.2-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for treecf-0.2.2-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 8bae474a08619fc92b18d617907a6653b41aa9f96e4be754cf01c78119c2d4c4
MD5 f9e5c221960009f86a45ffddfc29ed8a
BLAKE2b-256 643e5f6a868689f715581e6c94ed2b50abcfdd1d67ee260e2c9b3b468e369269

See more details on using hashes here.

Provenance

The following attestation bundles were made for treecf-0.2.2-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.2.2-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for treecf-0.2.2-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 0ccf6798b5c2b815e96fe6cbf7debb2cd7efee00bd1bf947725ce43467455e05
MD5 baf59019e0484d5b35e9ac0cf01c4c96
BLAKE2b-256 998e3bff0ab7860ea216b0e0b9b99651fbc48004cc3cc4b26183f0464187faf3

See more details on using hashes here.

Provenance

The following attestation bundles were made for treecf-0.2.2-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.2.2-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for treecf-0.2.2-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 6f61b4b12c65fcbd45f775bd115b502420af4ffef24b1ba8c4c90580d4cd71ec
MD5 37dcf65ba6f0228b1caa2445552eac51
BLAKE2b-256 df3239ada2d6114ce523342fbba0373492a07b507f75efb26b40882cafa1dc11

See more details on using hashes here.

Provenance

The following attestation bundles were made for treecf-0.2.2-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.2.2-cp311-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for treecf-0.2.2-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 c3f5ecf649fac1d8148a91e75a0e929c876ae77acef5b67c34016b7f1208a76d
MD5 93aa15589347d419f51b9b62c70bef74
BLAKE2b-256 5bc4c70e5f10574631056826a8ef30e36565e4e36d8b65e86ffd0f71a4873672

See more details on using hashes here.

Provenance

The following attestation bundles were made for treecf-0.2.2-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

0.3.1

7 files

0.3.0

7 files

0.2.4

7 files

0.2.3

7 files

This release

0.2.2 This release

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