treecf 0.2.2__tar.gz → 0.2.4__tar.gz

{treecf-0.2.2 → treecf-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: treecf
-Version: 0.2.2
+Version: 0.2.4
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
@@ -29,6 +29,7 @@ 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: probcal>=0.2 ; 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'
@@ -37,6 +38,9 @@ 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: pytest>=8.0 ; extra == 'test'
+Requires-Dist: hypothesis>=6.100 ; extra == 'test'
+Requires-Dist: probcal>=0.2 ; extra == 'test'
 Requires-Dist: matplotlib>=3.8 ; extra == 'viz'
 Requires-Dist: xgboost>=2.0 ; extra == 'xgboost'
 Provides-Extra: all
@@ -45,6 +49,7 @@ Provides-Extra: dev
 Provides-Extra: docs
 Provides-Extra: lightgbm
 Provides-Extra: sklearn
+Provides-Extra: test
 Provides-Extra: viz
 Provides-Extra: xgboost
 License-File: LICENSE
@@ -61,6 +66,8 @@ Project-URL: Issues, https://github.com/wlazlod/treecf/issues
 
 # treecf
 
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22069503.svg)](https://doi.org/10.5281/zenodo.22069503)
+
 **Constrained, threshold-aware counterfactual explanations for tree ensembles.**
 
 `treecf` answers the question: *"what is the minimal, feasible change to this instance such

{treecf-0.2.2 → treecf-0.2.4}/README.md

@@ -1,5 +1,7 @@
 # treecf
 
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22069503.svg)](https://doi.org/10.5281/zenodo.22069503)
+
 **Constrained, threshold-aware counterfactual explanations for tree ensembles.**
 
 `treecf` answers the question: *"what is the minimal, feasible change to this instance such

{treecf-0.2.2 → treecf-0.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "treecf"
-version = "0.2.2"
+version = "0.2.4"
 description = "Constrained, threshold-aware counterfactual explanations for tree ensembles (XGBoost, LightGBM, CatBoost, sklearn) — fast Rust genetic search, exact optimality proofs, certified infeasibility, and recourse regions."
 readme = "README.md"
 license = { text = "MIT" }
@@ -44,6 +44,11 @@ all = [
     "scikit-learn>=1.4",
     "matplotlib>=3.8",
 ]
+test = [
+    "pytest>=8.0",
+    "hypothesis>=6.100",
+    "probcal>=0.2",
+]
 dev = [
     "maturin>=1.7",
     "pytest>=8.0",
@@ -56,6 +61,7 @@ dev = [
     "catboost>=1.2",
     "scikit-learn>=1.4",
     "matplotlib>=3.8",
+    "probcal>=0.2",
 ]
 docs = [
     "mkdocs>=1.6",

{treecf-0.2.2 → treecf-0.2.4}/rust/Cargo.lock

@@ -419,7 +419,7 @@ checksum = "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca"
 
 [[package]]
 name = "treecf-core"
-version = "0.2.2"
+version = "0.2.4"
 dependencies = [
  "numpy",
  "pyo3",

{treecf-0.2.2 → treecf-0.2.4}/rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "treecf-core"
-version = "0.2.2"
+version = "0.2.4"
 edition = "2021"
 # f64::next_down (cells.rs) stabilized in 1.86; pyo3 0.29 needs 1.83
 rust-version = "1.86"

{treecf-0.2.2 → treecf-0.2.4}/rust/src/exact/search.rs

@@ -1053,19 +1053,18 @@ pub fn solve_exact(
     }
 
     completed = completed && dropped_floor >= incumbent_cost;
-    let lower_bound;
-    let proof;
-    if completed {
-        lower_bound = match incumbent_row {
+    let (lower_bound, proof) = if completed {
+        let bound = match incumbent_row {
             None => f64::INFINITY,
             Some(_) if gap == 0.0 => incumbent_cost,
             Some(_) => incumbent_cost / (1.0 + gap),
         };
-        proof = if gap > 0.0 && gap_prune_fired {
+        let label = if gap > 0.0 && gap_prune_fired {
             "optimal_within_gap"
         } else {
             "optimal"
         };
+        (bound, label)
     } else {
         let mut open_view = f64::INFINITY;
         if !ctx.order.is_empty() {
@@ -1081,9 +1080,11 @@ pub fn solve_exact(
         } else {
             dropped_floor
         };
-        lower_bound = py_min(py_min(open_view, incumbent_cost), set_aside_view);
-        proof = "heuristic";
-    }
+        (
+            py_min(py_min(open_view, incumbent_cost), set_aside_view),
+            "heuristic",
+        )
+    };
 
     let mut snapped: Vec<usize> = Vec::new();
     for (level, chosen_state) in incumbent_states.iter().flatten().enumerate() {

{treecf-0.2.2 → treecf-0.2.4}/src/treecf/__init__.py

@@ -28,7 +28,7 @@ from treecf.plausibility import Plausibility
 from treecf.regions import RecourseRegion
 from treecf.targets import Target
 
-__version__ = "0.2.2"
+__version__ = "0.2.4"
 
 __all__ = [
     "AllowMissing",

{treecf-0.2.2 → treecf-0.2.4}/src/treecf/api.py

@@ -129,6 +129,11 @@ class Counterfactual:
         region: The certified box around ``x_cf``, set only when the search ran
             with ``region=True`` (``Explainer.explain``/``explain_batch``/
             ``explain_coalitions``); ``None`` otherwise.
+        score_calibrated: The calibrator's probability at ``x_cf`` — set only
+            for a calibrated-space target whose calibrator exposes
+            ``predict_proba``; ``None`` otherwise. Presentational: the engine
+            optimized and verified against the raw interval the calibrator's
+            ``interval_inverse`` produced, never against this value.
     """
 
     x_cf: FloatArray
@@ -141,6 +146,7 @@ class Counterfactual:
     solver_stats: dict[str, object] = field(default_factory=dict)
     snapped: dict[str, bool] = field(default_factory=dict)  # value_policy outcome
     region: RecourseRegion | None = None  # set when `explain(..., region=True)`
+    score_calibrated: float | None = None  # presentational read-out; see docstring
 
 
 @dataclass(frozen=True)
@@ -171,6 +177,25 @@ class Infeasible:
     solver_stats: dict[str, object] = field(default_factory=dict)
 
 
+def _calibrated_readout(target: Target, score_raw: float) -> float | None:
+    """Calibrated probability at a raw score, or ``None`` when unavailable.
+
+    Duck-typed on ``predict_proba`` (never a probcal import); any failure in
+    the external calibrator degrades to ``None`` rather than erroring —
+    the read-out is presentational, the engine consumed the raw interval.
+    """
+    if target.space != "calibrated":
+        return None
+    predict = getattr(target.calibrator, "predict_proba", None)
+    if not callable(predict):
+        return None
+    try:
+        prob = 1.0 / (1.0 + np.exp(-np.float64(score_raw)))
+        return float(np.asarray(predict(np.array([prob])), dtype=np.float64).reshape(-1)[0])
+    except Exception:
+        return None
+
+
 # documented defaults for the exact-only kwargs; ``None`` at the public call
 # sites is the sentinel for "not explicitly passed"
 _DEFAULT_WARM_START = True
@@ -563,6 +588,10 @@ class Explainer:
                 )
                 if region and isinstance(outcome, Counterfactual):
                     outcome = replace(outcome, region=self._region_for(x, outcome.x_cf, interval))
+                if isinstance(outcome, Counterfactual) and target.space == "calibrated":
+                    outcome = replace(
+                        outcome, score_calibrated=_calibrated_readout(target, outcome.score_raw)
+                    )
                 results[name] = outcome
             message = _degraded_summary(band_degraded, len(band_degraded), len(intervals), "bands")
             if message is not None:
@@ -584,6 +613,10 @@ class Explainer:
         )
         if region and isinstance(result, Counterfactual):
             result = replace(result, region=self._region_for(x, result.x_cf, interval))
+        if isinstance(result, Counterfactual) and target.space == "calibrated":
+            result = replace(
+                result, score_calibrated=_calibrated_readout(target, result.score_raw)
+            )
         return result
 
     def explain_batch(
@@ -1318,7 +1351,9 @@ class Explainer:
             gap=gap, time_budget_s=time_budget_s, warm_start=warm_start,
         )
 
-    def check_certificate(self, cert: dict[str, object]) -> dict[str, object]:
+    def check_certificate(
+        self, cert: dict[str, object], *, calibrator: object | None = None
+    ) -> dict[str, object]:
         """Validate a stored certificate against *this* explainer.
 
         Recomputes both fingerprints (model and constraints) against this
@@ -1327,18 +1362,33 @@ class Explainer:
         changed constraint set each flips the corresponding boolean. This
         method reports — it never raises on a mismatch.
 
+        Without ``calibrator=``, a calibrated-target certificate is still
+        fully verifiable in *plan geometry*: the resolved ``raw_interval``
+        is stored, so this proves the plan reaches the stored interval — it
+        does not prove which calibrator produced that interval. Passing
+        ``calibrator=`` adds exactly that: the duck-typed ``fingerprint()``
+        is compared with the stored one, and the certificate's calibrated
+        ``lo``/``hi`` are re-inverted through the supplied calibrator and
+        compared with the stored interval (rtol 1e-9, infinities by
+        identity). Neither mode requires treecf to import a calibration
+        library.
+
         Args:
             cert: A certificate produced by ``Explainer.certificate`` (a
                 ``json.loads`` round trip of one works identically).
+            calibrator: Optional duck-typed calibrator (the object handed to
+                ``Target.calibrated``) to additionally verify calibrator
+                provenance against a calibrated-target certificate.
 
         Returns:
             ``{"model_match": bool, "constraints_match": bool,
             "verification_ok": bool, "mismatches": [...]}`` with one
-            human-readable string per mismatch.
+            human-readable string per mismatch, plus ``"calibrator_match":
+            bool`` when ``calibrator=`` was given.
         """
         from treecf.audit import check_certificate
 
-        return check_certificate(self, cert)
+        return check_certificate(self, cert, calibrator=calibrator)
 
     def _region_for(
         self, x: FloatArray, x_cf: FloatArray, interval: tuple[float, float]

{treecf-0.2.2 → treecf-0.2.4}/src/treecf/audit.py

@@ -309,6 +309,22 @@ def _verify_infeasible(
     }
 
 
+def _duck_fingerprint(calibrator: object) -> str | None:
+    """The calibrator's duck-typed ``fingerprint()``, or ``None``.
+
+    Absent or raising members degrade to ``None`` — provenance is optional
+    by design; treecf never requires a calibration library at runtime.
+    """
+    fn = getattr(calibrator, "fingerprint", None)
+    if not callable(fn):
+        return None
+    try:
+        value = fn()
+    except Exception:
+        return None
+    return str(value) if value is not None else None
+
+
 def _target_block(
     target: Target, band: str | None, explainer: Explainer
 ) -> tuple[dict[str, object], tuple[float, float]]:
@@ -338,10 +354,25 @@ def _target_block(
     if band is not None:
         block["band"] = band
     if target.space == "calibrated":
-        block["calibrator"] = "external — not embedded"
+        block["calibrator"] = {
+            "embedded": False,
+            "fingerprint": _duck_fingerprint(target.calibrator),
+            "type": type(target.calibrator).__name__,
+            "buffer_logit": _json_float(target.buffer_logit),
+        }
     return block, interval
 
 
+def _factual_block(explainer: Explainer, x: FloatArray, target: Target) -> dict[str, object]:
+    block: dict[str, object] = {"x": _encode_array(x)}
+    if target.space == "calibrated":
+        from treecf.api import _calibrated_readout
+
+        readout = _calibrated_readout(target, raw_score(explainer.ir, x))
+        block["score_calibrated"] = _json_float(readout) if readout is not None else None
+    return block
+
+
 def build_certificate(
     explainer: Explainer,
     x: FloatArray,
@@ -405,7 +436,7 @@ def build_certificate(
         },
         "target": target_block,
         "solve": solve,
-        "factual": {"x": _encode_array(x)},
+        "factual": _factual_block(explainer, x, target),
     }
     if reproducible_reason is not None:
         cert["reproducible_reason"] = reproducible_reason
@@ -443,7 +474,9 @@ def build_certificate(
     return cert
 
 
-def check_certificate(explainer: Explainer, cert: dict[str, object]) -> dict[str, object]:
+def check_certificate(
+    explainer: Explainer, cert: dict[str, object], *, calibrator: object | None = None
+) -> dict[str, object]:
     """Body of ``Explainer.check_certificate``; see its docstring."""
     mismatches: list[str] = []
 
@@ -517,9 +550,73 @@ def check_certificate(explainer: Explainer, cert: dict[str, object]) -> dict[str
         verification_ok = False
         mismatches.append(f"verification could not be re-run: {exc}")
 
-    return {
+    report: dict[str, object] = {
         "model_match": model_match,
         "constraints_match": constraints_match,
         "verification_ok": verification_ok,
         "mismatches": mismatches,
     }
+    if calibrator is not None:
+        report["calibrator_match"] = _check_calibrator(cert, calibrator, mismatches)
+    return report
+
+
+def _check_calibrator(
+    cert: dict[str, object], calibrator: object, mismatches: list[str]
+) -> bool:
+    """The two extra checks ``check_certificate(calibrator=...)`` adds.
+
+    (a) the duck-typed fingerprint against the stored one — unavailable on
+    either side is noted in ``mismatches`` without failing the match, since
+    absence is not evidence of a different calibrator; (b) the certificate's
+    calibrated ``lo``/``hi`` re-inverted through the calibrator against the
+    stored ``raw_interval`` (rtol 1e-9, infinities by identity) — the check
+    that actually proves this calibrator produces this plan geometry.
+    """
+    ok = True
+    target = cert.get("target")
+    if not isinstance(target, dict) or target.get("space") != "calibrated":
+        mismatches.append("calibrator= given but the certificate's target is not calibrated")
+        return False
+    stored_block = target.get("calibrator")
+    stored_fp = stored_block.get("fingerprint") if isinstance(stored_block, dict) else None
+    fresh_fp = _duck_fingerprint(calibrator)
+    if stored_fp is None or fresh_fp is None:
+        mismatches.append(
+            "calibrator fingerprint unavailable on "
+            + ("both sides" if stored_fp is None and fresh_fp is None else "one side")
+            + " — identity not confirmed by fingerprint"
+        )
+    elif stored_fp != fresh_fp:
+        ok = False
+        mismatches.append("calibrator fingerprint does not match the certificate's")
+    stored_buffer = (
+        _from_json_float(stored_block.get("buffer_logit", 0.0))
+        if isinstance(stored_block, dict)
+        else 0.0
+    )
+    raw = target.get("raw_interval")
+    try:
+        lo = _from_json_float(target.get("lo"))
+        hi = _from_json_float(target.get("hi"))
+        fresh_lo, fresh_hi = calibrator.interval_inverse(  # type: ignore[attr-defined]
+            lo, hi, space="logit", buffer_logit=stored_buffer
+        )
+        stored_lo = _from_json_float(raw[0])  # type: ignore[index]
+        stored_hi = _from_json_float(raw[1])  # type: ignore[index]
+        for fresh, stored in ((fresh_lo, stored_lo), (fresh_hi, stored_hi)):
+            if math.isinf(fresh) or math.isinf(stored):
+                same = fresh == stored
+            else:
+                same = math.isclose(fresh, stored, rel_tol=1e-9, abs_tol=1e-12)
+            if not same:
+                ok = False
+                mismatches.append(
+                    "re-inverted interval does not match the stored raw_interval: "
+                    f"fresh ({fresh_lo}, {fresh_hi}) vs stored ({stored_lo}, {stored_hi})"
+                )
+                break
+    except Exception as exc:
+        ok = False
+        mismatches.append(f"re-inversion through the supplied calibrator failed: {exc}")
+    return ok

{treecf-0.2.2 → treecf-0.2.4}/src/treecf/batch.py

@@ -93,6 +93,14 @@ class BatchRecord:
         solver_stats: Exact-backend diagnostics for the solve behind this
             record, same keys as ``Counterfactual.solver_stats``; empty for
             genetic/python solves (those engines report no per-row stats).
+        calibrator_fingerprint: The duck-typed ``fingerprint()`` of the
+            calibrated target's calibrator, when it exposes one; ``None``
+            for raw/probability targets or fingerprint-less calibrators.
+            Repeated on every record so each file line is self-contained.
+        score_calibrated: The calibrator's probability at ``x_cf`` for a
+            calibrated target whose calibrator exposes ``predict_proba``;
+            presentational only — the engine optimized and verified on the
+            resolved raw interval. ``None`` otherwise.
     """
 
     id: object
@@ -110,6 +118,11 @@ class BatchRecord:
     region: RecourseRegion | None = None  # set by explain_batch(..., region=True)
     proof: str = "heuristic"  # mirrors Counterfactual.proof / Infeasible.proof
     solver_stats: dict[str, object] = field(default_factory=dict)  # exact-backend only
+    # Calibrated-target provenance and read-out (0.2.4). The fingerprint is one
+    # value repeated per record on purpose: every JSON line stays self-contained
+    # for a validator who receives only a slice of the file.
+    calibrator_fingerprint: str | None = None
+    score_calibrated: float | None = None  # presentational; the engine used raw_interval
 
 
 @dataclass(frozen=True)
@@ -192,6 +205,8 @@ class BatchResult:
                     "blocked_lever": record.blocked_lever,
                     "coalition": record.coalition,
                     "proof": record.proof,
+                    "calibrator_fingerprint": record.calibrator_fingerprint,
+                    "score_calibrated": record.score_calibrated,
                     "solver_stats": {
                         key: encode_floats(value)
                         for key, value in record.solver_stats.items()
@@ -279,6 +294,9 @@ class BatchResult:
                     proof=raw.get(
                         "proof", "heuristic" if raw["feasible"] else "search_exhausted"
                     ),
+                    # absent in files written before 0.2.4
+                    calibrator_fingerprint=raw.get("calibrator_fingerprint"),
+                    score_calibrated=raw.get("score_calibrated"),
                     solver_stats={
                         key: decode_floats(value)
                         for key, value in raw.get("solver_stats", {}).items()
@@ -561,6 +579,24 @@ def explain_batch(
     if message is not None:
         warnings.warn(message, TreecfWarning, stacklevel=2)
 
+    if target.space == "calibrated":
+        from dataclasses import replace as _replace
+
+        from treecf.api import _calibrated_readout
+        from treecf.audit import _duck_fingerprint
+
+        calibrator_fp = _duck_fingerprint(target.calibrator)
+        if calibrator_fp is not None:
+            records = [_replace(r, calibrator_fingerprint=calibrator_fp) for r in records]
+        # The Rust wave paths assemble Counterfactuals without going through
+        # Explainer._explain, so the read-out is filled here for every path.
+        records = [
+            _replace(r, score_calibrated=_calibrated_readout(target, r.score_raw))
+            if r.feasible and r.score_calibrated is None and r.score_raw is not None
+            else r
+            for r in records
+        ]
+
     return BatchResult(
         feature_names=explainer.ir.feature_names,
         diversity=diversity,
@@ -595,6 +631,7 @@ def _record_from(
         n_changed=cf.n_changed,
         score_raw=cf.score_raw,
         score_prob=cf.score_prob,
+        score_calibrated=cf.score_calibrated,
         seed=seed,
         blocked_lever=blocked_lever,
         coalition=coalition,

{treecf-0.2.2 → treecf-0.2.4}/src/treecf/ir/parsers/sklearn.py

@@ -96,8 +96,40 @@ def _parse_hist_gradient_boosting(model: Any) -> EnsembleIR:
     )
 
 
+def _effective_le_threshold(t: float) -> float:
+    """The float64 boundary of sklearn's float32 input cast, exactly.
+
+    sklearn ``tree_``-based ensembles route ``float32(x) <= float64(t)`` —
+    the input is cast to float32 (round-to-nearest-even) before the
+    comparison. The IR evaluates in float64, so the stored threshold must be
+    the largest float64 ``T`` with ``float32(T) <= t``; then ``x <= T``
+    reproduces the native routing for *every* float64 ``x``, including points
+    exactly on split boundaries — where a counterfactual search naturally
+    lands. (Verified by a 138k-probe property sweep and the unquantized
+    conformance tests.)
+
+    Construction: let ``f`` be the largest float32 with ``f <= t`` and ``s``
+    its float32 successor; every ``x`` below their float64 midpoint rounds to
+    ``<= f``. The midpoint itself rounds half-to-even: it belongs to the left
+    side exactly when it rounds back to ``f``.
+    """
+    f32 = np.float32(t)
+    if float(f32) > t:
+        f32 = np.nextafter(f32, np.float32(-np.inf))
+    succ = np.nextafter(f32, np.float32(np.inf))
+    mid = (float(f32) + float(succ)) / 2.0
+    if float(np.float32(mid)) == float(f32):
+        return mid
+    return float(np.nextafter(mid, -np.inf))
+
+
 def _tree_from_arrays(tree: Any, scale: float, classifier: bool) -> Tree:
-    """Convert a fitted ``sklearn.tree._tree.Tree`` to IR nodes (LE convention)."""
+    """Convert a fitted ``sklearn.tree._tree.Tree`` to IR nodes (LE convention).
+
+    Thresholds are re-expressed on the float64 grid via
+    :func:`_effective_le_threshold` so the IR's float64 routing matches
+    sklearn's float32-cast routing bit-for-bit.
+    """
     left = tree.children_left
     right = tree.children_right
     feature = tree.feature
@@ -120,7 +152,7 @@ def _tree_from_arrays(tree: Any, scale: float, classifier: bool) -> Tree:
                 Node(
                     node_id=i,
                     feature=int(feature[i]),
-                    threshold=float(threshold[i]),
+                    threshold=_effective_le_threshold(float(threshold[i])),
                     op=SplitOp.LE,
                     missing_left=missing_left,
                     left=int(left[i]),
@@ -183,7 +215,7 @@ def parse_isolation_forest(model: Any) -> EnsembleIR:
                     Node(
                         node_id=i,
                         feature=int(tree.feature[i]),
-                        threshold=float(tree.threshold[i]),
+                        threshold=_effective_le_threshold(float(tree.threshold[i])),
                         op=SplitOp.LE,
                         missing_left=None,
                         left=int(tree.children_left[i]),