basic functionalities

.gitignore

@@ -3,3 +3,4 @@ __pycache__/
 .venv/
 venv/
 .env
+saved_models/

app.py

@@ -1,11 +1,85 @@
 import os
+import threading
+import time
+import uuid
 
+import numpy as np
 from flask import Flask, jsonify, render_template, request
 
 from pipeline import run_pipeline
+from utils.genome_neighbor_retrieval import GenomeNeighborRetriever
+from utils.protein_neighbor_retrieval import ProteinNeighborRetriever
+from utils.gene_context_retrieval import GeneContextRetriever
+from utils.synteny import build_synteny, neighbor_track, query_track
 
 app = Flask(__name__)
 
+# Background neighbor-search jobs: the imgvr_inphared indexes are large
+# enough (GB-scale, network-mounted) that a cold search can take tens of
+# seconds, so /analyze starts them and returns immediately; the frontend
+# polls /job/<id> (same pattern as phlam-demo's HOMOLOGY_JOBS/NEIGHBOR_JOBS).
+JOBS = {}
+_JOBS_LOCK = threading.Lock()
+
+# Query genome data kept for a later /synteny call (embeddings aren't sent
+# back to the client, so they're cached here keyed by analysis_id).
+ANALYSES = {}
+
+_genome_retriever = None
+_protein_retriever = None
+_gene_context_retriever = None
+
+
+def _get_genome_retriever():
+    global _genome_retriever
+    if _genome_retriever is None:
+        _genome_retriever = GenomeNeighborRetriever()
+    return _genome_retriever
+
+
+def _get_protein_retriever():
+    global _protein_retriever
+    if _protein_retriever is None:
+        _protein_retriever = ProteinNeighborRetriever()
+    return _protein_retriever
+
+
+def _get_gene_context_retriever():
+    global _gene_context_retriever
+    if _gene_context_retriever is None:
+        _gene_context_retriever = GeneContextRetriever()
+    return _gene_context_retriever
+
+
+def _prune(store, keep=8):
+    if len(store) <= keep:
+        return
+    stale = sorted(store, key=lambda k: store[k]["created"])[:-keep]
+    for k in stale:
+        store.pop(k, None)
+
+
+def _run_job(job_id, fn):
+    job = JOBS.get(job_id)
+    if job is None:
+        return
+    try:
+        job["result"] = fn()
+        job["status"] = "done"
+    except Exception as e:
+        print(f"[job {job_id}] failed: {e}")
+        job["status"] = "error"
+        job["error"] = str(e)
+
+
+def _start_job(fn):
+    job_id = uuid.uuid4().hex
+    JOBS[job_id] = {"status": "pending", "result": None, "error": None, "created": time.time()}
+    with _JOBS_LOCK:
+        _prune(JOBS)
+    threading.Thread(target=_run_job, args=(job_id, fn), daemon=True).start()
+    return job_id
+
 
 @app.route("/", methods=["GET"])
 def index():
@@ -23,9 +97,54 @@ def analyze():
     except Exception as e:
         print(f"[analyze] unexpected failure: {e}")
         return jsonify({"error": "Analysis failed -- check server logs."}), 500
+
+    esm_embeds = result.pop("esm_embeds")
+    phlam_protein = result.pop("phlam_protein")
+    phlam_genome = np.asarray(result["phlam_genome"], dtype=np.float32)[None, :]
+
+    analysis_id = uuid.uuid4().hex
+    ANALYSES[analysis_id] = {
+        "genome_name": result["genome_name"], "genome_length": result["genome_length"], "genes": result["genes"],
+        "esm_embeds": esm_embeds, "phlam_protein": phlam_protein, "created": time.time(),
+    }
+    with _JOBS_LOCK:
+        _prune(ANALYSES)
+
+    jobs = {
+        "genome_neighbors": _start_job(lambda: _get_genome_retriever().query(phlam_genome)[0]),
+        "protein_neighbors": _start_job(lambda: _get_protein_retriever().query(esm_embeds)),
+        "gene_context_neighbors": _start_job(lambda: _get_gene_context_retriever().query(phlam_protein)),
+    }
+    result["analysis_id"] = analysis_id
+    result["jobs"] = jobs
     return jsonify(result)
 
 
+@app.route("/synteny", methods=["POST"])
+def synteny():
+    data = request.get_json(silent=True) or {}
+    analysis = ANALYSES.get(data.get("analysis_id"))
+    if analysis is None:
+        return jsonify({"error": "analysis expired -- re-run the analysis"}), 404
+    genome_ids = [int(g) for g in data.get("genome_ids", [])][:11]  # query + up to 11 neighbors
+
+    def run():
+        tracks = [query_track(analysis["genome_name"], analysis["genome_length"], analysis["genes"],
+                               analysis["esm_embeds"], analysis["phlam_protein"])]
+        tracks += [neighbor_track(gid) for gid in genome_ids]
+        return build_synteny(tracks)
+
+    return jsonify({"job": _start_job(run)})
+
+
+@app.route("/job/<job_id>", methods=["GET"])
+def job_status(job_id):
+    job = JOBS.get(job_id)
+    if job is None:
+        return jsonify({"status": "unknown"}), 404
+    return jsonify({"status": job["status"], "result": job["result"], "error": job["error"]})
+
+
 if __name__ == "__main__":
     port = int(os.environ.get("PORT", "7860"))
     debug = os.environ.get("FLASK_DEBUG", "0").lower() in ("1", "true", "yes")

phlam/attention.py

