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 Aug 31, 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 31, 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.0.tar.gz (220.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.3.0-cp311-abi3-win_amd64.whl (556.5 kB view details)

Uploaded CPython 3.11+Windows x86-64

treecf-0.3.0-cp311-abi3-musllinux_1_2_x86_64.whl (875.8 kB view details)

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

treecf-0.3.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (664.2 kB view details)

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

treecf-0.3.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (641.0 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

treecf-0.3.0-cp311-abi3-macosx_11_0_arm64.whl (607.3 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

treecf-0.3.0-cp311-abi3-macosx_10_12_x86_64.whl (625.7 kB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: treecf-0.3.0.tar.gz
  • Upload date:
  • Size: 220.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.3.0.tar.gz
Algorithm Hash digest
SHA256 4ea3da2dae5ff5c94f7d493006684bd29b24d446cdcd897b1e07599ee2ace771
MD5 0402b29f60e274f667868101930757d5
BLAKE2b-256 5f0ac1dca748f37d0ff7fc9429fd4d147a037a74160b4375968e0fcc2299bc29

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: treecf-0.3.0-cp311-abi3-win_amd64.whl
  • Upload date:
  • Size: 556.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.3.0-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 85e0d72bceb3169eaa665dea842e16491487db0e94c387dfb64cbcda62942895
MD5 5a5fed4eb7c1bed5b21a1ec4cedcd77c
BLAKE2b-256 16ed7fc0ea10e7d1a44f9d57f515dd07ee6131c94623bd619a05d82843abeaa0

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.3.0-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 54ce4cd6be97ade64d5fc3dfb17383ede917e6726e8a009fd9e5cbf80d9b39e7
MD5 de0de20adc2a04de17730dcd813c8819
BLAKE2b-256 11b55303723a0fbcb9221a815b083946de5680d958aea64b95a3f007961fc752

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.3.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 fc551adc9ad52165bf99b6fd99efab8844611b3bdb085096f6d16694b855a4bd
MD5 1d989507949d75942e46b9190d9bc267
BLAKE2b-256 0d56f4c6ed48159289b555fef6b6ff42888ed7c51aee56033339e0f565e493d9

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.3.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 1fe1ccd9d11172fbfad7517115dac244b57825368ab958eaefa2e1bbb27a43ce
MD5 365aca571dd6ec97bf0b5602d8880ab8
BLAKE2b-256 ae07f3931cf5ba4b39037ae119c07d137d61d1352be1133a3b7784fea6a97bb5

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.3.0-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 613af8a9d146020ade804a69c0a18a395504333037f3448cb05aaedb3485395b
MD5 2b99ba1f5f280d9e7f5bb58feb942481
BLAKE2b-256 805e44085ec66cd9239f9f13461756587cdf26683c8dfef633ba35bb36e902cc

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.3.0-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 0e0093d68bdf847b10041ab3d401176fbb4b3ca514d3de329ad798f68db54728
MD5 4b876447392afbb26070a7d1f85ca2bf
BLAKE2b-256 a1d344b2bb3ba7d9c10ee2b13ef845d1c9bf3f68383b9c77cf4c207078a2c120

See more details on using hashes here.

Provenance

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

This release

0.3.0 This release

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