opd-viz 0.1.0__tar.gz

opd_viz-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Linting
+.ruff_cache/
+.mypy_cache/
+
+# Build
+dist/
+build/
+*.egg-info/
+
+# IDE
+.idea/
+.vscode/

opd_viz-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Construct Labs GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

opd_viz-0.1.0/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: opd-viz
+Version: 0.1.0
+Summary: Live per-token distillation-loss (SDPO) heatmap server for any vLLM-served chat model
+Project-URL: Homepage, https://constructlabs.com
+Author-email: Construct Labs GmbH <hello@constructlabs.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,distillation,kl-divergence,machine-learning,reinforcement-learning,sdpo,visualization,vllm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: jinja2>=3.1
+Requires-Dist: mcp>=1.2
+Requires-Dist: numpy>=1.24
+Requires-Dist: transformers>=4.44
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# opd-viz
+
+Live per-token distillation-loss (SDPO) heatmap server for any vLLM-served chat model.
+
+`opd-viz` visualizes the gold-hint SDPO per-token distillation loss: for each rollout
+token it compares the student-policy prediction against the gold-procedure-reprompted
+teacher prediction as a top-k KL, and colors that divergence onto the realized tokens in a
+browser heatmap. It is model-agnostic (you pick the endpoint, model, and tokenizer at
+runtime from the browser) and brings-your-own-MCP (register any MCP server for the agentic
+generate loop).
+
+## Install / run
+
+Zero-checkout, via uv:
+
+```bash
+uvx --from opd-viz opd-viz --port 8088
+```
+
+or into an environment:
+
+```bash
+pip install opd-viz
+opd-viz --port 8088
+```
+
+Then open `http://127.0.0.1:8088`. The server binds loopback and is single-user; there is
+no auth on the opd-viz server itself.
+
+Flags: `--host` (default `127.0.0.1`), `--port` (default `8088`). Everything else is set in
+the browser.
+
+## Requirements
+
+- A served, OpenAI-compatible **vLLM** endpoint. It **must** be started with
+  `--max-logprobs 100` so the teacher-forcing pass can return top-100 `prompt_logprobs`;
+  `opd-viz` preflights this on Connect and reports a clear error if it is missing.
+- The tokenizer matching your model is pulled from the Hugging Face Hub by the model id at
+  Connect time. For gated repos, set `HF_TOKEN` in the environment before launching:
+
+  ```bash
+  HF_TOKEN=<paste your hf_… token> uvx --from opd-viz opd-viz
+  ```
+
+  (Reference a secret manager rather than pasting tokens into shared shells.)
+
+## Use it (connect, generate, recompute)
+
+1. **Connect.** Fill in the vLLM endpoint (e.g. `http://host:port/v1`), optional API key,
+   the model id (e.g. `org/Model-Name`), an optional system prompt, and sampling params
+   (temperature plus any of top_p / top_k / min_p / presence_penalty / repetition_penalty;
+   blank fields are not sent). Click **Connect** — this loads the matching tokenizer, runs
+   the vLLM preflight, and runs a chat-template self-check, surfacing any warnings. Changing
+   the model and clicking Connect again re-pulls the matching tokenizer and re-preflights;
+   no restart needed.
+2. **Generate.** Type a question and click **Generate rollout**. Without tools this is a
+   single assistant turn (the student = its own tokens, so `gen == score` holds). The
+   generation logprobs are the student distribution.
+3. **Recompute.** Paste the gold hindsight (and optionally tweak the reprompt template),
+   then click **Recompute & visualize**. The exact generated token ids are teacher-forced
+   under the gold-hint prompt via vLLM `prompt_logprobs`, and the per-token KL (JSD / reverse
+   / forward) is colored onto the realized tokens. Hover any token for the student/teacher
+   top-k and the top-1 (dis)agreement.
+
+A rollout is stamped with the config that produced it; if you reconnect with a different
+model/config and then score a stale rollout, the server refuses (regenerate instead of
+mis-coloring).
+
+## MCP tools (optional, agentic)
+
+Register MCP servers in the Connect panel to make their tools available to an agentic
+generate loop:
+
+- **remote**: a URL (e.g. `https://host/mcp`) plus an optional auth header.
+- **stdio**: a command + args (+ optional `KEY=val` env), e.g. `uvx some-mcp-server`.
+
+After connecting, the **use tools** toggle enables once at least one MCP tool is discovered.
+With it on, Generate runs the model through tool calls (executed live) until it answers
+without a tool call; scoring colors each assistant turn and greys the tool results.
+
+`opd-viz` contacts only your vLLM endpoint, the MCP servers you register, and the HF Hub
+(for the tokenizer). Nothing else.

