contextattr 0.1.0__py3-none-any.whl

contextattr/methods/interactions.py

@@ -0,0 +1,215 @@
+"""The interaction methods (docs/methods.md), through shapiq, the extra [interactions]: Faith-Banzhaf and Faith-Shap
+(every interaction up to an order; small n), SPEX (sparse interactions up to a degree, 5 unless set; large n) and
+ProxySPEX (sparse, about a tenth of SPEX's masks). shapiq chooses its own masks and asks the value of each through
+the game it is given.
+
+Each gives its answer as Faith-Banzhaf (FBII) coefficients: at an order at least the surrogate's degree they are its
+Möbius coefficients, the product basis Surrogate uses, so predictions, R², removal and the indices of App. C apply as
+for the per-unit methods (Faith-Shap keeps its own FSII coefficients, a product-basis polynomial too). shapiq is
+imported only when one of these runs: its import takes 25–45 s and galois's first codes about 15 s more on a shared
+two-CPU machine (measured 2026-11-06), which `import contextattr` should not wait for."""
+
+from __future__ import annotations
+
+import itertools
+import random
+from contextlib import contextmanager
+
+import numpy as np
+
+from .base import Method, Surrogate, check_budget
+
+
+@contextmanager
+def _global_seed(seed: int):
+    """Seed numpy's and Python's global generators for one approximation, and give the caller's states back after.
+    SPEX's codes and delays are drawn by sparse_transform from numpy's global generator, which shapiq's random_state
+    does not reach: unseeded, the same seed gave other masks each run (found 2026-11-07, when a re-run found none of
+    them in the cache). The game is called inside, so a wrapper drawing from these generators draws seeded values."""
+    np_state, py_state = np.random.get_state(), random.getstate()
+    np.random.seed(seed)
+    random.seed(seed)
+    try:
+        yield
+    finally:
+        np.random.set_state(np_state)
+        random.setstate(py_state)
+
+
+class ShapiqMethod(Method):
+    """A shapiq approximator run against the game; `make(shapiq, n, seed)` builds it, `finish` reads its answer."""
+
+    index = "FBII"
+
+    def __init__(self, max_order: int = 2):
+        if isinstance(max_order, bool) or not isinstance(max_order, int) or max_order < 1:
+            raise ValueError(f"{type(self).__name__}: max_order must be a positive integer")
+        self.max_order = max_order
+
+    def make(self, shapiq, n: int, seed: int):
+        raise NotImplementedError
+
+    def check(self, approximator, n: int, budget: int) -> None:
+        """Called before the first value is asked: refuse what shapiq changed on its own."""
+
+    def run(self, game, n: int, budget: int, rng: np.random.Generator) -> tuple[Surrogate, int]:
+        check_budget(self.name, budget, 2)
+        import shapiq   # noqa: PLC0415 - imported only here, see the module's note
+
+        asked = []
+        seed = int(rng.integers(2 ** 31))
+        approximator = self.make(shapiq, n, seed)
+
+        def g(masks):
+            if not asked:
+                self.check(approximator, n, budget)
+            masks = np.array(masks, dtype=bool)
+            values = np.asarray(game(masks), dtype=float)
+            asked.append((masks, values))
+            return values
+
+        with _global_seed(seed):
+            values = approximator.approximate(budget, g)
+        return self.finish(values, n, asked), int(sum(len(m) for m, _ in asked))
+
+    def finish(self, values, n: int, asked: list) -> Surrogate:
+        """The surrogate from shapiq's answer; `asked` holds every (masks, values) batch shapiq asked for."""
+        return from_interaction_values(values, n)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(max_order={self.max_order})"
+
+
+class FaithBanzhaf(ShapiqMethod):
+    """Faith-Banzhaf (Tsai 2023): the best polynomial of order max_order under uniform weights over masks. shapiq's
+    RegressionFBII draws the masks. With `ridge` (the default since 2026-11-09), they are fitted as SPEX does (B.3:
+    cross-validated ridge regression; B.1: scikit-learn's RidgeCV), by `ridge_fit`; but when every one of the 2ⁿ masks
+    was asked, by shapiq's least squares, which then gives the index exactly (ridge could only shrink it). Least squares
+    on sampled masks (`ridge=False`) overfits as the terms near the masks. With noise of 0.3 of the function's spread, on
+    the same masks (measured 2026-11-08): R² −0.08 against ridge's 0.79 at n = 31, order 3 (4,992 terms on 5,376 masks),
+    where ridge took 9 min on one CPU against 5 s; within 0.005 of ridge at 2,017 terms or fewer on 5,376–6,912 masks."""
+
+    name = "faithbanzhaf"
+
+    def __init__(self, max_order: int = 2, ridge: bool = True):
+        super().__init__(max_order=max_order)
+        self.ridge = bool(ridge)
+
+    def make(self, shapiq, n, seed):
+        return shapiq.RegressionFBII(n, max_order=self.max_order, random_state=seed)
+
+    def finish(self, values, n, asked):
+        masks = np.concatenate([m for m, _ in asked])
+        if not self.ridge or len(np.unique(masks, axis=0)) == 2 ** n:
+            return super().finish(values, n, asked)
+        return ridge_fit(masks, np.concatenate([v for _, v in asked]), self.max_order)
+
+    def __repr__(self) -> str:   # always names the fit: before 2026-11-09, FaithBanzhaf(max_order=2) meant least squares
+        return f"FaithBanzhaf(max_order={self.max_order}, ridge={self.ridge})"
+
+
+class FaithShap(ShapiqMethod):
+    """Faith-Shap (Tsai 2023): the best polynomial of order max_order under the Shapley kernel's weights."""
+
+    name = "faithshap"
+    index = "FSII"
+
+    def make(self, shapiq, n, seed):
+        return shapiq.RegressionFSII(n, max_order=self.max_order, random_state=seed)
+
+
+class SPEX(ShapiqMethod):
+    """SPEX (Kang 2025, §5): sparse Fourier recovery with masks from channel codes; interactions up to `degree`
+    (SPEX's t), reported in full as FBII of that order, so the surrogate is SPEX's own. `chase_depth` is the soft
+    decoder's Chase depth (App. A, Algorithm 3, which does not give its value): by default (since 2026-11-09) 2t, as
+    the SPEX authors' spectralexplain, whose predictions this SPEX then gives on the same masks (measured 2026-11-08 in
+    8 of 8 noisy cases; with t, shapiq's own, R² was 0.003–0.070 lower there, and each fit 1–11 s faster).
+    `chase_depth=degree` is shapiq's SPEX exactly (sparse_transform takes no depth as t)."""
+
+    name = "spex"
+
+    def __init__(self, degree: int = 5, chase_depth: int | None = None):
+        super().__init__(max_order=degree)
+        if chase_depth is not None and (isinstance(chase_depth, bool) or not isinstance(chase_depth, int)
+                                        or chase_depth < 1):
+            raise ValueError("SPEX: chase_depth must be a positive integer, or None for 2·degree")
+        self.chase_depth = 2 * degree if chase_depth is None else chase_depth
+
+    def make(self, shapiq, n, seed):
+        approximator = shapiq.SPEX(n=n, max_order=self.max_order, index="FBII", degree_parameter=self.max_order,
+                                   random_state=seed)
+        from sparse_transform.qsft.utils.query import get_bch_decoder  # noqa: PLC0415 - a shapiq dependency
+        approximator.decoder_args["source_decoder"] = get_bch_decoder(n, self.max_order, "soft",
+                                                                      chase_depth=self.chase_depth)
+        return approximator
+
+    def check(self, approximator, n, budget):
+        """shapiq lowers the code's degree t when the budget is too small for it (at n = 20, measured 2026-11-06: to 2
+        at 300 masks, to 4 at 600, none from 1,200), which would explain at a degree other than the one named."""
+        t = getattr(approximator, "degree_parameter", self.max_order)
+        if t < self.max_order:
+            raise ValueError(f"SPEX: a budget of {budget} masks is too small for degree {self.max_order} at n = {n} "
+                             f"(shapiq would lower it to {t}); give a larger budget (SPEX Table 2) or "
+                             f"SPEX(degree={t})")
+
+    def __repr__(self) -> str:   # always names the depth: before 2026-11-09, SPEX(degree=5) meant depth t
+        return f"SPEX(degree={self.max_order}, chase_depth={self.chase_depth})"
+
+
+class ProxySPEX(ShapiqMethod):
+    """ProxySPEX (Butler 2025): gradient-boosted trees fitted to uniform masks, their Fourier transform read off the
+    trees. With `hpo` (shapiq's default) LightGBM is chosen by 5-fold cross-validation over depth 3 or 5, 500 or 1,000
+    trees and learning rate 0.01 or 0.1, shapiq's grid for Butler 2025's proxy (scikit-learn's GridSearchCV); without
+    it, LightGBM's own defaults (100 trees of up to 31 leaves, any depth). LightGBM takes as many threads as the
+    process may use CPUs, whatever OMP_NUM_THREADS says (LOKY_MAX_CPU_COUNT limits it)."""
+
+    name = "proxyspex"
+
+    def __init__(self, max_order: int = 5, hpo: bool = True):
+        super().__init__(max_order=max_order)
+        self.hpo = bool(hpo)
+
+    def make(self, shapiq, n, seed):
+        return shapiq.ProxySPEX(n=n, max_order=self.max_order, index="FBII", hpo=self.hpo, random_state=seed)
+
+    def __repr__(self) -> str:
+        return f"ProxySPEX(max_order={self.max_order}, hpo={self.hpo})"
+
+
+def ridge_fit(masks, values, order: int) -> Surrogate:
+    """Every term up to `order` fitted by scikit-learn's RidgeCV, the penalty chosen by leave-one-out among 100 from
+    1e-6 to 1e6, the intercept unpenalised. The fit is in the ±1 basis z = 1 − 2m (orthonormal under uniform masks, so
+    the penalty shrinks every term alike); its terms are then written in the product basis Surrogate uses:
+    Π_{i∈S} (1 − 2mᵢ) = Σ_{T⊆S} (−2)^|T| Π_{i∈T} mᵢ."""
+    from sklearn.linear_model import RidgeCV  # noqa: PLC0415 - as LIME and ContextCite import theirs
+
+    masks = np.asarray(masks, dtype=bool)
+    n = masks.shape[1]
+    sets = [list(s) for k in range(1, order + 1) for s in itertools.combinations(range(n), k)]
+    z = 1.0 - 2.0 * masks
+    x = np.empty((len(masks), len(sets)))
+    for j, s in enumerate(sets):
+        x[:, j] = z[:, s].prod(axis=1)
+    model = RidgeCV(alphas=np.logspace(-6, 6, 100)).fit(x, np.asarray(values, dtype=float))
+    terms = {(): float(model.intercept_)}
+    for s, c in zip(sets, model.coef_):
+        for k in range(len(s) + 1):
+            for t in itertools.combinations(s, k):
+                terms[t] = terms.get(t, 0.0) + (-2.0) ** k * float(c)
+    intercept = terms.pop(())
+    scores = np.zeros(n)
+    for t in [t for t in terms if len(t) == 1]:
+        scores[t[0]] = terms.pop(t)
+    return Surrogate(intercept=intercept, scores=scores, interactions={t: w for t, w in terms.items() if w != 0.0})
+
+
+def from_interaction_values(values, n: int) -> Surrogate:
+    """A Surrogate from shapiq's InteractionValues of a product-basis index (FBII, FSII): () is the intercept, single
+    units the scores, larger sets the interactions."""
+    terms = {tuple(int(i) for i in s): float(v) for s, v in values.dict_values.items()}
+    intercept = terms.pop((), float(getattr(values, "baseline_value", 0.0)))
+    scores = np.zeros(n)
+    for s in [s for s in terms if len(s) == 1]:
+        scores[s[0]] = terms.pop(s)
+    return Surrogate(intercept=intercept, scores=scores,
+                     interactions={s: w for s, w in terms.items() if s and w != 0.0})

