Add liability/QC, cluster & tree, and experiment tracking

Dockerfile

@@ -29,9 +29,7 @@ COPY . .
 ENV PORT=5007 \
     HOST=0.0.0.0
 
-# Hugging Face Spaces runs the container as UID 1000 (non-root). Point HOME and
-# library cache dirs at /tmp (world-writable) so Panel/Bokeh/matplotlib can
-# write caches without permission errors.
+# Hugging Face Spaces runs as UID 1000 (non-root); point caches at /tmp
 ENV HOME=/tmp \
     XDG_CACHE_HOME=/tmp/.cache \
     MPLCONFIGDIR=/tmp/matplotlib \

core/analysis/analyzer.py

@@ -27,6 +27,9 @@ from core.analysis.restriction_sites import (
 )
 from core.analysis.kozak import check_kozak, KozakResult
 from core.analysis.structure import predict_structure, StructureResult
+from core.analysis.uridine import analyze_uridine, UridineReport
+from core.analysis.motifs import scan_motifs, MotifHit
+from core.analysis.liability import assess_liabilities, LiabilityReport
 
 
 @dataclass
@@ -68,6 +71,15 @@ class AnalysisReport:
     # Secondary structure (ViennaRNA)
     structure: Optional[StructureResult] = None
 
+    # Uridine content (immunogenicity proxy)
+    uridine: Optional[UridineReport] = None
+
+    # Sequence-liability motifs (uORF, premature polyA, ARE, splice donor)
+    motif_hits: List[MotifHit] = field(default_factory=list)
+
+    # Aggregated liability / QC assessment
+    liability: Optional[LiabilityReport] = None
+
     # Errors / warnings generated during analysis
     warnings: List[str] = field(default_factory=list)
 
@@ -92,6 +104,12 @@ class AnalysisReport:
             "kozak_score": self.kozak.score if self.kozak else None,
             "kozak_strength": self.kozak.strength if self.kozak else None,
             "mfe": self.structure.mfe if self.structure else None,
+            "uridine_percent": self.uridine.u_percent if self.uridine else None,
+            "liability_score": self.liability.score if self.liability else None,
+            "liability_verdict": self.liability.verdict if self.liability else None,
+            "liability_critical": self.liability.n_critical if self.liability else None,
+            "liability_warning": self.liability.n_warning if self.liability else None,
+            "liability_flag_count": self.liability.flag_count if self.liability else None,
             "warnings": self.warnings,
         }
 
@@ -269,8 +287,22 @@ class SequenceAnalyzer:
             struct_data = self.analyze_structure(full_seq)
             report.structure = struct_data["structure"]
 
+        # Uridine content (immunogenicity proxy)
+        report.uridine = analyze_uridine(full_seq)
+
+        # Sequence-liability motifs (region-aware when components are available)
+        report.motif_hits = scan_motifs(
+            five_prime_utr=seq.five_prime_utr,
+            cds=seq.cds,
+            three_prime_utr=seq.three_prime_utr,
+            full_seq=full_seq,
+        )
+
         report.warnings = warnings
 
+        # Aggregate everything into the liability / QC assessment
+        report.liability = assess_liabilities(report, seq)
+
         # Cache result
         seq._analysis_cache[cache_key] = report
         return report

core/analysis/clustering.py

@@ -0,0 +1,201 @@
+"""
+Sequence clustering and tree building for worklist exploration.
+
+Provides a lightweight, dependency-light pipeline (numpy only) analogous to an
+immune-repertoire clustering view:
+
+  1. ``kmer_distance_matrix`` — k-mer cosine distance between sequences.
+  2. ``upgma`` — average-linkage hierarchical clustering → a SciPy-style
+     ``linkage`` array plus a leaf ordering for plotting a dendrogram.
+  3. ``flat_clusters`` — cut the tree at a distance threshold into flat clusters.
+
+Everything works on raw nucleotide strings; no alignment required.
+"""
+from __future__ import annotations
+
+from collections import Counter
+from dataclasses import dataclass, field
+from typing import Dict, List, Tuple
+
+import numpy as np
+
+
+def kmer_counts(seq: str, k: int = 4) -> Counter:
+    """Count k-mers in a sequence (DNA alphabet, U→T)."""
+    s = (seq or "").upper().replace("U", "T")
+    if len(s) < k:
+        return Counter()
+    return Counter(s[i:i + k] for i in range(len(s) - k + 1))
+
+
+def _cosine_distance(a: Counter, b: Counter) -> float:
+    """1 - cosine similarity between two k-mer count vectors."""
+    if not a or not b:
+        return 1.0
+    # dot product over shared keys
+    shared = set(a) & set(b)
+    dot = sum(a[k] * b[k] for k in shared)
+    na = np.sqrt(sum(v * v for v in a.values()))
+    nb = np.sqrt(sum(v * v for v in b.values()))
+    if na == 0 or nb == 0:
+        return 1.0
+    cos = dot / (na * nb)
+    return float(max(0.0, 1.0 - cos))
+
+
+def kmer_distance_matrix(sequences: List[str], k: int = 4) -> np.ndarray:
+    """Symmetric pairwise k-mer cosine distance matrix (n×n)."""
+    vecs = [kmer_counts(s, k) for s in sequences]
+    n = len(vecs)
+    d = np.zeros((n, n), dtype=float)
+    for i in range(n):
+        for j in range(i + 1, n):
+            dist = _cosine_distance(vecs[i], vecs[j])
+            d[i, j] = d[j, i] = dist
+    return d
+
+
+def upgma(dist: np.ndarray) -> Tuple[np.ndarray, List[int]]:
+    """
+    Average-linkage (UPGMA) hierarchical clustering.
+
+    Parameters
+    ----------
+    dist : np.ndarray
+        Square symmetric distance matrix (n×n).
+
+    Returns
+    -------
+    linkage : np.ndarray
+        SciPy-style (n-1)×4 array: each row [id_a, id_b, height, size].
+        Leaf ids are 0..n-1; internal nodes get ids n, n+1, …
+    leaf_order : list[int]
+        Left-to-right leaf ordering for plotting a non-crossing dendrogram.
+    """
+    n = dist.shape[0]
+    if n < 2:
+        return np.empty((0, 4)), list(range(n))
+
+    # active clusters: id -> (members, size). distances kept in a dict.
+    sizes: Dict[int, int] = {i: 1 for i in range(n)}
+    members: Dict[int, List[int]] = {i: [i] for i in range(n)}
+    active = list(range(n))
+    D: Dict[Tuple[int, int], float] = {}
+    for i in range(n):
+        for j in range(i + 1, n):
+            D[(i, j)] = dist[i, j]
+
+    def key(a: int, b: int) -> Tuple[int, int]:
+        return (a, b) if a < b else (b, a)
+
+    linkage = []
+    next_id = n
+    while len(active) > 1:
+        # find closest pair
+        best = None
+        best_pair = None
+        for ai in range(len(active)):
+            for bi in range(ai + 1, len(active)):
+                a, b = active[ai], active[bi]
+                dval = D[key(a, b)]
+                if best is None or dval < best:
+                    best = dval
+                    best_pair = (a, b)
+        a, b = best_pair
+        new = next_id
+        next_id += 1
+        sa, sb = sizes[a], sizes[b]
+        members[new] = members[a] + members[b]
+        sizes[new] = sa + sb
+        linkage.append([float(a), float(b), float(best), float(sizes[new])])
+
+        # update distances (average linkage weighted by size)
+        for c in active:
+            if c in (a, b):
+                continue
+            dac = D[key(a, c)]
+            dbc = D[key(b, c)]
+            D[key(new, c)] = (sa * dac + sb * dbc) / (sa + sb)
+        active.remove(a)
+        active.remove(b)
+        active.append(new)
+
+    # leaf order from the merge tree (recursive, left then right)
+    def leaves_of(node: int) -> List[int]:
+        return members[node]
+
+    root = active[0]
+    leaf_order = leaves_of(root)
+    return np.array(linkage, dtype=float), leaf_order
+
+
+def flat_clusters(linkage: np.ndarray, n_leaves: int, threshold: float) -> List[int]:
+    """
+    Cut the dendrogram at ``threshold``: merge nodes joined below the threshold,
+    returning a cluster id (0-based, contiguous) per original leaf.
+    """
+    if n_leaves == 0:
+        return []
+    parent = list(range(n_leaves + len(linkage)))
+
+    def find(x: int) -> int:
+        while parent[x] != x:
+            parent[x] = parent[parent[x]]
+            x = parent[x]
+        return x
+
+    def union(x: int, y: int) -> None:
+        parent[find(x)] = find(y)
+
+    for i, row in enumerate(linkage):
+        a, b, height = int(row[0]), int(row[1]), row[2]
+        new = n_leaves + i
+        if height <= threshold:
+            union(a, new)
+            union(b, new)
+
+    # map each leaf's root to a contiguous cluster id
+    roots = [find(i) for i in range(n_leaves)]
+    remap: Dict[int, int] = {}
+    out = []
+    for r in roots:
+        if r not in remap:
+            remap[r] = len(remap)
+        out.append(remap[r])
+    return out
+
+
+@dataclass
+class DendrogramLayout:
+    """Coordinates for drawing a dendrogram."""
+    leaf_order: List[int] = field(default_factory=list)
+    leaf_x: Dict[int, float] = field(default_factory=dict)   # leaf id -> x
+    # each link: (x0, x1, y0, y1) segments forming the bracket
+    segments: List[Tuple[float, float, float, float]] = field(default_factory=list)
+    node_x: Dict[int, float] = field(default_factory=dict)
+    node_y: Dict[int, float] = field(default_factory=dict)
+
+
+def dendrogram_layout(linkage: np.ndarray, leaf_order: List[int]) -> DendrogramLayout:
+    """Compute x/y coordinates + bracket segments for a horizontal-leaf dendrogram."""
+    layout = DendrogramLayout(leaf_order=list(leaf_order))
+    n = len(leaf_order)
+    # leaves on the x-axis at integer positions, y=0
+    for pos, leaf in enumerate(leaf_order):
+        layout.leaf_x[leaf] = float(pos)
+        layout.node_x[leaf] = float(pos)
+        layout.node_y[leaf] = 0.0
+
+    for i, row in enumerate(linkage):
+        a, b, height = int(row[0]), int(row[1]), float(row[2])
+        new = n + i
+        xa, xb = layout.node_x[a], layout.node_x[b]
+        ya, yb = layout.node_y[a], layout.node_y[b]
+        xnew = (xa + xb) / 2.0
+        layout.node_x[new] = xnew
+        layout.node_y[new] = height
+        # bracket: up from a, across at height, down to b
+        layout.segments.append((xa, xa, ya, height))   # left vertical
+        layout.segments.append((xb, xb, yb, height))   # right vertical
+        layout.segments.append((xa, xb, height, height))  # horizontal top
+    return layout

core/analysis/liability.py