@@ -0,0 +1,275 @@
+import math
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+
+N_POS_BUCKETS = 65   # 32 left + 32 right + 1 sink
+
+# Strand/relation categories (DeBERTa-style vector bias, see RelationalBias in model.py).
+# opp_far splits off convergent/divergent once the pair is farther apart than
+# opp_far_dist, so "these are opposite-strand and close" stays a distinct signal
+# from "these are opposite-strand and it barely matters".
+SAME, CONVERGENT, DIVERGENT, OPP_FAR, GLOBAL, SINK = range(6)
+N_STRAND_CATEGORIES = 6
+
+
+class GenomicDistanceBucketeer(nn.Module):
+    """
+    Maps distance magnitudes (in gene count, not bp) to bucket indices: linear
+    resolution near zero, geometric growth out to max_dist, last bucket is a
+    pure overflow catch-all. Boundaries are derived from (n_bins, max_dist)
+    rather than hardcoded, so every bucket stays reachable if max_dist is
+    retuned -- a previous hardcoded version silently went stale when the
+    model's default max_dist changed and some boundaries fell out of range.
+    """
+    def __init__(self, n_bins: int = 32, max_dist: int = 600, n_linear: int = 8):
+        super().__init__()
+        self.n_bins   = n_bins
+        self.max_dist = max_dist
+        self.register_buffer(
+            "boundaries", self._build_boundaries(n_bins, max_dist, n_linear)
+        )
+
+    @staticmethod
+    def _build_boundaries(n_bins: int, max_dist: int, n_linear: int) -> torch.Tensor:
+        n_boundaries = n_bins - 1                       # last bin index is the overflow catch-all
+        n_linear     = min(n_linear, n_boundaries - 1)   # leave room for >=1 geometric step
+
+        # Per-gene resolution starting at 1 (not 0 -- see class docstring).
+        linear = list(range(1, n_linear + 1))
+
+        n_geo     = n_boundaries - n_linear
+        geo_start = n_linear + 1
+        if n_geo > 0 and max_dist > geo_start:
+            geo = torch.exp(torch.linspace(math.log(geo_start), math.log(max_dist), n_geo))
+            geo = torch.round(geo)
+            for i in range(1, len(geo)):   # guard against rounding collisions at small n_geo
+                if geo[i] <= geo[i - 1]:
+                    geo[i] = geo[i - 1] + 1
+            geo = geo.tolist()
+        else:
+            geo = []
+
+        boundaries = torch.tensor(linear + geo, dtype=torch.float32)
+        return boundaries[:n_boundaries]
+
+    def forward(self, abs_diff: torch.Tensor) -> torch.Tensor:
+        buckets      = torch.bucketize(abs_diff.float(), self.boundaries, right=True)
+        is_over_max  = abs_diff >= self.max_dist
+        dist_buckets = torch.where(is_over_max, self.n_bins - 1, buckets)
+        return dist_buckets.clamp(0, self.n_bins - 1).long()
+
+
+def compute_genomic_bias_indices(strand_ids, mask, is_circular, bucketeer, opp_far_dist: float = 16.0):
+    """
+    Computes pos_buckets [B,S,S] (for the additive positional bias) and
+    orient_cats [B,S,S] (for the DeBERTa-style strand RelationalBias) in one pass, since both
+    depend on the same topo_diff / is_protein bookkeeping.
+
+    pos_buckets (65 entries): signed genomic offset.
+      Buckets  0-31: key is LEFT  (topo_diff <= 0)
+      Buckets 32-63: key is RIGHT (topo_diff >  0)
+      Bucket     64: SINK — non-protein pairs
+
+    orient_cats (6 entries):
+      0: SAME        FF or RR
+      1: CONVERGENT  >< — left gene fwd, |topo_diff| < opp_far_dist
+      2: DIVERGENT   <> — left gene rev, |topo_diff| < opp_far_dist
+      3: OPP_FAR     opposite strands but farther apart than opp_far_dist
+      4: GLOBAL      CLS-to-anything pairs
+      5: SINK        strand-masked, padding
+    """
+    N_SIGNED = 64
+    POS_SINK  = 64
+
+    is_protein = (strand_ids > 0) & (strand_ids < 3) & mask.bool()
+    positions   = torch.cumsum(is_protein.long(), dim=-1).float()
+    linear_diff = positions.unsqueeze(2) - positions.unsqueeze(1)
+
+    gen_sizes     = is_protein.sum(dim=-1, keepdim=True).unsqueeze(-1).float().clamp(min=1)
+    circular_diff = (linear_diff + gen_sizes / 2) % gen_sizes - gen_sizes / 2
+
+    ic        = is_circular.view(-1, 1, 1) if is_circular.dim() >= 1 \
+                else is_circular.view(1, 1, 1)
+    topo_diff = torch.where(ic.bool(), circular_diff, linear_diff)
+
+    s_q = strand_ids.unsqueeze(2)   # [B, S, 1]
+    s_k = strand_ids.unsqueeze(1)   # [B, 1, S]
+
+    pp = is_protein.unsqueeze(2) & is_protein.unsqueeze(1)
+
+    safe_abs    = torch.where(pp, topo_diff.abs(),
+                              torch.full_like(topo_diff, float(bucketeer.max_dist)))
+    mag         = bucketeer(safe_abs)
+    sign_off    = (topo_diff > 0).long() * (N_SIGNED // 2)
+    pos_buckets = (mag + sign_off).masked_fill(~pp, POS_SINK)
+
+    known      = lambda s: (s == 1) | (s == 2)
+    both_known = known(s_q) & known(s_k) & pp
+    opp        = both_known & (s_q != s_k)
+    is_far     = topo_diff.abs() >= opp_far_dist
+
+    query_is_left = topo_diff < 0
+    left_is_fwd   = torch.where(query_is_left, s_q == 1, s_k == 1)
+
+    orient_cats = pos_buckets.new_full(pos_buckets.shape, SINK)
+    orient_cats.masked_fill_(both_known & ~opp,             SAME)
+    orient_cats.masked_fill_(opp & ~is_far & left_is_fwd,    CONVERGENT)
+    orient_cats.masked_fill_(opp & ~is_far & ~left_is_fwd,   DIVERGENT)
+    orient_cats.masked_fill_(opp & is_far,                   OPP_FAR)
+    # GLOBAL applied last to override any accidental overlap with CLS pairs.
+    orient_cats.masked_fill_((s_q == 3) | (s_k == 3), GLOBAL)
+
+    return pos_buckets, orient_cats
+
+
+def _relation_scores(content: torch.Tensor, rel_vecs: torch.Tensor, cats: torch.Tensor,
+                      content_is_col: bool) -> torch.Tensor:
+    """
+    Shared building block for c2p/p2c: dots per-head content vectors against a
+    small per-category table, then gathers by category index. Cheaper than
+    materializing a full [B,H,S,S,d_k] tensor since there are only a handful
+    of relation categories.
+
+    content:  [B, H, S, d_k]   query content for c2p (indexed by row/query pos),
+                                key content for p2c (indexed by col/key pos)
+    rel_vecs: [H, n_cat, d_k]  category vectors, already head-projected
+    cats:     [B, S, S]        category index per (row=query, col=key) pair
+    content_is_col: False for c2p (content indexed by row i, broadcast over col j),
+                    True  for p2c (content indexed by col j, broadcast over row i)
+    returns:  [B, H, S, S]
+    """
+    B, H, S, _ = content.shape
+    n_cat = rel_vecs.shape[1]
+    per_cat = torch.einsum('bhsd,hcd->bhsc', content, rel_vecs)   # [B, H, S, n_cat]
+    if content_is_col:
+        per_cat = per_cat.unsqueeze(2).expand(B, H, S, S, n_cat)   # [B, H, S(row), S(col=s), n_cat]
+    else:
+        per_cat = per_cat.unsqueeze(3).expand(B, H, S, S, n_cat)   # [B, H, S(row=s), S(col), n_cat]
+    idx = cats.unsqueeze(1).unsqueeze(-1).expand(B, H, S, S, 1)
+    return torch.gather(per_cat, -1, idx).squeeze(-1)
+
+
+class GenomicSelfAttention(nn.Module):
+    """
+    Multi-head self-attention with two DeBERTa-style disentangled bias channels
+    (strand/relation and distance), computed once per forward pass at the
+    model level and threaded through every layer:
+
+      scores = QK/sqrt(d_k)
+              + sigmoid(gate_c2p_strand) * c2p_strand
+              + sigmoid(gate_p2c_strand) * p2c_strand                   (DeBERTa strand/relation)
+              + sigmoid(gate_c2p_pos)    * c2p_pos
+              + sigmoid(gate_p2c_pos)    * p2c_pos                      (DeBERTa distance)
+
+    No plain T5-style scalar-per-bucket scaffold: it reliably won the gradient
+    race over c2p_pos/p2c_pos, starving the content-gated channel of pressure
+    to learn real content-dependent distance expectations (e.g. a portal
+    protein expecting a head-scaffolding protein at a fixed offset, which a
+    different protein type at the same offset shouldn't care about).
+
+    c2p is query-content-gated, p2c is key-content-gated -- see RelationalBias
+    for why the category embeddings are projected through this layer's own
+    q_proj/k_proj rather than being a standalone lookup.
+    """
+
+    def __init__(self, d_model: int, num_heads: int, dropout: float = 0.0):
+        super().__init__()
+        assert d_model % num_heads == 0
+        self.num_heads = num_heads
+        self.d_k       = d_model // num_heads
+
+        self.q_proj    = nn.Linear(d_model, d_model, bias=False)
+        self.k_proj    = nn.Linear(d_model, d_model, bias=False)
+        self.v_proj    = nn.Linear(d_model, d_model, bias=False)
+        self.out_proj  = nn.Linear(d_model, d_model)
+        self.bias_drop = nn.Dropout(dropout)
+
+        # Diagnostic-only: when True, forward() records per-head realized-influence
+        # stats (gate * bias term, masked-mean-abs) for _log_bias_diagnostics to read.
+        # Left False during normal training so the hot path (and torch.compile) never
+        # sees this branch; a dedicated uncompiled diagnostic forward flips it on.
+        self.record_influence   = False
+        self.last_influence_strand = None   # set to a detached [H] tensor when recording
+        self.last_influence_pos    = None
+
+    def forward(self, x, mask, external_bias, output_attentions=False):
+        if external_bias is None:
+            raise ValueError("external_bias dict is required.")
+
+        B, S, D   = x.shape
+        amp_dtype = x.dtype
+
+        pos_buckets  = external_bias["pos_buckets"]            # [B, S, S], long bucket index
+        orient_c     = external_bias["orient_cats"]            # [B, S, S], long strand-category index
+        strand_k     = external_bias["strand_key_embed"]       # [n_strand_cat, D], raw (unprojected)
+        strand_q     = external_bias["strand_query_embed"]     # [n_strand_cat, D], raw (unprojected)
+        pos_k        = external_bias["pos_key_embed"]          # [n_pos_buckets, D], raw (unprojected)
+        pos_q        = external_bias["pos_query_embed"]        # [n_pos_buckets, D], raw (unprojected)
+        gate_c2p_s   = external_bias["rel_gate_c2p_strand"]    # [H]
+        gate_p2c_s   = external_bias["rel_gate_p2c_strand"]    # [H]
+        gate_c2p_p   = external_bias["rel_gate_c2p_pos"]       # [H]
+        gate_p2c_p   = external_bias["rel_gate_p2c_pos"]       # [H]
+
+        def split_heads(t):
+            return t.reshape(B, S, self.num_heads, self.d_k).transpose(1, 2)
+
+        q = split_heads(self.q_proj(x))
+        k = split_heads(self.k_proj(x))
+        v = split_heads(self.v_proj(x))
+
+        content_scores = torch.matmul(q, k.transpose(-2, -1)) / math.sqrt(self.d_k)
+
+        def split_heads_cat(t, n_cat):
+            # t: [n_cat, D] -> [H, n_cat, d_k], independent of the sequence-level B/S.
+            return t.reshape(n_cat, self.num_heads, self.d_k).transpose(0, 1)
+
+        n_strand_cat = strand_k.shape[0]
+        k_rel_s = split_heads_cat(self.k_proj(strand_k), n_strand_cat)   # [H, n_strand_cat, d_k]
+        q_rel_s = split_heads_cat(self.q_proj(strand_q), n_strand_cat)   # [H, n_strand_cat, d_k]
+
+        n_pos_cat = pos_k.shape[0]
+        k_rel_p = split_heads_cat(self.k_proj(pos_k), n_pos_cat)   # [H, n_pos_buckets, d_k]
+        q_rel_p = split_heads_cat(self.q_proj(pos_q), n_pos_cat)   # [H, n_pos_buckets, d_k]
+
+        c2p_strand = _relation_scores(q, k_rel_s, orient_c,    content_is_col=False) / math.sqrt(self.d_k)
+        p2c_strand = _relation_scores(k, q_rel_s, orient_c,    content_is_col=True)  / math.sqrt(self.d_k)
+        c2p_pos    = _relation_scores(q, k_rel_p, pos_buckets, content_is_col=False) / math.sqrt(self.d_k)
+        p2c_pos    = _relation_scores(k, q_rel_p, pos_buckets, content_is_col=True)  / math.sqrt(self.d_k)
+
+        rel_bias_strand = (
+            gate_c2p_s.sigmoid().view(1, -1, 1, 1) * c2p_strand +
+            gate_p2c_s.sigmoid().view(1, -1, 1, 1) * p2c_strand
+        )
+        rel_bias_pos = (
+            gate_c2p_p.sigmoid().view(1, -1, 1, 1) * c2p_pos +
+            gate_p2c_p.sigmoid().view(1, -1, 1, 1) * p2c_pos
+        )
+        rel_bias = rel_bias_strand + rel_bias_pos
+
+        scores = content_scores + self.bias_drop(rel_bias.to(amp_dtype))
+
+        mask_bool = mask.bool()
+        key_invalid = ~mask_bool.unsqueeze(1).unsqueeze(2)
+        scores = scores.masked_fill(key_invalid, torch.finfo(amp_dtype).min)
+
+        if self.record_influence:
+            # Realized per-head contribution: gate * bias term, masked-mean-abs over
+            # valid key positions. This is the "what it actually does" figure, as
+            # opposed to the gate alone ("what it wants") — not equivalent to
+            # gate-mean * term-norm-mean since both vary per head.
+            with torch.no_grad():
+                valid_key = mask_bool.to(rel_bias_strand.dtype).unsqueeze(1).unsqueeze(2)  # [B,1,1,S]
+                denom = valid_key.sum().clamp(min=1)
+                self.last_influence_strand = (rel_bias_strand.detach().abs() * valid_key).sum(dim=(0, 2, 3)) / denom
+                self.last_influence_pos    = (rel_bias_pos.detach().abs()    * valid_key).sum(dim=(0, 2, 3)) / denom
+
+        attn = F.softmax(scores, dim=-1)
+        out  = torch.matmul(attn, v)
+        out  = out * mask_bool.unsqueeze(1).unsqueeze(-1)
+        out  = out.transpose(1, 2).reshape(B, S, D)
+
+        # No separate diagnostic softmax needed: scores are already just
+        # content_scores + rel_bias (no T5 scalar to isolate against), so
+        # attn itself is the "content+relational" view.
+        return self.out_proj(out), (attn if output_attentions else None)

phlam/model.py

@@ -0,0 +1,277 @@
+import torch
+import torch.nn as nn
+import torch.nn.functional as F
+from phlam.attention import (
+    GenomicSelfAttention, GenomicDistanceBucketeer,
+    N_POS_BUCKETS, N_STRAND_CATEGORIES,
+    compute_genomic_bias_indices,
+)
+
+class ProjectionHead(nn.Module):
+    """
+    Semi-orthogonal (Stiefel-constrained) linear map: guarantees
+    ||proj(x) - proj(y)|| == ||x - y|| exactly, for any pair, by
+    construction -- not encouraged by a loss, structurally true regardless
+    of batch composition. When d_model > d_in this leaves d_model - d_in
+    output dimensions exactly zero at the projection itself; downstream
+    attention/FFN layers are unconstrained and free to populate them,
+    keeping content preservation and context integration as separate jobs
+    instead of one layer having to trade off between them.
+    """
+    def __init__(self, d_in: int, d_model: int):
+        super().__init__()
+        self.net = nn.Linear(d_in, d_model, bias=False)
+        #nn.utils.parametrizations.orthogonal(self.net, name="weight")
+    def forward(self, x): return self.net(x)
+
+class ProteomeReconHead(nn.Module):
+    def __init__(self, d_model: int, d_out: int):
+        super().__init__()
+        self.net = nn.Sequential(
+            nn.Linear(d_model, d_model), nn.ELU(),
+            nn.Linear(d_model, d_out),
+        )
+    def forward(self, x): return self.net(x)
+
+
+class PhyloInitializer(nn.Module):
+    """Cross-attention seeding the CLS token from the protein sequence."""
+    def __init__(self, d_model: int):
+        super().__init__()
+        self.q     = nn.Linear(d_model, d_model, bias=False)
+        self.k     = nn.Linear(d_model, d_model, bias=False)
+        self.v     = nn.Linear(d_model, d_model, bias=False)
+        self.scale = d_model ** -0.5
+        self.ln    = nn.LayerNorm(d_model)
+
+    def forward(self, phylo_token, h_p, mask):
+        q    = self.q(phylo_token)
+        k    = self.k(h_p)
+        v    = self.v(h_p)
+        attn = torch.matmul(q, k.transpose(-1, -2)) * self.scale
+        attn = attn.masked_fill(~mask.bool().unsqueeze(1), torch.finfo(attn.dtype).min)
+        return self.ln(phylo_token + torch.matmul(F.softmax(attn, dim=-1), v))
+
+
+class StrandPredHead(nn.Module):
+    """Predicts whether this position's fed-in strand_id was flipped (0=native, 1=flipped)."""
+    def __init__(self, d_model: int):
+        super().__init__()
+        self.norm   = nn.LayerNorm(d_model)
+        self.linear = nn.Linear(d_model, 2)
+
+    def forward(self, x: torch.Tensor) -> torch.Tensor:
+        return self.linear(self.norm(x))
+
+
+
+class RelationalBias(nn.Module):
+    """
+    DeBERTa-style disentangled bias table, shared shape for both channels that
+    use it: strand/relation (categories = same/convergent/divergent/opp_far/
+    global/sink) and distance (categories = signed position buckets). Holds one
+    d_model vector per category for each of the c2p (query-gated) and p2c
+    (key-gated) channels. Each attention layer projects these through its own
+    q_proj/k_proj so the vectors are entangled with content rather than being
+    a content-free shortcut — the actual per-head dot products happen inside
+    GenomicSelfAttention.
+    """
+    def __init__(self, n_categories: int, d_model: int):
+        super().__init__()
+        self.key_embed   = nn.Embedding(n_categories, d_model)   # dotted against queries (c2p)
+        self.query_embed = nn.Embedding(n_categories, d_model)   # dotted against keys (p2c)
+        # Small init (std=0.002) plus the -2.0 gate init
+        # means the relational term starts near-silent and only grows once content
+        # attention is stable, per the "gates fade in after content stabilizes" design.
+        nn.init.normal_(self.key_embed.weight,   std=0.002)
+        nn.init.normal_(self.query_embed.weight, std=0.002)
+
+    def forward(self):
+        return self.key_embed.weight, self.query_embed.weight
+
+
+class GenomicTransformerBlock(nn.Module):
+    def __init__(self, d_model: int, num_heads: int, dropout: float = 0.2):
+        super().__init__()
+        self.attn = GenomicSelfAttention(d_model=d_model, num_heads=num_heads, dropout=dropout)
+        self.ln1  = nn.LayerNorm(d_model)
+        self.ln2  = nn.LayerNorm(d_model)
+        self.ff   = nn.Sequential(
+            nn.Linear(d_model, 4 * d_model), nn.GELU(),
+            nn.Linear(4 * d_model, d_model), nn.Dropout(dropout),
+        )
+
+    def forward(self, x, mask, output_attentions=False, external_bias=None):
+        res, weights = self.attn(self.ln1(x), mask, external_bias=external_bias, output_attentions=output_attentions)
+        x = x + res
+        x = x + self.ff(self.ln2(x))
+        x = x * mask.bool().unsqueeze(-1)   # prevent FFN bias accumulation at padding slots
+        return x, weights
+
+
+class PHLAM(nn.Module):
+    """
+    Genomic LM for phage proteomes with a strand-flip-detection auxiliary task.
+
+    Strand IDs: 0=padding, 1=fwd, 2=rev, 3=CLS. The trainer may feed a corrupted
+    strand_id (1<->2 flipped) at a random subset of positions; the model has no
+    way to tell from strand_id alone, so strand_pred_head must catch the flip
+    from context (local synteny/orientation grammar), not from the label itself.
+    """
+
+    def __init__(
+        self,
+        input_dim:  int   = 480,
+        d_model:    int   = 512,
+        output_dim: int   = 480,
+        num_global: int   = 1,
+        num_layers: int   = 6,
+        num_heads:  int   = 8,
+        max_dist:   int   = 300,
+        opp_far_dist: float = 16.0,
+        dropout:    float = 0.2,
+    ):
+        super().__init__()
+        self.G         = num_global
+        self.num_heads = num_heads
+
+        # Both fixed, not learnable: a trainable placeholder has a direct
+        # gradient path to collapse toward the conditional mean of the target
+        # distribution instead of forcing genuine context-based inference.
+        # esm_mask_token is input_dim space (gene-dropout augmentation, see
+        # trainer.py's augment()); esm_bert_mask is d_model space, post-
+        # projection (BERT-style corruption_mask substitution below).
+        self.register_buffer("esm_mask_token", torch.zeros(1, 1, input_dim))
+        self.register_buffer("esm_bert_mask",  torch.zeros(1, 1, d_model))
+
+        # Skip the projection when dims match: identity preserves ESM's own
+        # basis exactly, not just its geometry -- the strongest possible
+        # guarantee against losing what ESM learned.
+        self.projection = nn.Identity() if input_dim == d_model else ProjectionHead(input_dim, d_model)
+        self.reconstruct_esm    = ProteomeReconHead(d_model, output_dim)
+        self.strand_pred_head   = StrandPredHead(d_model)
+        self.cls_token          = nn.Parameter(torch.randn(1, num_global, d_model) * 0.02)
+        self.phylo_init         = PhyloInitializer(d_model=d_model)
+
+        self.layers = nn.ModuleList([
+            GenomicTransformerBlock(d_model=d_model, num_heads=num_heads, dropout=dropout)
+            for _ in range(num_layers)
+        ])
+
+        self.bucketeer     = GenomicDistanceBucketeer(n_bins=32, max_dist=max_dist)
+        self.opp_far_dist  = opp_far_dist
+        self.strand_bias   = RelationalBias(N_STRAND_CATEGORIES, d_model)
+        # No plain T5-style scalar scaffold: it reliably won the gradient race
+        # over c2p_pos/p2c_pos (pos_layer_scale saturating almost everywhere),
+        # starving the content-gated channel of pressure to learn real
+        # content-dependent distance expectations.
+        self.pos_rel_bias = RelationalBias(N_POS_BUCKETS, d_model)
+
+        # Per-layer, per-head sigmoid gates, split by direction (c2p = query-
+        # driven, p2c = key-driven) and channel (strand vs. distance) so each
+        # can fade in independently. Init negative so gates open only after
+        # content attention stabilizes.
+        self.rel_gate_c2p_strand = nn.Parameter(torch.full((num_layers, num_heads), -2.0))
+        self.rel_gate_p2c_strand = nn.Parameter(torch.full((num_layers, num_heads), -2.0))
+        self.rel_gate_c2p_pos    = nn.Parameter(torch.full((num_layers, num_heads), -2.0))
+        self.rel_gate_p2c_pos    = nn.Parameter(torch.full((num_layers, num_heads), -2.0))
+
+    def forward(
+        self,
+        strand_ids:        torch.Tensor,
+        esm_embeds:        torch.Tensor,
+        is_circular:       float = 1.0,
+        output_attentions: bool  = False,
+        corruption_mask:   torch.Tensor | None = None,
+    ) -> dict:
+        B, L, _ = esm_embeds.shape
+        device   = esm_embeds.device
+
+        is_circular_tensor = torch.as_tensor(is_circular, device=device, dtype=torch.float32)
+        protein_mask = (strand_ids == 1) | (strand_ids == 2)
+
+        # Project in float32: ESM embeddings are compact unit-sphere vectors (~0.05/dim)
+        # where bf16's 7-bit mantissa loses meaningful precision. Transformer layers
+        # downstream run in bf16 via the outer autocast context.
+        with torch.amp.autocast(device_type=device.type, enabled=False):
+            x = self.projection(esm_embeds.float())   # [B, L, d_model] float32
+        projected = x   # clean, pre-corruption, pre-transformer -- returned for representation-depth analysis
+
+        # Apply BERT mask token before seeding CLS so CLS never sees clean
+        # content of masked positions — avoids a shortcut where masked tokens
+        # can attend to CLS and recover their original embedding.
+        # Without a corruption_mask (e.g. view-2, ae-mode) x stays clean.
+        if corruption_mask is not None:
+            x = torch.where(
+                corruption_mask.unsqueeze(-1).expand_as(x),
+                self.esm_bert_mask.expand(B, L, -1),
+                x,
+            )
+
+        # Seed CLS from (possibly corrupted) projections.
+        # At 15% masking 85% of proteins are still visible — enough signal
+        # for a good phylogenetic summary without leaking masked content.
+        cls = self.phylo_init(
+            self.cls_token.expand(B, -1, -1), x, mask=protein_mask
+        )
+
+        x_combined    = torch.cat([cls, x], dim=1)
+        combined_mask = torch.cat([
+            torch.ones(B, self.G, dtype=torch.bool, device=device),
+            protein_mask,
+        ], dim=1)
+        strands_plus  = torch.cat([
+            torch.full((B, self.G), 3, dtype=torch.long, device=device),
+            strand_ids.long(),
+        ], dim=1)
+
+        # Bucket/category indices computed once; shared across all layers.
+        pos_buckets, orient_cats = compute_genomic_bias_indices(
+            strands_plus, combined_mask, is_circular_tensor, self.bucketeer,
+            opp_far_dist=self.opp_far_dist,
+        )
+        strand_key_embed, strand_query_embed = self.strand_bias()     # each [n_strand_cat, D]
+        pos_key_embed, pos_query_embed       = self.pos_rel_bias()    # each [n_pos_buckets, D]
+
+        all_attentions = []
+        for li, layer in enumerate(self.layers):
+            x_combined, layer_attn = layer(
+                x_combined, combined_mask,
+                output_attentions=output_attentions,
+                external_bias={
+                    "pos_buckets":         pos_buckets,
+                    "orient_cats":         orient_cats,
+                    "strand_key_embed":    strand_key_embed,
+                    "strand_query_embed":  strand_query_embed,
+                    "pos_key_embed":       pos_key_embed,
+                    "pos_query_embed":     pos_query_embed,
+                    "rel_gate_c2p_strand": self.rel_gate_c2p_strand[li],
+                    "rel_gate_p2c_strand": self.rel_gate_p2c_strand[li],
+                    "rel_gate_c2p_pos":    self.rel_gate_c2p_pos[li],
+                    "rel_gate_p2c_pos":    self.rel_gate_p2c_pos[li],
+                },
+            )
+            if output_attentions and layer_attn is not None:
+                all_attentions.append(layer_attn)
+
+        h_global_tokens = x_combined[:, :self.G, :]
+        h_protein       = x_combined[:, self.G:, :]
+        h_global        = h_global_tokens.squeeze(1) if self.G == 1 else h_global_tokens.mean(1)
+        recon_esm       = self.reconstruct_esm(h_protein)
+        # h_protein only, not h_protein+h_global: h_global is already derived
+        # from h_protein, and every position already reaches genome-level
+        # context via CLS through ordinary self-attention across layers --
+        # adding the same h_global vector to every position again here would
+        # be a redundant, per-genome-constant signal that StrandPredHead's
+        # LayerNorm would partly normalize away regardless.
+        strand_logits   = self.strand_pred_head(h_protein)
+
+        return {
+            "recon_esm":     recon_esm,
+            "strand_logits": strand_logits,
+            "h_protein":     h_protein,
+            "h_global":      h_global,
+            "projected":     projected,
+            "attentions":    tuple(all_attentions) if output_attentions else None,
+            "mask":          protein_mask,
+        }

pipeline.py

@@ -11,12 +11,14 @@ from utils.gene_caller import call_genes
 from utils.esm_embedder import ESM2Embedder
 from utils.ncbi_retrieval import fetch_ncbi_accession
 from utils.annotation_retrieval import AnnotationRetriever
+from utils.phlam_embedder import PHLAMEmbedder
 
 ESM_MODEL_NAME = os.environ.get("ESM_MODEL", "facebook/esm2_t12_35M_UR50D")
 MIN_GENE_LEN = int(os.environ.get("MIN_GENE_LEN", "60"))
 ACCESSION_MAX_LEN = 12
 
 _esm_embedder = None
+_phlam_embedder = None
 _annotation_retriever = None
 
 
@@ -27,6 +29,13 @@ def _get_esm():
     return _esm_embedder
 
 
+def _get_phlam():
+    global _phlam_embedder
+    if _phlam_embedder is None:
+        _phlam_embedder = PHLAMEmbedder(device="cpu")
+    return _phlam_embedder
+
+
 def _get_annotation_retriever():
     # Not cached on failure -- the mounted bucket may not be attached yet.
     global _annotation_retriever
@@ -87,6 +96,9 @@ def run_pipeline(raw_input: str, is_circular: bool = True) -> dict:
     protein_seqs = df["sequence"].tolist()
     esm_embeds = _get_esm().get_embeddings(protein_seqs).numpy()
 
+    phlam = _get_phlam().embed(esm_embeds, df["strand"].tolist(), is_circular=is_circular)
+    phlam_protein = phlam["phlam_protein"]  # [L, 480], one row per gene, same order as df
+
     try:
         retriever = _get_annotation_retriever()
         annotations = retriever.query(esm_embeds)
@@ -95,7 +107,7 @@ def run_pipeline(raw_input: str, is_circular: bool = True) -> dict:
         annotations = [{"top_hit": None, "other_source_hit": None}] * len(df)
 
     gene_records = []
-    for row, annotation in zip(df.to_dict(orient="records"), annotations):
+    for row, annotation, protein_vec in zip(df.to_dict(orient="records"), annotations, phlam_protein):
         gene_records.append({
             "id": row["readable_gene_id"],
             "order": row["order"],
@@ -108,6 +120,7 @@ def run_pipeline(raw_input: str, is_circular: bool = True) -> dict:
             "length_bp": row["length_bp"],
             "sequence": row["sequence"],
             "annotation": annotation,
+            "phlam_protein": protein_vec.tolist(),
         })
 
     return {
@@ -116,4 +129,9 @@ def run_pipeline(raw_input: str, is_circular: bool = True) -> dict:
         "genome_length": len(sequence),
         "num_genes": len(gene_records),
         "genes": gene_records,
+        "phlam_genome": phlam["phlam_genome"].tolist(),
+        # not for display -- raw arrays for app.py to reuse starting the
+        # neighbor-search background jobs without recomputing embeddings.
+        "esm_embeds": esm_embeds,
+        "phlam_protein": phlam_protein,
     }

requirements.txt

@@ -8,3 +8,4 @@ pyrodigal>=3.0
 torch
 transformers>=4.40
 faiss-cpu>=1.8
+duckdb>=1.0

static/circular-viewer.css

@@ -0,0 +1,208 @@
+/* PHLAM circular genome viewer — scoped variables + tooltip.
+   Prefixed --phlam-* custom properties avoid clashing with the host
+   Gradio page's own theme variables (this file is loaded inside the
+   viewer's own iframe document, but kept prefixed regardless). */
+:root {
+  --phlam-bg:      #FCFBF9;
+  --phlam-surface: #F2F0EC;
+  --phlam-muted:   #5C584F;
+  --phlam-accent:  oklch(0.48 0.11 195);
+  --phlam-fwd:     oklch(0.48 0.11 195);
+  --phlam-rev:     oklch(0.5 0.13 25);
+  --phlam-warn:    oklch(0.55 0.13 75);
+  --phlam-pass:    oklch(0.48 0.11 195);
+  --phlam-text:    #191A19;
+  --phlam-border:  #D6D0C4;
+}
+
+[data-phlam-theme="dark"] {
+  --phlam-bg:      #12151a;
+  --phlam-surface: #1c2129;
+  --phlam-muted:   #7d8794;
+  --phlam-accent:  #5ec8f8;
+  --phlam-fwd:     #55c58a;
+  --phlam-rev:     #e0736b;
+  --phlam-warn:    #e0b04b;
+  --phlam-pass:    #55c58a;
+  --phlam-text:    #e7ebf0;
+  --phlam-border:  #2c333d;
+}
+
+.phlam-gv-outer {
+  display: flex;
+  align-items: flex-start;
+  gap: 12px;
+}
+
+.phlam-gv-wrap {
+  display: flex;
+  justify-content: center;
+  background: var(--phlam-bg);
+  border: 1px solid var(--phlam-border);
+  border-radius: 8px;
+  padding: 8px;
+  flex: 1 1 auto;
+  min-width: 0; /* allow the flex item to shrink below the SVG's intrinsic width */
+}
+
+.phlam-gv-wrap svg {
+  max-width: 100%;
+  height: auto;
+}
+
+/* Tooltip -- a permanent in-flow side panel next to the chart, at a fixed
+   spot (not position:fixed, not following the mouse). Its content swaps on
+   hover/pin; it never disappears or resizes the layout. */
+.gv-tooltip {
+  flex: 0 0 320px;
+  width: 320px;
+  align-self: flex-start;
+  padding: 12px 14px;
+  background: var(--phlam-surface);
+  border: 1px solid var(--phlam-border);
+  border-radius: 8px;
+  color: var(--phlam-text);
+  font-family: "Azeret Mono", ui-monospace, monospace;
+  font-size: 13.5px;
+  line-height: 1.55;
+  box-sizing: border-box;
+}
+
+.gv-tooltip--pinned {
+  border-color: var(--phlam-accent);
+  border-width: 1.5px;
+}
+
+.gv-tt-placeholder {
+  color: var(--phlam-muted);
+  font-size: 13px;
+}
+
+.gv-tt-title {
+  font-weight: 700;
+  font-size: 15px;
+  margin-bottom: 5px;
+  word-break: break-all;
+}
+
+.gv-tt-loc {
+  color: var(--phlam-muted);
+  margin-bottom: 6px;
+}
+
+.gv-tt-annot-axis {
+  padding: 6px 6px 2px;
+  margin-bottom: 8px;
+  border: 1px solid var(--phlam-accent);
+  border-radius: 6px;
+  /* One tier lighter than .gv-tt-annot-item's own --phlam-bg, so the
+     category/annotation item boxes still stand out inside this axis box
+     instead of blending into it. */
+  background: var(--phlam-surface);
+}
+
+.gv-tt-annot-axis:last-child {
+  margin-bottom: 0;
+}
+
+.gv-tt-annot-axis-label {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: 6px;
+  margin: 0 0 4px;
+  font-size: 11.5px;
+  font-weight: 700;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+  color: var(--phlam-accent);
+}
+
+.gv-tt-annot-axis-meta {
+  font-weight: 500;
+  text-transform: none;
+  letter-spacing: normal;
+  color: var(--phlam-muted);
+  font-size: 11px;
+}
+
+.gv-tt-annot-conf {
+  font-weight: 600;
+}
+
+.gv-tt-annot-conf-high {
+  color: var(--phlam-pass);
+}
+
+.gv-tt-annot-conf-mid {
+  color: var(--phlam-warn);
+}
+
+.gv-tt-annot-conf-low {
+  color: var(--phlam-rev);
+}
+
+.gv-tt-annot-group {
+  margin-bottom: 8px;
+}
+
+.gv-tt-annot-item {
+  padding: 4px 7px;
+  margin-bottom: 4px;
+  background: var(--phlam-bg);
+  border: 1px solid var(--phlam-border);
+  border-radius: 5px;
+}
+
+.gv-tt-annot-item:last-child {
+  margin-bottom: 0;
+}
+
+.gv-tt-annot-item.gv-tt-annot-unresolved {
+  opacity: 0.55;
+}
+
+.gv-tt-annot-item.gv-tt-annot-unresolved .gv-tt-annot-text {
+  font-style: italic;
+}
+
+.gv-tt-annot-level {
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.03em;
+  color: var(--phlam-muted);
+  margin-bottom: 2px;
+}
+
+.gv-tt-annot-text {
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+  gap: 8px;
+  font-size: 13.5px;
+}
+
+.gv-tt-annot-sim {
+  flex: 0 0 auto;
+  color: var(--phlam-muted);
+  font-size: 11.5px;
+}
+
+.gv-tt-row {
+  display: flex;
+  justify-content: space-between;
+  gap: 10px;
+  color: var(--phlam-text);
+}
+
+.gv-tt-row span:first-child {
+  color: var(--phlam-muted);
+}
+
+.gv-tt-pin {
+  margin-top: 8px;
+  padding-top: 6px;
+  border-top: 1px dashed var(--phlam-border);
+  color: var(--phlam-muted);
+  font-size: 11.5px;
+}

static/circular_genome_viewer.js

@@ -0,0 +1,542 @@
+// Shared with static/genome-viewer.js's PHLAM_PALETTE/phlamHashColor -- same
+// palette + same djb2 hash-of-the-annotation-string means a given annotation
+// (e.g. "endolysin") gets the identical color in both the circular view and
+// the synteny view, since neither view's local set of categories affects it
+// (unlike an ordinal scale keyed to sort- or appearance-order, which would
+// reassign colors whenever the surrounding category set changes).
+const PHLAM_PALETTE = [
+  'oklch(0.62 0.11 195)', 'oklch(0.62 0.11 25)', 'oklch(0.55 0.09 260)',
+  'oklch(0.62 0.11 140)', 'oklch(0.65 0.13 60)', 'oklch(0.55 0.10 320)',
+  'oklch(0.62 0.11 90)', 'oklch(0.58 0.12 350)', 'oklch(0.6 0.08 220)',
+  'oklch(0.65 0.12 10)', 'oklch(0.6 0.1 170)', 'oklch(0.55 0.11 290)',
+  'oklch(0.68 0.1 40)', 'oklch(0.58 0.09 240)', 'oklch(0.6 0.12 110)',
+  'oklch(0.5 0.08 200)',
+];
+const PHLAM_UNANNOTATED_COLOR = '#C9C4BB';
+
+function phlamHashColor(str, palette = PHLAM_PALETTE) {
+  if (!str || str === 'unannotated' || str === 'no annotation') return PHLAM_UNANNOTATED_COLOR;
+  let h = 5381;
+  for (let i = 0; i < str.length; i++) h = ((h << 5) + h + str.charCodeAt(i)) | 0;
+  return palette[Math.abs(h) % palette.length];
+}
+
+class CircularGenomeViewer {
+  constructor(svgId, options = {}) {
+    this.svgId = svgId;
+    this.W = options.width || 700;
+    this.H = options.height || 700;
+    this.R = options.radius || 260;
+    this.rH = options.trackWidth || 16;
+    this.HEAD_RAD = 0.075;
+    this.globalAttentionData = null;
+
+    // Interaction state
+    this._pinnedGeneIdx = null;
+    this._clickTimer = null;
+    this._lastClickedIdx = null;
+    this._geneNodes = [];
+
+    this.svg = d3.select(`#${this.svgId}`).attr('width', this.W).attr('height', this.H);
+    this.g = this.svg.append('g').attr('transform', `translate(${this.W / 2},${this.H / 2})`);
+
+    const defs = this.svg.append('defs');
+    defs.append('marker')
+      .attr('id', 'arrowhead')
+      .attr('markerWidth', 10)
+      .attr('markerHeight', 10)
+      .attr('refX', 8)
+      .attr('refY', 3)
+      .attr('orient', 'auto')
+      .append('polygon')
+      .attr('points', '0 0, 10 3, 0 6')
+      .attr('fill', 'var(--phlam-accent)');
+
+    this.chordG = this.g.append('g').attr('class', 'chord-layer');
+    this.axisG = this.g.append('g').attr('class', 'axis-layer');
+    this.geneG = this.g.append('g').attr('class', 'gene-layer');
+    this.labelG = this.g.append('g').attr('class', 'label-layer');
+    this.legendG = this.g.append('g').attr('class', 'legend-layer');
+
+    this._initTooltip();
+
+    // Click on SVG background unpins
+    const self = this;
+    this.svg.on('click', () => {
+      if (self._pinnedGeneIdx !== null) {
+        const node = self._geneNodes[self._pinnedGeneIdx];
+        if (node) d3.select(node).attr('fill-opacity', 0.85);
+        self._pinnedGeneIdx = null;
+        self._hideTooltip();
+        self._restoreChords();
+      }
+    });
+
+    this.genomeData = null;
+  }
+
+  // ── Tooltip ──────────────────────────────────────────────────────────────
+  // A permanent in-flow side panel (not position:fixed) at a fixed spot next
+  // to the chart -- never follows the mouse, and never needs viewport-size
+  // math (which broke once this chart started living inside a tightly-sized
+  // iframe with no guaranteed empty space around it).
+
+  _initTooltip() {
+    if (!document.getElementById('gv-tooltip')) {
+      const el = document.createElement('div');
+      el.id = 'gv-tooltip';
+      el.className = 'gv-tooltip';
+      const host = this.svg.node().closest('.phlam-gv-outer') || this.svg.node().parentNode || document.body;
+      host.appendChild(el);
+    }
+    this.tipEl = document.getElementById('gv-tooltip');
+    this._placeholderHtml = this.tipEl.innerHTML || '<div class="gv-tt-placeholder">Hover a protein for details.<br>Double-click any protein to copy the full gene table.</div>';
+    this._hideTooltip();
+  }
+
+  _showTooltip(html, pinned = false) {
+    this.tipEl.innerHTML = html;
+    this.tipEl.classList.toggle('gv-tooltip--pinned', pinned);
+    this._resizeFrame();
+  }
+
+  _hideTooltip() {
+    this.tipEl.innerHTML = this._placeholderHtml;
+    this.tipEl.classList.remove('gv-tooltip--pinned');
+    this._resizeFrame();
+  }
+
+  // The host <iframe> (viewer.py's srcdoc) starts at a fixed height from
+  // Python; the tooltip's content varies a lot per protein (how many
+  // annotation axes/homology hits resolved, how long the text wraps), so
+  // rather than ever risk this document's own scrollbar appearing, resize
+  // the iframe itself to match its actual content height after every
+  // change. srcdoc with no sandbox attribute is same-origin, so
+  // window.frameElement reaches the real <iframe> node in the parent page.
+  //
+  // Deliberately measures .phlam-gv-outer (the actual content wrapper), NOT
+  // document.documentElement/body: the root element's scrollHeight is
+  // max(content height, current viewport height) per spec, and the "current
+  // viewport height" of an iframe IS whatever height the parent last set it
+  // to -- so measuring the root turns every call into a ratchet that only
+  // ever grows (each call's floor is the previous call's result, plus the
+  // +4 padding on top of that): +8px on every single hover-in/hover-out
+  // pair, forever, never shrinking back down.
+  _resizeFrame() {
+    if (window.frameElement) {
+      const content = this.svg.node().closest('.phlam-gv-outer');
+      const h = content ? content.scrollHeight : document.body.scrollHeight;
+      window.frameElement.style.height = (h + 4) + 'px';
+    }
+  }
+
+  // ── Chord helpers ─────────────────────────────────────────────────────────
+
+  _dimChordsExcept(i) {
+    // Hover: fade non-connected chords to hint
+    this.svg.selectAll('.chord').attr('stroke-opacity', 0.03);
+    this.svg.selectAll(`.chord-i-${i}`).attr('stroke-opacity', function () {
+      return +d3.select(this).attr('data-base-opacity');
+    });
+  }
+
+  _isolateChordsFor(i) {
+    // Pin: show only ego-network edges (direct ins + outs), hide everything else
+    this.svg.selectAll('.chord').attr('stroke-opacity', 0);
+    this.svg.selectAll(`.chord-i-${i}`).attr('stroke-opacity', function () {
+      return +d3.select(this).attr('data-base-opacity');
+    });
+  }
+
+  _restoreChords() {
+    this.svg.selectAll('.chord').attr('stroke-opacity', function () {
+      return +d3.select(this).attr('data-base-opacity');
+    });
+  }
+
+  // ── Clipboard ─────────────────────────────────────────────────────────────
+
+  _copyGeneFasta(gn) {
+    let header = `>${gn.id} # ${gn.start} # ${gn.end} # ${gn.strand}`;
+    // PHLAM's only annotation signal is the flat ESM-homology block (gn.homology,
+    // built by viewer.py) -- there is no gn.annotation here (that hierarchical
+    // category/leaf shape belongs to the sibling genome_view project this
+    // viewer was adapted from, and PHLAM never populates it), so the FASTA
+    // header must be built from the same fields the hover tooltip already
+    // reads at gn.homology.{topHit,otherTopHit,majorityVote}.
+    const h = gn.homology;
+    if (h) {
+      const hit = (key, label) => {
+        const entry = h[key];
+        if (!entry) return;
+        const pct = entry.score != null ? (entry.score * 100).toFixed(0) : '';
+        header += ` # ${label}=${entry.text}` + (entry.source ? ` # ${label}_source=${entry.source}` : '')
+          + (entry.id ? ` # ${label}_id=${entry.id}` : '')
+          + (pct ? ` # ${label}_match=${pct}%` : '');
+      };
+      hit('topHit', 'top_hit');
+      hit('otherTopHit', 'other_top_hit');
+      if (h.majorityVote) {
+        const frac = h.majorityVote.voteFrac != null ? (h.majorityVote.voteFrac * 100).toFixed(0) : '';
+        header += ` # majority_vote=${h.majorityVote.text}` + (h.majorityVote.id ? ` # majority_vote_id=${h.majorityVote.id}` : '')
+          + (frac ? ` # majority_vote_agree=${frac}%` : '');
+      }
+    }
+    const text = `${header}\n${gn.sequence || ''}`;
+    const flash = (html) => {
+      const prev = this.tipEl.innerHTML;
+      this.tipEl.innerHTML = html;
+      setTimeout(() => { this.tipEl.innerHTML = prev; }, 1400);
+    };
+    const onCopied = () => flash('<div class="gv-tt-title" style="color:var(--phlam-pass)">✓ Protein FASTA copied</div>');
+    const onFailed = () => flash('<div class="gv-tt-title" style="color:var(--phlam-rev)">Copy failed — clipboard unavailable</div>');
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      navigator.clipboard.writeText(text).then(onCopied, () => this._legacyCopy(text) ? onCopied() : onFailed());
+    } else {
+      this._legacyCopy(text) ? onCopied() : onFailed();
+    }
+  }
+
+  // Fallback for contexts where the async Clipboard API is unavailable or
+  // denied (e.g. some sandboxed/cross-origin iframe embeddings) -- a
+  // synchronous execCommand('copy') off a throwaway textarea still works
+  // there since it runs inside the same user-gesture (dblclick) call stack.
+  _legacyCopy(text) {
+    try {
+      const ta = document.createElement('textarea');
+      ta.value = text;
+      ta.style.position = 'fixed';
+      ta.style.opacity = '0';
+      document.body.appendChild(ta);
+      ta.focus();
+      ta.select();
+      const ok = document.execCommand('copy');
+      document.body.removeChild(ta);
+      return ok;
+    } catch (e) {
+      return false;
+    }
+  }
+
+  // ── Legend ───────────────────────────────────────────────────────────────
+
+  _renderLegend(label, lo, hi, colorScale) {
+    const w = 150, h = 11, y = this.H / 2 - 36, x = -w / 2;
+    const gradId = 'phlam-legend-gradient';
+    const defs = this.svg.select('defs');
+    defs.select(`#${gradId}`).remove();
+    const grad = defs.append('linearGradient').attr('id', gradId).attr('x1', '0%').attr('x2', '100%');
+    d3.range(0, 1.0001, 0.1).forEach(t => {
+      grad.append('stop').attr('offset', `${t * 100}%`).attr('stop-color', colorScale(lo + t * (hi - lo)));
+    });
+
+    const legend = this.legendG.append('g').attr('transform', `translate(0, ${y})`);
+    legend.append('text').attr('x', 0).attr('y', -7).attr('text-anchor', 'middle')
+      .attr('fill', 'var(--phlam-muted)').attr('font-size', '11')
+      .attr('font-family', "'Azeret Mono', monospace").text(label);
+    legend.append('rect').attr('x', x).attr('y', 0).attr('width', w).attr('height', h)
+      .attr('fill', `url(#${gradId})`).attr('stroke', 'var(--phlam-border)').attr('stroke-width', 0.75);
+    legend.append('text').attr('x', x).attr('y', h + 14).attr('text-anchor', 'start')
+      .attr('fill', 'var(--phlam-muted)').attr('font-size', '10.5')
+      .attr('font-family', "'Azeret Mono', monospace").text(lo.toFixed(2));
+    legend.append('text').attr('x', x + w).attr('y', h + 14).attr('text-anchor', 'end')
+      .attr('fill', 'var(--phlam-muted)').attr('font-size', '10.5')
+      .attr('font-family', "'Azeret Mono', monospace").text(hi.toFixed(2));
+  }
+
+  // ── Render ────────────────────────────────────────────────────────────────
+
+  renderGenome(genomeData, colorMetric = null) {
+    this.genomeData = genomeData;
+    const { genomeSize, genes } = genomeData;
+
+    // Reset interaction state on each render
+    this._pinnedGeneIdx = null;
+    this._geneNodes = [];
+    if (this._clickTimer) { clearTimeout(this._clickTimer); this._clickTimer = null; }
+    this._hideTooltip();
+
+    this.axisG.selectAll('*').remove();
+    this.geneG.selectAll('*').remove();
+    this.labelG.selectAll('*').remove();
+    this.legendG.selectAll('*').remove();
+    this.chordG.selectAll('.global-attn-arrow').remove();
+
+    if (!genomeSize || !genes) return;
+
+    const R = this.R, rH = this.rH, HEAD_RAD = this.HEAD_RAD;
+    const ang = pos => (pos / genomeSize) * Math.PI * 2 - Math.PI / 2;
+    const pt = (r, a) => [Math.cos(a) * r, Math.sin(a) * r];
+
+    // Strand ('strand' mode, the default) keeps the categorical fwd/rev
+    // colors below; any other mode drives fill color from a per-gene metric
+    // instead (continuous: sequential scale + gradient legend; categorical,
+    // e.g. annotation category/subcategory: ordinal scale + swatch legend)
+    // -- gene shape/arrow direction still encodes strand regardless, so no
+    // information is lost by repurposing color.
+    let colorScale = null;
+    if (colorMetric && colorMetric.values && colorMetric.values.length === genes.length) {
+      if (colorMetric.type === 'categorical') {
+        colorScale = phlamHashColor;
+        // No swatch legend here: the categorical case is annotation text,
+        // often dozens of distinct values -- genes still get distinct
+        // colors per annotation, but a legend listing them all isn't
+        // usable. Hover tooltip still shows each gene's own annotation.
+      } else {
+        const [lo, hi] = colorMetric.domain || d3.extent(colorMetric.values);
+        colorScale = d3.scaleSequential(d3.interpolatePlasma).domain([lo, hi === lo ? lo + 1 : hi]);
+        this._renderLegend(colorMetric.label, lo, hi, colorScale);
+      }
+    }
+
+    // Background ring
+    this.axisG.append('circle').attr('r', R).attr('fill', 'none')
+      .attr('stroke', 'var(--phlam-surface)').attr('stroke-width', rH * 2 + 6);
+
+    // Tick marks
+    d3.range(8).forEach(i => {
+      const a = (i / 8) * Math.PI * 2 - Math.PI / 2;
+      const pos = Math.round((i / 8) * genomeSize);
+      const lbl = pos >= 1e6 ? (pos / 1e6).toFixed(1) + 'M' : pos >= 1e3 ? (pos / 1e3).toFixed(0) + 'k' : pos;
+      const r1 = R + rH + 5, r2 = r1 + 10;
+      this.axisG.append('line')
+        .attr('x1', Math.cos(a) * r1).attr('y1', Math.sin(a) * r1)
+        .attr('x2', Math.cos(a) * r2).attr('y2', Math.sin(a) * r2)
+        .attr('stroke', 'var(--phlam-muted)').attr('stroke-width', 1);
+      if (i > 0) this.axisG.append('text')
+        .attr('x', Math.cos(a) * (r2 + 12)).attr('y', Math.sin(a) * (r2 + 12))
+        .attr('text-anchor', 'middle').attr('dominant-baseline', 'middle')
+        .attr('fill', 'var(--phlam-muted)').attr('font-size', '11')
+        .attr('font-family', "'Azeret Mono', monospace").text(lbl);
+    });
+
+    this.geneElements = [];
+
+    const self = this;
+    genes.forEach((gn, i) => {
+      const isFwd = gn.strand === '+' || gn.strand === 1;
+      let color = gn.color;
+      if (!color) {
+        if (colorScale) color = colorScale(colorMetric.values[i]);
+        else if (gn.partial) color = 'var(--phlam-warn)';
+        else color = isFwd ? 'var(--phlam-fwd)' : 'var(--phlam-rev)';
+      }
+
+      const geneRH = rH;
+      const gStart = gn.start;
+      const angS = ang(gStart), angE = ang(gn.end);
+      const span = angE - angS;
+      const headA = Math.min(HEAD_RAD, Math.abs(span) * 0.4);
+      const bodyEnd = isFwd ? angE - headA : angS + headA;
+
+      let pathD;
+      if (isFwd) {
+        const p = [pt(R + geneRH, angS), pt(R + geneRH, bodyEnd), pt(R + geneRH + geneRH * .9, bodyEnd),
+          pt(R, angE), pt(R - geneRH - geneRH * .9, bodyEnd), pt(R - geneRH, bodyEnd), pt(R - geneRH, angS)];
+        pathD = `M${p[0]} A${R + geneRH},${R + geneRH} 0 0,1 ${p[1]} L${p[2]} L${p[3]} L${p[4]} L${p[5]} A${R - geneRH},${R - geneRH} 0 0,0 ${p[6]} Z`;
+      } else {
+        const p = [pt(R + geneRH, angE), pt(R + geneRH, bodyEnd), pt(R + geneRH + geneRH * .9, bodyEnd),
+          pt(R, angS), pt(R - geneRH - geneRH * .9, bodyEnd), pt(R - geneRH, bodyEnd), pt(R - geneRH, angE)];
+        pathD = `M${p[0]} A${R + geneRH},${R + geneRH} 0 0,0 ${p[1]} L${p[2]} L${p[3]} L${p[4]} L${p[5]} A${R - geneRH},${R - geneRH} 0 0,1 ${p[6]} Z`;
+      }
+
+      let tipHtml = `<div class="gv-tt-title" style="color:${color}">${gn.id || 'N/A'}</div>`;
+      tipHtml += `<div class="gv-tt-loc">${gStart.toLocaleString()} – ${gn.end.toLocaleString()} bp &nbsp;·&nbsp;<span style="color:${color}">${isFwd ? '(+) Forward' : '(−) Reverse'}</span></div>`;
+      if (gn.annotation) {
+        // Two independent axes (lifecycle stage / functional role). Within
+        // an axis, category/leaf come from the SAME winning pool node (one
+        // unified ranking per axis), so they share one similarity and are
+        // guaranteed mutually coherent -- no cross-check between them is
+        // possible or needed. The two axes are fully independent of each
+        // other, each gets its own group + node-type badge.
+        for (const axis of Object.values(gn.annotation)) {
+          // confidence = fraction of noise-perturbed re-searches that agreed
+          // with the winning match -- local stability, not raw similarity.
+          const confPct = (axis.confidence * 100).toFixed(0);
+          const confCls = axis.confidence >= 0.7 ? ' gv-tt-annot-conf-high' : axis.confidence >= 0.4 ? ' gv-tt-annot-conf-mid' : ' gv-tt-annot-conf-low';
+          const meta = (axis.nodeType ? `${axis.nodeType} · ` : '') + `<span class="gv-tt-annot-conf${confCls}">${confPct}% stable</span>`;
+          // Each axis is its own bordered block -- lifecycle_stage and
+          // functional_role are independently-searched answers, not levels
+          // of one tree, and should visually read that way, not just blend
+          // together as one continuous list.
+          tipHtml += '<div class="gv-tt-annot-axis">';
+          tipHtml += `<div class="gv-tt-annot-axis-label"><span>${axis.label}</span><span class="gv-tt-annot-axis-meta">${meta}</span></div>`;
+          tipHtml += '<div class="gv-tt-annot-group">';
+          for (const [level, entry] of [['category', axis.category], ['annotation', axis.leaf]]) {
+            const cls = entry.resolved ? '' : ' gv-tt-annot-unresolved';
+            tipHtml += `<div class="gv-tt-annot-item${cls}"><div class="gv-tt-annot-level">${level}</div>`
+              + `<div class="gv-tt-annot-text"><span>${entry.text}</span><span class="gv-tt-annot-sim">${(entry.sim * 100).toFixed(0)}%</span></div></div>`;
+          }
+          tipHtml += '</div></div>';
+        }
+      }
+      if (gn.homology) {
+        // Third, independent annotation signal: plain ESM-embedding
+        // nearest-neighbor homology (PHROG/SwissProt via Qdrant) -- its own
+        // bordered block so it's never confused with the CLIP-projected
+        // hierarchy axes above. Each row is independently optional.
+        const h = gn.homology;
+        if (h.topHit || h.otherTopHit || h.majorityVote) {
+          tipHtml += '<div class="gv-tt-annot-axis">';
+          tipHtml += '<div class="gv-tt-annot-axis-label"><span>Homology (ESM)</span></div>';
+          tipHtml += '<div class="gv-tt-annot-group">';
+          if (h.topHit) {
+            const pct = h.topHit.score != null ? `${(h.topHit.score * 100).toFixed(0)}%` : '';
+            tipHtml += `<div class="gv-tt-annot-item"><div class="gv-tt-annot-level">top hit${h.topHit.source ? ` · ${h.topHit.source}` : ''}${h.topHit.id ? ` · ${h.topHit.id}` : ''}</div>`
+              + `<div class="gv-tt-annot-text"><span>${h.topHit.text}</span><span class="gv-tt-annot-sim">${pct}</span></div></div>`;
+          }
+          if (h.otherTopHit) {
+            const pct = h.otherTopHit.score != null ? `${(h.otherTopHit.score * 100).toFixed(0)}%` : '';
+            tipHtml += `<div class="gv-tt-annot-item"><div class="gv-tt-annot-level">other source${h.otherTopHit.source ? ` · ${h.otherTopHit.source}` : ''}${h.otherTopHit.id ? ` · ${h.otherTopHit.id}` : ''}</div>`
+              + `<div class="gv-tt-annot-text"><span>${h.otherTopHit.text}</span><span class="gv-tt-annot-sim">${pct}</span></div></div>`;
+          }
+          if (h.majorityVote) {
+            const frac = h.majorityVote.voteFrac;
+            const voteCls = frac == null ? '' : frac >= 0.7 ? ' gv-tt-annot-conf-high' : frac >= 0.4 ? ' gv-tt-annot-conf-mid' : ' gv-tt-annot-conf-low';
+            const voteBadge = frac != null ? `<span class="gv-tt-annot-conf${voteCls}">${(frac * 100).toFixed(0)}% agree</span>` : '';
+            tipHtml += `<div class="gv-tt-annot-item"><div class="gv-tt-annot-level">majority vote${h.majorityVote.id ? ` · ${h.majorityVote.id}` : ''}</div>`
+              + `<div class="gv-tt-annot-text"><span>${h.majorityVote.text}</span>${voteBadge}</div></div>`;
+          }
+          tipHtml += '</div></div>';
+        }
+      }
+      if (gn.community !== undefined) {
+        tipHtml += `<div class="gv-tt-row"><span>community:</span> ${gn.community}</div>`;
+      }
+      if (gn.hoverData) {
+        for (const [key, val] of Object.entries(gn.hoverData)) {
+          tipHtml += `<div class="gv-tt-row"><span>${key}:</span> ${val}</div>`;
+        }
+      }
+      const pinnedTipHtml = tipHtml + '<div class="gv-tt-pin">click to unpin · dbl-click to copy protein FASTA</div>';
+
+      const geneEl = this.geneG.append('path')
+        .attr('d', pathD).attr('fill', color).attr('fill-opacity', 0.85)
+        .attr('stroke', color).attr('stroke-width', 0.4).style('cursor', 'pointer')
+        .on('mouseover', function () {
+          if (self._pinnedGeneIdx !== null) return;
+          self._showTooltip(tipHtml);
+          self._dimChordsExcept(i);
+          d3.select(this).attr('fill-opacity', 1);
+        })
+        .on('mouseout', function () {
+          if (self._pinnedGeneIdx !== null) return;
+          self._hideTooltip();
+          self._restoreChords();
+          d3.select(this).attr('fill-opacity', 0.85);
+        })
+        .on('click', function (event) {
+          event.stopPropagation();
+          const node = this;
+
+          // Two quick clicks on the same gene → double-click → copy
+          if (self._clickTimer) {
+            clearTimeout(self._clickTimer);
+            self._clickTimer = null;
+            if (self._lastClickedIdx === i) {
+              self._copyGeneFasta(gn);
+              return;
+            }
+          }
+
+          self._lastClickedIdx = i;
+          self._clickTimer = setTimeout(() => {
+            self._clickTimer = null;
+
+            if (self._pinnedGeneIdx === i) {
+              // Unpin
+              self._pinnedGeneIdx = null;
+              self._hideTooltip();
+              self._restoreChords();
+              d3.select(node).attr('fill-opacity', 0.85);
+            } else {
+              // Unpin previously pinned gene
+              if (self._pinnedGeneIdx !== null) {
+                const prev = self._geneNodes[self._pinnedGeneIdx];
+                if (prev) d3.select(prev).attr('fill-opacity', 0.85);
+              }
+              // Pin this gene
+              self._pinnedGeneIdx = i;
+              self._showTooltip(pinnedTipHtml, true);
+              self._isolateChordsFor(i);
+              d3.select(node).attr('fill-opacity', 1);
+            }
+          }, 220);
+        });
+
+      this._geneNodes[i] = geneEl.node();
+      this.geneElements.push({ element: geneEl, angS, angE, color });
+    });
+
+    this.labelG.append('text').attr('text-anchor', 'middle').attr('y', -12)
+      .attr('fill', 'var(--phlam-accent)').attr('font-size', '19')
+      .attr('font-family', "'Azeret Mono', monospace")
+      .text((genomeSize / 1e3).toFixed(0) + ' kb');
+    this.labelG.append('text').attr('text-anchor', 'middle').attr('y', 11)
+      .attr('fill', 'var(--phlam-muted)').attr('font-size', '13')
+      .attr('font-family', "'Azeret Mono', monospace")
+      .text(genes.length + ' genes');
+  }
+
+  updateArcs(matrix, percentile = 0) {
+    this.chordG.selectAll('.chord').remove();
+    if (!this.genomeData || !this.genomeData.genes || this.genomeData.genes.length === 0) return;
+    if (!matrix || matrix.length === 0) return;
+
+    const genes = this.genomeData.genes;
+    const genomeSize = this.genomeData.genomeSize;
+    const N = genes.length;
+
+    const ang = pos => (pos / genomeSize) * Math.PI * 2 - Math.PI / 2;
+    const pt = (r, a) => [Math.cos(a) * r, Math.sin(a) * r];
+    const rChord = this.R - this.rH - 8;
+
+    const geneMatrix = matrix.slice(1).map(row => row.slice(1));
+
+    const offDiag = [];
+    for (let i = 0; i < N && i < geneMatrix.length; i++) {
+      for (let j = 0; j < N && j < geneMatrix[i].length; j++) {
+        if (i !== j) offDiag.push(geneMatrix[i][j]);
+      }
+    }
+    offDiag.sort((a, b) => a - b);
+    if (offDiag.length === 0) return;
+
+    const threshIdx = Math.floor(offDiag.length * (percentile / 100));
+    const threshVal = offDiag[Math.min(threshIdx, offDiag.length - 1)] ?? 0;
+    const maxVal = offDiag[offDiag.length - 1] ?? 1;
+
+    for (let i = 0; i < N && i < geneMatrix.length; i++) {
+      for (let j = 0; j < N && j < geneMatrix[i].length; j++) {
+        if (i === j) continue;
+        const val = geneMatrix[i][j];
+        if (val <= threshVal) continue;
+        const norm = (val - threshVal) / (maxVal - threshVal + 1e-9);
+        // Width is the primary encoding of attention strength; opacity gives a
+        // secondary depth cue on top and still drives hover isolation below.
+        const width = 0.75 + 5.5 * norm;
+        const opacity = 0.25 + 0.55 * norm;
+        const midI = (genes[i].start + genes[i].end) / 2;
+        const midJ = (genes[j].start + genes[j].end) / 2;
+        const [x1, y1] = pt(rChord, ang(midI));
+        const [x2, y2] = pt(rChord, ang(midJ));
+
+        this.chordG.append('path')
+          .attr('class', `chord chord-i-${i} chord-i-${j}`)
+          .attr('d', `M ${x1} ${y1} Q 0 0 ${x2} ${y2}`)
+          .attr('fill', 'none').attr('stroke', 'var(--phlam-accent)')
+          .attr('stroke-width', width).attr('stroke-opacity', opacity)
+          .attr('data-base-opacity', opacity)
+          .attr('marker-end', 'url(#arrowhead)');
+      }
+    }
+
+    // Re-apply ego-network isolation if a gene is pinned
+    if (this._pinnedGeneIdx !== null) {
+      this._isolateChordsFor(this._pinnedGeneIdx);
+    }
+  }
+
+}
+
+window.CircularGenomeViewer = CircularGenomeViewer;