opd_viz-0.1.0/README.md

@@ -0,0 +1,82 @@
+# opd-viz
+
+Live per-token distillation-loss (SDPO) heatmap server for any vLLM-served chat model.
+
+`opd-viz` visualizes the gold-hint SDPO per-token distillation loss: for each rollout
+token it compares the student-policy prediction against the gold-procedure-reprompted
+teacher prediction as a top-k KL, and colors that divergence onto the realized tokens in a
+browser heatmap. It is model-agnostic (you pick the endpoint, model, and tokenizer at
+runtime from the browser) and brings-your-own-MCP (register any MCP server for the agentic
+generate loop).
+
+## Install / run
+
+Zero-checkout, via uv:
+
+```bash
+uvx --from opd-viz opd-viz --port 8088
+```
+
+or into an environment:
+
+```bash
+pip install opd-viz
+opd-viz --port 8088
+```
+
+Then open `http://127.0.0.1:8088`. The server binds loopback and is single-user; there is
+no auth on the opd-viz server itself.
+
+Flags: `--host` (default `127.0.0.1`), `--port` (default `8088`). Everything else is set in
+the browser.
+
+## Requirements
+
+- A served, OpenAI-compatible **vLLM** endpoint. It **must** be started with
+  `--max-logprobs 100` so the teacher-forcing pass can return top-100 `prompt_logprobs`;
+  `opd-viz` preflights this on Connect and reports a clear error if it is missing.
+- The tokenizer matching your model is pulled from the Hugging Face Hub by the model id at
+  Connect time. For gated repos, set `HF_TOKEN` in the environment before launching:
+
+  ```bash
+  HF_TOKEN=<paste your hf_… token> uvx --from opd-viz opd-viz
+  ```
+
+  (Reference a secret manager rather than pasting tokens into shared shells.)
+
+## Use it (connect, generate, recompute)
+
+1. **Connect.** Fill in the vLLM endpoint (e.g. `http://host:port/v1`), optional API key,
+   the model id (e.g. `org/Model-Name`), an optional system prompt, and sampling params
+   (temperature plus any of top_p / top_k / min_p / presence_penalty / repetition_penalty;
+   blank fields are not sent). Click **Connect** — this loads the matching tokenizer, runs
+   the vLLM preflight, and runs a chat-template self-check, surfacing any warnings. Changing
+   the model and clicking Connect again re-pulls the matching tokenizer and re-preflights;
+   no restart needed.
+2. **Generate.** Type a question and click **Generate rollout**. Without tools this is a
+   single assistant turn (the student = its own tokens, so `gen == score` holds). The
+   generation logprobs are the student distribution.
+3. **Recompute.** Paste the gold hindsight (and optionally tweak the reprompt template),
+   then click **Recompute & visualize**. The exact generated token ids are teacher-forced
+   under the gold-hint prompt via vLLM `prompt_logprobs`, and the per-token KL (JSD / reverse
+   / forward) is colored onto the realized tokens. Hover any token for the student/teacher
+   top-k and the top-1 (dis)agreement.
+
+A rollout is stamped with the config that produced it; if you reconnect with a different
+model/config and then score a stale rollout, the server refuses (regenerate instead of
+mis-coloring).
+
+## MCP tools (optional, agentic)
+
+Register MCP servers in the Connect panel to make their tools available to an agentic
+generate loop:
+
+- **remote**: a URL (e.g. `https://host/mcp`) plus an optional auth header.
+- **stdio**: a command + args (+ optional `KEY=val` env), e.g. `uvx some-mcp-server`.
+
+After connecting, the **use tools** toggle enables once at least one MCP tool is discovered.
+With it on, Generate runs the model through tool calls (executed live) until it answers
+without a tool call; scoring colors each assistant turn and greys the tool results.
+
+`opd-viz` contacts only your vLLM endpoint, the MCP servers you register, and the HF Hub
+(for the tokenizer). Nothing else.

