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: v0.1.0 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).
  • 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)

License

MIT

Project links

Data verified by PyPI on Aug 14, 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 14, 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.0.tar.gz (153.1 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.0-cp311-abi3-win_amd64.whl (461.5 kB view details)

Uploaded CPython 3.11+Windows x86-64

treecf-0.2.0-cp311-abi3-musllinux_1_2_x86_64.whl (786.2 kB view details)

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

treecf-0.2.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (574.9 kB view details)

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

treecf-0.2.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (556.0 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

treecf-0.2.0-cp311-abi3-macosx_11_0_arm64.whl (521.5 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

treecf-0.2.0-cp311-abi3-macosx_10_12_x86_64.whl (537.5 kB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: treecf-0.2.0.tar.gz
  • Upload date:
  • Size: 153.1 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.0.tar.gz
Algorithm Hash digest
SHA256 b5a15f165a4332dffd1e50cf7c71cdacac3b25f9c101a8e10149e86cddf2a42e
MD5 34257f92999e674280d1851fe9322ce6
BLAKE2b-256 03b2e14be0878170e21a20e3349c059048b5fdcbc4fecca7fc0b4a4d1d57501a

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: treecf-0.2.0-cp311-abi3-win_amd64.whl
  • Upload date:
  • Size: 461.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.0-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 ed51a89284c326a0c9f9929651d9c41e09ec5bd66dbb09374756fef4c094066e
MD5 424b95c1da6eb9697f6eba7b7f224169
BLAKE2b-256 78a8669e901b6d6bea84a102ad8f3a453268313f1b6724dfd3d00a71f94c8257

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.2.0-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 a956179ea6e5b754cb428c2635bb53948da1e96c2d3ee6f83bbcac330add74a7
MD5 9fd967c11ce958c4ed5cdcb83572b87d
BLAKE2b-256 c93d73a0526b946ca1dfaca116adb585d6f85f4b4c39498e8c91649c340e6d28

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.2.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 28bb2733d89a94ebe8e1690062818385aaf648448d32ee02c61c62095deb49a5
MD5 e868ea486bfaabd91c35be1d09c99cea
BLAKE2b-256 06306b329ed23fd9a627f7f9fcd2be3124d545e99f858128adbe36fb1e8cf109

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.2.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 8318988036241c287e931aa878ae6001ee405a6a91d325bd2760c6e035cd3885
MD5 2cdb18e7fd0f987195874e0c571dc425
BLAKE2b-256 ff5ee5409a5c29c254e852d9b947344796d18f5beb735235bc79743d51a1edca

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.2.0-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 36ebb0e987e0644edd7880da4eb647d0a4e8bfe06febe4981b07fc421bc2a465
MD5 06179cd2c99f9a2efc33d71c8e4069ad
BLAKE2b-256 4da845c4dd1fe6c01101aac2fe27bc520d3f3073a6a3d7587752bce8d80e59c0

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.2.0-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 ab1ef4095a9ae086c33121b99d479f57b636e586b1123f41a760713f532ba4ff
MD5 4e4ef5f21ec40a5b528254da81bbe5f0
BLAKE2b-256 d098e9b4bf414e4dcb091cafdb7a649453597a9f6bad5fb5164257f50e04c323

See more details on using hashes here.

Provenance

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

0.2.2

7 files

0.2.1

7 files

This release

0.2.0 This release

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