lens-eval 0.1.0__py3-none-any.whl

lens_eval/__init__.py

@@ -0,0 +1,55 @@
+"""lens-eval: interpretable multi-dimension text quality scoring.
+
+Public entrypoints:
+
+    from lens_eval import LENS
+    from lens_eval import semantic_score, nli_score, naturalness_score, emotion_score
+    from lens_eval import configure   # device, paths, naturalness mode/centroid
+
+See README.md for usage.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from .encoders import (
+    DIMENSIONS,
+    configure,
+    emotion_score,
+    featurize,
+    free,
+    naturalness_score,
+    nli_score,
+    semantic_score,
+)
+from .errors import (
+    AmbiguousTaskError,
+    CombinerBackendMissing,
+    DegenerateTargetError,
+    EncoderVersionMismatchError,
+    InsufficientDataError,
+    LensEvalError,
+    ReferenceModeError,
+)
+from .lens import LENS
+
+__all__ = [
+    "LENS",
+    "DIMENSIONS",
+    "configure",
+    "featurize",
+    "free",
+    "semantic_score",
+    "nli_score",
+    "naturalness_score",
+    "emotion_score",
+    "LensEvalError",
+    "InsufficientDataError",
+    "DegenerateTargetError",
+    "AmbiguousTaskError",
+    "ReferenceModeError",
+    "EncoderVersionMismatchError",
+    "CombinerBackendMissing",
+    "__version__",
+]

lens_eval/_validate.py

@@ -0,0 +1,85 @@
+"""Centralized structural validation for fit-time inputs.
+
+Both ``LENS.fit`` and the CLI route their inputs through this module so a
+missing ``groups`` array, an ambiguous task channel, or a malformed pairs
+matrix surfaces the *same* typed exception with the *same* error message
+regardless of where the call originated. The gateway is intentionally
+narrow — it does shape and channel checks only, no semantic validation.
+That belongs in the combiner layer.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Sequence, Tuple
+
+import numpy as np
+
+from .errors import AmbiguousTaskError
+
+
+TASK_CHANNELS = ("scores", "pairs", "ranks")
+TASK_TO_NAME = {"scores": "regression", "pairs": "pairwise", "ranks": "ranking"}
+
+
+def validate_task_channels(
+    *,
+    scores: Optional[Any] = None,
+    pairs:  Optional[Any] = None,
+    ranks:  Optional[Any] = None,
+    groups: Optional[Any] = None,
+) -> Tuple[str, str]:
+    """Resolve the task channel and validate channel-specific structure.
+
+    Returns ``(channel_name, task)`` where:
+      * ``channel_name`` is one of ``"scores" | "pairs" | "ranks"``.
+      * ``task``         is the inferred ``LENS`` task —
+                         ``"regression" | "pairwise" | "ranking"``.
+
+    Raises ``AmbiguousTaskError`` if zero or multiple channels are supplied.
+    Raises ``ValueError`` for shape / dtype / coverage issues with the chosen
+    channel (e.g. pairs must be ``(M, 2)``, ranking requires ``groups``).
+
+    Used by both ``LENS.fit`` and the CLI so the user-visible failure modes
+    are identical across entry points.
+    """
+    provided = [k for k, v in (("scores", scores), ("pairs", pairs), ("ranks", ranks))
+                if v is not None]
+    if len(provided) != 1:
+        # Zero ⇒ nothing to fit on. Two+ ⇒ which to optimise? Both are bad.
+        raise AmbiguousTaskError(
+            f"fit() / CLI needs exactly one of (scores, pairs, ranks); got {provided!r}"
+        )
+    channel = provided[0]
+    task = TASK_TO_NAME[channel]
+
+    if channel == "pairs":
+        arr = np.asarray(pairs)
+        if arr.ndim != 2 or arr.shape[1] != 2:
+            raise ValueError(
+                f"`pairs` must have shape (M, 2) of (winner_idx, loser_idx); got {arr.shape}"
+            )
+        if arr.size and not np.issubdtype(arr.dtype, np.integer):
+            # Allow float-typed indices that round to int, but reject strings /
+            # floats with fractional parts — those are user-error.
+            if not np.allclose(arr, np.round(arr)):
+                raise ValueError("`pairs` indices must be integer-valued.")
+    elif channel == "ranks":
+        # Ranking is the only channel that needs an auxiliary grouping array —
+        # lambdarank needs to know which rows belong to the same query. Without
+        # groups every row is treated as its own group, which silently
+        # collapses to "fit a regressor on rank labels" rather than learning
+        # within-query orderings. Reject upfront.
+        if groups is None:
+            raise ValueError(
+                "task='ranking' requires `groups` so lambdarank can isolate "
+                "within-query orderings — pass a per-row group-id array."
+            )
+        ranks_arr = np.asarray(ranks)
+        groups_arr = np.asarray(groups)
+        if ranks_arr.shape[0] != groups_arr.shape[0]:
+            raise ValueError(
+                f"`ranks` ({ranks_arr.shape[0]}) and `groups` ({groups_arr.shape[0]}) "
+                f"must align row-wise."
+            )
+
+    return channel, task

