zoneboost 0.37.0__py3-none-any.whl

zoneboost/_conformal.py

@@ -0,0 +1,198 @@
+"""Conformalized Quantile Regression (CQR): a distribution-free prediction
+interval whose width can vary with X, built from two quantile-mode
+:class:`zoneboost.ZoneBoostRegressor` fits -- unlike
+:meth:`zoneboost.ZoneBoostRegressor.predict_interval`'s split-conformal
+margin, which is a single fixed width added uniformly to every row.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from sklearn.base import BaseEstimator, clone
+from sklearn.utils.validation import check_is_fitted
+
+from ._common import ensure_dataframe
+from .regressor import ZoneBoostRegressor
+
+__all__ = ["ConformalizedQuantileRegressor"]
+
+
+def _rearrange(lo: np.ndarray, hi: np.ndarray) -> tuple:
+    """Chernozhukov, Fernandez-Val & Galichon (2010) rearrangement for
+    exactly two quantile levels: sorting two numbers per row is just an
+    elementwise ``min``/``max`` swap. Fixes "crossing"
+    (``lo[i] > hi[i]``) -- possible whenever ``lo``/``hi`` come from two
+    independently-fit models with no shared constraint between them --
+    without changing anything already ordered (``min``/``max`` of an
+    already-sorted pair is a no-op), so this never changes output on
+    data where crossing didn't occur."""
+    return np.minimum(lo, hi), np.maximum(lo, hi)
+
+
+class ConformalizedQuantileRegressor(BaseEstimator):
+    """Locally-adaptive prediction intervals via Conformalized Quantile
+    Regression (Romano, Patterson & Candes, 2019).
+
+    Fits two quantile-mode :class:`zoneboost.ZoneBoostRegressor` instances
+    at levels ``alpha/2`` and ``1 - alpha/2`` (the raw quantile band), then
+    conformalizes their gap on a genuinely held-out calibration split: the
+    nonconformity score ``E_i = max(q_lo(X_i) - y_i, y_i - q_hi(X_i))`` is
+    computed for every calibration row, and the same fixed additive margin
+    (the finite-sample-corrected quantile of these scores) is added to both
+    quantile predictions. The result still gives ``ZoneBoostRegressor.
+    predict_interval``'s exact distribution-free marginal coverage guarantee
+    (``P(y in interval) >= 1 - alpha``, under exchangeability) -- but
+    because the *quantile* predictions themselves already vary with ``X``,
+    the total interval width does too, unlike a plain split-conformal band's
+    single constant-width margin.
+
+    ``lo_``/``hi_`` are two **independently**-fit models, so nothing
+    guarantees ``lo_.predict(x) <= hi_.predict(x)`` for every row
+    ("crossing"). Both are rearranged (Chernozhukov, Fernandez-Val &
+    Galichon, 2010) -- for exactly two levels, an elementwise ``min``/``max``
+    swap -- before computing calibration scores and before returning an
+    interval, unconditionally (not behind a parameter): rearrangement never
+    increases estimation risk and is a no-op wherever a row was already
+    ordered, so this never changes output on data where crossing didn't
+    occur.
+
+    Not a general-purpose point regressor (there is no meaningful single
+    ``predict``): use :meth:`predict_interval` for the band, or fit
+    ``estimator`` directly (with ``loss="squared_error"``) alongside this
+    class if a point prediction is also needed.
+
+    Parameters
+    ----------
+    estimator : ZoneBoostRegressor, default=None
+        An unfit template supplying every tuning knob *other* than
+        ``loss``/``quantile``/``calibration_fraction`` (e.g. ``n_rounds``,
+        ``max_zones``, ``shrinkage_m``, ``monotonic_constraints``,
+        ``adaptive_boundary_smoothing``) -- cloned twice internally, once
+        per quantile level. ``None`` (default) uses a plain
+        ``ZoneBoostRegressor()``. Any ``loss``/``quantile``/
+        ``calibration_fraction``/``random_state`` set on the template are
+        always overridden (this class manages them itself) -- every other
+        parameter is respected as-is. Quantile-mode fitting uses
+        ``QuantileRegressor``'s linear-programming solver internally, which
+        is substantially more expensive per round than the default loss
+        (see :class:`zoneboost.ZoneBoostRegressor`'s ``loss`` parameter) --
+        two such models are fit here, so consider a smaller ``n_rounds`` or
+        ``n_iter_no_change`` on the template for large datasets.
+    alpha : float, default=0.1
+        Miscoverage rate -- e.g. ``0.1`` targets 90% coverage. The two
+        internal quantile levels are ``alpha / 2`` and ``1 - alpha / 2``.
+    calibration_fraction : float, default=0.2
+        Fraction of training rows held out (once, at the start of `fit`)
+        purely for CQR calibration -- genuinely separate from, and never
+        reused by, either quantile model's own internal
+        ``validation_fraction`` split (which only drives their own early
+        stopping).
+    random_state : int, default=42
+        Seed for the calibration split and (via the two cloned estimators)
+        their own internal splits/subsampling.
+
+    Attributes
+    ----------
+    lo_ : ZoneBoostRegressor
+        Fitted quantile model at level ``alpha / 2``.
+    hi_ : ZoneBoostRegressor
+        Fitted quantile model at level ``1 - alpha / 2``.
+    cqr_scores_ : ndarray
+        Sorted CQR nonconformity scores on the calibration split -- the
+        margin :meth:`predict_interval` draws from.
+
+    Examples
+    --------
+    >>> import pandas as pd
+    >>> from zoneboost import ConformalizedQuantileRegressor
+    >>> X = pd.DataFrame({"x": [1, 2, 3, 4, 5, 6, 7, 8]})
+    >>> y = [1.0, 2.1, 2.9, 4.2, 4.8, 6.1, 6.9, 8.3]
+    >>> model = ConformalizedQuantileRegressor(alpha=0.2, random_state=0).fit(X, y)
+    >>> lower, upper = model.predict_interval(X)
+    """
+
+    def __init__(
+        self,
+        estimator: ZoneBoostRegressor = None,
+        alpha: float = 0.1,
+        calibration_fraction: float = 0.2,
+        random_state: int = 42,
+    ):
+        self.estimator = estimator
+        self.alpha = alpha
+        self.calibration_fraction = calibration_fraction
+        self.random_state = random_state
+
+    def fit(self, X, y):
+        """Fit the two internal quantile models and calibrate the CQR margin.
+
+        Parameters
+        ----------
+        X : DataFrame or array-like of shape (n_samples, n_features)
+        y : array-like of shape (n_samples,)
+
+        Returns
+        -------
+        self : ConformalizedQuantileRegressor
+        """
+        if not 0 < self.alpha < 1:
+            raise ValueError(f"alpha must be in (0, 1), got {self.alpha!r}")
+        if not 0 < self.calibration_fraction < 1:
+            raise ValueError(f"calibration_fraction must be in (0, 1), got {self.calibration_fraction!r}")
+
+        X = ensure_dataframe(X, getattr(self, "feature_names_in_", None))
+        y_arr = np.asarray(y, dtype=float).reshape(-1)
+        if len(X) != len(y_arr):
+            raise ValueError(f"X and y have inconsistent lengths: {len(X)} vs {len(y_arr)}")
+        self.feature_names_in_ = np.array(X.columns)
+
+        base = self.estimator if self.estimator is not None else ZoneBoostRegressor()
+
+        rng = np.random.default_rng(self.random_state)
+        n_total = len(X)
+        perm = rng.permutation(n_total)
+        n_cal = max(1, int(n_total * self.calibration_fraction))
+        if n_cal >= n_total:
+            raise ValueError("calibration_fraction leaves no rows for the training split.")
+        cal_idx, train_idx = perm[:n_cal], perm[n_cal:]
+        X_cal = X.iloc[cal_idx].reset_index(drop=True)
+        y_cal = y_arr[cal_idx]
+        X_train = X.iloc[train_idx].reset_index(drop=True)
+        y_train = y_arr[train_idx]
+
+        self.lo_ = clone(base).set_params(
+            loss="quantile", quantile=self.alpha / 2, calibration_fraction=0.0, random_state=self.random_state
+        )
+        self.hi_ = clone(base).set_params(
+            loss="quantile", quantile=1 - self.alpha / 2, calibration_fraction=0.0, random_state=self.random_state
+        )
+        self.lo_.fit(X_train, y_train)
+        self.hi_.fit(X_train, y_train)
+
+        lo_cal_pred = self.lo_.predict(X_cal)
+        hi_cal_pred = self.hi_.predict(X_cal)
+        lo_cal_pred, hi_cal_pred = _rearrange(lo_cal_pred, hi_cal_pred)
+        scores = np.maximum(lo_cal_pred - y_cal, y_cal - hi_cal_pred)
+        self.cqr_scores_ = np.sort(scores)
+        return self
+
+    def predict_interval(self, X) -> tuple:
+        """Locally-adaptive prediction interval.
+
+        Parameters
+        ----------
+        X : DataFrame or array-like of shape (n_samples, n_features)
+
+        Returns
+        -------
+        lower, upper : ndarray of shape (n_samples,)
+        """
+        check_is_fitted(self, "lo_")
+        X = ensure_dataframe(X, self.feature_names_in_)
+        q_lo = self.lo_.predict(X)
+        q_hi = self.hi_.predict(X)
+        q_lo, q_hi = _rearrange(q_lo, q_hi)
+        n = len(self.cqr_scores_)
+        k = min(int(np.ceil((n + 1) * (1 - self.alpha))), n)
+        margin = self.cqr_scores_[k - 1]
+        return q_lo - margin, q_hi + margin