@@ -0,0 +1,237 @@
+"""
+Liability / QC aggregator.
+
+Rolls the individual analysis results (GC, homopolymers, restriction sites,
+uridine, CDS validation, Kozak, secondary structure, sequence motifs) into a
+single severity-ranked liability report with an overall QC score (0–100) and a
+pass / review / fail verdict — analogous to a developability/liability overlay.
+
+This module is a pure aggregator: it reads attributes off an already-computed
+analysis report (duck-typed) and the sequence object, so it imports neither the
+analyzer nor the Panel UI. It only depends on the homopolymer detector (to
+re-scan the construct *body*, excluding the legitimate poly-A tail).
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, List, Optional
+
+from core.analysis.homopolymers import detect_homopolymers
+
+# Severity levels, ordered most→least severe
+CRITICAL = "critical"
+WARNING = "warning"
+INFO = "info"
+
+_SEVERITY_ORDER = {CRITICAL: 0, WARNING: 1, INFO: 2}
+_PENALTY = {CRITICAL: 25, WARNING: 10, INFO: 3}
+
+# Thresholds
+_GC_LOW, _GC_HIGH = 40.0, 65.0          # warning band
+_GC_LOW_CRIT, _GC_HIGH_CRIT = 30.0, 70.0  # critical band
+_HOMOPOLYMER_WARN = 10                    # body run length → warning
+_HOMOPOLYMER_CRIT = 15                    # body run length → critical
+_URIDINE_WARN_PCT = 40.0
+_MFE_PER_NT_INFO = -0.45                  # very negative → highly structured
+
+
+@dataclass
+class LiabilityFlag:
+    """A single liability finding."""
+    id: str
+    category: str          # "GC", "Homopolymer", "Restriction", "Uridine",
+                           # "CDS", "Kozak", "Structure", "Motif"
+    severity: str          # CRITICAL | WARNING | INFO
+    title: str
+    detail: str
+    location: str = ""     # human-readable location, e.g. "CDS pos 123"
+    recommendation: str = ""
+
+
+@dataclass
+class LiabilityReport:
+    """Aggregated liability assessment for one sequence."""
+    flags: List[LiabilityFlag] = field(default_factory=list)
+    score: int = 100              # 0–100, higher is cleaner
+    verdict: str = "pass"         # "pass" | "review" | "fail"
+    n_critical: int = 0
+    n_warning: int = 0
+    n_info: int = 0
+    checks_run: int = 0
+
+    @property
+    def flag_count(self) -> int:
+        return len(self.flags)
+
+    def sorted_flags(self) -> List[LiabilityFlag]:
+        return sorted(self.flags, key=lambda f: _SEVERITY_ORDER.get(f.severity, 9))
+
+
+def _body_sequence(seq: Any) -> str:
+    """Construct body = everything except the legitimate poly-A tail."""
+    parts = [
+        getattr(seq, "five_prime_utr", None),
+        getattr(seq, "kozak", None),
+        getattr(seq, "cds", None),
+        getattr(seq, "three_prime_utr", None),
+    ]
+    return "".join(p for p in parts if p).upper().replace("U", "T")
+
+
+def assess_liabilities(report: Any, seq: Any) -> LiabilityReport:
+    """
+    Build a LiabilityReport from an analysis ``report`` and its ``seq``.
+
+    ``report`` is duck-typed: it is expected to expose the attributes set by
+    SequenceAnalyzer (gc_percent_global, restriction_enzymes_present, uridine,
+    has_start_codon/has_stop_codon/in_frame, kozak, structure, motif_hits).
+    """
+    flags: List[LiabilityFlag] = []
+    checks = 0
+
+    def add(category, severity, title, detail, location="", recommendation=""):
+        flags.append(LiabilityFlag(
+            id=f"{category.lower()}-{len(flags)}",
+            category=category, severity=severity, title=title,
+            detail=detail, location=location, recommendation=recommendation,
+        ))
+
+    # ── GC content ────────────────────────────────────────────────────────────
+    checks += 1
+    gc = getattr(report, "gc_percent_global", None)
+    if gc is not None and gc > 0:
+        if gc < _GC_LOW_CRIT or gc > _GC_HIGH_CRIT:
+            add("GC", CRITICAL, "GC content far outside optimal range",
+                f"Global GC is {gc:.1f}% (optimal {_GC_LOW:.0f}–{_GC_HIGH:.0f}%).",
+                "global",
+                "Re-balance GC; extremes hurt synthesis, translation, and stability.")
+        elif gc < _GC_LOW or gc > _GC_HIGH:
+            add("GC", WARNING, "GC content outside optimal range",
+                f"Global GC is {gc:.1f}% (optimal {_GC_LOW:.0f}–{_GC_HIGH:.0f}%).",
+                "global",
+                "Nudge GC toward 40–65% during codon optimisation.")
+
+    # ── Homopolymers in the body (exclude poly-A tail) ────────────────────────
+    checks += 1
+    body = _body_sequence(seq)
+    if body:
+        body_runs = detect_homopolymers(body, min_run=_HOMOPOLYMER_WARN)
+        if body_runs:
+            longest = max(body_runs, key=lambda r: r.length)
+            sev = CRITICAL if longest.length >= _HOMOPOLYMER_CRIT else WARNING
+            add("Homopolymer", sev, "Homopolymer run in construct body",
+                f"{len(body_runs)} run(s) ≥{_HOMOPOLYMER_WARN} nt; longest "
+                f"{longest.nucleotide}×{longest.length}.",
+                f"body pos {longest.start}",
+                "Break up long single-base runs to avoid synthesis errors and "
+                "polymerase slippage.")
+
+    # ── Restriction sites ─────────────────────────────────────────────────────
+    checks += 1
+    enzymes = getattr(report, "restriction_enzymes_present", None) or []
+    if enzymes:
+        add("Restriction", WARNING, "Internal restriction sites present",
+            f"Sites for: {', '.join(sorted(enzymes))}.",
+            "construct",
+            "Remove internal sites or pick a cloning strategy that avoids them.")
+
+    # ── Uridine content / high-U stretches ────────────────────────────────────
+    checks += 1
+    uri = getattr(report, "uridine", None)
+    if uri is not None:
+        stretches = getattr(uri, "high_u_stretches", []) or []
+        u_pct = getattr(uri, "u_percent", 0.0)
+        if u_pct >= _URIDINE_WARN_PCT or stretches:
+            detail = f"Uridine {u_pct:.1f}%"
+            if stretches:
+                detail += f"; {len(stretches)} high-U stretch(es)"
+            add("Uridine", WARNING, "Elevated uridine content",
+                detail + ".",
+                "construct",
+                "High U is immunostimulatory — optimise sequence and/or use "
+                "modified nucleotides (e.g. N1-methylpseudouridine).")
+
+    # ── CDS integrity ─────────────────────────────────────────────────────────
+    if getattr(report, "has_start_codon", None) is not None:
+        checks += 1
+        if report.has_start_codon is False:
+            add("CDS", CRITICAL, "CDS missing start codon",
+                "CDS does not begin with ATG.", "CDS 5' end",
+                "Ensure the CDS starts with ATG.")
+        if getattr(report, "has_stop_codon", None) is False:
+            add("CDS", CRITICAL, "CDS missing stop codon",
+                "CDS does not end with a stop codon.", "CDS 3' end",
+                "Append a stop codon (TAA/TAG/TGA).")
+        if getattr(report, "in_frame", None) is False:
+            add("CDS", CRITICAL, "CDS not in frame",
+                "CDS length is not divisible by 3.", "CDS",
+                "Fix indels so the CDS length is a multiple of 3.")
+
+    # ── Kozak context ─────────────────────────────────────────────────────────
+    kz = getattr(report, "kozak", None)
+    if kz is not None:
+        checks += 1
+        strength = getattr(kz, "strength", None)
+        if strength == "weak":
+            add("Kozak", WARNING, "Weak Kozak context",
+                f"Kozak score {getattr(kz, 'score', 0):.2f} (weak).",
+                "around start codon",
+                "Strengthen Kozak: purine (A/G) at -3 and G at +4.")
+        elif strength == "adequate":
+            add("Kozak", INFO, "Sub-optimal Kozak context",
+                f"Kozak score {getattr(kz, 'score', 0):.2f} (adequate).",
+                "around start codon",
+                "Optional: optimise -3/+4 positions for stronger initiation.")
+
+    # ── Secondary structure (if computed) ─────────────────────────────────────
+    struct = getattr(report, "structure", None)
+    if struct is not None and not getattr(struct, "is_stub", True):
+        checks += 1
+        length = max(len(getattr(struct, "sequence", "") or ""), 1)
+        per_nt = getattr(struct, "mfe", 0.0) / length
+        if per_nt < _MFE_PER_NT_INFO:
+            add("Structure", INFO, "Highly structured mRNA",
+                f"MFE {struct.mfe:.1f} kcal/mol ({per_nt:.2f}/nt).",
+                "global",
+                "Strong structure (esp. near the 5' cap/start) can impede "
+                "translation initiation.")
+
+    # ── Sequence motifs ───────────────────────────────────────────────────────
+    motif_hits = getattr(report, "motif_hits", None) or []
+    if motif_hits:
+        checks += 1
+        # group by motif name
+        by_name: dict = {}
+        for h in motif_hits:
+            by_name.setdefault(h.name, []).append(h)
+        for name, group in by_name.items():
+            first = group[0]
+            sev = min((h.severity for h in group), key=lambda s: _SEVERITY_ORDER.get(s, 9))
+            positions = ", ".join(f"{h.region}:{h.start}" for h in group[:5])
+            if len(group) > 5:
+                positions += f" (+{len(group) - 5} more)"
+            add("Motif", sev, first.label,
+                f"{len(group)} occurrence(s). {first.description}",
+                positions,
+                first.recommendation)
+
+    # ── Score & verdict ───────────────────────────────────────────────────────
+    n_crit = sum(1 for f in flags if f.severity == CRITICAL)
+    n_warn = sum(1 for f in flags if f.severity == WARNING)
+    n_info = sum(1 for f in flags if f.severity == INFO)
+
+    penalty = sum(_PENALTY.get(f.severity, 0) for f in flags)
+    score = max(0, min(100, 100 - penalty))
+
+    if n_crit > 0:
+        verdict = "fail"
+    elif n_warn > 0:
+        verdict = "review"
+    else:
+        verdict = "pass"
+
+    return LiabilityReport(
+        flags=flags, score=score, verdict=verdict,
+        n_critical=n_crit, n_warning=n_warn, n_info=n_info,
+        checks_run=checks,
+    )

core/analysis/motifs.py

@@ -0,0 +1,133 @@
+"""
+Sequence-liability motif scanning for mRNA constructs.
+
+Scans the functional regions of an mRNA for short sequence motifs that are
+known to compromise expression, stability, or processing:
+
+  - **uORF start (upstream AUG)** in the 5'UTR — can initiate an upstream
+    open reading frame and reduce translation of the main CDS.
+  - **Premature polyadenylation signal** (AAUAAA / AUUAAA) inside the CDS —
+    can cause truncated transcripts.
+  - **AU-rich element (ARE, AUUUA)** in the 3'UTR — recruits decay machinery
+    and shortens mRNA half-life.
+  - **Cryptic 5' splice-donor consensus** (GT[AG]AGT) anywhere — risk of
+    aberrant splicing when transcribed from a DNA template.
+
+All scanning is done on DNA alphabet (T, not U); inputs are normalised.
+Severities are plain strings ("critical" / "warning" / "info") so this module
+stays free of any dependency on the liability aggregator.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import List, Optional
+
+# Severity labels (kept as bare strings to avoid import cycles)
+CRITICAL = "critical"
+WARNING = "warning"
+INFO = "info"
+
+# Cap per-motif hits so a pathological sequence can't produce thousands of rows
+_MAX_HITS_PER_MOTIF = 50
+
+
+@dataclass
+class MotifHit:
+    """A single sequence-liability motif occurrence."""
+    name: str            # machine name, e.g. "uorf"
+    label: str           # human label, e.g. "Upstream AUG (uORF)"
+    region: str          # "5'UTR" | "CDS" | "3'UTR" | "full"
+    start: int           # 0-based start within the scanned region
+    end: int             # exclusive end within the region
+    match: str           # the matched subsequence (DNA alphabet)
+    severity: str        # CRITICAL | WARNING | INFO
+    description: str     # why it matters
+    recommendation: str  # what to do about it
+
+    def __repr__(self) -> str:
+        return f"MotifHit({self.name} {self.region}@{self.start} {self.match!r})"
+
+
+def _norm(seq: Optional[str]) -> str:
+    return (seq or "").upper().replace("U", "T")
+
+
+def _find_all(pattern: str, seq: str) -> List[re.Match]:
+    """Find non-overlapping regex matches, capped."""
+    return list(re.finditer(pattern, seq))[:_MAX_HITS_PER_MOTIF]
+
+
+def scan_motifs(
+    five_prime_utr: Optional[str] = None,
+    cds: Optional[str] = None,
+    three_prime_utr: Optional[str] = None,
+    full_seq: Optional[str] = None,
+) -> List[MotifHit]:
+    """
+    Scan an mRNA's regions for liability motifs.
+
+    Pass the individual components when available. ``full_seq`` is used for
+    region-agnostic scans (splice donor) and as a fallback when components
+    are not provided (e.g. a monolithic ``full_mrna`` record).
+    """
+    hits: List[MotifHit] = []
+
+    utr5 = _norm(five_prime_utr)
+    cds_s = _norm(cds)
+    utr3 = _norm(three_prime_utr)
+    full = _norm(full_seq) or (utr5 + cds_s + utr3)
+
+    # ── uORF: any ATG in the 5'UTR ────────────────────────────────────────────
+    for m in _find_all("ATG", utr5):
+        hits.append(MotifHit(
+            name="uorf",
+            label="Upstream AUG (uORF)",
+            region="5'UTR",
+            start=m.start(), end=m.end(), match=m.group(),
+            severity=WARNING,
+            description="An AUG in the 5'UTR can start an upstream ORF and "
+                        "reduce ribosome loading on the main CDS.",
+            recommendation="Remove or silently mutate upstream AUGs in the 5'UTR.",
+        ))
+
+    # ── Premature polyadenylation signal inside the CDS ───────────────────────
+    for m in _find_all("AATAAA|ATTAAA", cds_s):
+        hits.append(MotifHit(
+            name="premature_polya",
+            label="Premature polyA signal",
+            region="CDS",
+            start=m.start(), end=m.end(), match=m.group(),
+            severity=CRITICAL,
+            description="A canonical polyadenylation signal inside the CDS can "
+                        "cause premature cleavage and a truncated protein.",
+            recommendation="Codon-optimise to remove the internal AAUAAA/AUUAAA signal.",
+        ))
+
+    # ── AU-rich element (ARE) in the 3'UTR ────────────────────────────────────
+    for m in _find_all("ATTTA", utr3):
+        hits.append(MotifHit(
+            name="are",
+            label="AU-rich element (ARE)",
+            region="3'UTR",
+            start=m.start(), end=m.end(), match=m.group(),
+            severity=WARNING,
+            description="AUUUA pentamers recruit mRNA-decay machinery and shorten "
+                        "transcript half-life.",
+            recommendation="Remove ARE motifs from the 3'UTR to improve stability.",
+        ))
+
+    # ── Cryptic 5' splice-donor consensus (region-agnostic) ───────────────────
+    for m in _find_all("GT[AG]AGT", full):
+        hits.append(MotifHit(
+            name="splice_donor",
+            label="Cryptic splice donor",
+            region="full",
+            start=m.start(), end=m.end(), match=m.group(),
+            severity=INFO,
+            description="Matches the 5' splice-donor consensus; may cause aberrant "
+                        "splicing if transcribed from a DNA template in cells.",
+            recommendation="Consider disrupting the GU[A/G]AGU consensus if splicing is a concern.",
+        ))
+
+    return hits

demo/DEMO_SCRIPT.md

