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.
  • 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 8, 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 8, 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.1.1.tar.gz (71.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.1.1-cp311-abi3-win_amd64.whl (329.0 kB view details)

Uploaded CPython 3.11+Windows x86-64

treecf-0.1.1-cp311-abi3-musllinux_1_2_x86_64.whl (657.6 kB view details)

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

treecf-0.1.1-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (445.8 kB view details)

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

treecf-0.1.1-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (435.6 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

treecf-0.1.1-cp311-abi3-macosx_11_0_arm64.whl (405.5 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

treecf-0.1.1-cp311-abi3-macosx_10_12_x86_64.whl (414.6 kB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: treecf-0.1.1.tar.gz
  • Upload date:
  • Size: 71.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.1.1.tar.gz
Algorithm Hash digest
SHA256 b4338ca6b15cf0d9c25fccc983d277b275dfd07f96b9daac63394c0ee09c5dee
MD5 7b90813f0777ea9679f34b432bae82d3
BLAKE2b-256 fc9fd86c3f6f872f379176a711bcd5f172ee093072d1a56686af05cc829ca77d

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: treecf-0.1.1-cp311-abi3-win_amd64.whl
  • Upload date:
  • Size: 329.0 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.1.1-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 d722f3dc0342163f7a4d21d218ad73efdf052214960f7b494f605a0dc0f72e5d
MD5 5bdc4a2842913965a6d6eab928f8d5d8
BLAKE2b-256 a1fd40d765f4859e247230cc2e8311dfbd4fc3c52315940afafecd66359e9e8c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.1.1-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 9999fc33c526dc544e78684eb81236f1a40fb6cbd88d3043dcf10540679d6af4
MD5 f0c3b35507abb1547d76246e9813a284
BLAKE2b-256 5d06775110270907b022d4750a50946da19d75039a35b16e7cda19388fb998a9

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.1.1-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 fb479da5db47ea7daf220c4a21c4b1f50fe58d47c802c34671549ee5e4727673
MD5 81531b4b03cb3a7e70c117bbe0d5694b
BLAKE2b-256 9b9fb4d856aab2536a78467e3eab2ccb62173b52f33a2fe6fb49d9fd179afb35

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.1.1-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 8078cd98405618f234196210b0ec009dd11b43803c74aa4239d2c88bd729e819
MD5 cee56d3c73a6693e23b362cc94d1ce3e
BLAKE2b-256 19c2cc531a56ea99567d6195ba8fccfbceabdfc239319dd5231fb26fef2b1535

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.1.1-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 338905fb6217434b3240b730ed7ff2977ecd62d1029ed2d7a2f0e94d352032a5
MD5 1cfb7dd590329015be13da482bd44b59
BLAKE2b-256 c47524aff27c96e813de2ad2500fad6e3e444e959dd5f98dfb4a7e3cf8b532d5

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.1.1-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 b89a639fed45a686302d61c0568fd0d78cfa99055316901236b7bd5c16caf116
MD5 d1c74be9b1a74f6964adcf3937b590e7
BLAKE2b-256 54edeb6a4ab303ffe2981f394ee58bff0519902baf2f82fb3f4b69bf71041987

See more details on using hashes here.

Provenance

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

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

0.2.0

7 files

This release

0.1.1 This release

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