zoneboost/_drift.py

@@ -0,0 +1,168 @@
+"""Time-based / drift-aware reporting: a **stateless comparison** between
+two already-fitted `ZoneBoostRegressor` models -- e.g. last quarter's
+model and this quarter's -- not a new fit-time behavior. zoneboost itself
+doesn't monitor anything in real time or retain a history of past fits;
+the user retrains a new model each period and calls :func:`compare_models`
+to compare it against the previous one, on a shared evaluation dataset
+(zoneboost retains no training data after `fit`, so there is no other way
+to compare "the same rows" across two models).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from ._weak_learner import _column_zone_index
+
+__all__ = ["compare_models"]
+
+
+def _observed_range(model, feature: str) -> tuple:
+    """Min/max of ``feature``'s own zone centers across every round
+    ``model`` fit it in as a continuous main effect -- what the model
+    actually has information about, not the column's full theoretical
+    range. Shared by :meth:`zoneboost.ZoneBoostRegressor.counterfactual`
+    (via a thin wrapper) and :func:`compare_models` -- one implementation,
+    not two."""
+    mins, maxs = [], []
+    for round_ in model.rounds_:
+        if feature not in round_["main_effects"]:
+            continue
+        zone_info_col = round_["zone_info"][feature]
+        if zone_info_col[0] != "continuous":
+            continue
+        centers = zone_info_col[2]
+        if len(centers) > 0:
+            mins.append(float(centers.min()))
+            maxs.append(float(centers.max()))
+    if not mins:
+        raise ValueError(f"{feature!r} never appeared as a continuous main effect in any round.")
+    return min(mins), max(maxs)
+
+
+def _shared_continuous_columns(model_old, model_new) -> list:
+    old_cols = model_old._continuous_main_effect_columns()
+    new_cols = model_new._continuous_main_effect_columns()
+    return sorted(old_cols & new_cols)
+
+
+def _last_continuous_zone_info(model, feature):
+    """The most recent round's own zone_info for ``feature``, or ``None``
+    if it never appeared as a continuous main effect -- a representative
+    snapshot, not a claim about every round's own boundaries (zoneboost's
+    zones are re-derived fresh every round; see the module docstring)."""
+    for round_ in reversed(model.rounds_):
+        if feature in round_["main_effects"] and round_["zone_info"][feature][0] == "continuous":
+            return round_["zone_info"][feature]
+    return None
+
+
+def compare_models(model_old, model_new, X_eval, y_eval=None) -> dict:
+    """Compares two already-fitted :class:`zoneboost.ZoneBoostRegressor`
+    models -- e.g. a model refit on a later time period -- on a shared
+    evaluation dataset. Reuses existing, already-exact machinery
+    throughout (``feature_importance``, ``predict``) rather than
+    inventing parallel comparison logic.
+
+    **Scope**: regressor only (classifier support deferred -- multiclass's
+    per-class nested ``rounds_`` would meaningfully complicate every
+    comparison below); compares exactly two snapshots (call this function
+    pairwise across more periods for a longer trend); reports an aggregate
+    boundary/zone summary, not each model's full per-round boundary
+    provenance.
+
+    Parameters
+    ----------
+    model_old, model_new : ZoneBoostRegressor
+        Both already fitted.
+    X_eval : DataFrame or array-like of shape (n_samples, n_features)
+        A dataset both models can score -- typically the newer period's
+        data, or a fixed holdout common to both fits.
+    y_eval : array-like, default=None
+        If given, also reports ``performance_change``.
+
+    Returns
+    -------
+    dict with keys:
+        ``feature_importance_change`` -- DataFrame indexed by term name,
+        columns ``old``/``new``/``change`` (a term absent from one model
+        contributes `0`), sorted by ``|change|`` descending.
+        ``new_terms``/``disappeared_terms`` -- term names present in only
+        one model's ``feature_importance`` index.
+        ``boundary_shift`` -- ``{feature: {"old_range": (lo, hi),
+        "new_range": (lo, hi), "center_shift": float}}`` for every
+        continuous main-effect column present in both models --
+        ``center_shift`` is the shift in each range's own midpoint.
+        ``population_migration`` -- ``{feature: fraction}`` for the same
+        shared columns: using each model's own *last* fitted round's zone
+        boundaries (a representative snapshot) to assign every row of
+        ``X_eval`` a hard zone index under both models, the fraction of
+        rows whose zone assignment differs.
+        ``performance_change`` -- ``{"rmse_old": ..., "rmse_new": ...}``,
+        or ``None`` if ``y_eval`` not given.
+        ``prediction_shift`` -- ``{"mean": ..., "std": ...}`` of
+        ``predict_new(X_eval) - predict_old(X_eval)``.
+    """
+    X_eval = model_old._ensure_dataframe(X_eval)
+
+    importance_old = model_old.feature_importance(X_eval)
+    importance_new = model_new.feature_importance(X_eval)
+    all_terms = sorted(set(importance_old.index) | set(importance_new.index))
+    old_vals = np.array([float(importance_old.get(t, 0.0)) for t in all_terms])
+    new_vals = np.array([float(importance_new.get(t, 0.0)) for t in all_terms])
+    feature_importance_change = pd.DataFrame(
+        {"old": old_vals, "new": new_vals, "change": new_vals - old_vals}, index=all_terms
+    )
+    feature_importance_change = feature_importance_change.reindex(
+        feature_importance_change["change"].abs().sort_values(ascending=False).index
+    )
+
+    new_terms = sorted(set(importance_new.index) - set(importance_old.index))
+    disappeared_terms = sorted(set(importance_old.index) - set(importance_new.index))
+
+    shared_cols = _shared_continuous_columns(model_old, model_new)
+    boundary_shift = {}
+    population_migration = {}
+    for feature in shared_cols:
+        old_range = _observed_range(model_old, feature)
+        new_range = _observed_range(model_new, feature)
+        old_center = (old_range[0] + old_range[1]) / 2.0
+        new_center = (new_range[0] + new_range[1]) / 2.0
+        boundary_shift[feature] = {
+            "old_range": old_range,
+            "new_range": new_range,
+            "center_shift": new_center - old_center,
+        }
+
+        old_zone_info = _last_continuous_zone_info(model_old, feature)
+        new_zone_info = _last_continuous_zone_info(model_new, feature)
+        if old_zone_info is not None and new_zone_info is not None:
+            old_zones = _column_zone_index(X_eval[feature], old_zone_info)
+            new_zones = _column_zone_index(X_eval[feature], new_zone_info)
+            population_migration[feature] = float(np.mean(old_zones != new_zones))
+
+    performance_change = None
+    if y_eval is not None:
+        y_arr = np.asarray(y_eval, dtype=float).reshape(-1)
+        pred_old = model_old.predict(X_eval)
+        pred_new = model_new.predict(X_eval)
+        performance_change = {
+            "rmse_old": float(np.sqrt(np.mean((y_arr - pred_old) ** 2))),
+            "rmse_new": float(np.sqrt(np.mean((y_arr - pred_new) ** 2))),
+        }
+
+    pred_old = model_old.predict(X_eval)
+    pred_new = model_new.predict(X_eval)
+    diff = pred_new - pred_old
+    prediction_shift = {"mean": float(diff.mean()), "std": float(diff.std())}
+
+    return {
+        "feature_importance_change": feature_importance_change,
+        "new_terms": new_terms,
+        "disappeared_terms": disappeared_terms,
+        "boundary_shift": boundary_shift,
+        "population_migration": population_migration,
+        "performance_change": performance_change,
+        "prediction_shift": prediction_shift,
+    }

zoneboost/_evidence_card.py

@@ -0,0 +1,204 @@
+"""Model evidence cards: a compact, JSON-serializable snapshot of a fitted
+`ZoneBoostRegressor` -- zones/boundaries, per-term support/shrinkage,
+constraint declarations, calibration/conformal coverage, unsupported
+regions, and reproducibility info -- assembled entirely from attributes
+the model already exposes after `fit`. Pure aggregation, no new modeling
+math: every number here is read off `rounds_`, `get_params()`, or a
+method (`feature_importance`, `_observed_range`) this session's earlier
+items already added.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+import numpy as np
+import pandas as pd
+
+from ._drift import _observed_range
+from ._reliability import _find_term_key
+from ._version import __version__
+
+__all__ = ["evidence_card"]
+
+
+def _jsonable(obj):
+    """Recursively coerce numpy/pandas scalars and non-JSON containers
+    (``set``/``frozenset``, tuple dict keys) into plain Python types --
+    the whole point of a *machine-readable* card is that ``json.dumps``
+    never trips over it."""
+    if isinstance(obj, dict):
+        return {str(k): _jsonable(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple, set, frozenset)):
+        return [_jsonable(v) for v in obj]
+    if isinstance(obj, (np.floating,)):
+        return float(obj)
+    if isinstance(obj, (np.integer,)):
+        return int(obj)
+    if isinstance(obj, (np.bool_, bool)):
+        return bool(obj)
+    if isinstance(obj, np.ndarray):
+        return [_jsonable(v) for v in obj.tolist()]
+    return obj
+
+
+def _dataset_fingerprint(X: pd.DataFrame) -> dict:
+    row_hash = pd.util.hash_pandas_object(X, index=False)
+    digest = hashlib.sha256(row_hash.to_numpy().tobytes()).hexdigest()
+    return {
+        "n_rows": int(len(X)),
+        "n_columns": int(X.shape[1]),
+        "columns": list(X.columns),
+        "dtypes": {col: str(dt) for col, dt in X.dtypes.items()},
+        "hash": digest,
+    }
+
+
+def _term_diagnostics_summary(rounds: list, kind: str, key, shrinkage_m: float):
+    """Aggregates a term's own per-zone/cell ``counts`` array (already
+    stored per round when ``track_reliability=True``) across every round
+    it appeared in -- ``None`` if the model wasn't fit with
+    ``track_reliability=True`` (``diagnostics`` is ``None`` on every
+    round in that case). No ``X`` needed: unlike
+    :func:`zoneboost._reliability.explain_reliability`, this doesn't look
+    up any specific row's own zone, just the raw stored counts."""
+    term_id = frozenset(key) if isinstance(key, tuple) else frozenset([key])
+    all_counts = []
+    n_present = 0
+    for round_ in rounds:
+        if round_["diagnostics"] is None:
+            return None
+        term_dict = round_[kind]
+        dkey = key if key in term_dict else _find_term_key(term_dict, term_id)
+        if dkey is None:
+            continue
+        n_present += 1
+        all_counts.append(round_["diagnostics"][kind][dkey]["counts"].ravel())
+    if not all_counts:
+        return None
+    counts = np.concatenate(all_counts)
+    return {
+        "mean_support_per_zone": float(counts.mean()),
+        "mean_shrinkage_fraction": float((shrinkage_m / (counts + shrinkage_m)).mean()),
+    }
+
+
+def _term_name(key) -> str:
+    return key if isinstance(key, str) else " x ".join(sorted(key))
+
+
+def _conformal_summary(scores) -> dict:
+    return {
+        "n": int(len(scores)),
+        "median": float(np.median(scores)),
+        "p90": float(np.quantile(scores, 0.9)),
+    }
+
+
+def evidence_card(model, X: pd.DataFrame = None) -> dict:
+    """See :meth:`zoneboost.ZoneBoostRegressor.evidence_card` -- the
+    method is a thin wrapper around this standalone function."""
+    rounds = model.rounds_
+    shrinkage_m = model.shrinkage_m
+
+    # zones: each column's own *last* round as a main effect -- a
+    # representative snapshot, not a full per-round boundary history
+    # (same disclosed precedent as items 6/7's own drift/hierarchical
+    # reporting).
+    zones = {}
+    for col in model.predictor_names_:
+        last_round = None
+        n_present = 0
+        for round_ in rounds:
+            if col in round_["main_effects"]:
+                n_present += 1
+                last_round = round_
+        if last_round is None:
+            zones[col] = {"kind": None, "n_rounds_present": 0}
+            continue
+        zone_info_col = last_round["zone_info"][col]
+        kind = zone_info_col[0]
+        entry = {"kind": kind, "n_rounds_present": n_present}
+        if kind == "continuous":
+            entry["observed_range"] = _observed_range(model, col)
+        else:
+            entry["categories_seen"] = sorted(zone_info_col[1].keys())
+        zones[col] = entry
+
+    # terms: union of every main effect / interaction / triple across all
+    # rounds, keyed by the same "A x B" name explain()/feature_importance()
+    # already use.
+    term_keys = {"main_effects": {}, "interactions": {}, "triples": {}}
+    for round_ in rounds:
+        for col in round_["main_effects"]:
+            term_keys["main_effects"].setdefault(col, col)
+        for key in round_["interactions"]:
+            term_keys["interactions"].setdefault(frozenset(key), key)
+        for key in round_["triples"]:
+            term_keys["triples"].setdefault(frozenset(key), key)
+
+    importance = model.feature_importance(X) if X is not None else None
+
+    terms = {}
+    n_rounds_total = len(rounds)
+    for kind, keys in term_keys.items():
+        for term_id, key in keys.items():
+            name = _term_name(key)
+            if kind == "main_effects":
+                n_present = sum(1 for round_ in rounds if key in round_[kind])
+            else:
+                n_present = sum(1 for round_ in rounds if _find_term_key(round_[kind], term_id) is not None)
+            diag = _term_diagnostics_summary(rounds, kind, key, shrinkage_m)
+            terms[name] = {
+                "kind": kind.rstrip("s") if kind != "main_effects" else "main_effect",
+                "n_rounds_present": n_present,
+                "n_rounds_total": n_rounds_total,
+                "mean_abs_contribution": float(importance[name]) if importance is not None and name in importance.index else None,
+                "mean_support_per_zone": diag["mean_support_per_zone"] if diag else None,
+                "mean_shrinkage_fraction": diag["mean_shrinkage_fraction"] if diag else None,
+            }
+
+    continuous_cols = model._continuous_main_effect_columns()
+    unsupported_regions = {col: _observed_range(model, col) for col in sorted(continuous_cols)}
+
+    conformal_summary = _conformal_summary(model.conformal_scores_) if model.conformal_scores_ is not None else None
+
+    card = {
+        "zoneboost_version": __version__,
+        "model_class": type(model).__name__,
+        "reproducibility": {
+            "params": model.get_params(),
+            "random_state": model.random_state,
+        },
+        "dataset_fingerprint": _dataset_fingerprint(X) if X is not None else None,
+        "fit_summary": {
+            "n_rounds_fit": len(rounds),
+            "best_n_rounds": model.best_n_rounds_,
+            "baseline": model.baseline_,
+            "final_train_rmse": model.train_rmse_[model.best_n_rounds_ - 1] if model.train_rmse_ else None,
+            "final_val_rmse": model.val_rmse_[model.best_n_rounds_ - 1] if model.val_rmse_ else None,
+        },
+        "zones": zones,
+        "terms": terms,
+        "shrinkage": {
+            "shrinkage_m": model.shrinkage_m,
+            "boundary_shrinkage_m": model.boundary_shrinkage_m if model.adaptive_boundary_smoothing else None,
+            "track_reliability_enabled": model.track_reliability,
+        },
+        "constraints": {
+            "monotonic_constraints": model.monotonic_constraints_,
+            "convexity_constraints": model.convexity_constraints_,
+            "bounded_effects": model.bounded_effects_,
+            "forbidden_interactions": sorted(sorted(pair) for pair in model.forbidden_interactions_),
+            "group_col": model.group_col_,
+            "n_effect_overrides": len(model.effect_overrides_),
+        },
+        "calibration": {
+            "loss": model.loss,
+            "quantile": model.quantile if model.loss == "quantile" else None,
+            "conformal_scores_available": model.conformal_scores_ is not None,
+            "conformal_scores_summary": conformal_summary,
+        },
+        "unsupported_regions": unsupported_regions,
+    }
+    return _jsonable(card)

