shellde 0.2.0__py3-none-any.whl

shellde/features/pairwise.py

@@ -0,0 +1,64 @@
+"""GatedPairwiseBlock: explicit, restricted, evidence-gated pairwise epistasis.
+
+Reference-relative pairwise indicator features over a RESTRICTED set of position
+pairs (provide contacting / coevolving pairs, or pairs among the active positions
+for strong heredity), so the interaction parameter count stays estimable at low N.
+The block is GATED: when ``gate_open`` is False it presents zero columns (absent), so
+the surrogate is purely additive until the data justifies epistasis. This is the
+single explicit-epistasis path (no separate surrogate class).
+"""
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+import numpy as np
+
+from shellde.design_space import DesignSpace
+from shellde.features.base import FeatureBlock
+
+
+class GatedPairwiseBlock(FeatureBlock):
+    name = "pairwise"
+
+    def __init__(
+        self,
+        space: DesignSpace,
+        pairs: Sequence[tuple[int, int]] | None = None,
+        *,
+        gate_open: bool = True,
+    ) -> None:
+        if pairs is None:
+            pos = space.positions
+            pairs = [(pos[i], pos[j]) for i in range(len(pos)) for j in range(i + 1, len(pos))]
+        bad = [pp for pp in pairs if pp[0] not in space.reference or pp[1] not in space.reference]
+        if bad:
+            raise ValueError(f"pairwise pairs not in design space: {bad}")
+        self._pairs = [tuple(sorted(pp)) for pp in pairs]
+        self._gate_open = gate_open
+        self._q1 = space.q - 1  # reference-relative: drop the WT category per position
+        self._nonref_idx = {
+            p: {aa: k for k, aa in enumerate(a for a in space.alphabet if a != space.reference[p])}
+            for p in space.positions
+        }
+        self._dim = len(self._pairs) * self._q1 * self._q1
+
+    @property
+    def dim(self) -> int:
+        return self._dim
+
+    @property
+    def present(self) -> bool:
+        return self._gate_open and self._dim > 0
+
+    def _encode_present(
+        self, assignments: Sequence[Mapping[int, str]], space: DesignSpace
+    ) -> np.ndarray:
+        q1 = self._q1
+        x = np.zeros((len(assignments), self._dim), dtype=float)
+        for i, a in enumerate(assignments):
+            for pidx, (pi, pj) in enumerate(self._pairs):
+                ai = self._nonref_idx[pi].get(a[pi])
+                bj = self._nonref_idx[pj].get(a[pj])
+                if ai is not None and bj is not None:  # both positions are mutated
+                    x[i, pidx * q1 * q1 + ai * q1 + bj] = 1.0
+        return x

shellde/funclib.py