@@ -0,0 +1,54 @@
+# mRNA Design Studio — Demo Script (one page)
+
+**Live app:** https://offtargeteffect-mrna-design-studio.hf.space
+**Login:** username `admin` · password `vOAMljsXrzCemLZK4A38` *(or remove the password for a smoother live demo — see Prep)*
+**Open in its own browser tab** — not the Hugging Face embedded preview (that loops on login).
+
+---
+
+## Prep (do 5 min before)
+- [ ] Visit the URL to **wake the Space** (free tier sleeps; first load is slow).
+- [ ] Have the sample file ready to drag in: `demo/demo_sequences_extended.csv` (14 constructs).
+- [ ] *(Optional)* For the live database demo, have the Postgres connection details on a sticky note.
+- [ ] *(Optional)* Remove the login: Space → Settings → secrets → delete `MRNA_STUDIO_PASSWORD` → app opens with no login.
+
+---
+
+## The story — follow the sidebar top to bottom (~8–10 min)
+
+**1. Import Data  (90s)** — "It ingests real-world sequence tables and structures them automatically."
+- Drag `demo/demo_sequences_extended.csv` onto the CSV uploader.
+- Show the **auto-suggested column mapping** (gene_name, cds, UTRs, …).
+- Click **Import Records** → 14 sequences land in the Worklist.
+- *Or* demo the **PostgreSQL** path: pick PostgreSQL, paste the connection details, Connect → select `mrna_sequences` → Preview → Import.
+
+**2. Worklist → Analyze  (2 min)** — "Instant QC across the whole panel."
+- Select all → **Analyze**.
+- Point out **GC%**, **CAI** (codon adaptation), **homopolymer** runs (the poly-A tails!), **restriction sites**.
+- Note the contrast: component-based vs monolithic records both analyze cleanly.
+
+**3. Model Repository  (1 min)** — "Pluggable scoring — local models or remote APIs."
+- Show the two built-in scorers: **mRNA Stability Scorer** and **RNA Structure Scorer**.
+- Mention you can register a remote API endpoint too.
+
+**4. Worklist → Score & Export  (2 min)** — "Rank candidates, hand off to the lab."
+- Back on the Worklist, **Score** with a loaded model → **sort by score**.
+- **Export CSV** of the ranked panel.
+
+**5. Parts Workshop  (1 min)** — "A reusable parts library."
+- Browse 5'UTR / Kozak / CDS / 3'UTR / poly-A parts; compose a construct.
+
+**6. Assemble Plasmid → Generate Sequences  (2 min)** — "Close the loop."
+- Pick the **pUC19-MCS** backbone, run **QC**, export the assembled construct.
+- In **Generate Sequences**, produce a codon-optimized variant.
+
+---
+
+## If you have only 3 minutes
+Import `demo/demo_sequences_extended.csv` → **Analyze** → **Score** → **Export.**
+That's the whole value: ingest → analyze → score → export.
+
+## Likely questions
+- *"Where does the data live?"* → CSV/Excel upload or a PostgreSQL connection you provide.
+- *"Can I use my own models?"* → Yes — register a local Python model or a remote API endpoint.
+- *"Is it hosted?"* → Runs on Hugging Face Spaces (Docker); also runs locally with `make run`.

demo/ENPICOM_gap_analysis.md

@@ -0,0 +1,30 @@
+# mRNA Design Studio vs. ENPICOM IGX — gap analysis & roadmap
+
+## Positioning (one line)
+ENPICOM = **discover & de-risk** candidates from massive sequenced repertoires (antibodies/TCRs).
+mRNA Design Studio = **design, build & QC** chosen sequences for expression (mRNA).
+Same philosophy (no-code, data + AI for bench scientists); different pipeline stage and scale.
+
+## Shared backbone (already have)
+Import data + metadata · pluggable ML scoring · sequence analysis · candidate select/export · code-free UI.
+
+## What would make us a closer antibody-discovery analog
+
+### Quick wins (weeks)
+1. **Sequence clustering** — group by similarity (CDS/UTR family for mRNA; CDR3/V-gene for Ab). Mirrors IGX-Cluster; biggest "explore" gap.
+2. **Richer liability/QC panel** — extend current QC (restriction sites, homopolymers) into a flagged "liability" view: immunogenic motifs, GC extremes, secondary-structure hotspots. Mirrors IGX-Annotate (shallow version).
+3. **Bulk / large-table ingestion** — FASTA/FASTQ import + dedup so we handle thousands, not dozens.
+
+### Medium bets (1–2 quarters)
+4. **Tree / cluster visualization** for candidate prioritization (phylogenetic-style for Ab; family/variant tree for mRNA). Mirrors IGX-Branch.
+5. **Model lifecycle, not just a registry** — add training, versioning, and experiment tracking (we currently only *call* registered models). Mirrors ENPICOM's AI/MLOps layer.
+6. **Projects + collaboration** — multi-user workspaces, metadata lineage, audit trail. We already have Postgres + auth as a foundation.
+
+### Bigger bets (strategic)
+7. **NGS repertoire scale** — millions of reads, server-side processing. This is ENPICOM's core moat and the largest gap.
+8. **Structure-based developability** — fold/structure models for surface-liability prediction (the antibody-specific heavy lift).
+9. **Round/enrichment tracking** — compare selection/panning rounds over time.
+
+## Honest take
+Closing items 1–4 makes us a credible "design + light analysis" peer for a *focused* workflow.
+Items 7–8 are where ENPICOM's enterprise scale and antibody-structure depth live — matching those is a much larger investment and a different product bet.

demo/demo_sequences_extended.csv

