Add simultaneous streaming image and video comparisons

.gitattributes

@@ -36,3 +36,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 docs/assets/demo-poster.jpg filter=lfs diff=lfs merge=lfs -text
 docs/assets/demo.mp4 filter=lfs diff=lfs merge=lfs -text
 tokenizer.json filter=lfs diff=lfs merge=lfs -text
+gemma_rlcd/static/sample-street.jpg filter=lfs diff=lfs merge=lfs -text

MANIFEST.in

@@ -3,6 +3,6 @@ recursive-include docs *.md *.txt *.jpg *.mp4 *.json
 recursive-include examples *.json *.jsonl *.txt
 recursive-include reports *.md *.json
 recursive-include scripts *.py
-recursive-include tests *.py
-recursive-include gemma_rlcd/static *.html *.css *.js *.json
+recursive-include tests *.py *.cjs
+recursive-include gemma_rlcd/static *.html *.css *.js *.json *.jpg
 global-exclude .DS_Store *.py[cod] *.safetensors *.gguf

README.md

@@ -52,6 +52,10 @@ Choose **Run all fields** for answers and distributions, or **Compare with Gemma
 
 The download is approximately 3.6 GB and includes the image and audio encoders, tokenizer, processor, and chat template. Inference runs locally on Apple Silicon through MLX.
 
