contracts

Adapter-agnostic data contracts consumed by the TRIAD core.

Exact mode: TermData (per-term bin tensors: missing bin at index 0, unknown bin at index -1 along each axis) plus BinnedTerm (per-instance bin lookups). Approximate mode: ShapData (dense per-instance attributions from the deployed model plus bag-replica variance).

BinnedTerm dataclass

BinnedTerm(
    term_idx: int,
    bin_idx: tuple[ndarray, ...],
    missing: ndarray,
    oov: ndarray,
    decay: ndarray,
)

Per-instance bin lookups for one term at explanation time.

n_samples property

n_samples: int

Number of instances covered by this binning.

ModelData dataclass

ModelData(
    terms: tuple[TermData, ...],
    intercept: float,
    feature_names: tuple[str, ...],
)

Everything the exact-mode core needs from a fitted additive model.

ShapData dataclass

ShapData(
    phi: ndarray,
    base: float,
    v: ndarray,
    missing: ndarray,
    oov: ndarray,
    feature_names: tuple[str, ...],
)

Approximate-mode contract: deployed-model attributions + replica variance.

phi comes from the deployed model (e.g. LightGBM pred_contrib, base column excluded); v is the per-instance, per-feature variance of attributions across bag replicas (ddof=1). C1/C2 hold on phi; v only enters through the support weight.

n_features property

n_features: int

Number of features.

n_samples property

n_samples: int

Number of explained instances.

TermData dataclass

TermData(
    term_idx: int,
    feature_idxs: tuple[int, ...],
    f: ndarray,
    v: ndarray,
    n: ndarray,
)

Fitted bin-level data for one additive term.

Tensors f (centered bin scores), v (per-bin sampling variance) and n (per-bin training mass) share one shape; along each axis, index 0 is the missing bin and index -1 the unknown bin.

is_pair property

is_pair: bool

True for a pairwise interaction term.