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 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 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.3.tar.gz (183.9 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.3-cp311-abi3-win_amd64.whl (492.1 kB view details)

Uploaded CPython 3.11+Windows x86-64

treecf-0.2.3-cp311-abi3-musllinux_1_2_x86_64.whl (818.1 kB view details)

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

treecf-0.2.3-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (606.3 kB view details)

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

treecf-0.2.3-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (587.1 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

treecf-0.2.3-cp311-abi3-macosx_11_0_arm64.whl (550.8 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

treecf-0.2.3-cp311-abi3-macosx_10_12_x86_64.whl (566.7 kB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: treecf-0.2.3.tar.gz
  • Upload date:
  • Size: 183.9 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.3.tar.gz
Algorithm Hash digest
SHA256 4841968fc367a7dc36183bdf403113454e422d3fc9b31bd09a8fe776f51b81c5
MD5 d12ab0d071ca28972d32b95c6162699b
BLAKE2b-256 9ef32188c620fc6a8e986549c8b20af5bdaa3914584ed4b013527bf76112588f

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: treecf-0.2.3-cp311-abi3-win_amd64.whl
  • Upload date:
  • Size: 492.1 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.3-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 8fd2c1ecfc40fc48a18e89bbfce973684753d2ff6f224ebf8540abef2f2210ed
MD5 b4607cb0a673080943691bfa536f3a84
BLAKE2b-256 b667b93f0b36cae23a68a3bd7e73c3af881dea884bf1d5aea6c21237cff11a7c

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.2.3-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 c46984c9e917681b2c7ef8ae3e4d380feec55328e56c46b4c34fa815c9cda105
MD5 2bac4f970d70b7036d592765e3b12ad2
BLAKE2b-256 cb5a4eb7b86e33a62ea18bc07b6428d353996a09e80966f596186a8763f60cd5

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.2.3-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 3c3f63e99288054d0d5d78f931e4ce80bd1efe62b640ee183a4921705b4ede8c
MD5 c35a3b549491ae79b0711842311f89ab
BLAKE2b-256 89a04a88693773aba737e989289fd63e169943776a2a042c1cc07b47abd7faef

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.2.3-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 419da2063a4921fc01044c66fbbe8bf571c3705386a6554a4e1ff7371512762e
MD5 a58293ce83f10ee092cda6943712dc72
BLAKE2b-256 83220ecb783c623b4afbf9c68610167ec9333f6ef4fb7d511a0f1a14c0e4403f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.2.3-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 6e1a3315abd420686efe6a493303ca91918c903ea6a502f9d4a613581b424d4d
MD5 2e967259baa959d758d209a7098e4719
BLAKE2b-256 87e6d7a82d3cbfa5def8159a38b9b3937a1644118d1acef686484942c02384a0

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.2.3-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 24e1192f4f609625a0ad6479538386d176762f7a956ebe0d6a19b5de982f8bb8
MD5 88bf1e3aba2f5285117bcf66e8094be2
BLAKE2b-256 7be037b21f996bf75f1394075255d2831193af1b3fa9d20f8550ec0976f78438

See more details on using hashes here.

Provenance

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

This release

0.2.3 This release

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