treecf 0.0.1__tar.gz

treecf-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Wlazlo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

treecf-0.0.1/PKG-INFO

@@ -0,0 +1,116 @@
+Metadata-Version: 2.4
+Name: treecf
+Version: 0.0.1
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Dist: numpy>=1.24
+Requires-Dist: xgboost>=2.0 ; extra == 'all'
+Requires-Dist: lightgbm>=4.3 ; extra == 'all'
+Requires-Dist: catboost>=1.2 ; extra == 'all'
+Requires-Dist: scikit-learn>=1.4 ; extra == 'all'
+Requires-Dist: matplotlib>=3.8 ; extra == 'all'
+Requires-Dist: catboost>=1.2 ; extra == 'catboost'
+Requires-Dist: maturin>=1.7 ; extra == 'dev'
+Requires-Dist: pytest>=8.0 ; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0 ; extra == 'dev'
+Requires-Dist: hypothesis>=6.100 ; extra == 'dev'
+Requires-Dist: ruff>=0.5 ; extra == 'dev'
+Requires-Dist: mypy>=1.10 ; extra == 'dev'
+Requires-Dist: xgboost>=2.0 ; extra == 'dev'
+Requires-Dist: lightgbm>=4.3 ; extra == 'dev'
+Requires-Dist: catboost>=1.2 ; extra == 'dev'
+Requires-Dist: scikit-learn>=1.4 ; extra == 'dev'
+Requires-Dist: matplotlib>=3.8 ; extra == 'dev'
+Requires-Dist: mkdocs>=1.6 ; extra == 'docs'
+Requires-Dist: mkdocs-material>=9.5 ; extra == 'docs'
+Requires-Dist: mkdocstrings[python]>=0.27 ; extra == 'docs'
+Requires-Dist: pymdown-extensions>=10.9 ; extra == 'docs'
+Requires-Dist: mkdocs-jupyter>=0.24 ; extra == 'docs'
+Requires-Dist: ipykernel>=6.29 ; extra == 'docs'
+Requires-Dist: lightgbm>=4.3 ; extra == 'lightgbm'
+Requires-Dist: scikit-learn>=1.4 ; extra == 'sklearn'
+Requires-Dist: matplotlib>=3.8 ; extra == 'viz'
+Requires-Dist: xgboost>=2.0 ; extra == 'xgboost'
+Provides-Extra: all
+Provides-Extra: catboost
+Provides-Extra: dev
+Provides-Extra: docs
+Provides-Extra: lightgbm
+Provides-Extra: sklearn
+Provides-Extra: viz
+Provides-Extra: xgboost
+License-File: LICENSE
+Summary: Constrained, threshold-aware counterfactual explanations for tree ensembles (XGBoost, LightGBM, CatBoost, sklearn) on a bundled Rust genetic engine.
+Keywords: counterfactual,xai,interpretability,recourse,gbdt,xgboost,lightgbm,catboost,cp-sat,credit-risk
+Author-email: Daniel Wlazlo <wlazlo.daniel@gmail.com>
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Changelog, https://github.com/wlazlod/treecf/blob/main/CHANGELOG.md
+Project-URL: Documentation, https://wlazlod.github.io/treecf/
+Project-URL: Homepage, https://github.com/wlazlod/treecf
+Project-URL: Issues, https://github.com/wlazlod/treecf/issues
+
+# 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: pre-release (v0.1). See the [documentation](https://wlazlod.github.io/treecf/) 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
+
+```bash
+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
+
+```python
+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
+

treecf-0.0.1/README.md

@@ -0,0 +1,54 @@
+# 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: pre-release (v0.1). See the [documentation](https://wlazlod.github.io/treecf/) 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
+
+```bash
+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
+
+```python
+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

treecf-0.0.1/pyproject.toml

@@ -0,0 +1,132 @@
+[project]
+name = "treecf"
+version = "0.0.1"
+description = "Constrained, threshold-aware counterfactual explanations for tree ensembles (XGBoost, LightGBM, CatBoost, sklearn) on a bundled Rust genetic engine."
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Daniel Wlazlo", email = "wlazlo.daniel@gmail.com" }]
+requires-python = ">=3.11"
+keywords = [
+    "counterfactual",
+    "xai",
+    "interpretability",
+    "recourse",
+    "gbdt",
+    "xgboost",
+    "lightgbm",
+    "catboost",
+    "cp-sat",
+    "credit-risk",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = ["numpy>=1.24"]
+
+[project.optional-dependencies]
+xgboost = ["xgboost>=2.0"]
+lightgbm = ["lightgbm>=4.3"]
+catboost = ["catboost>=1.2"]
+sklearn = ["scikit-learn>=1.4"]
+viz = ["matplotlib>=3.8"]
+all = [
+    "xgboost>=2.0",
+    "lightgbm>=4.3",
+    "catboost>=1.2",
+    "scikit-learn>=1.4",
+    "matplotlib>=3.8",
+]
+dev = [
+    "maturin>=1.7",
+    "pytest>=8.0",
+    "pytest-cov>=5.0",
+    "hypothesis>=6.100",
+    "ruff>=0.5",
+    "mypy>=1.10",
+    "xgboost>=2.0",
+    "lightgbm>=4.3",
+    "catboost>=1.2",
+    "scikit-learn>=1.4",
+    "matplotlib>=3.8",
+]
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.27",
+    "pymdown-extensions>=10.9",
+    "mkdocs-jupyter>=0.24",
+    "ipykernel>=6.29",
+]
+
+[project.urls]
+Homepage = "https://github.com/wlazlod/treecf"
+Documentation = "https://wlazlod.github.io/treecf/"
+Issues = "https://github.com/wlazlod/treecf/issues"
+Changelog = "https://github.com/wlazlod/treecf/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["maturin>=1.7"]
+build-backend = "maturin"
+
+[tool.maturin]
+python-source = "src"
+manifest-path = "rust/Cargo.toml"
+module-name = "treecf._treecf_core"
+features = ["extension-module"]
+include = [{ path = "README.md", format = "sdist" }, { path = "LICENSE", format = "sdist" }]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+extend-exclude = ["dist", "build", "docs"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "N", "SIM", "RUF"]
+ignore = ["N803", "N806", "RUF001", "RUF002"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["N802"]
+
+[tool.mypy]
+# no python_version pin: numpy's stubs use PEP 695 `type` statements, which mypy
+# rejects when told to type-check as 3.11 while running under 3.12/3.13
+strict = true
+files = ["src/treecf"]
+
+[[tool.mypy.overrides]]
+module = [
+    "xgboost.*",
+    "lightgbm.*",
+    "catboost.*",
+    "sklearn.*",
+    "matplotlib.*",
+    "treecf._treecf_core",
+    "pandas",
+]
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q --strict-markers -m 'not bench'"
+markers = [
+    "bench: non-gating performance smoke benchmarks (run with -m bench)",
+    "rust: cross-language tests requiring the dev Rust extension (maturin develop)",
+]
+filterwarnings = [
+    "error",
+    # sklearn warns when a wrapper fitted on a DataFrame-less array is queried with
+    # plain ndarrays; harmless in conformance tests (recorded in CLAUDE.md)
+    "ignore:X does not have valid feature names:UserWarning",
+    # lightgbm 4.5 still passes force_all_finite to scikit-learn 1.6 (renamed there);
+    # only affects the pinned conformance-matrix cell (recorded in CLAUDE.md)
+    "ignore:'force_all_finite' was renamed to 'ensure_all_finite':FutureWarning",
+]