+### Live visual demo
+
+Open **http://127.0.0.1:8787/demo** for 32, 64, or 128 checks over an image or video. Use the included street photo or upload your own media. The parallel scorer streams completed field batches; normal Gemma streams its generated JSON. Live clocks, per-check probabilities, answer differences, and downloadable events make the comparison inspectable. Both paths start together and stream side by side, sharing the resident weights with separate processors and KV caches. Timings measure concurrent completion on one GPU, including resource contention. The playground’s ordinary comparison remains sequential for isolated timings.
+
 ## How it works
 
 ```mermaid
@@ -130,7 +134,7 @@ A ratio above 1 favors parallel scoring. The support example matches all 28 outp
 
 The playground accepts up to eight images, one audio source, and one video, with 200 MB of uploads per request. Audio and videos with sound support up to 30 seconds; silent video supports up to 60 seconds. Video targets one frame per second, capped at 32 frames, so brief events can fall between samples.
 
-Requests support up to 32 named fields, 64 primitive decisions, and 8,192 processed input tokens. Oversized inputs return an error rather than being truncated. Multi-picture phone JPEGs use the full-resolution primary photograph. Text and field definitions are saved in browser local storage; uploaded media is not retained.
+Requests support up to 32 named fields, 128 primitive decisions, and 8,192 processed input tokens. Oversized inputs return an error rather than being truncated. Multi-picture phone JPEGs use the full-resolution primary photograph. Text and field definitions are saved in browser local storage; uploaded media is not retained.
 
 ## Development
 

THIRD_PARTY_NOTICES.md

@@ -45,6 +45,10 @@ The project's MIT license applies to project code and synthetic examples, not th
 
 The demo video and poster use IBM Plex Sans, licensed under the SIL Open Font License. The license is retained in [docs/assets/Plex-OFL.txt](docs/assets/Plex-OFL.txt).
 
+## Visual demo photograph
+
+`gemma_rlcd/static/sample-street.jpg` is “Times Square (New York City)” by ISO Legacy, from [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Times_Square_(New_York_City).jpg), dedicated under [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/). The original photograph is included without modification.
+
 ## Bundled checkpoint
 
 The complete Gemma 4 E2B MLX checkpoint is included unchanged from the revision in [checkpoint provenance](checkpoint-provenance.json). Model licensing and attribution are retained in [MODEL_LICENSE](MODEL_LICENSE) and [NOTICE](NOTICE). The original conversion card is preserved in [docs/upstream-mlx-model-card.md](docs/upstream-mlx-model-card.md).

checkpoint-provenance.json

@@ -1,7 +1,7 @@
 {
   "repository": "larkooo/gemma-e2b-rlcd",
   "runtime_repository": "https://github.com/Larkooo/gemma-e2b-rlcd",
-  "runtime_commit": "2eb9b959e989b08eb140578282336223243a6084",
+  "runtime_commit": "e78b79605ac4e37b776727935e2de7dc8f259a81",
   "checkpoint_repository": "mlx-community/gemma-4-e2b-it-4bit",
   "checkpoint_revision": "238767527555cb75a05732a84dff5d6ba0dd6809",
   "checkpoint_modified": false,

docs/architecture.md

@@ -53,7 +53,7 @@ Float32 reduced the probability drift observed when changing execution shapes un
 - One silent video up to 60 seconds, sampled at a target of 1 fps with a 32-frame processor cap.
 - A video's soundtrack is included automatically. Videos with audio have a 30-second limit; a second audio source returns an error.
 - Up to 8,192 processed input tokens by default. Inputs exceeding the limit are rejected without truncation.
-- Up to 32 named fields and 64 primitive decisions in the playground.
+- Up to 32 named fields and 128 primitive decisions in the playground.
 - Questions and descriptions are strings; the Python contracts use name-to-description mappings.
 
 Video sampling can miss brief events. The limits describe the current serving configuration rather than the checkpoint's maximum context capacity.

gemma_rlcd/cached_backend.py

@@ -149,7 +149,11 @@ class CachedMLXBackend(MLXBackend):
         return scores
 
     def branches(
-        self, prepared: PreparedState, prefix_cache, requests: Sequence[ScoringRequest]
+        self,
+        prepared: PreparedState,
+        prefix_cache,
+        requests: Sequence[ScoringRequest],
+        on_batch=None,
     ) -> list[TokenScores]:
         mx = self.mx
         scores = []
@@ -188,9 +192,10 @@ class CachedMLXBackend(MLXBackend):
                 :, 0, :
             ].astype(mx.float32)
             mx.eval(logits)
-            scores.extend(
-                self._extract(logits, batch, [prepared.prefix_tokens + n for n in lengths])
-            )
+            completed = self._extract(logits, batch, [prepared.prefix_tokens + n for n in lengths])
+            scores.extend(completed)
+            if on_batch is not None:
+                on_batch(start, completed)
             batch_sizes.append(len(batch))
             tail_lengths.append(tail_length)
         self.last_stats["branch_batch_sizes"] = batch_sizes

gemma_rlcd/comparison.py

@@ -2,6 +2,10 @@
 
 import json
 import time
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import nullcontext
+from copy import copy, deepcopy
+from threading import Barrier
 
 from .core import Choice, DecisionEngine, Independent, Noul, Score, State
 from .mlx_backend import audio_paths
@@ -140,17 +144,14 @@ def prepare_generation(backend, state: State, questions: dict) -> tuple[str, dic
     return prompt, inputs
 
 
-def generate_answers(backend, state: State, questions: dict) -> dict:
-    from mlx_vlm import generate
+def generate_answers(backend, state: State, questions: dict, on_token=None) -> dict:
+    from mlx_vlm import generate, stream_generate
 
     started = time.perf_counter()
     prompt, inputs = prepare_generation(backend, state, questions)
     budget = output_budget(backend.tokenizer, questions)
     prepared = time.perf_counter()
-    generated = generate(
-        backend.model,
-        backend.processor,
-        prompt,
+    options = dict(
         **inputs,
         max_tokens=budget,
         temperature=0,
@@ -158,19 +159,32 @@ def generate_answers(backend, state: State, questions: dict) -> dict:
         logits_to_keep=1,
         verbose=False,
     )
+    if on_token is None:
+        generated = generate(backend.model, backend.processor, prompt, **options)
+        text = generated.text
+    else:
+        parts = []
+        generated = None
+        for chunk in stream_generate(backend.model, backend.processor, prompt, **options):
+            generated = chunk
+            parts.append(chunk.text)
+            on_token(chunk.text, chunk.generation_tokens)
+        if generated is None:
+            raise RuntimeError("Gemma returned no generation result")
+        text = "".join(parts)
     backend.mx.synchronize()
     generated_at = time.perf_counter()
     error = None
     answers = None
     try:
-        answers = parse_generated(generated.text, questions)
+        answers = parse_generated(text, questions)
         if generated.finish_reason != "stop":
             error = "Generation reached its token limit without an end-of-answer token"
     except ValueError as exc:
         error = str(exc)
     return {
         "answers": answers,
-        "raw_text": generated.text,
+        "raw_text": text,
         "valid": error is None,
         "error": error,
         "finish_reason": generated.finish_reason,
@@ -197,30 +211,132 @@ def discrete_answers(answers: dict) -> dict:
     return values
 
 
-def compare(backend, state: State, questions: dict, media_seconds: float) -> tuple[dict, dict]:
-    def evaluate(method):
+def generation_backend(backend):
+    """Share evaluated weights while isolating mutable processor state."""
+    result = copy(backend)
+    if hasattr(backend, "processor"):
+        result.processor = deepcopy(backend.processor)
+        result.tokenizer = result.processor.tokenizer
+    return result
+
+
+def compare(
+    backend,
+    state: State,
+    questions: dict,
+    media_seconds: float,
+    emit=None,
+    *,
+    concurrent=False,
+    normal_backend=None,
+) -> tuple[dict, dict]:
+    def evaluate(method, worker_backend, race_started=None):
         # No cross-run KV or vision cache. Start each path with completed GPU
         # work and a cleared allocator cache; weights remain resident.
-        if hasattr(backend, "mx"):
-            backend.mx.synchronize()
-            backend.mx.clear_cache()
-        started = time.perf_counter()
+        if not concurrent and hasattr(worker_backend, "mx"):
+            worker_backend.mx.synchronize()
+            worker_backend.mx.clear_cache()
+        started = time.perf_counter() if race_started is None else race_started
+        if emit:
+            emit({"type": "phase_start", "method": method, "media_seconds": media_seconds})
+
+        def on_answer(path, answer):
+            value = discrete_answers({"answer": answer})["answer"]
+            if len(path) == 2:
+                value = answer["choice"] == "yes"
+            emit(
+                {
+                    "type": "answer",
+                    "method": method,
+                    "path": list(path),
+                    "value": value,
+                    "answer": answer,
+                    "seconds": media_seconds + time.perf_counter() - started,
+                }
+            )
+
+        def on_token(text, tokens):
+            emit(
+                {
+                    "type": "token",
+                    "method": method,
+                    "text": text,
+                    "tokens": tokens,
+                    "seconds": media_seconds + time.perf_counter() - started,
+                }
+            )
+
         if method == "parallel":
-            output = DecisionEngine(backend).system_one(state, questions)
-            if hasattr(backend, "mx"):
-                backend.mx.synchronize()
+            engine = DecisionEngine(worker_backend)
+            output = (
+                engine.system_one(state, questions, on_answer=on_answer)
+                if emit
+                else engine.system_one(state, questions)
+            )
+            if hasattr(worker_backend, "mx"):
+                worker_backend.mx.synchronize()
             output.update(
                 inference_seconds=time.perf_counter() - started,
-                execution=dict(backend.last_stats),
+                execution=dict(worker_backend.last_stats),
                 valid=True,
             )
         else:
-            output = generate_answers(backend, state, questions)
+            output = (
+                generate_answers(worker_backend, state, questions, on_token=on_token)
+                if emit
+                else generate_answers(worker_backend, state, questions)
+            )
+        if concurrent:
+            output["inference_seconds"] = time.perf_counter() - started
         output["total_seconds"] = media_seconds + output["inference_seconds"]
+        if emit:
+            emit(
+                {
+                    "type": "phase_complete",
+                    "method": method,
+                    "seconds": output["total_seconds"],
+                    "valid": output["valid"],
+                }
+            )
         return output
 
-    parallel = evaluate("parallel")
-    normal = evaluate("normal")
+    if concurrent:
+        # Share evaluated weights only. Tokenizers/processors and KV caches have
+        # mutable request state, so normal generation gets its own processor.
+        if normal_backend is None:
+            normal_backend = generation_backend(backend)
+        if hasattr(backend, "mx"):
+            backend.mx.synchronize()
+            backend.mx.clear_cache()
+        ready = Barrier(3)
+        race_started = None
+
+        def worker(method, worker_backend):
+            ready.wait()
+            mx = getattr(worker_backend, "mx", None)
+            stream = mx.new_stream(mx.default_device()) if mx is not None else None
+            with mx.stream(stream) if mx is not None else nullcontext():
+                try:
+                    return evaluate(method, worker_backend, race_started)
+                finally:
+                    if mx is not None:
+                        mx.synchronize(stream)
+
+        with ThreadPoolExecutor(max_workers=2, thread_name_prefix="comparison") as pool:
+            parallel_future = pool.submit(worker, "parallel", backend)
+            normal_future = pool.submit(worker, "normal", normal_backend)
+            try:
+                race_started = time.perf_counter()
+                if emit:
+                    emit({"type": "race_start", "media_seconds": media_seconds})
+                ready.wait()
+            except BaseException:
+                ready.abort()
+                raise
+            parallel, normal = parallel_future.result(), normal_future.result()
+    else:
+        parallel = evaluate("parallel", backend)
+        normal = evaluate("normal", backend)
     decisions = discrete_answers(parallel["answers"])
     return parallel, {
         "seconds": {"parallel": parallel["total_seconds"], "normal": normal["total_seconds"]},
@@ -234,8 +350,14 @@ def compare(backend, state: State, questions: dict, media_seconds: float) -> tup
             for name in questions
         },
         "methodology": {
+            "execution": "concurrent_shared_gpu" if concurrent else "sequential",
             "model": "Same resident Gemma 4 E2B 4-bit weights; float32 compute; all 35 layers",
-            "timing": "One run per path, parallel scorer first, normal generation second. Includes input preparation and inference; shared upload decoding added equally to each path. Excludes model loading, upload transfer, and allocator reset. No warm-up runs; first-use effects and run order can affect this observation.",
+            "timing": (
+                "Both paths start together with one common clock, separate worker streams, processors, and KV caches. They share the same GPU and compete for its resources. This is simultaneous completion time, not isolated throughput."
+                if concurrent
+                else "One run per path, parallel scorer first, normal generation second. No warm-up runs; first-use effects and run order can affect this observation."
+            )
+            + " Includes input preparation and inference; shared upload decoding added equally to each path. Excludes model loading, upload transfer, worker setup, and initial allocator reset.",
             "cache": "Fresh input KV and media features for every run; ordinary output-token KV caching remains enabled for normal generation.",
             "answers": "Normal Gemma generates one JSON object for all fields, greedily, without thinking. Compare choice names, most likely grade levels, and booleans at a 50% threshold. The scorer also returns probability distributions and expected grades. Agreement is not an accuracy measurement.",
         },

gemma_rlcd/core.py

@@ -216,7 +216,7 @@ class DecisionEngine:
     def decide(self, state: State, question: Question) -> dict:
         return self.system_one(state, {"answer": question})["answers"]["answer"]
 
-    def system_one(self, state: State, questions: Mapping[str, Question]) -> dict:
+    def system_one(self, state: State, questions: Mapping[str, Question], on_answer=None) -> dict:
         if not questions:
             raise ValueError("At least one question is required")
         jobs = []
@@ -257,8 +257,22 @@ class DecisionEngine:
                 jobs.append((question_id, child_id, child, criteria))
         question_score = getattr(self.backend, "score_questions", None)
         batch_score = getattr(self.backend, "score_batch", None)
+
+        def completed_scores(rows):
+            for index, score in rows:
+                question_id, child_id, question, criteria = jobs[index]
+                probabilities, diagnostics = self._distribution(criteria, score)
+                on_answer(
+                    (question_id,) if child_id is None else (question_id, child_id),
+                    self._answer(question, probabilities, diagnostics),
+                )
+
         if question_score is not None:
-            scores = question_score(state, questions)
+            scores = (
+                question_score(state, questions, on_scores=completed_scores)
+                if on_answer
+                else question_score(state, questions)
+            )
         elif batch_score is not None:
             scores = batch_score(state, requests)
         else:
@@ -267,6 +281,8 @@ class DecisionEngine:
             ]
         if len(scores) != len(jobs):
             raise ValueError("Backend returned the wrong number of question results")
+        if on_answer is not None and question_score is None:
+            completed_scores(list(enumerate(scores)))
         for (question_id, child_id, question, criteria), score in zip(jobs, scores, strict=True):
             probabilities, diagnostics = self._distribution(criteria, score)
             if child_id is None:

gemma_rlcd/json_backend.py

@@ -12,7 +12,7 @@ from .json_scoring import candidate_fields, compile_field
 class JSONMLXBackend(CachedMLXBackend):
     probability_source = "restricted_json_value_likelihoods"
 
-    def _sequence_scores(self, prefix_cache, prefix_tokens, fields):
+    def _sequence_scores(self, prefix_cache, prefix_tokens, fields, on_scores=None):
         """Teacher-force every complete candidate in bounded GPU batches.
 
         Score all tokens, including string terminators. Shared first tokens and
@@ -26,6 +26,7 @@ class JSONMLXBackend(CachedMLXBackend):
         ]
         values = {index: [None] * len(field.candidates) for index, field in fields}
         batches = []
+        output = {}
         for start in range(0, len(jobs), self.branch_batch_size):
             batch = jobs[start : start + self.branch_batch_size]
             suffixes = [prefix + candidate[:-1] for _, _, prefix, candidate in batch]
@@ -53,15 +54,20 @@ class JSONMLXBackend(CachedMLXBackend):
             for (field_index, choice, _, _), total in zip(batch, totals, strict=True):
                 values[field_index][choice] = float(total.item())
             batches.append(len(batch))
-        output = {}
-        for index, field in fields:
-            scores = tuple(values[index])
-            mass = min(1.0, sum(math.exp(value) for value in scores))
-            length = prefix_tokens + len(field.prefix) + max(map(len, field.candidates)) - 1
-            output[index] = TokenScores(scores, mass, length)
+            completed = []
+            for index, field in fields:
+                if index in output or any(value is None for value in values[index]):
+                    continue
+                scores = tuple(values[index])
+                mass = min(1.0, sum(math.exp(value) for value in scores))
+                length = prefix_tokens + len(field.prefix) + max(map(len, field.candidates)) - 1
+                output[index] = TokenScores(scores, mass, length)
+                completed.append((index, output[index]))
+            if on_scores is not None and completed:
+                on_scores(completed)
         return output, batches
 
-    def score_questions(self, state, questions):
+    def score_questions(self, state, questions, on_scores=None):
         started = time.perf_counter()
         prompt, inputs = prepare_generation(self, state, questions)
         fields = [
@@ -102,7 +108,15 @@ class JSONMLXBackend(CachedMLXBackend):
             simple = PreparedState(
                 inputs, [list(field.prefix) for _, field in single], prefix_tokens
             )
-            results = self.branches(simple, prefix_cache, requests)
+
+            def completed_batch(start, results):
+                on_scores(
+                    [(single[start + offset][0], score) for offset, score in enumerate(results)]
+                )
+
+            results = self.branches(
+                simple, prefix_cache, requests, on_batch=completed_batch if on_scores else None
+            )
             batches.extend(self.last_stats["branch_batch_sizes"])
             for (index, _), result in zip(single, results, strict=True):
                 scores[index] = result
@@ -114,7 +128,7 @@ class JSONMLXBackend(CachedMLXBackend):
         candidate_batches = []
         if multiple:
             results, candidate_batches = self._sequence_scores(
-                prefix_cache, prefix_tokens, multiple
+                prefix_cache, prefix_tokens, multiple, on_scores=on_scores
             )
             for index, result in results.items():
                 scores[index] = result

gemma_rlcd/static/demo-utils.js

@@ -0,0 +1,55 @@
+"use strict";
+
+const VisualDemo = {
+  questions(config, count) {
+    if (![32, 64, 128].includes(count)) throw new Error("Choose 32, 64, or 128 checks.");
+    return Object.fromEntries(config.groups.map((group) => [group.id, {
+      type: "independent",
+      instructions: "Which of these checks are visually established?",
+      criteria: Object.fromEntries(group.checks.slice(0, count / config.groups.length).map((check) => [check.id, check.description])),
+    }]));
+  },
+  partialBooleans(text) {
+    // Read only completed boolean literals in the expected two-level JSON shape.
+    // Partial strings, quoted booleans, and malformed suffixes are not answers.
+    text = text.replace(/^\s*```(?:json)?\s*\n/, "");
+    let index = 0;
+    const values = Object.create(null);
+    const skip = () => { while (/\s/.test(text[index] || "x")) index++; };
+    const take = (char) => { skip(); if (text[index] !== char) return false; index++; return true; };
+    const string = () => {
+      skip();
+      if (text[index] !== '"') return null;
+      const start = index++;
+      while (index < text.length) {
+        if (text[index] === "\\") { index += 2; continue; }
+        if (text[index++] === '"') {
+          try { return JSON.parse(text.slice(start, index)); } catch { return null; }
+        }
+      }
+      return null;
+    };
+    if (!take("{")) return values;
+    while (index < text.length) {
+      const group = string();
+      if (group === null || !take(":") || !take("{")) break;
+      while (index < text.length) {
+        const key = string();
+        if (key === null || !take(":")) return values;
+        skip();
+        const match = /^(true|false)(?=\s*[,}])/.exec(text.slice(index));
+        if (!match) return values;
+        values[`${group}.${key}`] = match[1] === "true";
+        index += match[1].length;
+        skip();
+        if (take("}")) break;
+        if (!take(",")) return values;
+      }
+      skip();
+      if (take("}")) return values;
+      if (!take(",")) return values;
+    }
+    return values;
+  },
+};
+if (typeof module !== "undefined") module.exports = VisualDemo;

gemma_rlcd/static/demo.css

