pen-stack 0.1.0__py3-none-any.whl

pen_stack/data/ingest_safety_annot.py

@@ -0,0 +1,201 @@
+"""Safety annotations per 1 kb bin (license-clean source).
+
+Builds per-bin safety features from CancerMine (CC0; oncogene/TSG loci, the default, shipped) or COSMIC CGC
+(local-only, bring-your-own-license), DepMap CRISPRGeneEffect (essential genes), and GENCODE (gene/TSS distances):
+  - dist_oncogene, dist_tsg, dist_essential, dist_tss (bp to nearest, via bedtools closest)
+  - genotoxic_cis flag (bins within a window of LMO2/MECOM/CCND2/PRDM16/HMGA2)
+
+Inputs are staged on the VM under /data/external (COSMIC tsv, DepMap csv); GENCODE is downloaded.
+Runs CPU-only in the penstack:phase1 image (bedtools in-image). Output keyed on (chrom, bin).
+"""
+from __future__ import annotations
+
+import argparse
+import gzip
+import os
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+import pybedtools
+import requests
+
+from pen_stack.data.genome import MAIN_CHROMS
+
+GENCODE_GTF = ("https://ftp.ebi.ac.uk/pub/databases/gencode/Gencode_human/"
+               "release_46/gencode.v46.basic.annotation.gtf.gz")
+GENOTOXIC = ["LMO2", "MECOM", "EVI1", "CCND2", "PRDM16", "HMGA2"]
+BIN_BP = 1000
+CIS_WINDOW = 50000 # bp window around a genotoxic gene to flag
+
+
+def _chr(c: str) -> str:
+    c = str(c)
+    return c if c.startswith("chr") else f"chr{c}"
+
+
+def load_cosmic(tsv: str) -> pd.DataFrame:
+    df = pd.read_csv(tsv, sep="\t", dtype=str)
+    df = df.dropna(subset=["CHROMOSOME", "GENOME_START", "GENOME_STOP"])
+    df["chrom"] = df["CHROMOSOME"].map(_chr)
+    df["start"] = pd.to_numeric(df["GENOME_START"], errors="coerce")
+    df["end"] = pd.to_numeric(df["GENOME_STOP"], errors="coerce")
+    df = df.dropna(subset=["start", "end"])
+    df["role"] = df.get("ROLE_IN_CANCER", "").fillna("")
+    df = df[df["chrom"].isin(MAIN_CHROMS)]
+    df["start"] = df["start"].astype(int)
+    df["end"] = df["end"].astype(int)
+    return df[["chrom", "start", "end", "GENE_SYMBOL", "role"]]
+
+
+# CancerMine (CC0) is the license-clean oncogene/TSG/driver source that REPLACES COSMIC CGC in the shipped
+# artifact. Lever et al., Nat Methods 16:505-507 (2019), doi:10.1038/s41592-019-0422-y, CC0; Zenodo record 7689627.
+# COSMIC stays available (load_cosmic) but OFF by default, for local enrichment under the user's own license (BYO).
+CANCERMINE_URL = "https://zenodo.org/records/7689627/files/cancermine_collated.tsv?download=1"
+_ROLE_MAP = {"Oncogene": "oncogene", "Tumor_Suppressor": "TSG", "Driver": "driver"}
+
+
+def load_cancermine(tsv: str, genes: pd.DataFrame, min_citations: int = 3) -> pd.DataFrame:
+    """CC0 oncogene/TSG/driver list. The collated file has one row per (gene, cancer, role) with a citation_count;
+    we aggregate per gene-role across cancers (sum citations), keep roles with >= min_citations, and map the HUGO
+    symbol -> genomic coordinates via GENCODE. Returns the SAME schema as load_cosmic (chrom,start,end,GENE_SYMBOL,
+    role) with the role string containing 'oncogene'/'TSG'/'driver' so the downstream filters are unchanged."""
+    cm = pd.read_csv(tsv, sep="\t", dtype=str)
+    cm["cites"] = pd.to_numeric(cm.get("citation_count"), errors="coerce").fillna(0)
+    agg = cm.groupby(["gene_normalized", "role"], as_index=False)["cites"].sum()
+    agg = agg[agg["cites"] >= float(min_citations)]
+    agg["rn"] = agg["role"].map(_ROLE_MAP).fillna(agg["role"])
+    roles = (agg.groupby("gene_normalized")["rn"]
+             .apply(lambda s: ",".join(sorted(set(s)))).reset_index(name="role"))
+    g = genes[["gene_name", "chrom", "start", "end"]].drop_duplicates("gene_name")
+    m = roles.merge(g, left_on="gene_normalized", right_on="gene_name", how="inner")
+    return m.rename(columns={"gene_normalized": "GENE_SYMBOL"})[["chrom", "start", "end", "GENE_SYMBOL", "role"]]
+
+
+def load_depmap_essential(csv: str, thresh: float = -0.5) -> set[str]:
+    """Common-essential genes: mean Chronos effect across cell lines < thresh."""
+    df = pd.read_csv(csv, index_col=0)
+    means = df.mean(axis=0)
+    genes = {c.split(" (")[0] for c, m in means.items() if m < thresh}
+    return genes
+
+
+def download_gencode(dest: str, url: str = GENCODE_GTF) -> str:
+    if not (os.path.exists(dest) and os.path.getsize(dest) > 0):
+        Path(dest).parent.mkdir(parents=True, exist_ok=True)
+        with requests.get(url, stream=True, timeout=600) as r:
+            r.raise_for_status()
+            with open(dest, "wb") as fh:
+                for ch in r.iter_content(1 << 20):
+                    fh.write(ch)
+    return dest
+
+
+def parse_gencode_genes(gtf_gz: str) -> pd.DataFrame:
+    rows = []
+    with gzip.open(gtf_gz, "rt") as fh:
+        for line in fh:
+            if line.startswith("#"):
+                continue
+            f = line.rstrip("\n").split("\t")
+            if f[2] != "gene":
+                continue
+            chrom = f[0]
+            if chrom not in MAIN_CHROMS:
+                continue
+            start, end, strand = int(f[3]), int(f[4]), f[6]
+            attrs = f[8]
+            name = ""
+            for kv in attrs.split(";"):
+                kv = kv.strip()
+                if kv.startswith("gene_name"):
+                    name = kv.split('"')[1]
+                    break
+            tss = start if strand == "+" else end
+            rows.append((chrom, start, end, strand, name, tss))
+    return pd.DataFrame(rows, columns=["chrom", "start", "end", "strand", "gene_name", "tss"])
+
+
+def _bed(df: pd.DataFrame, cols=("chrom", "start", "end")) -> pybedtools.BedTool:
+    b = df[list(cols)].copy()
+    b.columns = ["chrom", "start", "end"]
+    b = b.sort_values(["chrom", "start"])
+    return pybedtools.BedTool.from_dataframe(b)
+
+
+def nearest_dist(bins_bed: pybedtools.BedTool, feat_df: pd.DataFrame, name: str) -> pd.DataFrame:
+    if feat_df.empty:
+        return pd.DataFrame(columns=["chrom", "start", name])
+    fb = _bed(feat_df).sort()
+    closest = bins_bed.closest(fb, d=True)
+    out = closest.to_dataframe(header=None, usecols=[0, 1, closest.field_count() - 1],
+                               names=["chrom", "start", name])
+    # bedtools closest -d returns -1 when there is NO feature on that chromosome; that means
+    # "no nearby feature" (effectively infinite distance), NOT distance 0. Map the sentinel to NaN.
+    out[name] = out[name].where(out[name] >= 0, other=np.nan)
+    return out.groupby(["chrom", "start"], as_index=False)[name].min()
+
+
+def build(bin_grid: str, depmap_csv: str, gencode_dest: str, sizes_tsv: str, out_parquet: str, *,
+          source: str = "cancermine", cancermine_tsv: str | None = None, cosmic_tsv: str | None = None,
+          min_citations: int = 3) -> pd.DataFrame:
+    """Build per-bin safety features. `source` selects the LICENSE-CLEAN oncogene/TSG list: 'cancermine' (CC0,
+    default, shipped) or 'cosmic' (local-only, under the user's own license, bring-your-own-license enrichment)."""
+    grid = pd.read_parquet(bin_grid)[["chrom", "start", "bin"]]
+    bins_bed = _bed(grid.assign(end=grid["start"] + BIN_BP)).sort()
+
+    gtf = download_gencode(gencode_dest)
+    genes = parse_gencode_genes(gtf)
+
+    if source == "cosmic":
+        cg = load_cosmic(cosmic_tsv)
+    else: # default: CancerMine (CC0)
+        cg = load_cancermine(cancermine_tsv, genes, min_citations=min_citations)
+    onco = cg[cg["role"].str.contains("oncogene", case=False, na=False)]
+    tsg = cg[cg["role"].str.contains("TSG", case=False, na=False)]
+
+    ess_syms = load_depmap_essential(depmap_csv)
+    ess = genes[genes["gene_name"].isin(ess_syms)]
+
+    out = grid.copy()
+    for nm, fdf in [("dist_oncogene", onco), ("dist_tsg", tsg),
+                    ("dist_essential", ess), ("dist_tss", genes.assign(end=genes["tss"] + 1, start=genes["tss"]))]:
+        d = nearest_dist(bins_bed, fdf, nm)
+        out = out.merge(d, on=["chrom", "start"], how="left")
+
+    # genotoxic CIS flag
+    gtox = genes[genes["gene_name"].isin(GENOTOXIC)].copy()
+    gtox["start"] = (gtox["start"] - CIS_WINDOW).clip(lower=0)
+    gtox["end"] = gtox["end"] + CIS_WINDOW
+    gflag = nearest_dist(bins_bed, gtox, "dist_gtox")
+    out = out.merge(gflag, on=["chrom", "start"], how="left")
+    out["genotoxic_cis"] = (out["dist_gtox"].fillna(1e9) == 0)
+
+    Path(out_parquet).parent.mkdir(parents=True, exist_ok=True)
+    out.to_parquet(out_parquet, index=False)
+    return out
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--bin-grid", default="/data/features/bin_grid_1kb.parquet")
+    ap.add_argument("--source", choices=["cancermine", "cosmic"], default="cancermine",
+                    help="oncogene/TSG source: cancermine (CC0, shipped default) or cosmic (local-only BYO-license)")
+    ap.add_argument("--cancermine", default="/data/external/cancermine_collated.tsv")
+    ap.add_argument("--min-citations", type=int, default=3,
+                    help="CancerMine per-gene-role citation threshold (3 = validated precision: safety AUROC 0.74)")
+    ap.add_argument("--cosmic", default="/data/external/Cosmic_CancerGeneCensus_v104_GRCh38.tsv")
+    ap.add_argument("--depmap", default="/data/external/CRISPRGeneEffect.csv")
+    ap.add_argument("--gencode", default="/data/raw/gencode.v46.basic.gtf.gz")
+    ap.add_argument("--sizes", default="/data/raw/hg38.chrom.sizes")
+    ap.add_argument("--out", default="/data/features/safety_annot.parquet")
+    a = ap.parse_args()
+    df = build(a.bin_grid, a.depmap, a.gencode, a.sizes, a.out, source=a.source,
+               cancermine_tsv=a.cancermine, cosmic_tsv=a.cosmic, min_citations=a.min_citations)
+    n_onco = (df["dist_oncogene"] == 0).sum()
+    print(f"safety_annot[{a.source}] bins={len(df)} cols={[c for c in df.columns if c.startswith('dist') or c=='genotoxic_cis']}")
+    print(f"bins in an oncogene={n_onco} genotoxic_cis bins={int(df['genotoxic_cis'].sum())}")
+
+
+if __name__ == "__main__":
+    main()

