pen-stack 7.1.4__tar.gz → 7.1.6__tar.gz

{pen_stack-7.1.4 → pen_stack-7.1.6}/CHANGELOG.md

@@ -3,6 +3,65 @@
 All notable changes to PEN-STACK are documented here. This file follows
 [Keep a Changelog](https://keepachangelog.com/).
 
+## [7.1.6] - 2026-06-30 - Immune axes wired end-to-end + Delivery folded into Design Studio
+
+### Fixed
+- **Four immune-risk axes were unreachable from the web UI and showed as out-of-scope** — innate sensing, anti-PEG,
+  and the writer-as-antigen MHC-II + ADA axes abstained on every web design because the design form never collected
+  their inputs (the engine computed them correctly when called directly; this was a wiring gap, not a model gap):
+  - **`innate`** needs a cargo sequence. The design form now has an optional **Cargo sequence** field; the cargo
+    nucleic-acid form (DNA -> CpG/TLR9, mRNA -> U-content + dsRNA, RNP -> transient) is derived from the vehicle's
+    defining cargo class (`immune_profile._vehicle_cargo_form`) so the axis computes for any caller (chat / MCP /
+    REST) once a sequence is supplied. Empty sequence still abstains; an explicit `cargo_form` still wins. No
+    fabrication: an unknown vehicle returns no form and the axis abstains.
+  - **`mhc2_writer` / `ada_writer`** need a writer protein. The design form now has a **Writer enzyme** selector
+    (the three grounded families with a bundled UniProt sequence + committed NetMHCIIpan-4.0 cache: serine integrase
+    Bxb1, bridge recombinase ISCro4, Cas9 SpCas9); `DEFAULT_DESIGN` ships a serine integrase so the two axes populate
+    out of the box. No writer selected -> the two axes abstain (never fabricated).
+  - **`anti_peg`** applies only to PEGylated vehicles; selecting `lnp_mrna` now surfaces it (with an inline hint),
+    and it correctly abstains for non-PEG vehicles.
+  - `ImmuneProfileCard` now shows the **writer-as-antigen** summary (representative writer, foreign/self, dominant
+    antigen) so the writer axes are self-explanatory.
+
+### Changed
+- **Delivery & Immunity folded into Design Studio.** The standalone Delivery page duplicated the same design form and
+  immune profile, so it is merged into Design Studio as a third action - **Profile immune & delivery** - with the
+  per-axis immune ScoreGuide, the vehicle quick-switch, the `ImmuneProfileCard` and the scope ledger. Design Studio is
+  now one design surface with three actions (Verify / Generate / Profile immune & delivery). `/delivery` redirects to
+  `/design`; the nav drops the separate item; old links keep working.
+
+### Added
+- `test_ws_profile.py`: tests for the vehicle-derived cargo form (innate computes for a DNA vehicle with a cargo
+  sequence; abstains without one; explicit form overrides) and for the writer axes computing when a grounded writer
+  is supplied (and abstaining otherwise).
+
+## [7.1.5] - 2026-06-29 - Chromosome field: validation, gene concordance, context
+
+### Added
+- The `chrom` design field was a free-text pass-through with no validation and no downstream effect. It is now
+  meaningful (`pen_stack/planner/chromosome.py`):
+  - **Validation** — the web form's Chromosome input is a controlled dropdown (chr1–chr22, chrX, chrY, chrM), so
+    an impossible value like `chrZZZ` can no longer be entered; `canonical_chromosome()` normalises/validates on
+    the backend (`chrX`/`X`/`x`, `chr1`/`1`, `chrM`/`chrMT`/`MT`, `23`→X, `24`→Y; rejects the rest).
+  - **Gene/chromosome concordance** — `verify()` now flags `chromosome_mismatch` when the entered chromosome does
+    not match the named gene's canonical location (e.g. *BRCA1 is on chr17, not chr1*), `chromosome_invalid` for a
+    non-standard value, and `chromosome_unverifiable` for an unknown gene. The web form shows the warning inline
+    with a one-click fix, driven by the new `GET /api/gene/location` endpoint. This closes the silent-mismatch gap.
+  - **Chromosome context** — `chromosome_context()` adds grounded, chromosome-driven advisories surfaced as scope
+    flags: **chrM** is not addressable by nuclear genome-writing tools (mtDNA needs DdCBE/TALED — out of scope),
+    **chrY** is male-specific with ampliconic repeats, **chrX** is hemizygous in 46,XY vs X-inactivated in 46,XX.
+- The Design Studio **cell-type dropdown now shows writability-atlas coverage** (from `/api/celltypes`): K562 /
+  HepG2 / HSPC are labelled measured (full / full / partial), while h1_hesc / iPSC / CD8 T / PBMC are labelled
+  "no atlas" — so a data-gated cell type is no longer silently indistinguishable from a measured one (the same
+  honest-field principle as the chromosome field). The 7 cell types are unchanged and already matched the backend.
+
+### Note (honest scoping)
+- The free-text chromosome does **not** move the scored locus: per-locus safety / durability / accessibility /
+  off-target are indexed by the gene's *resolved genomic coordinates* via the writability atlas, so a bare
+  chromosome string with no position cannot refine them. Rather than fabricate a per-chromosome score delta, the
+  field's grounded effect is validation + gene concordance (ensuring the score is read for the right locus, and
+  flagging when the entered chromosome disagrees with the gene) + the chromosome-context advisories above.
+
 ## [7.1.4] - 2026-06-29 - Germline-prohibition legality rule
 
 ### Added