@@ -0,0 +1,15 @@
+id,gene_name,five_prime_utr,cds,three_prime_utr,poly_a_tail,full_mrna,target_protein,organism,expression_system,gc_target_percent,notes
+1,eGFP-hBG-HEK,ACATTTGCTTCTGACACAACTGTGTTCACTAGCAACCTCAAACAGACACCATGGTGCATCTGACTCCTGAGGAGAAGTCT,ATGGTGAGCAAGGGCGAGGAGCTGTTCACCGGGGTGGTGCCCATCCTGGTCGAGCTGGACGGCGACGTAAACGGCCACAAGTTCAGCGTGTCCGGCGAGGGCGAGGGCGATGCCACCTACGGCAAGCTGACCCTGAAGTTCATCTGCACCACCGGCAAGCTGCCCGTGCCCTGGCCCACCCTCGTGACCACCCTGACCTACGGCGTGCAGTGCTTCAGCCGCTACCCCGACCACATGAAGCAGCACGACTTCTTCAAGTCCGCCATGCCCGAAGGCTACGTCCAGGAGCGCACCATCTTCTTCAAGGACGACGGCAACTACAAGACCCGCGCCGAGGTGAAGTTCGAGGGCGACACCCTGGTGAACCGCATCGAGCTGAAGGGCATCGACTTCAAGGAGGACGGCAACATCCTGGGGCACAAGCTGGAGTACAACTACAACAGCCACAACGTCTATATCATGGCCGACAAGCAGAAGAACGGCATCAAGGTGAACTTCAAGATCCGCCACAACATCGAGGACGGCAGCGTGCAGCTCGCCGACCACTACCAGCAGAACACCCCCATCGGCGACGGCCCCGTGCTGCTGCCCGACAACCACTACCTGAGCACCCAGTCCGCCCTGAGCAAAGACCCCAACGAGAAGCGCGATCACATGGTCCTGCTGGAGTTCGTGACCGCCGCCGGGATCACTCTCGGCATGGACGAGCTGTACAAGTAA,GCTCGCTTTCTTGCTGTCCAATTTCTATTAAAGGTTCCTTTGTTCCCTAAGTCCAACTACTAAACTGGGGGATATTATGAAGGGCCTTGAGCATCTGGAT,AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,,Enhanced GFP,Aequorea victoria,HEK293T,61.5,"Beta-globin UTRs, standard 120A tail. Benchmark reporter."
+2,eGFP-Alb-CHO,AGATCTTCTTTTAAATTTCTTTTTACTGAATTCAGCCAATATATGTAATCCTACTTTCAATCAATTTTCCTAAGCAATG,ATGGTGAGCAAGGGCGAGGAGCTGTTCACCGGGGTGGTGCCCATCCTGGTCGAGCTGGACGGCGACGTAAACGGCCACAAGTTCAGCGTGTCCGGCGAGGGCGAGGGCGATGCCACCTACGGCAAGCTGACCCTGAAGTTCATCTGCACCACCGGCAAGCTGCCCGTGCCCTGGCCCACCCTCGTGACCACCCTGACCTACGGCGTGCAGTGCTTCAGCCGCTACCCCGACCACATGAAGCAGCACGACTTCTTCAAGTCCGCCATGCCCGAAGGCTACGTCCAGGAGCGCACCATCTTCTTCAAGGACGACGGCAACTACAAGACCCGCGCCGAGGTGAAGTTCGAGGGCGACACCCTGGTGAACCGCATCGAGCTGAAGGGCATCGACTTCAAGGAGGACGGCAACATCCTGGGGCACAAGCTGGAGTACAACTACAACAGCCACAACGTCTATATCATGGCCGACAAGCAGAAGAACGGCATCAAGGTGAACTTCAAGATCCGCCACAACATCGAGGACGGCAGCGTGCAGCTCGCCGACCACTACCAGCAGAACACCCCCATCGGCGACGGCCCCGTGCTGCTGCCCGACAACCACTACCTGAGCACCCAGTCCGCCCTGAGCAAAGACCCCAACGAGAAGCGCGATCACATGGTCCTGCTGGAGTTCGTGACCGCCGCCGGGATCACTCTCGGCATGGACGAGCTGTACAAGTAA,AATAAAGATCTTTATTTTCATTAGATCTGTGTGTTGGTTTTTTGTGTGAATCGATAGTACTAAATACTTTTCAGACACCAGAAATGCAGAGCAGTTCAGA,AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,,Enhanced GFP,Aequorea victoria,CHO,61.5,Albumin UTRs for prolonged expression in CHO.
+3,eGFP-Alb-HEK-shortA,AGATCTTCTTTTAAATTTCTTTTTACTGAATTCAGCCAATATATGTAATCCTACTTTCAATCAATTTTCCTAAGCAATG,ATGGTGAGCAAGGGCGAGGAGCTGTTCACCGGGGTGGTGCCCATCCTGGTCGAGCTGGACGGCGACGTAAACGGCCACAAGTTCAGCGTGTCCGGCGAGGGCGAGGGCGATGCCACCTACGGCAAGCTGACCCTGAAGTTCATCTGCACCACCGGCAAGCTGCCCGTGCCCTGGCCCACCCTCGTGACCACCCTGACCTACGGCGTGCAGTGCTTCAGCCGCTACCCCGACCACATGAAGCAGCACGACTTCTTCAAGTCCGCCATGCCCGAAGGCTACGTCCAGGAGCGCACCATCTTCTTCAAGGACGACGGCAACTACAAGACCCGCGCCGAGGTGAAGTTCGAGGGCGACACCCTGGTGAACCGCATCGAGCTGAAGGGCATCGACTTCAAGGAGGACGGCAACATCCTGGGGCACAAGCTGGAGTACAACTACAACAGCCACAACGTCTATATCATGGCCGACAAGCAGAAGAACGGCATCAAGGTGAACTTCAAGATCCGCCACAACATCGAGGACGGCAGCGTGCAGCTCGCCGACCACTACCAGCAGAACACCCCCATCGGCGACGGCCCCGTGCTGCTGCCCGACAACCACTACCTGAGCACCCAGTCCGCCCTGAGCAAAGACCCCAACGAGAAGCGCGATCACATGGTCCTGCTGGAGTTCGTGACCGCCGCCGGGATCACTCTCGGCATGGACGAGCTGTACAAGTAA,AATAAAGATCTTTATTTTCATTAGATCTGTGTGTTGGTTTTTTGTGTGAATCGATAGTACTAAATACTTTTCAGACACCAGAAATGCAGAGCAGTTCAGA,AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,,Enhanced GFP,Aequorea victoria,HEK293T,61.5,Short 80A tail variant — tail-length screen.
+4,eGFP-noUTR-codonopt,,ATGGTGAGCAAGGGCGAGGAGCTGTTCACCGGGGTGGTGCCCATCCTGGTCGAGCTGGACGGCGACGTAAACGGCCACAAGTTCAGCGTGTCCGGCGAGGGCGAGGGCGATGCCACCTACGGCAAGCTGACCCTGAAGTTCATCTGCACCACCGGCAAGCTGCCCGTGCCCTGGCCCACCCTCGTGACCACCCTGACCTACGGCGTGCAGTGCTTCAGCCGCTACCCCGACCACATGAAGCAGCACGACTTCTTCAAGTCCGCCATGCCCGAAGGCTACGTCCAGGAGCGCACCATCTTCTTCAAGGACGACGGCAACTACAAGACCCGCGCCGAGGTGAAGTTCGAGGGCGACACCCTGGTGAACCGCATCGAGCTGAAGGGCATCGACTTCAAGGAGGACGGCAACATCCTGGGGCACAAGCTGGAGTACAACTACAACAGCCACAACGTCTATATCATGGCCGACAAGCAGAAGAACGGCATCAAGGTGAACTTCAAGATCCGCCACAACATCGAGGACGGCAGCGTGCAGCTCGCCGACCACTACCAGCAGAACACCCCCATCGGCGACGGCCCCGTGCTGCTGCCCGACAACCACTACCTGAGCACCCAGTCCGCCCTGAGCAAAGACCCCAACGAGAAGCGCGATCACATGGTCCTGCTGGAGTTCGTGACCGCCGCCGGGATCACTCTCGGCATGGACGAGCTGTACAAGTAA,,AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,,Enhanced GFP,Aequorea victoria,in vitro,61.5,Bare CDS for codon-optimization testing.
+5,eGFP-hBG-Jurkat,ACATTTGCTTCTGACACAACTGTGTTCACTAGCAACCTCAAACAGACACCATGGTGCATCTGACTCCTGAGGAGAAGTCT,ATGGTGAGCAAGGGCGAGGAGCTGTTCACCGGGGTGGTGCCCATCCTGGTCGAGCTGGACGGCGACGTAAACGGCCACAAGTTCAGCGTGTCCGGCGAGGGCGAGGGCGATGCCACCTACGGCAAGCTGACCCTGAAGTTCATCTGCACCACCGGCAAGCTGCCCGTGCCCTGGCCCACCCTCGTGACCACCCTGACCTACGGCGTGCAGTGCTTCAGCCGCTACCCCGACCACATGAAGCAGCACGACTTCTTCAAGTCCGCCATGCCCGAAGGCTACGTCCAGGAGCGCACCATCTTCTTCAAGGACGACGGCAACTACAAGACCCGCGCCGAGGTGAAGTTCGAGGGCGACACCCTGGTGAACCGCATCGAGCTGAAGGGCATCGACTTCAAGGAGGACGGCAACATCCTGGGGCACAAGCTGGAGTACAACTACAACAGCCACAACGTCTATATCATGGCCGACAAGCAGAAGAACGGCATCAAGGTGAACTTCAAGATCCGCCACAACATCGAGGACGGCAGCGTGCAGCTCGCCGACCACTACCAGCAGAACACCCCCATCGGCGACGGCCCCGTGCTGCTGCCCGACAACCACTACCTGAGCACCCAGTCCGCCCTGAGCAAAGACCCCAACGAGAAGCGCGATCACATGGTCCTGCTGGAGTTCGTGACCGCCGCCGGGATCACTCTCGGCATGGACGAGCTGTACAAGTAA,GCTCGCTTTCTTGCTGTCCAATTTCTATTAAAGGTTCCTTTGTTCCCTAAGTCCAACTACTAAACTGGGGGATATTATGAAGGGCCTTGAGCATCTGGAT,AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,,Enhanced GFP,Aequorea victoria,Jurkat,61.5,Beta-globin UTRs in T-cell line.
+6,mCherry-hBG-HEK,ACATTTGCTTCTGACACAACTGTGTTCACTAGCAACCTCAAACAGACACCATGGTGCATCTGACTCCTGAGGAGAAGTCT,ATGGTGAGCAAGGGCGAGGAGGATAACATGGCCATCATCAAGGAGTTCATGCGCTTCAAGGTGCACATGGAGGGCTCCGTGAACGGCCACGAGTTCGAGATCGAGGGCGAGGGCGAGGGCCGCCCCTACGAGGGCACCCAGACCGCCAAGCTGAAGGTGACCAAGGGTGGCCCCCTGCCCTTCGCCTGGGACATCCTGTCCCCTCAGTTCATGTACGGCTCCAAGGCCTACGTGAAGCACCCCGCCGACATCCCCGACTACTTGAAGCTGTCCTTCCCCGAGGGCTTCAAGTGGGAGCGCGTGATGAACTTCGAGGACGGCGGCGTGGTGACCGTGACCCAGGACTCCTCCCTGCAGGACGGCGAGTTCATCTACAAGGTGAAGCTGCGCGGCACCAACTTCCCCTCCGACGGCCCCGTAATGCAGAAGAAGACCATGGGCTGGGAGGCCTCCTCCGAGCGGATGTACCCCGAGGACGGCGCCCTGAAGGGCGAGATCAAGCAGAGGCTGAAGCTGAAGGACGGCGGCCACTACGACGCTGAGGTCAAGACCACCTACAAGGCCAAGAAGCCCGTGCAGCTGCCCGGCGCCTACAACGTCAACATCAAGTTGGACATCACCTCCCACAACGAGGACTACACCATCGTGGAACAGTACGAACGCGCCGAGGGCCGCCACTCCACCGGCGGCATGGACGAGCTGTACAAGTAA,GCTCGCTTTCTTGCTGTCCAATTTCTATTAAAGGTTCCTTTGTTCCCTAAGTCCAACTACTAAACTGGGGGATATTATGAAGGGCCTTGAGCATCTGGAT,AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,,mCherry RFP,Discosoma sp.,HEK293T,62.6,Red reporter with beta-globin UTRs.
+7,mCherry-Alb-CHO,AGATCTTCTTTTAAATTTCTTTTTACTGAATTCAGCCAATATATGTAATCCTACTTTCAATCAATTTTCCTAAGCAATG,ATGGTGAGCAAGGGCGAGGAGGATAACATGGCCATCATCAAGGAGTTCATGCGCTTCAAGGTGCACATGGAGGGCTCCGTGAACGGCCACGAGTTCGAGATCGAGGGCGAGGGCGAGGGCCGCCCCTACGAGGGCACCCAGACCGCCAAGCTGAAGGTGACCAAGGGTGGCCCCCTGCCCTTCGCCTGGGACATCCTGTCCCCTCAGTTCATGTACGGCTCCAAGGCCTACGTGAAGCACCCCGCCGACATCCCCGACTACTTGAAGCTGTCCTTCCCCGAGGGCTTCAAGTGGGAGCGCGTGATGAACTTCGAGGACGGCGGCGTGGTGACCGTGACCCAGGACTCCTCCCTGCAGGACGGCGAGTTCATCTACAAGGTGAAGCTGCGCGGCACCAACTTCCCCTCCGACGGCCCCGTAATGCAGAAGAAGACCATGGGCTGGGAGGCCTCCTCCGAGCGGATGTACCCCGAGGACGGCGCCCTGAAGGGCGAGATCAAGCAGAGGCTGAAGCTGAAGGACGGCGGCCACTACGACGCTGAGGTCAAGACCACCTACAAGGCCAAGAAGCCCGTGCAGCTGCCCGGCGCCTACAACGTCAACATCAAGTTGGACATCACCTCCCACAACGAGGACTACACCATCGTGGAACAGTACGAACGCGCCGAGGGCCGCCACTCCACCGGCGGCATGGACGAGCTGTACAAGTAA,AATAAAGATCTTTATTTTCATTAGATCTGTGTGTTGGTTTTTTGTGTGAATCGATAGTACTAAATACTTTTCAGACACCAGAAATGCAGAGCAGTTCAGA,AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,,mCherry RFP,Discosoma sp.,CHO,62.6,"Albumin UTRs, CHO production."
+8,mCherry-Alb-Primary,AGATCTTCTTTTAAATTTCTTTTTACTGAATTCAGCCAATATATGTAATCCTACTTTCAATCAATTTTCCTAAGCAATG,ATGGTGAGCAAGGGCGAGGAGGATAACATGGCCATCATCAAGGAGTTCATGCGCTTCAAGGTGCACATGGAGGGCTCCGTGAACGGCCACGAGTTCGAGATCGAGGGCGAGGGCGAGGGCCGCCCCTACGAGGGCACCCAGACCGCCAAGCTGAAGGTGACCAAGGGTGGCCCCCTGCCCTTCGCCTGGGACATCCTGTCCCCTCAGTTCATGTACGGCTCCAAGGCCTACGTGAAGCACCCCGCCGACATCCCCGACTACTTGAAGCTGTCCTTCCCCGAGGGCTTCAAGTGGGAGCGCGTGATGAACTTCGAGGACGGCGGCGTGGTGACCGTGACCCAGGACTCCTCCCTGCAGGACGGCGAGTTCATCTACAAGGTGAAGCTGCGCGGCACCAACTTCCCCTCCGACGGCCCCGTAATGCAGAAGAAGACCATGGGCTGGGAGGCCTCCTCCGAGCGGATGTACCCCGAGGACGGCGCCCTGAAGGGCGAGATCAAGCAGAGGCTGAAGCTGAAGGACGGCGGCCACTACGACGCTGAGGTCAAGACCACCTACAAGGCCAAGAAGCCCGTGCAGCTGCCCGGCGCCTACAACGTCAACATCAAGTTGGACATCACCTCCCACAACGAGGACTACACCATCGTGGAACAGTACGAACGCGCCGAGGGCCGCCACTCCACCGGCGGCATGGACGAGCTGTACAAGTAA,AATAAAGATCTTTATTTTCATTAGATCTGTGTGTTGGTTTTTTGTGTGAATCGATAGTACTAAATACTTTTCAGACACCAGAAATGCAGAGCAGTTCAGA,AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,,mCherry RFP,Discosoma sp.,Primary T cells,62.6,Long tail for primary-cell stability.
+9,mCherry-noUTR-base,,ATGGTGAGCAAGGGCGAGGAGGATAACATGGCCATCATCAAGGAGTTCATGCGCTTCAAGGTGCACATGGAGGGCTCCGTGAACGGCCACGAGTTCGAGATCGAGGGCGAGGGCGAGGGCCGCCCCTACGAGGGCACCCAGACCGCCAAGCTGAAGGTGACCAAGGGTGGCCCCCTGCCCTTCGCCTGGGACATCCTGTCCCCTCAGTTCATGTACGGCTCCAAGGCCTACGTGAAGCACCCCGCCGACATCCCCGACTACTTGAAGCTGTCCTTCCCCGAGGGCTTCAAGTGGGAGCGCGTGATGAACTTCGAGGACGGCGGCGTGGTGACCGTGACCCAGGACTCCTCCCTGCAGGACGGCGAGTTCATCTACAAGGTGAAGCTGCGCGGCACCAACTTCCCCTCCGACGGCCCCGTAATGCAGAAGAAGACCATGGGCTGGGAGGCCTCCTCCGAGCGGATGTACCCCGAGGACGGCGCCCTGAAGGGCGAGATCAAGCAGAGGCTGAAGCTGAAGGACGGCGGCCACTACGACGCTGAGGTCAAGACCACCTACAAGGCCAAGAAGCCCGTGCAGCTGCCCGGCGCCTACAACGTCAACATCAAGTTGGACATCACCTCCCACAACGAGGACTACACCATCGTGGAACAGTACGAACGCGCCGAGGGCCGCCACTCCACCGGCGGCATGGACGAGCTGTACAAGTAA,,AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,,mCherry RFP,Discosoma sp.,in vitro,62.6,Minimal construct — GC/CAI baseline.
+10,mCherry-hBG-shortA,ACATTTGCTTCTGACACAACTGTGTTCACTAGCAACCTCAAACAGACACCATGGTGCATCTGACTCCTGAGGAGAAGTCT,ATGGTGAGCAAGGGCGAGGAGGATAACATGGCCATCATCAAGGAGTTCATGCGCTTCAAGGTGCACATGGAGGGCTCCGTGAACGGCCACGAGTTCGAGATCGAGGGCGAGGGCGAGGGCCGCCCCTACGAGGGCACCCAGACCGCCAAGCTGAAGGTGACCAAGGGTGGCCCCCTGCCCTTCGCCTGGGACATCCTGTCCCCTCAGTTCATGTACGGCTCCAAGGCCTACGTGAAGCACCCCGCCGACATCCCCGACTACTTGAAGCTGTCCTTCCCCGAGGGCTTCAAGTGGGAGCGCGTGATGAACTTCGAGGACGGCGGCGTGGTGACCGTGACCCAGGACTCCTCCCTGCAGGACGGCGAGTTCATCTACAAGGTGAAGCTGCGCGGCACCAACTTCCCCTCCGACGGCCCCGTAATGCAGAAGAAGACCATGGGCTGGGAGGCCTCCTCCGAGCGGATGTACCCCGAGGACGGCGCCCTGAAGGGCGAGATCAAGCAGAGGCTGAAGCTGAAGGACGGCGGCCACTACGACGCTGAGGTCAAGACCACCTACAAGGCCAAGAAGCCCGTGCAGCTGCCCGGCGCCTACAACGTCAACATCAAGTTGGACATCACCTCCCACAACGAGGACTACACCATCGTGGAACAGTACGAACGCGCCGAGGGCCGCCACTCCACCGGCGGCATGGACGAGCTGTACAAGTAA,GCTCGCTTTCTTGCTGTCCAATTTCTATTAAAGGTTCCTTTGTTCCCTAAGTCCAACTACTAAACTGGGGGATATTATGAAGGGCCTTGAGCATCTGGAT,AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,,mCherry RFP,Discosoma sp.,HEK293T,62.6,Short tail variant for stability comparison.
+11,eGFP-mono-hBG,,,,,ACATTTGCTTCTGACACAACTGTGTTCACTAGCAACCTCAAACAGACACCATGGTGCATCTGACTCCTGAGGAGAAGTCTGCCACCATGGTGAGCAAGGGCGAGGAGCTGTTCACCGGGGTGGTGCCCATCCTGGTCGAGCTGGACGGCGACGTAAACGGCCACAAGTTCAGCGTGTCCGGCGAGGGCGAGGGCGATGCCACCTACGGCAAGCTGACCCTGAAGTTCATCTGCACCACCGGCAAGCTGCCCGTGCCCTGGCCCACCCTCGTGACCACCCTGACCTACGGCGTGCAGTGCTTCAGCCGCTACCCCGACCACATGAAGCAGCACGACTTCTTCAAGTCCGCCATGCCCGAAGGCTACGTCCAGGAGCGCACCATCTTCTTCAAGGACGACGGCAACTACAAGACCCGCGCCGAGGTGAAGTTCGAGGGCGACACCCTGGTGAACCGCATCGAGCTGAAGGGCATCGACTTCAAGGAGGACGGCAACATCCTGGGGCACAAGCTGGAGTACAACTACAACAGCCACAACGTCTATATCATGGCCGACAAGCAGAAGAACGGCATCAAGGTGAACTTCAAGATCCGCCACAACATCGAGGACGGCAGCGTGCAGCTCGCCGACCACTACCAGCAGAACACCCCCATCGGCGACGGCCCCGTGCTGCTGCCCGACAACCACTACCTGAGCACCCAGTCCGCCCTGAGCAAAGACCCCAACGAGAAGCGCGATCACATGGTCCTGCTGGAGTTCGTGACCGCCGCCGGGATCACTCTCGGCATGGACGAGCTGTACAAGTAAGCTCGCTTTCTTGCTGTCCAATTTCTATTAAAGGTTCCTTTGTTCCCTAAGTCCAACTACTAAACTGGGGGATATTATGAAGGGCCTTGAGCATCTGGATAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,Enhanced GFP,Aequorea victoria,HEK293T,51.5,Monolithic archive record (assembled mRNA).
+12,eGFP-mono-Alb,,,,,AGATCTTCTTTTAAATTTCTTTTTACTGAATTCAGCCAATATATGTAATCCTACTTTCAATCAATTTTCCTAAGCAATGGCCACCATGGTGAGCAAGGGCGAGGAGCTGTTCACCGGGGTGGTGCCCATCCTGGTCGAGCTGGACGGCGACGTAAACGGCCACAAGTTCAGCGTGTCCGGCGAGGGCGAGGGCGATGCCACCTACGGCAAGCTGACCCTGAAGTTCATCTGCACCACCGGCAAGCTGCCCGTGCCCTGGCCCACCCTCGTGACCACCCTGACCTACGGCGTGCAGTGCTTCAGCCGCTACCCCGACCACATGAAGCAGCACGACTTCTTCAAGTCCGCCATGCCCGAAGGCTACGTCCAGGAGCGCACCATCTTCTTCAAGGACGACGGCAACTACAAGACCCGCGCCGAGGTGAAGTTCGAGGGCGACACCCTGGTGAACCGCATCGAGCTGAAGGGCATCGACTTCAAGGAGGACGGCAACATCCTGGGGCACAAGCTGGAGTACAACTACAACAGCCACAACGTCTATATCATGGCCGACAAGCAGAAGAACGGCATCAAGGTGAACTTCAAGATCCGCCACAACATCGAGGACGGCAGCGTGCAGCTCGCCGACCACTACCAGCAGAACACCCCCATCGGCGACGGCCCCGTGCTGCTGCCCGACAACCACTACCTGAGCACCCAGTCCGCCCTGAGCAAAGACCCCAACGAGAAGCGCGATCACATGGTCCTGCTGGAGTTCGTGACCGCCGCCGGGATCACTCTCGGCATGGACGAGCTGTACAAGTAAAATAAAGATCTTTATTTTCATTAGATCTGTGTGTTGGTTTTTTGTGTGAATCGATAGTACTAAATACTTTTCAGACACCAGAAATGCAGAGCAGTTCAGAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,Enhanced GFP,Aequorea victoria,CHO,49.9,"Monolithic, albumin UTRs."
+13,mCherry-mono-hBG,,,,,ACATTTGCTTCTGACACAACTGTGTTCACTAGCAACCTCAAACAGACACCATGGTGCATCTGACTCCTGAGGAGAAGTCTGCCACCATGGTGAGCAAGGGCGAGGAGGATAACATGGCCATCATCAAGGAGTTCATGCGCTTCAAGGTGCACATGGAGGGCTCCGTGAACGGCCACGAGTTCGAGATCGAGGGCGAGGGCGAGGGCCGCCCCTACGAGGGCACCCAGACCGCCAAGCTGAAGGTGACCAAGGGTGGCCCCCTGCCCTTCGCCTGGGACATCCTGTCCCCTCAGTTCATGTACGGCTCCAAGGCCTACGTGAAGCACCCCGCCGACATCCCCGACTACTTGAAGCTGTCCTTCCCCGAGGGCTTCAAGTGGGAGCGCGTGATGAACTTCGAGGACGGCGGCGTGGTGACCGTGACCCAGGACTCCTCCCTGCAGGACGGCGAGTTCATCTACAAGGTGAAGCTGCGCGGCACCAACTTCCCCTCCGACGGCCCCGTAATGCAGAAGAAGACCATGGGCTGGGAGGCCTCCTCCGAGCGGATGTACCCCGAGGACGGCGCCCTGAAGGGCGAGATCAAGCAGAGGCTGAAGCTGAAGGACGGCGGCCACTACGACGCTGAGGTCAAGACCACCTACAAGGCCAAGAAGCCCGTGCAGCTGCCCGGCGCCTACAACGTCAACATCAAGTTGGACATCACCTCCCACAACGAGGACTACACCATCGTGGAACAGTACGAACGCGCCGAGGGCCGCCACTCCACCGGCGGCATGGACGAGCTGTACAAGTAAGCTCGCTTTCTTGCTGTCCAATTTCTATTAAAGGTTCCTTTGTTCCCTAAGTCCAACTACTAAACTGGGGGATATTATGAAGGGCCTTGAGCATCTGGATAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,mCherry RFP,Discosoma sp.,HEK293T,52.1,"Monolithic red reporter, beta-globin UTRs."
+14,mCherry-mono-Alb,,,,,AGATCTTCTTTTAAATTTCTTTTTACTGAATTCAGCCAATATATGTAATCCTACTTTCAATCAATTTTCCTAAGCAATGGCCACCATGGTGAGCAAGGGCGAGGAGGATAACATGGCCATCATCAAGGAGTTCATGCGCTTCAAGGTGCACATGGAGGGCTCCGTGAACGGCCACGAGTTCGAGATCGAGGGCGAGGGCGAGGGCCGCCCCTACGAGGGCACCCAGACCGCCAAGCTGAAGGTGACCAAGGGTGGCCCCCTGCCCTTCGCCTGGGACATCCTGTCCCCTCAGTTCATGTACGGCTCCAAGGCCTACGTGAAGCACCCCGCCGACATCCCCGACTACTTGAAGCTGTCCTTCCCCGAGGGCTTCAAGTGGGAGCGCGTGATGAACTTCGAGGACGGCGGCGTGGTGACCGTGACCCAGGACTCCTCCCTGCAGGACGGCGAGTTCATCTACAAGGTGAAGCTGCGCGGCACCAACTTCCCCTCCGACGGCCCCGTAATGCAGAAGAAGACCATGGGCTGGGAGGCCTCCTCCGAGCGGATGTACCCCGAGGACGGCGCCCTGAAGGGCGAGATCAAGCAGAGGCTGAAGCTGAAGGACGGCGGCCACTACGACGCTGAGGTCAAGACCACCTACAAGGCCAAGAAGCCCGTGCAGCTGCCCGGCGCCTACAACGTCAACATCAAGTTGGACATCACCTCCCACAACGAGGACTACACCATCGTGGAACAGTACGAACGCGCCGAGGGCCGCCACTCCACCGGCGGCATGGACGAGCTGTACAAGTAAAATAAAGATCTTTATTTTCATTAGATCTGTGTGTTGGTTTTTTGTGTGAATCGATAGTACTAAATACTTTTCAGACACCAGAAATGCAGAGCAGTTCAGAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA,mCherry RFP,Discosoma sp.,Jurkat,50.5,"Monolithic, albumin UTRs, T-cell line."

