Add pairwise sequence alignment (Needleman–Wunsch / Smith–Waterman)

Closes the biggest "looks incomplete vs Benchling" gap from the competitive
audit — we couldn't align two sequences at all.

- dee/core/align.py: numpy global + local pairwise alignment with identity %,
match midline, gaps, score; |a|×|b| size cap. +8 unit tests.
- POST /api/align (stateless utility, rate-limited, no sign-in gate).
- "Align two sequences" card in the Plasmid workbench: two inputs, Global/Local
toggle, blocked alignment view + identity/score stats.

Verified live: global 88.9% identity with correct midline, local finds the
shared region (100%, 0 gaps), empty→400. Full suite 324 passing.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

dee/core/align.py

@@ -0,0 +1,112 @@
+"""Pairwise sequence alignment — Needleman–Wunsch (global) and Smith–Waterman
+(local). numpy + stdlib only; no Biopython dependency so it's trivially testable.
+
+Identity-based scoring (match / mismatch + linear gap) — enough for the
+"compare two sequences" use case: visualise percent identity, mismatches, and
+gaps for DNA or protein. O(n·m) DP, so we cap |a|·|b| to keep it snappy.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict
+
+import numpy as np
+
+# |a| * |b| ceiling (~1225 × 1225). Above this we ask the user to align a
+# shorter region — the pure-Python traceback + DP fill stays sub-second below it.
+MAX_CELLS = 1_500_000
+
+
+def _clean(s: str) -> str:
+    return "".join(c for c in (s or "").upper() if not c.isspace())
+
+
+def align(a: str, b: str, *, mode: str = "global",
+          match: int = 2, mismatch: int = -1, gap: int = -2) -> Dict[str, Any]:
+    """Align sequences `a` and `b`.
+
+    mode: 'global' (Needleman–Wunsch) or 'local' (Smith–Waterman).
+    Returns aligned strings, a match midline, percent identity, score, gaps.
+    """
+    a = _clean(a)
+    b = _clean(b)
+    if not a or not b:
+        raise ValueError("Both sequences must be non-empty.")
+    if len(a) * len(b) > MAX_CELLS:
+        raise ValueError(
+            f"Sequences too large to align in-browser (|a|×|b| > {MAX_CELLS:,}). "
+            "Align a shorter region."
+        )
+
+    local = (mode == "local")
+    n, m = len(a), len(b)
+    H = np.zeros((n + 1, m + 1), dtype=np.int32)
+    # traceback codes: 0 diag, 1 up (gap in b), 2 left (gap in a), 3 stop
+    T = np.zeros((n + 1, m + 1), dtype=np.int8)
+
+    if not local:
+        H[:, 0] = np.arange(n + 1) * gap
+        H[0, :] = np.arange(m + 1) * gap
+        T[1:, 0] = 1
+        T[0, 1:] = 2
+
+    best_score, best_i, best_j = 0, 0, 0
+    for i in range(1, n + 1):
+        ai = a[i - 1]
+        Hi, Hprev, Ti = H[i], H[i - 1], T[i]
+        for j in range(1, m + 1):
+            sc = match if ai == b[j - 1] else mismatch
+            cell = Hprev[j - 1] + sc
+            t = 0
+            up = Hprev[j] + gap
+            if up > cell:
+                cell, t = up, 1
+            left = Hi[j - 1] + gap
+            if left > cell:
+                cell, t = left, 2
+            if local and cell < 0:
+                cell, t = 0, 3
+            Hi[j] = cell
+            Ti[j] = t
+            if local and cell > best_score:
+                best_score, best_i, best_j = cell, i, j
+
+    if local:
+        score, i, j = best_score, best_i, best_j
+    else:
+        score, i, j = int(H[n, m]), n, m
+
+    out_a, out_b = [], []
+    while i > 0 or j > 0:
+        t = int(T[i, j])
+        if local and (H[i, j] == 0 or t == 3):
+            break
+        if t == 0:
+            out_a.append(a[i - 1]); out_b.append(b[j - 1]); i -= 1; j -= 1
+        elif t == 1:
+            out_a.append(a[i - 1]); out_b.append("-"); i -= 1
+        elif t == 2:
+            out_a.append("-"); out_b.append(b[j - 1]); j -= 1
+        else:
+            break
+    out_a.reverse(); out_b.reverse()
+    aa, bb = "".join(out_a), "".join(out_b)
+
+    cols = len(aa)
+    matches = sum(1 for x, y in zip(aa, bb) if x == y and x != "-")
+    identity = round(100.0 * matches / cols, 1) if cols else 0.0
+    gaps = aa.count("-") + bb.count("-")
+    midline = "".join(
+        "|" if (x == y and x != "-") else (" " if (x == "-" or y == "-") else ".")
+        for x, y in zip(aa, bb)
+    )
+    return {
+        "mode": "local" if local else "global",
+        "score": int(score),
+        "identity": identity,
+        "length": cols,
+        "matches": matches,
+        "gaps": gaps,
+        "aligned_a": aa,
+        "aligned_b": bb,
+        "midline": midline,
+    }

dee/server.py

@@ -1567,6 +1567,23 @@ def create_app() -> Flask:
         return send_file(io.BytesIO(payload.encode("utf-8")), mimetype=mime,
                          as_attachment=True, download_name=f"{stem}.{ext}")
 
+    @app.post("/api/align")
+    def align_sequences() -> Response:
+        """Pairwise alignment (global/local) of two sequences. Stateless utility,
+        no sign-in needed; bounded by align()'s size cap + the global rate limit."""
+        from .core import align as _AL
+        body = request.get_json(force=True, silent=True) or {}
+        a, b = body.get("a") or "", body.get("b") or ""
+        mode = "local" if body.get("mode") == "local" else "global"
+        try:
+            result = _AL.align(a, b, mode=mode)
+        except ValueError as exc:
+            return jsonify({"error": str(exc)}), 400
+        except Exception:  # noqa: BLE001
+            logger.exception("alignment failed")
+            return jsonify({"error": "Alignment failed — check the two sequences."}), 500
+        return jsonify({"ok": True, **result})
+
     @app.post("/api/plasmid/save")
     def plasmid_save() -> Response:
         auth, denied = _plasmid_signin_guard()