{pen_stack-7.1.4 → pen_stack-7.1.6}/CITATION.cff

@@ -1,8 +1,8 @@
 cff-version: 1.2.0
 message: "If you use PEN-STACK, please cite it as below."
 title: "PEN-STACK: open infrastructure for genome writing"
-version: 7.1.4
-date-released: 2026-06-29
+version: 7.1.6
+date-released: 2026-06-30
 authors:
   - family-names: "Mahaboob Ali"
     given-names: "Anees Ahmed"

{pen_stack-7.1.4 → pen_stack-7.1.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 7.1.4
+Version: 7.1.6
 Summary: Open infrastructure for genome writing: the Writable Genome atlas, the Writer Atlas, and the Write Planner.
 Author-email: Anees Ahmed Mahaboob Ali <ahmedaneesm@gmail.com>
 License: MIT

{pen_stack-7.1.4 → pen_stack-7.1.6}/pen_stack/__init__.py

@@ -1,2 +1,2 @@
 """PEN-STACK v3.0 - open infrastructure for genome writing."""
-__version__ = "7.1.4"
+__version__ = "7.1.6"

pen_stack-7.1.6/pen_stack/planner/chromosome.py

@@ -0,0 +1,106 @@
+"""Chromosome validation, gene/chromosome concordance, and chromosome-context advisories (v7.1.5).
+
+The `chrom` field on a design was previously a free-text pass-through with no validation and no downstream
+effect. This module makes it meaningful WITHOUT fabricating a score: the engine's per-locus safety / durability /
+accessibility / off-target numbers are indexed by the GENE's resolved genomic coordinates via the writability
+atlas (`planner.optimize.gene_region`), not by a free-text chromosome string - a bare "chrX" with no position
+cannot index a specific locus value. So the honest, grounded use of the field is:
+
+  * `canonical_chromosome` - validate / normalise to a standard human chromosome (chr1-chr22, chrX, chrY, chrM);
+  * `gene_chromosome` - the gene's canonical chromosome from the gene-coordinate table;
+  * `chromosome_concordance` - flag when the entered chromosome does not match the named gene's real location
+    (the "BRCA1 is on chr17, not chr1" case), making explicit that scoring uses the gene's canonical locus;
+  * `chromosome_context` - chromosome-driven advisories that ARE grounded in biology: chrM is not addressable by
+    nuclear genome-writing tools (mtDNA needs DdCBE/TALED - out of scope), chrY is male-specific with ampliconic
+    repeats, chrX is hemizygous in 46,XY vs X-inactivated in 46,XX.
+"""
+from __future__ import annotations
+
+import re
+
+STANDARD_CHROMOSOMES = [f"chr{i}" for i in range(1, 23)] + ["chrX", "chrY", "chrM"]
+
+
+def canonical_chromosome(chrom: str | None) -> str | None:
+    """Normalise a chromosome string to canonical UCSC form (chr1..chr22, chrX, chrY, chrM), or None if it is not
+    a standard human chromosome. Accepts 'chrX'/'X'/'x', 'chr1'/'1', 'chrM'/'chrMT'/'MT', '23'->X, '24'->Y."""
+    if chrom is None:
+        return None
+    c = re.sub(r"\s+", "", str(chrom)).lower()
+    if not c:
+        return None
+    if c.startswith("chr"):
+        c = c[3:]
+    c = {"mt": "m", "23": "x", "24": "y", "25": "m"}.get(c, c)
+    if c in {"x", "y", "m"}:
+        return "chr" + c.upper()
+    if c.isdigit() and 1 <= int(c) <= 22:
+        return "chr" + c
+    return None
+
+
+def gene_chromosome(gene: str | None) -> str | None:
+    """The canonical chromosome of a gene (or safe-harbour locus nickname), from the gene-coordinate table; None
+    if the gene is unknown."""
+    if not gene:
+        return None
+    try:
+        from pen_stack.planner.optimize import gene_region
+        reg = gene_region(gene)
+    except Exception:  # noqa: BLE001 - coords table absent (bare checkout) -> cannot resolve, do not fabricate
+        return None
+    return canonical_chromosome(reg[0]) if reg else None
+
+
+def chromosome_concordance(gene: str | None, chrom: str | None) -> dict:
+    """Validate the entered chromosome and check it against the named gene's canonical location.
+
+    status is one of:
+      * 'invalid'  - the entered string is not a standard human chromosome;
+      * 'mismatch' - valid, but does not match the gene's canonical chromosome (the silent-mismatch case);
+      * 'match'    - matches the gene's canonical chromosome;
+      * 'unverifiable' - valid chromosome but the gene's location is unknown (cannot confirm);
+      * 'none'     - no chromosome supplied.
+    """
+    entered = canonical_chromosome(chrom)
+    gchrom = gene_chromosome(gene)
+    out = {"entered_raw": chrom, "entered": entered, "valid": entered is not None,
+           "gene": gene, "gene_chrom": gchrom}
+    if chrom in (None, "") or str(chrom).strip() == "":
+        out["status"] = "none"
+        out["message"] = None
+    elif entered is None:
+        out["status"] = "invalid"
+        out["message"] = (f"'{chrom}' is not a standard human chromosome. Use chr1-chr22, chrX, chrY, or chrM.")
+    elif gchrom and entered != gchrom:
+        out["status"] = "mismatch"
+        out["message"] = (f"{gene} is on {gchrom}, not {entered}. Locus scoring uses {gene}'s canonical location "
+                          f"({gchrom}); the entered chromosome does not move the locus.")
+    elif gchrom and entered == gchrom:
+        out["status"] = "match"
+        out["message"] = f"{entered} matches the canonical location of {gene}."
+    else:
+        out["status"] = "unverifiable"
+        out["message"] = (f"{entered} is a valid chromosome, but {gene or 'the gene'} is not in the coordinate "
+                          "table, so the gene/chromosome match cannot be confirmed.")
+    return out
+
+
+def chromosome_context(chrom: str | None) -> dict | None:
+    """A grounded, chromosome-driven advisory (or None for an autosome). These are real biological constraints
+    the chromosome identity alone implies; magnitudes remain locus/subject-dependent (not predicted here)."""
+    c = canonical_chromosome(chrom)
+    if c == "chrM":
+        return {"chrom": "chrM", "severity": "high",
+                "note": ("the mitochondrial genome is NOT addressable by nuclear genome-writing tools "
+                         "(integrases / recombinases / nuclear-targeted Cas9); mtDNA editing requires "
+                         "mitochondrially-targeted base editors (DdCBE / TALED) - out of scope for this tool.")}
+    if c == "chrY":
+        return {"chrom": "chrY", "severity": "medium",
+                "note": ("the Y chromosome is male-specific (absent in 46,XX) and rich in ampliconic / palindromic "
+                         "repeats, so confirm the target is single-copy before trusting a unique-site assumption.")}
+    if c == "chrX":
+        return {"chrom": "chrX", "severity": "low",
+                "note": ("the X chromosome is hemizygous in 46,XY (one copy) but subject to X-inactivation in "
+                         "46,XX (mosaic expression); dosage and durability are sex- and locus-dependent.")}
+    return None

{pen_stack-7.1.4 → pen_stack-7.1.6}/pen_stack/planner/immune_profile.py

@@ -53,6 +53,34 @@ _SCORE_KEY = {"genotoxicity": "genotox_score", "cd8_epitope": "capsid_immune_sco
               "innate": "innate_score", "preexisting_nab": "preexisting_score",
               "anti_peg": "preexisting_antipeg_score"}
 
+# Canonical cargo nucleic-acid FORM per delivery vehicle, used to drive the innate-sensing pathway (DNA -> TLR9
+# CpG; mRNA -> TLR7/8 + RIG-I/MDA5; RNP -> transient) when a design does not state ``cargo_form`` explicitly.
+# This is the vehicle's defining cargo class, NOT a fabricated quantity: an LNP-mRNA vehicle delivers mRNA, a
+# DNA-virus / electroporated-plasmid vehicle delivers DNA, an (e)VLP delivers a transient ribonucleoprotein. A
+# lentivirus is packaged as RNA but the persistent, innate-relevant cassette is the integrated proviral DNA.
+# An unknown vehicle returns None so the innate axis ABSTAINS rather than guesses a form.
+_VEHICLE_CARGO_FORM = {
+    "lnp_mrna": "mRNA",
+    "aav_single": "DNA", "aav_dual": "DNA", "lentivirus": "DNA",
+    "helper_dependent_adenovirus": "DNA", "hsv_amplicon": "DNA", "electroporation": "DNA",
+    "evlp": "RNP", "vlp": "RNP",
+}
+
+
+def _vehicle_cargo_form(vehicle: str | None) -> str | None:
+    """Derive the cargo nucleic-acid form (DNA / mRNA / RNP) from the delivery vehicle, or None when unknown.
+    Used only when the design does not supply ``cargo_form`` / ``writer_output_form`` explicitly."""
+    if not vehicle:
+        return None
+    v = str(vehicle).strip().lower()
+    if v in _VEHICLE_CARGO_FORM:
+        return _VEHICLE_CARGO_FORM[v]
+    if "mrna" in v or "lnp" in v:
+        return "mRNA"
+    if "vlp" in v:
+        return "RNP"
+    return None
+
 
 def _axis(result, axis: str) -> dict:
     """One axis record: value (headline score or None when abstaining) + native uncertainty + scope + the
@@ -108,7 +136,11 @@ def immune_profile(design: dict) -> dict:
     veh = design.get("delivery_vehicle") or design.get("vehicle")
     sero = design.get("serotype")
     cargo_seq = design.get("cargo_seq") or ""
-    form = design.get("writer_output_form") or design.get("cargo_form") or ""
+    # cargo form: honour an explicit design field, else derive it from the vehicle's defining cargo class so the
+    # innate axis computes for any caller (chat / MCP / REST) once a cargo sequence is supplied. Still abstains
+    # with no sequence and for an unknown vehicle (form None) - never fabricates.
+    form = (design.get("writer_output_form") or design.get("cargo_form")
+            or _vehicle_cargo_form(veh) or "")
     peg = design.get("pegylated")
 
     capsid_cd8 = capsid_epitope_oracle(veh)

{pen_stack-7.1.4 → pen_stack-7.1.6}/pen_stack/server/api.py

@@ -119,6 +119,23 @@ def crosslink_loci(request: Request, family: str, ct: str = "k562", cell_type: s
     return {"family": family, "ct": ct, "loci": _records(loci), "disclaimer": _DISCLAIMER}
 
 
+@app.get("/gene/location")
+def gene_location(gene: str):
+    """v7.1.5: the canonical chromosome of a gene (or safe-harbour locus nickname), for the UI's gene/chromosome
+    concordance check. found=False when the gene is not in the coordinate table (no fabrication)."""
+    from pen_stack.planner.chromosome import canonical_chromosome
+    from pen_stack.planner.optimize import gene_region, resolve_gene
+    try:
+        reg = gene_region(gene)
+    except Exception:  # noqa: BLE001 - coords table absent -> cannot resolve
+        reg = None
+    resolved = resolve_gene(gene)
+    if reg is None:
+        return {"gene": gene, "resolved": resolved, "found": False, "chrom": None}
+    return {"gene": gene, "resolved": resolved, "found": True, "chrom": canonical_chromosome(reg[0]),
+            "start": int(reg[1]), "end": int(reg[2])}
+
+
 @app.get("/writable")
 def writable(request: Request, gene: str, ct: str = "k562", cell_type: str | None = None,
              top: int = Query(20, le=200)):

{pen_stack-7.1.4 → pen_stack-7.1.6}/pen_stack/verify/service.py

@@ -98,6 +98,18 @@ def verify(design: Design | dict, question: str | None = None, *, actor: str = "
                   for r in results if r["kind"] == "scope_flag" and r["status"] == "scope"]
     scope_flags += rule_scope
 
+    # v7.1.5: chromosome validation + gene/chromosome concordance + chromosome-context advisory. The free-text
+    # chrom field does not move the scored locus (scoring is indexed by the gene's resolved coordinates), so a
+    # mismatch / invalid value / chromosome-context note is surfaced as a scope flag, never silently ignored.
+    from pen_stack.planner.chromosome import chromosome_concordance, chromosome_context
+    conc = chromosome_concordance(design.gene, getattr(design, "chrom", None))
+    if conc["status"] in ("invalid", "mismatch", "unverifiable"):
+        scope_flags.append({"kind": f"chromosome_{conc['status']}", "reason": conc["message"],
+                            "entered": conc["entered"], "gene_chrom": conc["gene_chrom"]})
+    ctx = chromosome_context(getattr(design, "chrom", None))
+    if ctx:
+        scope_flags.append({"kind": "chromosome_context", "chrom": ctx["chrom"], "reason": ctx["note"]})
+
     pc = _plan_confidence(design)
     verdict = classify(grounded=True, confidence=pc["confidence"], out_of_scope=oos_hit)
 

{pen_stack-7.1.4 → pen_stack-7.1.6}/pen_stack.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pen-stack
-Version: 7.1.4
+Version: 7.1.6
 Summary: Open infrastructure for genome writing: the Writable Genome atlas, the Writer Atlas, and the Write Planner.
 Author-email: Anees Ahmed Mahaboob Ali <ahmedaneesm@gmail.com>
 License: MIT

{pen_stack-7.1.4 → pen_stack-7.1.6}/pen_stack.egg-info/SOURCES.txt

@@ -252,6 +252,7 @@ pen_stack/planner/antipeg_oracle.py
 pen_stack/planner/capsid_epitope_oracle.py
 pen_stack/planner/cargo.py
 pen_stack/planner/cargo_polish.py
+pen_stack/planner/chromosome.py
 pen_stack/planner/delivery.py
 pen_stack/planner/delivery_constraints.py
 pen_stack/planner/delivery_immune.py

{pen_stack-7.1.4 → pen_stack-7.1.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pen-stack"
-version = "7.1.4"
+version = "7.1.6"
 description = "Open infrastructure for genome writing: the Writable Genome atlas, the Writer Atlas, and the Write Planner."
 readme = "README.md"
 requires-python = ">=3.11"