@@ -0,0 +1 @@
+:root{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",sans-serif;color:#1d2924;background:#f6f7f4;--green:#23674e;--muted:#69766d;--line:#dfe5dc}*{box-sizing:border-box}body{margin:0;font-size:14px;line-height:1.5}header{display:flex;align-items:center;justify-content:space-between;gap:20px;padding:20px 36px;border-bottom:1px solid var(--line);background:#fcfdfb}.brand{font-weight:650;font-size:17px;color:inherit;text-decoration:none}nav{display:flex;gap:24px;align-items:center;font-size:12px}a{color:var(--green)}#model-status{color:var(--muted)}main{max-width:1560px;margin:auto;padding:35px 36px 70px}h1,h2,h3,p{margin:0}h1{font-size:36px;letter-spacing:-1.4px;font-weight:580;line-height:1.25;margin:8px 0}h1>span{color:var(--green)}h2{font-size:15px;font-weight:650}h3{font-size:14px;font-weight:620}.eyebrow{font-size:10px;font-weight:650;letter-spacing:1.7px;color:var(--muted)}.heading{display:flex;align-items:center;justify-content:space-between;gap:20px;margin-bottom:28px}.heading p{color:var(--muted);font-size:13px}.workspace{display:grid;grid-template-columns:minmax(280px,.75fr) minmax(0,1.6fr);gap:24px;align-items:start}.input-panel,.live-panel,.wall{border:1px solid var(--line);background:white;border-radius:10px;padding:22px}.section-title{display:flex;align-items:center;justify-content:space-between;gap:12px;margin-bottom:16px}.small{font-size:11px;color:var(--muted);line-height:1.65}.preview{height:260px;background:#eff2ed;border-radius:6px;overflow:hidden;display:grid;place-items:center;cursor:pointer}.preview img,.preview video{width:100%;height:100%;max-height:260px;object-fit:contain}.preview.dragging{outline:3px solid #7aab8f}.media-controls{display:flex;gap:12px;align-items:center;margin-top:12px}.file-button{font-size:12px;font-weight:550;color:var(--green);cursor:pointer;position:relative;flex-shrink:0}.file-button input{position:absolute;inset:0;opacity:0;width:100%;cursor:pointer}#file-name{font-size:10px;color:var(--muted);overflow:hidden;text-overflow:ellipsis;white-space:nowrap}#credit{margin-top:5px;min-height:18px}label:not(.file-button){display:block;font-size:11px;font-weight:550;margin:15px 0 6px}button,input,textarea,select{font:inherit;color:inherit}button,select{cursor:pointer}button{border:1px solid transparent;border-radius:6px;padding:10px 14px;font-size:12px;font-weight:550}button:disabled{opacity:.5;cursor:default}.primary{background:var(--green);color:white}.primary:hover:not(:disabled){background:#18513b}.secondary{background:white;border-color:var(--line)}.text-button{padding:2px;background:none;color:var(--green);font-size:11px}.input-panel select,.input-panel textarea{width:100%;border:1px solid var(--line);border-radius:6px;padding:10px;background:#fcfdfb;font-size:12px}.input-panel textarea{resize:vertical;line-height:1.5;margin-bottom:9px}.actions{display:flex;gap:10px;margin:18px 0 9px}.actions .primary{flex:1}.engines{display:grid;grid-template-columns:1fr 1fr;gap:24px}.engine{min-width:0}.engine-title{display:flex;align-items:center;justify-content:space-between;gap:8px}.engine-title>span{font-size:10px;color:var(--muted)}.parallel h3,.parallel .clock{color:var(--green)}.clock{display:block;font-size:50px;font-weight:450;letter-spacing:-2px;font-variant-numeric:tabular-nums;margin-top:8px}.clock>span{font-size:15px;letter-spacing:0;color:var(--muted);margin-left:7px}.progress{height:4px;background:#edf0e9;border-radius:3px;overflow:hidden;margin-top:12px}.progress i{display:block;height:100%;width:0;background:var(--green)}.normal .progress i{background:#4b5850}.engine-stats{display:flex;justify-content:space-between;gap:5px;color:var(--muted);font-size:10px;margin-top:7px}.engine>.small{margin-top:10px}.verdict{border-top:1px solid var(--line);border-bottom:1px solid var(--line);margin:22px 0;padding:15px 0;min-height:54px;font-size:13px;color:var(--green)}.verdict strong{font-size:22px;font-weight:600;margin-right:8px}.streams{display:grid;grid-template-columns:1fr 1fr;gap:20px;min-width:0}.streams>div{min-width:0}.stream-label{display:flex;justify-content:space-between;gap:10px;font-size:11px;color:var(--muted)}.live-dot{font-size:8px;letter-spacing:1px;color:var(--green)}pre{height:235px;margin:10px 0 0;background:#f6f8f3;border:1px solid #e9eee4;border-radius:6px;padding:12px;white-space:pre-wrap;overflow-wrap:anywhere;overflow:auto;font:11px/1.7 ui-monospace,SFMono-Regular,Menlo,monospace;color:#3e6550}.normal-stream{color:#46504a}.method-note{font-size:10px;color:var(--muted);line-height:1.8;margin-top:17px}.wall{margin-top:24px}.wall-heading{display:flex;justify-content:space-between;align-items:center;gap:20px;margin-bottom:20px}.wall-heading p{margin-top:5px}.filters{display:flex;align-items:center;gap:12px;flex-shrink:0}.filters select{font-size:11px;padding:8px;border:1px solid var(--line);border-radius:6px;background:white}.group{margin-top:19px}.group:first-child{margin-top:0}.group-title{font-size:11px;color:var(--muted);font-weight:550;margin-bottom:9px}.check-grid{display:grid;grid-template-columns:repeat(8,minmax(0,1fr));gap:7px}.check{border:1px solid #e3e8de;border-radius:5px;padding:8px 9px;min-width:0;min-height:59px;transition:background .2s,border-color .2s}.check-name{display:block;font-size:10px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;color:#53624f}.values{display:flex;gap:12px;justify-content:space-between;margin-top:6px;font:10px ui-monospace,monospace;color:#8a9585}.values b{font-weight:500}.check.detected{background:#f0f7ec;border-color:#c7dcc1}.check.different{background:#fff6e9;border-color:#e9c998}.values .yes{color:#23674e}.values .no{color:#727d70}.check.flash{animation:arrive .55s ease-out}.details{font-size:11px;color:var(--muted);margin-top:20px;max-width:1000px}.details p{margin-top:10px}.details summary{cursor:pointer}#error{margin-top:12px;padding:11px;border:1px solid #eccfc4;background:#fff6f0;color:#963e2e;font-size:12px;border-radius:6px}.sr-only{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0,0,0,0)}[hidden]{display:none!important}:focus-visible{outline:3px solid #75a58c;outline-offset:3px}@keyframes arrive{0%{background:#dceccd}100%{}}@media(prefers-reduced-motion:reduce){*{animation:none!important;transition:none!important}}@media(max-width:1200px){.check-grid{grid-template-columns:repeat(6,minmax(0,1fr))}.workspace{grid-template-columns:minmax(275px,.8fr) minmax(0,1.4fr)}.clock{font-size:43px}.engine-title{align-items:flex-start;flex-direction:column;gap:2px}}@media(max-width:850px){header{padding:17px 20px}main{padding:25px 20px 50px}.workspace{grid-template-columns:1fr}.preview{height:280px}.preview img,.preview video{max-height:280px}.input-panel{display:grid;grid-template-columns:1fr 1fr;column-gap:20px}.input-panel>*{grid-column:1/-1}.check-grid{grid-template-columns:repeat(4,minmax(0,1fr))}.engine-title{flex-direction:row}.wall-heading{align-items:flex-start;flex-direction:column}h1{font-size:32px}}@media(max-width:520px){header{align-items:flex-start}.brand{font-size:14px}nav{flex-direction:column;gap:3px;align-items:flex-end;font-size:10px}main{padding:22px 13px 40px}.heading{align-items:flex-start}.heading>button{padding:8px;font-size:10px;white-space:nowrap}h1{font-size:27px}.heading p{font-size:12px}.input-panel,.live-panel,.wall{padding:16px}.engines{gap:17px}.engine-title{align-items:flex-start;flex-direction:column}.clock{font-size:40px}.streams{gap:12px}pre{height:215px;font-size:10px;padding:9px}.check-grid{grid-template-columns:repeat(3,minmax(0,1fr))}.check{padding:7px}.values{gap:6px}.preview{height:230px}.preview img,.preview video{max-height:230px}.filters{flex-wrap:wrap}.wall-heading p{font-size:10px}}

gemma_rlcd/static/demo.html

@@ -0,0 +1,43 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>Live visual demo · Gemma E2B RLCD</title>
+  <link rel="stylesheet" href="/static/demo.css"><script src="/static/demo-utils.js" defer></script><script src="/static/demo.js" defer></script>
+</head>
+<body>
+  <header><a class="brand" href="/demo">Gemma E2B RLCD</a><nav><span id="model-status" role="status">Connecting…</span><a href="/">Open playground ↗</a></nav></header>
+  <main>
+    <div class="heading"><div><span class="eyebrow">LIVE MULTIMODAL COMPARISON</span><h1>One scene. <span id="headline-count">128</span> decisions.</h1><p>Both start together. Watch batched decisions race against normal Gemma’s streamed JSON.</p></div><button id="export" class="secondary" disabled>Export run ↓</button></div>
+    <div class="workspace">
+      <section class="input-panel" aria-labelledby="input-title">
+        <div class="section-title"><h2 id="input-title">The evidence</h2><button id="sample" class="text-button">Use sample photo</button></div>
+        <div id="dropzone" class="preview" tabindex="0" role="button" aria-label="Choose an image or video"><img id="image-preview" alt="Selected input"><video id="video-preview" controls playsinline hidden></video><div id="empty-preview" hidden>Drop an image or video</div></div>
+        <div class="media-controls"><label class="file-button">Choose image or video<input id="media-file" type="file" accept="image/png,image/jpeg,image/webp,image/bmp,video/*"></label><span id="file-name"></span></div>
+        <p id="credit" class="small"></p>
+        <label for="output-count">Number of visual checks</label><select id="output-count"><option value="32">32 checks · quick comparison</option><option value="64">64 checks · larger output</option><option value="128" selected>128 checks · full visual inventory</option></select>
+        <label for="instructions">Instructions</label><textarea id="instructions" rows="3" placeholder="Optional instructions for both models"></textarea>
+        <p class="small">One image or video. Silent clips up to 60 s; clips with audio up to 30 s. Sampled video frames and soundtrack go to both paths.</p>
+        <div class="actions"><button id="run" class="primary" disabled>Compare · stream answers</button><button id="stop" class="secondary" hidden>Stop</button></div>
+        <p id="run-note" class="small" role="status">The model loads once. Every comparison uses fresh input state.</p>
+        <div id="error" role="alert" hidden></div>
+      </section>
+      <section class="live-panel" aria-labelledby="live-title">
+        <div class="section-title"><h2 id="live-title">Live output</h2><span id="run-phase" class="small">Ready</span></div>
+        <div class="engines">
+          <article class="engine parallel"><div class="engine-title"><h3>Parallel scorer</h3><span id="parallel-state">Waiting</span></div><strong class="clock" id="parallel-clock">0.00<span>s</span></strong><div class="progress"><i id="parallel-progress"></i></div><div class="engine-stats"><span id="parallel-count">0 / 128 decisions</span><span>GPU batches</span></div><p id="parallel-first" class="small">First answer —</p></article>
+          <article class="engine normal"><div class="engine-title"><h3>Normal Gemma</h3><span id="normal-state">Waiting</span></div><strong class="clock" id="normal-clock">0.00<span>s</span></strong><div class="progress"><i id="normal-progress"></i></div><div class="engine-stats"><span id="normal-count">0 / 128 decisions</span><span id="token-count">0 tokens</span></div><p id="normal-first" class="small">First answer —</p></article>
+        </div>
+        <div id="verdict" class="verdict" aria-live="polite">Upload a scene or try the sample. Results are measured live.</div>
+        <div class="streams">
+          <div><div class="stream-label"><span>Completed decisions</span><span class="live-dot">LIVE</span></div><pre id="parallel-stream" aria-label="Parallel scorer output">Answers appear as soon as each batch completes.</pre></div>
+          <div><div class="stream-label"><span>Generated JSON</span><span class="live-dot">LIVE</span></div><pre id="normal-stream" aria-label="Normal Gemma generated JSON">Real token output will stream here.</pre></div>
+        </div>
+        <p class="method-note">Both paths start together on the same GPU, with independent input state and one shared clock. Same weights, media, questions, and compact answer contract. Timings include resource contention; model loading excluded.</p>
+      </section>
+    </div>
+    <section class="wall" aria-labelledby="wall-title"><div class="wall-heading"><div><h2 id="wall-title">Every decision, as it lands</h2><p class="small">A check is “yes” when visually established. P = parallel probability of yes · G = Gemma’s boolean. Streaming JSON is provisional until validated.</p></div><div class="filters"><label for="filter" class="sr-only">Filter decisions</label><select id="filter"><option value="all">All checks</option><option value="yes">Detected by either</option><option value="different">Different answers</option></select><span id="agreement" class="small"></span></div></div><div id="output-grid"></div><p id="no-matches" class="small" hidden>No completed checks match this filter.</p></section>
+    <details class="details"><summary>What is being measured?</summary><p>Both paths process the same complete image or sampled video, instructions, and label descriptions. The parallel scorer returns probabilities as field batches finish. Normal Gemma is asked to generate one compact JSON object with boolean decisions, without explanations or probability prose.</p><p>The timers include input preparation and inference, with shared upload decoding added equally. They exclude model loading, upload transfer, and allocator reset. This is one simultaneous run per path; GPU contention and first-use effects can affect timing. The result measures completion time while both are running, not isolated throughput. Matching answers measures agreement, not correctness. Invalid normal output is shown without a speedup claim.</p><p>Video processing targets one frame per second with a 32-frame cap. Long media plus 128 questions can exceed the 8,192-token input limit; reduce the number of checks or use a shorter clip. Media is never silently trimmed.</p></details>
+  </main>
+</body>
+</html>

gemma_rlcd/static/demo.js

@@ -0,0 +1,242 @@
+"use strict";
+const $ = (selector) => document.querySelector(selector);
+const escapeHTML = (value) => String(value).replace(/[&<>"']/g, (char) => ({"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"}[char]));
+let config, media, mediaURL, active = false, ready = false, controller, finalResult = null;
+let checks = [], rows = new Map(), completed = {parallel: new Map(), normal: new Map()};
+let clocks = {}, rawText = "", parallelLines = [], events = [], firstAnswer = {}, frame = null, sampleVersion = 0;
+
+function error(message) { $("#error").textContent = message; $("#error").hidden = !message; }
+function seconds(value) { return `${value.toFixed(2)}<span>s</span>`; }
+function count() { return Number($("#output-count").value); }
+function setMedia(file, credit = "") {
+  if (active) return;
+  if (file.size > 200 * 1024 * 1024) return error("The media file exceeds 200 MB.");
+  const extension = file.name.split(".").pop().toLowerCase();
+  const kind = file.type.startsWith("image/") || ["jpg","jpeg","png","webp","bmp"].includes(extension) ? "image" : file.type.startsWith("video/") || ["mp4","mov","webm","mkv","m4v"].includes(extension) ? "video" : null;
+  if (!kind) return error("Choose an image or video file.");
+  if (mediaURL) URL.revokeObjectURL(mediaURL);
+  media = {file, kind}; mediaURL = URL.createObjectURL(file);
+  $("#image-preview").hidden = kind !== "image";
+  $("#video-preview").hidden = kind !== "video";
+  $("#image-preview").removeAttribute("src");
+  $("#video-preview").removeAttribute("src");
+  $(`#${kind}-preview`).src = mediaURL;
+  $("#image-preview").alt = file.name;
+  $("#file-name").textContent = file.name;
+  $("#credit").innerHTML = credit;
+  reset(); error("");
+}
+async function sample() {
+  const version = ++sampleVersion;
+  $("#sample").disabled = true;
+  try {
+    const response = await fetch(config.sample.url);
+    if (!response.ok) throw new Error("Could not load the sample photo.");
+    const blob = await response.blob();
+    if (version !== sampleVersion || active) return;
+    setMedia(new File([blob], "times-square.jpg", {type:"image/jpeg"}), `<a href="${escapeHTML(config.sample.source)}" target="_blank" rel="noreferrer">${escapeHTML(config.sample.author)} · ${escapeHTML(config.sample.license)}</a>`);
+  } catch (failure) { error(failure.message); }
+  finally { $("#sample").disabled = active; }
+}
+function reset() {
+  finalResult = null; rawText = ""; parallelLines = []; events = []; firstAnswer = {}; clocks = {};
+  completed = {parallel: new Map(), normal: new Map()};
+  $("#headline-count").textContent = count();
+  $("#parallel-stream").textContent = "Answers appear as soon as each batch completes.";
+  $("#normal-stream").textContent = "Real token output will stream here.";
+  $("#token-count").textContent = "0 tokens";
+  $("#run-phase").textContent = "Ready";
+  $("#agreement").textContent = "";
+  $("#verdict").textContent = "Upload a scene or try the sample. Results are measured live.";
+  $("#export").disabled = true;
+  for (const method of ["parallel","normal"]) {
+    $(`#${method}-clock`).innerHTML = seconds(0);
+    $(`#${method}-state`).textContent = "Waiting";
+    $(`#${method}-first`).textContent = "First answer —";
+    $(`#${method}-progress`).style.width = "0%";
+    $(`#${method}-count`).textContent = `0 / ${count()} decisions`;
+  }
+  renderGrid(); syncButtons();
+}
+function renderGrid() {
+  checks = [];
+  $("#output-grid").innerHTML = config.groups.map((group) => {
+    const items = group.checks.slice(0, count() / config.groups.length);
+    return `<section class="group"><h3 class="group-title">${escapeHTML(group.name)} · ${items.length} checks</h3><div class="check-grid">${items.map((check) => {
+      const path = `${group.id}.${check.id}`; checks.push(path);
+      return `<div class="check" data-path="${escapeHTML(path)}" title="${escapeHTML(check.description)}"><span class="check-name">${escapeHTML(check.label)}</span><div class="values"><span>P <b data-method="parallel">—</b></span><span>G <b data-method="normal">—</b></span></div></div>`;
+    }).join("")}</div></section>`;
+  }).join("");
+  rows = new Map(Array.from(document.querySelectorAll(".check"), (row) => [row.dataset.path, row]));
+  filter();
+}
+function updateDecision(method, path, value, probability, elapsed) {
+  const row = rows.get(path);
+  if (!row || completed[method].has(path) && completed[method].get(path).value === value) return;
+  completed[method].set(path, {value, probability});
+  const cell = row.querySelector(`[data-method="${method}"]`);
+  cell.textContent = method === "parallel" ? `${Math.round(probability * 100)}%` : value ? "yes" : "no";
+  cell.className = value ? "yes" : "no";
+  row.classList.add("flash"); setTimeout(() => row.classList.remove("flash"), 600);
+  const parallel = completed.parallel.get(path), normal = completed.normal.get(path);
+  row.classList.toggle("detected", Boolean(parallel?.value || normal?.value));
+  row.classList.toggle("different", Boolean(parallel && normal && parallel.value !== normal.value));
+  if (firstAnswer[method] === undefined) {
+    firstAnswer[method] = elapsed;
+    $(`#${method}-first`).textContent = `First answer ${elapsed.toFixed(2)} s`;
+  }
+  $(`#${method}-count`).textContent = `${completed[method].size} / ${count()} decisions`;
+  $(`#${method}-progress`).style.width = `${100 * completed[method].size / count()}%`;
+  filter();
+}
+function filter() {
+  const mode = $("#filter").value;
+  let visible = 0;
+  for (const [path, row] of rows) {
+    const p = completed.parallel.get(path), n = completed.normal.get(path);
+    row.hidden = mode === "yes" ? !(p?.value || n?.value) : mode === "different" ? !(p && n && p.value !== n.value) : false;
+    if (!row.hidden) visible++;
+  }
+  for (const group of document.querySelectorAll(".group")) group.hidden = !Array.from(group.querySelectorAll(".check")).some((row) => !row.hidden);
+  $("#no-matches").hidden = visible > 0;
+}
+function tick() {
+  for (const [method, clock] of Object.entries(clocks)) {
+    if (clock.running) $(`#${method}-clock`).innerHTML = seconds((performance.now() - clock.start) / 1000);
+  }
+  if (active) frame = requestAnimationFrame(tick);
+}
+function handle(event) {
+  events.push(event.type === "complete" ? {type: "complete"} : event);
+  const method = event.method;
+  if (event.type === "accepted") { $("#run-phase").textContent = "Preparing media"; return; }
+  if (event.type === "error") throw new Error(event.error);
+  if (event.type === "race_start") {
+    const start = performance.now() - event.media_seconds * 1000;
+    for (const name of ["parallel","normal"]) {
+      clocks[name] = {running:true, start};
+      $(`#${name}-state`).textContent = "Running";
+    }
+    $("#run-phase").textContent = "Both running · live";
+    $("#verdict").textContent = "Both paths started together. Watch the answers arrive…";
+  } else if (event.type === "phase_start") {
+    if (!clocks[method]) clocks[method] = {running:true, start:performance.now() - event.media_seconds * 1000};
+    $(`#${method}-state`).textContent = "Running";
+  } else if (event.type === "answer") {
+    const path = event.path.join(".");
+    const probability = event.answer.probabilities.yes;
+    updateDecision("parallel",path,event.value,probability,event.seconds);
+    parallelLines.push(`${path}: ${event.value}  (${(probability*100).toFixed(1)}% yes)`);
+    $("#parallel-stream").textContent = parallelLines.join("\n");
+    $("#parallel-stream").scrollTop = $("#parallel-stream").scrollHeight;
+  } else if (event.type === "token") {
+    rawText += event.text;
+    $("#normal-stream").textContent = rawText;
+    $("#normal-stream").scrollTop = $("#normal-stream").scrollHeight;
+    $("#token-count").textContent = `${event.tokens} tokens`;
+    for (const [path,value] of Object.entries(VisualDemo.partialBooleans(rawText))) updateDecision("normal",path,value,null,event.seconds);
+  } else if (event.type === "phase_complete") {
+    clocks[method].running = false;
+    $(`#${method}-clock`).innerHTML = seconds(event.seconds);
+    $(`#${method}-state`).textContent = event.valid ? "Complete" : "Invalid output";
+    const other = method === "parallel" ? "normal" : "parallel";
+    if (clocks[other]?.running) {
+      const name = method === "parallel" ? "Parallel scorer" : "Normal Gemma";
+      const otherName = other === "parallel" ? "Parallel scorer" : "Normal Gemma";
+      $("#run-phase").textContent = `${otherName} still running`;
+      $("#verdict").textContent = `${name} ${event.valid ? "finished" : "returned invalid output"} in ${event.seconds.toFixed(2)} s. ${otherName} is still working…`;
+    }
+  } else if (event.type === "complete") {
+    finalResult = event.result;
+    const comparison = finalResult.comparison;
+    let matched = 0;
+    if (comparison.normal.valid) {
+      for (const [group, values] of Object.entries(comparison.normal.answers)) {
+        for (const [key,value] of Object.entries(values)) {
+          const path = `${group}.${key}`;
+          updateDecision("normal",path,value,null,comparison.seconds.normal);
+          if (completed.parallel.get(path)?.value === value) matched++;
+        }
+      }
+      $("#agreement").textContent = `${matched} / ${count()} matched`;
+      const ratio = comparison.normal_over_parallel;
+      $("#verdict").innerHTML = `<strong>${ratio >= 1 ? ratio.toFixed(2) : (1 / ratio).toFixed(2)}× ${ratio >= 1 ? "faster" : "slower"}</strong> this run · ${matched} / ${count()} matching answers`;
+    } else {
+      $("#verdict").textContent = "Normal Gemma returned an invalid answer. No valid-response speedup is reported.";
+      error(comparison.normal.error);
+      $("#agreement").textContent = "Normal output invalid";
+    }
+    $("#run-phase").textContent = "Comparison complete";
+    $("#export").disabled = false;
+  }
+}
+function syncButtons() {
+  $("#run").disabled = !ready || active || !media;
+  $("#stop").hidden = !active;
+  for (const selector of ["#sample","#media-file","#output-count","#instructions"]) $(selector).disabled = active;
+  $("#run").textContent = active ? "Streaming…" : "Compare · stream answers";
+}
+async function run() {
+  if (active || !ready || !media) return;
+  reset(); error(""); active = true; controller = new AbortController(); syncButtons(); tick();
+  const spec = {text:"", instructions:$("#instructions").value, questions:VisualDemo.questions(config,count()), media:[{name:media.file.name,kind:media.kind}]};
+  const form = new FormData(); form.append("spec",JSON.stringify(spec)); form.append("media",media.file);
+  try {
+    const response = await fetch("/api/compare-stream",{method:"POST",body:form,signal:controller.signal});
+    if (!response.ok) { const data=await response.json(); throw new Error(data.error || "Comparison failed."); }
+    const reader=response.body.getReader(), decoder=new TextDecoder(); let pending="";
+    while (true) {
+      const {value,done}=await reader.read(); pending += decoder.decode(value,{stream:!done});
+      let end;
+      while ((end=pending.indexOf("\n"))>=0) { const line=pending.slice(0,end); pending=pending.slice(end+1); if(line.trim()) handle(JSON.parse(line)); }
+      if(done) break;
+    }
+    if(pending.trim()) handle(JSON.parse(pending));
+    if(!finalResult) throw new Error("The stream ended before the comparison completed.");
+    finalResult = {request:spec,response:finalResult,stream_events:events,first_answer_seconds:firstAnswer};
+    $("#run-note").textContent = "Complete. Export preserves the answers, events, and measured timings.";
+  } catch(failure) {
+    controller.abort();
+    const cancelled=failure.name==="AbortError";
+    if(!cancelled) error(failure.message);
+    $("#run-phase").textContent=cancelled ? "Stopped" : "Run failed";
+    $("#verdict").textContent=cancelled ? "Stopped. Partial results are shown; no complete-response comparison." : "The comparison did not complete.";
+    for(const [method,clock] of Object.entries(clocks)) if(clock.running) $(`#${method}-state`).textContent=cancelled ? "Stopped" : "Failed";
+  } finally {
+    active=false; cancelAnimationFrame(frame); for(const clock of Object.values(clocks)) clock.running=false;
+    syncButtons(); status();
+  }
+}
+async function status() {
+  try {
+    const response=await fetch("/api/status"), state=await response.json();
+    ready=state.ready && !state.busy;
+    $("#model-status").textContent=state.error ? "Model unavailable" : state.busy ? "Gemma · running" : state.ready ? "Gemma 4 E2B · ready" : "Loading model…";
+    if(state.error) error(state.error);
+  } catch { ready=false; $("#model-status").textContent="Server disconnected"; }
+  syncButtons();
+}
+$("#run").addEventListener("click",run);
+$("#stop").addEventListener("click",()=>controller?.abort());
+$("#sample").addEventListener("click",sample);
+$("#filter").addEventListener("change",filter);
+$("#output-count").addEventListener("change",reset);
+$("#instructions").addEventListener("input",()=>{ if(finalResult) $("#run-note").textContent="Instructions changed. Run again to update the results."; });
+$("#media-file").addEventListener("change",(event)=>{ sampleVersion++; if(event.target.files[0]) setMedia(event.target.files[0]); event.target.value=""; });
+$("#dropzone").addEventListener("click",(event)=>{ if(event.target.tagName!=="VIDEO" && !active) $("#media-file").click(); });
+$("#dropzone").addEventListener("keydown",(event)=>{ if(["Enter"," "].includes(event.key) && !active) {event.preventDefault(); $("#media-file").click();} });
+for(const name of ["dragover","dragenter"]) $("#dropzone").addEventListener(name,(event)=>{event.preventDefault(); if(!active) $("#dropzone").classList.add("dragging");});
+for(const name of ["dragleave","drop"]) $("#dropzone").addEventListener(name,(event)=>{event.preventDefault(); $("#dropzone").classList.remove("dragging");});
+$("#dropzone").addEventListener("drop",(event)=>{sampleVersion++; if(event.dataTransfer.files[0]) setMedia(event.dataTransfer.files[0]);});
+$("#export").addEventListener("click",()=>{
+  if(!finalResult) return;
+  const url=URL.createObjectURL(new Blob([JSON.stringify(finalResult,null,2)],{type:"application/json"}));
+  const link=document.createElement("a"); link.href=url; link.download="gemma-visual-comparison.json"; link.click(); setTimeout(()=>URL.revokeObjectURL(url),1000);
+});
+async function init() {
+  try {
+    const response=await fetch("/static/visual-demo.json"); if(!response.ok) throw new Error("Could not load the visual checks.");
+    config=await response.json(); $("#instructions").value=config.instructions; reset(); await sample(); await status(); setInterval(status,2000);
+  } catch(failure) { error(failure.message); }
+}
+init();

gemma_rlcd/static/index.html

@@ -12,7 +12,7 @@
 <body>
   <header class="topbar">
     <a class="brand" href="/" aria-label="Gemma E2B RLCD home"><span class="brand-mark" aria-hidden="true"><i></i><i></i><i></i></span>Gemma E2B RLCD<span class="local-tag">LOCAL</span></a>
-    <div class="model-status"><span id="status-dot" class="status-dot loading"></span><span id="model-status" role="status">Loading Gemma 4 E2B…</span></div>
+    <div class="model-status"><a href="/demo">Live visual demo ↗</a><span id="status-dot" class="status-dot loading"></span><span id="model-status" role="status">Loading Gemma 4 E2B…</span></div>
   </header>
   <main>
     <div class="page-heading">

gemma_rlcd/static/visual-demo.json

@@ -0,0 +1,677 @@
+{
+  "title": "Visual inventory",
+  "instructions": "Evaluate only visible evidence. For video, a check is true if visible in at least one sampled frame. A spoken mention or a printed picture of an object does not establish that the real object is present. If a check is not visually established, answer false.",
+  "groups": [
+    {
+      "id": "people",
+      "name": "People & activity",
+      "checks": [
+        {
+          "id": "person",
+          "label": "Person",
+          "description": "A person is visible"
+        },
+        {
+          "id": "crowd",
+          "label": "Crowd",
+          "description": "At least ten people are visible"
+        },
+        {
+          "id": "walking",
+          "label": "Walking",
+          "description": "A person is visibly walking"
+        },
+        {
+          "id": "sitting",
+          "label": "Sitting",
+          "description": "A person is sitting"
+        },
+        {
+          "id": "standing",
+          "label": "Standing",
+          "description": "A person is standing"
+        },
+        {
+          "id": "running",
+          "label": "Running",
+          "description": "A person is running"
+        },
+        {
+          "id": "cycling",
+          "label": "Cycling",
+          "description": "A person is riding a bicycle"
+        },
+        {
+          "id": "carrying_bag",
+          "label": "Carrying bag",
+          "description": "A person is carrying a bag"
+        },
+        {
+          "id": "backpack",
+          "label": "Backpack",
+          "description": "A person is wearing a backpack"
+        },
+        {
+          "id": "handbag",
+          "label": "Handbag",
+          "description": "A handbag is visible"
+        },
+        {
+          "id": "hat",
+          "label": "Hat",
+          "description": "A person is wearing a hat or cap"
+        },
+        {
+          "id": "sunglasses",
+          "label": "Sunglasses",
+          "description": "A person is wearing sunglasses"
+        },
+        {
+          "id": "umbrella",
+          "label": "Umbrella",
+          "description": "A person is holding an umbrella"
+        },
+        {
+          "id": "phone_in_hand",
+          "label": "Phone in hand",
+          "description": "A person is holding a phone"
+        },
+        {
+          "id": "using_camera",
+          "label": "Using camera",
+          "description": "A person is using a camera"
+        },
+        {
+          "id": "raised_hand",
+          "label": "Raised hand",
+          "description": "A person has a raised hand"
+        },
+        {
+          "id": "waving",
+          "label": "Waving",
+          "description": "A person is waving"
+        },
+        {
+          "id": "pointing",
+          "label": "Pointing",
+          "description": "A person is pointing"
+        },
+        {
+          "id": "eating",
+          "label": "Eating",
+          "description": "A person is eating"
+        },
+        {
+          "id": "drinking",
+          "label": "Drinking",
+          "description": "A person is drinking"
+        },
+        {
+          "id": "stroller",
+          "label": "Stroller",
+          "description": "A baby stroller is visible"
+        },
+        {
+          "id": "walking_dog",
+          "label": "Walking dog",
+          "description": "A person is walking a dog on a leash"
+        },
+        {
+          "id": "uniform",
+          "label": "Uniform",
+          "description": "A person is wearing a uniform"
+        },
+        {
+          "id": "helmet",
+          "label": "Helmet",
+          "description": "A person is wearing a helmet"
+        },
+        {
+          "id": "high_vis_vest",
+          "label": "High vis vest",
+          "description": "A high-visibility safety vest is visible"
+        },
+        {
+          "id": "face_mask",
+          "label": "Face mask",
+          "description": "A person is wearing a face mask"
+        },
+        {
+          "id": "red_clothing",
+          "label": "Red clothing",
+          "description": "Red clothing is visible"
+        },
+        {
+          "id": "blue_clothing",
+          "label": "Blue clothing",
+          "description": "Blue clothing is visible"
+        },
+        {
+          "id": "white_clothing",
+          "label": "White clothing",
+          "description": "White clothing is visible"
+        },
+        {
+          "id": "striped_clothing",
+          "label": "Striped clothing",
+          "description": "Striped clothing is visible"
+        },
+        {
+          "id": "group_interaction",
+          "label": "Group interaction",
+          "description": "Two people are visibly interacting"
+        },
+        {
+          "id": "person_lying_down",
+          "label": "Person lying down",
+          "description": "A person is lying down"
+        }
+      ]
+    },
+    {
+      "id": "objects",
+      "name": "Vehicles & objects",
+      "checks": [
+        {
+          "id": "car",
+          "label": "Car",
+          "description": "A car is visible"
+        },
+        {
+          "id": "bus",
+          "label": "Bus",
+          "description": "A bus is visible"
+        },
+        {
+          "id": "bicycle",
+          "label": "Bicycle",
+          "description": "A bicycle is visible"
+        },
+        {
+          "id": "motorcycle",
+          "label": "Motorcycle",
+          "description": "A motorcycle is visible"
+        },
+        {
+          "id": "truck",
+          "label": "Truck",
+          "description": "A truck is visible"
+        },
+        {
+          "id": "taxi",
+          "label": "Taxi",
+          "description": "A marked taxi is visible"
+        },
+        {
+          "id": "boat",
+          "label": "Boat",
+          "description": "A boat is visible"
+        },
+        {
+          "id": "train",
+          "label": "Train",
+          "description": "A train is visible"
+        },
+        {
+          "id": "traffic_light",
+          "label": "Traffic light",
+          "description": "A traffic light is visible"
+        },
+        {
+          "id": "street_sign",
+          "label": "Street sign",
+          "description": "A street sign is visible"
+        },
+        {
+          "id": "billboard",
+          "label": "Billboard",
+          "description": "A large advertising billboard is visible"
+        },
+        {
+          "id": "bench",
+          "label": "Bench",
+          "description": "A bench is visible"
+        },
+        {
+          "id": "chair",
+          "label": "Chair",
+          "description": "A chair is visible"
+        },
+        {
+          "id": "table",
+          "label": "Table",
+          "description": "A table is visible"
+        },
+        {
+          "id": "trash_bin",
+          "label": "Trash bin",
+          "description": "A trash bin is visible"
+        },
+        {
+          "id": "traffic_cone",
+          "label": "Traffic cone",
+          "description": "A traffic cone is visible"
+        },
+        {
+          "id": "bollard",
+          "label": "Bollard",
+          "description": "A bollard or short street barrier post is visible"
+        },
+        {
+          "id": "fence",
+          "label": "Fence",
+          "description": "A fence is visible"
+        },
+        {
+          "id": "streetlamp",
+          "label": "Streetlamp",
+          "description": "A streetlamp is visible"
+        },
+        {
+          "id": "shop_window",
+          "label": "Shop window",
+          "description": "A shop display window is visible"
+        },
+        {
+          "id": "door",
+          "label": "Door",
+          "description": "A door is visible"
+        },
+        {
+          "id": "stairs",
+          "label": "Stairs",
+          "description": "Stairs are visible"
+        },
+        {
+          "id": "ramp",
+          "label": "Ramp",
+          "description": "A ramp is visible"
+        },
+        {
+          "id": "clock",
+          "label": "Clock",
+          "description": "A clock face is visible"
+        },
+        {
+          "id": "flag",
+          "label": "Flag",
+          "description": "A flag is visible"
+        },
+        {
+          "id": "food_stall",
+          "label": "Food stall",
+          "description": "A food stall or food cart is visible"
+        },
+        {
+          "id": "bottle",
+          "label": "Bottle",
+          "description": "A bottle is visible"
+        },
+        {
+          "id": "cup",
+          "label": "Cup",
+          "description": "A drinking cup is visible"
+        },
+        {
+          "id": "suitcase",
+          "label": "Suitcase",
+          "description": "A suitcase is visible"
+        },
+        {
+          "id": "screen",
+          "label": "Screen",
+          "description": "An electronic display screen is visible"
+        },
+        {
+          "id": "fire_hydrant",
+          "label": "Fire hydrant",
+          "description": "A fire hydrant is visible"
+        },
+        {
+          "id": "scaffolding",
+          "label": "Scaffolding",
+          "description": "Construction scaffolding is visible"
+        }
+      ]
+    },
+    {
+      "id": "nature",
+      "name": "Animals & environment",
+      "checks": [
+        {
+          "id": "dog",
+          "label": "Dog",
+          "description": "A real dog is visible"
+        },
+        {
+          "id": "cat",
+          "label": "Cat",
+          "description": "A real cat is visible"
+        },
+        {
+          "id": "bird",
+          "label": "Bird",
+          "description": "A real bird is visible"
+        },
+        {
+          "id": "horse",
+          "label": "Horse",
+          "description": "A real horse is visible"
+        },
+        {
+          "id": "cow",
+          "label": "Cow",
+          "description": "A real cow is visible"
+        },
+        {
+          "id": "sheep",
+          "label": "Sheep",
+          "description": "A real sheep is visible"
+        },
+        {
+          "id": "goat",
+          "label": "Goat",
+          "description": "A real goat is visible"
+        },
+        {
+          "id": "skunk",
+          "label": "Skunk",
+          "description": "A real skunk is visible"
+        },
+        {
+          "id": "rabbit",
+          "label": "Rabbit",
+          "description": "A real rabbit is visible"
+        },
+        {
+          "id": "squirrel",
+          "label": "Squirrel",
+          "description": "A real squirrel is visible"
+        },
+        {
+          "id": "duck",
+          "label": "Duck",
+          "description": "A real duck is visible"
+        },
+        {
+          "id": "fish",
+          "label": "Fish",
+          "description": "A real fish is visible"
+        },
+        {
+          "id": "tree",
+          "label": "Tree",
+          "description": "A tree is visible"
+        },
+        {
+          "id": "grass",
+          "label": "Grass",
+          "description": "Grass is visible"
+        },
+        {
+          "id": "flowers",
+          "label": "Flowers",
+          "description": "Flowers are visible"
+        },
+        {
+          "id": "potted_plant",
+          "label": "Potted plant",
+          "description": "A potted plant is visible"
+        },
+        {
+          "id": "bush",
+          "label": "Bush",
+          "description": "A bush is visible"
+        },
+        {
+          "id": "mountain",
+          "label": "Mountain",
+          "description": "A mountain is visible"
+        },
+        {
+          "id": "water",
+          "label": "Water",
+          "description": "An exposed body of water is visible"
+        },
+        {
+          "id": "beach",
+          "label": "Beach",
+          "description": "A sandy beach is visible"
+        },
+        {
+          "id": "snow",
+          "label": "Snow",
+          "description": "Snow is visible"
+        },
+        {
+          "id": "rain",
+          "label": "Rain",
+          "description": "Falling rain is visible"
+        },
+        {
+          "id": "clouds",
+          "label": "Clouds",
+          "description": "Clouds are visible"
+        },
+        {
+          "id": "blue_sky",
+          "label": "Blue sky",
+          "description": "Blue sky is visible"
+        },
+        {
+          "id": "sun",
+          "label": "Sun",
+          "description": "The sun itself is visible"
+        },
+        {
+          "id": "moon",
+          "label": "Moon",
+          "description": "The moon itself is visible"
+        },
+        {
+          "id": "smoke",
+          "label": "Smoke",
+          "description": "Smoke is visible"
+        },
+        {
+          "id": "fire",
+          "label": "Fire",
+          "description": "Flames are visible"
+        },
+        {
+          "id": "rocks",
+          "label": "Rocks",
+          "description": "Natural rocks are visible"
+        },
+        {
+          "id": "fallen_leaves",
+          "label": "Fallen leaves",
+          "description": "Fallen leaves are visible on the ground"
+        },
+        {
+          "id": "puddle",
+          "label": "Puddle",
+          "description": "A puddle is visible"
+        },
+        {
+          "id": "animal_group",
+          "label": "Animal group",
+          "description": "Two or more real animals are visible"
+        }
+      ]
+    },
+    {
+      "id": "scene",
+      "name": "Scene & composition",
+      "checks": [
+        {
+          "id": "outdoors",
+          "label": "Outdoors",
+          "description": "The scene is outdoors"
+        },
+        {
+          "id": "indoors",
+          "label": "Indoors",
+          "description": "The scene is indoors"
+        },
+        {
+          "id": "street",
+          "label": "Street",
+          "description": "A street or road is visible"
+        },
+        {
+          "id": "sidewalk",
+          "label": "Sidewalk",
+          "description": "A sidewalk is visible"
+        },
+        {
+          "id": "crosswalk",
+          "label": "Crosswalk",
+          "description": "A marked pedestrian crossing is visible"
+        },
+        {
+          "id": "buildings",
+          "label": "Buildings",
+          "description": "Buildings are visible"
+        },
+        {
+          "id": "high_rise",
+          "label": "High rise",
+          "description": "A high-rise building is visible"
+        },
+        {
+          "id": "storefront",
+          "label": "Storefront",
+          "description": "A storefront is visible"
+        },
+        {
+          "id": "park",
+          "label": "Park",
+          "description": "The setting is visibly a park"
+        },
+        {
+          "id": "kitchen",
+          "label": "Kitchen",
+          "description": "The setting is visibly a kitchen"
+        },
+        {
+          "id": "office",
+          "label": "Office",
+          "description": "The setting is visibly an office"
+        },
+        {
+          "id": "living_room",
+          "label": "Living room",
+          "description": "The setting is visibly a living room"
+        },
+        {
+          "id": "daylight",
+          "label": "Daylight",
+          "description": "The scene is lit by daylight"
+        },
+        {
+          "id": "night",
+          "label": "Night",
+          "description": "The scene is visibly at night"
+        },
+        {
+          "id": "artificial_lighting",
+          "label": "Artificial lighting",
+          "description": "Artificial lights are visibly illuminating the scene"
+        },
+        {
+          "id": "shadows",
+          "label": "Shadows",
+          "description": "Distinct cast shadows are visible"
+        },
+        {
+          "id": "reflections",
+          "label": "Reflections",
+          "description": "Reflections are visible"
+        },
+        {
+          "id": "wet_ground",
+          "label": "Wet ground",
+          "description": "The ground appears wet"
+        },
+        {
+          "id": "visible_text",
+          "label": "Visible text",
+          "description": "Readable or recognizable text is visible"
+        },
+        {
+          "id": "advertising",
+          "label": "Advertising",
+          "description": "Advertising is visible"
+        },
+        {
+          "id": "road_markings",
+          "label": "Road markings",
+          "description": "Painted road markings are visible"
+        },
+        {
+          "id": "red_dominant_area",
+          "label": "Red dominant area",
+          "description": "A large red area is visible"
+        },
+        {
+          "id": "blue_dominant_area",
+          "label": "Blue dominant area",
+          "description": "A large blue area is visible"
+        },
+        {
+          "id": "green_dominant_area",
+          "label": "Green dominant area",
+          "description": "A large green area is visible"
+        },
+        {
+          "id": "yellow_dominant_area",
+          "label": "Yellow dominant area",
+          "description": "A large yellow area is visible"
+        },
+        {
+          "id": "closeup",
+          "label": "Closeup",
+          "description": "The framing is a close-up view"
+        },
+        {
+          "id": "wide_view",
+          "label": "Wide view",
+          "description": "The framing shows a wide scene"
+        },
+        {
+          "id": "blur",
+          "label": "Blur",
+          "description": "Substantial image blur is visible"
+        },
+        {
+          "id": "occlusion",
+          "label": "Occlusion",
+          "description": "A main subject is partly hidden by another object"
+        },
+        {
+          "id": "dense_scene",
+          "label": "Dense scene",
+          "description": "Many distinct objects fill the scene"
+        },
+        {
+          "id": "clear_foreground",
+          "label": "Clear foreground",
+          "description": "A clear foreground subject is visible"
+        },
+        {
+          "id": "distant_background",
+          "label": "Distant background",
+          "description": "A distant background is visible"
+        }
+      ]
+    }
+  ],
+  "sample": {
+    "url": "/static/sample-street.jpg",
+    "name": "Times Square",
+    "author": "ISO Legacy",
+    "source": "https://commons.wikimedia.org/wiki/File:Times_Square_(New_York_City).jpg",
+    "license": "CC0 1.0"
+  }
+}

gemma_rlcd/web.py

@@ -11,9 +11,11 @@ from concurrent.futures import ThreadPoolExecutor
 from contextlib import asynccontextmanager
 from pathlib import Path
 from tempfile import TemporaryDirectory
+from threading import Event
 
+from anyio import CancelScope
 from fastapi import FastAPI, Request
-from fastapi.responses import FileResponse, JSONResponse
+from fastapi.responses import FileResponse, JSONResponse, StreamingResponse
 from fastapi.staticfiles import StaticFiles
 from PIL import Image, ImageOps, UnidentifiedImageError
 from starlette.datastructures import UploadFile
@@ -104,8 +106,8 @@ def read_spec(encoded: str) -> tuple[dict, dict]:
     field_count = sum(
         len(q.criteria) if isinstance(q, Independent) else 1 for q in questions.values()
     )
-    if field_count > 64:
-        raise ValueError("At most 64 individual fields or independent labels can run together")
+    if field_count > 128:
+        raise ValueError("At most 128 individual fields or independent labels can run together")
     media = spec.get("media", [])
     if not isinstance(media, list) or len(media) > 10:
         raise ValueError("Attach at most 8 images, one audio clip, and one video")
@@ -121,6 +123,32 @@ def read_spec(encoded: str) -> tuple[dict, dict]:
     return spec, questions
 
 
+async def read_upload(request: Request, directory: str):
+    async with request.form(max_files=10, max_fields=1, max_part_size=1024 * 1024) as form:
+        if set(form) - {"spec", "media"} or not isinstance(form.get("spec"), str):
+            raise ValueError("Submit a JSON spec and optional media attachments")
+        spec, questions = read_spec(form["spec"])
+        files = form.getlist("media")
+        if len(files) != len(spec.get("media", [])) or not all(
+            isinstance(file, UploadFile) for file in files
+        ):
+            raise ValueError("Attachment files do not match the request")
+        paths, total = [], 0
+        for index, file in enumerate(files):
+            suffix = Path(file.filename or "upload").suffix.lower()
+            if len(suffix) > 10 or not suffix.replace(".", "").isalnum():
+                suffix = ".bin"
+            path = Path(directory) / f"attachment-{index}{suffix}"
+            with path.open("wb") as output:
+                while chunk := await file.read(1024 * 1024):
+                    total += len(chunk)
+                    if total > MAX_UPLOAD_BYTES:
+                        raise ValueError("Attachments exceed the 200 MB total upload limit")
+                    output.write(chunk)
+            paths.append(path)
+        return spec, questions, paths
+
+
 def inspect_media(path: Path) -> dict:
     try:
         process = subprocess.run(
@@ -240,6 +268,7 @@ class Runtime:
         self.pool = ThreadPoolExecutor(max_workers=1, thread_name_prefix="decision-model")
         self.lock = asyncio.Lock()
         self.backend = None
+        self.normal_backend = None
         self.error = None
         self.load_seconds = None
 
@@ -249,9 +278,13 @@ class Runtime:
             if self.factory is None:
                 from .json_backend import JSONMLXBackend
 
-                self.backend = JSONMLXBackend(self.model, branch_batch_size=8)
+                backend = JSONMLXBackend(self.model, branch_batch_size=8)
             else:
-                self.backend = self.factory()
+                backend = self.factory()
+            from .comparison import generation_backend
+
+            self.normal_backend = generation_backend(backend)
+            self.backend = backend
             self.load_seconds = time.perf_counter() - started
 
         try:
@@ -261,7 +294,7 @@ class Runtime:
             self.error = "The model could not load. Check the model path and server log."
 
     def evaluate(
-        self, spec: dict, questions: dict, paths: list[Path], comparison: bool = False
+        self, spec: dict, questions: dict, paths: list[Path], comparison: bool = False, emit=None
     ) -> dict:
         started = time.perf_counter()
         media, metadata = prepare_media(paths, spec.get("media", []))
@@ -271,7 +304,19 @@ class Runtime:
         if comparison:
             from .comparison import compare
 
-            result, details = compare(self.backend, state, questions, normalized - started)
+            result, details = (
+                compare(
+                    self.backend,
+                    state,
+                    questions,
+                    normalized - started,
+                    emit=emit,
+                    concurrent=True,
+                    normal_backend=self.normal_backend,
+                )
+                if emit
+                else compare(self.backend, state, questions, normalized - started)
+            )
         else:
             result = DecisionEngine(self.backend).system_one(state, questions)
         finished = time.perf_counter()
@@ -332,6 +377,90 @@ def create_app(model: str, work_dir: Path, backend_factory=None) -> FastAPI:
     async def index():
         return FileResponse(STATIC / "index.html")
 
+    @app.get("/demo")
+    async def demo():
+        return FileResponse(STATIC / "demo.html")
+
+    @app.post("/api/compare-stream")
+    async def stream(request: Request):
+        if runtime.backend is None or runtime.error:
+            return JSONResponse(
+                {"error": runtime.error or "The model is still loading."}, status_code=503
+            )
+        if runtime.lock.locked():
+            return JSONResponse(
+                {"error": "Another evaluation is running. Wait for it to finish."}, status_code=429
+            )
+
+        await runtime.lock.acquire()
+        try:
+            directory = TemporaryDirectory(prefix="stream-", dir=work_dir)
+        except BaseException:
+            runtime.lock.release()
+            raise
+        try:
+            spec, questions, paths = await read_upload(request, directory.name)
+        except BaseException as exc:
+            directory.cleanup()
+            runtime.lock.release()
+            if isinstance(exc, (ValueError, TypeError, KeyError)):
+                return JSONResponse({"error": str(exc)}, status_code=400)
+            raise
+
+        async def events():
+            loop = asyncio.get_running_loop()
+            queue = asyncio.Queue()
+            stopped = Event()
+
+            class StreamStopped(Exception):
+                pass
+
+            def emit(event):
+                if stopped.is_set():
+                    raise StreamStopped()
+                loop.call_soon_threadsafe(queue.put_nowait, event)
+
+            def evaluate():
+                try:
+                    result = runtime.evaluate(spec, questions, paths, True, emit)
+                    emit({"type": "complete", "result": result})
+                except StreamStopped:
+                    pass
+                except (ValueError, TypeError, KeyError) as exc:
+                    loop.call_soon_threadsafe(
+                        queue.put_nowait, {"type": "error", "error": str(exc)}
+                    )
+                except Exception:
+                    LOGGER.exception("Streaming evaluation failed")
+                    if not stopped.is_set():
+                        loop.call_soon_threadsafe(
+                            queue.put_nowait,
+                            {
+                                "type": "error",
+                                "error": "Evaluation failed. Check the media or reduce the input size. Details are in the server log.",
+                            },
+                        )
+
+            future = loop.run_in_executor(runtime.pool, evaluate)
+            future.add_done_callback(lambda _: queue.put_nowait(None))
+            try:
+                yield json.dumps({"type": "accepted"}) + "\n"
+                while (event := await queue.get()) is not None:
+                    yield json.dumps(event, allow_nan=False) + "\n"
+            finally:
+                stopped.set()
+                # Keep uploads and the GPU lock alive until the worker stops.
+                with CancelScope(shield=True):
+                    try:
+                        await asyncio.shield(future)
+                    finally:
+                        directory.cleanup()
+                        runtime.lock.release()
+
+        return StreamingResponse(
+            events(), media_type="application/x-ndjson", headers={"X-Accel-Buffering": "no"}
+        )
+
     @app.get("/api/status")
     async def status():
         return {
@@ -359,46 +488,21 @@ def create_app(model: str, work_dir: Path, backend_factory=None) -> FastAPI:
         async with runtime.lock:
             started = time.perf_counter()
             try:
-                async with request.form(
-                    max_files=10, max_fields=1, max_part_size=1024 * 1024
-                ) as form:
-                    if set(form) - {"spec", "media"} or not isinstance(form.get("spec"), str):
-                        raise ValueError("Submit a JSON spec and optional media attachments")
-                    spec, questions = read_spec(form["spec"])
-                    files = form.getlist("media")
-                    if len(files) != len(spec.get("media", [])) or not all(
-                        isinstance(file, UploadFile) for file in files
-                    ):
-                        raise ValueError("Attachment files do not match the request")
-                    with TemporaryDirectory(prefix="run-", dir=work_dir) as directory:
-                        paths, total = [], 0
-                        for index, file in enumerate(files):
-                            suffix = Path(file.filename or "upload").suffix.lower()
-                            if len(suffix) > 10 or not suffix.replace(".", "").isalnum():
-                                suffix = ".bin"
-                            path = Path(directory) / f"attachment-{index}{suffix}"
-                            with path.open("wb") as output:
-                                while chunk := await file.read(1024 * 1024):
-                                    total += len(chunk)
-                                    if total > MAX_UPLOAD_BYTES:
-                                        raise ValueError(
-                                            "Attachments exceed the 200 MB total upload limit"
-                                        )
-                                    output.write(chunk)
-                            paths.append(path)
-                        future = asyncio.get_running_loop().run_in_executor(
-                            runtime.pool,
-                            runtime.evaluate,
-                            spec,
-                            questions,
-                            paths,
-                            request.url.path == "/api/compare",
-                        )
-                        try:
-                            result = await asyncio.shield(future)
-                        except asyncio.CancelledError:
-                            await future
-                            raise
+                with TemporaryDirectory(prefix="run-", dir=work_dir) as directory:
+                    spec, questions, paths = await read_upload(request, directory)
+                    future = asyncio.get_running_loop().run_in_executor(
+                        runtime.pool,
+                        runtime.evaluate,
+                        spec,
+                        questions,
+                        paths,
+                        request.url.path == "/api/compare",
+                    )
+                    try:
+                        result = await asyncio.shield(future)
+                    except asyncio.CancelledError:
+                        await future
+                        raise
                 result["request_seconds"] = time.perf_counter() - started
                 return JSONResponse(result)
             except (ValueError, TypeError, KeyError) as exc:

tests/test_comparison.py

@@ -3,7 +3,7 @@ import json
 import pytest
 
 from gemma_rlcd.comparison import discrete_answers, generation_task, parse_generated
-from gemma_rlcd.core import Choice, Independent, Noul, Score
+from gemma_rlcd.core import Choice, Independent, Noul, Score, State
 
 
 def questions():
@@ -58,3 +58,117 @@ def test_agreement_uses_grade_mode_and_boolean_thresholds():
             "presence": {"type": "independent", "probabilities": {"car": 0.9, "person": 0.1}},
         }
     ) == {"grade": 2, "moving": True, "presence": {"car": True, "person": False}}
+
+
+def test_streaming_generation_uses_real_chunks_and_validates_complete_answer(monkeypatch):
+    import sys
+    from types import SimpleNamespace
+
+    from gemma_rlcd import comparison
+
+    seen = []
+    parts = ['{"visible":', "true", "}"]
+
+    def stream(*args, **kwargs):
+        for index, text in enumerate(parts):
+            assert len(seen) == index
+            yield SimpleNamespace(
+                text=text,
+                generation_tokens=index + 1,
+                prompt_tokens=50,
+                finish_reason="stop" if index == len(parts) - 1 else None,
+            )
+
+    monkeypatch.setitem(
+        sys.modules, "mlx_vlm", SimpleNamespace(generate=None, stream_generate=stream)
+    )
+    monkeypatch.setattr(comparison, "prepare_generation", lambda *args: ("prompt", {}))
+    backend = SimpleNamespace(
+        model=None,
+        processor=None,
+        tokenizer=SimpleNamespace(encode=lambda *args, **kwargs: [1]),
+        mx=SimpleNamespace(synchronize=lambda: None),
+    )
+    result = comparison.generate_answers(
+        backend,
+        State(text="test"),
+        {"visible": Noul("Visible?")},
+        on_token=lambda text, count: seen.append((text, count)),
+    )
+    assert seen == list(zip(parts, [1, 2, 3], strict=True))
+    assert result["valid"] and result["answers"] == {"visible": True}
+    assert result["raw_text"] == "".join(parts)
+
+
+def test_concurrent_comparison_streams_both_paths_before_either_finishes(monkeypatch):
+    from threading import Event
+    from types import SimpleNamespace
+
+    from gemma_rlcd import comparison
+    from gemma_rlcd.core import TokenScores
+
+    scored, generated = Event(), Event()
+    events = []
+
+    class Backend:
+        last_stats = {}
+        processor = SimpleNamespace(tokenizer=SimpleNamespace(mutable=[]))
+
+        def symbols(self, count):
+            return ("A", "B")
+
+        def score_questions(self, state, questions, on_scores):
+            assert generated.wait(2), "Generation never started alongside scoring"
+            result = TokenScores((5, 0), 1, 20)
+            on_scores([(0, result)])
+            scored.set()
+            return [result]
+
+    backend = Backend()
+
+    def generate(worker, state, questions, on_token):
+        assert worker.processor is not backend.processor
+        assert worker.processor.tokenizer is not backend.processor.tokenizer
+        on_token('{"visible":', 1)
+        generated.set()
+        assert scored.wait(2), "Scoring never completed while generation was active"
+        on_token("true}", 2)
+        return {"answers": {"visible": True}, "valid": True, "inference_seconds": 0}
+
+    monkeypatch.setattr(comparison, "generate_answers", generate)
+    _, result = comparison.compare(
+        backend,
+        State(text="scene"),
+        {"visible": Noul("Visible?")},
+        0,
+        emit=events.append,
+        concurrent=True,
+    )
+    assert events[0]["type"] == "race_start"
+    first_token = next(i for i, event in enumerate(events) if event["type"] == "token")
+    first_answer = next(i for i, event in enumerate(events) if event["type"] == "answer")
+    first_finish = next(i for i, event in enumerate(events) if event["type"] == "phase_complete")
+    assert first_token < first_answer < first_finish
+    assert result["agreement"] == {"visible": True}
+    assert result["methodology"]["execution"] == "concurrent_shared_gpu"
+
+
+@pytest.mark.parametrize("cancel_at", ["race_start", "phase_start"])
+def test_concurrent_comparison_can_stop_before_or_after_worker_launch(cancel_at):
+    from types import SimpleNamespace
+
+    from gemma_rlcd.comparison import compare
+
+    def emit(event):
+        if event["type"] == cancel_at:
+            raise RuntimeError("Client stopped")
+
+    with pytest.raises(RuntimeError, match="Client stopped"):
+        compare(
+            SimpleNamespace(),
+            State(text="scene"),
+            {"visible": Noul("Visible?")},
+            0,
+            emit=emit,
+            concurrent=True,
+        )

tests/test_decisions.py

@@ -178,3 +178,25 @@ def test_batch_result_count_is_checked():
 
     with pytest.raises(ValueError, match="wrong number of question results"):
         DecisionEngine(Broken([])).system_one(State(text="test"), {"test": Noul("True?")})
+
+
+def test_streamed_decisions_arrive_before_later_batches_and_match_final_answers():
+    seen = []
+
+    class Streaming(StubBackend):
+        def score_questions(self, state, questions, on_scores=None):
+            scores = [TokenScores((2.0, 0.0), 0.8, 50), TokenScores((0.0, 2.0), 0.8, 50)]
+            on_scores([(0, scores[0])])
+            assert len(seen) == 1
+            on_scores([(1, scores[1])])
+            return scores
+
+    result = DecisionEngine(Streaming([])).system_one(
+        State(text="evidence"),
+        {"visible": Independent("Which?", {"cat": "Cat", "dog": "Dog"})},
+        on_answer=lambda path, answer: seen.append((path, answer)),
+    )
+    assert [path for path, _ in seen] == [("visible", "cat"), ("visible", "dog")]
+    assert result["answers"]["visible"]["probabilities"] == {
+        path[1]: answer["probabilities"]["yes"] for path, answer in seen
+    }

tests/test_demo.cjs

@@ -0,0 +1,22 @@
+const assert = require('node:assert/strict');
+const {test} = require('node:test');
+const demo = require('../gemma_rlcd/static/demo-utils.js');
+const config = require('../gemma_rlcd/static/visual-demo.json');
+test('visual schemas contain distinct meaningful checks at each size', () => {
+  for (const size of [32,64,128]) {
+    const questions = demo.questions(config,size);
+    assert.equal(Object.values(questions).reduce((n,q) => n + Object.keys(q.criteria).length,0),size);
+    assert.equal(new Set(Object.values(questions).flatMap(q => Object.values(q.criteria))).size,size);
+  }
+  assert.throws(() => demo.questions(config,129));
+});
+test('partial JSON reveals only complete booleans with a delimiter', () => {
+  const input = '{"people":{"person":true,"walking":false},"objects":{"car":true}}';
+  assert.deepEqual({...demo.partialBooleans(input)}, {'people.person':true,'people.walking':false,'objects.car':true});
+  const prefix = '{"people":{"person":true';
+  assert.deepEqual({...demo.partialBooleans(prefix)}, {});
+  assert.deepEqual({...demo.partialBooleans(prefix + ',"walking":fa')}, {'people.person':true});
+  assert.deepEqual({...demo.partialBooleans('{"people":{"person":"true"}')}, {});
+  assert.deepEqual({...demo.partialBooleans('{"people":{"person":truefake,')}, {});
+  assert.deepEqual({...demo.partialBooleans('```json\n' + input + '\n```')}, {...demo.partialBooleans(input)});
+});

tests/test_json_backend.py

@@ -27,9 +27,11 @@ def test_complete_candidate_likelihood_uses_suffix_and_ignores_padding(batch_siz
         )
     )
     fields = [(0, FieldTokens((9,), ((1, 2), (1, 3), (4,))))]
-    results, batches = backend._sequence_scores([], 100, fields)
+    streamed = []
+    results, batches = backend._sequence_scores([], 100, fields, on_scores=streamed.append)
     likelihoods = [math.exp(value) for value in results[0].logits]
     assert likelihoods == pytest.approx([0.09, 0.81, 0.1], abs=1e-6)
     assert results[0].allowed_token_mass == pytest.approx(1, abs=1e-6)
     assert sum(batches) == 3
     assert max(batches) <= batch_size
+    assert streamed == [[(0, results[0])]]

tests/test_web.py

@@ -264,10 +264,10 @@ def test_independent_expansion_is_bounded():
         "labels": {
             "type": "independent",
             "instructions": "Check each",
-            "criteria": {str(i): "An option" for i in range(65)},
+            "criteria": {str(i): "An option" for i in range(129)},
         }
     }
-    with pytest.raises(ValueError, match="64 individual fields"):
+    with pytest.raises(ValueError, match="128 individual fields"):
         read_spec(json.dumps(spec))
 
 
@@ -442,3 +442,78 @@ def test_invalid_generated_answer_remains_visible_without_speedup_claim(playgrou
     assert data["comparison"]["agreement"]["animal"] is None
     assert data["comparison"]["normal"]["raw_text"] == "not json"
     assert data["answers"]["animal"]["choice"] == "cat"
+
+
+def test_visual_demo_has_128_distinct_checks_and_supports_each_size(playground):
+    client, backend, _ = playground
+    assert "One scene." in client.get("/demo").text
+    config = client.get("/static/visual-demo.json").json()
+    assert len(config["groups"]) == 4
+    for size in (32, 64, 128):
+        spec = {
+            "text": "scene",
+            "instructions": config["instructions"],
+            "questions": {
+                group["id"]: {
+                    "type": "independent",
+                    "instructions": "Which checks are visible?",
+                    "criteria": {
+                        check["id"]: check["description"] for check in group["checks"][: size // 4]
+                    },
+                }
+                for group in config["groups"]
+            },
+        }
+        response = client.post("/api/run", data={"spec": json.dumps(spec)})
+        assert response.status_code == 200, response.text
+        assert len(backend.calls[-1][1]) == size
+
+
+def test_streaming_comparison_orders_events_and_cleans_uploads(playground, monkeypatch):
+    from gemma_rlcd import comparison
+
+    client, _, directory = playground
+
+    def generate(backend, state, questions, on_token=None):
+        on_token('{"animal":', 1)
+        on_token('"cat"}', 2)
+        return {
+            "answers": {"animal": "cat"},
+            "raw_text": '{"animal":"cat"}',
+            "valid": True,
+            "error": None,
+            "inference_seconds": 1,
+            "output_tokens": 2,
+        }
+
+    monkeypatch.setattr(comparison, "generate_answers", generate)
+    response = client.post("/api/compare-stream", data={"spec": json.dumps(request_spec())})
+    assert response.status_code == 200
+    assert response.headers["content-type"].startswith("application/x-ndjson")
+    events = [json.loads(line) for line in response.text.splitlines()]
+    assert [event["type"] for event in events[:2]] == ["accepted", "race_start"]
+    assert events[-1]["type"] == "complete"
+    assert [event["type"] for event in events if event.get("method") == "parallel"] == [
+        "phase_start",
+        "answer",
+        "phase_complete",
+    ]
+    assert [event["type"] for event in events if event.get("method") == "normal"] == [
+        "phase_start",
+        "token",
+        "token",
+        "phase_complete",
+    ]
+    assert next(event for event in events if event["type"] == "answer")["value"] == "cat"
+    assert events[-1]["result"]["comparison"]["normal"]["valid"]
+    assert events[-1]["result"]["comparison"]["methodology"]["execution"] == "concurrent_shared_gpu"
+    assert not client.get("/api/status").json()["busy"]
+    assert list(directory.iterdir()) == []
+
+
+def test_stream_validation_failure_releases_gpu_lock(playground):
+    client, _, directory = playground
+    response = client.post("/api/compare-stream", data={"spec": "{}"})
+    assert response.status_code == 400
+    assert not client.get("/api/status").json()["busy"]
+    assert list(directory.iterdir()) == []