dee/static/app.css

@@ -5614,6 +5614,16 @@ h3, h4 {
 /* selection arc mirrored on the companion circular map */
 .pm-sel { stroke: var(--brand); stroke-width: 15; opacity: 0.42; stroke-linecap: round; }
 
+/* ── Pairwise alignment card ── */
+.plasmid-align-card .align-inputs { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; margin: 10px 0; }
+@media (max-width: 700px) { .plasmid-align-card .align-inputs { grid-template-columns: 1fr; } }
+.align-actions { display: flex; align-items: center; gap: 14px; flex-wrap: wrap; }
+.align-stats { font-family: var(--font-mono); font-size: 12px; color: var(--ink-soft); }
+.align-output { margin-top: 14px; overflow-x: auto; }
+.align-block { margin-bottom: 10px; font-family: var(--font-mono); font-size: 12.5px; line-height: 1.5; white-space: pre; }
+.align-row { white-space: pre; }
+.align-mid { color: var(--ink-faint); }
+
 @media (max-width: 640px) {
     .seqtool-input { width: 100%; }
     .seqtool-find { width: 100%; }

dee/static/app.js

@@ -8026,3 +8026,51 @@ function runOracle(opts){
                  outcomes: [{ subject, measured_value: parseFloat($('coResult').value), outcome: 'measured' }] };
     });
 })();
+
+// ── Pairwise sequence alignment (Plasmid workbench card → /api/align) ──
+(function initAlign() {
+    const A = document.getElementById('alignA');
+    const B = document.getElementById('alignB');
+    const runBtn = document.getElementById('alignRun');
+    const out = document.getElementById('alignOutput');
+    const stats = document.getElementById('alignStats');
+    if (!A || !B || !runBtn || !out) return;
+    let mode = 'global';
+    document.querySelectorAll('[data-align-mode]').forEach((btn) => {
+        btn.addEventListener('click', () => {
+            mode = btn.getAttribute('data-align-mode');
+            document.querySelectorAll('[data-align-mode]').forEach((b) =>
+                b.classList.toggle('clone-method-active', b === btn));
+        });
+    });
+    function render(r) {
+        const W = 60, aa = r.aligned_a || '', bb = r.aligned_b || '', mid = r.midline || '';
+        let html = '';
+        for (let i = 0; i < aa.length; i += W) {
+            const n = Math.min(i + W, aa.length);
+            html += `<div class="align-block">`
+                + `<div class="align-row">${i + 1} ${escapeHtml(aa.slice(i, n))}</div>`
+                + `<div class="align-row align-mid">${' '.repeat(String(i + 1).length + 1)}${escapeHtml(mid.slice(i, n))}</div>`
+                + `<div class="align-row">${i + 1} ${escapeHtml(bb.slice(i, n))}</div></div>`;
+        }
+        out.innerHTML = html;
+        out.hidden = false;
+        stats.textContent = `${r.mode} · ${r.identity}% identity · ${r.matches}/${r.length} matches · ${r.gaps} gaps · score ${r.score}`;
+    }
+    runBtn.addEventListener('click', async () => {
+        const a = (A.value || '').trim(), b = (B.value || '').trim();
+        if (!a || !b) { stats.textContent = 'Paste two sequences first.'; out.hidden = true; return; }
+        runBtn.disabled = true; stats.textContent = 'Aligning…'; out.hidden = true;
+        try {
+            const res = await fetch('/api/align', {
+                method: 'POST', headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ a, b, mode }),
+            });
+            const data = await res.json().catch(() => ({}));
+            if (!res.ok || data.error) { stats.textContent = data.error || `Alignment failed (${res.status}).`; }
+            else render(data);
+        } catch (e) {
+            stats.textContent = 'Network error — try again.';
+        } finally { runBtn.disabled = false; }
+    });
+})();

dee/static/index.html