pen_stack/data/ingest_trip.py

@@ -0,0 +1,76 @@
+"""TRIP durability supervision.
+
+Ingests the Akhtar et al. 2013 TRIP data (GEO GSE49806 tet-O + GSE49807 mPGK; mouse mESC): each row is
+one integrated reporter at a genomic position with expression. Produces (position, expression level,
+silenced/expressed label) - the supervision for the conditional chromatin-context durability model.
+
+The model learns `local chromatin features -> expression`; it never sees the coordinate. So TRIP being
+mouse is fine: attach mouse (mES) chromatin features at these positions, train the function, then apply
+it to a human epigenome (the headline function-transfer test).
+"""
+from __future__ import annotations
+
+import argparse
+import gzip
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+
+def load_trip(txt_gz: str, promoter: str) -> pd.DataFrame:
+    """Robust to both TRIP schemas: GSE49807 (plain) and GSE49806 (leading '#' comment + multi-Dox
+    columns; we use the 100 ng full-induction normalization/expression pair)."""
+    with gzip.open(txt_gz, "rt") as fh:
+        raw = pd.read_csv(fh, sep="\t", comment="#", dtype=str)
+    cols = {c.lower().strip(): c for c in raw.columns}
+    chrom_c = cols.get("chromosome")
+    pos_c = cols.get("position")
+    norm_c = cols.get("normalization_counts_100ng_1") or cols.get("normalization_counts")
+    expr_c = cols.get("expression_counts_100ng_1") or cols.get("expression_counts")
+    if not all([chrom_c, pos_c, norm_c, expr_c]):
+        raise ValueError(f"{txt_gz}: missing expected columns; have {list(raw.columns)[:8]}")
+    df = pd.DataFrame({
+        "chrom": raw[chrom_c].astype(str),
+        "pos": pd.to_numeric(raw[pos_c], errors="coerce"),
+        "norm_counts": pd.to_numeric(raw[norm_c], errors="coerce"),
+        "expr_counts": pd.to_numeric(raw[expr_c], errors="coerce"),
+    }).dropna()
+    df["pos"] = df["pos"].astype(int)
+    df["promoter"] = promoter
+    return df
+
+
+def assemble(files: dict[str, str], out_parquet: str, silenced_quantile: float = 0.25) -> pd.DataFrame:
+    parts = [load_trip(path, prom) for prom, path in files.items()]
+    df = pd.concat(parts, ignore_index=True)
+    # normalized expression (expression per normalization read), log scale
+    df["expression"] = np.log2((df["expr_counts"] + 1) / (df["norm_counts"] + 1))
+    # silenced/expressed: low tail of expression flagged silenced (per promoter, to control for promoter strength)
+    df["silenced"] = False
+    for prom, g in df.groupby("promoter"):
+        thr = g["expression"].quantile(silenced_quantile)
+        df.loc[g.index, "silenced"] = g["expression"] <= thr
+    df["stable"] = ~df["silenced"]
+    Path(out_parquet).parent.mkdir(parents=True, exist_ok=True)
+    df.to_parquet(out_parquet, index=False)
+    return df
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--teto", default="/data/external/trip/GSE49806_S2.txt.gz")
+    ap.add_argument("--mpgk", default="/data/external/trip/GSE49807_S3.txt.gz")
+    ap.add_argument("--out", default="/data/features/trip_mesc.parquet")
+    a = ap.parse_args()
+    files = {k: v for k, v in {"tetO": a.teto, "mPGK": a.mpgk}.items() if Path(v).exists()}
+    df = assemble(files, a.out)
+    print(f"TRIP integrations: {len(df)} promoters={df['promoter'].value_counts().to_dict()}")
+    print(f"expression range (log2): [{df['expression'].min():.2f}, {df['expression'].max():.2f}] "
+          f"~{2**(df['expression'].max()-df['expression'].min()):.0f}-fold")
+    print(f"silenced={int(df['silenced'].sum())} stable={int(df['stable'].sum())}")
+    print(f"chroms: {sorted(df['chrom'].unique())[:6]}... (mouse build)")
+
+
+if __name__ == "__main__":
+    main()