zoneboost/_explain.py

@@ -0,0 +1,116 @@
+"""Exact, non-approximate prediction attribution.
+
+Unlike SHAP or LIME, this isn't a post-hoc approximation of a black-box
+model -- it's an algebraic decomposition of what the boosting loop already
+computed. Each round's contribution to the running score is
+
+    intercept + contributions @ weights
+
+where ``contributions`` holds one column per term (main effects +
+interactions + any adaptively-selected 3-way interactions) and
+``(intercept, weights)`` is that round's own Lasso fit of the residual on
+those per-term contributions (see ``_weak_learner._fit_lasso_weights``).
+Because the dot product is already a per-term sum, this expands exactly
+into
+
+    round_baseline + sum_i( weight_i * term_i )
+
+with round_baseline = intercept, a fixed per-round constant. Summing that
+across rounds gives, for every row, a set of per-term contributions that
+add up EXACTLY to the model's prediction (or, for the classifier, to the
+pre-sigmoid log-odds score) -- not an estimate of it.
+
+Each ``term_i`` itself is a soft, interpolated lookup for continuous
+columns (see ``_weak_learner._column_soft_zone_index`` and
+``_blend_1d``/``_blend_2d``/``_blend_3d``) rather than a hard single-zone
+value -- this module must use the exact same blend `predict` does, or the
+row-sum-equals-prediction invariant above would break.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from ._weak_learner import _blend_1d, _blend_2d, _blend_3d, _column_soft_zone_index
+
+__all__ = ["explain_rounds"]
+
+
+def explain_rounds(X: pd.DataFrame, rounds: list, baseline: float, learning_rate: float) -> pd.DataFrame:
+    """Per-row, per-term contribution breakdown across boosting rounds.
+
+    Parameters
+    ----------
+    X : DataFrame
+    rounds : list
+        A (possibly truncated) ``rounds_`` list, as stored on
+        ZoneBoostRegressor or one of ZoneBoostClassifier's internal
+        boosters.
+    baseline : float
+        The model's starting value before any round is applied.
+    learning_rate : float
+
+    Returns
+    -------
+    DataFrame of shape (len(X), n_terms + 1)
+        One column per term that appeared in any round -- each predictor's
+        own name for its main effect, ``"A x B"`` for an interaction pair,
+        ``"A x B x C"`` for a 3-way interaction -- plus a ``"baseline"``
+        column. Row sums equal the model's raw prediction (regression) or
+        log-odds score (classification) exactly.
+    """
+    n = len(X)
+    baseline_total = float(baseline)
+    term_totals: dict[str, np.ndarray] = {}
+
+    for round_ in rounds:
+        zone_info = round_["zone_info"]
+        main_effects = round_["main_effects"]
+        interactions = round_["interactions"]
+        triples = round_["triples"]
+        weights = round_["weights"]
+
+        n_terms = len(main_effects) + len(interactions) + len(triples)
+        if n_terms == 0:
+            continue
+        baseline_total += learning_rate * round_["intercept"]
+
+        # weights is aligned to main_effects -> interactions -> triples, in
+        # each dict's own (Python-guaranteed) insertion order -- the exact
+        # same order weak_learner_contributions builds its columns in, and
+        # the order the round's weights were fit against.
+        i = 0
+        for col, deviation in main_effects.items():
+            z_lo, z_hi, w = _column_soft_zone_index(X[col], zone_info[col])
+            share = learning_rate * weights[i] * _blend_1d(deviation, z_lo, z_hi, w)
+            term_totals.setdefault(col, np.zeros(n))
+            term_totals[col] += share
+            i += 1
+
+        for (a, b), deviation in interactions.items():
+            za_lo, za_hi, wa = _column_soft_zone_index(X[a], zone_info[a])
+            zb_lo, zb_hi, wb = _column_soft_zone_index(X[b], zone_info[b])
+            share = learning_rate * weights[i] * _blend_2d(deviation, za_lo, za_hi, wa, zb_lo, zb_hi, wb)
+            # Canonicalize: a pair's fit order varies round to round (each
+            # round samples/orders columns independently), so without
+            # sorting, "A x B" and "B x A" would fragment into separate
+            # columns instead of accumulating as the same term.
+            key = " x ".join(sorted((a, b)))
+            term_totals.setdefault(key, np.zeros(n))
+            term_totals[key] += share
+            i += 1
+
+        for (a, b, c), deviation in triples.items():
+            za_lo, za_hi, wa = _column_soft_zone_index(X[a], zone_info[a])
+            zb_lo, zb_hi, wb = _column_soft_zone_index(X[b], zone_info[b])
+            zc_lo, zc_hi, wc = _column_soft_zone_index(X[c], zone_info[c])
+            share = learning_rate * weights[i] * _blend_3d(
+                deviation, za_lo, za_hi, wa, zb_lo, zb_hi, wb, zc_lo, zc_hi, wc
+            )
+            key = " x ".join(sorted((a, b, c)))
+            term_totals.setdefault(key, np.zeros(n))
+            term_totals[key] += share
+            i += 1
+
+    return pd.DataFrame({"baseline": np.full(n, baseline_total), **term_totals}, index=X.index)