shellde 0.2.0__py3-none-any.whl

shellde/cli.py

@@ -0,0 +1,1517 @@
+"""Command-line entry point: a single ``recommend`` plus ``bench`` and ``report``.
+
+  recommend MEASURED.csv   variant,fitness -> ranked candidates + evidence report
+  bench                    synthetic alpha-spectrum tool-comparative benchmark
+  report SPECTRUM.json     summarise a benchmark (or recommend) JSON
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections import Counter
+from pathlib import Path
+
+import numpy as np
+
+from shellde.acquisition import UCB
+from shellde.bench import run_spectrum
+from shellde.candidates import CandidatePool, generate_candidates, recombine_beneficials, select_positions
+from shellde.conformal import cross_conformal_normalized_q
+from shellde.design_space import AA_ALPHABET, DesignSpace, mutations_of
+from shellde.types import Prediction
+from shellde.features import (
+    FeatureBlock,
+    FeatureMatrix,
+    GatedPairwiseBlock,
+    InverseFoldingBlock,
+    default_blocks,
+)
+from shellde.gating import should_include_block, should_open_pairwise
+from shellde.structure import (
+    contacts_from_pdb,
+    load_ddg_table,
+    load_inverse_folding_logprobs,
+    shells_from_pdb,
+)
+from shellde.advisor import data_readiness
+from shellde.prereg import prereg_hash, stamp
+from shellde.rank import rank_candidates
+from shellde.report import write_report
+from shellde.surrogate import EnsembleSurrogate, GlobalEpistasisSurrogate, RankingSurrogate, RFSurrogate, RidgeSurrogate
+from shellde.embeddings.provider import EmbeddingCache
+from shellde.plm import build_naturalness, build_provider, plm_rerank, read_fasta
+from shellde.funclib import design_library, tolerance_from_logprob_table
+from shellde.msa import build_msa_mmseqs2, load_msa_logprobs
+from shellde.hotspots import rank_hotspots
+from shellde.holo import find_holo_homolog
+from shellde.consensus import build_consensus, consensus_summary
+from shellde.campaign import (
+    SurrogateSpec,
+    funclib_seed_variants,
+    simulate_campaign,
+    single_mutant_variants,
+    stable_variants,
+)
+from shellde.sitefinder import (
+    ResolveResult,
+    fetch_alphafold,
+    fetch_pdb,
+    fetch_uniprot,
+    pdb_ids_from_uniprot,
+    resolve_from_apo,
+    resolve_from_entry,
+    resolve_from_pdb,
+    uniprot_from_sequence,
+)
+
+_SURROGATE = {
+    "ridge": RidgeSurrogate, "ensemble": EnsembleSurrogate, "rf": RFSurrogate,
+    "ranking": RankingSurrogate, "global_epistasis": GlobalEpistasisSurrogate,
+}
+
+
+def resolve_plm_pooling(pooling: str, plm_model: str) -> str:
+    """Resolve --plm-pooling 'auto' to a concrete mode based on the PLM model.
+
+    Optimal pooling depends on model size (held-out: esmc_600m favours site-specific,
+    esmc_300m and smaller favour whole-sequence mean). 'auto' -> 'site' iff the model is
+    esmc_600m, else 'mean' (the safe default that every ESM-C size can run). A non-'auto'
+    value is returned unchanged (explicit override).
+    """
+    if pooling != "auto":
+        return pooling
+    return "site" if plm_model == "esmc_600m" else "mean"
+
+
+def _read_design(measured_path: str, design_positions: str | None):
+    """Load a variant,fitness CSV and build the DesignSpace (shared by recommend/advise)."""
+    import pandas as pd
+
+    df = pd.read_csv(measured_path)
+    for col in ("variant", "fitness"):
+        if col not in df.columns:
+            raise ValueError(f"{measured_path}: missing required column {col!r} (need variant,fitness)")
+    variants = [str(v) for v in df["variant"]]
+    fitness = df["fitness"].to_numpy(dtype=float)
+    if not variants:
+        raise ValueError(f"{measured_path}: no measured variants")
+    length = len(variants[0])
+    if any(len(v) != length for v in variants):
+        raise ValueError("all variants must share one length for a fixed-site design space")
+    if design_positions:
+        positions = tuple(sorted(int(x) for x in design_positions.split(",")))
+        if len(positions) != length:
+            raise ValueError(f"--design-positions has {len(positions)} positions but variants have length {length}")
+    else:
+        positions = tuple(range(1, length + 1))
+    ref = {p: Counter(v[j] for v in variants).most_common(1)[0][0] for j, p in enumerate(positions)}
+    return variants, fitness, DesignSpace(positions, ref), ref, length
+
+
+def _print_epistasis_next_step(
+    recommendation: str, measured: object = None, positions: object = None
+) -> None:
+    """The ``open_epistasis`` verdict is actionable on ``recommend`` ONLY: neither ``campaign``/
+    ``round`` nor ``advise`` exposes the pairwise data-gate flag. ``measured`` is the measured
+    path(s) in scope at the call site (a single path on ``advise``, a per-round list on
+    ``campaign``/``round``). With exactly one path the printed command names a real file; with
+    several (or none) the measured CSV is a ``<placeholder>``, because ``recommend`` takes ONE CSV
+    and the caller must concatenate the rounds first. That join is spelled out header-aware on
+    purpose: a plain ``cat r0.csv r1.csv`` leaves the SECOND file's header line as a data row, and
+    ``_read_design`` then dies inside ``float("fitness")``. The printed command uses ``head``/``tail``
+    so exactly one header line survives.
+
+    The two commands do NOT read the same formats: ``campaign``/``round`` load measured tables via
+    ``_read_landscape`` (CSV/TSV *and* Excel, lenient column names), while ``recommend``/``advise``
+    load them via ``_read_design``, which is ``pandas.read_csv`` plus exact ``variant``/``fitness``
+    columns. Variant NOTATION differs too: ``campaign``/``round`` resolve each variant through
+    ``design_space.to_assignment``, which accepts mutation tokens (``V39A``, ``L42M:K88R``) as well as
+    fixed-site combo strings, whereas ``_read_design`` requires every variant to be a combo string of
+    one shared length and raises otherwise. So a file that ``campaign`` accepted may still be
+    rejected by ``recommend``. There is ONE shipped file that always crosses cleanly: the
+    ``roundN_measured_template.csv`` that ``campaign``/``round`` writes into ``--outdir`` is already
+    ``variant``,``fitness`` with combo-string variants, so it is readable by ``recommend`` as soon as
+    its ``fitness`` column is filled. For anything else there is NO shipped converter (the
+    subcommands are recommend / advise / funclib / campaign / resolve-site / round / hotspots /
+    bench / report; none of them reshapes a measured table), so the user has to reshape it by hand.
+    When the caller is that path (``measured`` given as a list, i.e. not a ``str``), the printed
+    guidance carries both facts, so the user does not discover them at the shell.
+
+    ``positions`` is the resolved design region in scope (the campaign/round variant strings are
+    the per-position combo encoding over it). It is printed as ``--design-positions`` so the
+    suggested command runs over the SAME mutation space: without it ``recommend`` falls back to
+    ``1..len(variant)``, which is the wrong space for a campaign round.
+    """
+    if recommendation != "open_epistasis":
+        return
+    paths = [str(measured)] if isinstance(measured, str) else [str(m) for m in (measured or [])]
+    # advise passes a str already validated by _read_design; campaign/round pass a list read by
+    # the lenient _read_landscape, so those files may not be readable by `recommend` as-is.
+    fmt = ("" if isinstance(measured, str) else
+           "; `recommend` needs a CSV with exact `variant`,`fitness` columns and fixed-site combo "
+           "variants (one residue per design position, every row the same length). The "
+           "`roundN_measured_template.csv` written into --outdir is already in that format once its "
+           "`fitness` column is filled. Any other round file (Excel, other column names, or "
+           "mutation-token variants like `V39A`) has to be reshaped BY HAND: ShellDE ships no "
+           "converter subcommand")
+    if isinstance(positions, str):
+        pos = f" --design-positions {positions}"
+    elif positions:
+        pos = " --design-positions " + ",".join(str(p) for p in positions)
+    else:
+        pos = ""
+    if len(paths) == 1:
+        print(f"  -> act on it with: shellde recommend {paths[0]}{pos} --auto-gate-pairwise "
+              f"(the pairwise block is a data-gated opt-in on `recommend`{fmt})")
+    elif len(paths) > 1:
+        # A plain `cat` of the rounds leaves the later header lines as data rows and _read_design
+        # fails inside float("fitness"), so name a join that keeps exactly ONE header line.
+        join = ("head -1 " + paths[0] + " > all_measured.csv; tail -q -n +2 "
+                + " ".join(paths) + " >> all_measured.csv")
+        print(f"  -> act on it with: shellde recommend <all_measured.csv>{pos} --auto-gate-pairwise "
+              "(the pairwise block is a data-gated opt-in on `recommend`, which takes ONE measured "
+              f"CSV: concatenate {', '.join(paths)} first, keeping exactly ONE header row -- "
+              f"`{join}`. A plain `cat` of them leaves the second header as a data row and the read "
+              f"then fails with `could not convert string to float: \'fitness\'`{fmt})")
+    else:
+        print(f"  -> act on it with: shellde recommend <measured.csv>{pos} --auto-gate-pairwise "
+              f"(the pairwise block is a data-gated opt-in on `recommend`{fmt})")
+
+
+def cmd_advise(args: argparse.Namespace) -> int:
+    variants, fitness, space, _ref, _length = _read_design(args.measured, args.design_positions)
+    r = data_readiness(space, variants, fitness)
+    spear = "n/a" if r["heldout_spearman"] is None else f"{r['heldout_spearman']:+.3f}"
+    print(f"[advise] n={r['n_measured']} sites={space.n_positions} | held-out Spearman={spear} "
+          f"| trustworthy={r['model_trustworthy']} | gate_improvement={r['gate_improvement']:+.3f} "
+          f"(epistasis_ready={r['epistasis_ready']})")
+    print(f"[advise] recommendation: {r['recommendation'].upper()} -- {r['why']}")
+    _print_epistasis_next_step(r["recommendation"], args.measured, args.design_positions)
+    hw = r["conformal_halfwidth_90"]
+    hw_disp = "n/a" if hw is None else f"{hw:+.3f}"
+    print(f"[advise] conformal 90% interval half-width: {hw_disp} (distribution-free, valid at low N)")
+    return 0
+
+
+def cmd_recommend(args: argparse.Namespace) -> int:
+    variants, fitness, space, ref, length = _read_design(args.measured, getattr(args, "design_positions", None))
+    blocks: list[FeatureBlock] = default_blocks(space)
+    pairs = contacts_from_pdb(args.contacts_pdb, space.positions, cutoff=args.contact_cutoff) if args.contacts_pdb else None
+    use_pairwise = bool(args.contacts_pdb)  # explicit contacts -> include the restricted block
+    if getattr(args, "auto_gate_pairwise", False):
+        use_pairwise = should_open_pairwise(space, variants, fitness, pairs=pairs)
+    if use_pairwise:
+        blocks.append(GatedPairwiseBlock(space, pairs))
+    signal_gate: dict | None = None
+    if args.if_logprobs:
+        if_block = InverseFoldingBlock(space, load_inverse_folding_logprobs(args.if_logprobs))
+        if getattr(args, "auto_signals", True):
+            # Tool decides whether the supplied signal helps on THIS protein's held-out data,
+            # instead of using it unconditionally (opt-in audit 2026-06-29).
+            include, signal_gate = should_include_block(
+                space, variants, fitness, blocks, if_block, label="inverse_folding",
+            )
+            if include:
+                blocks.append(if_block)
+        else:
+            blocks.append(if_block)  # --no-auto-signals: expert override, use unconditionally
+    matrix = FeatureMatrix(space, blocks)
+    x_enc = matrix.encode(variants)
+    chosen = args.model_class
+    sur = _SURROGATE[chosen](random_state=0).fit(x_enc, fitness)
+
+    # Normalized cross-conformal quantile on the MEASURED set (heteroscedastic-preserving).
+    # Guard: needs enough points + non-degenerate y, else the gate is disabled (None).
+    conf_q = (
+        cross_conformal_normalized_q(x_enc, fitness, lambda: _SURROGATE[chosen](random_state=0))
+        if len(variants) >= 8 and float(np.std(fitness)) > 0.0
+        else None
+    )
+    # Max mutation count among the measured variants (vs WT/consensus reference). Candidates
+    # with n_mut above this are out of the calibration distribution (label conformal_oob).
+    max_meas_nmut = max(len(mutations_of(v, space)) for v in variants)
+
+    if args.max_positions is not None and args.max_positions < length:
+        pool = select_positions(sur, matrix, m=args.max_positions, interaction_aware=args.interaction_aware)
+    else:
+        pool = list(space.positions)
+    cset = generate_candidates(
+        sur, matrix, pinned_positions=pool, max_mut=min(args.max_mut, len(pool)),
+        generated_cap=args.generated_cap, scored_cap=args.scored_cap, beta=args.beta,
+        interaction_aware=args.interaction_aware, seed=0,
+    )
+    n_recombined = 0
+    if getattr(args, "recombine", False):
+        # Evidence-backed strategy: recombine measured beneficials (not just surrogate-guided combos).
+        recomb = recombine_beneficials(
+            space, variants, fitness, min_gain=args.recombine_min_gain,
+            max_mut=min(args.max_mut, len(pool)), cap=args.generated_cap,
+        )
+        have = set(cset.variants) | set(variants)
+        extra = [v for v in recomb if v not in have]
+        if extra:
+            pr = sur.predict(matrix.encode(extra))
+            n_recombined = len(extra)
+            cset = CandidatePool(
+                variants=list(cset.variants) + extra,
+                pred=Prediction(
+                    np.concatenate([np.asarray(cset.pred.mean, float), np.asarray(pr.mean, float)]),
+                    np.concatenate([np.asarray(cset.pred.std, float), np.asarray(pr.std, float)]),
+                ),
+                mut_count=list(cset.mut_count) + [len(mutations_of(v, space)) for v in extra],
+                pool_positions=cset.pool_positions,
+                stats={**cset.stats, "n_recombined": n_recombined},
+            )
+    wt_mean = float(sur.predict(matrix.encode([space.wt()])).mean[0])
+    if args.plm != "none" or args.naturalness != "none":
+        if not args.wt_fasta:
+            raise ValueError("--plm/--naturalness requires --wt-fasta (full WT background sequence)")
+        emb_cache = EmbeddingCache(args.plm_cache) if args.plm_cache else None
+        nat_cache = EmbeddingCache(args.naturalness_cache) if args.naturalness_cache else None
+        provider = build_provider(args.plm, model=args.plm_model, cache=emb_cache) if args.plm != "none" else None
+        nat = build_naturalness(args.naturalness, model=args.plm_model, cache=nat_cache) if args.naturalness != "none" else None
+        resolved_pooling = resolve_plm_pooling(args.plm_pooling, args.plm_model)
+        cset = plm_rerank(
+            cset, space, variants, fitness, provider=provider, naturalness=nat,
+            wt_sequence=read_fasta(args.wt_fasta), top_k=args.plm_rerank,
+            plm_pooling=resolved_pooling,
+        )
+        wt_mean = float(cset.stats.get("wt_mean", wt_mean))
+        if emb_cache is not None:
+            emb_cache.save()
+        if nat_cache is not None:
+            nat_cache.save()
+    ranking = rank_candidates(
+        cset, space, acquisition=UCB(args.beta), per_count_k=args.per_count_k,
+        global_k=args.top, wt_mean=wt_mean,
+        conformal_q=conf_q, max_measured_nmut=max_meas_nmut,
+    )
+    paths = write_report(ranking, args.outdir, prereg_hash=prereg_hash())
+
+    print(f"[recommend] {length} sites, WT={space.wt()}; generated={cset.stats.get('n_generated', 0)} "
+          f"scored={cset.stats.get('n_scored', 0)}")
+    if n_recombined:
+        print(f"[recommend] recombine: added {n_recombined} recombinations of measured beneficials "
+              f"(>WT) to the candidate pool")
+    if getattr(args, "auto_gate_pairwise", False) or args.contacts_pdb:
+        opened = "pairwise" in matrix.active_blocks()
+        npairs = "all" if pairs is None else str(len(pairs))
+        print(f"[recommend] epistasis block {'OPEN' if opened else 'closed'} "
+              f"(pairs={npairs}{', contact-restricted' if args.contacts_pdb else ''}; "
+              f"{'data justifies' if opened else 'data does not justify' if args.auto_gate_pairwise else 'structure-provided'})")
+    if signal_gate is not None:
+        print(f"[recommend] signal gate [{signal_gate['label']}]: "
+              f"{'KEPT' if signal_gate['included'] else 'DROPPED'} -- {signal_gate['reason']}")
+    if args.plm != "none" or args.naturalness != "none":
+        pooling_note = (
+            f" pooling={resolve_plm_pooling(args.plm_pooling, args.plm_model)}"
+            if args.plm != "none" else ""
+        )
+        print(f"[recommend] rerank PLM={args.plm} naturalness={args.naturalness}{pooling_note} "
+              f"top {cset.stats.get('plm_reranked', 0)} (dim={cset.stats.get('plm_dim', 0)})")
+    if args.max_positions is not None and args.max_positions < length:
+        print(f"[recommend] auto-selected {len(pool)}/{length} positions: "
+              f"{','.join(f'{ref[p]}{p}' for p in pool)}")
+    print(f"[recommend] top {min(args.top, len(ranking.global_ranking))} (global):")
+    for c in ranking.global_ranking[: args.top]:
+        muts = ",".join(c.mutations) or "WT"
+        print(f"  {c.variant}  mu={c.mu:.3f} sigma={c.sigma:.3f} acq={c.acq:.3f} [{muts}] ({c.evidence['risk']})")
+    if conf_q is not None:
+        top = ranking.global_ranking[: args.top]
+        n_abstain = sum(1 for c in top if c.evidence.get("abstain"))
+        n_oob = sum(1 for c in top if c.evidence.get("conformal_scope") == "conformal_oob")
+        scope_note = (
+            "; conformal-derived conservative threshold (calibrated on measured set; "
+            "this candidate is a higher-order combination, out of the calibration distribution)"
+            if n_oob else ""
+        )
+        print(f"[recommend] conformal abstain gate (q_norm={conf_q:.3f}, max measured n_mut="
+              f"{max_meas_nmut}): {n_abstain}/{len(top)} top candidates flagged abstain "
+              f"(cannot conclude they beat WT){f', {n_oob} out-of-distribution' if n_oob else ''}"
+              f"{scope_note}")
+    for kind, p in paths.items():
+        print(f"[recommend] wrote {kind}: {p}")
+    return 0
+
+
+def _funclib_signals(args: argparse.Namespace, space: DesignSpace):
+    """Resolve (ddG table, per-substitution tolerance) from --ddg/--tolerance/--if-logprobs/--msa.
+
+    Shared by `funclib` and `campaign` so both gate the seed library with identical signal
+    precedence: explicit --tolerance > --if-logprobs > --msa (first present wins).
+    """
+    ddg = load_ddg_table(args.ddg) if args.ddg else None
+    tolerance: dict[str, float] | None = None
+    if getattr(args, "tolerance", None):
+        raw = json.loads(Path(args.tolerance).read_text())
+        if raw and all(isinstance(v, dict) for v in raw.values()):
+            tolerance = tolerance_from_logprob_table({int(k): v for k, v in raw.items()}, space)
+        else:
+            tolerance = {str(k): float(v) for k, v in raw.items()}
+    elif args.if_logprobs:
+        tolerance = tolerance_from_logprob_table(load_inverse_folding_logprobs(args.if_logprobs), space)
+    elif args.msa:
+        tolerance = tolerance_from_logprob_table(load_msa_logprobs(args.msa), space)
+    return ddg, tolerance
+
+
+def _funclib_positions(args: argparse.Namespace, seq_len: int) -> list[int]:
+    """Resolve the design region: explicit --positions, else an active-site shell from --holo."""
+    if args.positions:
+        positions = sorted({int(x) for x in args.positions.split(",")})
+    elif args.holo:
+        resn = args.ligand_resnames.split(",") if args.ligand_resnames else None
+        shells = shells_from_pdb(args.holo, ligand_resnames=resn, contact_cutoff=args.contact_cutoff)
+        if args.shell == "both":
+            positions = sorted(set(shells[1]) | set(shells[2]))
+        else:
+            positions = sorted(shells[int(args.shell)])
+    else:
+        raise ValueError("funclib needs --positions or --holo (a ligand pose) to define the design region")
+    bad = [p for p in positions if p < 1 or p > seq_len]
+    if bad:
+        raise ValueError(f"positions {bad} fall outside the WT sequence (length {seq_len})")
+    return positions
+
+
+def cmd_funclib(args: argparse.Namespace) -> int:
+    seq = read_fasta(args.wt_fasta)
+    outdir = Path(args.outdir)
+    outdir.mkdir(parents=True, exist_ok=True)
+    positions = _funclib_positions(args, len(seq))
+    if not positions:
+        (outdir / "funclib.json").write_text(json.dumps(
+            {"abstained": True, "reason": "no positions (apo structure or empty shell)", "library": []}, indent=2))
+        print("[funclib] ABSTAIN: no positions (apo structure or empty shell)")
+        return 0
+
+    ref = {p: seq[p - 1] for p in positions}
+    space = DesignSpace(tuple(positions), ref)
+
+    ddg, tolerance = _funclib_signals(args, space)
+
+    lib = design_library(
+        space, ddg=ddg, tolerance=tolerance,
+        ddg_cutoff=args.ddg_cutoff, tolerance_cutoff=args.tolerance_cutoff,
+        per_position_cap=args.per_position_cap, min_mut=args.min_mut, max_mut=args.max_mut,
+        additive_ddg_budget=args.additive_ddg_budget, max_library=args.max_library,
+        allow_unscored=args.allow_unscored,
+    )
+
+    proposal = {
+        "positions": list(lib.positions),
+        "abstained": lib.abstained,
+        "reason": lib.reason,
+        "stats": lib.stats,
+        "tolerated": {str(p): [[aa, s] for aa, s in lib.tolerated.get(p, [])] for p in lib.positions},
+        "library": [
+            {"variant": c.variant, "mutations": list(c.mutations), "n_mut": c.n_mut, **c.evidence}
+            for c in lib.candidates
+        ],
+    }
+    (outdir / "funclib.json").write_text(json.dumps(proposal, indent=2))
+    import csv as _csv
+    with (outdir / "funclib_library.csv").open("w", newline="") as fh:
+        w = _csv.writer(fh)
+        w.writerow(["mutations", "n_mut", "combo_score", "additive_ddg", "variant"])
+        for c in lib.candidates:
+            w.writerow([":".join(c.mutations), c.n_mut, f"{c.acq:.4f}",
+                        f"{c.evidence['additive_ddg']:.4f}" if "additive_ddg" in c.evidence else "", c.variant])
+
+    if lib.abstained:
+        print(f"[funclib] ABSTAIN: {lib.reason}")
+    else:
+        st = lib.stats
+        gates = "+".join(g for g in ("ddG", "tolerance") if st["gates"][g.lower() if g == "tolerance" else "ddg"])
+        print(f"[funclib] region={st['n_positions']} positions, gates={gates or 'none'}; "
+              f"{st['n_kept_positions']} mutable after filters")
+        print(f"[funclib] naive saturation {st['naive_saturation_space']:.3g} -> library {st['library_size']} "
+              f"(reduction {st['reduction_factor']:.3g}x){' [truncated]' if st['truncated'] else ''}")
+        for p in lib.positions:
+            opts = lib.tolerated.get(p, [])
+            tag = ",".join(aa for aa, _ in opts) if opts else "(excluded: conserved/destabilizing core)"
+            print(f"    {ref[p]}{p}: {tag}")
+        print(f"[funclib] top {min(10, len(lib.candidates))} combinable multipoint targets (to MEASURE, not predictions):")
+        for c in lib.candidates[:10]:
+            extra = f" ddG={c.evidence['additive_ddg']:+.2f}" if "additive_ddg" in c.evidence else ""
+            print(f"  {':'.join(c.mutations)}  score={c.acq:.3f} n_mut={c.n_mut}{extra}")
+    print(f"[funclib] wrote json: {outdir / 'funclib.json'}")
+    print(f"[funclib] wrote csv: {outdir / 'funclib_library.csv'}")
+    return 0
+
+
+def _read_table(path: str) -> tuple[list[dict], list[str]]:
+    """Read a tabular file (CSV/TSV or Excel .xlsx/.xls/.xlsm) -> (rows as dicts, column names).
+
+    Excel needs pandas (clear error otherwise). CSV/TSV is stdlib with BOM stripping and a simple
+    tab-vs-comma delimiter sniff, so files exported straight from a spreadsheet load without a crash.
+    """
+    import csv as _csv
+
+    suffix = Path(path).suffix.lower()
+    if suffix in (".xlsx", ".xls", ".xlsm"):
+        try:
+            import pandas as pd
+        except Exception as exc:  # noqa: BLE001 (no pandas -> tell the user to export CSV)
+            raise ValueError(
+                f"{path} is an Excel file but pandas is unavailable to read it; export it to CSV "
+                "and pass the CSV instead"
+            ) from exc
+        frame = pd.read_excel(path)  # first sheet
+        return (
+            [{str(k): v for k, v in rec.items()} for rec in frame.to_dict("records")],
+            [str(c) for c in frame.columns],
+        )
+    with open(path, newline="", encoding="utf-8-sig") as fh:  # utf-8-sig strips Excel's BOM
+        sample = fh.read(8192)
+        fh.seek(0)
+        delim = "\t" if ("\t" in sample and sample.count("\t") >= sample.count(",")) else ","
+        rdr = _csv.DictReader(fh, delimiter=delim)
+        return list(rdr), list(rdr.fieldnames or [])
+
+
+def _read_landscape(path: str) -> dict[str, float]:
+    """Read a variant,fitness table into {variant: fitness}. Last value wins on dup.
+
+    Accepts CSV/TSV *and* Excel (.xlsx/.xls) -- users routinely upload spreadsheets. Column
+    detection is lenient: a variant column (variant/mutant/mutation/sequence) and a fitness column
+    (fitness/activity/score/value/y), else the first two columns. Rows with a blank or non-numeric
+    fitness are skipped (an unfilled template column, or a predictions-only export).
+    """
+    rows, fieldnames = _read_table(path)
+    if not fieldnames:
+        raise ValueError(f"{path}: no columns found (need a variant column and a fitness column)")
+    cols = {str(c).strip().lower(): c for c in fieldnames}
+    vcol = next((cols[k] for k in ("variant", "variants", "mutant", "mutation", "mutations",
+                                   "sequence", "seq") if k in cols), fieldnames[0])
+    fcol = next((cols[k] for k in ("fitness", "activity", "score", "value", "y", "measured",
+                                   "y_actual", "fit") if k in cols),
+                fieldnames[1] if len(fieldnames) > 1 else None)
+    if fcol is None:
+        raise ValueError(f"{path}: need a fitness column (e.g. 'fitness'/'activity'); found {fieldnames}")
+    table: dict[str, float] = {}
+    for row in rows:
+        v = str(row.get(vcol, "")).strip()
+        raw = row.get(fcol, None)
+        s = "" if raw is None else str(raw).strip()
+        if not v or s == "":
+            continue
+        try:
+            val = float(s)
+        except ValueError:
+            continue
+        if val != val:  # NaN (e.g. a blank Excel cell)
+            continue
+        table[v] = val
+    if not table:
+        raise ValueError(
+            f"{path}: found columns {fieldnames} but no rows with a numeric '{fcol}' value "
+            "(predictions-only or unfilled template? need measured variant,fitness)"
+        )
+    return table
+
+
+def _funclib_space(args: argparse.Namespace, seq: str) -> DesignSpace:
+    positions = _funclib_positions(args, len(seq))
+    ref = {p: seq[p - 1] for p in positions}
+    return DesignSpace(tuple(positions), ref)
+
+
+def cmd_campaign(args: argparse.Namespace) -> int:
+    """funclib -> active-learning handoff: R0 seed (funclib) then measurement-driven AL rounds.
+
+    --simulate LANDSCAPE.csv reproduces/validates the handoff against a measured landscape
+    (D19/D25). Without --simulate it is the live loop: no --measured -> emit the funclib R0 seed
+    plate; --measured given -> fit on accumulated data and propose the next plate over the FULL
+    saturation universe of the design positions (never hard-restricted to the funclib library).
+    """
+    seq = read_fasta(args.wt_fasta)
+    space = _funclib_space(args, seq)
+    outdir = Path(args.outdir)
+    outdir.mkdir(parents=True, exist_ok=True)
+    # auto-MSA seeds the funclib R0 library only; Rk (measured given) is activity-driven and never
+    # uses the tolerance signal, so skip the network build there.
+    if getattr(args, "auto_msa", False) and not args.msa and not args.measured:
+        print("[campaign] no --msa given; building the seed MSA from the WT sequence via ColabFold MMseqs2 ...")
+        a3m = build_msa_mmseqs2(seq)
+        if a3m:
+            msa_path = outdir / "auto_msa.a3m"
+            msa_path.write_text(a3m)
+            args.msa = str(msa_path)
+            print(f"[campaign] auto-MSA: {a3m.count('>')} sequences -> {msa_path}")
+        else:
+            print("[campaign] auto-MSA failed (MMseqs2 API unreachable / no hits); "
+                  "R0 will abstain unless you supply --msa / --ddg / --if-logprobs")
+    ddg, tolerance = _funclib_signals(args, space)
+    make_surrogate = SurrogateSpec(args.model_class)  # picklable factory (enables --jobs)
+
+    if args.simulate:
+        table = _read_landscape(args.simulate)
+        # design positions must match the landscape's combo encoding (one residue per position)
+        wt = space.wt()
+        if wt not in table:
+            print(f"[campaign] note: WT combo {wt!r} not in landscape (ok if landscape lacks WT row)")
+        constraint_info = None
+        if args.stability_constraint:
+            if ddg is None:
+                raise ValueError("--stability-constraint requires --ddg (predicted folding ddG table)")
+            global_win = max(table, key=table.get)
+            stable = set(stable_variants(
+                list(table), space, ddg, ddg_cutoff=args.ddg_cutoff,
+                additive_budget=args.additive_ddg_budget,
+            ))
+            stable.add(wt)  # always allow WT (the campaign baseline)
+            kept = {v: f for v, f in table.items() if v in stable}
+            constr_win = max(kept, key=kept.get) if kept else None
+            constraint_info = {
+                "global_activity_winner": global_win,
+                "global_winner_fitness": table[global_win],
+                "global_winner_passes_stability": global_win in stable,
+                "n_stable": len(kept), "n_total": len(table),
+                "constrained_optimum": constr_win,
+                "constrained_optimum_fitness": (kept[constr_win] if constr_win else None),
+            }
+            table = kept
+            print(f"[campaign] stability constraint (ddG<= {args.ddg_cutoff}"
+                  f"{f', budget {args.additive_ddg_budget}' if args.additive_ddg_budget is not None else ''}): "
+                  f"{len(kept)}/{constraint_info['n_total']} variants stable; "
+                  f"global activity winner {global_win} {'PASSES' if constraint_info['global_winner_passes_stability'] else 'FAILS'} the gate")
+        seed_lib = None
+        results = {}
+        for strat in args.strategies:
+            if strat == "funclib":
+                sv, seed_lib = funclib_seed_variants(
+                    space, plate=args.plate, ddg=ddg, tolerance=tolerance,
+                    ddg_cutoff=args.ddg_cutoff, tolerance_cutoff=args.tolerance_cutoff,
+                    per_position_cap=args.per_position_cap, min_mut=args.min_mut,
+                    max_mut=args.max_mut, additive_ddg_budget=args.additive_ddg_budget,
+                    allow_unscored=args.allow_unscored,
+                )
+                if not sv:
+                    print(f"[campaign] funclib ABSTAINED ({seed_lib.reason}); skipping funclib arm")
+                    continue
+            elif strat == "singles":
+                sv = single_mutant_variants(space)
+            elif strat == "random":
+                sv = None
+            else:
+                raise ValueError(f"unknown strategy {strat!r}")
+            res = simulate_campaign(
+                table, space, seed_variants=sv, strategy=strat, plate=args.plate,
+                rounds=args.rounds, n_seeds=args.seeds, beta=args.beta,
+                make_surrogate=make_surrogate, n_jobs=args.jobs,
+            )
+            results[strat] = res
+
+        payload = {
+            "mode": "simulate", "landscape": args.simulate,
+            "positions": list(space.positions), "wt": space.wt(),
+            "plate": args.plate, "rounds": args.rounds, "n_seeds": args.seeds,
+            "acquisition": "greedy" if args.beta <= 0 else f"ucb(beta={args.beta})",
+            "surrogate": args.model_class,
+            "stability_constraint": constraint_info,
+            "funclib_seed_size": (len(seed_lib.candidates) if seed_lib else None),
+            "strategies": {
+                s: {
+                    "winner_reach_rate": r.winner_reach_rate,
+                    "rounds_to_winner_median": r.rounds_to_winner_median,
+                    "best_found_mean": r.best_found_mean,
+                    "best_found_percentile_mean": r.best_found_percentile_mean,
+                    "per_seed": r.per_seed,
+                } for s, r in results.items()
+            },
+        }
+        (outdir / "campaign_simulate.json").write_text(json.dumps(payload, indent=2))
+        print(f"[campaign] simulate over {len(table)} measured variants; positions={list(space.positions)} "
+              f"plate={args.plate} rounds={args.rounds} seeds={args.seeds} "
+              f"acq={'greedy' if args.beta<=0 else f'ucb{args.beta}'}")
+        for s, r in results.items():
+            rtw = f"{r.rounds_to_winner_median:.1f}" if r.rounds_to_winner_median is not None else "n/a"
+            print(f"  {s:8s}: winner-reach {r.winner_reach_rate*100:5.1f}%  median rounds-to-winner {rtw}  "
+                  f"best-found percentile {r.best_found_percentile_mean:.3f}")
+        print(f"[campaign] wrote {outdir / 'campaign_simulate.json'}")
+        return 0
+
+    # ---- live mode ----
+    measured_paths = args.measured or []
+    if not measured_paths:
+        # R0: cold start -> funclib seed plate to MEASURE (AL is blind with zero data).
+        sv, lib = funclib_seed_variants(
+            space, plate=args.plate, ddg=ddg, tolerance=tolerance,
+            ddg_cutoff=args.ddg_cutoff, tolerance_cutoff=args.tolerance_cutoff,
+            per_position_cap=args.per_position_cap, min_mut=args.min_mut,
+            max_mut=args.max_mut, additive_ddg_budget=args.additive_ddg_budget,
+            allow_unscored=args.allow_unscored,
+        )
+        if lib.abstained or not sv:
+            print(f"[campaign] R0 ABSTAIN: {lib.reason or 'no seed variants'} (supply --msa/--ddg/--if-logprobs or relax cutoffs)")
+            return 0
+        import csv as _csv
+
+        def _r0_rows(cands):
+            for c in cands:
+                yield [":".join(c.mutations) or "WT", c.n_mut, f"{c.acq:.4f}", c.variant]
+
+        header = ["mutations", "n_mut", "seed_score", "variant"]
+        top = lib.candidates[: args.plate]
+        for name, rows in (("round0_plate.csv", top), ("round0_all.csv", lib.candidates)):
+            with (outdir / name).open("w", newline="") as fh:
+                w = _csv.writer(fh)
+                w.writerow(header)
+                w.writerows(_r0_rows(rows))
+        with (outdir / "round0_measured_template.csv").open("w", newline="") as fh:
+            w = _csv.writer(fh)
+            w.writerow(["variant", "fitness"])
+            for c in top:
+                w.writerow([c.variant, ""])
+        print(f"[campaign] R0 funclib seed over positions {list(space.positions)}: "
+              f"{len(top)} to MEASURE (round0_plate.csv), {len(lib.candidates)} total candidates "
+              f"(round0_all.csv)")
+        print("[campaign] fill the 'fitness' column of round0_measured_template.csv, then re-run with "
+              "--measured round0_measured_template.csv for R1 (AL over the full saturation space).")
+        return 0
+
+    # Rk: fit on accumulated measurements, propose the next plate over the FULL saturation universe.
+    table: dict[str, float] = {}
+    for p in measured_paths:
+        table.update(_read_landscape(p))
+    variants = list(table)
+    if getattr(args, "wt_fitness", None) is not None:
+        # WT is not on the plate, but under WT-normalisation its (relative) activity is known
+        # (e.g. 1.0). Anchor it so "beats WT" and the surrogate baseline are exact, not predicted.
+        table.setdefault(space.wt(), float(args.wt_fitness))
+        variants = list(table)
+    # Guard: measured variants must fit the resolved design region. A whole-protein single-mutant
+    # scan (e.g. "29I", or positions outside the active-site shell) is a different regime -- abstain
+    # with guidance instead of crashing deep in the variant parser / encoder.
+    _measured_only = [v for v in variants if v != space.wt()]
+    _unfit: dict[str, str] = {}
+    for _v in _measured_only:
+        try:
+            mutations_of(_v, space)
+        except ValueError as _exc:
+            _unfit[_v] = str(_exc)
+    if _measured_only and len(_unfit) == len(_measured_only):
+        _lo, _hi = space.positions[0], space.positions[-1]
+        print(f"[campaign] ABSTAIN: none of the {len(_measured_only)} measured variants fit the design "
+              f"region (positions {_lo}-{_hi}, {space.n_positions} sites).")
+        for _v, _why in list(_unfit.items())[:4]:
+            print(f"    {_v}: {_why}")
+        print("[campaign] this looks like a whole-protein single-mutant scan, not active-site "
+              "combinatorial data for these positions.")
+        print("[campaign] -> rank positions from a scan with `shellde hotspots <scan.csv>`, then "
+              "`round --positions <top>`; or set --positions to the measured positions.")
+        print("[campaign] -> variant notation must be [WT][pos][MT] (e.g. V29I), not 29I.")
+        return 1
+    if _unfit:
+        print(f"[campaign] WARNING: dropping {len(_unfit)}/{len(_measured_only)} measured variants "
+              f"outside the design region (e.g. {next(iter(_unfit))}); fitting on the rest.")
+        variants = [v for v in variants if v == space.wt() or v not in _unfit]
+    fitness = np.asarray([table[v] for v in variants], dtype=float)
+    matrix = FeatureMatrix(space, default_blocks(space))
+    if args.if_logprobs:
+        matrix = FeatureMatrix(space, [*default_blocks(space), InverseFoldingBlock(space, load_inverse_folding_logprobs(args.if_logprobs))])
+    x_enc = matrix.encode(variants)
+    sur = make_surrogate().fit(x_enc, fitness)
+    conf_q = (
+        cross_conformal_normalized_q(x_enc, fitness, make_surrogate)
+        if len(variants) >= 8 and float(np.std(fitness)) > 0.0 else None
+    )
+    max_meas_nmut = max(len(mutations_of(v, space)) for v in variants)
+    cset = generate_candidates(
+        sur, matrix, pinned_positions=list(space.positions), max_mut=min(args.max_mut, space.n_positions),
+        generated_cap=args.generated_cap, scored_cap=args.scored_cap, beta=args.beta, seed=0,
+    )
+    wt_mean = float(sur.predict(matrix.encode([space.wt()])).mean[0])
+    if getattr(args, "plm", "none") != "none" or getattr(args, "naturalness", "none") != "none":
+        # EVOLVEpro-style Rk: refit a surrogate on the measured data over ESM embeddings and rerank the
+        # top-K one-hot candidates. Embeds only measured + shortlist (tractable). GPU-recommended.
+        emb_cache = EmbeddingCache(args.plm_cache) if getattr(args, "plm_cache", None) else None
+        nat_cache = EmbeddingCache(args.naturalness_cache) if getattr(args, "naturalness_cache", None) else None
+        provider = build_provider(args.plm, model=args.plm_model, cache=emb_cache) if args.plm != "none" else None
+        nat = (build_naturalness(args.naturalness, model=args.plm_model, cache=nat_cache)
+               if args.naturalness != "none" else None)
+        resolved_pooling = resolve_plm_pooling(args.plm_pooling, args.plm_model)
+        print(f"[campaign] Rk rerank: refit PLM/naturalness surrogate on {len(variants)} measured -> "
+              f"rerank top {args.plm_rerank} candidates ({args.plm}/{args.naturalness})")
+        cset = plm_rerank(cset, space, variants, fitness, provider=provider, naturalness=nat,
+                          wt_sequence=read_fasta(args.wt_fasta), top_k=args.plm_rerank,
+                          plm_pooling=resolved_pooling)
+        wt_mean = float(cset.stats.get("wt_mean", wt_mean))
+        if emb_cache is not None:
+            emb_cache.save()
+        if nat_cache is not None:
+            nat_cache.save()
+    ranking = rank_candidates(
+        cset, space, acquisition=UCB(max(args.beta, 0.0)), per_count_k=args.plate,
+        global_k=args.plate, wt_mean=wt_mean, conformal_q=conf_q, max_measured_nmut=max_meas_nmut,
+    )
+    rk = len(measured_paths)
+    import csv as _csv
+
+    def _rk_rows(cands):
+        for c in cands:
+            yield [":".join(c.mutations) or "WT", len(c.mutations), f"{c.mu:.4f}", f"{c.sigma:.4f}",
+                   f"{c.acq:.4f}", c.evidence.get("risk", ""), c.variant]
+
+    header = ["mutations", "n_mut", "mu", "sigma", "acq", "risk", "variant"]
+    top = ranking.global_ranking[: args.plate]
+    for name, rows in ((f"round{rk}_plate.csv", top), (f"round{rk}_all.csv", ranking.global_ranking)):
+        with (outdir / name).open("w", newline="") as fh:
+            w = _csv.writer(fh)
+            w.writerow(header)
+            w.writerows(_rk_rows(rows))
+    with (outdir / f"round{rk}_measured_template.csv").open("w", newline="") as fh:
+        w = _csv.writer(fh)
+        w.writerow(["variant", "fitness"])
+        for c in top:
+            w.writerow([c.variant, ""])
+    print(f"[campaign] R{rk}: fit on {len(variants)} measured; {len(top)} to MEASURE "
+          f"(round{rk}_plate.csv), {len(ranking.global_ranking)} scored candidates (round{rk}_all.csv) "
+          f"over full saturation of {space.n_positions} positions")
+    for c in top[: min(10, len(top))]:
+        print(f"  [{','.join(c.mutations) or 'WT'}]  mu={c.mu:.3f} sigma={c.sigma:.3f} "
+              f"acq={c.acq:.3f} ({c.evidence.get('risk', '')})")
+    print(f"[campaign] fill the 'fitness' column of round{rk}_measured_template.csv for the next round")
+    try:  # auto-advise: is the surrogate trustworthy yet, or keep measuring? (advisory, never fatal)
+        adv = data_readiness(space, variants, fitness)
+        sp = "n/a" if adv["heldout_spearman"] is None else f"{adv['heldout_spearman']:+.3f}"
+        print(f"[campaign] advise: held-out Spearman={sp}, trustworthy={adv['model_trustworthy']} "
+              f"-> {adv['recommendation'].upper()} ({adv['why']})")
+        _print_epistasis_next_step(
+            adv["recommendation"], getattr(args, "measured", None), space.positions,
+        )
+    except Exception:  # noqa: BLE001 (advisory only)
+        pass
+    return 0
+
+
+def _resolve_site_ladder(
+    args: argparse.Namespace, seq: str
+) -> tuple[ResolveResult | None, Path | None]:
+    """Evidence ladder (UniProt features -> UniProt-linked PDB cocrystal -> AlphaFold fetch),
+    every position sequence-aligned onto the WT numbering. Returns (result, alphafold_model_path).
+    Returns (None, None) when no lookup source (--uniprot/--query/--pdb) was given. Shared by
+    ``resolve-site`` and the ``round`` front door so both use one ladder with one behaviour.
+    """
+    if getattr(args, "uniprot", None) == "auto":
+        accs = uniprot_from_sequence(seq, timeout=args.timeout)
+        if accs:
+            print(f"[resolve-site] exact UniProt match for this sequence: {accs[0]}"
+                  f"{f' (+{len(accs) - 1} identical entrie(s))' if len(accs) > 1 else ''}")
+            args.uniprot = accs[0]
+        else:
+            print("[resolve-site] no EXACT UniProt match for this sequence (engineered construct?) "
+                  "-> pass --uniprot ACC / --query / --pdb / --positions")
+            args.uniprot = None
+    lig = args.ligand_resnames.split(",") if args.ligand_resnames else None
+
+    def _try_pdb(pdb_ref: str) -> ResolveResult:
+        # accept a LOCAL structure file (your own AlphaFold model or cocrystal) OR an RCSB ID
+        if Path(pdb_ref).is_file():
+            text = Path(pdb_ref).read_text()
+            pid = Path(pdb_ref).stem
+        else:
+            try:
+                text = fetch_pdb(pdb_ref, timeout=args.timeout)
+            except Exception as exc:  # noqa: BLE001 (network/HTTP failures -> skip this PDB)
+                return ResolveResult(source=f"PDB:{pdb_ref}", abstained=True,
+                                     reason=f"download failed ({exc})")
+            pid = pdb_ref
+        return resolve_from_pdb(seq, text, pdb_id=pid, ligand_resnames=lig,
+                                contact_cutoff=args.contact_cutoff, min_coverage=args.min_coverage)
+
+    acc = args.uniprot
+    if args.pdb and (args.uniprot or args.query):
+        # Both a structure AND a UniProt source: the PDB cocrystal shell is the (broad) design set,
+        # and UniProt curated sites annotate its catalytic core (+ QC that they fall in the shell).
+        # --exclude-catalytic then designs only the tunable 2nd-shell ring (avoids saturating the
+        # usually-lethal catalytic core).
+        res = _try_pdb(args.pdb)
+        if res is not None and not res.abstained:
+            catalytic: set[int] = set()
+            try:
+                udata = fetch_uniprot(accession=args.uniprot, query=args.query, timeout=args.timeout)
+            except Exception:  # noqa: BLE001 (UniProt lookup failure -> just skip annotation)
+                udata = None
+            if udata:
+                ures = resolve_from_entry(seq, udata, min_coverage=args.min_coverage)
+                if not ures.abstained:
+                    catalytic = set(ures.positions)
+            in_shell = sorted(catalytic & set(res.positions))
+            print(f"[resolve-site] combine: PDB shell {len(res.positions)} positions + UniProt catalytic "
+                  f"{len(catalytic)}; {len(in_shell)}/{len(catalytic)} catalytic residues fall in the shell (QC)")
+            res.consensus = build_consensus({
+                "pdb_cocrystal_shell": list(res.positions),
+                "uniprot_catalytic": sorted(catalytic),
+            })
+            print(f"[resolve-site] evidence consensus: {consensus_summary(res.consensus)} "
+                  "(high = >=2 evidence types agree; measure high-confidence positions first)")
+            if getattr(args, "exclude_catalytic", False):
+                keep = [p for p in res.positions if p not in catalytic]
+                res.positions = keep
+                res.sites = [s for s in res.sites if s.wt_position in keep]
+                res.source = f"{res.source}+UniProt(-catalytic)"
+                print(f"[resolve-site] --exclude-catalytic: designing over {len(keep)} tunable-ring "
+                      f"positions (dropped {len(in_shell)} catalytic-core positions {in_shell})")
+            else:
+                res.source = f"{res.source}+UniProt(catalytic-flagged)"
+                if in_shell:
+                    print(f"[resolve-site] catalytic core flagged: {in_shell} "
+                          "(pass --exclude-catalytic to design only the tunable ring)")
+    elif args.pdb:
+        res = _try_pdb(args.pdb)
+    elif not (args.uniprot or args.query):
+        return None, None
+    else:
+        try:
+            data = fetch_uniprot(accession=args.uniprot, query=args.query, timeout=args.timeout)
+        except Exception as exc:  # noqa: BLE001 (network/HTTP/timeout -> abstain, never crash)
+            return ResolveResult(source="UniProt", abstained=True,
+                                 reason=f"UniProt lookup failed ({exc})"), None
+        if data is None:
+            return ResolveResult(source="UniProt", abstained=True,
+                                 reason="no UniProt entry matched"), None
+        acc = acc or data.get("primaryAccession")
+        res = resolve_from_entry(seq, data, min_coverage=args.min_coverage)
+        if res.abstained and not args.no_pdb_fallback:
+            pdb_ids = pdb_ids_from_uniprot(data)
+            if pdb_ids:
+                print(f"[resolve-site] UniProt features did not map ({res.reason}); "
+                      f"trying {min(len(pdb_ids), args.max_pdb)} linked PDB cocrystal(s): {pdb_ids[:args.max_pdb]}")
+                for pid in pdb_ids[: args.max_pdb]:
+                    cand = _try_pdb(pid)
+                    print(f"[resolve-site]   {pid}: {'ok' if not cand.abstained else 'skip -- ' + cand.reason}")
+                    if not cand.abstained:
+                        res = cand
+                        break
+
+    outdir = Path(args.outdir)
+    outdir.mkdir(parents=True, exist_ok=True)
+    af_saved = None
+    if res.abstained and acc and not args.no_alphafold:
+        af = fetch_alphafold(acc, timeout=args.timeout)
+        if af:
+            af_saved = outdir / f"AF-{acc}.pdb"
+            af_saved.write_text(af)
+            if args.apo_pocket:
+                apo = resolve_from_apo(seq, af, fpocket_bin=args.fpocket)
+                if not apo.abstained:
+                    res = apo  # predicted-pocket -- LOW confidence, must verify
+    return res, af_saved
+
+
+def _find_holo_pdb(args: argparse.Namespace, seq: str) -> str | None:
+    """--find-holo: get a WT query structure (--pdb, or the AlphaFold model via accession) -> Foldseek
+    -> top ligand-bound (holo) PDB id, to use as the design region. None if nothing usable."""
+    query = None
+    if args.pdb:
+        query = Path(args.pdb).read_text() if Path(args.pdb).exists() else fetch_pdb(args.pdb, timeout=args.timeout)
+    else:
+        acc = args.uniprot if args.uniprot and args.uniprot != "auto" else None
+        if acc is None and args.uniprot == "auto":
+            hits = uniprot_from_sequence(seq, timeout=args.timeout)
+            acc = hits[0] if hits else None
+        if acc:
+            try:
+                query = fetch_alphafold(acc, timeout=args.timeout)
+            except Exception:  # noqa: BLE001
+                query = None
+    if not query:
+        print("[round] --find-holo: no query structure (need --pdb, or --uniprot ACC/auto for the "
+              "AlphaFold model); skipping")
+        return None
+    print("[round] --find-holo: Foldseek-searching for ligand-bound homologs (network; ~1 min)...")
+    cands = find_holo_homolog(query, timeout=args.timeout)
+    if not cands:
+        print("[round] --find-holo: no ligand-bound homolog found -> continuing with the normal ladder")
+        return None
+    print("[round] holo homolog candidates: " + ", ".join(
+        f"{c['pdb_id']}(lig {';'.join(c['ligands'])}; E={c['evalue']:.0e}, cov {c['coverage']:.0%})"
+        for c in cands))
+    top = cands[0]["pdb_id"]
+    print(f"[round] --find-holo: using {top} as --pdb (override by passing a different pdb=)")
+    return top
+
+
+def cmd_round(args: argparse.Namespace) -> int:
+    """One command per wet-lab round: auto-resolve the active-site design region (evidence ladder),
+    then run the campaign round. No --measured -> emit the R0 funclib seed plate to MEASURE; add each
+    round's results via --measured to get the next AL plate over the full saturation universe. The
+    front door: WT FASTA + an accession/PDB in, a plate CSV out, no position bookkeeping by hand.
+    """
+    seq = read_fasta(args.wt_fasta)
+    if getattr(args, "find_holo", False) and not args.pdb and not args.positions and not args.holo:
+        holo_id = _find_holo_pdb(args, seq)
+        if holo_id:
+            args.pdb = holo_id
+    if not args.positions and not args.holo:
+        if not (args.uniprot or args.query or args.pdb):
+            print("[round] need a design region: --positions, --holo <PDB>, or a lookup source "
+                  "(--uniprot ACC / --query / --pdb ID) for the auto evidence ladder")
+            return 1
+        res, af_saved = _resolve_site_ladder(args, seq)
+        if res is None or res.abstained or not res.positions:
+            reason = "no lookup source" if res is None else (res.reason or "no positions mapped")
+            print(f"[round] active-site auto-resolve ABSTAINED ({reason}); supply --positions or --holo <PDB>")
+            if af_saved:
+                print(f"[round] fetched AlphaFold model -> {af_saved} (apo; add a ligand pose and pass via --pdb)")
+            return 1
+        args.positions = ",".join(map(str, res.positions))
+        print(f"[round] resolved {len(res.positions)} active-site positions from {res.source} "
+              f"(WT-coverage {res.coverage:.0%}): {args.positions}")
+    return cmd_campaign(args)
+
+def cmd_resolve_site(args: argparse.Namespace) -> int:
+    """Resolve active-site/binding positions via an evidence ladder, mapped to the WT numbering.
+
+    Ladder: (1) UniProt curated site features; (2) if those do not map and fallback is allowed, a
+    UniProt-linked PDB cocrystal -> active-site shells. ``--pdb ID`` forces the structure path.
+    Abstains (defer to --holo / --positions) when no evidence maps. Every position is sequence-aligned
+    onto WT so numbering offsets (transit peptide / species / PDB gaps) are handled, never guessed.
+    """
+    seq = read_fasta(args.wt_fasta)
+    res, af_saved = _resolve_site_ladder(args, seq)
+    if res is None:
+        print("[resolve-site] no --uniprot/--query/--pdb given; cannot look up evidence")
+        print("[resolve-site] -> provide --uniprot ACC, --query, or --pdb ID (or use --holo/--positions)")
+        return 0
+    if res.source == "UniProt" and res.reason == "no UniProt entry matched" and not res.sites:
+        print("[resolve-site] no UniProt entry matched; abstaining -> use --holo/--positions")
+        return 0
+    outdir = Path(args.outdir)
+    outdir.mkdir(parents=True, exist_ok=True)
+
+    payload = {
+        "source": res.source, "wt_coverage": res.coverage, "abstained": res.abstained,
+        "reason": res.reason, "positions": res.positions, "consensus": res.consensus,
+        "alphafold_model": (str(af_saved) if af_saved else None),
+        "sites": [
+            {"wt_position": s.wt_position, "residue": s.residue, "source_position": s.source_position,
+             "types": list(s.types), "ligands": list(s.ligands), "confidence": s.confidence}
+            for s in res.sites
+        ],
+        "unmapped_features": [
+            {"type": f.type, "uniprot_position": f.start, "ligand": f.ligand, "evidence": f.evidence}
+            for f in res.unmapped
+        ],
+    }
+    (outdir / "resolve_site.json").write_text(json.dumps(payload, indent=2))
+    if getattr(args, "find_holo", False):
+        qtext = None
+        if af_saved:
+            qtext = Path(af_saved).read_text()
+        elif getattr(args, "holo", None) and Path(args.holo).exists():
+            qtext = Path(args.holo).read_text()
+        elif args.pdb:
+            qtext = Path(args.pdb).read_text() if Path(args.pdb).exists() else fetch_pdb(args.pdb, timeout=args.timeout)
+        if not qtext:
+            print("[resolve-site] --find-holo needs a query structure (AlphaFold model / --holo / --pdb); none available")
+        else:
+            print("[resolve-site] --find-holo: Foldseek-searching for ligand-bound homologs (network; ~1 min)...")
+            cands = find_holo_homolog(qtext, timeout=args.timeout)
+            if cands:
+                print(f"[resolve-site] holo homolog candidates ({len(cands)}):")
+                for c in cands:
+                    print(f"    {c['pdb_id']}  ligands={';'.join(c['ligands'])}  "
+                          f"(E={c['evalue']:.0e}, coverage {c['coverage']:.0%}, Foldseek rank {c['rank']})")
+                print(f"[resolve-site] -> re-run with  --pdb {cands[0]['pdb_id']}  to use its ligand pose (aligned onto WT)")
+            else:
+                print("[resolve-site] --find-holo: no ligand-bound homolog found (abstained)")
+    if res.abstained:
+        print(f"[resolve-site] ABSTAIN ({res.source}, WT-coverage {res.coverage:.0%}): {res.reason}")
+        if af_saved:
+            print(f"[resolve-site] fetched AlphaFold model -> {af_saved} (predicted, APO / no ligand)")
+            if args.apo_pocket:
+                print("[resolve-site] apo-pocket (fpocket) found no pocket that maps to WT")
+            else:
+                print("[resolve-site] -> add a ligand pose and pass via --pdb, or try --apo-pocket "
+                      "(fpocket; LOW confidence -- can miss the catalytic site), or --positions.")
+        print("[resolve-site] -> options: --positions (manual); --pdb <RCSB id or local holo PDB>; --holo in campaign.")
+        print(f"[resolve-site] wrote {outdir / 'resolve_site.json'}")
+        return 0
+    if any(s.confidence == "predicted-pocket" for s in res.sites):
+        print("[resolve-site] WARNING: predicted-pocket (apo fpocket) is LOW-confidence and can MISS the "
+              "catalytic site (it did on ispS in our test). Verify before committing a campaign.")
+    print(f"[resolve-site] {res.source}  WT-coverage {res.coverage:.0%}  {len(res.sites)} mapped site positions")
+    for s in res.sites:
+        ligs = f" lig={';'.join(s.ligands)}" if s.ligands else ""
+        print(f"  {s.residue}{s.wt_position}  [{','.join(s.types)}]{ligs}  ({s.confidence}; src {s.source_position})")
+    if res.unmapped:
+        print(f"[resolve-site] {len(res.unmapped)} UniProt features did NOT align onto WT "
+              f"(numbering/region mismatch) -- not used (see json)")
+    pstr = ",".join(map(str, res.positions))
+    print(f"[resolve-site] positions: {pstr}")
+    print(f"[resolve-site] -> next: shellde campaign {args.wt_fasta} --positions {pstr} --msa ... --plate 95")
+    print(f"[resolve-site] wrote {outdir / 'resolve_site.json'}")
+    return 0
+
+
+def cmd_bench(args: argparse.Namespace) -> int:
+    alphabet = AA_ALPHABET[: args.q]
+    positions = tuple(range(1, args.n_sites + 1))
+    space = DesignSpace(positions, {p: alphabet[0] for p in positions}, alphabet=alphabet)
+    out = run_spectrum(
+        space, alphas=args.alphas, seeds=list(range(args.seeds)),
+        n_init=args.n_init, batch_size=args.batch_size, n_rounds=args.n_rounds,
+    )
+    payload = stamp(out)
+    outdir = Path(args.outdir)
+    outdir.mkdir(parents=True, exist_ok=True)
+    (outdir / "spectrum.json").write_text(json.dumps(payload, indent=2))
+    print(f"[bench] prereg {payload['prereg_hash'][:12]} | sites={args.n_sites} q={args.q} seeds={args.seeds}")
+    _print_spectrum(out)
+    print(f"[bench] wrote {outdir / 'spectrum.json'}")
+    return 0
+
+
+def cmd_report(args: argparse.Namespace) -> int:
+    path = Path(args.path)
+    if not path.exists():
+        print(f"[report] not found: {path}", file=sys.stderr)
+        return 1
+    data = json.loads(path.read_text())
+    if "per_alpha" in data:
+        _print_spectrum(data)
+    elif "global_ranking" in data:
+        print(f"[report] {len(data['global_ranking'])} global candidates (prereg {str(data.get('prereg_hash'))[:12]})")
+        for i, c in enumerate(data["global_ranking"][:20], start=1):
+            print(f"  {i}. {c['variant']} acq={c['acq']:.3f} risk={c['risk']}")
+    else:
+        print("[report] unrecognised JSON (expected a bench spectrum or a recommend report)")
+        return 1
+    return 0
+
+
+def _print_spectrum(out: dict) -> None:
+    for alpha, row in out["per_alpha"].items():
+        mr = row["mean_regret"]
+        print(f"  alpha={alpha}: " + " ".join(f"{k}={v:.4f}" for k, v in mr.items()))
+        for name, comp in row["ours_vs"].items():
+            sig = "sig" if comp.get("fdr_significant") else "-"
+            print(f"      ours vs {name}: dReg={comp['regret_reduction_mean']:+.4f} "
+                  f"p={comp['p']:.3f} [{sig}]")
+
+
+def _read_singles(path: str, mutation_col: str | None, score_col: str | None):
+    """Read a single-mutant scan CSV -> [(mutation_token, score)], auto-detecting the columns.
+
+    Mutation column: named variant/mutation/mutant, else the first column whose values look like
+    ``V100F``. Score column: prefer a measured column (y_actual/fitness/activity/measured) with
+    numeric values, else a predicted one (score/y_pred/prediction/pred). Returns (rows, mut_col, score_col).
+    """
+    from shellde.hotspots import parse_mutation
+
+    rows, fields = _read_table(path)  # CSV/TSV or Excel
+    low = {f.lower(): f for f in fields}
+
+    if mutation_col is None:
+        for cand in ("variant", "mutation", "mutant", "mut"):
+            if cand in low:
+                mutation_col = low[cand]
+                break
+        else:
+            for f in fields:
+                v = next((r[f] for r in rows if r.get(f)), "")
+                if parse_mutation(str(v)):
+                    mutation_col = f
+                    break
+    if mutation_col is None:
+        raise ValueError("could not find a mutation column (e.g. 'variant' with tokens like V100F)")
+
+    def _numeric_count(f: str) -> int:
+        c = 0
+        for r in rows:
+            v = r.get(f, "")
+            if v in ("", None):
+                continue
+            try:
+                float(v)
+                c += 1
+            except (TypeError, ValueError):
+                return -1
+        return c
+
+    if score_col is None:
+        for cand in ("y_actual", "fitness", "activity", "measured", "score", "y_pred", "prediction", "pred"):
+            if cand in low and _numeric_count(low[cand]) > 0:
+                score_col = low[cand]
+                break
+    if score_col is None:
+        raise ValueError("could not find a numeric score column (e.g. fitness/activity/y_pred)")
+
+    out = [(r[mutation_col], r[score_col]) for r in rows
+           if r.get(mutation_col) and r.get(score_col) not in ("", None)]
+    return out, mutation_col, score_col
+
+
+def cmd_hotspots(args: argparse.Namespace) -> int:
+    """Scan->focus bridge: rank hotspot positions from a whole-protein single-mutant scan."""
+    singles, mcol, scol = _read_singles(args.scan, args.mutation_col, args.score_col)
+    hs = rank_hotspots(singles, top_k=args.top_k, metric=args.metric,
+                       baseline=args.baseline, min_effect=args.min_effect)
+    if not hs:
+        print("[hotspots] no positions ranked -- check the CSV (a mutation column like V100F "
+              "+ a numeric score column)")
+        return 1
+    print(f"[hotspots] scan {args.scan}: mutation='{mcol}', score='{scol}', metric={args.metric}, "
+          f"top {len(hs)} of the scanned positions")
+    for h in hs:
+        print(f"  {h.wt}{h.position}  best {h.best_sub} ({h.best_effect:.4g})  n_beneficial={h.n_beneficial}")
+    positions = ",".join(str(h.position) for h in sorted(hs, key=lambda x: x.position))
+    print(f"[hotspots] positions: {positions}")
+    print(f"[hotspots] -> next: shellde round WT.fasta --positions {positions} --auto-msa "
+          "(combinatorial AL over the hotspots: the candidate pool is multi-mutant, "
+          "the fitted model is additive by default)")
+    outdir = Path(args.outdir)
+    outdir.mkdir(parents=True, exist_ok=True)
+    (outdir / "hotspots.json").write_text(json.dumps({
+        "scan": args.scan, "metric": args.metric, "positions": [h.position for h in hs],
+        "hotspots": [{"position": h.position, "wt": h.wt, "best_sub": h.best_sub,
+                      "best_effect": h.best_effect, "n_beneficial": h.n_beneficial} for h in hs],
+    }, indent=2))
+    print(f"[hotspots] wrote {outdir / 'hotspots.json'}")
+    return 0
+
+
+def _add_plm_args(p: argparse.ArgumentParser) -> None:
+    """PLM/naturalness options for the Rk surrogate rerank (EVOLVEpro-style). Shared by campaign/round."""
+    p.add_argument("--plm", default="none", choices=["none", "esmc", "esm2"],
+                   help="PLM embedding surrogate for the Rk plate (EVOLVEpro-style: refit on YOUR measured "
+                        "data over ESM embeddings, rerank the plate). GPU-recommended; opt-in")
+    p.add_argument("--plm-model", dest="plm_model", default="", help="specific PLM model, e.g. esmc_600m")
+    p.add_argument("--plm-pooling", dest="plm_pooling", default="auto", choices=["auto", "mean", "site"],
+                   help="embedding pooling; auto -> site for esmc_600m, else mean")
+    p.add_argument("--plm-cache", dest="plm_cache", default=None,
+                   help="embedding cache path (reuse across rounds so ESM runs once per sequence)")
+    p.add_argument("--plm-rerank", dest="plm_rerank", type=int, default=256,
+                   help="rerank the top-K one-hot candidates with the PLM surrogate (default 256)")
+    p.add_argument("--naturalness", default="none", choices=["none", "esmc", "esm2"],
+                   help="zero-shot naturalness block for the Rk rerank")
+    p.add_argument("--naturalness-cache", dest="naturalness_cache", default=None, help="naturalness cache path")
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="shellde",
+        description="Low-N, acquisition-driven mutation recommendation (calibrated-additive default; "
+                    "pairwise epistasis is an opt-in on `recommend` only, CV-gated under "
+                    "--auto-gate-pairwise, while --contacts-pdb opens it with no gate)",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    rc = sub.add_parser("recommend", help="rank mutation candidates from a measured CSV")
+    rc.add_argument("measured", help="CSV with variant,fitness columns")
+    rc.add_argument("--outdir", default="outputs/recommend")
+    rc.add_argument("--max-mut", dest="max_mut", type=int, default=3)
+    rc.add_argument("--max-positions", dest="max_positions", type=int, default=None)
+    rc.add_argument("--interaction-aware-positions", dest="interaction_aware", action="store_true",
+                    help="rank positions by interaction-aware importance (for epistatic targets)")
+    rc.add_argument("--top", type=int, default=20)
+    rc.add_argument("--per-count-k", dest="per_count_k", type=int, default=10)
+    rc.add_argument("--model-class", dest="model_class", default="ensemble",
+                    choices=[*_SURROGATE],
+                    help="surrogate class (default ensemble = nested-CV best at low N); ridge/rf/ranking/"
+                         "global_epistasis are expert overrides for known regimes (the default needs no "
+                         "manual choice). CV auto-selection was pruned (not shown to beat the fixed default).")
+    rc.add_argument("--beta", type=float, default=1.0, help="UCB exploration weight")
+    rc.add_argument("--generated-cap", dest="generated_cap", type=int, default=200000)
+    rc.add_argument("--scored-cap", dest="scored_cap", type=int, default=20000)
+    rc.add_argument("--plm", default="none", choices=["none", "esmc", "esm2"],
+                    help="PLM front end for stage-2 re-rank (ESM-C is the N=95 lever; needs the SDK)")
+    rc.add_argument("--plm-model", dest="plm_model", default="",
+                    help="PLM model id (e.g. esmc_300m, facebook/esm2_t30_150M_UR50D)")
+    rc.add_argument("--plm-pooling", dest="plm_pooling", default="auto",
+                    choices=["auto", "mean", "site"],
+                    help="PLM embedding pooling: 'mean' (whole-seq), 'site' (design-position "
+                         "residues), or 'auto' (site for esmc_600m, else mean)")
+    rc.add_argument("--wt-fasta", dest="wt_fasta", default=None,
+                    help="full WT background FASTA (required with --plm; design positions splice into it)")
+    rc.add_argument("--plm-cache", dest="plm_cache", default=None,
+                    help="path to a .npz embedding cache (persisted across runs/rounds)")
+    rc.add_argument("--plm-rerank", dest="plm_rerank", type=int, default=256,
+                    help="shortlist size the PLM surrogate re-scores (keep small: CPU PLM is slow)")
+    rc.add_argument("--design-positions", dest="design_positions", default=None,
+                    help="comma-separated absolute 1-based residue positions (default 1..len); needed when variants are a non-contiguous subset")
+    rc.add_argument("--naturalness", default="none", choices=["none", "esmc", "esm2"],
+                    help="zero-shot naturalness warm-start feature in stage-2 rerank (needs --wt-fasta + SDK)")
+    rc.add_argument("--naturalness-cache", dest="naturalness_cache", default=None,
+                    help="path to a .npz naturalness-score cache")
+    rc.add_argument("--auto-gate-pairwise", dest="auto_gate_pairwise", action="store_true",
+                    help="open the explicit-pairwise epistasis block only if k-fold CV shows it helps (data-gate)")
+    rc.add_argument("--contacts-pdb", dest="contacts_pdb", default=None,
+                    help="PDB structure; restrict the pairwise epistasis block to Cbeta contacts "
+                         "among design positions (absolute residue numbers). NOTE: this OPENS the "
+                         "pairwise block unconditionally (no CV gate) unless --auto-gate-pairwise "
+                         "is also given")
+    rc.add_argument("--contact-cutoff", dest="contact_cutoff", type=float, default=8.0,
+                    help="Cbeta-Cbeta contact distance cutoff in Angstrom (default 8.0)")
+    rc.add_argument("--if-logprobs", dest="if_logprobs", default=None,
+                    help="JSON {position: {aa: logprob}} inverse-folding table (e.g. from ProteinMPNN); adds an IF score feature")
+    rc.add_argument("--no-auto-signals", dest="auto_signals", action="store_false",
+                    help="expert override: include provided optional signals (--if-logprobs) UNCONDITIONALLY "
+                         "instead of CV-gating them. Default: the tool held-out-CV-tests each supplied signal "
+                         "and opens it only if it beats the additive baseline on this protein's data (abstains at low N)")
+    rc.set_defaults(auto_signals=True)
+    rc.add_argument("--recombine", action="store_true",
+                    help="add recombinations of MEASURED beneficials (variants that beat WT) to the "
+                         "candidate pool (Arnold-style; the strategy the real-data evidence supports)")
+    rc.add_argument("--recombine-min-gain", dest="recombine_min_gain", type=float, default=0.0,
+                    help="only recombine mutations from variants whose fitness exceeds WT by at least this")
+    rc.set_defaults(func=cmd_recommend)
+
+    ad = sub.add_parser("advise", help="readiness check on measured data: learned enough? open epistasis? proceed?")
+    ad.add_argument("measured", help="CSV with variant,fitness columns (current accumulated data)")
+    ad.add_argument("--design-positions", dest="design_positions", default=None,
+                    help="comma-separated absolute 1-based residue positions (default 1..len)")
+    ad.set_defaults(func=cmd_advise)
+
+    fl = sub.add_parser(
+        "funclib",
+        help="FuncLib-style active-site library: tolerated+stable combinable multipoint mutants "
+             "to MEASURE directly (design-space construction, NOT activity predictions)",
+    )
+    fl.add_argument("wt_fasta", help="full WT background FASTA (defines sequence + reference residues)")
+    fl.add_argument("--outdir", default="outputs/funclib")
+    fl.add_argument("--holo", default=None,
+                    help="HOLO PDB with a ligand pose; design region = active-site shell(s) by contact topology")
+    fl.add_argument("--ligand-resnames", dest="ligand_resnames", default=None,
+                    help="comma-separated HETATM resnames to treat as the ligand (else auto; additives blocklisted)")
+    fl.add_argument("--shell", default="2", choices=["1", "2", "both"],
+                    help="active-site shell to design over (default 2 = tunable ring; 1 = catalytic core, usually lethal to saturate)")
+    fl.add_argument("--contact-cutoff", dest="contact_cutoff", type=float, default=4.5,
+                    help="ligand/residue heavy-atom contact cutoff in Angstrom for shells (default 4.5)")
+    fl.add_argument("--positions", default=None,
+                    help="explicit comma-separated absolute 1-based positions (overrides --holo)")
+    fl.add_argument("--ddg", default=None,
+                    help="ddG table (JSON {position:{aa:ddG}} or CSV/TSV with position+aa+ddG or mutation token); stability gate")
+    fl.add_argument("--tolerance", default=None,
+                    help="JSON tolerance: {token: score} (MSA PSSM / PLM zero-shot) or {position: {aa: logp}} (auto-detected)")
+    fl.add_argument("--if-logprobs", dest="if_logprobs", default=None,
+                    help="JSON inverse-folding {position: {aa: logp}} used as the tolerance signal (log-odds vs WT)")
+    fl.add_argument("--msa", default=None,
+                    help="a3m MSA file; Henikoff-weighted PSSM log-odds as the tolerance signal "
+                         "(evolutionary conservation; GPU-free alternative to PLM, comparable to "
+                         "ESM across 217 ProteinGym DMS, not a proven improvement)")
+    fl.add_argument("--ddg-cutoff", dest="ddg_cutoff", type=float, default=2.5,
+                    help="keep mutations with folding ddG <= this (kcal/mol; default 2.5)")
+    fl.add_argument("--tolerance-cutoff", dest="tolerance_cutoff", type=float, default=0.0,
+                    help="keep mutations with tolerance score >= this (default 0.0)")
+    fl.add_argument("--per-position-cap", dest="per_position_cap", type=int, default=4,
+                    help="keep at most this many tolerated+stable AAs per position (default 4)")
+    fl.add_argument("--min-mut", dest="min_mut", type=int, default=1)
+    fl.add_argument("--max-mut", dest="max_mut", type=int, default=4,
+                    help="max mutated positions per combo (FuncLib designs carry ~3-6; default 4)")
+    fl.add_argument("--additive-ddg-budget", dest="additive_ddg_budget", type=float, default=None,
+                    help="drop combos whose summed single-mutation ddG exceeds this (additive destabilization proxy)")
+    fl.add_argument("--max-library", dest="max_library", type=int, default=2000,
+                    help="keep at most this many combos in the final library (default 2000)")
+    fl.add_argument("--allow-unscored", dest="allow_unscored", action="store_true",
+                    help="treat mutations missing from the ddG table as passing the stability gate (ddG=0)")
+    fl.set_defaults(func=cmd_funclib)
+
+    cp = sub.add_parser(
+        "campaign",
+        help="funclib R0 seed -> active-learning rounds (the validated handoff); "
+             "--simulate to reproduce/validate against a measured landscape",
+    )
+    cp.add_argument("wt_fasta", help="full WT background FASTA (defines sequence + reference residues)")
+    cp.add_argument("--outdir", default="outputs/campaign")
+    cp.add_argument("--simulate", default=None,
+                    help="variant,fitness landscape CSV: reproduce the funclib->AL handoff against it "
+                         "(design --positions must match the landscape's per-position combo encoding)")
+    cp.add_argument("--measured", nargs="*", default=None,
+                    help="live mode: accumulated variant,fitness CSV(s). None -> emit the funclib R0 seed plate")
+    cp.add_argument("--strategies", nargs="+", default=["funclib", "random"],
+                    choices=["funclib", "singles", "random"],
+                    help="simulate arms to compare (default funclib vs random)")
+    cp.add_argument("--plate", type=int, default=95, help="variants measured per round (default 95)")
+    cp.add_argument("--rounds", type=int, default=3, help="active-learning rounds after the seed (default 3)")
+    cp.add_argument("--seeds", type=int, default=20, help="RNG seeds per strategy in --simulate (default 20)")
+    cp.add_argument("--jobs", type=int, default=1,
+                    help="parallel processes for --simulate seeds (default 1 = serial; >1 = byte-identical, "
+                         "for batch evidence/bench runs). Threads do not help (GIL-bound loop body)")
+    cp.add_argument("--beta", type=float, default=0.0,
+                    help="acquisition: 0 = greedy exploitation (D25 default), >0 = UCB exploration weight")
+    cp.add_argument("--model-class", dest="model_class", default="ensemble", choices=[*_SURROGATE],
+                    help="surrogate class for the AL rounds (default ensemble)")
+    # design region + seed signals (shared with funclib)
+    cp.add_argument("--positions", default=None,
+                    help="explicit comma-separated 1-based positions (required for --simulate to match the landscape)")
+    cp.add_argument("--holo", default=None, help="HOLO PDB with a ligand pose; design region = active-site shell(s)")
+    cp.add_argument("--ligand-resnames", dest="ligand_resnames", default=None,
+                    help="comma-separated HETATM resnames for the ligand (else auto)")
+    cp.add_argument("--shell", default="2", choices=["1", "2", "both"], help="active-site shell to design over")
+    cp.add_argument("--contact-cutoff", dest="contact_cutoff", type=float, default=4.5,
+                    help="ligand/residue heavy-atom contact cutoff for shells (Angstrom)")
+    cp.add_argument("--ddg", default=None, help="ddG table (stability gate for the funclib seed)")
+    cp.add_argument("--tolerance", default=None, help="JSON tolerance ({token:score} or {pos:{aa:logp}})")
+    cp.add_argument("--if-logprobs", dest="if_logprobs", default=None,
+                    help="JSON inverse-folding {position:{aa:logp}} (tolerance signal + AL IF feature). "
+                         "NOTE: on `campaign` the AL IF feature is added UNCONDITIONALLY, with no CV "
+                         "gate -- unlike `recommend`, which held-out-CV-tests it first")
+    cp.add_argument("--msa", default=None, help="a3m MSA file; PSSM log-odds tolerance signal for the seed")
+    cp.add_argument("--auto-msa", dest="auto_msa", action="store_true",
+                    help="if --msa is not given, build the seed MSA from the WT sequence via the "
+                         "ColabFold MMseqs2 API (GPU-free; network). Abstains gracefully if unreachable")
+    cp.add_argument("--ddg-cutoff", dest="ddg_cutoff", type=float, default=2.5)
+    cp.add_argument("--tolerance-cutoff", dest="tolerance_cutoff", type=float, default=0.0)
+    cp.add_argument("--per-position-cap", dest="per_position_cap", type=int, default=4)
+    cp.add_argument("--min-mut", dest="min_mut", type=int, default=1)
+    cp.add_argument("--max-mut", dest="max_mut", type=int, default=4)
+    cp.add_argument("--additive-ddg-budget", dest="additive_ddg_budget", type=float, default=None)
+    cp.add_argument("--allow-unscored", dest="allow_unscored", action="store_true")
+    cp.add_argument("--stability-constraint", dest="stability_constraint", action="store_true",
+                    help="simulate: restrict the AL universe to variants passing the --ddg stability gate "
+                         "throughout (predicted-stability constraint + measured-activity objective = the "
+                         "honest multi-objective decomposition); reports if the activity winner survives")
+    cp.add_argument("--generated-cap", dest="generated_cap", type=int, default=200000)
+    cp.add_argument("--scored-cap", dest="scored_cap", type=int, default=20000)
+    cp.add_argument("--wt-fitness", dest="wt_fitness", type=float, default=None,
+                    help="known (normalised) WT activity, e.g. 1.0 under WT-normalisation. WT is not "
+                         "on the plate; this anchors the 'beats WT' baseline exactly instead of "
+                         "predicting it. Injected as the WT combo in the measured set")
+    _add_plm_args(cp)
+    cp.set_defaults(func=cmd_campaign)
+
+    rs = sub.add_parser(
+        "resolve-site",
+        help="resolve active-site/binding positions from UniProt experimental annotation "
+             "(alignment-mapped to your WT numbering); abstains when no curated evidence maps",
+    )
+    rs.add_argument("wt_fasta", help="WT FASTA whose numbering the resolved positions are mapped to")
+    rs.add_argument("--uniprot", default=None,
+                    help="UniProt accession, e.g. Q50L36 (most reliable); or 'auto' to find the "
+                         "accession by EXACT sequence match against UniProt (abstains if no exact match)")
+    rs.add_argument("--query", default=None,
+                    help="UniProt text search, e.g. 'isoprene synthase Populus' (top hit used)")
+    rs.add_argument("--min-coverage", dest="min_coverage", type=float, default=0.6,
+                    help="abstain if WT aligns to less than this fraction of the UniProt sequence (wrong entry guard)")
+    rs.add_argument("--timeout", type=float, default=20.0, help="network timeout seconds")
+    rs.add_argument("--pdb", default=None,
+                    help="force the structure path: an RCSB PDB ID or a LOCAL structure file "
+                         "(cocrystal, or an AlphaFold model with a docked ligand)")
+    rs.add_argument("--find-holo", dest="find_holo", action="store_true",
+                    help="Foldseek-search for a ligand-bound (holo) structural homolog and list candidate "
+                         "PDB ids (with their ligands) to feed back via --pdb; fills the apo/no-ligand gap")
+    rs.add_argument("--exclude-catalytic", dest="exclude_catalytic", action="store_true",
+                    help="when BOTH --pdb and --uniprot are given: design over the PDB shell MINUS the "
+                         "UniProt catalytic core (the tunable 2nd-shell ring), instead of flagging it")
+    rs.add_argument("--no-pdb-fallback", dest="no_pdb_fallback", action="store_true",
+                    help="do not fall back to UniProt-linked PDB cocrystals when features do not map")
+    rs.add_argument("--max-pdb", dest="max_pdb", type=int, default=5,
+                    help="max UniProt-linked PDB cocrystals to try in the fallback")
+    rs.add_argument("--no-alphafold", dest="no_alphafold", action="store_true",
+                    help="do not fetch an AlphaFold model when no experimental evidence is available")
+    rs.add_argument("--apo-pocket", dest="apo_pocket", action="store_true",
+                    help="LOW-confidence: run fpocket on the fetched AlphaFold (apo) model to guess pocket "
+                         "positions. Can miss the catalytic site (it did on ispS); verify. Needs fpocket.")
+    rs.add_argument("--fpocket", default="fpocket", help="fpocket binary path (for --apo-pocket)")
+    rs.add_argument("--ligand-resnames", dest="ligand_resnames", default=None,
+                    help="comma-separated HETATM ligand resnames for shell detection (else auto)")
+    rs.add_argument("--contact-cutoff", dest="contact_cutoff", type=float, default=4.5,
+                    help="ligand/residue heavy-atom contact cutoff (Angstrom) for PDB shells")
+    rs.add_argument("--outdir", default="outputs/resolve_site")
+    rs.set_defaults(func=cmd_resolve_site)
+
+    rd = sub.add_parser(
+        "round",
+        help="one command per round: auto-resolve active-site positions then emit the next plate "
+             "(no --measured -> R0 funclib seed; --measured -> Rk AL plate). The wet-lab front door.",
+    )
+    rd.add_argument("wt_fasta", help="full WT background FASTA")
+    rd.add_argument("--measured", nargs="*", default=None,
+                    help="accumulated variant,fitness CSV(s); omit for the R0 seed plate, add each "
+                         "round's measured results to advance (R1, R2, ...)")
+    rd.add_argument("--outdir", default="outputs/round")
+    # design region: pick one (the auto ladder is the easy path)
+    rd.add_argument("--uniprot", default=None,
+                    help="UniProt accession (e.g. Q50L36) -> auto active-site positions; or 'auto' "
+                         "to match the accession from the WT sequence exactly (abstains if none)")
+    rd.add_argument("--query", default=None, help="UniProt text search (top hit); auto active-site positions")
+    rd.add_argument("--pdb", default=None, help="RCSB PDB ID or local holo structure; active-site shell (aligned to WT)")
+    rd.add_argument("--find-holo", dest="find_holo", action="store_true",
+                    help="no cocrystal? Foldseek-find a ligand-bound (holo) homolog of the WT (via its "
+                         "AlphaFold model or --pdb) and use it as the design region automatically")
+    rd.add_argument("--exclude-catalytic", dest="exclude_catalytic", action="store_true",
+                    help="with both --pdb and --uniprot: design the tunable ring (PDB shell minus the "
+                         "UniProt catalytic core) instead of the full shell")
+    rd.add_argument("--holo", default=None, help="local HOLO PDB with a ligand pose; active-site shell by contact")
+    rd.add_argument("--positions", default=None, help="explicit comma-separated 1-based positions (skips auto-resolve)")
+    # seed signals (optional but recommended for a strong R0)
+    rd.add_argument("--msa", default=None, help="a3m MSA; PSSM tolerance signal for the funclib seed (GPU-free)")
+    rd.add_argument("--auto-msa", dest="auto_msa", action="store_true",
+                    help="build the R0 seed MSA from the WT sequence via ColabFold MMseqs2 when no "
+                         "--msa is given (GPU-free; network) -- lets R0 run from just WT + region")
+    rd.add_argument("--ddg", default=None, help="folding ddG table; stability gate for the seed")
+    rd.add_argument("--if-logprobs", dest="if_logprobs", default=None,
+                    help="inverse-folding {pos:{aa:logp}}; tolerance signal for the seed + AL IF feature. "
+                         "NOTE: `round` runs the campaign round, which adds the AL IF feature "
+                         "UNCONDITIONALLY, with no CV gate -- unlike `recommend`")
+    rd.add_argument("--tolerance", default=None, help="explicit tolerance JSON (alternative to --msa/--if-logprobs)")
+    rd.add_argument("--ligand-resnames", dest="ligand_resnames", default=None,
+                    help="HETATM ligand resnames for shell detection (else auto)")
+    # plate + model knobs (validated defaults; usually leave alone)
+    rd.add_argument("--plate", type=int, default=95, help="variants per plate (default 95)")
+    rd.add_argument("--max-mut", dest="max_mut", type=int, default=4, help="max mutated positions per combo")
+    rd.add_argument("--beta", type=float, default=0.0, help="acquisition: 0 greedy (default), >0 UCB weight")
+    rd.add_argument("--model-class", dest="model_class", default="ensemble", choices=[*_SURROGATE],
+                    help="AL surrogate class (default ensemble)")
+    rd.add_argument("--min-coverage", dest="min_coverage", type=float, default=0.6,
+                    help="abstain if WT aligns to less than this fraction of the reference (wrong-entry guard)")
+    rd.add_argument("--timeout", type=float, default=20.0, help="network timeout seconds (auto-resolve)")
+    rd.add_argument("--wt-fitness", dest="wt_fitness", type=float, default=None,
+                    help="known (normalised) WT activity (e.g. 1.0) to anchor the 'beats WT' baseline "
+                         "exactly; WT stays off the plate")
+    _add_plm_args(rd)
+    rd.set_defaults(
+        func=cmd_round,
+        simulate=None, strategies=["funclib", "random"], stability_constraint=False,
+        seeds=20, jobs=1, rounds=3, generated_cap=200000, scored_cap=20000,
+        ddg_cutoff=2.5, tolerance_cutoff=0.0, per_position_cap=4, min_mut=1,
+        additive_ddg_budget=None, allow_unscored=False, shell="2", contact_cutoff=4.5,
+        max_pdb=5, no_pdb_fallback=False, no_alphafold=False, apo_pocket=False, fpocket="fpocket",
+        exclude_catalytic=False,
+    )
+    b = sub.add_parser("bench", help="synthetic alpha-spectrum tool-comparative benchmark")
+    b.add_argument("--outdir", default="outputs/bench")
+    b.add_argument("--n-sites", dest="n_sites", type=int, default=5)
+    b.add_argument("--q", type=int, default=4, help="alphabet size (first q amino acids)")
+    b.add_argument("--alphas", type=float, nargs="+", default=[0.0, 0.5, 1.0, 2.0])
+    b.add_argument("--seeds", type=int, default=20)
+    b.add_argument("--n-init", dest="n_init", type=int, default=95)
+    b.add_argument("--batch-size", dest="batch_size", type=int, default=95)
+    b.add_argument("--n-rounds", dest="n_rounds", type=int, default=3)
+    b.set_defaults(func=cmd_bench)
+
+    r = sub.add_parser("report", help="summarise a bench spectrum or recommend report JSON")
+    r.add_argument("path", help="path to spectrum.json or report.json")
+    r.set_defaults(func=cmd_report)
+    hp = sub.add_parser(
+        "hotspots",
+        help="whole-protein single-mutant SCAN -> top hotspot positions for combinatorial AL "
+             "(the scan->focus bridge; feed the positions to `round`/`campaign`)",
+    )
+    hp.add_argument("scan", help="single-mutant CSV: a mutation column (e.g. V100F) + a score column "
+                                 "(measured fitness/activity, or a predicted y_pred/score)")
+    hp.add_argument("--top-k", dest="top_k", type=int, default=6, help="number of hotspot positions to return")
+    hp.add_argument("--metric", default="max", choices=["max", "mean", "count"],
+                    help="rank positions by best single ('max', default), average ('mean'), or count of "
+                         "beneficials above --baseline ('count')")
+    hp.add_argument("--baseline", type=float, default=0.0, help="score above which a single counts as beneficial")
+    hp.add_argument("--min-effect", dest="min_effect", type=float, default=None,
+                    help="drop positions whose best single scores below this")
+    hp.add_argument("--mutation-col", dest="mutation_col", default=None, help="mutation column name (else auto)")
+    hp.add_argument("--score-col", dest="score_col", default=None, help="score column name (else auto)")
+    hp.add_argument("--outdir", default="outputs/hotspots")
+    hp.set_defaults(func=cmd_hotspots)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return int(args.func(args))
+
+
+if __name__ == "__main__":
+    sys.exit(main())