pen_stack/design/__init__.py

@@ -0,0 +1,14 @@
+"""pen_stack.design, the grounded generative designer.
+
+Generate candidate end-to-end writing systems, keep only those that pass safety + legality + calibration
+(verifier-as-discriminator), and return the Pareto frontier of real tradeoffs, including an immune-risk axis
+grounded in the profile. Nothing unvalidated is asserted: every survivor is `output_kind="candidate"`.
+"""
+from __future__ import annotations
+
+from pen_stack.design.generate import generate_designs
+from pen_stack.design.pareto import AXES, neg_immune_risk, pareto_front
+from pen_stack.design.space import candidate_space, deliverability_score
+
+__all__ = ["generate_designs", "candidate_space", "deliverability_score",
+           "pareto_front", "neg_immune_risk", "AXES"]

pen_stack/design/capsid_generate.py

@@ -0,0 +1,62 @@
+"""Verify-gated generative AAV capsid candidates.
+
+Proposes engineered AAV capsid variants in the mutagenized VP1 region, scores them with the learned FLIP-AAV
+capsid-fitness model, and keeps only candidates above a fitness threshold, the verifier-as-discriminator pattern
+GENERATE proposes, the fitness model + biosecurity context DISPOSE. Every survivor is a CANDIDATE,
+never asserted to assemble or to have any in-vivo tropism. Abstains when the fitness model is not present (no
+fabricated capsids).
+
+a generated capsid's predicted fitness is for the MEASURED packaging axis only; assembly, in-vivo tropism,
+and immunogenicity are not claimed (the latter routes through the immune-risk axis). This is a design proposer, not a validation.
+"""
+from __future__ import annotations
+
+_AAS = "ACDEFGHIKLMNPQRSTVWY"
+
+
+def _mutate(seq: str, region: tuple[int, int], n_mut: int, rng) -> str:
+    s = list(seq)
+    lo, hi = region
+    positions = rng.sample(range(lo, min(hi, len(s))), min(n_mut, max(0, min(hi, len(s)) - lo)))
+    for p in positions:
+        s[p] = _AAS[rng.randrange(len(_AAS))]
+    return "".join(s)
+
+
+def generate_capsid_candidates(wt_vp1: str, n: int = 200, max_mut: int = 4, fitness_threshold: float | None = None,
+                               seed: int = 7, top: int = 20) -> dict:
+    """Propose AAV capsid variants (random substitutions in the VP1 555-595 mutagenized window), score with the
+    learned capsid-fitness model, and return the top survivors above ``fitness_threshold`` (defaults to the WT's
+    predicted fitness). Candidates are flagged; abstains when the fitness model is absent, never fabricates."""
+    import random
+    from pen_stack.planner.delivery_predict import capsid_fitness
+    wt = capsid_fitness(wt_vp1)
+    if not wt.get("available"):
+        return {"available": False, "abstain": True, "candidates": [], "output_kind": "candidate",
+                "note": "capsid-fitness model not present -> cannot score generated capsids; no fabrication.",
+                "bench": wt.get("bench")}
+    rng = random.Random(seed)
+    thr = fitness_threshold if fitness_threshold is not None else wt["predicted_fitness"]
+    region = (555, 595)
+    seen = set()
+    scored = []
+    for _ in range(max(1, n)):
+        nm = rng.randint(1, max_mut)
+        cand = _mutate(wt_vp1, region, nm, rng)
+        if cand == wt_vp1 or cand in seen:
+            continue
+        seen.add(cand)
+        f = capsid_fitness(cand)["predicted_fitness"]
+        scored.append({"vp1_window": cand[region[0]:region[1]], "predicted_fitness": f,
+                       "n_mut_in_region": sum(1 for a, b in zip(cand[region[0]:region[1]],
+                                                                wt_vp1[region[0]:region[1]]) if a != b),
+                       "passes_threshold": bool(f >= thr), "output_kind": "candidate"})
+    survivors = sorted([c for c in scored if c["passes_threshold"]],
+                       key=lambda c: c["predicted_fitness"], reverse=True)[:top]
+    return {"available": True, "abstain": False, "wt_predicted_fitness": wt["predicted_fitness"],
+            "fitness_threshold": round(float(thr), 4), "n_proposed": len(scored), "n_survivors": len(survivors),
+            "candidates": survivors, "output_kind": "candidate",
+            "verifier": "learned FLIP-AAV capsid-fitness (verifier-as-discriminator); fitness >= WT kept",
+            "honesty": "CANDIDATES, predicted packaging fitness only; assembly, in-vivo tropism, and "
+                       "immunogenicity are NOT claimed (immunogenicity routes through the immune-risk profile). A design proposer, "
+                       "not a validation. Run a biosecurity/verify() gate before any synthesis."}

