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: early pre-release — v0.0.1 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 Jul 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 Jul 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.1.0.tar.gz (68.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.1.0-cp311-abi3-win_amd64.whl (325.7 kB view details)

Uploaded CPython 3.11+Windows x86-64

treecf-0.1.0-cp311-abi3-musllinux_1_2_x86_64.whl (654.2 kB view details)

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

treecf-0.1.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (442.7 kB view details)

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

treecf-0.1.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (432.7 kB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

treecf-0.1.0-cp311-abi3-macosx_11_0_arm64.whl (402.4 kB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

treecf-0.1.0-cp311-abi3-macosx_10_12_x86_64.whl (411.3 kB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

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

File metadata

  • Download URL: treecf-0.1.0.tar.gz
  • Upload date:
  • Size: 68.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for treecf-0.1.0.tar.gz
Algorithm Hash digest
SHA256 5c61a835e76524db51149ff433400fc06c28eb83511a5a38edfe02576e26780f
MD5 7f76b593f3cb604092134aac75fc9493
BLAKE2b-256 1b1fe44ce724f1f445ded8f9de6a2636707354cb676c3a83b08ca6ca7fb23f48

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: treecf-0.1.0-cp311-abi3-win_amd64.whl
  • Upload date:
  • Size: 325.7 kB
  • Tags: CPython 3.11+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for treecf-0.1.0-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 d8d5a56f5eaa84afa083175836b5785c046584a1dc4ca8cca750c49684bd9f99
MD5 7e5074844ad7e41da17cecd3fa10a549
BLAKE2b-256 c215d5b977084e912d5521c11af84d27b895a1f7194c0d3e4b2140dc285cd099

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.1.0-cp311-abi3-musllinux_1_2_x86_64.whl
Algorithm Hash digest
SHA256 1aa66e1d7d290eeab81ebae34ca05f63f03e5f31d453ceff81d330543443c8dc
MD5 920ed94cc6fb40760e13a56ff9f80b1c
BLAKE2b-256 04d43d8e37c5e0e55e2d164e31674187c9a1bbe213d7d2f1bd6605d705ecec7d

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.1.0-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 6a19b397602b5083030d4099c0c812b6989f20b68ca39f4203f8b9e9b9211899
MD5 cce14d15485e459c46011dfc9c8b96d8
BLAKE2b-256 9eed01a0cc6b248a8347fc3d8705026550c21563a0d1a9dd70e0cad88b179628

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.1.0-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 b3fbd321294864a2045cddfbfe1a90e31a09f7a4694d2aa1f926be6a0c93622a
MD5 385de4622e171babfafe7a79814ec703
BLAKE2b-256 bfff6638fe815e161d48e55c7b8b649ed7795de04b23c708a4c8de16ac966ae0

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.1.0-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 0c1145ecdacb4660151605b78e129dcb3b33dcc2d1cd101b12a070c50d206af2
MD5 04ee414e94941ce139492a29e6356ba0
BLAKE2b-256 589a961ca51199e4e134445182e5dd1c21818d70adc508dd5d3b6061c2d29eb0

See more details on using hashes here.

Provenance

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

File metadata

File hashes

Hashes for treecf-0.1.0-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 b8efd597c66347cc62e4b59f8c9dc21bd4aed0698c8fe39083ade9575f2d7d33
MD5 2461b2854daa1955b3e2403390c29440
BLAKE2b-256 1b7bc93826a5939f79a7e4199771cbe2a1d1a44687bd01aadd99a32c9f9c2aab

See more details on using hashes here.

Provenance

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

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

0.1.1

7 files

This release

0.1.0 This release

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