models/runs.py

@@ -0,0 +1,122 @@
+"""
+Model run / experiment tracking.
+
+A lightweight MLOps layer: every time a scoring model is run against a worklist
+we record a ``ModelRun`` (model name + version, timestamp, score statistics, and
+per-sequence scores). ``RunHistory`` stores them and can compare two runs — e.g.
+two versions of the same model — to show how scores shifted.
+
+Pure-Python (uses only the stdlib ``statistics`` module).
+"""
+from __future__ import annotations
+
+import math
+import statistics
+import uuid
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+
+@dataclass
+class ModelRun:
+    """A single scoring run over a set of sequences."""
+    model_name: str
+    model_version: str
+    model_source: str
+    worklist_name: str
+    n_sequences: int
+    score_min: float
+    score_max: float
+    score_mean: float
+    score_std: float
+    timestamp: str                         # ISO-8601
+    run_id: str = field(default_factory=lambda: str(uuid.uuid4())[:8])
+    notes: str = ""
+    scores: Dict[str, float] = field(default_factory=dict)  # seq_id -> score
+
+    @property
+    def label(self) -> str:
+        return f"{self.model_name} v{self.model_version} · {self.timestamp}"
+
+
+def summarize_run(
+    model_name: str,
+    model_version: str,
+    model_source: str,
+    worklist_name: str,
+    scores: Dict[str, float],
+    timestamp: str,
+    notes: str = "",
+) -> ModelRun:
+    """Build a ModelRun from a {seq_id: score} mapping (ignoring NaNs in stats)."""
+    valid = [v for v in scores.values() if v is not None and not math.isnan(v)]
+    n = len(valid)
+    smin = min(valid) if valid else float("nan")
+    smax = max(valid) if valid else float("nan")
+    smean = statistics.fmean(valid) if valid else float("nan")
+    sstd = statistics.pstdev(valid) if len(valid) > 1 else 0.0
+    return ModelRun(
+        model_name=model_name, model_version=model_version,
+        model_source=model_source, worklist_name=worklist_name,
+        n_sequences=n, score_min=smin, score_max=smax,
+        score_mean=smean, score_std=sstd, timestamp=timestamp,
+        notes=notes, scores=dict(scores),
+    )
+
+
+@dataclass
+class RunComparison:
+    """Per-sequence delta between two runs over their shared sequences."""
+    run_a: ModelRun
+    run_b: ModelRun
+    shared_ids: List[str]
+    deltas: Dict[str, float]               # seq_id -> (b - a)
+    mean_delta: float
+    n_improved: int                        # b > a
+    n_worsened: int                        # b < a
+    n_unchanged: int
+
+
+class RunHistory:
+    """Append-only store of ModelRun records."""
+
+    def __init__(self) -> None:
+        self.runs: List[ModelRun] = []
+
+    def add(self, run: ModelRun) -> None:
+        self.runs.append(run)
+
+    def for_model(self, model_name: str) -> List[ModelRun]:
+        return [r for r in self.runs if r.model_name == model_name]
+
+    def model_names(self) -> List[str]:
+        # preserve first-seen order
+        seen: List[str] = []
+        for r in self.runs:
+            if r.model_name not in seen:
+                seen.append(r.model_name)
+        return seen
+
+    @staticmethod
+    def compare(run_a: ModelRun, run_b: ModelRun) -> RunComparison:
+        shared = [sid for sid in run_a.scores if sid in run_b.scores]
+        deltas: Dict[str, float] = {}
+        improved = worsened = unchanged = 0
+        for sid in shared:
+            a, b = run_a.scores[sid], run_b.scores[sid]
+            if a is None or b is None or math.isnan(a) or math.isnan(b):
+                continue
+            d = b - a
+            deltas[sid] = d
+            if d > 1e-9:
+                improved += 1
+            elif d < -1e-9:
+                worsened += 1
+            else:
+                unchanged += 1
+        mean_delta = statistics.fmean(deltas.values()) if deltas else 0.0
+        return RunComparison(
+            run_a=run_a, run_b=run_b, shared_ids=list(deltas.keys()),
+            deltas=deltas, mean_delta=mean_delta,
+            n_improved=improved, n_worsened=worsened, n_unchanged=unchanged,
+        )

tests/test_clustering.py

@@ -0,0 +1,73 @@
+"""Tests for sequence clustering and dendrogram building."""
+import numpy as np
+import pytest
+
+from core.analysis.clustering import (
+    kmer_distance_matrix, upgma, flat_clusters, dendrogram_layout,
+)
+
+
+class TestDistance:
+    def test_identical_sequences_zero_distance(self):
+        d = kmer_distance_matrix(["ATGCATGC", "ATGCATGC"], k=3)
+        assert d[0, 1] == pytest.approx(0.0, abs=1e-9)
+
+    def test_disjoint_sequences_high_distance(self):
+        d = kmer_distance_matrix(["AAAAAAAA", "GGGGGGGG"], k=3)
+        assert d[0, 1] > 0.9
+
+    def test_matrix_is_symmetric_zero_diagonal(self):
+        d = kmer_distance_matrix(["ATGCATGC", "TTGGCCAA", "ATGCATGG"], k=3)
+        assert np.allclose(d, d.T)
+        assert np.allclose(np.diag(d), 0.0)
+
+    def test_short_sequence_safe(self):
+        d = kmer_distance_matrix(["AT", "ATGC"], k=4)  # first too short for k
+        assert d.shape == (2, 2)
+
+
+class TestUPGMA:
+    SEQS = ["ATGCATGCATGC", "ATGCATGCATGG", "TTTTGGGGTTTT", "TTTTGGGGTTTG"]
+
+    def test_linkage_shape(self):
+        link, order = upgma(kmer_distance_matrix(self.SEQS, k=3))
+        assert link.shape == (3, 4)              # n-1 merges
+        assert sorted(order) == [0, 1, 2, 3]     # leaf order is a permutation
+
+    def test_single_sequence_safe(self):
+        link, order = upgma(kmer_distance_matrix(["ATGC"], k=3))
+        assert link.shape == (0, 4)
+        assert order == [0]
+
+
+class TestFlatClusters:
+    SEQS = ["ATGCATGCATGC", "ATGCATGCATGG", "TTTTGGGGTTTT", "TTTTGGGGTTTG"]
+
+    def _link(self):
+        return upgma(kmer_distance_matrix(self.SEQS, k=3))[0]
+
+    def test_two_clusters_group_correctly(self):
+        cl = flat_clusters(self._link(), 4, threshold=0.5)
+        assert cl[0] == cl[1] and cl[2] == cl[3] and cl[0] != cl[2]
+
+    def test_high_threshold_single_cluster(self):
+        cl = flat_clusters(self._link(), 4, threshold=10.0)
+        assert len(set(cl)) == 1
+
+    def test_negative_threshold_all_singletons(self):
+        cl = flat_clusters(self._link(), 4, threshold=-1.0)
+        assert len(set(cl)) == 4
+
+    def test_cluster_ids_contiguous_from_zero(self):
+        cl = flat_clusters(self._link(), 4, threshold=0.5)
+        assert set(cl) == set(range(len(set(cl))))
+
+
+class TestDendrogramLayout:
+    def test_segments_and_heights(self):
+        seqs = ["ATGCATGCATGC", "ATGCATGCATGG", "TTTTGGGGTTTT", "TTTTGGGGTTTG"]
+        link, order = upgma(kmer_distance_matrix(seqs, k=3))
+        lay = dendrogram_layout(link, order)
+        assert len(lay.segments) == 3 * 3          # 3 segments per merge
+        assert all(y >= 0 for y in lay.node_y.values())
+        assert len(lay.leaf_x) == 4