@@ -0,0 +1,331 @@
+"""FuncLib-style active-site library designer (design-space construction, NOT a predictor).
+
+Implements the core principle of FuncLib (Khersonsky & Fleishman, Mol Cell 2018; htFuncLib,
+J Mol Biol 2025): substantial active-site improvements demand MULTIPLE proximal mutations whose
+epistasis on activity is unpredictable, so do NOT try to predict the winning mutation. Instead
+constrain the combinatorial space to point mutations that are
+
+  (1) tolerated by natural diversity  -- a per-substitution tolerance score >= cutoff
+      (an MSA PSSM log-odds, or a PLM zero-shot ensemble; ``zero_shot.zero_shot_ensemble``
+      returns exactly the {token: score} map this consumes), and
+  (2) not destabilizing               -- a per-mutation folding ddG <= cutoff
+      (ThermoMPNN / FoldX; ``structure.load_ddg_table`` loads it),
+
+then enumerate COMBINABLE multipoint variants for DIRECT measurement. This collapses the naive
+q**L active-site saturation space to a small, screenable library and auto-excludes the conserved
+catalytic core (no natural diversity -> fails the tolerance gate; saturating it is lethal).
+
+This module predicts NOTHING about activity. Its outputs are saturation / measurement targets
+(``role="saturation_target"``, ``predict=False``). Whether saturating them yields activity-
+improving variants is wet-lab-gated -- the same honesty bar as ``StructureSiteProposer`` and the
+inverse-folding block. The verifiable, by-construction value is the combinatorial reduction and
+the lethal-core exclusion; the activity benefit is a claim only the wet lab settles.
+
+Negative epistasis between the chosen mutations is approximated additively here (an optional cap
+on the summed single-mutation ddG of a combo). When measured data on these positions arrives, the
+contact-restricted ``GatedPairwiseBlock`` is the epistasis-aware upgrade; this module is the
+data-free seeding step for the regime where the surrogate has no signal.
+
+Dependency-light by design (numpy + stdlib): it consumes precomputed tables. Producing the ddG /
+tolerance tables is an external one-time step (free tools; see the table loaders' docstrings).
+"""
+from __future__ import annotations
+
+import itertools
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, field
+
+from shellde.design_space import DesignSpace
+from shellde.types import Candidate
+
+
+def tolerance_from_logprob_table(
+    table: Mapping[int, Mapping[str, float]],
+    space: DesignSpace,
+    *,
+    positions: Sequence[int] | None = None,
+) -> dict[str, float]:
+    """Convert a per-position log-prob table to per-substitution tolerance, keyed by token.
+
+    Maps {position: {aa: logp}} (an inverse-folding / ProteinMPNN table, or a PLM per-position
+    marginal) to {"<WT><pos><AA>": logp(AA) - logp(WT)}: a log-odds-vs-WT tolerance where a
+    higher value means the substitution is more natural/foldable than WT at that site. WT tokens
+    are omitted. Positions absent from ``table`` are skipped (they simply contribute no tolerated
+    mutations downstream). Use this to feed an IF/PLM table into :func:`design_library`.
+    """
+    pos = list(space.positions if positions is None else positions)
+    out: dict[str, float] = {}
+    for p in pos:
+        col = table.get(int(p))
+        if col is None:
+            continue
+        wt = space.reference[p]
+        wt_lp = float(col.get(wt, 0.0))
+        for aa in space.alphabet:
+            if aa == wt or aa not in col:
+                continue
+            out[f"{wt}{p}{aa}"] = float(col[aa]) - wt_lp
+    return out
+
+
+def combine_tolerances(
+    maps: Sequence[Mapping[str, float]], *, standardize: bool = True
+) -> dict[str, float]:
+    """Ensemble several per-substitution tolerance maps into one (MULTI-evolve style).
+
+    Each input is a ``{token: score}`` map (e.g. ESM-C, ESM-2 and inverse-folding zero-shot
+    signals on different scales). When ``standardize`` each map is z-scored (mean 0, unit std)
+    so signals on different scales combine fairly, then averaged across the maps that score each
+    token. A token present in any map survives, valued by the mean of its available standardised
+    scores. Empty input -> ``{}``. Per MULTI-evolve, a multi-method zero-shot ensemble surfaces
+    more enhancing mutations than any single scorer; whether it helps a given protein is an
+    empirical question (backtest before trusting it).
+    """
+    std_maps: list[dict[str, float]] = []
+    for m in maps:
+        vals = list(m.values())
+        if standardize and len(vals) > 1:
+            mu = sum(vals) / len(vals)
+            var = sum((v - mu) ** 2 for v in vals) / len(vals)
+            sd = var ** 0.5
+            std_maps.append({k: (v - mu) / sd for k, v in m.items()} if sd > 1e-12 else {k: 0.0 for k in m})
+        else:
+            std_maps.append(dict(m))
+    acc: dict[str, list[float]] = {}
+    for sm in std_maps:
+        for k, v in sm.items():
+            acc.setdefault(k, []).append(v)
+    return {k: sum(vs) / len(vs) for k, vs in acc.items()}
+
+
+@dataclass(frozen=True)
+class FuncLibLibrary:
+    """A FuncLib-style design-space proposal: filtered per-position options + a combinable library.
+
+    ``candidates`` are saturation/measurement targets (``evidence["role"] == "saturation_target"``,
+    ``evidence["predict"] is False``), NOT ranked activity predictions. ``tolerated`` is the
+    per-position kept-mutation map (position -> list of (aa, score), score descending). ``stats``
+    carries the by-construction provenance (naive vs filtered space size, reduction factor,
+    truncation). ``abstained`` is True when no stability/tolerance signal was supplied or every
+    mutation was filtered out, with ``reason`` explaining why.
+    """
+
+    positions: tuple[int, ...]
+    tolerated: dict[int, list[tuple[str, float]]]
+    candidates: list[Candidate]
+    abstained: bool = False
+    reason: str = ""
+    stats: dict = field(default_factory=dict)
+
+
+def _combo_string(assignment: Mapping[int, str], space: DesignSpace) -> str:
+    return "".join(assignment.get(p, space.reference[p]) for p in space.positions)
+
+
+def design_library(
+    space: DesignSpace,
+    *,
+    positions: Sequence[int] | None = None,
+    ddg: Mapping[int, Mapping[str, float]] | None = None,
+    tolerance: Mapping[str, float] | None = None,
+    ddg_cutoff: float = 2.5,
+    tolerance_cutoff: float = 0.0,
+    per_position_cap: int = 4,
+    min_mut: int = 1,
+    max_mut: int = 4,
+    additive_ddg_budget: float | None = None,
+    generated_cap: int = 200_000,
+    max_library: int = 2000,
+    allow_unscored: bool = False,
+) -> FuncLibLibrary:
+    """Construct a FuncLib-style combinable multipoint library over ``positions``.
+
+    Parameters
+    ----------
+    space:
+        The :class:`DesignSpace`. Emitted combo strings span ``space.positions``; positions not
+        in ``positions`` stay at WT.
+    positions:
+        Subset of ``space.positions`` to design over (e.g. an active-site 2nd shell from
+        :func:`structure.shells_from_pdb`). Defaults to all of ``space.positions``.
+    ddg:
+        Per-position per-AA folding ddG (kcal/mol; positive = destabilizing). The stability gate
+        keeps a mutation iff ``ddg[p][aa] <= ddg_cutoff``. ``None`` disables the gate.
+    tolerance:
+        Per-substitution tolerance keyed by token ``"<WT><pos><AA>"`` (higher = more tolerated;
+        from an MSA PSSM or :func:`zero_shot.zero_shot_ensemble`). The tolerance gate keeps a
+        mutation iff ``tolerance[token] >= tolerance_cutoff``. ``None`` disables the gate.
+    ddg_cutoff, tolerance_cutoff:
+        Gate thresholds (see above).
+    per_position_cap:
+        Keep at most this many tolerated+stable mutations per position (top by combined score).
+    min_mut, max_mut:
+        Inclusive bounds on the number of mutated positions per emitted variant (FuncLib designs
+        carry ~3-6 active-site mutations).
+    additive_ddg_budget:
+        If set and ``ddg`` is given, drop any combo whose summed single-mutation ddG exceeds this
+        (an additive negative-epistasis / total-destabilization proxy).
+    generated_cap:
+        Hard cap on enumerated combos before ranking (guards against combinatorial blow-up).
+    max_library:
+        Keep at most this many combos in the final library (top by combined score).
+    allow_unscored:
+        When ``ddg`` is given but a position/AA is missing from it, treat the mutation as passing
+        the stability gate (ddG contribution 0) instead of dropping it. Off by default (a missing
+        ddG cannot be certified stable).
+
+    Returns
+    -------
+    FuncLibLibrary
+        Abstains (empty ``candidates``, ``abstained=True``) when neither ``ddg`` nor ``tolerance``
+        is supplied (that would be unfiltered saturation, not FuncLib), or when every mutation is
+        filtered out.
+    """
+    if min_mut < 1 or max_mut < min_mut:
+        raise ValueError("require 1 <= min_mut <= max_mut")
+    if per_position_cap < 1:
+        raise ValueError("per_position_cap must be >= 1")
+
+    pos = list(space.positions if positions is None else sorted(set(int(p) for p in positions)))
+    bad = [p for p in pos if p not in space.positions]
+    if bad:
+        raise ValueError(f"positions {bad} not in design space")
+
+    try:
+        naive_space = float(len(space.alphabet) ** len(pos))  # exact int -> float (may overflow)
+    except OverflowError:
+        naive_space = float("inf")
+    base_stats = {
+        "positions": pos,
+        "n_positions": len(pos),
+        "naive_saturation_space": naive_space,
+    }
+
+    if ddg is None and tolerance is None:
+        return FuncLibLibrary(
+            positions=tuple(pos), tolerated={}, candidates=[], abstained=True,
+            reason="no stability (ddG) or tolerance signal supplied: this would be unfiltered "
+                   "saturation, not a FuncLib-filtered library",
+            stats=base_stats,
+        )
+
+    # ---- per-position gates -------------------------------------------------------------- #
+    ddg_single: dict[tuple[int, str], float] = {}
+    tolerated: dict[int, list[tuple[str, float]]] = {}
+    for p in pos:
+        wt = space.reference[p]
+        scored: list[tuple[str, float]] = []
+        ddg_col = None if ddg is None else ddg.get(int(p))
+        for aa in space.alphabet:
+            if aa == wt:
+                continue
+            tok = f"{wt}{p}{aa}"
+            # tolerance gate
+            tol_val = None if tolerance is None else tolerance.get(tok)
+            if tolerance is not None:
+                if tol_val is None or tol_val < tolerance_cutoff:
+                    continue
+            # stability gate
+            d_val: float | None = None
+            if ddg is not None:
+                d_val = None if ddg_col is None else ddg_col.get(aa)
+                if d_val is None:
+                    if not allow_unscored:
+                        continue
+                    d_val = 0.0
+                elif d_val > ddg_cutoff:
+                    continue
+            ddg_single[(p, aa)] = 0.0 if d_val is None else float(d_val)
+            score = (0.0 if tol_val is None else float(tol_val)) - (0.0 if d_val is None else float(d_val))
+            scored.append((aa, score))
+        scored.sort(key=lambda kv: kv[1], reverse=True)
+        if scored:
+            tolerated[p] = scored[:per_position_cap]
+
+    kept_positions = sorted(tolerated)
+    base_stats["kept_positions"] = kept_positions
+    base_stats["n_kept_positions"] = len(kept_positions)
+    base_stats["tolerated_per_position"] = {p: len(tolerated[p]) for p in kept_positions}
+
+    if not kept_positions:
+        return FuncLibLibrary(
+            positions=tuple(pos), tolerated={}, candidates=[], abstained=True,
+            reason="every candidate mutation failed the tolerance/stability gates "
+                   "(active-site core may be too conserved or too destabilizing to mutate)",
+            stats=base_stats,
+        )
+
+    # ---- combinable enumeration (capped) ------------------------------------------------- #
+    eff_max = min(max_mut, len(kept_positions))
+    rows: list[tuple[float, dict[int, str], float]] = []  # (score, assignment, summed_ddg)
+    truncated = False
+    for k in range(min_mut, eff_max + 1):
+        if truncated:
+            break
+        for poscombo in itertools.combinations(kept_positions, k):
+            option_lists = [tolerated[p] for p in poscombo]
+            for picks in itertools.product(*option_lists):
+                summed_ddg = sum(ddg_single[(poscombo[i], aa)] for i, (aa, _) in enumerate(picks))
+                if additive_ddg_budget is not None and ddg is not None and summed_ddg > additive_ddg_budget:
+                    continue
+                assignment = {poscombo[i]: aa for i, (aa, _) in enumerate(picks)}
+                combo_score = sum(s for _, s in picks)
+                rows.append((combo_score, assignment, summed_ddg))
+                if len(rows) >= generated_cap:
+                    truncated = True
+                    break
+            if truncated:
+                break
+
+    rows.sort(key=lambda r: r[0], reverse=True)
+    rows = rows[:max_library]
+
+    candidates: list[Candidate] = []
+    for combo_score, assignment, summed_ddg in rows:
+        muts = tuple(
+            f"{space.reference[p]}{p}{assignment[p]}" for p in space.positions if p in assignment
+        )
+        evidence = {
+            "role": "saturation_target",
+            "predict": False,
+            "source": "funclib",
+            "combo_score": float(combo_score),
+        }
+        if ddg is not None:
+            evidence["additive_ddg"] = float(summed_ddg)
+        candidates.append(
+            Candidate(
+                variant=_combo_string(assignment, space),
+                n_mut=len(assignment),
+                mu=0.0,
+                sigma=0.0,
+                acq=float(combo_score),
+                mutations=muts,
+                evidence=evidence,
+            )
+        )
+
+    base_stats["generated"] = len(rows) if not truncated else generated_cap
+    base_stats["library_size"] = len(candidates)
+    base_stats["truncated"] = truncated
+    base_stats["reduction_factor"] = (
+        naive_space / len(candidates) if candidates else float("inf")
+    )
+    base_stats["gates"] = {
+        "ddg": ddg is not None,
+        "tolerance": tolerance is not None,
+        "ddg_cutoff": ddg_cutoff,
+        "tolerance_cutoff": tolerance_cutoff,
+        "per_position_cap": per_position_cap,
+        "min_mut": min_mut,
+        "max_mut": max_mut,
+        "additive_ddg_budget": additive_ddg_budget,
+    }
+    return FuncLibLibrary(
+        positions=tuple(pos),
+        tolerated=tolerated,
+        candidates=candidates,
+        abstained=not candidates,
+        reason="" if candidates else "no combos survived the additive ddG budget",
+        stats=base_stats,
+    )

