shellde 0.2.0__py3-none-any.whl

shellde/holo.py

@@ -0,0 +1,175 @@
+"""Find a ligand-bound (holo) structural homolog when the target is apo.
+
+ShellDE's resolve-site needs a ligand pose to define the active-site shell; it abstains on apo
+structures. This module fills that gap: submit a query structure to the public Foldseek search server
+(same ticket-based API family as the ColabFold MMseqs2 MSA API already used here), take the PDB hits,
+and keep the ones that actually have a bound ligand (RCSB check). It returns candidate holo PDB ids for
+the user to feed to ``resolve-site --pdb <id>`` (the existing shell machinery aligns it onto WT).
+
+Network + polling; every failure returns an empty list so callers ABSTAIN, never fabricate. Advisory
+only: it proposes candidates, it does not auto-superpose. stdlib urllib (no requests dependency).
+"""
+from __future__ import annotations
+
+import json
+import io
+import re
+import tarfile
+import time
+import urllib.request
+import uuid
+
+from shellde.structure import _NON_LIGAND
+
+_UA = {"User-Agent": "shellde (https://pypi.org/project/shellde/)"}
+_PDB_ID = re.compile(r"(?<![A-Za-z0-9])([1-9][A-Za-z0-9]{3})(?![A-Za-z0-9])")
+
+
+def _encode_multipart(fields: list[tuple[str, str]], filename: str, filedata: bytes) -> tuple[bytes, str]:
+    """Build a multipart/form-data body (repeated keys allowed, e.g. ``database[]``) for the ``q`` file."""
+    boundary = "----shelldeFoldseek" + uuid.uuid4().hex
+    crlf = "\r\n"
+    parts = []
+    for key, val in fields:
+        parts.append(
+            f'--{boundary}{crlf}Content-Disposition: form-data; name="{key}"{crlf}{crlf}{val}{crlf}'
+        )
+    parts.append(
+        f'--{boundary}{crlf}Content-Disposition: form-data; name="q"; filename="{filename}"{crlf}'
+        f"Content-Type: application/octet-stream{crlf}{crlf}"
+    )
+    body = "".join(parts).encode() + filedata + f"{crlf}--{boundary}--{crlf}".encode()
+    return body, f"multipart/form-data; boundary={boundary}"
+
+
+def foldseek_search(
+    pdb_text: str,
+    *,
+    host: str = "https://search.foldseek.com/api",
+    databases: tuple[str, ...] = ("pdb100",),
+    mode: str = "3diaa",
+    timeout: float = 30.0,
+    max_wait: float = 600.0,
+    poll: float = 5.0,
+    max_evalue: float = 1e-3,
+    min_coverage: float = 0.5,
+) -> list[dict]:
+    """Foldseek-search a query structure, gate on structural significance, return ranked hits.
+
+    Submits the structure (POST /ticket), polls, downloads the .m8 result, and keeps only hits that are
+    a SIGNIFICANT, well-covering structural match -- E-value <= ``max_evalue`` AND alignment coverage
+    (alnlen/qlen) >= ``min_coverage`` -- so a distant/partial homolog whose ligand pocket may not
+    correspond to the target is NOT returned. Each hit is ``{"pdb_id","evalue","coverage","bits"}``,
+    ranked by bits (best first). [] on any failure or if nothing passes the gate.
+    """
+    data = pdb_text.encode() if isinstance(pdb_text, str) else pdb_text
+    if not data:
+        return []
+    fields = [("mode", mode)] + [("database[]", db) for db in databases]
+    body, ctype = _encode_multipart(fields, "query.pdb", data)
+
+    def _get_json(url: str, payload: bytes | None = None, ctype_hdr: str | None = None) -> dict | None:
+        try:
+            headers = dict(_UA)
+            if ctype_hdr:
+                headers["Content-Type"] = ctype_hdr
+            req = urllib.request.Request(url, data=payload, headers=headers)
+            with urllib.request.urlopen(req, timeout=timeout) as r:  # noqa: S310 (trusted host)
+                return json.loads(r.read().decode())
+        except Exception:  # noqa: BLE001 (network/HTTP/JSON -> abstain)
+            return None
+
+    job = _get_json(f"{host}/ticket", body, ctype)
+    if not job or "id" not in job or job.get("status") in ("ERROR", "MAINTENANCE", None):
+        return []
+    jid, st, waited = job["id"], job.get("status"), 0.0
+    while st in ("PENDING", "RUNNING", "UNKNOWN", "RATELIMIT"):
+        time.sleep(poll)
+        waited += poll
+        if waited > max_wait:
+            return []
+        s = _get_json(f"{host}/ticket/{jid}")
+        st = s.get("status") if s else None
+    if st != "COMPLETE":
+        return []
+
+    try:
+        req = urllib.request.Request(f"{host}/result/download/{jid}", headers=_UA)
+        with urllib.request.urlopen(req, timeout=max(timeout, 120.0)) as r:  # noqa: S310
+            blob = r.read()
+    except Exception:  # noqa: BLE001
+        return []
+
+    rows: dict[str, dict] = {}
+    try:
+        with tarfile.open(fileobj=io.BytesIO(blob), mode="r:gz") as tar:
+            for m in tar.getmembers():
+                if not m.name.endswith(".m8"):
+                    continue
+                fh = tar.extractfile(m)
+                if fh is None:
+                    continue
+                for line in fh.read().decode("utf-8", "ignore").splitlines():
+                    cols = line.split("\t")
+                    if len(cols) < 14:  # need through qlen (col 13)
+                        continue
+                    hit = _PDB_ID.search(cols[1])
+                    if not hit:
+                        continue
+                    try:
+                        alnlen = int(cols[3])
+                        evalue = float(cols[11])
+                        bits = float(cols[12])
+                        qlen = int(cols[13])
+                    except (ValueError, IndexError):
+                        continue
+                    cov = alnlen / qlen if qlen else 0.0
+                    if evalue > max_evalue or cov < min_coverage:  # structural-significance gate
+                        continue
+                    pid = hit.group(1).upper()
+                    rec = {"pdb_id": pid, "evalue": evalue, "coverage": round(cov, 3), "bits": bits}
+                    if pid not in rows or bits > rows[pid]["bits"]:
+                        rows[pid] = rec
+    except Exception:  # noqa: BLE001
+        return []
+    return sorted(rows.values(), key=lambda r: -r["bits"])
+
+
+def rcsb_ligands(pdb_id: str, *, timeout: float = 15.0) -> list[str]:
+    """Bound non-polymer ligand comp-ids for a PDB entry, minus crystallization additives. [] on failure."""
+    try:
+        req = urllib.request.Request(
+            f"https://data.rcsb.org/rest/v1/core/entry/{pdb_id.upper()}", headers=_UA
+        )
+        with urllib.request.urlopen(req, timeout=timeout) as r:  # noqa: S310
+            info = json.loads(r.read().decode())
+    except Exception:  # noqa: BLE001
+        return []
+    comps = info.get("rcsb_entry_info", {}).get("nonpolymer_bound_components") or []
+    return [c for c in comps if c.upper() not in _NON_LIGAND]
+
+
+def find_holo_homolog(
+    pdb_text: str,
+    *,
+    top_n: int = 10,
+    max_candidates: int = 3,
+    timeout: float = 30.0,
+    max_wait: float = 600.0,
+) -> list[dict]:
+    """Advisory: rank ligand-bound (holo) PDB homologs of a query structure.
+
+    Runs :func:`foldseek_search` (pdb100), then keeps the top hits that RCSB reports as having a bound
+    (non-additive) ligand. Returns up to ``max_candidates`` dicts ``{"pdb_id", "ligands", "rank"}`` for
+    the user to pass to ``resolve-site --pdb``. Empty on any failure (ABSTAIN).
+    """
+    hits = foldseek_search(pdb_text, timeout=timeout, max_wait=max_wait)
+    out: list[dict] = []
+    for rank, h in enumerate(hits[:top_n], 1):
+        ligs = rcsb_ligands(h["pdb_id"], timeout=min(timeout, 15.0))
+        if ligs:
+            out.append({"pdb_id": h["pdb_id"], "ligands": ligs, "evalue": h["evalue"],
+                        "coverage": h["coverage"], "rank": rank})
+            if len(out) >= max_candidates:
+                break
+    return out

