step-through viewer over recorded decoder traces

README.md

@@ -1,10 +1,27 @@
 ---
-title: Sbd Sql Decoder
-emoji: 📉
-colorFrom: green
+title: Set Block Decoding
+emoji: ⚡
+colorFrom: gray
 colorTo: indigo
 sdk: static
+app_file: index.html
 pinned: false
+license: apache-2.0
+models:
+  - belumind/sbd-sql-0.5b
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Set Block Decoding, step by step
+
+Step through real decoding runs of [`belumind/sbd-sql-0.5b`](https://huggingface.co/belumind/sbd-sql-0.5b):
+one 0.5B model proposing a block of tokens past the frontier and verifying every one of them exactly.
+
+Each token is coloured by where the accepted proposal came from — the causal NTP frontier, the
+masked block (MATP), or an n-gram copied out of the prompt — and rollbacks show the verifier
+refusing a guess and committing the true conditional instead.
+
+These are **recorded runs, not live inference**: every step is a real `sbd_generate` call executed on
+an A100 in bf16 and logged forward pass by forward pass. The tracer was checked against the shipped
+decoder and reproduces it token for token. For live generation, run
+[`demo/demo_colab.ipynb`](https://huggingface.co/belumind/sbd-sql-0.5b/blob/main/demo/demo_colab.ipynb)
+on a Colab GPU.

index.html

@@ -1,19 +1,299 @@
 <!doctype html>
-<html>
-	<head>
-		<meta charset="utf-8" />
-		<meta name="viewport" content="width=device-width" />
-		<title>My static Space</title>
-		<link rel="stylesheet" href="style.css" />
-	</head>
-	<body>
-		<div class="card">
-			<h1>Welcome to your static Space!</h1>
-			<p>You can modify this app directly by editing <i>index.html</i> in the Files and versions tab.</p>
-			<p>
-				Also don't forget to check the
-				<a href="https://huggingface.co/docs/hub/spaces" target="_blank">Spaces documentation</a>.
-			</p>
-		</div>
-	</body>
-</html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Set Block Decoding — step through a real run</title>
+<style>
+:root{
+  --bg:#fbfbfa; --panel:#ffffff; --ink:#1d1c1a; --muted:#6b6862; --line:#e4e1db;
+  --ntp:#8a8781; --ntp-bg:#f1efeb;
+  --matp:#2f6f8f; --matp-bg:#e2eef4;
+  --ngram:#9a6b1f; --ngram-bg:#f7eddb;
+  --bad:#a33a2c; --bad-bg:#f8e6e2;
+  --accent:#1d1c1a;
+}
+@media (prefers-color-scheme: dark){
+  :root:not([data-theme="light"]){
+    --bg:#141413; --panel:#1c1c1a; --ink:#eeece7; --muted:#93908a; --line:#2f2e2b;
+    --ntp:#8f8c86; --ntp-bg:#262623;
+    --matp:#7fc2e0; --matp-bg:#16303c;
+    --ngram:#e0b46a; --ngram-bg:#3a2d15;
+    --bad:#e8897a; --bad-bg:#3a201c;
+    --accent:#eeece7;
+  }
+}
+*{box-sizing:border-box}
+body{margin:0;background:var(--bg);color:var(--ink);
+  font:15px/1.55 ui-sans-serif,system-ui,-apple-system,"Segoe UI",Inter,sans-serif;
+  -webkit-font-smoothing:antialiased}
+.wrap{max-width:1080px;margin:0 auto;padding:32px 20px 72px}
+h1{font-size:26px;line-height:1.2;margin:0 0 6px;letter-spacing:-.01em}
+h2{font-size:15px;text-transform:uppercase;letter-spacing:.07em;color:var(--muted);
+  margin:36px 0 12px;font-weight:600}
+a{color:inherit;text-decoration:underline;text-underline-offset:2px;text-decoration-thickness:1px}
+.sub{color:var(--muted);margin:0 0 20px;max-width:62ch}
+.note{border:1px solid var(--line);border-left:3px solid var(--accent);background:var(--panel);
+  padding:12px 14px;border-radius:6px;color:var(--muted);font-size:13.5px;max-width:72ch;margin:0 0 26px}
+.note b{color:var(--ink)}
+.panel{background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:16px}
+.controls{display:grid;grid-template-columns:repeat(auto-fit,minmax(190px,1fr));gap:14px;margin-bottom:14px}
+label{display:block;font-size:12px;text-transform:uppercase;letter-spacing:.06em;
+  color:var(--muted);margin-bottom:5px;font-weight:600}
+select,button{font:inherit;font-size:14px;color:var(--ink);background:var(--panel);
+  border:1px solid var(--line);border-radius:6px;padding:7px 9px;width:100%}
+button{cursor:pointer;font-weight:500}
+button:hover{border-color:var(--muted)}
+button:disabled{opacity:.4;cursor:default}
+.row{display:flex;gap:8px;align-items:center}
+.row button{width:auto;padding:7px 14px}
+input[type=range]{width:100%;accent-color:var(--accent)}
+.layout{display:grid;grid-template-columns:1fr 250px;gap:16px;align-items:start}
+@media(max-width:820px){.layout{grid-template-columns:1fr}}
+.stream{font:13.5px/1.9 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;
+  white-space:pre-wrap;word-break:break-word;min-height:180px}
+.tk{border-radius:3px;padding:1px 0}
+.tk.ntp{background:var(--ntp-bg)}
+.tk.matp{background:var(--matp-bg);color:var(--matp)}
+.tk.ngram{background:var(--ngram-bg);color:var(--ngram)}
+.tk.fix{background:var(--bad-bg);color:var(--bad);text-decoration:underline;
+  text-decoration-style:wavy;text-underline-offset:3px}
+.prop{opacity:.95}
+.prop .tk{outline:1px dashed currentColor;outline-offset:1px}
+.prop .rej{opacity:.35;text-decoration:line-through}
+.cursor{display:inline-block;width:2px;height:1em;background:var(--accent);
+  vertical-align:-2px;margin:0 1px;animation:b 1.1s steps(1) infinite}
+@keyframes b{50%{opacity:0}}
+.stat{display:flex;justify-content:space-between;gap:10px;padding:7px 0;
+  border-bottom:1px solid var(--line);font-size:13.5px}
+.stat:last-child{border-bottom:0}
+.stat span:first-child{color:var(--muted)}
+.stat b{font-variant-numeric:tabular-nums;font-weight:600}
+.big{font-size:26px;font-variant-numeric:tabular-nums;letter-spacing:-.02em;margin:2px 0 0}
+.verdict{margin-top:12px;font-size:13.5px;padding:9px 11px;border-radius:6px;
+  border:1px solid var(--line);background:var(--bg)}
+.verdict.roll{border-color:var(--bad);color:var(--bad)}
+.key{display:flex;flex-wrap:wrap;gap:14px;margin:12px 0 0;font-size:12.5px;color:var(--muted)}
+.key i{display:inline-block;width:11px;height:11px;border-radius:3px;margin-right:5px;
+  vertical-align:-1px;font-style:normal}
+table{border-collapse:collapse;width:100%;font-size:13.5px;margin-top:4px}
+th,td{text-align:left;padding:7px 10px;border-bottom:1px solid var(--line)}
+th{color:var(--muted);font-weight:600;font-size:12px;text-transform:uppercase;letter-spacing:.05em}
+td.n,th.n{text-align:right;font-variant-numeric:tabular-nums}
+.scroll{overflow-x:auto}
+details{margin-top:10px;border-top:1px solid var(--line);padding-top:10px}
+summary{cursor:pointer;color:var(--muted);font-size:13px}
+pre.pt{font:12.5px/1.6 ui-monospace,Menlo,monospace;white-space:pre-wrap;
+  color:var(--muted);max-height:200px;overflow:auto;margin:8px 0 0}
+footer{margin-top:44px;padding-top:18px;border-top:1px solid var(--line);
+  color:var(--muted);font-size:13px}
+</style>
+</head>
+<body>
+<div class="wrap">
+
+<h1>Set Block Decoding, step by step</h1>
+<p class="sub">One 0.5B model proposes a block of tokens past the frontier and verifies every one of
+them exactly. Step through a run and watch where each accepted token came from — and what happens
+when the verifier says no.</p>
+
+<div class="note">
+<b>These are recorded runs, not live inference.</b> Every step below is a real
+<code>sbd_generate</code> call on <a href="https://huggingface.co/belumind/sbd-sql-0.5b">belumind/sbd-sql-0.5b</a>,
+executed on an A100 in bf16 and logged forward pass by forward pass; the tracer was checked
+against the shipped decoder and reproduces it token for token. A live Gradio Space needs paid
+hardware, so the interactive version runs in Colab —
+<a href="https://huggingface.co/belumind/sbd-sql-0.5b/blob/main/demo/demo_colab.ipynb">demo/demo_colab.ipynb</a>.
+</div>
+
+<div class="controls">
+  <div><label for="p">Prompt</label><select id="p"></select></div>
+  <div><label for="m">Proposal sources</label><select id="m"></select></div>
+  <div><label for="s">Step</label><div class="row">
+    <button id="prev">&larr;</button><button id="next">&rarr;</button><button id="play">Play</button>
+  </div></div>
+</div>
+<input type="range" id="s" min="0" value="0" style="margin-bottom:16px">
+
+<div class="layout">
+  <div class="panel">
+    <div class="stream" id="stream"></div>
+    <div class="verdict" id="verdict"></div>
+    <div class="key">
+      <span><i style="background:var(--ntp-bg);border:1px solid var(--ntp)"></i>NTP frontier</span>
+      <span><i style="background:var(--matp-bg);border:1px solid var(--matp)"></i>MATP block</span>
+      <span><i style="background:var(--ngram-bg);border:1px solid var(--ngram)"></i>n-gram copy</span>
+      <span><i style="background:var(--bad-bg);border:1px solid var(--bad)"></i>correction after rollback</span>
+      <span>dashed outline = proposed, not yet verified</span>
+    </div>
+    <details><summary>Show the prompt</summary><pre class="pt" id="ptxt"></pre></details>
+  </div>
+
+  <div class="panel">
+    <div style="color:var(--muted);font-size:12px;text-transform:uppercase;letter-spacing:.06em;font-weight:600">tokens / forward</div>
+    <div class="big" id="tpf">—</div>
+    <div style="height:10px"></div>
+    <div class="stat"><span>forward passes</span><b id="fw">0</b></div>
+    <div class="stat"><span>tokens committed</span><b id="tc">0</b></div>
+    <div class="stat"><span>rollbacks</span><b id="rb">0</b></div>
+    <div class="stat"><span>from NTP</span><b id="a-ntp">0</b></div>
+    <div class="stat"><span>from MATP</span><b id="a-matp">0</b></div>
+    <div class="stat"><span>from n-gram</span><b id="a-ngram">0</b></div>
+    <div class="stat" style="border-top:1px solid var(--line);margin-top:8px;padding-top:9px">
+      <span>run total</span><b id="final">—</b></div>
+  </div>
+</div>
+
+<h2>What the whole run measures</h2>
+<div class="panel scroll">
+  <table id="runs"><thead><tr>
+    <th>Prompt</th><th>Sources</th><th class="n">&tau;</th><th class="n">tok/fwd</th>
+    <th class="n">forwards</th><th class="n">rollbacks</th><th class="n">MATP</th><th class="n">n-gram</th>
+  </tr></thead><tbody></tbody></table>
+</div>
+<p class="sub" style="margin-top:12px;font-size:13.5px">
+Single runs, so they scatter. The averaged numbers — 1.87 tok/fwd on 20 held-out real documents,
+2.28 on a template-generated set, and what that gap means — are on the
+<a href="https://huggingface.co/belumind/sbd-sql-0.5b">model card</a>.</p>
+
+<h2>How to read it</h2>
+<div class="panel" style="max-width:74ch">
+<p style="margin-top:0"><b>Every forward pass proposes and verifies at the same time.</b> The block of
+8 mask tokens appended after the frontier gives the MATP guesses; the same pass recomputes the true
+conditionals for the tokens proposed last round, which is what verification costs — nothing extra.</p>
+<p><b>The first proposed token is always exact.</b> It is the ordinary next-token prediction at a
+purely causal frontier, so the decoder can never fall below one token per forward.</p>
+<p><b>A rollback is not an error.</b> It is the verifier refusing a guess. Output stays identical to
+greedy decoding — measured at 100% agreement in bf16 and fp32 — and &tau; only trades rollbacks
+against speed. Loosen it and you will see more crossed-out tokens here, and a higher tok/fwd anyway.</p>
+<p style="margin-bottom:0"><b>tokens/forward is not wall-clock.</b> This reference decoder keeps no
+KV cache and recomputes the whole sequence every step. It still beat
+<code>generate(use_cache=True)</code> by 1.58&times; end to end on the same A100 — a
+<code>transformers</code> baseline, not an optimised server.</p>
+</div>
+
+<footer>
+Built by <a href="https://huggingface.co/belumind">Belumind</a> ·
+<a href="https://huggingface.co/belumind/sbd-sql-0.5b">model &amp; card</a> ·
+method: <a href="https://arxiv.org/abs/2509.04185">Set Block Decoding</a> (arXiv 2509.04185)
+<span id="meta" style="display:block;margin-top:6px"></span>
+</footer>
+</div>
+
+<script>
+let B=null,cur=null,step=0,timer=null;
+
+const $=id=>document.getElementById(id);
+const esc=s=>s.replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;");
+const vis=s=>esc(s).replace(/\n/g,"⏎\n");
+const MODES={union:"NTP + MATP + n-gram",matp:"NTP + MATP",ngram:"NTP + n-gram",ntp:"NTP only (no speculation)"};
+
+fetch("traces.json").then(r=>r.json()).then(b=>{B=b;init()})
+ .catch(e=>{$("stream").textContent="Could not load traces.json — "+e});
+
+function init(){
+  $("meta").textContent = B.meta.model+" · "+B.meta.gpu+" · "+B.meta.dtype
+    +" · block "+B.meta.block_size+" · "+B.meta.prompt_tokens+"-token prompt, "
+    +B.meta.max_new_tokens+" new tokens · recorded "+B.meta.recorded;
+  B.prompts.forEach(p=>{const o=document.createElement("option");o.value=p.id;o.textContent=p.label;$("p").appendChild(o)});
+  const seen=[];
+  B.runs.forEach(r=>{const k=r.mode+"|"+r.tau;
+    if(seen.indexOf(k)<0){seen.push(k);
+      const o=document.createElement("option");o.value=k;
+      o.textContent=MODES[r.mode]+(r.mode==="ntp"?"":"  ·  τ "+r.tau.toFixed(2));
+      $("m").appendChild(o)}});
+  $("m").value="union|0.6";
+  fillTable();
+  ["p","m"].forEach(id=>$(id).onchange=pick);
+  $("s").oninput=()=>{step=+$("s").value;stop();render()};
+  $("prev").onclick=()=>{stop();step=Math.max(0,step-1);render()};
+  $("next").onclick=()=>{stop();step=Math.min(cur.steps.length-1,step+1);render()};
+  $("play").onclick=play;
+  pick();
+}
+
+function pick(){
+  const [m,t]=$("m").value.split("|");
+  cur=B.runs.find(r=>r.prompt===$("p").value&&r.mode===m&&r.tau===+t);
+  step=0;$("s").max=cur.steps.length-1;$("s").value=0;
+  $("ptxt").textContent=B.prompts.find(p=>p.id===cur.prompt).text;
+  stop();render();
+}
+
+function play(){
+  if(timer){stop();return}
+  if(step>=cur.steps.length-1)step=0;
+  $("play").textContent="Pause";
+  timer=setInterval(()=>{
+    if(step>=cur.steps.length-1){stop();return}
+    step++;$("s").value=step;render();
+  },520);
+}
+function stop(){if(timer)clearInterval(timer);timer=null;$("play").textContent="Play"}
+
+function render(){
+  $("s").value=step;
+  let html="",fw=0,tc=0,rb=0,a={ntp:0,matp:0,ngram:0};
+  for(let i=0;i<step;i++){
+    const st=cur.steps[i],v=st.verdict;fw++;
+    if(!v){continue}
+    const kept=v.kept;
+    for(let j=0;j<kept;j++){
+      const tk=st.propose[j];
+      html+='<span class="tk '+tk.src+'">'+vis(tk.t)+'</span>';
+      a[tk.src]++;tc++;
+    }
+    if(v.rollback){
+      rb++;html+='<span class="tk fix">'+vis(v.fix)+'</span>';
+      a.ntp++;tc++;
+    }
+  }
+  const st=cur.steps[step];fw++;
+  html+='<span class="cursor"></span><span class="prop">';
+  const v=st.verdict,kept=v?v.kept:st.propose.length;
+  st.propose.forEach((tk,j)=>{
+    const rej=v&&v.rollback&&j>=kept;
+    html+='<span class="tk '+tk.src+(rej?" rej":"")+'">'+vis(tk.t)+'</span>';
+  });
+  html+='</span>';
+  $("stream").innerHTML=html;
+
+  let msg;
+  if(!v){msg="Last block of the run — nothing left to verify.";$("verdict").className="verdict"}
+  else if(v.rollback){
+    msg="Next pass verified "+kept+" of "+st.propose.length+" proposed token"
+      +(st.propose.length===1?"":"s")+", then rejected the rest and committed "
+      +JSON.stringify(v.fix)+" from the true conditional.";
+    $("verdict").className="verdict roll";
+  }else{
+    msg="Next pass verified all "+kept+" proposed token"+(kept===1?"":"s")+" — "
+      +kept+" token"+(kept===1?"":"s")+" from one forward pass.";
+    $("verdict").className="verdict";
+  }
+  $("verdict").textContent="Step "+(step+1)+" of "+cur.steps.length+". "+msg;
+
+  $("fw").textContent=fw;$("tc").textContent=tc;$("rb").textContent=rb;
+  $("a-ntp").textContent=a.ntp;$("a-matp").textContent=a.matp;$("a-ngram").textContent=a.ngram;
+  $("tpf").textContent=fw?(tc/fw).toFixed(2):"—";
+  $("final").textContent=cur.tok_per_fwd.toFixed(2)+" tok/fwd";
+}
+
+function fillTable(){
+  const tb=$("runs").querySelector("tbody");
+  B.runs.forEach(r=>{
+    const tot=r.accepted.ntp+r.accepted.matp+r.accepted.ngram||1;
+    const tr=document.createElement("tr");
+    tr.innerHTML="<td>"+B.prompts.find(p=>p.id===r.prompt).label+"</td>"
+      +"<td>"+MODES[r.mode]+"</td>"
+      +'<td class="n">'+(r.mode==="ntp"?"—":r.tau.toFixed(2))+"</td>"
+      +'<td class="n"><b>'+r.tok_per_fwd.toFixed(2)+"</b></td>"
+      +'<td class="n">'+r.forwards+"</td>"
+      +'<td class="n">'+r.rollbacks+"</td>"
+      +'<td class="n">'+Math.round(100*r.accepted.matp/tot)+"%</td>"
+      +'<td class="n">'+Math.round(100*r.accepted.ngram/tot)+"%</td>";
+    tb.appendChild(tr);
+  });
+}
+</script>
+</body>
+</html>