static/lib/d3.LICENSE

@@ -0,0 +1,13 @@
+Copyright 2010-2023 Mike Bostock
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.

static/style.css

@@ -1,3 +1,8 @@
-body { font-family: sans-serif; max-width: 800px; margin: 2rem auto; padding: 0 1rem; }
+body { font-family: sans-serif; max-width: 1000px; margin: 2rem auto; padding: 0 1rem; }
 textarea { width: 100%; font-family: monospace; }
-#result { background: #f4f4f4; padding: 1rem; overflow-x: auto; white-space: pre-wrap; }
+table { border-collapse: collapse; width: 100%; margin-top: 1rem; font-size: 0.9rem; }
+th, td { border: 1px solid #ddd; padding: 0.3rem 0.5rem; text-align: left; }
+th { background: #f0f0f0; }
+.job-panel { margin-top: 1.5rem; }
+.job-status { color: #666; font-style: italic; }
+.job-result, #result { background: #f4f4f4; padding: 1rem; overflow-x: auto; white-space: pre-wrap; max-height: 400px; overflow-y: auto; }

static/synteny/synteny-view.css

@@ -0,0 +1,50 @@
+/* synteny-view.css - styles for synteny-view.js. Colours come from these variables; override them on .sv
+   (or an ancestor) to theme the viewer. Light theme only for now. */
+.sv {
+  --sv-ink: #191A19; --sv-ink2: #57544F; --sv-ink3: #6E6A63; --sv-line: #EDEAE4; --sv-border: #C9C4BB;
+  --sv-soft: #FCFBF9; --sv-accent: oklch(0.52 0.11 195); --sv-accent-bg: #EAF6F5; --sv-track: #8F897D;
+  --sv-mono: 'Azeret Mono', ui-monospace, monospace; --sv-sans: Figtree, system-ui, sans-serif;
+  position: relative; font-family: var(--sv-sans); color: var(--sv-ink);
+}
+.sv-bar { display: flex; align-items: center; gap: 8px; flex-wrap: wrap; padding: 0 28px 10px; }
+.sv-btn { height: 28px; padding: 0 11px; border: 1.25px solid var(--sv-border); border-radius: 6px; background: #fff;
+  font: 500 13px var(--sv-sans); color: var(--sv-ink); cursor: pointer; }
+.sv-btn:hover { border-color: var(--sv-ink); }
+.sv-range { margin-left: 8px; font: 400 12.5px var(--sv-mono); color: var(--sv-ink2); }
+.sv-hint { flex-basis: 100%; font-size: 12.5px; color: var(--sv-ink3); }
+.sv-ctl { display: inline-flex; align-items: center; gap: 7px; margin-left: 14px; font-size: 13px; color: var(--sv-ink2); cursor: pointer; }
+.sv-thr { margin-left: auto; cursor: default; }
+.sv-lab { font: 500 11.5px var(--sv-mono); letter-spacing: .06em; color: var(--sv-ink3); }
+.sv-select { height: 28px; border: 1.25px solid var(--sv-border); border-radius: 6px; background: #fff; font: 400 12.5px var(--sv-mono); color: var(--sv-ink); }
+.sv-range-input { width: 150px; accent-color: var(--sv-ink); cursor: pointer; }
+.sv-num { width: 74px; height: 28px; border: 1.25px solid var(--sv-border); border-radius: 6px; padding: 0 6px; font: 400 12.5px var(--sv-mono); }
+.sv-ctl input[type=checkbox] { accent-color: var(--sv-ink); }
+.sv-body { display: flex; align-items: flex-start; }
+.sv-labels { position: relative; flex: none; }
+.sv-plot { position: relative; flex: 1 1 auto; min-width: 0; margin-right: 20px; }
+.sv-svg { display: block; cursor: grab; touch-action: none; user-select: none; }
+.sv-svg:active { cursor: grabbing; }
+
+.sv-track { position: absolute; left: 28px; right: 8px; transform: translateY(-50%); display: flex; align-items: center; gap: 6px; }
+.sv-tname { flex: 1 1 auto; min-width: 0; display: flex; flex-direction: column; line-height: 1.25; }
+.sv-name { font: 600 13px var(--sv-mono); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.sv-name.sv-link { cursor: pointer; }
+.sv-name.sv-link:hover { text-decoration: underline; }
+.sv-sub { font: 400 11px var(--sv-mono); color: var(--sv-ink3); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.sv-tbtns { flex: none; display: flex; gap: 3px; }
+.sv-tbtn { width: 21px; height: 19px; padding: 0; border: 1.25px solid #ADA89D; border-radius: 4px; background: #F2F0EC;
+  font-size: 10.5px; color: #4A473F; cursor: pointer; line-height: 1; }
+.sv-tbtn:disabled { background: var(--sv-soft); color: #C9C4BB; border-color: #DDD9D2; cursor: default; }
+.sv-tbtn.sv-on { background: var(--sv-accent-bg); border-color: var(--sv-accent); color: var(--sv-accent); }
+
+.sv-axis text { font: 400 10.5px var(--sv-mono); fill: var(--sv-ink3); }
+.sv-axis path, .sv-axis line { stroke: var(--sv-border); }
+.sv-lines line { stroke: var(--sv-track); stroke-width: 1.5; }
+.sv-gene { stroke: var(--sv-ink); stroke-width: 0.6; cursor: pointer; }
+.sv-gene:hover { filter: brightness(1.12); stroke-width: 1.2; }
+.sv-gene.sv-anchor { stroke: var(--sv-accent); stroke-width: 2; }
+.sv-gene.sv-hl { stroke: var(--sv-ink); stroke-width: 2.4; }
+.sv-gene-label { font: 400 10px var(--sv-sans); fill: #4A473F; pointer-events: none; }
+.sv-tip { position: absolute; z-index: 20; pointer-events: none; opacity: 0; transition: opacity .08s; max-width: 360px;
+  background: var(--sv-ink); color: #F2F0EC; font: 13.5px/1.5 var(--sv-sans); padding: 8px 11px; border-radius: 8px;
+  box-shadow: 0 6px 20px rgba(0, 0, 0, .28); }

static/synteny/synteny-view.js

@@ -0,0 +1,458 @@
+// synteny-view.js - linear multi-genome synteny viewer with continuous zoom and pan.
+//
+// Standalone ES module: data in, events out; it knows nothing about PhageVault's API. Needs d3 v7
+// (options.d3, or the global `d3` from lib/d3.v7.9.0.min.js) and synteny-view.css. See README.md.
+//
+//   import { createSyntenyView } from "/static/synteny/synteny-view.js";
+//   const view = createSyntenyView(element, { onGeneClick: (gene, track) => ... });
+//   view.setData({ tracks, links }, { reset: true });
+//
+// tracks: [{ id, name, length, sub?, meta?: {key: value}, genes: [{ id, start, end, strand: 1 | -1,
+//           colour?, group?, label?, data? }] }]            gene ids unique over all tracks; 1-based coords
+// links:  [{ a: geneId, b: geneId, scores: { metricKey: number } }] (or `value` for a single unnamed metric);
+//          drawn only between tracks adjacent on screen, and only when the active metric reaches its threshold
+// metrics: [{ key, label, min, max, step, value }]         the toolbar picks one and sets its threshold; the
+//          threshold only decides link / no link, the opacity then shows the score between threshold and max
+//
+// Interaction: drag = pan; Ctrl/Cmd + wheel (or pinch) = zoom at the pointer; Shift + wheel or a sideways
+// trackpad swipe = pan; a plain wheel is left to the page (it scrolls). Zoom stops at maxZoomBp across the
+// plot. Per track: move up / down, flip. Double-click a gene: align every track on that gene's group.
+
+const DEFAULTS = {
+  d3: null,
+  labelWidth: 210,        // px, left column with names and track buttons
+  labelMaxChars: 18,      // longer names are middle-truncated (full name on hover)
+  trackSpacing: 64,       // px between gene rows
+  geneHeight: 13,
+  axisHeight: 30,
+  maxZoomBp: 1000,        // the most zoomed-in view spans this many bp
+  geneLabels: "auto",     // "auto": label genes wide enough on screen | "all": every gene, slanted | "none"
+  linkColour: "gene",     // "gene": colour of the upper gene | "grey" (also switchable in the toolbar)
+  metrics: [{ key: "value", label: "score", min: 0, max: 1, step: 0.001, value: 0 }],
+  linkOpacity: (v, thr, max) => 0.08 + 0.5 * Math.max(0, Math.min(1, (v - thr) / ((max - thr) || 1))),
+  unknownColour: "#ADA89D",
+  highlight: null,        // Set of gene ids drawn with a heavy outline (and their shared links darker)
+  geneTooltip: true,      // true | false | function (gene, track) -> HTML
+  onGeneHover: null,      // (gene, track) on enter, (null) on leave
+  onGeneClick: null,      // (gene, track); delayed so that a double-click still aligns
+  onTrackClick: null,     // (track) when a track name is clicked
+  onViewChange: null,     // ({ start, end }) visible range, in coordinates of the top track
+};
+
+const esc = s => String(s ?? "").replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+function midTrunc(s, n) {
+  s = String(s ?? "");
+  if (!n || s.length <= n) return s;
+  const tail = Math.ceil((n - 1) * 0.55);
+  return s.slice(0, n - 1 - tail) + "…" + s.slice(-tail);
+}
+const fmtBp = bp => Math.abs(bp) >= 1e6 ? (bp / 1e6).toFixed(2) + " Mb" : Math.abs(bp) >= 1e3 ? (bp / 1e3).toFixed(1) + " kb" : Math.round(bp) + " bp";
+
+export function createSyntenyView(host, options = {}) {
+  const d3 = options.d3 || globalThis.d3;
+  if (!d3) throw new Error("synteny-view: d3 v7 is required (options.d3 or a global d3)");
+  const opts = { ...DEFAULTS, ...options };
+
+  let data = { tracks: [], links: [] };
+  let geneIndex = new Map();           // gene id -> { gene, track }
+  let order = [];                      // track ids, top to bottom
+  const flipped = new Set();
+  let alignGroup = null;
+  const alignPref = new Map();         // track id -> preferred gene id within alignGroup
+  let offsets = new Map();             // track id -> bp shift applied by the alignment
+  let xBase = null, transform = d3.zoomIdentity, width = 0, height = 0;
+  let frame = 0, clickTimer = null;
+  let metric = opts.metrics[0].key;
+  const thresholds = new Map(opts.metrics.map(m => [m.key, m.value ?? m.min]));
+  const metricDef = () => opts.metrics.find(m => m.key === metric) || opts.metrics[0];
+  const score = l => l.scores ? l.scores[metric] : l.value;
+
+  // ------------------------------------------------------------------ DOM
+  host.innerHTML = "";
+  const root = d3.select(host).append("div").attr("class", "sv");
+  const bar = root.append("div").attr("class", "sv-bar");
+  const body = root.append("div").attr("class", "sv-body");
+  const labels = body.append("div").attr("class", "sv-labels").style("width", opts.labelWidth + "px");
+  const plot = body.append("div").attr("class", "sv-plot");
+  const svg = plot.append("svg").attr("class", "sv-svg");
+  const clipId = "sv-clip-" + Math.random().toString(36).slice(2, 9);
+  const clipRect = svg.append("defs").append("clipPath").attr("id", clipId).append("rect");
+  const axisG = svg.append("g").attr("class", "sv-axis");
+  const content = svg.append("g").attr("clip-path", `url(#${clipId})`);
+  const lineL = content.append("g").attr("class", "sv-lines");
+  const linkL = content.append("g").attr("class", "sv-links");
+  const geneL = content.append("g").attr("class", "sv-genes");
+  const textL = content.append("g").attr("class", "sv-gene-labels");
+  const tip = root.append("div").attr("class", "sv-tip");
+
+  const btn = (label, title, onClick) => bar.append("button").attr("type", "button").attr("class", "sv-btn")
+    .attr("title", title).text(label).on("click", onClick);
+  btn("↺ Reset", "Reset flips, order, alignment and zoom", () => api.reset());
+  btn("Fit", "Show whole genomes", () => api.fit());
+  btn("−", "Zoom out", () => zoomBy(1 / 2));
+  btn("+", "Zoom in", () => zoomBy(2));
+  const range = bar.append("span").attr("class", "sv-range");
+
+  // link threshold (per metric), gene labels, link colour
+  const thrBox = bar.append("span").attr("class", "sv-ctl sv-thr");
+  const metricSel = thrBox.append("select").attr("class", "sv-select").attr("title", "Link metric")
+    .on("change", e => { metric = e.target.value; syncThreshold(); draw(); });
+  const thrLabel = thrBox.append("span").attr("class", "sv-lab");
+  const thrRange = thrBox.append("input").attr("type", "range").attr("class", "sv-range-input")
+    .on("input", e => setThreshold(+e.target.value));
+  const thrNum = thrBox.append("input").attr("type", "number").attr("class", "sv-num")
+    .on("change", e => setThreshold(+e.target.value));
+  const labBox = bar.append("label").attr("class", "sv-ctl").attr("title", "Gene labels: when wide enough, all (slanted) or none");
+  labBox.append("span").attr("class", "sv-lab").text("LABELS");
+  const labSel = labBox.append("select").attr("class", "sv-select")
+    .on("change", e => { opts.geneLabels = e.target.value; layout(true); renderLabels(); draw(); });
+  labSel.selectAll("option").data([["auto", "auto"], ["all", "all"], ["none", "none"]]).join("option")
+    .attr("value", d => d[0]).text(d => d[1]);
+  const colBox = bar.append("label").attr("class", "sv-ctl").attr("title", "Colour each link like its upper gene instead of grey");
+  const colChk = colBox.append("input").attr("type", "checkbox")
+    .on("change", e => { opts.linkColour = e.target.checked ? "gene" : "grey"; draw(); });
+  colBox.append("span").text("colour links");
+  const status = bar.append("span").attr("class", "sv-hint");
+
+  function syncControls() {
+    metricSel.style("display", opts.metrics.length > 1 ? null : "none")
+      .selectAll("option").data(opts.metrics, m => m.key).join("option").attr("value", m => m.key).text(m => m.label);
+    metricSel.property("value", metric);
+    syncThreshold();
+    labSel.property("value", opts.geneLabels);
+    colChk.property("checked", opts.linkColour === "gene");
+  }
+  function syncThreshold() {
+    const m = metricDef(), v = thresholds.get(m.key);
+    thrLabel.text(`${opts.metrics.length > 1 ? "" : m.label.toUpperCase() + " "}≥`);
+    for (const inp of [thrRange, thrNum]) inp.attr("min", m.min).attr("max", m.max).attr("step", m.step).property("value", v);
+  }
+  function setThreshold(v) {
+    const m = metricDef();
+    if (!isFinite(v)) return;
+    v = Math.max(m.min, Math.min(m.max, v));
+    thresholds.set(m.key, v);
+    thrRange.property("value", v);
+    thrNum.property("value", v);
+    schedule();
+  }
+
+  // ------------------------------------------------------------------ geometry
+  const trackOf = id => data.tracks.find(t => t.id === id);
+  const rowY = i => opts.axisHeight + (opts.geneLabels === "all" ? 56 : 12) + i * (opts.trackSpacing + opts.geneHeight);
+  // world coordinate (bp) of position p on track t, with its flip and alignment offset
+  const world = (t, p) => (offsets.get(t.id) || 0) + (flipped.has(t.id) ? t.length - p : p);
+  const geneSpan = (t, g) => {
+    const a = world(t, g.start - 1), b = world(t, g.end);
+    return [Math.min(a, b), Math.max(a, b), flipped.has(t.id) ? -g.strand : g.strand];
+  };
+
+  function computeOffsets() {
+    offsets = new Map();
+    if (alignGroup == null) return;
+    const anchors = new Map();
+    for (const t of data.tracks) {
+      const pref = alignPref.get(t.id);
+      const g = t.genes.find(x => x.id === pref && x.group === alignGroup) || t.genes.find(x => x.group === alignGroup);
+      if (g) anchors.set(t.id, geneSpan(t, g)[0]);
+    }
+    if (!anchors.size) return;
+    const target = Math.max(...anchors.values());
+    for (const [id, a] of anchors) offsets.set(id, target - a);
+  }
+
+  function worldExtent() {
+    let lo = Infinity, hi = -Infinity;
+    for (const t of data.tracks) {
+      const o = offsets.get(t.id) || 0;
+      lo = Math.min(lo, o); hi = Math.max(hi, o + t.length);
+    }
+    return isFinite(lo) ? [lo, hi] : [0, 1];
+  }
+
+  // ------------------------------------------------------------------ zoom
+  const zoom = d3.zoom()
+    .filter(e => e.type === "wheel" ? (e.ctrlKey || e.metaKey) : (!e.button && e.type !== "dblclick"))
+    .clickDistance(4)
+    .on("zoom", e => { transform = e.transform; schedule(); });
+  svg.call(zoom).on("dblclick.zoom", null);
+
+  // a plain vertical wheel scrolls the page; Shift + wheel or a sideways swipe pans the view
+  svg.node().addEventListener("wheel", e => {
+    if (e.ctrlKey || e.metaKey) return;
+    const dx = e.shiftKey ? (e.deltaX || e.deltaY) : e.deltaX;
+    if (!e.shiftKey && Math.abs(e.deltaX) <= Math.abs(e.deltaY)) return;
+    e.preventDefault();
+    svg.call(zoom.translateBy, -dx / transform.k, 0);
+  }, { passive: false });
+
+  function layout(keepView) {
+    const visible = keepView && xBase ? transform.rescaleX(xBase).domain() : null;
+    width = Math.max(200, plot.node().clientWidth);
+    height = rowY(Math.max(0, order.length - 1)) + opts.geneHeight + 18;
+    svg.attr("width", width).attr("height", height).attr("viewBox", `0 0 ${width} ${height}`);
+    labels.style("height", height + "px");
+    clipRect.attr("x", 0).attr("y", 0).attr("width", width).attr("height", height);
+    const [lo, hi] = worldExtent();
+    const pad = (hi - lo) * 0.01;
+    xBase = d3.scaleLinear().domain([lo - pad, hi + pad]).range([8, width - 8]);
+    const maxK = Math.max(1, (hi - lo + 2 * pad) / opts.maxZoomBp);
+    zoom.scaleExtent([1, maxK]).extent([[0, 0], [width, height]]).translateExtent([[0, 0], [width, height]]);
+    if (visible) zoomToWorld(visible[0], visible[1], true);
+    else svg.call(zoom.transform, d3.zoomIdentity);
+  }
+
+  function zoomToWorld(a, b, instant) {
+    const [r0, r1] = xBase.range();
+    const k = (r1 - r0) / Math.max(1e-9, xBase(b) - xBase(a));
+    const t = d3.zoomIdentity.translate(r0 - k * xBase(a), 0).scale(k);
+    (instant ? svg : svg.transition().duration(200)).call(zoom.transform, t);
+  }
+
+  function zoomBy(f) { svg.transition().duration(200).call(zoom.scaleBy, f, [width / 2, 0]); }
+
+  new ResizeObserver(() => { if (data.tracks.length && Math.abs(plot.node().clientWidth - width) > 1) { layout(true); renderLabels(); } })
+    .observe(plot.node());
+
+  // ------------------------------------------------------------------ drawing
+  function schedule() {
+    if (!frame) frame = requestAnimationFrame(() => { frame = 0; draw(); });
+  }
+
+  function arrow(x1, x2, y, h, strand) {
+    const w = Math.max(1, x2 - x1), head = Math.min(10, w), m = y + h / 2;
+    return strand >= 0
+      ? `M${x1},${y}H${x1 + w - head}L${x1 + w},${m}L${x1 + w - head},${y + h}H${x1}Z`
+      : `M${x1 + w},${y}H${x1 + head}L${x1},${m}L${x1 + head},${y + h}H${x1 + w}Z`;
+  }
+
+  function draw() {
+    if (!xBase) return;
+    const x = transform.rescaleX(xBase);
+    const h = opts.geneHeight;
+    const [v0, v1] = x.domain();
+    const tracks = order.map(trackOf);
+    const rowOf = new Map(order.map((id, i) => [id, i]));
+    const hl = opts.highlight;
+
+    // axis in coordinates of the top track (bp from its start, respecting its flip and offset)
+    const top = tracks[0];
+    if (top) {
+      const local = w => flipped.has(top.id) ? top.length - (w - (offsets.get(top.id) || 0)) : w - (offsets.get(top.id) || 0);
+      const ax = d3.scaleLinear().domain([local(v0), local(v1)]).range(x.range());
+      axisG.attr("transform", `translate(0,${opts.axisHeight - 6})`)
+        .call(d3.axisTop(ax).ticks(Math.max(2, Math.floor(width / 110))).tickFormat(fmtBp).tickSizeOuter(0));
+      range.text(`${top.name}: ${fmtBp(Math.max(0, Math.min(local(v0), local(v1))))} – ${fmtBp(Math.min(top.length, Math.max(local(v0), local(v1))))}`);
+      if (opts.onViewChange) opts.onViewChange({ start: Math.min(local(v0), local(v1)), end: Math.max(local(v0), local(v1)) });
+    }
+
+    lineL.selectAll("line").data(tracks, t => t.id).join("line")
+      .attr("x1", t => x(Math.max(v0, offsets.get(t.id) || 0)))
+      .attr("x2", t => x(Math.min(v1, (offsets.get(t.id) || 0) + t.length)))
+      .attr("y1", t => rowY(rowOf.get(t.id)) + h / 2).attr("y2", t => rowY(rowOf.get(t.id)) + h / 2);
+
+    // links between tracks that are adjacent on screen, culled to the visible range
+    const links = [];
+    const m = metricDef(), thr = thresholds.get(m.key);
+    for (const l of data.links) {
+      const v = score(l);
+      if (v == null || v < thr) continue;
+      const A = geneIndex.get(l.a), B = geneIndex.get(l.b);
+      if (!A || !B) continue;
+      let ra = rowOf.get(A.track.id), rb = rowOf.get(B.track.id);
+      if (Math.abs(ra - rb) !== 1) continue;
+      let [ua, ub] = [A, B];
+      if (ra > rb) { [ua, ub] = [B, A]; [ra, rb] = [rb, ra]; }
+      const sa = geneSpan(ua.track, ua.gene), sb = geneSpan(ub.track, ub.gene);
+      if (Math.max(sa[1], sb[1]) < v0 || Math.min(sa[0], sb[0]) > v1) continue;
+      const on = hl && hl.has(ua.gene.id) && hl.has(ub.gene.id);
+      links.push({ l, v, ua, ub, sa, sb, ra, rb, on });
+    }
+    linkL.selectAll("path").data(links, d => d.l.a + "|" + d.l.b).join("path")
+      .attr("d", d => {
+        const y1 = rowY(d.ra) + h, y2 = rowY(d.rb), m = (y1 + y2) / 2;
+        const a1 = x(d.sa[0]), a2 = x(d.sa[1]), b1 = x(d.sb[0]), b2 = x(d.sb[1]);
+        return `M${a1},${y1}L${a2},${y1}C${a2},${m} ${b2},${m} ${b2},${y2}L${b1},${y2}C${b1},${m} ${a1},${m} ${a1},${y1}Z`;
+      })
+      .attr("fill", d => d.on ? "#191A19" : opts.linkColour === "gene" ? (d.ua.gene.colour || opts.unknownColour) : "#4A473F")
+      .attr("fill-opacity", d => d.on ? 0.5 : opts.linkOpacity(d.v, thr, m.max))
+      .on("mousemove", (e, d) => showTip(e, `<b>${esc(d.ua.gene.label || d.ua.gene.id)}</b> ↔ <b>${esc(d.ub.gene.label || d.ub.gene.id)}</b><br>` +
+        opts.metrics.map(mm => { const x = d.l.scores ? d.l.scores[mm.key] : d.l.value; return x == null ? "" : `${esc(mm.label)} ${(+x).toFixed(4)}<br>`; }).join("")))
+      .on("mouseleave", hideTip);
+
+    // genes, culled to the visible range
+    const genes = [];
+    for (const t of tracks) {
+      const r = rowOf.get(t.id);
+      for (const g of t.genes) {
+        const s = geneSpan(t, g);
+        if (s[1] < v0 || s[0] > v1) continue;
+        genes.push({ g, t, s, r });
+      }
+    }
+    geneL.selectAll("path").data(genes, d => d.g.id).join(enter => enter.append("path")
+        .on("mouseenter", (e, d) => { if (opts.onGeneHover) opts.onGeneHover(d.g, d.t); })
+        .on("mousemove", (e, d) => { if (opts.geneTooltip) showTip(e, geneTipHtml(d.g, d.t)); })
+        .on("mouseleave", () => { hideTip(); if (opts.onGeneHover) opts.onGeneHover(null); })
+        .on("click", (e, d) => {
+          if (!opts.onGeneClick) return;
+          clearTimeout(clickTimer);
+          clickTimer = setTimeout(() => opts.onGeneClick(d.g, d.t), 230);
+        })
+        .on("dblclick", (e, d) => {
+          e.preventDefault();
+          clearTimeout(clickTimer);
+          if (d.g.group == null) return;
+          if (alignGroup === d.g.group) { alignGroup = null; alignPref.clear(); }
+          else { alignGroup = d.g.group; alignPref.clear(); alignPref.set(d.t.id, d.g.id); }
+          computeOffsets(); layout(false); renderLabels();
+        }))
+      .attr("class", d => "sv-gene" + (alignGroup != null && d.g.group === alignGroup ? " sv-anchor" : "") + (hl && hl.has(d.g.id) ? " sv-hl" : ""))
+      .attr("d", d => arrow(x(d.s[0]), x(d.s[1]), rowY(d.r), h, d.s[2]))
+      .attr("fill", d => d.g.colour || opts.unknownColour);
+
+    // gene labels: "auto" writes a label inside the plot above genes wide enough for it
+    const lab = opts.geneLabels === "none" ? [] : genes.filter(d => d.g.label && (opts.geneLabels === "all" ||
+      x(d.s[1]) - x(d.s[0]) >= d.g.label.length * 6.2 + 6));
+    textL.selectAll("text").data(lab, d => d.g.id).join("text")
+      .attr("class", "sv-gene-label")
+      .attr("x", d => opts.geneLabels === "all" ? x(d.s[0]) + 2 : (x(d.s[0]) + x(d.s[1])) / 2)
+      .attr("y", d => rowY(d.r) - 3)
+      .attr("text-anchor", opts.geneLabels === "all" ? "start" : "middle")
+      .attr("transform", d => opts.geneLabels === "all" ? `rotate(-35 ${x(d.s[0]) + 2} ${rowY(d.r) - 3})` : null)
+      .text(d => d.g.label);
+  }
+
+  function geneTipHtml(g, t) {
+    if (typeof opts.geneTooltip === "function") return opts.geneTooltip(g, t);
+    return `<b>${esc(g.label || g.id)}</b><br>${esc(t.name)} · ${g.start}..${g.end} (${g.strand >= 0 ? "+" : "−"})` +
+      (g.group != null ? `<br>group ${esc(g.group)}` : "") + `<br><i>double-click: align all tracks on this group</i>`;
+  }
+
+  function showTip(e, html) {
+    const r = root.node().getBoundingClientRect();
+    tip.html(html).style("opacity", 1);
+    const w = tip.node().offsetWidth, hh = tip.node().offsetHeight;
+    let left = e.clientX - r.left + 14, topPx = e.clientY - r.top + 14;
+    if (e.clientX + 14 + w > window.innerWidth - 8) left = e.clientX - r.left - 14 - w;
+    if (e.clientY + 14 + hh > window.innerHeight - 8) topPx = e.clientY - r.top - 14 - hh;
+    tip.style("left", left + "px").style("top", topPx + "px");
+  }
+  function hideTip() { tip.style("opacity", 0); }
+
+  // ------------------------------------------------------------------ track labels + buttons (HTML, not zoomed)
+  function renderLabels() {
+    const tracks = order.map(trackOf);
+    labels.selectAll("div.sv-track").data(tracks, t => t.id).join(enter => {
+      const d = enter.append("div").attr("class", "sv-track");
+      const txt = d.append("div").attr("class", "sv-tname");
+      txt.append("span").attr("class", "sv-name").on("click", (e, t) => { if (opts.onTrackClick) opts.onTrackClick(t); });
+      txt.append("span").attr("class", "sv-sub");
+      const b = d.append("div").attr("class", "sv-tbtns");
+      b.append("button").attr("type", "button").attr("class", "sv-tbtn sv-up").attr("title", "Move up").text("▲")
+        .on("click", (e, t) => move(t.id, -1));
+      b.append("button").attr("type", "button").attr("class", "sv-tbtn sv-down").attr("title", "Move down").text("▼")
+        .on("click", (e, t) => move(t.id, 1));
+      b.append("button").attr("type", "button").attr("class", "sv-tbtn sv-flip").attr("title", "Flip (reverse complement)").text("⇄")
+        .on("click", (e, t) => { flipped.has(t.id) ? flipped.delete(t.id) : flipped.add(t.id); computeOffsets(); layout(true); renderLabels(); });
+      return d;
+    })
+      .style("top", (t, i) => (rowY(i) + opts.geneHeight / 2) + "px")
+      .attr("title", t => [t.name + (flipped.has(t.id) ? " (reversed)" : ""),
+        ...Object.entries(t.meta || {}).filter(([, v]) => v != null && v !== "").map(([k, v]) => `${k}: ${v}`)].join("\n"))
+      .call(d => {
+        d.select(".sv-name").text(t => midTrunc(t.name, opts.labelMaxChars)).classed("sv-link", !!opts.onTrackClick);
+        d.select(".sv-sub").text(t => t.sub || "");
+        d.select(".sv-up").property("disabled", (t, i) => i === 0);
+        d.select(".sv-down").property("disabled", (t, i) => i === tracks.length - 1);
+        d.select(".sv-flip").classed("sv-on", t => flipped.has(t.id));
+      });
+    status.text(alignGroup != null ? `aligned on ${alignGroup} · double-click it again to clear`
+      : "drag or Shift + wheel to pan · Ctrl/⌘ + wheel to zoom · double-click a gene to align its family");
+  }
+
+  function move(id, dir) {
+    const i = order.indexOf(id), j = i + dir;
+    if (j < 0 || j >= order.length) return;
+    [order[i], order[j]] = [order[j], order[i]];
+    layout(true); renderLabels();
+  }
+
+  // ------------------------------------------------------------------ public API
+  syncControls();
+
+  const api = {
+    /** data = { tracks, links }; reset: forget flips / order / alignment / zoom (a new set of genomes). */
+    setData(d, { reset = false } = {}) {
+      data = { tracks: d.tracks || [], links: d.links || [] };
+      geneIndex = new Map();
+      for (const t of data.tracks) for (const g of t.genes) geneIndex.set(g.id, { gene: g, track: t });
+      const ids = data.tracks.map(t => t.id);
+      if (reset) { order = ids.slice(); flipped.clear(); alignGroup = null; alignPref.clear(); }
+      else order = [...order.filter(id => ids.includes(id)), ...ids.filter(id => !order.includes(id))];
+      computeOffsets();
+      layout(!reset);
+      renderLabels();
+      draw();
+      return api;
+    },
+    /** Change options (highlight, linkColour, geneLabels, callbacks, ...) and redraw, keeping the view. */
+    setOptions(patch) {
+      const relayout = "geneLabels" in patch || "trackSpacing" in patch || "geneHeight" in patch || "maxZoomBp" in patch;
+      Object.assign(opts, patch);
+      if ("metrics" in patch) {
+        for (const m of opts.metrics) if (!thresholds.has(m.key)) thresholds.set(m.key, m.value ?? m.min);
+        if (!opts.metrics.some(m => m.key === metric)) metric = opts.metrics[0].key;
+      }
+      syncControls();
+      if (relayout) layout(true);
+      renderLabels();
+      draw();
+      return api;
+    },
+    /** { flipped: {trackId: bool}, order: [trackIds], alignGroup, alignPref: {trackId: geneId} } */
+    setState(st = {}) {
+      if (st.flipped) for (const [id, f] of Object.entries(st.flipped)) f ? flipped.add(id) : flipped.delete(id);
+      if (st.order) order = [...st.order.filter(id => trackOf(id)), ...order.filter(id => !st.order.includes(id))];
+      if ("alignGroup" in st) {
+        alignGroup = st.alignGroup;
+        alignPref.clear();
+        for (const [id, g] of Object.entries(st.alignPref || {})) alignPref.set(id, g);
+      }
+      computeOffsets(); layout(false); renderLabels(); draw();
+      return api;
+    },
+    /** Current link threshold: { metric, value } (the toolbar sets it; this is for reading it back). */
+    getThreshold() { return { metric, value: thresholds.get(metric) }; },
+    setThreshold(value, metricKey) { if (metricKey) metric = metricKey; syncThreshold(); setThreshold(value); return api; },
+    getState() {
+      return { flipped: Object.fromEntries([...flipped].map(id => [id, true])), order: order.slice(),
+               alignGroup, alignPref: Object.fromEntries(alignPref) };
+    },
+    reset() { flipped.clear(); alignGroup = null; alignPref.clear(); order = data.tracks.map(t => t.id);
+              computeOffsets(); layout(false); renderLabels(); draw(); return api; },
+    fit() { svg.transition().duration(200).call(zoom.transform, d3.zoomIdentity); return api; },
+    /** Zoom to [start, end] of a track (default: the top one), in that track's coordinates. */
+    zoomTo(start, end, trackId) {
+      const t = trackOf(trackId || order[0]);
+      if (t) { const a = world(t, start), b = world(t, end); zoomToWorld(Math.min(a, b), Math.max(a, b)); }
+      return api;
+    },
+    zoomToGene(geneId, marginBp = 2000) {
+      const G = geneIndex.get(geneId);
+      if (G) { const s = geneSpan(G.track, G.gene); zoomToWorld(s[0] - marginBp, s[1] + marginBp); }
+      return api;
+    },
+    /** Standalone SVG of the current view, with the track names, for figures. */
+    exportSVG() {
+      const lw = opts.labelWidth;
+      const clone = svg.node().cloneNode(true);
+      const names = order.map((id, i) => `<text x="${lw - 12}" y="${rowY(i) + opts.geneHeight / 2 + 4}" text-anchor="end" ` +
+        `font-family="sans-serif" font-size="12" font-weight="600">${esc(trackOf(id).name)}</text>`).join("");
+      return `<svg xmlns="http://www.w3.org/2000/svg" width="${width + lw}" height="${height}" font-family="sans-serif" font-size="10">` +
+        `<rect width="100%" height="100%" fill="#fff"/>${names}<g transform="translate(${lw},0)">${clone.innerHTML}</g></svg>`;
+    },
+    destroy() { host.innerHTML = ""; },
+  };
+  return api;
+}

templates/index.html

@@ -4,6 +4,7 @@
 <meta charset="UTF-8">
 <title>PHLAM</title>
 <link rel="stylesheet" href="{{ url_for('static', filename='style.css') }}">
+<link rel="stylesheet" href="{{ url_for('static', filename='synteny/synteny-view.css') }}">
 </head>
 <body>
   <h1>PHLAM</h1>
@@ -12,15 +13,140 @@
   <br>
   <button id="run">Analyze</button>
   <p id="status"></p>
-  <pre id="result"></pre>
 
-  <script>
+  <table id="genes" hidden>
+    <thead>
+      <tr><th>#</th><th>start</th><th>end</th><th>strand</th><th>aa</th><th>conf</th><th>top hit</th><th>other source</th></tr>
+    </thead>
+    <tbody></tbody>
+  </table>
+
+  <div id="jobs"></div>
+
+  <div id="synteny-section" hidden>
+    <h3>Synteny vs. genome neighbors</h3>
+    <button id="load-synteny">Load synteny (top 5 neighbors)</button>
+    <p id="synteny-status"></p>
+    <div id="synteny-plot" style="height:500px;"></div>
+  </div>
+
+  <script src="{{ url_for('static', filename='lib/d3.v7.9.0.min.js') }}"></script>
+  <script type="module">
+    import { createSyntenyView } from "{{ url_for('static', filename='synteny/synteny-view.js') }}";
+
+    const JOB_LABELS = {
+      genome_neighbors: "Genome neighbors",
+      protein_neighbors: "Protein neighbors (per gene, context-independent)",
+      gene_context_neighbors: "Gene-context neighbors (per gene)",
+    };
+
+    function annotationText(a) {
+      if (!a || !a.top_hit) return "-";
+      return `${a.top_hit.annotation} (${a.top_hit.source}, ${a.top_hit.score.toFixed(3)})`;
+    }
+    function otherHitText(a) {
+      if (!a || !a.other_source_hit) return "-";
+      const o = a.other_source_hit;
+      return `${o.annotation} (${o.source}, ${o.score.toFixed(3)})`;
+    }
+
+    function renderGenes(genes) {
+      const tbody = document.querySelector("#genes tbody");
+      tbody.innerHTML = "";
+      genes.forEach(g => {
+        const tr = document.createElement("tr");
+        tr.innerHTML = `<td>${g.order}</td><td>${g.start}</td><td>${g.end}</td><td>${g.strand}</td>
+          <td>${g.length_aa}</td><td>${g.confidence.toFixed(1)}</td>
+          <td>${annotationText(g.annotation)}</td><td>${otherHitText(g.annotation)}</td>`;
+        tbody.appendChild(tr);
+      });
+      document.getElementById("genes").hidden = false;
+    }
+
+    function jobPanel(key) {
+      const div = document.createElement("div");
+      div.className = "job-panel";
+      div.innerHTML = `<h3>${JOB_LABELS[key] || key}</h3><p class="job-status">pending...</p><pre class="job-result"></pre>`;
+      return div;
+    }
+
+    // Polls /job/<id> until done/error; resolves with the final {status, result, error}.
+    async function pollJob(jobId, { onDone } = {}) {
+      for (let i = 0; i < 150; i++) {
+        const res = await fetch(`/job/${jobId}`);
+        const data = await res.json();
+        if (data.status !== "pending") {
+          if (onDone) onDone(data);
+          return data;
+        }
+        await new Promise(r => setTimeout(r, 2000));
+      }
+      return { status: "timeout" };
+    }
+
+    function pollJobIntoPanel(jobId, panel) {
+      const statusEl = panel.querySelector(".job-status");
+      const resultEl = panel.querySelector(".job-result");
+      return pollJob(jobId, {
+        onDone: data => {
+          statusEl.textContent = data.status;
+          resultEl.textContent = data.status === "done"
+            ? JSON.stringify(data.result, null, 2) : (data.error || "job not found");
+        },
+      });
+    }
+
+    // tracks/links come back as phagevault-style positional tuples; synteny-view.js
+    // wants {id, start, end, strand} genes and {a, b, scores} links (ids unique over all tracks).
+    let syntenyView = null;
+    function renderSynteny(syn) {
+      const tracks = syn.tracks.map((t, ti) => ({
+        id: String(ti), name: t.name, length: t.length_bp,
+        genes: t.genes.map(([start, end, strand], gi) => ({
+          id: `${ti}:${gi}`, start, end, strand: strand === "-" ? -1 : 1,
+        })),
+      }));
+      const links = syn.links.map(([a, i, b, j, esm, phlam]) => ({
+        a: `${a}:${i}`, b: `${b}:${j}`, scores: { esm, phlam },
+      }));
+      if (!syntenyView) {
+        syntenyView = createSyntenyView(document.getElementById("synteny-plot"), {
+          metrics: [
+            { key: "esm", label: "ESM cosine", min: syn.esm_floor, max: 1, step: 0.001, value: syn.esm_floor },
+            { key: "phlam", label: "PHLAM cosine", min: syn.phlam_floor, max: 1, step: 0.001, value: syn.phlam_floor },
+          ],
+        });
+      }
+      syntenyView.setData({ tracks, links }, { reset: true });
+    }
+
+    document.getElementById("load-synteny").addEventListener("click", async () => {
+      const statusEl = document.getElementById("synteny-status");
+      statusEl.textContent = "Running...";
+      const res = await fetch("/synteny", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          analysis_id: window.PHLAM_ANALYSIS_ID,
+          genome_ids: window.PHLAM_NEIGHBOR_IDS.slice(0, 5),
+        }),
+      });
+      const data = await res.json();
+      if (!res.ok) { statusEl.textContent = "Error: " + data.error; return; }
+      const final = await pollJob(data.job);
+      if (final.status !== "done") { statusEl.textContent = "Error: " + (final.error || final.status); return; }
+      statusEl.textContent = `${final.result.links.length} links across ${final.result.tracks.length} tracks.`;
+      renderSynteny(final.result);
+    });
+
     document.getElementById("run").addEventListener("click", async () => {
       const input = document.getElementById("input").value;
       const statusEl = document.getElementById("status");
-      const resultEl = document.getElementById("result");
+      const jobsEl = document.getElementById("jobs");
+      document.getElementById("genes").hidden = true;
+      document.getElementById("synteny-section").hidden = true;
+      jobsEl.innerHTML = "";
       statusEl.textContent = "Running...";
-      resultEl.textContent = "";
       try {
         const res = await fetch("/analyze", {
           method: "POST",
@@ -32,8 +158,23 @@
           statusEl.textContent = "Error: " + data.error;
           return;
         }
-        statusEl.textContent = `Done: ${data.num_genes} genes predicted.`;
-        resultEl.textContent = JSON.stringify(data, null, 2);
+        statusEl.textContent = `Done: ${data.num_genes} genes predicted in ${data.display_name}.`;
+        renderGenes(data.genes);
+        window.PHLAM_ANALYSIS_ID = data.analysis_id;
+
+        // Poll every job concurrently -- jobs.jobs isn't in a meaningful
+        // order (jsonify sorts keys), and a slow job must never block a
+        // fast one's panel (or the synteny section) from updating.
+        for (const [key, jobId] of Object.entries(data.jobs || {})) {
+          const panel = jobPanel(key);
+          jobsEl.appendChild(panel);
+          pollJobIntoPanel(jobId, panel).then(finalData => {
+            if (key === "genome_neighbors" && finalData.status === "done") {
+              window.PHLAM_NEIGHBOR_IDS = finalData.result.map(h => h.genome_id);
+              document.getElementById("synteny-section").hidden = false;
+            }
+          });
+        }
       } catch (e) {
         statusEl.textContent = "Error: " + e;
       }

utils/annotation_retrieval.py

@@ -4,11 +4,9 @@ reference_min.parquet, row i of the parquet matching vector i of the index.
 Table columns: id, source (swissprot / acr / phrog), annotation, category."""
 import os
 
-import faiss
-import numpy as np
-import pandas as pd
+from utils.vector_store import VectorStore
 
-REFERENCE_DIR = os.environ.get("REFERENCE_DATA_DIR", "/data/reference/reference")
+REFERENCE_DIR = os.environ.get("REFERENCE_DATA_DIR", "/data/reference")
 INDEX_FILENAME = os.environ.get("REFERENCE_INDEX_FILE", "reference_min.index")
 PARQUET_FILENAME = os.environ.get("REFERENCE_PARQUET_FILE", "reference_min.parquet")
 
@@ -16,50 +14,38 @@ PARQUET_FILENAME = os.environ.get("REFERENCE_PARQUET_FILE", "reference_min.parqu
 class AnnotationRetriever:
     def __init__(self, data_dir=REFERENCE_DIR, index_filename=INDEX_FILENAME,
                  parquet_filename=PARQUET_FILENAME, top_k=16):
-        self.top_k = top_k
-        index_path = os.path.join(data_dir, index_filename)
-        parquet_path = os.path.join(data_dir, parquet_filename)
-
-        self.df = pd.read_parquet(parquet_path)
-        self.index = faiss.read_index(index_path, faiss.IO_FLAG_MMAP)
-        if len(self.df) != self.index.ntotal:
-            raise RuntimeError(
-                f"row-count mismatch: {parquet_filename} has {len(self.df)} rows, "
-                f"{index_filename} has {self.index.ntotal} vectors."
-            )
-        self._normalize_query = (self.index.metric_type == faiss.METRIC_INNER_PRODUCT)
+        self.store = VectorStore(
+            os.path.join(data_dir, index_filename),
+            os.path.join(data_dir, parquet_filename),
+            id_column=None, top_k=top_k,
+        )
 
     def query(self, esm_embeddings):
         """esm_embeddings: [N, D] array-like. Returns a list of N dicts, one
         per query: {"top_hit", "other_source_hit"}."""
-        vecs = np.asarray(esm_embeddings, dtype=np.float32)
-        if self._normalize_query:
-            norms = np.linalg.norm(vecs, axis=1, keepdims=True)
-            vecs = vecs / np.clip(norms, 1e-12, None)
-
-        scores, indices = self.index.search(vecs, self.top_k)
-        return [self._summarize(s, i) for s, i in zip(scores, indices)]
+        scores, indices = self.store.search(esm_embeddings)
+        rows = self.store.fetch_rows(indices.ravel())
+        return [self._summarize(s, i, rows) for s, i in zip(scores, indices)]
 
-    def _as_dict(self, score, idx):
-        row = self.df.iloc[idx]
+    def _as_dict(self, score, row):
         return {
             "id": row["id"], "source": row["source"], "annotation": row["annotation"],
             "category": row["category"], "score": float(score),
         }
 
-    def _summarize(self, scores, indices):
+    def _summarize(self, scores, indices, rows):
         valid = [(float(s), int(i)) for s, i in zip(scores, indices) if i >= 0]
         if not valid:
             return {"top_hit": None, "other_source_hit": None}
 
         top_score, top_idx = valid[0]
-        top_hit = self._as_dict(top_score, top_idx)
-        top_source = self.df.iloc[top_idx]["source"]
+        top_hit = self._as_dict(top_score, rows[top_idx])
+        top_source = rows[top_idx]["source"]
 
         other_source_hit = None
         for score, idx in valid[1:]:
-            if self.df.iloc[idx]["source"] != top_source:
-                other_source_hit = self._as_dict(score, idx)
+            if rows[idx]["source"] != top_source:
+                other_source_hit = self._as_dict(score, rows[idx])
                 break
 
         return {"top_hit": top_hit, "other_source_hit": other_source_hit}

utils/gene_context_retrieval.py

@@ -0,0 +1,23 @@
+"""Gene-level nearest-neighbor search against the imgvr_inphared corpus,
+using a query gene's phlam_protein vector (its genomic-context residual,
+not just the protein sequence -- the same gene in a different genome lands
+at a different point)."""
+import os
+
+from utils.vector_store import VectorStore
+
+IMGVR_DIR = os.environ.get("IMGVR_DATA_DIR", "/data/imgvr_inphared")
+
+
+class GeneContextRetriever:
+    def __init__(self, data_dir=IMGVR_DIR, top_k=10):
+        self.store = VectorStore(
+            os.path.join(data_dir, "phlam_protein.faiss"),
+            os.path.join(data_dir, "phlam_genes.parquet"),
+            id_column="gene_id", top_k=top_k,
+        )
+
+    def query(self, phlam_protein_vecs):
+        """phlam_protein_vecs: [N, 480] array-like. Returns a list of N hit
+        lists, each hit {gene_id, genome_id, gene_order, protein_id, seq_hash, norm, score}."""
+        return self.store.search_and_fetch(phlam_protein_vecs)

utils/genome_neighbor_retrieval.py

@@ -0,0 +1,21 @@
+"""Genome-level nearest-neighbor search against the imgvr_inphared corpus,
+using a query genome's phlam_genome (h_global) vector."""
+import os
+
+from utils.vector_store import VectorStore
+
+IMGVR_DIR = os.environ.get("IMGVR_DATA_DIR", "/data/imgvr_inphared")
+
+
+class GenomeNeighborRetriever:
+    def __init__(self, data_dir=IMGVR_DIR, top_k=10):
+        self.store = VectorStore(
+            os.path.join(data_dir, "phlam_genome.faiss"),
+            os.path.join(data_dir, "phlam_genomes.parquet"),
+            id_column="genome_id", top_k=top_k,
+        )
+
+    def query(self, phlam_genome_vecs):
+        """phlam_genome_vecs: [N, 480] array-like. Returns a list of N hit
+        lists, each hit {genome_id, n_genes, norm_genome, norm_meanpool, score}."""
+        return self.store.search_and_fetch(phlam_genome_vecs)

utils/phlam_embedder.py

@@ -0,0 +1,60 @@
+"""PHLAM genome/protein embeddings from a genome's ESM2 protein embeddings.
+
+phlam_genome:  h_global  -- one vector per genome.
+phlam_protein: h_protein - mean(h_protein over the genome) -- one residual
+               vector per protein, i.e. each protein's deviation from its
+               own genome's average.
+"""
+import os
+
+import torch
+import torch.nn.functional as F
+
+from phlam.model import PHLAM
+
+# matches training (phagevault/pipelines/embed_phlam.py: raw +1 -> 2, raw -1 -> 1)
+STRAND_TO_ID = {"+": 2, "-": 1}
+
+_ROOT = os.path.dirname(os.path.abspath(__file__))
+MODEL_CKPT_PATH = os.environ.get(
+    "PHLAM_CKPT_PATH", os.path.join(os.path.dirname(_ROOT), "saved_models", "phlam_model.pt"))
+NUM_LAYERS = 10
+NUM_HEADS = 12
+
+
+class PHLAMEmbedder:
+    def __init__(self, ckpt_path=MODEL_CKPT_PATH, device="cpu"):
+        ckpt = torch.load(ckpt_path, map_location="cpu", weights_only=False)
+        state_dict = {k.replace("_orig_mod.", ""): v for k, v in ckpt["model_state_dict"].items()}
+        model = PHLAM(input_dim=480, d_model=480, output_dim=480,
+                       num_layers=NUM_LAYERS, num_heads=NUM_HEADS, num_global=1)
+        model.load_state_dict(state_dict, strict=True)
+        model.eval()
+        self.model = model.to(device)
+        self.device = device
+
+    def embed(self, esm_embeds, strands, is_circular=True):
+        """esm_embeds: [L, 480] tensor/array of raw (pre-normalization) ESM
+        embeddings for one genome, in gene order. strands: list[str] of "+"/"-"
+        of length L. Returns {"phlam_genome": [480], "phlam_protein": [L, 480]}
+        as numpy arrays."""
+        strand_ids = [STRAND_TO_ID[s] for s in strands]
+
+        esm_t = torch.as_tensor(esm_embeds, dtype=torch.float32)
+        esm_in = F.normalize(esm_t, p=2, dim=-1).unsqueeze(0).to(self.device)
+        strand_t = torch.tensor([strand_ids], dtype=torch.long, device=self.device)
+
+        with torch.no_grad():
+            out = self.model(
+                strand_ids=strand_t, esm_embeds=esm_in,
+                is_circular=1.0 if is_circular else 0.0,
+                output_attentions=False,
+            )
+            h_protein = out["h_protein"][0]              # [L, 480]
+            h_global = out["h_global"][0]                 # [480]
+            phlam_protein = h_protein - h_protein.mean(dim=0, keepdim=True)
+
+        return {
+            "phlam_genome": h_global.float().cpu().numpy(),
+            "phlam_protein": phlam_protein.float().cpu().numpy(),
+        }

utils/protein_neighbor_retrieval.py

@@ -0,0 +1,21 @@
+"""Protein-level nearest-neighbor search against the imgvr_inphared corpus,
+using a query gene's raw ESM2-35M embedding (context-independent)."""
+import os
+
+from utils.vector_store import VectorStore
+
+IMGVR_DIR = os.environ.get("IMGVR_DATA_DIR", "/data/imgvr_inphared")
+
+
+class ProteinNeighborRetriever:
+    def __init__(self, data_dir=IMGVR_DIR, top_k=10):
+        self.store = VectorStore(
+            os.path.join(data_dir, "protein_esm2_t12_35M_UR50D.faiss"),
+            os.path.join(data_dir, "proteins.parquet"),
+            id_column="protein_id", top_k=top_k,
+        )
+
+    def query(self, esm_embeds):
+        """esm_embeds: [N, 480] array-like. Returns a list of N hit lists,
+        each hit {protein_id, seq_hash, sequence, length, norm, score}."""
+        return self.store.search_and_fetch(esm_embeds)

utils/synteny.py

@@ -0,0 +1,106 @@
+"""Gene-level synteny links between genome tracks: a query genome (computed
+locally) and/or database neighbor genomes (imgvr_inphared corpus), compared
+pairwise on ESM cosine and PHLAM context-residual cosine. Ported from
+phagevault/ui/app/search.py's synteny(), adapted from Milvus/Postgres to the
+local FAISS/DuckDB/parquet corpus."""
+import os
+
+import numpy as np
+
+from utils.vector_store import VectorStore
+
+IMGVR_DIR = os.environ.get("IMGVR_DATA_DIR", "/data/imgvr_inphared")
+ESM_LINK_FLOOR = float(os.environ.get("ESM_LINK_FLOOR", "0.95"))
+PHLAM_LINK_FLOOR = float(os.environ.get("PHLAM_LINK_FLOOR", "0.5"))
+
+_genes_store = None
+_proteins_store = None
+
+
+def _get_genes_store():
+    global _genes_store
+    if _genes_store is None:
+        _genes_store = VectorStore(
+            os.path.join(IMGVR_DIR, "phlam_protein.faiss"),
+            os.path.join(IMGVR_DIR, "phlam_genes.parquet"), id_column="gene_id")
+    return _genes_store
+
+
+def _get_proteins_store():
+    global _proteins_store
+    if _proteins_store is None:
+        _proteins_store = VectorStore(
+            os.path.join(IMGVR_DIR, "protein_esm2_t12_35M_UR50D.faiss"),
+            os.path.join(IMGVR_DIR, "proteins.parquet"), id_column="protein_id")
+    return _proteins_store
+
+
+def _normalize(mat):
+    if mat.shape[0] == 0:
+        return mat
+    norms = np.linalg.norm(mat, axis=1, keepdims=True)
+    return mat / np.clip(norms, 1e-12, None)
+
+
+def neighbor_track(genome_id):
+    """A database genome's genes + per-gene ESM/PHLAM vectors, as a synteny track."""
+    genes_store = _get_genes_store()
+    rows = genes_store._con.execute(
+        "SELECT gene_id, gene_order, begin_pos, end_pos, strand, protein_id FROM read_parquet(?) "
+        "WHERE genome_id = ? ORDER BY gene_order",
+        [genes_store.parquet_path, genome_id],
+    ).fetchall()
+    cols = ("gene_id", "gene_order", "begin_pos", "end_pos", "strand", "protein_id")
+    genes = [dict(zip(cols, r)) for r in rows]
+
+    length_bp = genes_store._con.execute(
+        "SELECT length_bp FROM read_parquet(?) WHERE genome_id = ?",
+        [os.path.join(IMGVR_DIR, "phlam_genomes.parquet"), genome_id],
+    ).fetchone()
+    length_bp = length_bp[0] if length_bp else (genes[-1]["end_pos"] if genes else 0)
+
+    phl = np.stack([genes_store.index.reconstruct(int(g["gene_id"])) for g in genes]) \
+        if genes else np.zeros((0, 480), np.float32)
+    esm_store = _get_proteins_store()
+    esm = np.stack([esm_store.index.reconstruct(int(g["protein_id"])) for g in genes]) \
+        if genes else np.zeros((0, 480), np.float32)
+
+    return {
+        "genome_id": genome_id, "name": f"genome_{genome_id}", "length_bp": length_bp,
+        "genes": genes, "esm": _normalize(esm), "phlam": _normalize(phl),
+    }
+
+
+def query_track(genome_name, genome_length, genes, esm_embeds, phlam_protein):
+    """genes: pipeline.py's gene_records (start/end/strand keys), same order
+    as esm_embeds/phlam_protein."""
+    return {
+        "genome_id": None, "name": genome_name, "length_bp": genome_length,
+        "genes": [{"gene_id": None, "begin_pos": g["start"], "end_pos": g["end"], "strand": g["strand"]}
+                  for g in genes],
+        "esm": _normalize(np.asarray(esm_embeds, dtype=np.float32)),
+        "phlam": _normalize(np.asarray(phlam_protein, dtype=np.float32)),
+    }
+
+
+def build_synteny(tracks):
+    """tracks: list of dicts from query_track/neighbor_track, in display
+    order. Returns {tracks, esm_floor, phlam_floor, links} ready for
+    synteny-view.js (links as [track_a, gene_i, track_b, gene_j, esm, phlam])."""
+    links = []
+    for a in range(len(tracks)):
+        for b in range(a + 1, len(tracks)):
+            ea, eb = tracks[a]["esm"], tracks[b]["esm"]
+            if ea.shape[0] == 0 or eb.shape[0] == 0:
+                continue
+            pa, pb = tracks[a]["phlam"], tracks[b]["phlam"]
+            se = ea @ eb.T
+            sp = pa @ pb.T if pa.shape[0] and pb.shape[0] else np.zeros_like(se)
+            for i, j in zip(*np.nonzero((se >= ESM_LINK_FLOOR) | (sp >= PHLAM_LINK_FLOOR))):
+                links.append([a, int(i), b, int(j), round(float(se[i, j]), 4), round(float(sp[i, j]), 4)])
+
+    out_tracks = [{
+        "genome_id": t.get("genome_id"), "name": t.get("name"), "length_bp": t.get("length_bp"),
+        "genes": [[g["begin_pos"], g["end_pos"], g["strand"], g.get("gene_id")] for g in t["genes"]],
+    } for t in tracks]
+    return {"tracks": out_tracks, "esm_floor": ESM_LINK_FLOOR, "phlam_floor": PHLAM_LINK_FLOOR, "links": links}

utils/vector_store.py

@@ -0,0 +1,80 @@
+"""Generic FAISS + DuckDB/Parquet nearest-neighbor store, mounted read-only
+(hfmount). FAISS is mmap'd; the parquet table is never fully loaded --
+DuckDB queries it directly, pushing id filters down to row-group pruning.
+
+Two id modes, matching how an index was built:
+  id_column=None  -- plain index, vector i <-> parquet row i (positional).
+                     Table is small enough to load once (e.g. the ~10MB
+                     annotation reference); searched ids ARE row positions.
+  id_column=<col> -- IndexIDMap2 built with add_with_ids(vecs, <col> values)
+                     (e.g. genome_id/gene_id). Searched ids are real key
+                     values; fetch_rows does a WHERE <col> IN (...) lookup
+                     with no full-table load, for tables too big to load.
+"""
+import duckdb
+import faiss
+import numpy as np
+
+
+class VectorStore:
+    def __init__(self, index_path, parquet_path, id_column=None, top_k=16):
+        self.parquet_path = parquet_path
+        self.id_column = id_column
+        self.top_k = top_k
+        self.index = faiss.read_index(index_path, faiss.IO_FLAG_MMAP)
+        self._normalize = (self.index.metric_type == faiss.METRIC_INNER_PRODUCT)
+        self._con = duckdb.connect()
+
+        if id_column is None:
+            self.table = self._con.execute(
+                "SELECT * FROM read_parquet(?)", [parquet_path]).df()
+            n_rows = len(self.table)
+        else:
+            self.table = None
+            n_rows = self._con.execute(
+                "SELECT count(*) FROM read_parquet(?)", [parquet_path]).fetchone()[0]
+
+        if n_rows != self.index.ntotal:
+            raise RuntimeError(
+                f"row-count mismatch: {parquet_path} has {n_rows} rows, "
+                f"{index_path} has {self.index.ntotal} vectors."
+            )
+
+    def search(self, vectors, k=None):
+        """vectors: [N, D] array-like. Returns (scores, ids), each [N, k] --
+        ids are row positions (id_column=None) or key values (id_column set);
+        -1 pads rows with fewer than k hits."""
+        vecs = np.asarray(vectors, dtype=np.float32)
+        if self._normalize:
+            norms = np.linalg.norm(vecs, axis=1, keepdims=True)
+            vecs = vecs / np.clip(norms, 1e-12, None)
+        return self.index.search(vecs, k or self.top_k)
+
+    def fetch_rows(self, ids):
+        """ids: iterable of row positions or key values (matching id_column
+        mode), -1 entries ignored. Returns {id: row_dict}."""
+        ids = sorted({int(i) for i in ids if i >= 0})
+        if not ids:
+            return {}
+        if self.id_column is None:
+            return {i: self.table.iloc[i].to_dict() for i in ids}
+        placeholders = ",".join("?" * len(ids))
+        rows = self._con.execute(
+            f"SELECT * FROM read_parquet(?) WHERE {self.id_column} IN ({placeholders})",
+            [self.parquet_path] + ids,
+        ).fetchall()
+        cols = [d[0] for d in self._con.description]
+        return {row[cols.index(self.id_column)]: dict(zip(cols, row)) for row in rows}
+
+    def search_and_fetch(self, vectors, k=None):
+        """One search + one batched fetch_rows for the whole query batch.
+        Returns a list of per-query hit lists: [{**row, "score": float}, ...]."""
+        scores, ids = self.search(vectors, k)
+        rows = self.fetch_rows(ids.ravel())
+        results = []
+        for s_row, i_row in zip(scores, ids):
+            results.append([
+                {**rows[int(i)], "score": float(s)}
+                for s, i in zip(s_row, i_row) if i >= 0 and int(i) in rows
+            ])
+        return results