opd_viz-0.1.0/pyproject.toml

@@ -0,0 +1,104 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "opd-viz"
+version = "0.1.0"
+description = "Live per-token distillation-loss (SDPO) heatmap server for any vLLM-served chat model"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [
+    { name = "Construct Labs GmbH", email = "hello@constructlabs.com" }
+]
+keywords = [
+    "sdpo",
+    "distillation",
+    "kl-divergence",
+    "vllm",
+    "visualization",
+    "reinforcement-learning",
+    "ai",
+    "machine-learning",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Typing :: Typed",
+]
+dependencies = [
+    "transformers>=4.44",
+    "jinja2>=3.1",          # apply_chat_template (render path) needs it; transformers leaves it optional
+    "numpy>=1.24",          # Phase 2 (KL math); transformers already pulls it
+    "mcp>=1.2",             # Phase 4 (generic MCP client)
+]
+
+[project.scripts]
+opd-viz = "opd_viz.server:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "ruff>=0.1.0",
+    "mypy>=1.0.0",
+    "build>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://constructlabs.com"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+    "/README.md",
+    "/LICENSE",
+]
+
+[tool.hatch.build.targets.wheel]
+# hatchling ships every file under the package dir (incl. assets/viz_client.js and
+# py.typed), so no explicit force-include is needed; a force-include here would
+# double-add the asset and fail the build. The Phase 5 smoke test guards inclusion.
+packages = ["src/opd_viz"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # Pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "C4",  # flake8-comprehensions
+    "UP",  # pyupgrade
+]
+ignore = [
+    "E501",  # line too long (handled by formatter)
+    "E401",  # multiple imports on one line (kept from the original loose scripts)
+    "E701",  # multiple statements on one line, colon (kept from the original loose scripts)
+    "E702",  # multiple statements on one line, semicolon (kept from the original loose scripts)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["opd_viz"]
+
+[tool.mypy]
+python_version = "3.10"
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+asyncio_mode = "auto"

opd_viz-0.1.0/src/opd_viz/__init__.py

@@ -0,0 +1,18 @@
+"""opd-viz - live per-token distillation-loss (SDPO) heatmap server.
+
+A self-contained, model-agnostic server that visualizes the gold-hint SDPO per-token
+distillation loss against any vLLM-served chat model: for each rollout token, the
+student-policy prediction vs the gold-procedure-reprompted teacher prediction, as a
+top-k KL colored onto the realized tokens in a browser heatmap.
+
+For licensing and support, contact hello@constructlabs.com
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("opd-viz")
+except PackageNotFoundError:
+    __version__ = "0.0.0+dev"
+
+__all__ = ["__version__"]

opd_viz-0.1.0/src/opd_viz/assets/viz_client.js

@@ -0,0 +1,210 @@
+// Shared SDPO heatmap client. Pure browser JS, no build step. Inlined verbatim by
+// BOTH the static builder (build_multi_viz.py) and the live server (serve_viz.py).
+// All per-token interactivity recomputes client-side from the stored primitives
+// (loss variant, kl_clip, importance multiply, top-1-disagree, KDE, hover).
+//
+// State is a mutable record array. setData() (static bootstrap) / addRecord() (live
+// recompute) repopulate the sample dropdown and re-render. CAP (the fixed colour
+// reference = 95th pct of kl_jsd over scored tokens) is passed in by the static
+// builder, or computed client-side in live mode.
+let DATA = [], CAP = 6, cur = 0;
+const sel = document.getElementById('sel');
+
+// top-1 agreement, computed client-side from the stored top-k. The two scorers order
+// their top-k differently (Qwen3.6: sorted by teacher prob; verl-dump 8B: teacher probs
+// in STUDENT rank order), so take each side's argmax BY PROBABILITY rather than [0].
+// Both top-k are restricted to the student's top-k candidate set, so this is
+// teacher-argmax-within-set vs student-argmax. Prefer a stored top1_agree if present.
+function amaxTok(rows){ let bi=0; for(let i=1;i<rows.length;i++){ if(rows[i][1]>rows[bi][1]) bi=i; } return rows[bi][0]; }
+function teacherTop1(t){ return (t.t_top&&t.t_top.length)?amaxTok(t.t_top):null; }
+function agree(t){ return (t.top1_agree!=null) ? t.top1_agree
+  : (t.s_top&&t.t_top&&t.s_top.length&&t.t_top.length) ? amaxTok(t.s_top)===amaxTok(t.t_top) : true; }
+// gap = t_chosen - s_chosen, the detached student-teacher logprob gap (SDAR gate input,
+// AntiSD's PMI, SERL magnitude). 0 when either chosen logprob is missing.
+function gapOf(t){ return (t.t_chosen!=null && t.s_chosen!=null) ? (t.t_chosen - t.s_chosen) : 0; }
+function baseSignal(t){
+  switch(document.getElementById('signal').value){
+    case 'gap':     return gapOf(t);
+    case 'abs_gap': return Math.abs(gapOf(t));
+    case 'vopd':    return -t.kl_rev;            // vOPD value baseline -D_KL(pi||pi_T) ~ -kl_rev
+    case 'entropy': return t.entropy!=null ? t.entropy : 0;
+    default:        return t[document.getElementById('signal').value]; // kl_jsd | kl_rev | kl_fwd
+  }
+}
+// the single token-to-scalar chokepoint. Returns a SIGNED scalar (sign preserved through
+// clip); set-level stages (mask, top-p, cap, KDE, strip) all consume this. Transform order:
+// base -> gate -> importance -> clip.
+function signalOf(t){
+  let x = baseSignal(t);
+  if(document.getElementById('gate').checked) x *= 1/(1+Math.exp(-5*gapOf(t)));  // SDAR sigmoid gate beta=5
+  if(document.getElementById('isclip').checked){ const ic=DATA[cur].is_clip; if(ic) x *= Math.min(t.is_ratio, ic); }
+  const clip=+document.getElementById('clip').value;
+  if(clip>0) x = Math.sign(x) * Math.min(Math.abs(x), clip);   // clip magnitude, keep sign
+  return x;
+}
+function drawKDE(vals,cap){
+  const svg=document.getElementById('kde'),W=190,H=46,pad=3;
+  if(!vals.length){svg.innerHTML='';return;}
+  const xmax=Math.max(cap,Math.max(...vals))||1, n=vals.length;
+  const mean=vals.reduce((a,b)=>a+b,0)/n;
+  const sd=Math.sqrt(vals.reduce((a,b)=>a+(b-mean)*(b-mean),0)/n)||0.1;
+  const bw=Math.max(0.05,1.06*sd*Math.pow(n,-0.2)),M=80;
+  let ys=[],ymax=0;
+  for(let i=0;i<M;i++){const x=xmax*i/(M-1);let d=0;
+    for(const v of vals){const z=(x-v)/bw;d+=Math.exp(-0.5*z*z);}
+    d/=(n*bw*Math.sqrt(2*Math.PI));ys.push(d);if(d>ymax)ymax=d;}
+  ymax=ymax||1; const capx=pad+(W-2*pad)*Math.min(cap,xmax)/xmax;
+  let p=`M ${pad} ${H-pad}`;
+  for(let i=0;i<M;i++){const px=pad+(W-2*pad)*i/(M-1),py=H-pad-(H-2*pad)*ys[i]/ymax;p+=` L ${px.toFixed(1)} ${py.toFixed(1)}`;}
+  p+=` L ${W-pad} ${H-pad} Z`;
+  svg.innerHTML=`<path d="${p}" fill="#ff6b3566" stroke="#ff8a4a" stroke-width="1"/>`+
+    `<line x1="${capx.toFixed(1)}" y1="2" x2="${capx.toFixed(1)}" y2="${H-2}" stroke="#ff3b3088" stroke-width="1" stroke-dasharray="2,2"/>`;
+}
+// split the flat token stream into assistant turns at the unscored tool-result separator
+// (the only client-derivable boundary; drift tokens are unscored but keep the real token).
+function turnsOf(tokens){
+  const turns=[]; let cur=[];
+  for(const t of tokens){
+    if(!t.scored && /↳ tool result:/.test(t.tok)){ if(cur.length){turns.push(cur);cur=[];} continue; }
+    cur.push(t);
+  }
+  if(cur.length) turns.push(cur);
+  return turns;
+}
+// one bar per assistant turn, height = mean |displayed signal| over that turn's scored tokens.
+// Auto-hide for single-turn rollouts (no degenerate single bar).
+function drawStrip(tokens){
+  const svg=document.getElementById('strip'); if(!svg) return;
+  const turns=turnsOf(tokens).map(ts=>{
+    const v=ts.filter(t=>t.scored).map(t=>Math.abs(signalOf(t)));
+    return v.length ? v.reduce((a,b)=>a+b,0)/v.length : 0;
+  });
+  if(turns.length<2){ svg.innerHTML=''; svg.style.display='none'; return; }   // single-turn: degrade
+  svg.style.display='';
+  const W=150,H=46,pad=4, ymax=Math.max(...turns)||1, n=turns.length, bw=(W-2*pad)/n;
+  svg.innerHTML=turns.map((m,i)=>{
+    const h=(H-2*pad)*m/ymax, x=pad+i*bw+1, y=H-pad-h;
+    return `<rect x="${x.toFixed(1)}" y="${y.toFixed(1)}" width="${(bw-2).toFixed(1)}" height="${h.toFixed(1)}" fill="#ff8a4a" opacity="0.8"/>`;
+  }).join('');
+}
+// diverging map: intensity from |x|/cap; warm hue for x>=0 (teacher-favored / positive),
+// cool for x<0 (student-favored / negative); outline at the cap in the matching hue.
+function color(x,cap){
+  const a=Math.min(1,Math.sqrt(Math.abs(x)/cap)), warm=x>=0;
+  const hue=warm?35-35*a:210, light=55-12*a;
+  const ol=Math.abs(x)>=cap?(';outline:1.5px solid '+(warm?'#ff3b30':'#3b82f6')+';outline-offset:-1px'):'';
+  return `background:hsla(${hue},85%,${light}%,${a.toFixed(3)})${ol}`;
+}
+function esc(s){return s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');}
+function tops(rows){return rows.map(([t,p])=>`${esc(t)}=${p}`).join(' &middot; ');}
+// position the hover tooltip; flip it ABOVE the cursor when it would overflow the viewport bottom
+function placeTip(tip,e){
+  tip.style.display='block';
+  tip.style.left=Math.min(e.clientX+14,innerWidth-540)+'px';
+  const th=tip.offsetHeight||140;
+  tip.style.top=(e.clientY+18+th>innerHeight ? Math.max(8,e.clientY-th-14) : e.clientY+18)+'px';
+}
+function render(){
+  const r=DATA[cur]; if(!r){return;} sel.value=String(cur);
+  const clip=+document.getElementById('clip').value; document.getElementById('clipv').textContent=clip>0?clip:'off';
+  const dis=document.getElementById('disagree').checked;
+  const ntop1=document.getElementById('nottop1').checked;
+  const masked = t => (dis && agree(t)) || (ntop1 && t.realized_top1);   // mask -> excluded
+  const allScored=r.tokens.filter(t=>t.scored);
+  const nDis=allScored.filter(t=>!agree(t)).length;
+  let scored=r.tokens.filter(t=>t.scored && !masked(t));
+  // top-p selection on |signal|: keep the smallest set whose cumulative |signal| >= p*total
+  const topp=+document.getElementById('topp').value;
+  const tv=document.getElementById('toppv'); if(tv) tv.textContent=topp>0?topp:'off';
+  if(topp>0 && topp<1 && scored.length){
+    const ranked=[...scored].sort((a,b)=>Math.abs(signalOf(b))-Math.abs(signalOf(a)));
+    const total=ranked.reduce((s,t)=>s+Math.abs(signalOf(t)),0)||1; let acc=0; const keep=new Set();
+    for(const t of ranked){ keep.add(t); acc+=Math.abs(signalOf(t)); if(acc>=topp*total) break; }
+    scored=scored.filter(t=>keep.has(t));
+  }
+  const shown=new Set(scored);   // survivors get colored; mask/top-p exclusions stay transparent text
+  // colour reference = MAX of |displayed signal| over survivors, so intensity spans the full
+  // range and the high end stays discriminable. The KDE is over magnitude; sign lives in color().
+  const sls=scored.map(signalOf), abs=sls.map(Math.abs);
+  const mean=sls.reduce((a,b)=>a+b,0)/(sls.length||1);
+  const cap=abs.length ? abs.reduce((m,x)=>x>m?x:m,0) : CAP;
+  const fid=100*allScored.filter(t=>t.realized_top1).length/(allScored.length||1);
+  drawKDE(abs,cap);
+  drawStrip(r.tokens);
+  const rw = r.reward==null ? '' : ` &middot; <b style="color:${r.reward>=1?'#7ee787':'#ff7b72'}">${r.reward>=1?'SOLVED':'failed'} (${r.reward})</b>`;
+  const src = r.backend ? ` &middot; <span class=lab>${esc(r.backend)} &middot; top-${r.k||'?'}${r.k&&r.k<100?' <span style="color:#d8a14a">(coarse tail)</span>':''}</span>` : '';
+  const sel_active = dis || ntop1 || (topp>0 && topp<1);
+  const disLab = sel_active ? `${scored.length} shown / ${r.n_scored} scored toks &middot; mean signal ${mean.toFixed(3)} &middot; ${nDis} top-1 disagree` : `${r.n_scored} scored / ${r.n_total} toks &middot; mean signal ${mean.toFixed(3)} &middot; ${nDis} top-1 disagree`;
+  const legend = `<span class=u>grey = tool/unscored</span>` + (sel_active?` &middot; <span class=lab>uncolored = masked/excluded (signal 0)</span>`:``);
+  document.getElementById('hdr').innerHTML=`<b>${r.sample}</b>${rw}${src} &middot; &alpha;=${r.alpha} &middot; ${disLab} &middot; realized==student-top1: <b>${fid.toFixed(0)}%</b> &middot; ${legend}`;
+  // Show the full picture in one continuous view: the reprompt template (question +
+  // hindsight injected) as a grey lead-in, then the generated completion colored by KL.
+  const st=document.getElementById('stream'); st.innerHTML='';
+  if(r.hint_prompt){
+    const pre=document.createElement('div');
+    pre.className='hint-prompt';
+    pre.textContent=r.hint_prompt;
+    st.appendChild(pre);
+  }
+  r.tokens.forEach((tk)=>{const sp=document.createElement('span');
+    sp.textContent=tk.tok.replace(/\n/g,'↵');
+    if(!tk.scored){ sp.className='u';   // only tool-response / unscored tokens are greyed
+      sp.onmousemove=(e)=>{const tip=document.getElementById('tip');
+        tip.innerHTML=`<span class=lab>tool response / unscored (response_mask=0, no loss)</span>`;
+        placeTip(tip,e);};
+      sp.onmouseleave=()=>document.getElementById('tip').style.display='none';
+      st.appendChild(sp); return; }
+    // masked / top-p-excluded tokens stay readable text with transparent background, not greyed
+    const vis = shown.has(tk);
+    const L = vis ? signalOf(tk) : 0; sp.className='t'; sp.style.cssText=color(L,cap);
+    sp.onmousemove=(e)=>{const tip=document.getElementById('tip');
+      const agr = agree(tk)
+        ? ` <span class=s>top-1 AGREE</span>`
+        : ` <span class=tt>top-1 DISAGREE &rarr; teacher wants ${esc(teacherTop1(tk)||'?')}</span>`;
+      const g = gapOf(tk), favs = g>=0 ? '<span class=tt>teacher-favored</span>' : '<span class=s>student-favored</span>';
+      tip.innerHTML=
+        `<b class=kl>signal ${signalOf(tk).toFixed(3)}</b> <span class=lab>(${document.getElementById('signal').value})</span>${agr}<br>`+
+        `<span class=lab>gap t&minus;s:</span> <b>${g>=0?'+':''}${g.toFixed(3)}</b> ${favs} `+
+        `<span class=lab>&middot; s_chosen ${tk.s_chosen} &middot; t_chosen ${tk.t_chosen}</span><br>`+
+        `<span class=lab>kl jsd ${tk.kl_jsd} rev ${tk.kl_rev} fwd ${tk.kl_fwd} &middot; H ${tk.entropy} &middot; eff ${tk.eff_support}</span><br>`+
+        `<span class=lab>realized:</span> ${esc(tk.tok)} ${tk.realized_top1?'<span class=s>(=student top-1)</span>':'<span class=tt>(NOT top-1)</span>'}<br>`+
+        `<span class=s>student:</span> ${tops(tk.s_top)}<br><span class=tt>teacher:</span> ${tops(tk.t_top)}`;
+      placeTip(tip,e);};
+    sp.onmouseleave=()=>document.getElementById('tip').style.display='none';
+    st.appendChild(sp);});
+}
+function nav(d){if(!DATA.length)return;cur=(cur+d+DATA.length)%DATA.length;render();}
+function computeCap(recs){
+  const kls=[]; for(const r of recs) for(const t of r.tokens) if(t.scored) kls.push(t.kl_jsd);
+  kls.sort((a,b)=>a-b);
+  return kls.length ? Math.round(kls[Math.floor(0.95*(kls.length-1))]*100)/100 : 6.0;
+}
+function repopulate(){
+  sel.innerHTML='';
+  DATA.forEach((r,i)=>{const o=document.createElement('wa-option');o.value=String(i);o.textContent=`${i+1}/${DATA.length}  ${r.sample}`;sel.appendChild(o);});
+}
+// static bootstrap: load a fixed corpus with a precomputed CAP
+function setData(recs, cap){
+  DATA=recs||[]; CAP=(cap!=null)?cap:computeCap(DATA);
+  cur=Math.min(cur, Math.max(0, DATA.length-1)); repopulate();
+  if(DATA.length) render();
+  else {document.getElementById('stream').innerHTML='';document.getElementById('hdr').innerHTML='';}
+}
+// live mode: append one freshly-scored record, recompute CAP, jump to it
+function addRecord(rec){ DATA.push(rec); CAP=computeCap(DATA); cur=DATA.length-1; repopulate(); render(); }
+// Wire the loss-control bar. Web Awesome's wa-select / wa-slider / wa-switch emit
+// NATIVE change/input events, so plain addEventListener works (no wa- prefix).
+function _wire(id,ev,fn){const el=document.getElementById(id); if(el) el.addEventListener(ev,fn);}
+_wire('sel','change',function(){cur=+this.value;render();});
+_wire('signal','change',render);
+_wire('clip','input',render);
+_wire('gate','change',render);
+_wire('isclip','change',render);
+_wire('topp','input',render);
+_wire('disagree','change',render);
+_wire('nottop1','change',render);
+document.onkeydown=(e)=>{
+  const t=e.target, tag=t&&t.tagName;
+  if(tag==='WA-INPUT'||tag==='WA-TEXTAREA'||tag==='INPUT'||tag==='TEXTAREA') return;  // don't hijack typing
+  if(e.key==='ArrowLeft')nav(-1);if(e.key==='ArrowRight')nav(1);
+};