pen_stack/design/generate.py

@@ -0,0 +1,70 @@
+"""Generative inverse design, verifier-as-discriminator.
+
+Generation PROPOSES candidate end-to-end writing systems; the `verify()`, now safety-gated,
+legality-checked, calibrated, and immune-profiled, DISPOSES. A candidate that is hazardous
+(safety refuse/escalate) or illegal is DISCARDED, never returned as a claim: the `as_claim()` guard generalised
+to whole designs. Survivors are explicitly `output_kind="candidate"`, calibrated and immune-profiled, but never
+asserted to work.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from pen_stack.design.space import candidate_space, vehicle_sweep
+from pen_stack.verify import verify
+
+# a survivor must be legal AND safe (cleared or low-severity advisory); refuse/escalate are discarded.
+_SAFE_DECISIONS = {"clear", "flag"}
+
+
+def _confidence_key(d: dict) -> tuple:
+    c = d.get("confidence")
+    return (c is not None, c if c is not None else -1.0)
+
+
+def generate_designs(goal: dict | None = None, *, candidates: list[dict] | None = None,
+                     n: int = 200, keep: int = 25, actor: str = "generator") -> list[dict[str, Any]]:
+    """Generate -> discriminate with `verify()`. Returns the surviving candidates, each carrying a calibrated
+    confidence (or explicit abstention), the immune profile, the safety decision, and scope flags, sorted
+    by confidence. Hazardous (refuse/escalate) or illegal proposals are discarded, never returned.
+
+    Pass an explicit ``candidates`` list to discriminate a known pool (atlas-independent); otherwise candidates
+    are enumerated from ``goal`` via the planner-backed candidate space.
+
+    When the goal's cell type has NO measured writability atlas (so the planner-backed candidate_space
+    yields nothing), fall back to an atlas-free vehicle sweep so the legality + biosecurity discrimination still
+    runs; those survivors carry no calibrated confidence (it abstains, surfaced in the UI) rather than
+    the page showing an empty table for a perfectly legal, screened design. The explicit-``candidates`` path is
+    untouched (``generate_designs(candidates=[])`` still returns [])."""
+    if candidates is not None:
+        pool = candidates
+    else:
+        pool = candidate_space(goal or {}, n=n)
+        if not pool and goal: # atlas absent for this cell type -> atlas-free sweep (confidence will abstain)
+            pool = vehicle_sweep(goal, n=n)
+    survivors: list[dict] = []
+    for d in pool:
+        v = verify(dict(d), actor=actor)
+        decision = v.safety.decision if v.safety is not None else "clear"
+        if v.legal is not True or decision not in _SAFE_DECISIONS:
+            continue # discarded by the discriminator
+        survivors.append({
+            **d,
+            "confidence": v.confidence, "interval": v.interval,
+            "immune_profile": v.immune_profile, # grounded per-axis vector
+            "safety_decision": decision, "legal": v.legal,
+            "scope_flags": v.scope_flags, "output_kind": "candidate",
+        })
+    survivors.sort(key=_confidence_key, reverse=True)
+    # Dedupe: candidate_space pairs every top SITE with every vehicle, so several same-(writer, vehicle, cargo)
+    # candidates differ only by site and render identically in the sweep table. Collapse them, keeping the
+    # highest-confidence one (already first after the sort). The site remains available on the survivor.
+    seen: set = set()
+    deduped: list[dict] = []
+    for s in survivors:
+        key = (s.get("write_type"), s.get("writer_family"), s.get("delivery_vehicle"), s.get("cargo_bp"))
+        if key in seen:
+            continue
+        seen.add(key)
+        deduped.append(s)
+    return deduped[:keep]

pen_stack/design/pareto.py

@@ -0,0 +1,70 @@
+"""Multi-objective Pareto frontier with a GROUNDED immune-risk axis.
+
+Returns the non-dominated set of generated candidates over the design tradeoff axes. The `neg_immune_risk` axis
+is sourced from the immune profile (no longer a placeholder): it is the WORST-CASE per-axis in-scope score
+(lower score = higher risk) with the per-axis uncertainty carried as a band, never collapsing the profile into
+one confident number, and keeping the in-vivo magnitude scope-flagged. Unknown axes enter as flagged bounds,
+never fabricated points; the per-axis profile remains the source of truth.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+# higher is better for every axis (neg_* are already oriented so that higher = better).
+AXES = ("efficiency", "durability", "safety", "deliverability", "neg_immune_risk", "neg_cost")
+_COST_CAP_BP = 10000
+
+
+def neg_immune_risk(design: dict) -> dict:
+    """Aggregate the immune profile into ONE Pareto axis WITHOUT collapsing it into a confident number:
+    worst-case per-axis in-scope value + the largest per-axis uncertainty as a band. Returns the value (or None
+    when no axis is in scope) + the band + which axes were used + the standing in-vivo scope flag."""
+    prof = (design.get("immune_profile") or {}).get("axes", {})
+    in_scope = {k: a for k, a in prof.items()
+                if a.get("in_scope") and a.get("value") is not None}
+    worst = min((a["value"] for a in in_scope.values()), default=None) # lower score = higher risk
+    band = max((a.get("uncertainty") or 0.0 for a in in_scope.values()), default=0.0)
+    return {"value": worst, "uncertainty": band, "axes_used": sorted(in_scope),
+            "scope_flag": "in_vivo_magnitude_unknown"}
+
+
+def _scores(design: dict) -> dict[str, float | None]:
+    cargo = float(design.get("cargo_bp") or 0)
+    nir = neg_immune_risk(design)
+    return {
+        "efficiency": _f(design.get("writer_activity")),
+        "durability": _f(design.get("p_durable")),
+        "safety": _f(design.get("safety")),
+        "deliverability": _f(design.get("deliverability")),
+        "neg_immune_risk": nir["value"],
+        "neg_cost": max(0.0, 1.0 - min(cargo, _COST_CAP_BP) / _COST_CAP_BP),
+    }
+
+
+def _f(x) -> float | None:
+    try:
+        return float(x)
+    except (TypeError, ValueError):
+        return None
+
+
+def _dominates(a: dict, b: dict) -> bool:
+    """`a` dominates `b` iff a is >= on every COMPARABLE axis and strictly > on at least one. Axes that are
+    None (unknown) on either design are skipped (a flagged bound never fabricates a winning point)."""
+    comparable = [k for k in AXES if a["scores"][k] is not None and b["scores"][k] is not None]
+    if not comparable:
+        return False
+    ge = all(a["scores"][k] >= b["scores"][k] for k in comparable)
+    gt = any(a["scores"][k] > b["scores"][k] for k in comparable)
+    return ge and gt
+
+
+def pareto_front(designs: list[dict]) -> list[dict[str, Any]]:
+    """Non-dominated set over AXES. Each returned design gets a `scores` dict and a `neg_immune_risk_detail`
+    (value + uncertainty band + axes used + in-vivo scope flag). The immune axis is grounded."""
+    enriched = []
+    for d in designs:
+        d = {**d, "scores": _scores(d), "neg_immune_risk_detail": neg_immune_risk(d)}
+        enriched.append(d)
+    front = [d for d in enriched if not any(_dominates(o, d) for o in enriched if o is not d)]
+    return front

