shellde 0.2.0__py3-none-any.whl

shellde/report.py

@@ -0,0 +1,132 @@
+"""Write a ranking to JSON / CSV / markdown / SVG (em-dash-free, dependency-light).
+
+The markdown and CSV surface the calibrated risk flag so an experimentalist can see,
+per recommendation, whether the predicted gain is robust to uncertainty (confident)
+or speculative (high-risk / high-reward). SVG is a hand-written bar of the global
+top-N by acquisition (no matplotlib dependency).
+"""
+from __future__ import annotations
+
+import csv
+import json
+from pathlib import Path
+
+from shellde.rank import RankingResult
+from shellde.types import Candidate
+
+_EM_DASH = "\u2014"
+
+
+def _entry_dict(c: Candidate) -> dict:
+    return {
+        "variant": c.variant,
+        "n_mut": c.n_mut,
+        "mu": c.mu,
+        "sigma": c.sigma,
+        "acq": c.acq,
+        "mutations": list(c.mutations),
+        "baseline_gain": c.evidence.get("baseline_gain"),
+        "risk": c.evidence.get("risk"),
+        "abstain": c.evidence.get("abstain"),
+        "conformal_lo": c.evidence.get("conformal_lo"),
+        "conformal_scope": c.evidence.get("conformal_scope"),
+    }
+
+
+def _json(ranking: RankingResult, prereg_hash: str | None) -> str:
+    payload = {
+        "prereg_hash": prereg_hash,
+        "global_is_exploratory": ranking.global_is_exploratory,
+        "per_count": {str(k): [_entry_dict(c) for c in v] for k, v in ranking.per_count.items()},
+        "global_ranking": [_entry_dict(c) for c in ranking.global_ranking],
+    }
+    return json.dumps(payload, indent=2)
+
+
+def _abstain_cell(c: Candidate) -> str:
+    """Render the abstain flag for tabular output; '' when the conformal gate is off."""
+    a = c.evidence.get("abstain")
+    return "" if a is None else str(bool(a))
+
+
+def _csv_rows(ranking: RankingResult) -> list[list]:
+    rows: list[list[object]] = [["rank", "n_mut", "variant", "mutations", "mu", "sigma", "acq", "baseline_gain", "risk", "abstain"]]
+    for i, c in enumerate(ranking.global_ranking, start=1):
+        rows.append(
+            [i, c.n_mut, c.variant, " ".join(c.mutations), f"{c.mu:.4f}", f"{c.sigma:.4f}",
+             f"{c.acq:.4f}", f"{c.evidence.get('baseline_gain', 0.0):.4f}", c.evidence.get("risk", ""),
+             _abstain_cell(c)]
+        )
+    return rows
+
+
+def _md(ranking: RankingResult, prereg_hash: str | None) -> str:
+    lines = ["# Mutation candidate ranking", ""]
+    if prereg_hash:
+        lines += [f"prereg hash: `{prereg_hash}`", ""]
+    for count, tier in ranking.per_count.items():
+        lines += [f"## {count}-mutation tier", ""]
+        lines += ["| rank | variant | mutations | mu | sigma | acq | gain | risk |",
+                  "|--:|:--|:--|--:|--:|--:|--:|:--|"]
+        for i, c in enumerate(tier, start=1):
+            muts = ",".join(c.mutations) or "WT"
+            lines.append(
+                f"| {i} | {c.variant} | {muts} | {c.mu:.3f} | {c.sigma:.3f} | {c.acq:.3f} | "
+                f"{c.evidence.get('baseline_gain', 0.0):+.3f} | {c.evidence.get('risk', '')} |"
+            )
+        lines.append("")
+    lines += ["## global ranking (exploratory: mixes mutation counts)", ""]
+    lines += ["| rank | count | variant | mu | sigma | acq | risk | abstain |",
+              "|--:|--:|:--|--:|--:|--:|:--|:--|"]
+    for i, c in enumerate(ranking.global_ranking, start=1):
+        lines.append(
+            f"| {i} | {c.n_mut} | {c.variant} | {c.mu:.3f} | {c.sigma:.3f} | {c.acq:.3f} | "
+            f"{c.evidence.get('risk', '')} | {_abstain_cell(c)} |"
+        )
+    lines.append("")
+    text = "\n".join(lines)
+    if _EM_DASH in text:  # repo convention: generated markdown must be em-dash-free
+        raise ValueError("generated markdown contains an em-dash")
+    return text
+
+
+def _svg(ranking: RankingResult) -> str:
+    top = ranking.global_ranking[:15]
+    if not top:
+        return '<svg xmlns="http://www.w3.org/2000/svg" width="10" height="10"></svg>'
+    acqs = [c.acq for c in top]
+    lo, hi = min(acqs), max(acqs)
+    span = (hi - lo) or 1.0
+    row_h, bar_w, pad = 18, 240, 140
+    h = row_h * len(top) + 10
+    parts = [f'<svg xmlns="http://www.w3.org/2000/svg" width="{pad + bar_w + 60}" height="{h}" font-family="monospace" font-size="11">']
+    for i, c in enumerate(top):
+        y = 8 + i * row_h
+        w = int(bar_w * (c.acq - lo) / span) + 1
+        colour = "#1f4e79" if c.evidence.get("risk") == "confident" else "#a8c4e0"
+        parts.append(f'<text x="2" y="{y + 10}">{c.variant}</text>')
+        parts.append(f'<rect x="{pad}" y="{y}" width="{w}" height="12" fill="{colour}"/>')
+        parts.append(f'<text x="{pad + w + 4}" y="{y + 10}">{c.acq:.2f}</text>')
+    parts.append("</svg>")
+    return "\n".join(parts)
+
+
+def write_report(ranking: RankingResult, outdir: str | Path, *, prereg_hash: str | None = None) -> dict[str, str]:
+    """Write report.json / report.csv / report.md / report.svg; return {kind: path}."""
+    out = Path(outdir)
+    out.mkdir(parents=True, exist_ok=True)
+    paths: dict[str, str] = {}
+
+    (out / "report.json").write_text(_json(ranking, prereg_hash))
+    paths["json"] = str(out / "report.json")
+
+    with (out / "report.csv").open("w", newline="") as fh:
+        csv.writer(fh).writerows(_csv_rows(ranking))
+    paths["csv"] = str(out / "report.csv")
+
+    (out / "report.md").write_text(_md(ranking, prereg_hash))
+    paths["markdown"] = str(out / "report.md")
+
+    (out / "report.svg").write_text(_svg(ranking))
+    paths["svg"] = str(out / "report.svg")
+    return paths