contextattr/methods/kernelshap.py

@@ -0,0 +1,114 @@
+"""KernelSHAP (Lundberg & Lee 2017; SPEX B.3): Shapley values as the weighted least-squares fit of the Shapley kernel,
+with the empty and the full prompt fitted exactly (efficiency: the scores add up to f(1) − f(0)).
+
+The masks are drawn as the shap library's KernelExplainer draws them. The kernel puts most weight on the smallest and
+the largest coalitions, so whole size groups are enumerated first, sizes 1 and n − 1, then 2 and n − 2, …, while the
+budget holds them; each enumerated mask gets its kernel weight π(s) = (n − 1) / (C(n, s)·s·(n − s)). The rest of the
+budget is drawn from the sizes left, size s with probability ∝ C(n, s)·π(s), each mask beside its complement (paired
+sampling), and these masks share the kernel weight of the sizes left equally. A budget of 2^n enumerates every mask
+and gives the exact Shapley values; one of 2n + 2 already completes sizes 1 and n − 1, so the fit is always determined.
+
+The kernel's denominator C(n, s)·s·(n − s) outgrows numpy's 64-bit integers from n = 57, and C(n, s) a float from
+n ≈ 1,030, so the weights come from Python's exact integers: a size group's mass C(n, s)·π(s) = (n − 1) / (s·(n − s))
+needs no C(n, s) at all, and the weights of masks from elsewhere are taken in logarithms, relative to the largest
+(the fit does not change with their scale).
+"""
+
+from __future__ import annotations
+
+import itertools
+from math import comb, exp, log
+
+import numpy as np
+
+from .base import Method, Surrogate, check_budget, least_squares
+
+
+class KernelSHAP(Method):
+    name = "kernelshap"
+
+    def __init__(self, paired: bool = True):
+        self.paired = bool(paired)
+        self._design: tuple[np.ndarray, np.ndarray] | None = None
+
+    @staticmethod
+    def least_budget(n: int) -> int:
+        return 2 if n == 1 else min(2 ** n, 2 * n + 2)
+
+    def masks(self, n: int, budget: int, rng: np.random.Generator) -> np.ndarray:
+        check_budget(self.name, budget, self.least_budget(n))
+        rows, weights = [np.zeros(n, dtype=bool), np.ones(n, dtype=bool)], [0.0, 0.0]
+        left = budget - 2
+        done: set[int] = set()
+        for s in range(1, n // 2 + 1):                     # the kernel's mass of a size group falls as s nears n/2
+            group = [s] if 2 * s == n else [s, n - s]
+            count = sum(comb(n, k) for k in group)
+            if count > left:
+                break
+            for k in group:
+                for subset in itertools.combinations(range(n), k):
+                    row = np.zeros(n, dtype=bool)
+                    row[list(subset)] = True
+                    rows.append(row)
+                    weights.append(_kernel(n, k))
+            left -= count
+            done.update(group)
+        sizes = [k for k in range(1, n) if k not in done]
+        draws = left - left % 2 if self.paired else left      # every drawn mask beside its complement: an even count
+        if sizes and draws > 0:
+            mass = np.array([(n - 1) / (k * (n - k)) for k in sizes])      # C(n, k)·π(k), Python's integers
+            drawn = []
+            while len(drawn) < draws:
+                row = np.zeros(n, dtype=bool)
+                row[rng.permutation(n)[: rng.choice(sizes, p=mass / mass.sum())]] = True
+                drawn.append(row)
+                if self.paired:
+                    drawn.append(~row)
+            rows += drawn
+            weights += [mass.sum() / len(drawn)] * len(drawn)
+        masks = np.array(rows)
+        self._design = (masks.copy(), np.array(weights))
+        return masks
+
+    def fit(self, masks: np.ndarray, values: np.ndarray) -> Surrogate:
+        masks, values = np.asarray(masks, dtype=bool), np.asarray(values, dtype=float)
+        n = masks.shape[1]
+        size = masks.sum(axis=1)
+        empty, full = np.flatnonzero(size == 0), np.flatnonzero(size == n)
+        if not len(empty) or not len(full):
+            raise ValueError("KernelSHAP needs the empty and the full prompt among its masks")
+        f0, f1 = values[empty[0]], values[full[0]]
+        if n == 1:
+            return Surrogate(intercept=f0, scores=np.array([f1 - f0]))
+        if self._design is not None and np.array_equal(self._design[0], masks):
+            weights = self._design[1]
+        else:            # masks from elsewhere: each with its kernel weight (right for every mask, or for uniform draws)
+            weights = kernel_weights(n, size)
+        inner = (size > 0) & (size < n) & (weights > 0)
+        x, y, w = masks[inner].astype(float), values[inner] - f0, weights[inner]
+        # efficiency, Σφ = f(1) − f(0), eliminates the last score: y − x_n Δ = Σ_{i<n} φ_i (x_i − x_n)
+        delta = f1 - f0
+        design = x[:, :-1] - x[:, -1:]
+        phi = least_squares(design, y - x[:, -1] * delta, w, refuse=(
+            f"KernelSHAP: these masks leave the {n} scores undetermined; give a budget of at least "
+            f"{self.least_budget(n)}"))
+        return Surrogate(intercept=f0, scores=np.append(phi, delta - phi.sum()))
+
+    def __repr__(self) -> str:
+        return f"KernelSHAP(paired={self.paired})"
+
+
+def _kernel(n: int, s: int) -> float:
+    """The Shapley kernel's weight π(s) of one coalition of size s, 0 < s < n, for the sizes enumerated whole (C(n, s)
+    at most the budget)."""
+    n, s = int(n), int(s)
+    return (n - 1) / (comb(n, s) * s * (n - s))
+
+
+def kernel_weights(n: int, sizes) -> np.ndarray:
+    """π(s) of masks of these sizes relative to the largest among them, from log π(s) (exact integers inside the
+    logarithm); 0 for the empty and the full mask."""
+    n = int(n)
+    logs = {k: log(n - 1) - log(comb(n, k)) - log(k) - log(n - k) for k in {int(s) for s in sizes} if 0 < k < n}
+    top = max(logs.values(), default=0.0)
+    return np.array([exp(logs[int(s)] - top) if 0 < s < n else 0.0 for s in sizes])

contextattr/methods/linear.py

@@ -0,0 +1,104 @@
+"""Linear fits on random masks (docs/methods.md): Banzhaf, LIME and ContextCite. Each fits f(m) ≈ b + Σ_i w_i·m_i;
+they differ in which masks they draw and how they fit. scikit-learn is imported only when ContextCite or LIME fits
+(its import takes long on a busy machine, and `import contextattr` should not wait for it)."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .base import Method, Surrogate, all_masks, check_budget, least_squares
+
+EXACT_UP_TO = 16    # Banzhaf enumerates every mask when the budget covers all 2^n of them and n is at most this
+
+
+class Banzhaf(Method):
+    """Banzhaf values: least squares on masks drawn uniformly (each unit kept with probability ½), which is
+    Faith-Banzhaf at order 1 (SPEX B.3, eq. 32). With a budget of at least 2^n masks every mask is used once and the
+    values are exact. Masks that leave the fit undetermined (too few, or units always kept or removed together) are
+    refused rather than fitted."""
+
+    name = "banzhaf"
+
+    def masks(self, n: int, budget: int, rng: np.random.Generator) -> np.ndarray:
+        check_budget(self.name, budget, n + 1)
+        if n <= EXACT_UP_TO and budget >= 2 ** n:
+            return all_masks(n)
+        return rng.random((budget, n)) < 0.5
+
+    def fit(self, masks: np.ndarray, values: np.ndarray) -> Surrogate:
+        x = np.hstack([np.ones((len(masks), 1)), np.asarray(masks, dtype=float)])
+        coef = least_squares(x, np.asarray(values, dtype=float), refuse=(
+            f"Banzhaf: these {len(x)} masks leave the {x.shape[1] - 1} scores undetermined (too few masks, or units "
+            f"always kept or removed together); give a larger budget"))
+        return Surrogate(intercept=coef[0], scores=coef[1:])
+
+
+class ContextCite(Method):
+    """ContextCite (Cohen-Wang 2024 §3): a Lasso on masks that keep each unit with probability ½, so most scores are
+    exactly 0. alpha = 0.01 as in ContextCite. With standardize (the default) the Lasso fits the values divided by
+    their spread, so alpha means the same whatever the target's units; standardize=False fits the raw values, as
+    ContextCite does with its log-odds target."""
+
+    name = "contextcite"
+
+    def __init__(self, alpha: float = 0.01, standardize: bool = True):
+        if not alpha > 0:
+            raise ValueError("ContextCite: alpha must be positive")
+        self.alpha, self.standardize = float(alpha), bool(standardize)
+
+    def masks(self, n: int, budget: int, rng: np.random.Generator) -> np.ndarray:
+        check_budget(self.name, budget, 2)
+        return rng.random((budget, n)) < 0.5
+
+    def fit(self, masks: np.ndarray, values: np.ndarray) -> Surrogate:
+        x, y = np.asarray(masks, dtype=float), np.asarray(values, dtype=float)
+        mean, spread = y.mean(), y.std()
+        if spread == 0:
+            return Surrogate(intercept=mean, scores=np.zeros(x.shape[1]))
+        from sklearn.linear_model import Lasso  # noqa: PLC0415
+
+        scale = spread if self.standardize else 1.0
+        model = Lasso(alpha=self.alpha, fit_intercept=True, max_iter=100_000, tol=1e-10)
+        model.fit(x, (y - mean) / scale)
+        return Surrogate(intercept=mean + scale * model.intercept_, scores=scale * model.coef_)
+
+    def __repr__(self) -> str:
+        return f"ContextCite(alpha={self.alpha}, standardize={self.standardize})"
+
+
+class LIME(Method):
+    """LIME (Ribeiro 2016) as its text explainer does it: the full prompt, then masks that each remove a number of
+    units drawn uniformly from 1 to n; each mask weighted by sqrt(exp(−d²/width²)) of its cosine distance d (×100) to
+    the full prompt, width 25; a weighted ridge fit (alpha 1) on every unit (no feature selection)."""
+
+    name = "lime"
+
+    def __init__(self, kernel_width: float = 25.0, alpha: float = 1.0):
+        if not kernel_width > 0 or not alpha >= 0:
+            raise ValueError("LIME: kernel_width must be positive and alpha at least 0")
+        self.kernel_width, self.alpha = float(kernel_width), float(alpha)
+
+    def masks(self, n: int, budget: int, rng: np.random.Generator) -> np.ndarray:
+        check_budget(self.name, budget, 2)
+        out = np.ones((budget, n), dtype=bool)
+        for row in out[1:]:
+            row[rng.choice(n, size=rng.integers(1, n + 1), replace=False)] = False
+        return out
+
+    def weights(self, masks: np.ndarray) -> np.ndarray:
+        kept = np.asarray(masks, dtype=float).sum(axis=1)
+        n = masks.shape[1]
+        cosine = np.sqrt(kept / n)                       # the cosine of a 0/1 mask with the all-ones vector
+        distance = (1 - cosine) * 100
+        return np.sqrt(np.exp(-(distance ** 2) / self.kernel_width ** 2))
+
+    def fit(self, masks: np.ndarray, values: np.ndarray) -> Surrogate:
+        from sklearn.linear_model import Ridge  # noqa: PLC0415
+
+        x, y = np.asarray(masks, dtype=float), np.asarray(values, dtype=float)
+        model = Ridge(alpha=self.alpha, fit_intercept=True)
+        model.fit(x, y, sample_weight=self.weights(masks))
+        return Surrogate(intercept=model.intercept_, scores=model.coef_)
+
+    def __repr__(self) -> str:
+        return f"LIME(kernel_width={self.kernel_width}, alpha={self.alpha})"

contextattr/methods/loo.py

@@ -0,0 +1,31 @@
+"""Leave-one-out (ContextCite's baseline, SPEX §2): each unit's score is how much the value falls when that unit
+alone is removed from the full prompt. n + 1 masks; the budget does not apply."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .base import Method, Surrogate
+
+
+class LeaveOneOut(Method):
+    name = "loo"
+
+    def masks(self, n: int, budget: int | None = None, rng=None) -> np.ndarray:
+        return np.vstack([np.ones((1, n), dtype=bool), ~np.eye(n, dtype=bool)])
+
+    def fit(self, masks: np.ndarray, values: np.ndarray) -> Surrogate:
+        masks, values = np.asarray(masks, dtype=bool), np.asarray(values, dtype=float)
+        n = masks.shape[1]
+        full = np.flatnonzero(masks.all(axis=1))
+        if not len(full):
+            raise ValueError("leave-one-out needs the full prompt among its masks")
+        f_full = values[full[0]]
+        scores = np.empty(n)
+        for i in range(n):
+            row = np.flatnonzero((masks.sum(axis=1) == n - 1) & ~masks[:, i])
+            if not len(row):
+                raise ValueError(f"leave-one-out needs the mask without unit {i}")
+            scores[i] = f_full - values[row[0]]
+        # the additive model anchored at the full prompt: f̂(1) = f(1), f̂(1 − e_i) = f(1 − e_i)
+        return Surrogate(intercept=f_full - scores.sum(), scores=scores)

contextattr/prompt/__init__.py

@@ -0,0 +1,9 @@
+"""The input: prompts, units, splitting, masking and prompts.jsonl (docs/interface.md §2)."""
+
+from .io import prompt_from_dict, prompt_to_dict, read_prompts, write_prompts
+from .render import as_mask, render
+from .split import KINDS, split
+from .units import LABELS, Group, Message, Piece, Prompt, Response, Unit
+
+__all__ = ["KINDS", "LABELS", "Group", "Message", "Piece", "Prompt", "Response", "Unit", "as_mask",
+           "prompt_from_dict", "prompt_to_dict", "read_prompts", "render", "split", "write_prompts"]