pen_stack/design/space.py

@@ -0,0 +1,137 @@
+"""Candidate-space generation for the generative designer.
+
+`candidate_space(goal)` enumerates candidate end-to-end writing systems, writer x site x cargo x delivery,
+by wrapping the validated inverse-design planner (`plan_write`) for the site x writer x scores, then
+pairing each with every *compatible* delivery vehicle from the curated palette (cargo fits the vehicle
+capacity). Every candidate carries the planner's grounded scores (safety / p_durable / writer_activity) so the
+verifier-as-discriminator can compute a calibrated confidence and the immune profile downstream.
+
+Atlas-dependent: when the writability atlas is absent (e.g. a bare laptop checkout), `plan_write`
+yields nothing and `candidate_space` returns []. The discriminator/Pareto logic is independent of the atlas and
+is exercised on explicit candidates (tests/bench fixtures); the atlas path runs on the VM/with data.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from pen_stack.planner.delivery_vehicles import names as _vehicle_names
+from pen_stack.planner.delivery_vehicles import vehicle as _vehicle
+
+# edit-intent -> write_type (the router/verifier dispatches on write_type)
+_INTENT_WRITE_TYPE = {
+    "safe_harbour_insertion": "insertion",
+    "high_durability_insertion": "insertion",
+    "knock_in_with_disruption": "insertion",
+    "landing_pad_insertion": "landing_pad",
+    "regulatory_element_excision": "excision",
+    "repeat_excision": "excision",
+    "regulatory_rewrite": "regulatory_rewrite",
+}
+
+
+def _compatible_vehicles(cargo_bp: int, in_vivo: bool | None = None) -> list[str]:
+    """Vehicles whose curated cargo capacity fits the cargo (capacity None = no DNA-packaging limit).
+
+    When an administration ``in_vivo`` context is given, also filter by the vehicle's curated route
+    (the `in_vivo` / `ex_vivo` flags in configs/delivery_vehicles.yaml) - an in-vivo goal keeps the in-vivo-capable
+    vehicles, an ex-vivo goal keeps the ex-vivo-capable ones (e.g. lentivirus / electroporation / eVLP). This is a
+    grounded compatibility filter from the curated palette, not a clinical claim. ``in_vivo=None`` keeps all."""
+    out = []
+    for n in _vehicle_names():
+        v = _vehicle(n) or {}
+        cap = v.get("cargo_capacity_bp")
+        if cap is not None and cargo_bp > cap:
+            continue
+        if in_vivo is True and not v.get("in_vivo"):
+            continue
+        if in_vivo is False and not v.get("ex_vivo"):
+            continue
+        out.append(n)
+    return out
+
+
+def deliverability_score(vehicle_name: str, cargo_bp: int) -> float:
+    """Grounded deliverability proxy: capacity headroom (more spare capacity = more deliverable),
+    clipped to [0,1]. Vehicles with no packaging limit score 1.0. NOT a clinical claim."""
+    cap = (_vehicle(vehicle_name) or {}).get("cargo_capacity_bp")
+    if cap is None:
+        return 1.0
+    if cargo_bp > cap:
+        return 0.0
+    return max(0.0, min(1.0, (cap - cargo_bp) / cap))
+
+
+def candidate_space(goal: dict, *, n: int = 200, k: int = 8) -> list[dict[str, Any]]:
+    """Enumerate candidate designs for a goal {gene, intent, cargo_bp, cell_type, cargo_function?}. Each candidate
+    is a plain dict consumable by `verify()` and carries the planner's grounded scores. Returns [] if the atlas is
+    absent.
+
+    The goal's screening-relevant fields (cargo_function, cargo_seq, in_vivo, delivery_tropism,
+    replication_competent) are PROPAGATED onto every candidate so the Guardian biosecurity gate in verify() screens
+    the cargo function for each swept vehicle. Previously these were dropped here, so a hazardous cargo function
+    reached NO screen on the goal-based path."""
+    gene = goal["gene"]
+    intent = goal.get("intent") or goal.get("edit_intent") or "safe_harbour_insertion"
+    cargo_bp = int(goal.get("cargo_bp") or goal.get("payload_bp") or 3000)
+    ct = goal.get("cell_type") or goal.get("ct") or "k562"
+    write_type = _INTENT_WRITE_TYPE.get(intent, "insertion")
+    # screening-relevant goal fields propagated onto every candidate (the Guardian reads cargo_function).
+    screen_extra = {f: goal[f] for f in ("cargo_function", "cargo_seq", "in_vivo", "delivery_tropism",
+                                         "replication_competent") if goal.get(f) is not None}
+
+    from pen_stack.planner.pipeline import plan_write
+    try:
+        plans = plan_write(gene, intent, cargo_bp, ct, k=k)
+    except Exception: # atlas/data absent -> no candidates (discriminator/Pareto unaffected)
+        return []
+
+    vehicles = _compatible_vehicles(cargo_bp, in_vivo=goal.get("in_vivo"))
+    cands: list[dict] = []
+    for p in plans:
+        for veh in vehicles:
+            cands.append({
+                **screen_extra, # cargo_function et al. so the Guardian screens this candidate
+                "write_type": write_type, "gene": gene, "chrom": p["site"]["chrom"],
+                "edit_intent": intent, "writer_family": p["writer"], "cargo_bp": cargo_bp,
+                "cell_type": ct, "delivery_vehicle": veh,
+                # grounded planner scores (model_extra) -> verify() calibrated confidence + downstream:
+                "safety": p["safety"], "p_durable": p["durability"], "writer_activity": p["writer_activity"],
+                "on_target": p["on_target"], "reachability_tier": p.get("reachability_tier"),
+                "deliverability": deliverability_score(veh, cargo_bp),
+                "site": p.get("site"), "cargo": p.get("cargo"),  # carry the site + assembled cassette to the survivor
+                "_planner_score": p["score"],
+                "provenance": {**p.get("provenance", {}), "candidate_space": "plan_write x delivery palette"},
+            })
+            if len(cands) >= n:
+                return cands
+    return cands
+
+
+def vehicle_sweep(goal: dict, *, n: int = 200) -> list[dict[str, Any]]:
+    """Atlas-FREE candidate enumeration: sweep the compatible delivery vehicles for the goal WITHOUT planner
+    scores. Used when the writability atlas has no coverage for the requested cell type (e.g. cd8_t / pbmc /
+    h1_hesc), so `candidate_space` (which needs `plan_write`) yields nothing.
+
+    Each candidate carries the goal's cargo_function (so the Guardian still screens it), the cargo size (so the
+    capacity rules still filter oversize vehicles), and NO safety/p_durable/writer_activity (so verify()
+    ABSTAINS on the calibrated confidence rather than inventing one). The legality + biosecurity discrimination is
+    fully exercised; only the calibrated-confidence column is left uncomputed (and labelled as such in the UI)."""
+    intent = goal.get("intent") or goal.get("edit_intent") or "safe_harbour_insertion"
+    cargo_bp = int(goal.get("cargo_bp") or goal.get("payload_bp") or 3000)
+    ct = goal.get("cell_type") or goal.get("ct") or "k562"
+    write_type = _INTENT_WRITE_TYPE.get(intent, "insertion")
+    screen_extra = {f: goal[f] for f in ("cargo_function", "cargo_seq", "in_vivo", "delivery_tropism",
+                                         "replication_competent") if goal.get(f) is not None}
+    cands: list[dict] = []
+    for veh in _compatible_vehicles(cargo_bp, in_vivo=goal.get("in_vivo")):
+        cands.append({
+            **screen_extra,
+            "write_type": write_type, "gene": goal.get("gene"), "chrom": goal.get("chrom"),
+            "edit_intent": intent, "cargo_bp": cargo_bp, "cell_type": ct, "delivery_vehicle": veh,
+            "deliverability": deliverability_score(veh, cargo_bp),
+            "provenance": {"candidate_space": "atlas-free vehicle sweep "
+                           "(no measured writability atlas for this cell type; confidence abstains)"},
+        })
+        if len(cands) >= n:
+            break
+    return cands