shellde/selector.py

@@ -0,0 +1,63 @@
+"""Method-level selector: let each protein's own held-out data choose the surrogate.
+
+No-Free-Lunch means no single surrogate is best for every landscape. Rather than hardcode
+one, run k-fold CV (held-out Spearman) over the candidate surrogates on the measured data
+and pick the best. This is the general, adaptive core: the data selects the method. It is
+approximately-dominant (tracks the best single surrogate), not strictly; at very low N or
+flat signal it returns the first candidate and the caller should lean on abstain.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+
+import numpy as np
+from sklearn.model_selection import KFold
+
+from shellde.protocols import Surrogate
+
+
+def _spearman(a: np.ndarray, b: np.ndarray) -> float:
+    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
+    r = float(np.corrcoef(ra, rb)[0, 1])
+    return r if np.isfinite(r) else 0.0
+
+
+def cv_spearman(
+    make_surrogate: Callable[[], Surrogate], x: np.ndarray, y: np.ndarray, *, k: int = 4, seed: int = 0
+) -> float:
+    """k-fold held-out Spearman for one surrogate factory on (x, y)."""
+    x = np.asarray(x, dtype=float)
+    y = np.asarray(y, dtype=float).ravel()
+    n = len(y)
+    if n < 8 or np.std(y) < 1e-9:
+        return 0.0
+    pred = np.zeros(n)
+    for tr, va in KFold(n_splits=min(k, n), shuffle=True, random_state=seed).split(x):
+        if np.std(y[tr]) < 1e-9:
+            continue
+        m = make_surrogate().fit(x[tr], y[tr])
+        pred[va] = np.asarray(m.predict(x[va]).mean, dtype=float)
+    return _spearman(pred, y)
+
+
+def select_surrogate(
+    candidates: Mapping[str, Callable[[], Surrogate]],
+    x: np.ndarray,
+    y: np.ndarray,
+    *,
+    k: int = 4,
+    seed: int = 0,
+) -> tuple[str, dict[str, float]]:
+    """Return (best surrogate name, per-candidate CV Spearman). Deterministic; ties -> first.
+
+    At N too small for CV (all scores 0.0) the first candidate wins by max() stability; the
+    caller should treat that as low-confidence (abstain regime).
+    """
+    if not candidates:
+        raise ValueError("no candidate surrogates")
+    scores = {name: cv_spearman(f, x, y, k=k, seed=seed) for name, f in candidates.items()}
+    best = max(candidates, key=lambda n: scores[n])
+    return best, scores

shellde/sitefinder.py

@@ -0,0 +1,465 @@
+"""Resolve active-site / binding positions from EXPERIMENTAL curation first (UniProt), not prediction.
+
+Evidence ladder for "where do I mutate?": curated UniProt features (active/binding/metal site) ->
+[future: linked PDB cocrystal -> AlphaFold + pocket]. The point is to ground the design anchor in
+experimental data when it exists, and abstain (defer to a structure or manual --positions) when it
+does not -- never to fabricate positions.
+
+CRITICAL (the numbering trap): UniProt numbering (often a Precursor with a transit/signal peptide)
+need NOT match the user's construct numbering (e.g. PtIspS 1-560 with an "AA" prefix vs the 558-aa
+mature form -> a +2 offset). So every UniProt feature position is mapped through a sequence
+ALIGNMENT of the user's WT against the UniProt sequence; positions that do not align are reported
+unmapped, never guessed. Residue identity at the mapped position is verified by construction
+(positions come only from exact matching blocks).
+
+Network (urllib, stdlib) is used only by ``fetch_uniprot``; parsing/alignment/mapping are pure and
+unit-tested offline.
+"""
+from __future__ import annotations
+
+import difflib
+import json
+import os
+import tempfile
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass, field
+
+from shellde.structure import shells_from_pdb
+
+_AA3 = {
+    "ALA": "A", "ARG": "R", "ASN": "N", "ASP": "D", "CYS": "C", "GLN": "Q", "GLU": "E",
+    "GLY": "G", "HIS": "H", "ILE": "I", "LEU": "L", "LYS": "K", "MET": "M", "PHE": "F",
+    "PRO": "P", "SER": "S", "THR": "T", "TRP": "W", "TYR": "Y", "VAL": "V",
+}
+
+_SITE_TYPES = ("Active site", "Binding site", "Metal binding", "Site")
+# ECO evidence code -> human confidence (experimental curation outranks by-similarity / predicted)
+_CONFIDENCE = {
+    "ECO:0000269": "experimental",
+    "ECO:0007744": "experimental-combined",
+    "ECO:0000305": "curator-inferred",
+    "ECO:0000250": "by-similarity",
+    "ECO:0000255": "predicted",
+    "ECO:0000256": "predicted",
+}
+_CONF_RANK = {
+    "experimental": 0, "experimental-combined": 1, "curator-inferred": 2,
+    "by-similarity": 3, "predicted": 4, "unknown": 5,
+}
+
+
+@dataclass(frozen=True)
+class Feature:
+    """One UniProt site feature in UNIPROT numbering."""
+
+    type: str
+    start: int
+    end: int
+    ligand: str = ""
+    evidence: str = ""
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class ResolvedSite:
+    """A UniProt site mapped onto the user's WT numbering (one row per WT position)."""
+
+    wt_position: int
+    residue: str
+    source_position: int  # UniProt residue no. (features) or PDB residue no. (structure)
+    types: tuple[str, ...]
+    ligands: tuple[str, ...]
+    confidence: str
+
+
+@dataclass
+class ResolveResult:
+    source: str = ""
+    coverage: float = 0.0
+    sites: list[ResolvedSite] = field(default_factory=list)
+    positions: list[int] = field(default_factory=list)
+    unmapped: list[Feature] = field(default_factory=list)
+    abstained: bool = False
+    reason: str = ""
+    consensus: list[dict] = field(default_factory=list)  # per-position evidence map (build_consensus)
+
+
+def _confidence(eco: str) -> str:
+    return _CONFIDENCE.get(eco, "unknown")
+
+
+def parse_uniprot_entry(data: dict) -> tuple[str, str, list[Feature]]:
+    """(sequence, accession, site features) from a UniProt entry JSON. Pure."""
+    seq = (data.get("sequence") or {}).get("value", "") or ""
+    acc = data.get("primaryAccession", "") or ""
+    feats: list[Feature] = []
+    for f in data.get("features", []) or []:
+        t = f.get("type")
+        if t not in _SITE_TYPES:
+            continue
+        loc = f.get("location") or {}
+        s = (loc.get("start") or {}).get("value")
+        e = (loc.get("end") or {}).get("value")
+        if s is None:
+            continue
+        ev = ((f.get("evidences") or [{}])[0]).get("evidenceCode", "")
+        lig = (f.get("ligand") or {}).get("name", "")
+        feats.append(Feature(type=t, start=int(s), end=int(e if e is not None else s),
+                             ligand=lig, evidence=ev, description=f.get("description", "")))
+    return seq, acc, feats
+
+
+def _alignment_map(wt: str, up: str) -> tuple[dict[int, int], float]:
+    """Map UniProt 0-based index -> WT 0-based index over exact matching blocks; + WT coverage."""
+    sm = difflib.SequenceMatcher(a=wt, b=up, autojunk=False)
+    m: dict[int, int] = {}
+    matched = 0
+    for a0, b0, size in sm.get_matching_blocks():
+        for k in range(size):
+            m[b0 + k] = a0 + k
+        matched += size
+    coverage = matched / len(wt) if wt else 0.0
+    return m, coverage
+
+
+def resolve_from_entry(wt_seq: str, data: dict, *, min_coverage: float = 0.6) -> ResolveResult:
+    """Map a UniProt entry's site features onto ``wt_seq`` numbering. Pure (no network)."""
+    up_seq, acc, feats = parse_uniprot_entry(data)
+    res = ResolveResult(source=f"UniProt:{acc}" if acc else "UniProt")
+    if not up_seq:
+        res.abstained = True
+        res.reason = "UniProt entry has no sequence"
+        return res
+    idx_map, coverage = _alignment_map(wt_seq, up_seq)
+    res.coverage = coverage
+    if coverage < min_coverage:
+        res.abstained = True
+        res.reason = (f"WT aligns to only {coverage:.0%} of the UniProt sequence "
+                      f"(< {min_coverage:.0%}): likely the wrong entry/isoform -- not mapping")
+        return res
+    # aggregate features per mapped WT position
+    agg: dict[int, dict] = {}
+    for f in feats:
+        mapped = False
+        for up_pos in range(f.start, f.end + 1):
+            wt0 = idx_map.get(up_pos - 1)
+            if wt0 is None:
+                continue
+            mapped = True
+            d = agg.setdefault(wt0 + 1, {"uni": up_pos, "res": wt_seq[wt0], "types": set(),
+                                         "ligands": set(), "confs": set()})
+            d["types"].add(f.type)
+            if f.ligand:
+                d["ligands"].add(f.ligand)
+            d["confs"].add(_confidence(f.evidence))
+        if not mapped:
+            res.unmapped.append(f)
+    for wtp in sorted(agg):
+        d = agg[wtp]
+        best = min(d["confs"], key=lambda c: _CONF_RANK.get(c, 99)) if d["confs"] else "unknown"
+        res.sites.append(ResolvedSite(
+            wt_position=wtp, residue=d["res"], source_position=d["uni"],
+            types=tuple(sorted(d["types"])), ligands=tuple(sorted(d["ligands"])), confidence=best,
+        ))
+    res.positions = sorted(agg)
+    if not res.sites:
+        res.abstained = True
+        res.reason = ("no active/binding/metal-site features mapped onto WT "
+                      "(entry has none, or they fell outside the aligned region)")
+    return res
+
+
+_UA = {"User-Agent": "Mozilla/5.0 (compatible; shellde-resolve-site)"}
+
+
+def _get_json(url: str, timeout: float = 20.0) -> dict:
+    req = urllib.request.Request(url, headers=_UA)
+    with urllib.request.urlopen(req, timeout=timeout) as r:  # noqa: S310 (trusted host)
+        return json.loads(r.read().decode())
+
+
+def fetch_uniprot(accession: str | None = None, query: str | None = None,
+                  *, timeout: float = 20.0) -> dict | None:
+    """Fetch a UniProt entry JSON by accession, or the top search hit for a text query. Network."""
+    if accession:
+        return _get_json(f"https://rest.uniprot.org/uniprotkb/{urllib.parse.quote(accession)}.json", timeout)
+    if query:
+        q = urllib.parse.urlencode({"query": query, "format": "json", "size": "1"})
+        hits = _get_json(f"https://rest.uniprot.org/uniprotkb/search?{q}", timeout)
+        results = hits.get("results") or []
+        if not results:
+            return None
+        acc = results[0].get("primaryAccession")
+        return _get_json(f"https://rest.uniprot.org/uniprotkb/{acc}.json", timeout) if acc else results[0]
+    raise ValueError("provide an accession or a query")
+
+def _uniparc_accessions(data: dict) -> list[str]:
+    """UniProtKB accessions cross-referenced by a UniParc entry (exact-sequence match), ordered
+    Swiss-Prot (reviewed, has curated features) before TrEMBL, active entries first. Pure/offline."""
+    refs = data.get("dbReference") or data.get("uniParcCrossReferences") or []
+
+    def rank(x: dict) -> tuple:
+        typ = x.get("type") or x.get("database") or ""
+        active = str(x.get("active", "Y")).upper()
+        return (0 if active != "N" else 1, 0 if "Swiss-Prot" in typ else 1)
+
+    out: list[str] = []
+    for x in sorted(refs, key=rank):
+        typ = x.get("type") or x.get("database") or ""
+        acc = x.get("id")
+        if "UniProtKB" in typ and acc and acc not in out:
+            out.append(acc)
+    return out
+
+
+def uniprot_from_sequence(seq: str, *, timeout: float = 20.0) -> list[str]:
+    """UniProtKB accession(s) whose sequence EXACTLY matches ``seq`` (100% identity over the whole
+    sequence, via the EBI Proteins API over UniParc), Swiss-Prot first. Returns [] when there is no
+    exact match (e.g. an engineered construct with tags/point mutations) or on any network/HTTP error
+    -- the caller must then abstain or ask for an accession, never guess. Network.
+    """
+    clean = "".join(seq.split()).upper()
+    if not clean:
+        return []
+    try:
+        req = urllib.request.Request(
+            "https://www.ebi.ac.uk/proteins/api/uniparc/sequence",
+            data=clean.encode(), method="POST",
+            headers={**_UA, "Content-Type": "text/plain", "Accept": "application/json"},
+        )
+        with urllib.request.urlopen(req, timeout=timeout) as r:  # noqa: S310 (trusted EBI host)
+            data = json.loads(r.read().decode())
+    except Exception:  # noqa: BLE001 (no exact match / network / HTTP -> abstain, return [])
+        return []
+    return _uniparc_accessions(data)
+
+# --------------------------------------------------------------------------- #
+# Layer 2: UniProt-linked PDB cocrystal -> structure-derived active-site shells
+# --------------------------------------------------------------------------- #
+def pdb_ids_from_uniprot(data: dict) -> list[str]:
+    """PDB IDs cross-referenced by a UniProt entry, X-ray first then best resolution."""
+    rows = []
+    for x in data.get("uniProtKBCrossReferences", []) or []:
+        if x.get("database") != "PDB":
+            continue
+        props = {p.get("key"): p.get("value") for p in (x.get("properties") or [])}
+        rows.append((x.get("id", ""), props.get("Method", ""), props.get("Resolution", "")))
+
+    def rank(t: tuple) -> tuple:
+        _, method, resol = t
+        try:
+            r = float(str(resol).split()[0])
+        except (ValueError, IndexError):
+            r = 9e9
+        return (0 if "X-ray" in method else 1, r)
+
+    return [pid for pid, _, _ in sorted(rows, key=rank) if pid]
+
+
+def _pdb_chain_residues(pdb_text: str, chain: str | None = None) -> tuple[str | None, list[tuple[int, str]]]:
+    """(chain id used, [(residue_number, aa1)]) from CA ATOM records of one chain (first if None)."""
+    target = chain
+    out: list[tuple[int, str]] = []
+    for line in pdb_text.splitlines():
+        if not line.startswith("ATOM") or line[12:16].strip() != "CA":
+            continue
+        if line[16] not in (" ", "A"):
+            continue
+        c = line[21]
+        if target is None:
+            target = c
+        if c != target:
+            continue
+        try:
+            out.append((int(line[22:26]), _AA3.get(line[17:20].strip(), "X")))
+        except ValueError:
+            continue
+    return target, out
+
+
+def fetch_pdb(pdb_id: str, *, timeout: float = 20.0) -> str:
+    """Download a PDB file from RCSB. Network."""
+    url = f"https://files.rcsb.org/download/{pdb_id.upper()}.pdb"
+    req = urllib.request.Request(url, headers=_UA)
+    with urllib.request.urlopen(req, timeout=timeout) as r:  # noqa: S310 (trusted RCSB host)
+        return r.read().decode("latin-1")
+
+
+def fetch_alphafold(accession: str, *, timeout: float = 20.0) -> str | None:
+    """Fetch the AlphaFold DB predicted model (PDB text) for a UniProt accession, or None.
+
+    Uses the AFDB API to resolve the current file URL (version changes over time; do not hardcode),
+    then downloads the model. Returns None on any failure/absence. The model is APO (no ligand), so it
+    yields a structure for inspection / --holo-with-a-docked-ligand / external pocket tools, not
+    active-site positions by itself. Network.
+    """
+    try:
+        meta = _get_json(f"https://alphafold.ebi.ac.uk/api/prediction/{urllib.parse.quote(accession)}", timeout)
+    except Exception:  # noqa: BLE001
+        return None
+    if not meta or not isinstance(meta, list):
+        return None
+    url = meta[0].get("pdbUrl")
+    if not url:
+        return None
+    try:
+        req = urllib.request.Request(url, headers=_UA)
+        with urllib.request.urlopen(req, timeout=timeout) as r:  # noqa: S310 (trusted AFDB host)
+            return r.read().decode("latin-1")
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def run_fpocket(pdb_text: str, *, fpocket_bin: str = "fpocket", top: int = 1, timeout: float = 180.0):
+    """Run fpocket on a structure; return the top-``top`` pockets' atom-PDB texts, or None.
+
+    Requires the external ``fpocket`` binary (conda-forge). None if it is not installed or finds no
+    pocket -- callers then abstain (no fabricated pocket). Apo-structure pocket detection is a
+    heuristic prior, tagged low-confidence downstream.
+    """
+    import shutil
+    import subprocess
+    exe = shutil.which(fpocket_bin) or (fpocket_bin if os.path.isfile(fpocket_bin) else None)
+    if not exe:
+        return None
+    d = tempfile.mkdtemp()
+    try:
+        p = os.path.join(d, "model.pdb")
+        with open(p, "w") as fh:
+            fh.write(pdb_text)
+        subprocess.run([exe, "-f", p], capture_output=True, timeout=timeout, cwd=d, check=False)
+        pockets = []
+        for i in range(1, top + 1):
+            f = os.path.join(d, "model_out", "pockets", f"pocket{i}_atm.pdb")
+            if os.path.isfile(f):
+                pockets.append(open(f).read())
+        return pockets or None
+    except Exception:  # noqa: BLE001
+        return None
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+def resolve_from_apo(
+    wt_seq: str, apo_pdb_text: str, *, source: str = "AlphaFold+fpocket",
+    fpocket_bin: str = "fpocket", top_pockets: int = 1, min_coverage: float = 0.6,
+) -> ResolveResult:
+    """Predicted pocket residues from an APO structure (fpocket), mapped onto WT. LOW confidence.
+
+    For novel proteins with no experimental site/structure: detect the pocket geometrically on a
+    predicted (AlphaFold) model, then map the pocket-lining residues onto WT by alignment. Abstains
+    if fpocket is unavailable or nothing maps. Tagged ``predicted-pocket`` -- a heuristic prior to
+    verify, not curated evidence.
+    """
+    res = ResolveResult(source=source)
+    pockets = run_fpocket(apo_pdb_text, fpocket_bin=fpocket_bin, top=top_pockets)
+    if not pockets:
+        res.abstained = True
+        res.reason = "fpocket unavailable or found no pocket"
+        return res
+    _, residues = _pdb_chain_residues(apo_pdb_text)
+    if not residues:
+        res.abstained = True
+        res.reason = "no ATOM CA records in apo model"
+        return res
+    obs_seq = "".join(a for _, a in residues)
+    idx_map, coverage = _alignment_map(wt_seq, obs_seq)
+    res.coverage = coverage
+    if coverage < min_coverage:
+        res.abstained = True
+        res.reason = f"WT aligns to only {coverage:.0%} of the apo model (< {min_coverage:.0%})"
+        return res
+    resnum_to_obs = {rn: i for i, (rn, _) in enumerate(residues)}
+    agg: dict[int, dict] = {}
+    for rank, pk in enumerate(pockets, 1):
+        pk_resnums = set()
+        for line in pk.splitlines():
+            if line.startswith("ATOM"):  # protein residues only (skip STP alpha-sphere HETATM)
+                try:
+                    pk_resnums.add(int(line[22:26]))
+                except ValueError:
+                    continue
+        for rn in pk_resnums:
+            obs_i = resnum_to_obs.get(rn)
+            if obs_i is None:
+                continue
+            wt0 = idx_map.get(obs_i)
+            if wt0 is None:
+                continue
+            agg.setdefault(wt0 + 1, {"uni": rn, "res": wt_seq[wt0], "rank": rank})
+    for wtp in sorted(agg):
+        d = agg[wtp]
+        res.sites.append(ResolvedSite(
+            wt_position=wtp, residue=d["res"], source_position=d["uni"],
+            types=(f"predicted-pocket-{d['rank']}",), ligands=(), confidence="predicted-pocket",
+        ))
+    res.positions = sorted(agg)
+    if not res.sites:
+        res.abstained = True
+        res.reason = "fpocket pocket residues did not align onto WT"
+    return res
+
+
+def resolve_from_pdb(
+    wt_seq: str, pdb_text: str, *, pdb_id: str = "", chain: str | None = None,
+    ligand_resnames=None, contact_cutoff: float = 4.5, min_coverage: float = 0.6,
+) -> ResolveResult:
+    """Active-site shells from a (holo) PDB, mapped onto WT numbering. Pure (no network).
+
+    Runs :func:`structure.shells_from_pdb` (needs a ligand pose), then maps the PDB-numbered shell
+    residues onto WT positions through a sequence alignment of the chosen chain -- so PDB numbering
+    gaps/offsets are handled the same way as the UniProt path. Abstains when there is no ligand or
+    the chain does not align to WT.
+    """
+    res = ResolveResult(source=f"PDB:{pdb_id}" if pdb_id else "PDB")
+    used_chain, residues = _pdb_chain_residues(pdb_text, chain)
+    if not residues:
+        res.abstained = True
+        res.reason = "no ATOM CA records in PDB"
+        return res
+    tf = tempfile.NamedTemporaryFile("w", suffix=".pdb", delete=False)
+    try:
+        tf.write(pdb_text)
+        tf.close()
+        shells = shells_from_pdb(tf.name, ligand_resnames=ligand_resnames, chain=used_chain,
+                                 contact_cutoff=contact_cutoff)
+    except ValueError as exc:
+        res.abstained = True
+        res.reason = f"no ligand/active-site shell in PDB ({exc})"
+        return res
+    finally:
+        try:
+            os.unlink(tf.name)
+        except OSError:
+            pass
+    obs_seq = "".join(a for _, a in residues)
+    idx_map, coverage = _alignment_map(wt_seq, obs_seq)
+    res.coverage = coverage
+    if coverage < min_coverage:
+        res.abstained = True
+        res.reason = f"WT aligns to only {coverage:.0%} of the PDB chain (< {min_coverage:.0%})"
+        return res
+    resnum_to_obs = {rn: i for i, (rn, _) in enumerate(residues)}
+    agg: dict[int, dict] = {}
+    for level, label in ((1, "active-site shell 1"), (2, "active-site shell 2")):
+        for rn in shells.get(level, []):
+            obs_i = resnum_to_obs.get(rn)
+            if obs_i is None:
+                continue
+            wt0 = idx_map.get(obs_i)
+            if wt0 is None:
+                continue
+            d = agg.setdefault(wt0 + 1, {"uni": rn, "res": wt_seq[wt0], "types": set()})
+            d["types"].add(label)
+    for wtp in sorted(agg):
+        d = agg[wtp]
+        res.sites.append(ResolvedSite(
+            wt_position=wtp, residue=d["res"], source_position=d["uni"],
+            types=tuple(sorted(d["types"])), ligands=(), confidence="structure",
+        ))
+    res.positions = sorted(agg)
+    if not res.sites:
+        res.abstained = True
+        res.reason = "active-site shells did not align onto WT"
+    return res