tests/test_liability.py

@@ -0,0 +1,127 @@
+"""Tests for sequence-liability motif scanning and the liability aggregator."""
+from types import SimpleNamespace
+
+import pytest
+
+from core.analysis.motifs import scan_motifs
+from core.analysis.liability import assess_liabilities, CRITICAL, WARNING
+
+
+# ── Motif scanning ──────────────────────────────────────────────────────────
+
+class TestMotifs:
+    def test_uorf_in_5utr(self):
+        hits = scan_motifs(five_prime_utr="GGGCATGGGG", cds="ATGAAATAA", three_prime_utr="")
+        names = [h.name for h in hits]
+        assert "uorf" in names
+        uorf = next(h for h in hits if h.name == "uorf")
+        assert uorf.region == "5'UTR"
+        assert uorf.severity == WARNING
+
+    def test_premature_polya_in_cds_is_critical(self):
+        hits = scan_motifs(cds="ATGAATAAACCCTAA")
+        prem = [h for h in hits if h.name == "premature_polya"]
+        assert prem and prem[0].severity == CRITICAL
+        assert prem[0].region == "CDS"
+
+    def test_are_in_3utr(self):
+        hits = scan_motifs(three_prime_utr="GGATTTAGG")
+        are = [h for h in hits if h.name == "are"]
+        assert are and are[0].region == "3'UTR"
+
+    def test_splice_donor_detected_in_full(self):
+        hits = scan_motifs(full_seq="CCCGTAAGTCCC")
+        assert any(h.name == "splice_donor" for h in hits)
+
+    def test_clean_sequence_has_no_motifs(self):
+        # CDS with no AATAAA/ATTAAA, UTRs without ATG/ATTTA, no GT[AG]AGT
+        hits = scan_motifs(
+            five_prime_utr="CCGCCGCCGCC",
+            cds="ATGGGCGGCGGCTAA",
+            three_prime_utr="CCGCCGCCG",
+        )
+        assert hits == []
+
+    def test_uridine_input_is_normalised(self):
+        # RNA alphabet (U) should be treated like T
+        hits = scan_motifs(three_prime_utr="GGAUUUAGG")
+        assert any(h.name == "are" for h in hits)
+
+
+# ── Liability aggregation ───────────────────────────────────────────────────
+
+def _clean_report():
+    return SimpleNamespace(
+        gc_percent_global=52.0,
+        restriction_enzymes_present=[],
+        uridine=SimpleNamespace(u_percent=22.0, high_u_stretches=[]),
+        has_start_codon=True, has_stop_codon=True, in_frame=True,
+        kozak=SimpleNamespace(strength="strong", score=0.9),
+        structure=SimpleNamespace(is_stub=True, mfe=0.0, sequence=""),
+        motif_hits=[],
+    )
+
+
+def _clean_seq():
+    return SimpleNamespace(
+        five_prime_utr="CCGCCACC", kozak=None,
+        cds="ATGGGCGGCGGCTAA", three_prime_utr="CCGCCG",
+        poly_a="A" * 120,
+    )
+
+
+class TestLiability:
+    def test_clean_sequence_passes(self):
+        rep = assess_liabilities(_clean_report(), _clean_seq())
+        assert rep.verdict == "pass"
+        assert rep.score == 100
+        assert rep.n_critical == 0 and rep.flag_count == 0
+
+    def test_polya_tail_not_flagged_as_homopolymer(self):
+        # body has no long run; the 120-A tail must be ignored
+        rep = assess_liabilities(_clean_report(), _clean_seq())
+        assert not any(f.category == "Homopolymer" for f in rep.flags)
+
+    def test_body_homopolymer_flagged(self):
+        seq = _clean_seq()
+        seq.cds = "ATG" + "A" * 16 + "GGCTAA"   # 16-A run in the body
+        rep = assess_liabilities(_clean_report(), seq)
+        hp = [f for f in rep.flags if f.category == "Homopolymer"]
+        assert hp and hp[0].severity == CRITICAL
+
+    def test_extreme_gc_is_critical(self):
+        rep_dict = _clean_report()
+        rep_dict.gc_percent_global = 25.0
+        rep = assess_liabilities(rep_dict, _clean_seq())
+        assert any(f.category == "GC" and f.severity == CRITICAL for f in rep.flags)
+
+    def test_restriction_and_uridine_are_warnings(self):
+        r = _clean_report()
+        r.restriction_enzymes_present = ["EcoRI", "BamHI"]
+        r.uridine = SimpleNamespace(u_percent=46.0, high_u_stretches=[(1, 51, 50)])
+        rep = assess_liabilities(r, _clean_seq())
+        cats = {f.category for f in rep.flags}
+        assert "Restriction" in cats and "Uridine" in cats
+        assert rep.verdict == "review"
+
+    def test_missing_start_codon_fails(self):
+        r = _clean_report()
+        r.has_start_codon = False
+        rep = assess_liabilities(r, _clean_seq())
+        assert rep.verdict == "fail"
+        assert any(f.category == "CDS" and f.severity == CRITICAL for f in rep.flags)
+
+    def test_score_decreases_with_severity(self):
+        r = _clean_report()
+        r.has_start_codon = False            # critical (-25)
+        r.restriction_enzymes_present = ["EcoRI"]  # warning (-10)
+        rep = assess_liabilities(r, _clean_seq())
+        assert rep.score <= 65
+        assert rep.verdict == "fail"
+
+    def test_motif_hits_become_flags(self):
+        r = _clean_report()
+        r.motif_hits = scan_motifs(cds="ATGAATAAACCCTAA")  # premature polyA (critical)
+        rep = assess_liabilities(r, _clean_seq())
+        assert any(f.category == "Motif" and f.severity == CRITICAL for f in rep.flags)
+        assert rep.verdict == "fail"

tests/test_runs.py

@@ -0,0 +1,62 @@
+"""Tests for model run / experiment tracking."""
+import math
+
+from models.runs import summarize_run, RunHistory
+
+
+def _run(name, version, scores, ts="2026-01-01 00:00:00"):
+    return summarize_run(
+        model_name=name, model_version=version, model_source="local",
+        worklist_name="wl", scores=scores, timestamp=ts,
+    )
+
+
+class TestSummarize:
+    def test_basic_stats(self):
+        r = _run("m", "1.0", {"a": 1.0, "b": 3.0, "c": 5.0})
+        assert r.n_sequences == 3
+        assert r.score_min == 1.0 and r.score_max == 5.0
+        assert r.score_mean == 3.0
+        assert r.score_std > 0
+
+    def test_nan_scores_excluded(self):
+        r = _run("m", "1.0", {"a": 2.0, "b": float("nan")})
+        assert r.n_sequences == 1
+        assert r.score_mean == 2.0
+
+    def test_empty_scores_safe(self):
+        r = _run("m", "1.0", {})
+        assert r.n_sequences == 0
+        assert math.isnan(r.score_mean)
+
+    def test_label(self):
+        r = _run("MyModel", "2.1", {"a": 1.0})
+        assert "MyModel" in r.label and "2.1" in r.label
+
+
+class TestRunHistory:
+    def test_add_and_for_model(self):
+        h = RunHistory()
+        h.add(_run("A", "1.0", {"x": 1.0}))
+        h.add(_run("B", "1.0", {"x": 2.0}))
+        h.add(_run("A", "2.0", {"x": 3.0}))
+        assert len(h.runs) == 3
+        assert len(h.for_model("A")) == 2
+        assert h.model_names() == ["A", "B"]
+
+    def test_compare_deltas(self):
+        a = _run("A", "1.0", {"s1": 1.0, "s2": 2.0, "s3": 5.0})
+        b = _run("A", "2.0", {"s1": 2.0, "s2": 2.0, "s3": 4.0})  # +1, 0, -1
+        cmp = RunHistory.compare(a, b)
+        assert cmp.n_improved == 1
+        assert cmp.n_worsened == 1
+        assert cmp.n_unchanged == 1
+        assert cmp.mean_delta == 0.0
+        assert set(cmp.shared_ids) == {"s1", "s2", "s3"}
+
+    def test_compare_only_shared_sequences(self):
+        a = _run("A", "1.0", {"s1": 1.0, "only_a": 9.0})
+        b = _run("A", "2.0", {"s1": 2.0, "only_b": 8.0})
+        cmp = RunHistory.compare(a, b)
+        assert cmp.shared_ids == ["s1"]
+        assert cmp.deltas["s1"] == 1.0

ui/app.py

@@ -40,6 +40,8 @@ from ui.components.plasmid_view import PlasmidView
 from ui.components.model_repository import ModelRepositoryPanel
 from ui.components.plasmid_assembly import PlasmidAssemblyPanel
 from ui.components.generate_sequences import GenerateSequencesPanel
+from ui.components.cluster_view import ClusterView
+from ui.components.experiment_view import ExperimentView
 
 
 # ── Design tokens ─────────────────────────────────────────────────────────────
@@ -150,11 +152,13 @@ _TAB_NAMES = [
     "Import Data",
     "Model Repository",
     "Worklist",
+    "Cluster & Tree",
+    "Experiments",
     "Parts Workshop",
     "Assemble Plasmid",
     "Generate Sequences",
 ]
-_TAB_KEYS = ["import_db", "model_repo", "worklist", "parts", "assemble", "generate"]
+_TAB_KEYS = ["import_db", "model_repo", "worklist", "clusters", "experiments", "parts", "assemble", "generate"]
 
 
 logger = logging.getLogger(__name__)
@@ -185,6 +189,8 @@ class StudioApp(param.Parameterized):
         self._model_repo    = ModelRepositoryPanel(self.state)
         self._assembly      = PlasmidAssemblyPanel(self.state)
         self._generate      = GenerateSequencesPanel(self.state)
+        self._cluster       = ClusterView(self.state)
+        self._experiments   = ExperimentView(self.state)
 
         # ── Build persistent widgets once ─────────────────────────────────────
         self._tabs = pn.Tabs(
@@ -200,9 +206,11 @@ class StudioApp(param.Parameterized):
                 pn.panel(self._worklist.panel),
                 sizing_mode="stretch_width",
             )),
-            (_TAB_NAMES[3], pn.panel(self._parts.panel)),
-            (_TAB_NAMES[4], pn.panel(self._assembly.panel)),
-            (_TAB_NAMES[5], pn.panel(self._generate.panel)),
+            (_TAB_NAMES[3], pn.panel(self._cluster.panel)),
+            (_TAB_NAMES[4], pn.panel(self._experiments.panel)),
+            (_TAB_NAMES[5], pn.panel(self._parts.panel)),
+            (_TAB_NAMES[6], pn.panel(self._assembly.panel)),
+            (_TAB_NAMES[7], pn.panel(self._generate.panel)),
             active=0,
             sizing_mode="stretch_width",
         )

ui/components/analysis_dashboard.py