shellde/gating.py

@@ -0,0 +1,181 @@
+"""Evidence-based data gate for the explicit-pairwise epistasis arm.
+
+Per the tool-development synthesis (recs 2 and 6): never hardcode "this protein gets
+the epistasis arm". Instead decide it from the data: open the gated-pairwise block only
+when adding it measurably improves held-out prediction over a pure-additive baseline by
+k-fold cross-validation. At N=95, q=20 the pairwise block is unestimable so this
+correctly stays shut; on a low-q / higher-N / strongly-epistatic landscape it opens.
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import numpy as np
+from sklearn.model_selection import KFold
+
+from shellde.design_space import DesignSpace
+from shellde.features import FeatureBlock, FeatureMatrix, GatedPairwiseBlock, OneHotBlock
+from shellde.surrogate import RidgeSurrogate
+
+DEFAULT_MIN_IMPROVE = 0.02
+
+
+def _cv_rmse(
+    space: DesignSpace, variants: Sequence[str], y: np.ndarray,
+    blocks: Sequence[FeatureBlock], *, k: int, seed: int,
+) -> float:
+    """k-fold held-out RMSE of a Ridge surrogate on the given feature blocks (nan if degenerate)."""
+    n = len(variants)
+    if n < 8 or float(np.std(y)) < 1e-12:
+        return float("nan")
+    x = FeatureMatrix(space, list(blocks)).encode(variants)
+    kf = KFold(n_splits=min(k, n), shuffle=True, random_state=seed)
+    sse, cnt = 0.0, 0
+    for tr, te in kf.split(x):
+        if len(tr) < 2 or float(np.std(y[tr])) < 1e-12:
+            continue
+        cnt += len(te)
+        m = RidgeSurrogate(random_state=seed).fit(x[tr], y[tr])
+        sse += float(np.sum((m.predict(x[te]).mean - y[te]) ** 2))
+    return float(np.sqrt(sse / cnt)) if cnt else float("nan")
+
+
+def block_gate_evidence(
+    space: DesignSpace,
+    variants: Sequence[str],
+    fitness: np.ndarray,
+    base_blocks: Sequence[FeatureBlock],
+    candidate_block: FeatureBlock,
+    *,
+    k: int = 4,
+    seed: int = 0,
+) -> dict:
+    """k-fold held-out RMSE of ``base_blocks`` vs ``base_blocks + candidate_block``.
+
+    ``improvement`` = (base_rmse - candidate_rmse) / base_rmse (>0 means the candidate block
+    helps out of sample). The general data-gate behind any optional feature signal.
+    """
+    y = np.asarray(fitness, dtype=float)
+    if len(variants) != y.shape[0]:
+        raise ValueError(f"{len(variants)} variants but {y.shape[0]} fitness values")
+    base = _cv_rmse(space, variants, y, base_blocks, k=k, seed=seed)
+    aug = _cv_rmse(space, variants, y, [*base_blocks, candidate_block], k=k, seed=seed)
+    if not (np.isfinite(base) and np.isfinite(aug) and base > 0):
+        improvement = 0.0
+    else:
+        improvement = (base - aug) / base
+    return {"base_rmse": base, "candidate_rmse": aug, "improvement": improvement, "n": len(variants)}
+
+
+def should_include_block(
+    space: DesignSpace,
+    variants: Sequence[str],
+    fitness: np.ndarray,
+    base_blocks: Sequence[FeatureBlock],
+    candidate_block: FeatureBlock,
+    *,
+    label: str = "signal",
+    min_improve: float = DEFAULT_MIN_IMPROVE,
+    min_n: int = 12,
+    k: int = 4,
+    seed: int = 0,
+    n_gate_seeds: int = 5,
+    min_positive_fraction: float = 0.6,
+) -> tuple[bool, dict]:
+    """Decide whether to open an optional feature block FROM THE PROTEIN'S OWN held-out data.
+
+    Returns (include, report). At N < ``min_n`` the gate is unreliable, so it abstains to the
+    conservative additive baseline (include=False) rather than guess. Otherwise it repeats the
+    same block-vs-baseline CV gate across several deterministic fold seeds and opens the block only
+    when the MEDIAN improvement clears ``min_improve`` AND enough split seeds show positive
+    improvement. This reduces the single-fold-split variance/overfitting that motivated pruning
+    the old ``--model-class auto`` selector.
+    """
+    n = len(variants)
+    if n < min_n:
+        return False, {"label": label, "included": False, "n": n, "min_n": min_n, "improvement": 0.0,
+                       "reason": f"N={n} < min_n={min_n}: gate unreliable, using conservative additive baseline"}
+    n_gate_seeds = max(1, int(n_gate_seeds))
+    reports = [
+        block_gate_evidence(space, variants, fitness, base_blocks, candidate_block, k=k, seed=seed + i)
+        for i in range(n_gate_seeds)
+    ]
+    improvements = np.asarray([float(r["improvement"]) for r in reports], dtype=float)
+    improvement = float(np.median(improvements))
+    positive_fraction = float(np.mean(improvements > 0.0))
+    ev = {
+        "label": label,
+        "n": n,
+        "base_rmse": float(np.median([r["base_rmse"] for r in reports])),
+        "candidate_rmse": float(np.median([r["candidate_rmse"] for r in reports])),
+        "improvement": improvement,
+        "improvements": [float(x) for x in improvements],
+        "positive_fraction": positive_fraction,
+        "n_gate_seeds": n_gate_seeds,
+        "min_positive_fraction": min_positive_fraction,
+        "min_improve": min_improve,
+    }
+    ev["included"] = improvement >= min_improve and positive_fraction >= min_positive_fraction
+    ev["reason"] = (
+        f"median held-out RMSE improvement {improvement:+.3f} >= {min_improve} and "
+        f"positive split fraction {positive_fraction:.2f} >= {min_positive_fraction:.2f} "
+        f"(robust across {n_gate_seeds} CV seeds)"
+        if ev["included"] else
+        f"median held-out RMSE improvement {improvement:+.3f} / positive split fraction "
+        f"{positive_fraction:.2f} did not pass {min_improve}/{min_positive_fraction:.2f} "
+        f"(dropped; robust gate across {n_gate_seeds} CV seeds)"
+    )
+    return ev["included"], ev
+
+
+def pairwise_gate_evidence(
+    space: DesignSpace,
+    variants: Sequence[str],
+    fitness: np.ndarray,
+    *,
+    pairs: Sequence[tuple[int, int]] | None = None,
+    k: int = 4,
+    seed: int = 0,
+) -> dict:
+    """k-fold held-out RMSE of additive vs additive+pairwise; relative improvement.
+
+    ``improvement`` = (additive_rmse - pairwise_rmse) / additive_rmse (>0 means the
+    pairwise block helps out of sample). Returns RMSEs and the improvement fraction.
+    """
+    ev = block_gate_evidence(
+        space, variants, fitness, [OneHotBlock(space)], GatedPairwiseBlock(space, pairs), k=k, seed=seed
+    )
+    return {"additive_rmse": ev["base_rmse"], "pairwise_rmse": ev["candidate_rmse"], "improvement": ev["improvement"]}
+
+
+def should_open_pairwise(
+    space: DesignSpace,
+    variants: Sequence[str],
+    fitness: np.ndarray,
+    *,
+    pairs: Sequence[tuple[int, int]] | None = None,
+    min_improve: float = DEFAULT_MIN_IMPROVE,
+    k: int = 4,
+    seed: int = 0,
+) -> bool:
+    """True iff the pairwise block improves held-out RMSE by at least ``min_improve``."""
+    return pairwise_gate_evidence(space, variants, fitness, pairs=pairs, k=k, seed=seed)["improvement"] >= min_improve
+
+
+def pairwise_regate(
+    space: DesignSpace, *, pairs: Sequence[tuple[int, int]] | None = None,
+    min_improve: float = DEFAULT_MIN_IMPROVE, k: int = 4, seed: int = 0
+):
+    """A ``run_campaign(regate=...)`` callback: open the pairwise block per round by CV.
+
+    Each round it rebuilds [OneHot (+ GatedPairwise if the accumulated data justify it)],
+    so explicit epistasis turns ON only once enough rounds have accumulated to estimate
+    it, and stays additive otherwise. Returns ``(variants, fitness) -> FeatureMatrix``.
+    """
+    def _regate(variants: Sequence[str], fitness: np.ndarray) -> FeatureMatrix:
+        blocks: list = [OneHotBlock(space)]
+        if should_open_pairwise(space, variants, fitness, pairs=pairs, min_improve=min_improve, k=k, seed=seed):
+            blocks.append(GatedPairwiseBlock(space, pairs))
+        return FeatureMatrix(space, blocks)
+
+    return _regate