@@ -28,7 +28,7 @@
     <!-- ?v= query bumps invalidate browser + iframe asset caches when app.css /
          app.js change. Bump these numbers whenever you ship a frontend update —
          without them, users keep getting the stale file for up to a week. -->
-    <link rel="stylesheet" href="/static/app.css?v=20260609-fold" />
+    <link rel="stylesheet" href="/static/app.css?v=20260609-align" />
     <link rel="icon" type="image/svg+xml" href="/static/favicon.svg?v=2" />
     <link rel="apple-touch-icon" href="/static/favicon.svg?v=2" />
     <!-- Mol* (PDBe) 3-D viewer is ~4.9 MB. We do NOT eager-load it on every
@@ -1270,6 +1270,27 @@
                           circular-aware. Auto-annotation flags ORFs + common motifs; GenBank features are kept as-is.</p>
                   </section>
 
+                  <!-- Pairwise sequence alignment -->
+                  <section class="card plasmid-align-card">
+                      <div class="clone-head">
+                          <h2 class="clone-title">Align two sequences</h2>
+                          <div class="clone-methods" role="tablist">
+                              <button class="clone-method clone-method-active" data-align-mode="global" type="button">Global</button>
+                              <button class="clone-method" data-align-mode="local" type="button">Local</button>
+                          </div>
+                      </div>
+                      <p class="field-hint">Compare two DNA or protein sequences — percent identity, mismatches and gaps. <strong>Global</strong> aligns end-to-end (Needleman–Wunsch); <strong>Local</strong> finds the best shared region (Smith–Waterman).</p>
+                      <div class="align-inputs">
+                          <textarea id="alignA" class="primer-textarea mono" rows="3" spellcheck="false" placeholder="Sequence A — ACGT… or protein"></textarea>
+                          <textarea id="alignB" class="primer-textarea mono" rows="3" spellcheck="false" placeholder="Sequence B"></textarea>
+                      </div>
+                      <div class="align-actions">
+                          <button class="primary" type="button" id="alignRun">Align</button>
+                          <span class="align-stats" id="alignStats"></span>
+                      </div>
+                      <div class="align-output" id="alignOutput" hidden></div>
+                  </section>
+
                   <!-- Cloning / assembly -->
                   <section class="card plasmid-clone-card">
                       <div class="clone-head">
@@ -1816,6 +1837,6 @@
     <!-- Cloning reference data must load before app.js so the Designer
          can read VECTORS / ENZYMES / CLONING_METHODS / TAGS / LINKERS. -->
     <script src="/static/cloning_db.js?v=20260530-ui-polish" defer></script>
-    <script src="/static/app.js?v=20260609-fold" defer></script>
+    <script src="/static/app.js?v=20260609-align" defer></script>
 </body>
 </html>

tests/test_align.py

@@ -0,0 +1,64 @@
+"""Tests for pairwise alignment (dee/core/align.py)."""
+import pytest
+
+from dee.core import align as A
+
+
+def test_identical_global():
+    r = A.align("ACGTACGT", "ACGTACGT")
+    assert r["identity"] == 100.0
+    assert r["gaps"] == 0
+    assert r["aligned_a"] == r["aligned_b"] == "ACGTACGT"
+    assert r["mode"] == "global"
+
+
+def test_single_mismatch():
+    r = A.align("ACGTACGT", "ACGTTCGT")
+    assert r["gaps"] == 0
+    assert r["length"] == 8
+    assert r["matches"] == 7
+    assert 80.0 < r["identity"] < 100.0
+    assert r["midline"].count(".") == 1   # one mismatch column
+
+
+def test_insertion_makes_a_gap():
+    # b has an extra base → a gap appears in the alignment
+    r = A.align("ACGTACGT", "ACGTAACGT")
+    assert r["gaps"] >= 1
+    assert "-" in r["aligned_a"]
+    # all original bases still match where aligned
+    assert r["matches"] == 8
+
+
+def test_local_finds_embedded_region():
+    a = "GGGGGGACGTACGTGGGGGG"
+    b = "TTTTACGTACGTTTTT"
+    r = A.align(a, b, mode="local")
+    assert r["mode"] == "local"
+    # the shared ACGTACGT core should align at 100% identity, no gaps
+    assert "ACGTACGT" in r["aligned_a"].replace("-", "")
+    assert r["identity"] == 100.0
+    assert r["gaps"] == 0
+
+
+def test_whitespace_and_case_normalised():
+    r = A.align("ac gt\nac gt", "ACGTACGT")
+    assert r["identity"] == 100.0
+
+
+def test_empty_raises():
+    with pytest.raises(ValueError):
+        A.align("", "ACGT")
+    with pytest.raises(ValueError):
+        A.align("ACGT", "   ")
+
+
+def test_oversize_raises():
+    big = "A" * 2000
+    with pytest.raises(ValueError):
+        A.align(big, big)   # 4,000,000 cells > MAX_CELLS
+
+
+def test_midline_lengths_consistent():
+    r = A.align("ACGTACGTAC", "ACGAACGTTC")
+    assert len(r["aligned_a"]) == len(r["aligned_b"]) == len(r["midline"]) == r["length"]