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"

License

MIT

Project links

Data verified by PyPI on Aug 23, 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 23, 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.2.4.tar.gz (186.3 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.4-cp311-abi3-win_amd64.whl (494.6 kB view details)

Uploaded CPython 3.11+Windows x86-64

treecf-0.2.4-cp311-abi3-musllinux_1_2_x86_64.whl (820.6 kB view details)

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

treecf-0.2.4-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (608.8 kB view details)

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

treecf-0.2.4-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (589.6 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

treecf-0.2.4-cp311-abi3-macosx_11_0_arm64.whl (553.2 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

treecf-0.2.4-cp311-abi3-macosx_10_12_x86_64.whl (569.5 kB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: treecf-0.2.4.tar.gz
  • Upload date:
  • Size: 186.3 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.4.tar.gz
Algorithm Hash digest
SHA256 f7cc785c8153d82595b4474c5f1b4325ff22c977fb5b35ba96edea63813c703e
MD5 93ebfd71dc519573f7b5ca72eb27dc14
BLAKE2b-256 795b24ee12105e83970e894dc409d67e5245694177f1c33582728fd39f085c1f

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: treecf-0.2.4-cp311-abi3-win_amd64.whl
  • Upload date:
  • Size: 494.6 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.4-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 922e71daa046b4db181a1160ed50ea79d2db34304ba8c63f774f4c2e113543fe
MD5 d3e32d4746e58ad37a550361ee059be5
BLAKE2b-256 708b7bcdb29fd7002d48b5754fc8927141ad1454c7ace0195825658e962bb300

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.2.4-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 86a4d22975dbb75f25c1bc5cd5e418002f37cc027f72901342906ea145da458e
MD5 c6d87958c799568fe80797429dfaffa6
BLAKE2b-256 bf996d428d4c7a26d59f2fc234c32b5fd25f33f8a8a17f7531c28e231b159709

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.2.4-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 a4beee16d7cf19231568c34b19ff067e2b168f3cda806c794cc97e72940dfbc6
MD5 5b3eedf9582f1e9bd060dcce9810a2dd
BLAKE2b-256 74d3f34ad25cafcd912bb886f4eede1d5c57788f20de85aa24698b8871ac3055

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.2.4-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 f26f84d3dff27a58ed4189613087b1bf4a6d9ca547a8715ce0adda0c944eb9a7
MD5 d1934fad233f762346dfda5c97d9b4dc
BLAKE2b-256 553eca0ba4c5c269e1739d431b3403373f18dd9636f4845cb70dd5425ece1d0c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.2.4-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 593dfaaaa49ef4bb3a2a8c4087ddf6201f65a5a3a6dce967e0fd46f1eb2481cb
MD5 13124a36d3e172ae176bc30211e7f341
BLAKE2b-256 54408564ac314b1364d2b66f96b0cf7181e502720b69271cec4b91af7e9f3c50

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.2.4-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 7b7990c850f28e34dcb19092d6cb55f1b75f6a85179ca4d3086be30c80fbd51a
MD5 188ce0d68e2d6d320fb80225054e0d80
BLAKE2b-256 33c7574d5071422b6bcd1be0ae0a34c75d6d395325513ccb48f85853fbf3c9be

See more details on using hashes here.

Provenance

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

This release

0.2.4 This release

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