shellde/hotspots.py

@@ -0,0 +1,108 @@
+"""Bridge (niche C): a whole-protein single-mutant SCAN -> hotspot positions for combinatorial AL.
+
+The scan->focus handoff that neither EVOLVEpro (whole-protein singles + additive stacking) nor
+FuncLib/ALDE (you must already know the positions) provides:
+
+  1. SCAN  -- a whole-protein single-mutant table (measured or PLM-predicted, EVOLVEpro-style,
+              mutation-notation like ``V100F``) ranks how impactful each POSITION is.
+  2. BRIDGE -- pick the top-k hotspot positions here.
+  3. FOCUS -- feed those positions to ``campaign``/``round`` (combinatorial AL: the candidate pool is
+              multi-mutant, the fitted model is additive by default), which MEASURES real
+              combinations instead of assuming additive stacking.
+
+This module is the BRIDGE. It is pure/offline (parsing + per-position aggregation); the scan itself
+(producing the single-mutant scores) and the combinatorial phase live elsewhere.
+
+Honest scope: ranking positions from single-mutant scores is a heuristic to CHOOSE where to look; it
+does not predict the combinatorial winner (that needs the measured combinatorial AL). If the scores
+are predictions (e.g. EVOLVEpro y_pred), the choice inherits that model's ceiling.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+_MUT = re.compile(r"^([A-Za-z])?(\d+)([A-Za-z*])$")
+
+
+@dataclass(frozen=True)
+class Hotspot:
+    """One design position summarised from the single-mutant scan."""
+
+    position: int
+    wt: str
+    best_effect: float           # score of the best single substitution at this position
+    best_sub: str                # e.g. "V100F"
+    n_beneficial: int            # substitutions scoring above the baseline
+    subs: dict[str, float] = field(default_factory=dict)   # aa -> score
+
+
+def parse_mutation(token: str) -> tuple[str, int, str] | None:
+    """``'V100F'`` -> ``('V', 100, 'F')``; ``'100F'``/``'100 F'`` -> ``('', 100, 'F')``.
+
+    The wild-type letter is optional so position+AA scan exports (e.g. ``29I``, common when the WT is
+    implied) parse too; ranking only needs the position and the substituted residue. None if the token
+    is not a single substitution.
+    """
+    m = _MUT.match(token.strip())
+    if not m:
+        return None
+    return (m.group(1) or "").upper(), int(m.group(2)), m.group(3).upper()
+
+
+def rank_hotspots(
+    singles,
+    *,
+    baseline: float = 0.0,
+    top_k: int = 6,
+    metric: str = "max",
+    min_effect: float | None = None,
+) -> list[Hotspot]:
+    """Aggregate single-mutant scores per position and return the top-``top_k`` hotspots.
+
+    ``singles``: iterable of ``(mutation_token, score)`` where higher score == more desirable
+    (activity / predicted benefit). ``metric`` ranks positions by ``'max'`` (best single here, the
+    default), ``'mean'`` (average over its substitutions), or ``'count'`` (number scoring above
+    ``baseline``). ``min_effect`` drops positions whose best single is below it. Pure.
+    """
+    by_pos: dict[int, dict] = {}
+    for token, score in singles:
+        parsed = parse_mutation(token)
+        if parsed is None:
+            continue
+        wt, pos, mut = parsed
+        try:
+            val = float(score)
+        except (TypeError, ValueError):
+            continue
+        slot = by_pos.setdefault(pos, {"wt": wt, "subs": {}})
+        slot["subs"][mut] = val
+
+    hotspots: list[Hotspot] = []
+    for pos, slot in by_pos.items():
+        subs = slot["subs"]
+        if not subs:
+            continue
+        best_aa = max(subs, key=subs.get)
+        hotspots.append(
+            Hotspot(
+                position=pos,
+                wt=slot["wt"],
+                best_effect=subs[best_aa],
+                best_sub=f"{slot['wt']}{pos}{best_aa}",
+                n_beneficial=sum(1 for v in subs.values() if v > baseline),
+                subs=dict(subs),
+            )
+        )
+
+    key = {
+        "max": lambda h: h.best_effect,
+        "mean": lambda h: sum(h.subs.values()) / len(h.subs),
+        "count": lambda h: h.n_beneficial,
+    }
+    if metric not in key:
+        raise ValueError(f"metric must be one of {sorted(key)}, got {metric!r}")
+    hotspots.sort(key=key[metric], reverse=True)
+    if min_effect is not None:
+        hotspots = [h for h in hotspots if h.best_effect >= min_effect]
+    return hotspots[:top_k]

shellde/loop.py

@@ -0,0 +1,161 @@
+"""The active-learning / experimental-design loop: fit -> acquire -> measure -> repeat.
+
+This is the organizing axis of the tool. Each round re-fits a fresh surrogate on ALL
+accumulated measurements, predicts (calibrated mean+std) over the unmeasured pool,
+the pluggable acquisition selects the next batch, the oracle measures it, and the
+data accumulates. The candidate pool is the oracle's enumerable universe, so a
+campaign reports best-found over genuinely measurable variants and identical budget
+across methods is the harness's responsibility.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping, Sequence
+
+import numpy as np
+
+
+from shellde.design_space import DesignSpace
+from shellde.features.matrix import FeatureMatrix
+from shellde.protocols import Acquisition, Oracle, Surrogate
+from shellde.types import CampaignResult, RoundLog
+
+
+def _spearman(a: np.ndarray, b: np.ndarray) -> float:
+    """Spearman rank correlation via numpy (avoids a scipy typing dependency here)."""
+    ra = np.argsort(np.argsort(a)).astype(float)
+    rb = np.argsort(np.argsort(b)).astype(float)
+    if np.std(ra) < 1e-12 or np.std(rb) < 1e-12:
+        return 0.0
+    return float(np.corrcoef(ra, rb)[0, 1])
+
+
+def run_campaign(
+    oracle: Oracle,
+    space: DesignSpace,
+    *,
+    make_matrix: Callable[[], FeatureMatrix],
+    regate: Callable[[list[str], np.ndarray], FeatureMatrix] | None = None,
+    make_surrogate: Callable[[], Surrogate],
+    acquisition: Acquisition,
+    n_init: int = 95,
+    batch_size: int = 95,
+    n_rounds: int = 3,
+    seed: int = 0,
+    init_variants: Sequence[str] | None = None,
+    anchors: Mapping[str, float] | None = None,
+) -> CampaignResult:
+    """Run an active-learning campaign against an oracle with an enumerable universe."""
+    universe = oracle.universe
+    if universe is None:
+        raise ValueError("run_campaign requires an oracle exposing an enumerable universe")
+    rng = np.random.default_rng(seed)
+    if init_variants is not None:
+        # Explicit seed plate (e.g. a funclib R0 library): use it as the initial measured set
+        # instead of a random draw. The AL pool below is still the FULL universe, so the loop
+        # explores beyond the seed (never hard-restricted to it). Variants outside the universe
+        # are dropped; if the seed is short, top up with a random draw to keep n_init honest.
+        uni_set = set(universe)
+        init = list(dict.fromkeys(v for v in init_variants if v in uni_set))[:n_init]
+        if len(init) < n_init:
+            extra = [universe[int(i)] for i in rng.permutation(len(universe))
+                     if universe[int(i)] not in set(init)]
+            init.extend(extra[: n_init - len(init)])
+    else:
+        init_idx = rng.choice(len(universe), min(n_init, len(universe)), replace=False)
+        init = [universe[int(i)] for i in init_idx]
+    measured: dict[str, float] = dict(zip(init, (float(x) for x in oracle.evaluate(init)), strict=True))
+
+    static_matrix = make_matrix() if regate is None else None  # fixed blocks unless re-gated
+    # Encode-once: with fixed blocks (no per-round regate) the design matrix never changes, so
+    # encode the whole universe a SINGLE time and index rows by a measured-mask instead of
+    # re-encoding the ~|universe| pool every round. Byte-identical: encode is row-independent, so
+    # universe_enc[i] == static_matrix.encode([universe[i]])[0], and the masked pool keeps universe
+    # order (== the old `[v for v in universe if v not in measured]`).
+    universe_enc = static_matrix.encode(universe) if static_matrix is not None else None
+    idx_of = {v: i for i, v in enumerate(universe)} if static_matrix is not None else {}
+    measured_mask = np.zeros(len(universe), dtype=bool)
+    if static_matrix is not None:
+        for v in measured:
+            measured_mask[idx_of[v]] = True
+    # Anchors are FIT-only free rows; the invariant is they never become pool candidates
+    # (so they cannot be acquired into measured/best/trajectory). This mask is a no-op when
+    # `anchors` is None -- the pool-construction path below is then byte-identical.
+    anchor_keys = set(anchors) if anchors else set()
+    anchor_mask = np.zeros(len(universe), dtype=bool)
+    if anchors and static_matrix is not None:
+        for v in anchor_keys:
+            if v in idx_of:
+                anchor_mask[idx_of[v]] = True
+    trajectory = [max(measured.values())]
+    rounds: list[RoundLog] = []
+    heldout_spearman: list[float] = []
+
+    for r in range(n_rounds):
+        vs = list(measured)
+        if static_matrix is not None:
+            pool_mask = ~measured_mask
+            if anchors:
+                pool_mask = pool_mask & ~anchor_mask
+            pool_idx = np.where(pool_mask)[0]
+            pool = [universe[int(i)] for i in pool_idx]
+        else:
+            pool_idx = None
+            if anchors:
+                pool = [v for v in universe if v not in measured and v not in anchor_keys]
+            else:
+                pool = [v for v in universe if v not in measured]
+        if len(vs) < 2 or not pool:
+            break
+        ys = np.asarray([measured[v] for v in vs], dtype=float)
+        if static_matrix is not None:
+            matrix = static_matrix
+            x_vs = universe_enc[[idx_of[v] for v in vs]]
+            x_pool = universe_enc[pool_idx]
+        else:
+            matrix = regate(vs, ys)
+            assert matrix is not None
+            x_vs = matrix.encode(vs)
+            x_pool = matrix.encode(pool)
+        # Anchor: extra free labeled rows into the FIT ONLY (kept out of `measured`,
+        # the pool mask, and best-found). Budget parity: anchors add on top of the draw.
+        if anchors:
+            extra = [(v, fv) for v, fv in anchors.items() if v not in measured]
+            if extra:
+                ev = [v for v, _ in extra]
+                x_extra = static_matrix.encode(ev) if static_matrix is not None else matrix.encode(ev)
+                x_vs = np.vstack([x_vs, x_extra])
+                ys = np.concatenate([ys, np.asarray([fv for _, fv in extra], dtype=float)])
+        sur = make_surrogate().fit(x_vs, ys)
+        pred = sur.predict(x_pool)
+        k = min(batch_size, len(pool))
+        sel = acquisition.select(pred, k, candidates=pool, space=space)
+        batch = [pool[i] for i in sel]
+        pred_batch = np.asarray(pred.mean, dtype=float)[sel]
+        batch_y = np.asarray(oracle.evaluate(batch), dtype=float)
+        for v, fv in zip(batch, batch_y, strict=True):
+            measured[v] = float(fv)
+            if static_matrix is not None:
+                measured_mask[idx_of[v]] = True
+        ho_rmse = float(np.sqrt(np.mean((pred_batch - batch_y) ** 2))) if batch_y.size else None
+        ho_rho: float | None = None
+        if batch_y.size >= 3 and float(np.std(batch_y)) > 1e-12 and float(np.std(pred_batch)) > 1e-12:
+            ho_rho = _spearman(pred_batch, batch_y)
+            heldout_spearman.append(ho_rho)
+        best = max(measured.values())
+        trajectory.append(best)
+        rounds.append(RoundLog(
+            round_index=r, n_measured=len(measured), best_fitness=best, batch=batch,
+            heldout_rmse=ho_rmse, heldout_spearman=ho_rho,
+            notes={"active_blocks": matrix.active_blocks()},
+        ))
+
+    best_v = max(measured, key=lambda kk: measured[kk])
+    return CampaignResult(
+        trajectory=trajectory,
+        measured=measured,
+        best_variant=best_v,
+        best_fitness=measured[best_v],
+        n_rounds=len(rounds),
+        rounds=rounds,
+        heldout_spearman=heldout_spearman,
+    )