lens_eval/cli.py

@@ -0,0 +1,215 @@
+"""`lens-eval` CLI — thin wrapper around the Python API.
+
+    lens-eval fit \
+        --texts hyp.txt --refs ref.txt --scores scores.csv \
+        --output ./my-lens --task auto --verbose
+
+    lens-eval score \
+        --model ./my-lens \
+        --texts new_hyp.txt --refs new_ref.txt \
+        --output predictions.csv
+
+    lens-eval report ./my-lens --html report.html
+
+All three accept ``--features path.csv`` to skip encoding entirely. The
+features CSV must have one column per dimension; column order follows the
+LENS ``dimensions_used_`` for ``score``, or the user-passed ``--dimensions``
+for ``fit``.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+import numpy as np
+
+
+def _read_lines(path: str | Path) -> List[str]:
+    p = Path(path)
+    text = p.read_text(encoding="utf-8")
+    if p.suffix.lower() == ".csv":
+        return [row[0] for row in csv.reader(text.splitlines()) if row]
+    return [ln for ln in text.splitlines() if ln]
+
+
+def _read_scalar_csv(path: str | Path) -> np.ndarray:
+    rows: List[float] = []
+    with open(path, newline="") as f:
+        for row in csv.reader(f):
+            if not row:
+                continue
+            try:
+                rows.append(float(row[0]))
+            except ValueError:
+                # Header row — skip silently.
+                continue
+    return np.asarray(rows, dtype=float)
+
+
+def _read_features_csv(path: str | Path) -> np.ndarray:
+    arr = []
+    with open(path, newline="") as f:
+        for row in csv.reader(f):
+            if not row:
+                continue
+            try:
+                arr.append([float(x) for x in row])
+            except ValueError:
+                continue
+    return np.asarray(arr, dtype=float)
+
+
+def _read_pairs_csv(path: str | Path) -> np.ndarray:
+    pairs = []
+    with open(path, newline="") as f:
+        for row in csv.reader(f):
+            if not row:
+                continue
+            try:
+                a, b = int(row[0]), int(row[1])
+            except (ValueError, IndexError):
+                continue
+            pairs.append((a, b))
+    if not pairs:
+        raise ValueError(f"no pair rows parsed from {path}")
+    return np.asarray(pairs, dtype=int)
+
+
+def _read_int_column_csv(path: str | Path) -> np.ndarray:
+    vals: List[int] = []
+    with open(path, newline="") as f:
+        for row in csv.reader(f):
+            if not row:
+                continue
+            try:
+                vals.append(int(row[0]))
+            except ValueError:
+                continue
+    if not vals:
+        raise ValueError(f"no integer rows parsed from {path}")
+    return np.asarray(vals, dtype=int)
+
+
+def _cmd_fit(args) -> int:
+    from . import encoders as enc
+    from ._validate import validate_task_channels
+    from .lens import LENS
+
+    if args.naturalness_mode:
+        enc.configure(naturalness_mode=args.naturalness_mode)
+
+    texts  = _read_lines(args.texts)           if args.texts    else None
+    refs   = _read_lines(args.refs)            if args.refs     else None
+    feats  = _read_features_csv(args.features) if args.features else None
+    y      = _read_scalar_csv(args.scores)     if args.scores   else None
+    pairs  = _read_pairs_csv(args.pairs)       if args.pairs    else None
+    ranks  = _read_int_column_csv(args.ranks)  if args.ranks    else None
+    groups = _read_int_column_csv(args.groups) if args.groups   else None
+
+    try:
+        channel, _ = validate_task_channels(
+            scores=y, pairs=pairs, ranks=ranks, groups=groups,
+        )
+    except Exception as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+    lens = LENS()
+    lens.fit(
+        texts=texts,
+        references=refs,
+        features=feats,
+        scores=y, pairs=pairs, ranks=ranks, groups=groups,
+        task=args.task,
+        target_type=args.target_type,
+        selection=args.selection,
+        verbose=args.verbose,
+    )
+    lens.save(args.output)
+    if args.html:
+        lens.report_html(args.html)
+    print(f"saved fitted LENS to {args.output} ({channel} channel)")
+    return 0
+
+
+def _cmd_score(args) -> int:
+    from .lens import LENS
+
+    lens = LENS.load(args.model)
+    texts = _read_lines(args.texts)            if args.texts    else None
+    refs  = _read_lines(args.refs)             if args.refs     else None
+    feats = _read_features_csv(args.features)  if args.features else None
+
+    if texts is None and feats is None:
+        print("error: provide --texts or --features", file=sys.stderr)
+        return 2
+
+    scores = lens.score(texts, references=refs, features=feats)
+
+    out = Path(args.output)
+    with open(out, "w", newline="") as f:
+        w = csv.writer(f)
+        w.writerow(["score"])
+        for s in scores:
+            w.writerow([float(s)])
+    print(f"wrote {len(scores)} scores to {out}")
+    return 0
+
+
+def _cmd_report(args) -> int:
+    from .lens import LENS
+
+    lens = LENS.load(args.model)
+    lens.report()
+    if args.html:
+        lens.report_html(args.html)
+        print(f"wrote HTML report to {args.html}")
+    return 0
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    p = argparse.ArgumentParser(prog="lens-eval", description="lens-eval CLI")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    pf = sub.add_parser("fit", help="fit a LENS combiner")
+    pf.add_argument("--texts",    help="path to candidate texts (txt or csv)")
+    pf.add_argument("--refs",     help="path to references (txt or csv)")
+    pf.add_argument("--features", help="path to precomputed feature matrix CSV (D columns)")
+    pf.add_argument("--scores",   help="scalar targets CSV (1 column)")
+    pf.add_argument("--pairs",    help="pairwise CSV: 2 columns (winner_idx, loser_idx)")
+    pf.add_argument("--ranks",    help="ranking CSV: 1 column of integer ranks")
+    pf.add_argument("--groups",   help="ranking grouping CSV: 1 column of group ids — REQUIRED with --ranks")
+    pf.add_argument("--output",   required=True, help="where to save the fitted LENS directory")
+    pf.add_argument("--task",        default="auto", choices=("auto", "regression", "pairwise", "ranking"))
+    pf.add_argument("--target-type", default="auto",
+                    choices=("auto", "bounded", "ordinal", "binary", "continuous"))
+    pf.add_argument("--selection",   default="auto",
+                    choices=("auto", "fast", "exhaustive", "glm", "glm_interactions", "ebm", "gbm"))
+    pf.add_argument("--naturalness-mode", default="centroid", choices=("centroid", "reference"))
+    pf.add_argument("--html",    help="optional: also write an HTML report to this path")
+    pf.add_argument("--verbose", action="store_true")
+    pf.set_defaults(func=_cmd_fit)
+
+    ps = sub.add_parser("score", help="score new texts with a saved LENS")
+    ps.add_argument("--model",    required=True, help="path to a saved LENS directory")
+    ps.add_argument("--texts",    help="path to candidate texts (txt or csv)")
+    ps.add_argument("--refs",     help="path to references (txt or csv)")
+    ps.add_argument("--features", help="path to precomputed feature matrix CSV (D columns)")
+    ps.add_argument("--output",   required=True, help="output CSV path for predictions")
+    ps.set_defaults(func=_cmd_score)
+
+    pr = sub.add_parser("report", help="print/render the selection report from a saved LENS")
+    pr.add_argument("model", help="path to a saved LENS directory")
+    pr.add_argument("--html", help="optional: write an HTML report to this path too")
+    pr.set_defaults(func=_cmd_report)
+
+    args = p.parse_args(argv)
+    return int(args.func(args) or 0)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

lens_eval/combiners/__init__.py

@@ -0,0 +1,93 @@
+"""Combiner registry.
+
+Each combiner implements the BaseCombiner protocol. The `AVAILABLE` dict maps
+combiner type names → (factory, is_backend_available) so the selection layer can
+filter to what's actually installable without having to import each module
+eagerly.
+"""
+
+from __future__ import annotations
+
+from typing import Callable, Dict, Optional, Tuple
+
+from .base import BaseCombiner, expand_pairs
+from .glm import GLMCombiner
+from .glm_interactions import GLMInteractionsCombiner
+
+
+def _ebm_available() -> bool:
+    # ImportError → package missing. OSError → native lib missing (e.g. some
+    # interpret-ml builds without their native deps). Either way: not usable.
+    try:
+        import interpret.glassbox  # noqa: F401
+    except Exception:
+        return False
+    return True
+
+
+def _gbm_available() -> bool:
+    # lightgbm's ctypes load can OSError on macOS without libomp; treat as
+    # "not installed" rather than crashing the candidate filter.
+    try:
+        import lightgbm  # noqa: F401
+    except Exception:
+        return False
+    return True
+
+
+def _ebm_factory(**kwargs) -> BaseCombiner:
+    # Factory wraps the import so AVAILABLE can be built without importing
+    # interpret-ml — the module is only touched when the user actually
+    # picks this combiner.
+    from .ebm import EBMCombiner
+    return EBMCombiner(**kwargs)
+
+
+def _gbm_factory(**kwargs) -> BaseCombiner:
+    # Same deferred-import pattern as the EBM factory.
+    from .gbm import GBMCombiner
+    return GBMCombiner(**kwargs)
+
+
+# Registry: name → (factory, availability_check). The factory is called only
+# when this combiner wins selection; the check runs during candidate-filter
+# without any heavy imports.
+AVAILABLE: Dict[str, Tuple[Callable[..., BaseCombiner], Callable[[], bool]]] = {
+    "glm":              (lambda **kw: GLMCombiner(**kw),             lambda: True),
+    "glm_interactions": (lambda **kw: GLMInteractionsCombiner(**kw), lambda: True),
+    "ebm":              (_ebm_factory,                                _ebm_available),
+    "gbm":              (_gbm_factory,                                _gbm_available),
+}
+
+# Capacity ordering: simpler first. Used by the 1-SE selection rule to break
+# ties toward lower-capacity (more interpretable, less prone to overfit).
+CAPACITY_ORDER: Tuple[str, ...] = ("glm", "glm_interactions", "ebm", "gbm")
+
+
+def make(combiner_type: str, **kwargs) -> BaseCombiner:
+    """Build a combiner by name."""
+    if combiner_type not in AVAILABLE:
+        raise ValueError(
+            f"unknown combiner {combiner_type!r}; choose from {list(AVAILABLE)}"
+        )
+    factory, check = AVAILABLE[combiner_type]
+    # Double-check at construction time — selection layer should have
+    # filtered already, but guard against a direct `make()` call too.
+    if not check():
+        from ..errors import CombinerBackendMissing
+        raise CombinerBackendMissing(
+            f"combiner {combiner_type!r} requires an optional dependency. "
+            f"Install with: pip install 'lens-eval[{combiner_type}]'"
+        )
+    return factory(**kwargs)
+
+
+__all__ = [
+    "BaseCombiner",
+    "GLMCombiner",
+    "GLMInteractionsCombiner",
+    "AVAILABLE",
+    "CAPACITY_ORDER",
+    "expand_pairs",
+    "make",
+]

lens_eval/combiners/base.py

@@ -0,0 +1,93 @@
+"""BaseCombiner: the protocol every combiner tier implements.
+
+Invariants:
+
+1. ``predict(X)`` returns scores in target space (logit/latent/raw — the
+   combiner decides). LENS applies any inverse link before returning to the
+   user; ranking only needs ordering, so we don't enforce calibration here.
+2. ``contributions(X)`` returns an (N, D) attribution matrix. Linear combiners
+   return ``X * coef``; EBM/GBM return per-feature SHAP-style contributions.
+3. ``coefficients()`` returns a dict of interpretable parameters used by the
+   report layer.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+import numpy as np
+
+
+@dataclass
+class BaseCombiner(ABC):
+    """Common state every combiner carries."""
+
+    task: str = "regression"            # 'regression' | 'pairwise' | 'ranking'
+    target_type: str = "continuous"     # 'bounded' | 'ordinal' | 'binary' | 'continuous'
+    link: str = "identity"              # 'identity' | 'logit' | 'cumulative_logit'
+    random_state: int = 42
+    hyperparameters: Dict[str, Any] = field(default_factory=dict)
+    feature_names: Optional[list] = None
+
+    # Subclasses MUST set this to True at the end of fit().
+    is_fitted_: bool = field(default=False, init=False)
+
+    @abstractmethod
+    def fit(
+        self,
+        X: np.ndarray,
+        y: Optional[np.ndarray] = None,
+        *,
+        pairs: Optional[np.ndarray] = None,
+        ranks: Optional[np.ndarray] = None,
+        groups: Optional[np.ndarray] = None,
+    ) -> "BaseCombiner":
+        ...
+
+    @abstractmethod
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        """Score in target space; higher = better quality."""
+
+    @abstractmethod
+    def contributions(self, X: np.ndarray) -> np.ndarray:
+        """Per-sample per-feature contribution matrix, shape (N, D)."""
+
+    def coefficients(self) -> Dict[str, Any]:
+        """Interpretable parameters. Override to expose more."""
+        return {}
+
+    def _check_fitted(self) -> None:
+        if not self.is_fitted_:
+            raise RuntimeError(
+                f"{type(self).__name__} is not fitted; call .fit() before prediction."
+            )
+
+    @property
+    def type_name(self) -> str:
+        return _TYPE_NAME.get(type(self).__name__, type(self).__name__.lower())
+
+
+_TYPE_NAME = {
+    "GLMCombiner":              "glm",
+    "GLMInteractionsCombiner":  "glm_interactions",
+    "EBMCombiner":              "ebm",
+    "GBMCombiner":              "gbm",
+}
+
+
+def expand_pairs(X: np.ndarray, pairs: np.ndarray):
+    """Bradley-Terry antisymmetric expansion.
+
+    Each pair ``(a, b)`` (a beat b) becomes two training rows: ``(x_a - x_b, 1)``
+    and ``(x_b - x_a, 0)``. Returns ``(X_diff, y_bin)`` of length ``2 * len(pairs)``.
+    """
+    pairs = np.asarray(pairs, dtype=int)
+    diff = X[pairs[:, 0]] - X[pairs[:, 1]]
+    X_use = np.vstack([diff, -diff])
+    y_use = np.concatenate([
+        np.ones(len(pairs), dtype=int),
+        np.zeros(len(pairs), dtype=int),
+    ])
+    return X_use, y_use