@@ -181,6 +181,115 @@ def _structure_card(report: AnalysisReport) -> pn.pane.HTML:
     """)
 
 
+def _uridine_card(report: AnalysisReport) -> pn.pane.HTML:
+    u = report.uridine
+    if u is None:
+        return pn.pane.HTML('<div style="color:#64748B;font-size:12px;">No uridine data.</div>')
+    color = "#059669" if u.u_percent < 35 else "#D97706" if u.u_percent < 45 else "#DC2626"
+    stretches = len(u.high_u_stretches)
+    return pn.pane.HTML(f"""
+        <div>
+            <span style="font-size:18px;font-weight:700;color:{color};">{u.u_percent:.1f}%</span>
+            <span style="font-size:11px;color:#64748B;margin-left:6px;">uridine</span>
+        </div>
+        <div style="font-size:11px;color:#64748B;margin-top:4px;">
+            {stretches} high-U stretch(es) · U/A ratio {u.ua_ratio:.2f}</div>
+        <div style="font-size:10px;color:#94A3B8;margin-top:3px;">
+            High U is immunostimulatory — modified nucleotides mitigate it.</div>
+    """)
+
+
+def _motif_card(report: AnalysisReport) -> pn.pane.HTML:
+    hits = report.motif_hits
+    if not hits:
+        return pn.pane.HTML(
+            '<div style="color:#059669;font-size:12px;">No liability motifs detected.</div>'
+        )
+    sev_color = {"critical": "#DC2626", "warning": "#D97706", "info": "#64748B"}
+    rows = ""
+    for h in hits[:12]:
+        c = sev_color.get(h.severity, "#64748B")
+        rows += (
+            f'<div style="display:flex;gap:8px;align-items:baseline;margin-bottom:3px;">'
+            f'<span style="background:{c};color:white;border-radius:3px;padding:1px 5px;'
+            f'font-size:9px;text-transform:uppercase;">{h.severity}</span>'
+            f'<span style="font-size:12px;">{h.label}</span>'
+            f'<span style="font-size:10px;color:#94A3B8;font-family:monospace;">'
+            f'{h.region}:{h.start}</span></div>'
+        )
+    more = f'<div style="font-size:10px;color:#94A3B8;">+{len(hits)-12} more</div>' if len(hits) > 12 else ""
+    return pn.pane.HTML(rows + more)
+
+
+_VERDICT_STYLE = {
+    "pass":   ("#059669", "PASS"),
+    "review": ("#D97706", "REVIEW"),
+    "fail":   ("#DC2626", "FAIL"),
+}
+_SEV_STYLE = {
+    "critical": ("#DC2626", "Critical"),
+    "warning":  ("#D97706", "Warning"),
+    "info":     ("#64748B", "Info"),
+}
+
+
+def render_liability_panel(report: AnalysisReport) -> pn.pane.HTML:
+    """Reusable liability / QC scorecard + ranked flag list (pure HTML)."""
+    lia = getattr(report, "liability", None)
+    if lia is None:
+        return pn.pane.HTML('<div style="color:#64748B;font-size:12px;">No liability assessment.</div>')
+
+    vcolor, vlabel = _VERDICT_STYLE.get(lia.verdict, ("#64748B", lia.verdict.upper()))
+    score_color = "#059669" if lia.score >= 85 else "#D97706" if lia.score >= 60 else "#DC2626"
+
+    counts = (
+        f'<span style="color:#DC2626;font-weight:700;">{lia.n_critical}</span> critical · '
+        f'<span style="color:#D97706;font-weight:700;">{lia.n_warning}</span> warning · '
+        f'<span style="color:#64748B;font-weight:700;">{lia.n_info}</span> info'
+    )
+
+    if not lia.flags:
+        flag_html = (
+            '<div style="color:#059669;font-size:12px;padding:6px 0;">'
+            f'No liabilities flagged across {lia.checks_run} checks.</div>'
+        )
+    else:
+        items = ""
+        for f in lia.sorted_flags():
+            sc, sl = _SEV_STYLE.get(f.severity, ("#64748B", f.severity.title()))
+            loc = f'<span style="font-family:monospace;color:#94A3B8;font-size:10px;margin-left:6px;">{f.location}</span>' if f.location else ""
+            rec = f'<div style="font-size:11px;color:#64748B;margin-top:2px;">↳ {f.recommendation}</div>' if f.recommendation else ""
+            items += f"""
+            <div style="border-left:3px solid {sc};padding:6px 0 6px 10px;margin-bottom:8px;">
+                <div style="display:flex;align-items:baseline;gap:8px;">
+                    <span style="background:{sc};color:white;border-radius:3px;padding:1px 6px;
+                                 font-size:9px;text-transform:uppercase;font-weight:700;">{sl}</span>
+                    <span style="font-size:13px;font-weight:600;color:#0F172A;">{f.title}</span>
+                    {loc}
+                </div>
+                <div style="font-size:12px;color:#334155;margin-top:2px;">{f.detail}</div>
+                {rec}
+            </div>"""
+        flag_html = items
+
+    return pn.pane.HTML(f"""
+    <div style="border:1px solid #CBD5E1;border-radius:8px;padding:14px 16px;background:white;">
+        <div style="display:flex;align-items:center;gap:18px;flex-wrap:wrap;
+                    border-bottom:1px solid #E2E8F0;padding-bottom:10px;margin-bottom:10px;">
+            <div>
+                <div style="font-size:10px;color:#64748B;letter-spacing:.05em;">QC SCORE</div>
+                <div style="font-size:30px;font-weight:800;color:{score_color};line-height:1;">{lia.score}</div>
+            </div>
+            <div style="background:{vcolor};color:white;border-radius:6px;padding:6px 14px;
+                        font-size:14px;font-weight:800;letter-spacing:.05em;">{vlabel}</div>
+            <div style="font-size:12px;color:#475569;">{counts}</div>
+            <div style="font-size:11px;color:#94A3B8;margin-left:auto;">{lia.checks_run} checks</div>
+        </div>
+        {flag_html}
+    </div>
+    """)
+
+
 def _metric_panel(title: str, content: pn.viewable.Viewable) -> pn.Column:
     return pn.Column(
         pn.pane.HTML(
@@ -266,6 +375,11 @@ class AnalysisDashboard(param.Parameterized):
             ),
             pn.pane.HTML(warnings_html) if warnings_html else pn.pane.HTML(""),
             pn.pane.HTML(summary_html),
+            pn.pane.HTML(
+                '<div style="font-size:13px;font-weight:700;color:#0F172A;'
+                'margin:6px 0 6px 0;">Liability / QC assessment</div>'
+            ),
+            render_liability_panel(report),
             pn.layout.Divider(),
             _gc_plot(report),
             pn.GridBox(
@@ -274,6 +388,8 @@ class AnalysisDashboard(param.Parameterized):
                 _metric_panel("Kozak Context", _kozak_card(report)),
                 _metric_panel("Homopolymers", _homopolymer_card(report)),
                 _metric_panel("Restriction Sites", _restriction_card(report)),
+                _metric_panel("Uridine Content", _uridine_card(report)),
+                _metric_panel("Liability Motifs", _motif_card(report)),
                 _metric_panel("Secondary Structure (MFE)", _structure_card(report)),
                 ncols=2,
                 sizing_mode="stretch_width",

ui/components/cluster_view.py

@@ -0,0 +1,183 @@
+"""
+Cluster & tree explorer.
+
+Clusters the current worklist's sequences by k-mer distance and renders an
+interactive dendrogram (UPGMA tree) with a distance cutoff that splits the tree
+into flat clusters — an exploration view analogous to repertoire clustering.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List, Tuple
+
+import panel as pn
+import param
+import plotly.graph_objects as go
+
+from core.analysis.clustering import (
+    kmer_distance_matrix, upgma, flat_clusters, dendrogram_layout,
+)
+
+if TYPE_CHECKING:
+    from ui.state import AppState
+
+
+# Categorical palette for clusters (cycled)
+_PALETTE = [
+    "#0F766E", "#2563EB", "#D97706", "#DC2626", "#7C3AED",
+    "#059669", "#DB2777", "#0891B2", "#CA8A04", "#4F46E5",
+]
+
+
+def _empty(msg: str) -> pn.pane.HTML:
+    return pn.pane.HTML(f'<div style="color:#64748B;padding:30px;text-align:center;">{msg}</div>')
+
+
+class ClusterView(param.Parameterized):
+    """Worklist clustering + dendrogram panel."""
+
+    def __init__(self, state: "AppState", **params: object) -> None:
+        super().__init__(**params)
+        self._state = state
+        self._k = pn.widgets.IntSlider(
+            name="k-mer size", start=2, end=6, value=4, width=160, margin=(4, 10))
+        self._threshold = pn.widgets.FloatSlider(
+            name="Distance cutoff", start=0.0, end=1.0, step=0.02, value=0.30,
+            width=260, margin=(4, 10))
+        self._region = pn.widgets.Select(
+            name="Compare", options=["Full sequence", "CDS only"],
+            value="Full sequence", width=150, margin=(4, 10))
+
+    # ── data ────────────────────────────────────────────────────────────────
+    def _sequences(self) -> Tuple[List[str], List[str]]:
+        names: List[str] = []
+        seqs: List[str] = []
+        for item in self._state.worklist.items:
+            s = item.sequence
+            if self._region.value == "CDS only":
+                txt = s.cds or ""
+            else:
+                try:
+                    txt = s.assembled_sequence
+                except Exception:
+                    txt = s.cds or ""
+            if txt:
+                names.append(s.name)
+                seqs.append(txt)
+        return names, seqs
+
+    # ── rendering ─────────────────────────────────────────────────────────────
+    def _render(self, k: int, threshold: float, region: str) -> pn.viewable.Viewable:
+        names, seqs = self._sequences()
+        n = len(seqs)
+        if n < 2:
+            return _empty("Add at least 2 sequences (with content) to the worklist to cluster.")
+
+        D = kmer_distance_matrix(seqs, k=k)
+        link, order = upgma(D)
+        clusters = flat_clusters(link, n, threshold)
+        layout = dendrogram_layout(link, order)
+        n_clusters = len(set(clusters))
+
+        fig = go.Figure()
+
+        # dendrogram branches as a single trace (None-separated segments)
+        xs: List = []
+        ys: List = []
+        for (x0, x1, y0, y1) in layout.segments:
+            xs += [x0, x1, None]
+            ys += [y0, y1, None]
+        fig.add_trace(go.Scatter(
+            x=xs, y=ys, mode="lines",
+            line={"color": "#94A3B8", "width": 1.2},
+            hoverinfo="skip", showlegend=False,
+        ))
+
+        # cutoff line
+        fig.add_hline(
+            y=threshold, line_dash="dash", line_color="#DC2626", opacity=0.7,
+            annotation_text=f"cutoff {threshold:.2f}", annotation_position="top left",
+        )
+
+        # leaf markers grouped per cluster (legend = clusters)
+        for c in range(n_clusters):
+            cx = [layout.leaf_x[leaf] for leaf in order if clusters[leaf] == c]
+            ctext = [names[leaf] for leaf in order if clusters[leaf] == c]
+            if not cx:
+                continue
+            fig.add_trace(go.Scatter(
+                x=cx, y=[0] * len(cx), mode="markers",
+                marker={"size": 11, "color": _PALETTE[c % len(_PALETTE)],
+                        "line": {"color": "white", "width": 1}},
+                name=f"Cluster {c}", text=ctext,
+                hovertemplate="%{text}<br>cluster " + str(c) + "<extra></extra>",
+            ))
+
+        fig.update_layout(
+            title={"text": f"UPGMA dendrogram — {n} sequences, {n_clusters} cluster(s)",
+                   "font": {"size": 13}},
+            xaxis={"tickmode": "array",
+                   "tickvals": [layout.leaf_x[leaf] for leaf in order],
+                   "ticktext": [names[leaf] for leaf in order],
+                   "tickangle": -40, "tickfont": {"size": 10}},
+            yaxis={"title": "k-mer distance", "rangemode": "tozero"},
+            height=440, margin={"l": 60, "r": 20, "t": 40, "b": 130},
+            plot_bgcolor="#F8FAFC", paper_bgcolor="white",
+            legend={"orientation": "h", "y": -0.45, "font": {"size": 10}},
+        )
+
+        # cluster membership summary
+        groups: dict = {}
+        for leaf in order:
+            groups.setdefault(clusters[leaf], []).append(names[leaf])
+        rows = ""
+        for c in sorted(groups):
+            color = _PALETTE[c % len(_PALETTE)]
+            members = ", ".join(groups[c])
+            rows += (
+                f'<tr>'
+                f'<td style="padding:4px 10px;"><span style="display:inline-block;width:10px;'
+                f'height:10px;border-radius:2px;background:{color};margin-right:6px;"></span>'
+                f'Cluster {c}</td>'
+                f'<td style="padding:4px 10px;color:#475569;font-size:12px;">{len(groups[c])}</td>'
+                f'<td style="padding:4px 10px;color:#334155;font-size:12px;">{members}</td>'
+                f'</tr>'
+            )
+        table = pn.pane.HTML(
+            '<div style="font-size:12px;font-weight:700;margin:10px 0 4px 0;">Cluster membership</div>'
+            '<table style="border-collapse:collapse;width:100%;">'
+            '<tr style="border-bottom:1px solid #E2E8F0;font-size:11px;color:#64748B;">'
+            '<td style="padding:4px 10px;">Cluster</td><td style="padding:4px 10px;">Size</td>'
+            '<td style="padding:4px 10px;">Members</td></tr>'
+            f'{rows}</table>'
+        )
+
+        return pn.Column(pn.pane.Plotly(fig, sizing_mode="stretch_width"), table,
+                         sizing_mode="stretch_width")
+
+    @param.depends("_state.worklist")
+    def panel(self) -> pn.Column:
+        wl = self._state.worklist
+        if wl is None or wl.count == 0:
+            return pn.Column(
+                pn.pane.HTML('<div style="font-size:16px;font-weight:800;padding:8px 0;">'
+                             'Cluster &amp; Tree</div>'),
+                _empty("Worklist is empty. Import sequences to cluster them."),
+                styles={"padding": "8px 16px"},
+            )
+
+        controls = pn.Row(
+            self._region, self._k, self._threshold,
+            sizing_mode="stretch_width",
+            styles={"background": "#F8FAFC", "border": "1px solid #E2E8F0",
+                    "border-radius": "6px", "padding": "4px 8px", "margin": "0 0 8px 0"},
+        )
+        body = pn.bind(self._render, self._k, self._threshold, self._region)
+        return pn.Column(
+            pn.pane.HTML('<div style="font-size:16px;font-weight:800;padding:8px 0;">'
+                         f'Cluster &amp; Tree <span style="color:#64748B;font-size:13px;">'
+                         f'({wl.count} sequences)</span></div>'),
+            controls,
+            pn.panel(body),
+            sizing_mode="stretch_width",
+            styles={"padding": "8px 16px"},
+        )

ui/components/experiment_view.py