shellde/msa.py

@@ -0,0 +1,186 @@
+"""MSA-derived evolutionary tolerance: Henikoff-weighted PSSM log-probabilities.
+
+A per-position amino-acid log-probability table built from a multiple sequence alignment (a3m),
+usable as a funclib tolerance signal exactly like an inverse-folding or ddG table. This is the
+classic evolutionary-conservation signal (the "independent" MSA model that funclib's design names
+as a canonical tolerance). On a small 4-protein gate test it matched/beat ESM-2, BUT on the
+217-DMS ProteinGym benchmark MSA and ESM are statistically INDISTINGUISHABLE (per-DMS paired, ns
+on both Spearman and top-recall). So this is a GPU-free MSA ALTERNATIVE to PLM tolerance, NOT a
+proven improvement; the 4-protein advantage (esp. GB1's shallow-MSA anti-enrichment) did not
+generalize. See ``scripts/proteingym_revalidate.py`` and decision log D11/D13.
+
+Honest scope: this is the independent (per-site) conservation model, not the epistasis-aware
+GEMME / EVmutation (Potts) signal. Same recall ceiling as all tolerance signals (it predicts
+"tolerated/functional", not "improved").
+
+Dependency-light: numpy + stdlib. Produce the a3m once with any MSA tool (jackhmmer, hhblits, or
+the ColabFold MMseqs2 API); this module turns it into the log-prob table.
+"""
+from __future__ import annotations
+
+import io
+import json
+import tarfile
+import time
+import urllib.parse
+import urllib.request
+
+from pathlib import Path
+
+import numpy as np
+
+AA20 = "ACDEFGHIKLMNPQRSTVWY"
+
+
+def read_a3m(path: str | Path) -> list[str]:
+    """Parse an a3m into match-state-only aligned rows (all of equal length = query length).
+
+    a3m insertion columns are lowercase; dropping every lowercase character collapses each record
+    to the query's match columns, so all returned rows share the query length. The first record is
+    the query.
+    """
+    seqs: list[str] = []
+    cur: str | None = None
+    for line in Path(path).read_text().splitlines():
+        if line.startswith(">"):
+            if cur is not None:
+                seqs.append(cur)
+            cur = ""
+        elif cur is not None:
+            cur += line.strip()
+    if cur:
+        seqs.append(cur)
+    aligned = ["".join(c for c in s if not c.islower()) for s in seqs]
+    if not aligned:
+        raise ValueError(f"{path}: no sequences parsed from a3m")
+    length = len(aligned[0])
+    return [a for a in aligned if len(a) == length]
+
+
+def _henikoff_weights(matrix: np.ndarray) -> np.ndarray:
+    """Henikoff position-based sequence weights over an (N, L) residue-char matrix.
+
+    Each column contributes 1/(r_j * count_{j,a}) to the weight of a sequence with residue a in
+    column j, where r_j is the number of distinct amino acids in column j (gaps ignored). Down-
+    weights redundant sequences without the O(N^2) cost of identity clustering.
+    """
+    n, length = matrix.shape
+    aaset = set(AA20)
+    w = np.zeros(n, dtype=float)
+    for j in range(length):
+        col = matrix[:, j]
+        uniq, counts = np.unique(col, return_counts=True)
+        cmap = {u: c for u, c in zip(uniq, counts)}
+        r = sum(1 for u in uniq if u in aaset)
+        if r == 0:
+            continue
+        for i in range(n):
+            a = col[i]
+            if a in aaset:
+                w[i] += 1.0 / (r * cmap[a])
+    total = float(w.sum())
+    return w / total if total > 0 else np.full(n, 1.0 / n)
+
+
+def load_msa_logprobs(
+    path: str | Path, *, pseudocount: float | None = None, reweight: bool = True
+) -> dict[int, dict[str, float]]:
+    """Henikoff-weighted PSSM as a {position: {aa: log_probability}} table from an a3m.
+
+    Positions are 1-based query (first-record) columns. Frequencies use a uniform pseudocount
+    (default ``1/20``) so unobserved residues get a finite log-prob. With ``reweight`` (default),
+    sequences are Henikoff-weighted to reduce alignment redundancy bias; set ``reweight=False`` for
+    raw counts. Feed the result to ``funclib.design_library`` / ``funclib.tolerance_from_logprob_table``
+    as a tolerance signal (top-K is invariant to the WT baseline, so it gates on conservation rank).
+    """
+    rows = read_a3m(path)
+    matrix = np.array([list(r) for r in rows])
+    n, length = matrix.shape
+    pc = (1.0 / len(AA20)) if pseudocount is None else float(pseudocount)
+    w = _henikoff_weights(matrix) if reweight else np.full(n, 1.0 / max(n, 1))
+    aaidx = {a: i for i, a in enumerate(AA20)}
+    out: dict[int, dict[str, float]] = {}
+    for j in range(length):
+        f = np.zeros(len(AA20), dtype=float)
+        col = matrix[:, j]
+        for i in range(n):
+            a = col[i]
+            if a in aaidx:
+                f[aaidx[a]] += w[i]
+        f = (f + pc) / (f.sum() + pc * len(AA20))
+        lp = np.log(f)
+        out[j + 1] = {a: float(lp[aaidx[a]]) for a in AA20}
+    return out
+
+
+_MMSEQS_UA = {"User-Agent": "shellde (https://pypi.org/project/shellde/)"}
+
+
+def build_msa_mmseqs2(
+    seq: str,
+    *,
+    host: str = "https://api.colabfold.com",
+    timeout: float = 30.0,
+    max_wait: float = 600.0,
+    poll: float = 5.0,
+) -> str | None:
+    """Build an a3m MSA for a single sequence via the public ColabFold MMseqs2 API (no local DBs).
+
+    Submit -> poll -> download the result tar.gz, then concatenate its a3m members. Returns the a3m
+    text, or None on any error/timeout so callers ABSTAIN (never fabricate an alignment). This removes
+    the "R0 needs a tolerance signal" friction; it is a GPU-free evolutionary signal, NOT a proven
+    accuracy improvement (see module docstring). Network + polling. Fair-use: one job at a time
+    (https://colabfold.mmseqs.com).
+    """
+    clean = "".join(seq.split()).upper()
+    if not clean:
+        return None
+
+    def _call(url: str, data: bytes | None) -> dict | None:
+        try:
+            req = urllib.request.Request(url, data=data, headers=_MMSEQS_UA)
+            with urllib.request.urlopen(req, timeout=timeout) as r:  # noqa: S310 (trusted host)
+                return json.loads(r.read().decode())
+        except Exception:  # noqa: BLE001 (network/HTTP/JSON -> abstain)
+            return None
+
+    body = urllib.parse.urlencode({"q": f">101\n{clean}\n", "mode": "env"}).encode()
+    job = _call(f"{host}/ticket/msa", body)
+    tries = 0
+    while job and job.get("status") in ("UNKNOWN", "RATELIMIT") and tries < 5:
+        time.sleep(max(poll, 8.0))
+        job = _call(f"{host}/ticket/msa", body)
+        tries += 1
+    if not job or "id" not in job or job.get("status") in ("ERROR", "MAINTENANCE", None):
+        return None
+
+    jid, st, waited = job["id"], job.get("status"), 0.0
+    while st in ("PENDING", "RUNNING", "UNKNOWN"):
+        time.sleep(poll)
+        waited += poll
+        if waited > max_wait:
+            return None
+        s = _call(f"{host}/ticket/{jid}", None)
+        st = s.get("status") if s else None
+    if st != "COMPLETE":
+        return None
+
+    try:
+        req = urllib.request.Request(f"{host}/result/download/{jid}", headers=_MMSEQS_UA)
+        with urllib.request.urlopen(req, timeout=max(timeout, 120.0)) as r:  # noqa: S310
+            blob = r.read()
+    except Exception:  # noqa: BLE001
+        return None
+
+    parts: list[str] = []
+    try:
+        with tarfile.open(fileobj=io.BytesIO(blob), mode="r:gz") as tar:
+            for m in tar.getmembers():
+                if m.name.endswith(".a3m"):
+                    fh = tar.extractfile(m)
+                    if fh is not None:
+                        parts.append(fh.read().decode("utf-8", "ignore"))
+    except Exception:  # noqa: BLE001
+        return None
+    a3m = "\n".join(p.strip() for p in parts if p.strip()).strip()
+    return a3m or None