lens_eval/combiners/ebm.py

@@ -0,0 +1,141 @@
+"""EBM combiner — wraps interpret-ml's Explainable Boosting Machine."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+import numpy as np
+
+from .base import BaseCombiner, expand_pairs
+
+
+@dataclass
+class EBMCombiner(BaseCombiner):
+    max_bins:     int = 256
+    outer_bags:   int = 8
+    interactions: Any = "auto"   # 0, int, or "auto"
+
+    model_: Optional[Any] = field(default=None, init=False, repr=False)
+
+    def fit(
+        self,
+        X: np.ndarray,
+        y: Optional[np.ndarray] = None,
+        *,
+        pairs: Optional[np.ndarray] = None,
+        ranks: Optional[np.ndarray] = None,
+        groups: Optional[np.ndarray] = None,
+    ) -> "EBMCombiner":
+        # Deferred import so the module is importable without interpret-ml.
+        from interpret.glassbox import (
+            ExplainableBoostingClassifier,
+            ExplainableBoostingRegressor,
+        )
+
+        X = np.asarray(X, dtype=float)
+
+        # `interactions`: number of pairwise interactions EBM auto-discovers
+        # via FAST. n_features - 1 is a sensible default at D=4 (3 pairs).
+        inter = max(0, X.shape[1] - 1) if self.interactions == "auto" else self.interactions
+
+        common = dict(
+            max_bins=self.max_bins,
+            outer_bags=self.outer_bags,
+            interactions=inter,
+            random_state=self.random_state,
+        )
+        # Push real dim names through to interpret-ml so explain_global /
+        # explain_local don't return "feature_0000" — that breaks both
+        # LENS.feature_importance() (name-based lookup) and the text report
+        # (interactions render as "feature_0000 & feature_0001" otherwise).
+        if self.feature_names:
+            common["feature_names"] = list(self.feature_names)
+
+        if self.task == "pairwise":
+            if pairs is not None:
+                X_use, y_use = expand_pairs(X, pairs)
+            else:
+                X_use = X
+                y_use = np.asarray(y, dtype=int).ravel()
+            self.model_ = ExplainableBoostingClassifier(**common)
+            self.model_.fit(X_use, y_use)
+        elif self.target_type == "binary":
+            self.model_ = ExplainableBoostingClassifier(**common)
+            self.model_.fit(X, np.asarray(y, dtype=int).ravel())
+        else:
+            self.model_ = ExplainableBoostingRegressor(**common)
+            self.model_.fit(X, np.asarray(y, dtype=float).ravel())
+
+        self.is_fitted_ = True
+        return self
+
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        self._check_fitted()
+        X = np.asarray(X, dtype=float)
+        # Classifier → positive-class probability, matching GLM.predict shape.
+        if self.task == "pairwise" or self.target_type == "binary":
+            return self.model_.predict_proba(X)[:, 1]
+        return self.model_.predict(X)
+
+    def contributions(self, X: np.ndarray) -> np.ndarray:
+        """Per-feature local contributions via interpret-ml's ``explain_local``.
+
+        Interaction-term contributions are split 50/50 between their parents so
+        the result stays (N, D_base). Falls back to finite differences when
+        ``explain_local`` raises (the API shifts across interpret-ml versions).
+        """
+        self._check_fitted()
+        X = np.asarray(X, dtype=float)
+        D = X.shape[1]
+        try:
+            explanation = self.model_.explain_local(X)
+            contribs = np.zeros((X.shape[0], D), dtype=float)
+            base_names = (list(self.model_.feature_names_in_)
+                          if hasattr(self.model_, "feature_names_in_")
+                          else [f"feature_{i:04d}" for i in range(D)])
+            name_to_idx = {n: i for i, n in enumerate(base_names)}
+            for row_idx in range(X.shape[0]):
+                row = explanation.data(row_idx)
+                if row is None:
+                    continue
+                for n, s in zip(row["names"], row["scores"]):
+                    n = str(n)
+                    if " & " in n:
+                        a, b = n.split(" & ", 1)
+                        if a in name_to_idx and b in name_to_idx:
+                            contribs[row_idx, name_to_idx[a]] += 0.5 * float(s)
+                            contribs[row_idx, name_to_idx[b]] += 0.5 * float(s)
+                    elif n in name_to_idx:
+                        contribs[row_idx, name_to_idx[n]] += float(s)
+            return contribs
+        except Exception:
+            return _finite_diff_contribs(self.predict, X)
+
+    def coefficients(self) -> Dict[str, Any]:
+        out: Dict[str, Any] = {}
+        if self.model_ is None:
+            return out
+        try:
+            g = self.model_.explain_global().data()
+            out["feature_names"] = list(g.get("names", []))
+            out["feature_importances"] = list(g.get("scores", []))
+        except Exception:
+            pass
+        out["hyperparameters"] = {
+            "max_bins":     self.max_bins,
+            "outer_bags":   self.outer_bags,
+            "interactions": self.interactions,
+        }
+        return out
+
+
+def _finite_diff_contribs(predict_fn, X: np.ndarray, eps: float = 1e-3) -> np.ndarray:
+    """Centred-difference fallback: ∂f/∂x_j × x_j (Taylor expansion around 0)."""
+    D = X.shape[1]
+    out = np.zeros_like(X, dtype=float)
+    for j in range(D):
+        Xp = X.copy(); Xp[:, j] += eps
+        Xm = X.copy(); Xm[:, j] -= eps
+        out[:, j] = (predict_fn(Xp) - predict_fn(Xm)) / (2 * eps) * X[:, j]
+    return out