@@ -0,0 +1,197 @@
+"""
+Experiments / model lifecycle view.
+
+Surfaces the model lifecycle that sits on top of the registry:
+  - registered models and their versions,
+  - a run history (every scoring run, with version + score statistics),
+  - a run-vs-run comparison (e.g. two versions of the same model) showing how
+    per-sequence scores shifted.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Dict, List, Optional
+
+import panel as pn
+import param
+
+if TYPE_CHECKING:
+    from ui.state import AppState
+
+
+def _fmt(x: Optional[float]) -> str:
+    return "—" if x is None or (isinstance(x, float) and x != x) else f"{x:.3f}"
+
+
+class ExperimentView(param.Parameterized):
+    """Model lifecycle / experiment tracking panel."""
+
+    def __init__(self, state: "AppState", **params: object) -> None:
+        super().__init__(**params)
+        self._state = state
+        self._run_a = pn.widgets.Select(name="Run A (baseline)", width=320, margin=(4, 10))
+        self._run_b = pn.widgets.Select(name="Run B (compare)", width=320, margin=(4, 10))
+
+    # ── registered models ─────────────────────────────────────────────────────
+    def _models_table(self) -> pn.pane.HTML:
+        reg = self._state.model_registry
+        models = reg.all_models if reg else []
+        if not models:
+            return pn.pane.HTML('<div style="color:#64748B;font-size:12px;">No models registered yet.</div>')
+        rows = ""
+        for m in models:
+            try:
+                ver = m.model.version
+            except Exception:
+                ver = "—"
+            rows += (
+                f'<tr style="border-bottom:1px solid #F1F5F9;">'
+                f'<td style="padding:4px 10px;font-size:12px;">{m.model.name}</td>'
+                f'<td style="padding:4px 10px;font-size:12px;color:#475569;">{m.model_type}</td>'
+                f'<td style="padding:4px 10px;font-size:12px;"><span style="background:#F0FDFA;'
+                f'color:#0F766E;border-radius:3px;padding:1px 6px;">v{ver}</span></td>'
+                f'<td style="padding:4px 10px;font-size:12px;color:#64748B;">{m.source}</td>'
+                f'</tr>'
+            )
+        return pn.pane.HTML(
+            '<table style="border-collapse:collapse;width:100%;">'
+            '<tr style="font-size:11px;color:#64748B;border-bottom:1px solid #E2E8F0;">'
+            '<td style="padding:4px 10px;">Model</td><td style="padding:4px 10px;">Type</td>'
+            '<td style="padding:4px 10px;">Version</td><td style="padding:4px 10px;">Source</td></tr>'
+            f'{rows}</table>'
+        )
+
+    # ── run history ───────────────────────────────────────────────────────────
+    def _runs_table(self) -> pn.pane.HTML:
+        runs = self._state.run_history.runs
+        if not runs:
+            return pn.pane.HTML(
+                '<div style="color:#64748B;font-size:12px;">No runs yet. Score a worklist '
+                'with a model (Worklist → Run) to record an experiment.</div>'
+            )
+        rows = ""
+        for r in reversed(runs):  # newest first
+            rows += (
+                f'<tr style="border-bottom:1px solid #F1F5F9;">'
+                f'<td style="padding:4px 10px;font-size:11px;color:#64748B;">{r.timestamp}</td>'
+                f'<td style="padding:4px 10px;font-size:12px;">{r.model_name}</td>'
+                f'<td style="padding:4px 10px;font-size:12px;">v{r.model_version}</td>'
+                f'<td style="padding:4px 10px;font-size:12px;">{r.n_sequences}</td>'
+                f'<td style="padding:4px 10px;font-size:12px;">{_fmt(r.score_mean)}</td>'
+                f'<td style="padding:4px 10px;font-size:12px;color:#64748B;">'
+                f'{_fmt(r.score_min)}–{_fmt(r.score_max)}</td>'
+                f'<td style="padding:4px 10px;font-size:11px;color:#94A3B8;">{r.worklist_name}</td>'
+                f'</tr>'
+            )
+        return pn.pane.HTML(
+            '<table style="border-collapse:collapse;width:100%;">'
+            '<tr style="font-size:11px;color:#64748B;border-bottom:1px solid #E2E8F0;">'
+            '<td style="padding:4px 10px;">Time</td><td style="padding:4px 10px;">Model</td>'
+            '<td style="padding:4px 10px;">Version</td><td style="padding:4px 10px;">N</td>'
+            '<td style="padding:4px 10px;">Mean</td><td style="padding:4px 10px;">Range</td>'
+            '<td style="padding:4px 10px;">Worklist</td></tr>'
+            f'{rows}</table>'
+        )
+
+    # ── comparison ────────────────────────────────────────────────────────────
+    def _run_options(self) -> Dict[str, object]:
+        return {f"{r.run_id} · {r.label}": r.run_id for r in reversed(self._state.run_history.runs)}
+
+    def _name_lookup(self) -> Dict[str, str]:
+        names: Dict[str, str] = {}
+        for item in self._state.worklist.items:
+            names[item.sequence.id] = item.sequence.name
+        return names
+
+    def _render_comparison(self, run_a_id: str, run_b_id: str) -> pn.viewable.Viewable:
+        from models.runs import RunHistory
+        runs = {r.run_id: r for r in self._state.run_history.runs}
+        ra, rb = runs.get(run_a_id), runs.get(run_b_id)
+        if not ra or not rb:
+            return pn.pane.HTML('<div style="color:#64748B;font-size:12px;">Pick two runs to compare.</div>')
+        if ra.run_id == rb.run_id:
+            return pn.pane.HTML('<div style="color:#64748B;font-size:12px;">Pick two different runs.</div>')
+
+        cmp = RunHistory.compare(ra, rb)
+        if not cmp.shared_ids:
+            return pn.pane.HTML(
+                '<div style="color:#D97706;font-size:12px;">No shared sequences between these runs.</div>'
+            )
+        d = cmp.mean_delta
+        dcolor = "#059669" if d > 0 else "#DC2626" if d < 0 else "#64748B"
+        summary = pn.pane.HTML(f"""
+            <div style="display:flex;gap:18px;align-items:center;flex-wrap:wrap;
+                        border:1px solid #E2E8F0;border-radius:8px;padding:10px 14px;margin:6px 0;">
+                <div><div style="font-size:10px;color:#64748B;">MEAN Δ (B − A)</div>
+                     <div style="font-size:22px;font-weight:800;color:{dcolor};">{d:+.3f}</div></div>
+                <div style="font-size:12px;color:#059669;">▲ {cmp.n_improved} improved</div>
+                <div style="font-size:12px;color:#DC2626;">▼ {cmp.n_worsened} worsened</div>
+                <div style="font-size:12px;color:#64748B;">= {cmp.n_unchanged} unchanged</div>
+                <div style="font-size:11px;color:#94A3B8;margin-left:auto;">
+                    {len(cmp.shared_ids)} shared sequences</div>
+            </div>
+        """)
+
+        names = self._name_lookup()
+        ordered = sorted(cmp.deltas.items(), key=lambda kv: kv[1])  # worst→best
+        rows = ""
+        for sid, delta in ordered[:50]:
+            c = "#059669" if delta > 0 else "#DC2626" if delta < 0 else "#64748B"
+            nm = names.get(sid, sid[:8])
+            rows += (
+                f'<tr style="border-bottom:1px solid #F1F5F9;">'
+                f'<td style="padding:3px 10px;font-size:12px;">{nm}</td>'
+                f'<td style="padding:3px 10px;font-size:12px;color:#64748B;">{_fmt(ra.scores.get(sid))}</td>'
+                f'<td style="padding:3px 10px;font-size:12px;color:#64748B;">{_fmt(rb.scores.get(sid))}</td>'
+                f'<td style="padding:3px 10px;font-size:12px;font-weight:700;color:{c};">{delta:+.3f}</td>'
+                f'</tr>'
+            )
+        table = pn.pane.HTML(
+            '<table style="border-collapse:collapse;width:100%;">'
+            '<tr style="font-size:11px;color:#64748B;border-bottom:1px solid #E2E8F0;">'
+            '<td style="padding:3px 10px;">Sequence</td>'
+            f'<td style="padding:3px 10px;">A (v{ra.model_version})</td>'
+            f'<td style="padding:3px 10px;">B (v{rb.model_version})</td>'
+            '<td style="padding:3px 10px;">Δ</td></tr>'
+            f'{rows}</table>'
+        )
+        return pn.Column(summary, table, sizing_mode="stretch_width")
+
+    # ── panel ─────────────────────────────────────────────────────────────────
+    @param.depends("_state.run_history", "_state.model_registry")
+    def panel(self) -> pn.Column:
+        # refresh comparison dropdown options
+        opts = self._run_options()
+        self._run_a.options = opts
+        self._run_b.options = opts
+        run_ids = list(opts.values())
+        if len(run_ids) >= 2:
+            self._run_a.value = run_ids[1]   # older of the two newest
+            self._run_b.value = run_ids[0]   # newest
+        elif run_ids:
+            self._run_a.value = self._run_b.value = run_ids[0]
+
+        comparison = pn.bind(self._render_comparison, self._run_a, self._run_b)
+
+        def card(title: str, body: pn.viewable.Viewable) -> pn.Column:
+            return pn.Column(
+                pn.pane.HTML(f'<div style="font-size:13px;font-weight:700;margin:6px 0;">{title}</div>'),
+                body,
+                styles={"background": "white", "border": "1px solid #CBD5E1",
+                        "border-radius": "8px", "padding": "12px 14px"},
+                margin=(0, 0, 12, 0), sizing_mode="stretch_width",
+            )
+
+        return pn.Column(
+            pn.pane.HTML(
+                '<div style="font-size:16px;font-weight:800;padding:8px 0 2px 0;">Experiments</div>'
+                '<div style="font-size:12px;color:#64748B;margin-bottom:10px;">'
+                'Model versions, scoring-run history, and version-to-version comparison.</div>'
+            ),
+            card("Registered models", self._models_table()),
+            card("Run history", self._runs_table()),
+            card("Compare runs (version A → B)",
+                 pn.Column(pn.Row(self._run_a, self._run_b), pn.panel(comparison),
+                           sizing_mode="stretch_width")),
+            sizing_mode="stretch_width",
+            styles={"padding": "8px 16px", "max-height": "78vh", "overflow-y": "auto"},
+        )

ui/components/worklist_view.py

@@ -55,11 +55,17 @@ class WorklistView(param.Parameterized):
                 row["CAI"] = f"{base.get('cai', 0):.3f}" if base.get('cai') else "—"
                 row["Homopolymers"] = base.get('homopolymer_count', 0)
                 row["Restriction Sites"] = base.get('restriction_site_count', 0)
+                verdict = base.get('liability_verdict')
+                score = base.get('liability_score')
+                row["QC"] = f"{verdict.title()} · {score}" if verdict is not None else "—"
+                row["Liabilities"] = base.get('liability_flag_count', 0) if base.get('liability_flag_count') is not None else "—"
             else:
                 row["GC%"] = "—"
                 row["CAI"] = "—"
                 row["Homopolymers"] = "—"
                 row["Restriction Sites"] = "—"
+                row["QC"] = "—"
+                row["Liabilities"] = "—"
 
             # Add model score columns from analyses
             for analysis_name, analysis_data in item.analyses.items():
@@ -262,10 +268,39 @@ class WorklistView(param.Parameterized):
             self._create_wl_section,
             pn.pane.HTML(f'<div style="margin-bottom:8px;">{origin_chips}</div>') if origin_chips else pn.pane.HTML(""),
             table_or_empty,
+            self._liability_detail,
             sizing_mode="stretch_width",
             styles={"padding": "8px 16px"},
         )
 
+    @param.depends("_state.active_sequence")
+    def _liability_detail(self) -> pn.viewable.Viewable:
+        """Liability / QC breakdown for the currently selected sequence."""
+        seq = self._state.active_sequence
+        if seq is None:
+            return pn.pane.HTML(
+                '<div style="color:#94A3B8;font-size:12px;padding:10px 2px;">'
+                'Click a row to see its liability / QC breakdown.</div>'
+            )
+        try:
+            from core.analysis.analyzer import SequenceAnalyzer
+            from ui.components.analysis_dashboard import render_liability_panel
+
+            report = SequenceAnalyzer().run_full_analysis(seq)
+            return pn.Column(
+                pn.pane.HTML(
+                    f'<div style="font-size:13px;font-weight:700;margin:10px 0 6px 0;">'
+                    f'Liabilities — {seq.name}</div>'
+                ),
+                render_liability_panel(report),
+                sizing_mode="stretch_width",
+            )
+        except Exception as e:  # noqa: BLE001 — surface any analysis error inline
+            return pn.pane.HTML(
+                f'<div style="color:#DC2626;font-size:12px;padding:8px 0;">'
+                f'Liability analysis error: {e}</div>'
+            )
+
     def _create_worklist_from_selection(self, name: str, selection: List[int], df: pd.DataFrame) -> None:
         """Create a new worklist from selected rows."""
         if not selection:
@@ -380,7 +415,41 @@ class WorklistView(param.Parameterized):
                 item.status = "error"
                 item.notes = f"{model_name}: {str(e)}"
 
+        # Record this scoring run for experiment / version tracking
+        self._record_run(model_reg)
+
         self._state.param.trigger("worklist")
         self._state.set_status(
             f"{model_name} complete: {analyzed_count} scored, {skipped_count} skipped (already scored)"
         )
+
+    def _record_run(self, model_reg: object) -> None:
+        """Capture a ModelRun snapshot of the current scores for this model."""
+        from datetime import datetime
+        from models.runs import summarize_run
+
+        name = model_reg.model.name
+        # gather all current scores for this model across the worklist
+        scores = {}
+        for item in self._state.worklist.items:
+            data = item.analyses.get(name)
+            if isinstance(data, dict) and "score" in data:
+                scores[item.sequence.id] = data["score"]
+        if not scores:
+            return
+
+        try:
+            version = model_reg.model.version
+        except Exception:
+            version = "1.0"
+
+        run = summarize_run(
+            model_name=name,
+            model_version=str(version),
+            model_source=getattr(model_reg, "source", ""),
+            worklist_name=self._state.worklist.name,
+            scores=scores,
+            timestamp=datetime.now().strftime("%Y-%m-%d %H:%M:%S"),
+        )
+        self._state.run_history.add(run)
+        self._state.param.trigger("run_history")

ui/state.py

@@ -21,6 +21,7 @@ from core.models.worklist import Worklist
 from core.models.parts import SequencePart
 from core.database.base import DatabaseConnector, SchemaMapper
 from models.base import ModelRegistry
+from models.runs import RunHistory
 
 
 class AppState(param.Parameterized):
@@ -68,6 +69,12 @@ class AppState(param.Parameterized):
         instantiate=True,
     )
 
+    # ── Experiment / run history (model lifecycle) ─────────────────────────────
+    run_history: RunHistory = param.ClassSelector(
+        class_=RunHistory, default=None, allow_None=False,
+        instantiate=True,
+    )
+
     # ── Plasmid backbones ─────────────────────────────────────────────────────
     backbone_library: List[PlasmidBackbone] = param.List(
         default=[], doc="Available plasmid backbones"
@@ -97,6 +104,8 @@ class AppState(param.Parameterized):
             params["worklist"] = Worklist()
         if "model_registry" not in params:
             params["model_registry"] = ModelRegistry()
+        if "run_history" not in params:
+            params["run_history"] = RunHistory()
         super().__init__(**params)
 
         # Load seed parts library if parts_library is empty