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 15, 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 15, 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.1.tar.gz (176.0 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.1-cp311-abi3-win_amd64.whl (483.2 kB view details)

Uploaded CPython 3.11+Windows x86-64

treecf-0.2.1-cp311-abi3-musllinux_1_2_x86_64.whl (808.0 kB view details)

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

treecf-0.2.1-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (596.3 kB view details)

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

treecf-0.2.1-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (577.4 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

treecf-0.2.1-cp311-abi3-macosx_11_0_arm64.whl (542.1 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

treecf-0.2.1-cp311-abi3-macosx_10_12_x86_64.whl (558.1 kB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: treecf-0.2.1.tar.gz
  • Upload date:
  • Size: 176.0 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.1.tar.gz
Algorithm Hash digest
SHA256 183f085e0acc73d62884da1cdaf3aa0df37383d8bc87de2088a27f70ad44c415
MD5 1ee598eb8af6599e42ee14cd5dcc1b55
BLAKE2b-256 3ca90adebaa88d6ecf8e5dab6166dc2bc24ada3a0c1a8e29649853b1c22594f6

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: treecf-0.2.1-cp311-abi3-win_amd64.whl
  • Upload date:
  • Size: 483.2 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.1-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 3abe4b9cf48f616c80b1a1ba2896ca0800500bbda31a7391ba1b36654b92e806
MD5 27d10c7b54e714c42e1f5f97fbb5c7c7
BLAKE2b-256 bfbd2d428a72b82347b3bcf545b65c8047e2333256e5574bf4df89d289b3ed00

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.2.1-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 89f450a5c777eac49a89c67ba6d79366e3b3c835d08e5be012b4fe06e7fdbe50
MD5 e68d9984c6d8605f4154cda0b3d7310d
BLAKE2b-256 b83e7eb2c12327616f675692541ba454d554f4ae5e02205cb89d1a7b70cd611b

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.2.1-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 0ef92931077ed6121c4b80cc7e742b3c4df19356f289e01c7999efcc26f9f789
MD5 3e1abbdd171c107cb2c55ce257845e1c
BLAKE2b-256 69cf4f9e276d1f0f11cf14c82a9a9ae7739a15acd2673b96be8676241a965c1f

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.2.1-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 6698fe02731484b71d71853f5e79904b8e8bbbe8ff7a5136c678dfdde92e8dfa
MD5 4fc92a2603bca735cbb687e78251af0b
BLAKE2b-256 c348bc49028df986de7b61bd0134691d88832412c17fbef6ad3d10b7b6ed87a8

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.2.1-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 ab055a4db763efa96fa74726d405ada79599c6f99202e4f1f50df74c31a22d8f
MD5 0c6a28b4aa5124d7b274fbdc85fc9fe4
BLAKE2b-256 194d2b5041af216b10e84e6f2e731fea1f268b2a9257979bd91c3f216bd05ca5

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.2.1-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 6a747d2f5f3340ebbdacedd011e1d3d709c5b18c9c8dbc68dec99add8eecd50e
MD5 1b322403d4d7527b85c15d4d4976f8fd
BLAKE2b-256 1eed6c7a22f4e0a46fcfc4b08651dc6cc2ea1d47cf6b8715f0d841b512a0c9ad

See more details on using hashes here.

Provenance

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

This release

0.2.1 This release

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