Prepare Space-ready demo foundation

Co-authored-by: Codex <codex@openai.com>

FIELD_NOTES.md

@@ -0,0 +1,43 @@
+# Field Notes
+
+These notes are the seed for the hackathon build report.
+
+## Submission Thesis
+
+Tiny Narrator is a small-model accessibility article reader. It is not a generic chatbot wrapped in a page. The app uses semantic article structure, a keyboard-first reader mode, and model-specific jobs so each small model has a clear reason to exist.
+
+## Bonus Targets
+
+| Target | Evidence we are building |
+| --- | --- |
+| Tiny Titan | Every planned model is at or below 4B parameters. |
+| Llama Champion | The reader-brain layer calls a GGUF model through a llama.cpp OpenAI-compatible endpoint. |
+| Off-Brand | The visible app is custom HTML, CSS, and JavaScript served by `gr.Server`. |
+| Field Notes | This file documents model choices, architecture, fallbacks, and accessibility behavior. |
+
+## Model Budget
+
+| Role | Model | Size | Why it belongs |
+| --- | --- | ---: | --- |
+| Reader brain | `nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF` | 3.97B | Local narration planning through llama.cpp. |
+| Vision | `openbmb/MiniCPM-V-2` | 3B | Describes generated article images and handles OCR-like image text. |
+| Speech | `hexgrad/Kokoro-82M` | 82M | Fast screen-reader voice with a tiny footprint. |
+| Image generation | `black-forest-labs/FLUX.2-klein-4B` | 4B | Generates the article illustrations while staying Tiny Titan-safe. |
+
+## Reader Mode Behavior
+
+The frontend creates a reading queue from semantic nodes: headings, paragraphs, quotes, figures, captions, and controls. It speaks one item at a time, keeps keyboard focus synchronized with the active node, and exposes the current narration through an `aria-live` region.
+
+Keyboard map:
+
+- `Space`: play or pause.
+- `N`: next item.
+- `P`: previous item.
+- `H`: next heading.
+- `I`: next image.
+- `R`: repeat current item.
+- `Esc`: stop audio.
+
+## Fallback Strategy
+
+Live accessibility demos need dependable behavior. If llama.cpp is not available, the app uses deterministic local narration prefixes. If Kokoro is not installed or cannot load a voice, the app returns a short silent WAV while keeping the transcript visible. If the VLM integration is unavailable, image ids map to cached alt text.

README.md

@@ -1,3 +1,15 @@
+---
+title: Tiny Narrator
+emoji: 🔊
+colorFrom: teal
+colorTo: yellow
+sdk: gradio
+sdk_version: 6.16.0
+app_file: app.py
+pinned: false
+license: apache-2.0
+---
+
 # Tiny Narrator
 
 Tiny Narrator is a Build Small Hackathon prototype: a custom Gradio Server article app that can switch into a guided screen-reader mode.
@@ -40,6 +52,23 @@ python app.py
 
 Open the local URL printed by Gradio. The custom frontend calls `/api/reader-brain`, `/api/describe-image`, `/api/speak`, and `/api/generate-image`.
 
+Useful environment variables:
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `LLAMA_CPP_BASE_URL` | `http://localhost:8080/v1` | OpenAI-compatible llama.cpp server URL |
+| `LLAMA_CPP_MODEL` | `narrator-brain` | Alias passed to llama.cpp |
+| `GRADIO_SERVER_NAME` | `0.0.0.0` | Bind address for local or Space runtime |
+| `GRADIO_SERVER_PORT` / `PORT` | `7860` | App port |
+
+## Verification
+
+```powershell
+python scripts/verify.py
+```
+
+The verifier checks syntax, static assets, deterministic fallback model paths, and generated speech file behavior.
+
 ## Screen Reader Mode
 
 The frontend builds a reading queue from semantic article nodes. When screen-reader mode is on:

app.py

@@ -23,6 +23,8 @@ OUTPUT_DIR.mkdir(exist_ok=True)
 
 LLAMA_CPP_BASE_URL = os.getenv("LLAMA_CPP_BASE_URL", "http://localhost:8080/v1")
 LLAMA_CPP_MODEL = os.getenv("LLAMA_CPP_MODEL", "narrator-brain")
+GRADIO_SERVER_NAME = os.getenv("GRADIO_SERVER_NAME", "0.0.0.0")
+GRADIO_SERVER_PORT = int(os.getenv("PORT", os.getenv("GRADIO_SERVER_PORT", "7860")))
 
 app = Server(title="Tiny Narrator")
 app.mount("/static", StaticFiles(directory=STATIC_DIR), name="static")
@@ -204,11 +206,29 @@ async def health() -> JSONResponse:
         {
             "ok": True,
             "app": "Tiny Narrator",
+            "frontend": "custom Gradio Server HTML/CSS/JS",
+            "llama_cpp_base_url": LLAMA_CPP_BASE_URL,
             "models": {
-                "reader_brain": "nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF via llama.cpp",
-                "vision": "openbmb/MiniCPM-V-2",
-                "speech": "hexgrad/Kokoro-82M",
-                "image_generation": "black-forest-labs/FLUX.2-klein-4B",
+                "reader_brain": {
+                    "id": "nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF",
+                    "params": "3.97B",
+                    "runtime": "llama.cpp",
+                },
+                "vision": {
+                    "id": "openbmb/MiniCPM-V-2",
+                    "params": "3B",
+                    "runtime": "Python integration planned",
+                },
+                "speech": {
+                    "id": "hexgrad/Kokoro-82M",
+                    "params": "82M",
+                    "runtime": "Python",
+                },
+                "image_generation": {
+                    "id": "black-forest-labs/FLUX.2-klein-4B",
+                    "params": "4B",
+                    "runtime": "Python integration planned",
+                },
             },
         }
     )
@@ -260,4 +280,4 @@ async def handle_exception(_: Request, exc: Exception) -> JSONResponse:
 
 
 if __name__ == "__main__":
-    app.launch()
+    app.launch(server_name=GRADIO_SERVER_NAME, server_port=GRADIO_SERVER_PORT)

scripts/verify.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import py_compile
+import sys
+import wave
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT))
+
+import app
+from fastapi.testclient import TestClient
+
+
+def assert_true(condition: bool, message: str) -> None:
+    if not condition:
+        raise AssertionError(message)
+
+
+def verify_static_assets() -> None:
+    required = [
+        ROOT / "static" / "index.html",
+        ROOT / "static" / "app.css",
+        ROOT / "static" / "app.js",
+        ROOT / "static" / "generated" / "desk-reader.svg",
+        ROOT / "static" / "generated" / "model-map.svg",
+        ROOT / "static" / "generated" / "field-notes.svg",
+    ]
+    for path in required:
+        assert_true(path.exists(), f"Missing required asset: {path}")
+
+
+def verify_core_fallbacks() -> None:
+    narration = app.reader_brain_core(
+        node_type="heading",
+        text="Why tiny models matter",
+        position="item 1 of 1",
+        mode="narrate",
+    )
+    assert_true(narration["ok"], "Reader-brain fallback did not return ok")
+    assert_true("Heading." in narration["narration"], "Reader-brain fallback lost heading prefix")
+
+    description = app.describe_image_core("model-map", caption=None, prompt=None)
+    assert_true(description["ok"], "Image description did not return ok")
+    assert_true("small AI models" in description["alt_text"], "Image description fallback changed unexpectedly")
+
+    speech = app.speak_core("Tiny Narrator verification.", voice="af_heart", speed=1.0)
+    assert_true(speech["ok"], "Speech path did not return ok")
+    audio_path = ROOT / speech["audio_url"].lstrip("/")
+    assert_true(audio_path.exists(), f"Speech output missing: {audio_path}")
+    with wave.open(str(audio_path), "rb") as wav:
+        assert_true(wav.getframerate() == 24000, "Speech output should be 24 kHz")
+        assert_true(wav.getnchannels() == 1, "Speech output should be mono")
+
+
+def verify_routes() -> None:
+    client = TestClient(app.app)
+
+    home = client.get("/")
+    assert_true(home.status_code == 200, "Home route should return 200")
+    assert_true("Tiny Narrator" in home.text, "Home route should include app title")
+    assert_true("readerToggle" in home.text, "Home route should include reader toggle")
+
+    health = client.get("/api/health")
+    assert_true(health.status_code == 200, "Health route should return 200")
+    payload = health.json()
+    assert_true(payload["ok"], "Health payload should be ok")
+    assert_true(
+        payload["models"]["reader_brain"]["runtime"] == "llama.cpp",
+        "Health route should document llama.cpp reader-brain runtime",
+    )
+
+
+def main() -> None:
+    py_compile.compile(str(ROOT / "app.py"), doraise=True)
+    verify_static_assets()
+    verify_core_fallbacks()
+    verify_routes()
+    print("Tiny Narrator verification passed.")
+
+
+if __name__ == "__main__":
+    main()

static/app.js

@@ -28,6 +28,7 @@ const nodes = [...document.querySelectorAll(".speakable")].map((element, index)
 let enabled = false;
 let currentIndex = -1;
 let playing = false;
+let requestSerial = 0;
 
 function setEnabled(nextValue) {
   enabled = nextValue;
@@ -80,39 +81,54 @@ async function postJson(url, payload) {
 
 async function narrate(index) {
   if (!enabled || !nodes[index]) return;
+  const serial = ++requestSerial;
   setActive(index);
   const node = nodes[index];
   runtimeStatus.textContent = "Thinking";
-
-  let sourceText = node.text;
-  if (node.type === "image") {
-    const description = await postJson("/api/describe-image", {
-      image_id: node.imageId,
-      caption: node.text,
+  controls.play.disabled = true;
+
+  try {
+    let sourceText = node.text;
+    if (node.type === "image") {
+      const description = await postJson("/api/describe-image", {
+        image_id: node.imageId,
+        caption: node.text,
+      });
+      sourceText = description.alt_text;
+    }
+
+    const result = await postJson("/api/reader-brain", {
+      node_type: node.type,
+      text: sourceText,
+      position: `item ${index + 1} of ${nodes.length}`,
+      mode: "narrate",
     });
-    sourceText = description.alt_text;
-  }
 
-  const result = await postJson("/api/reader-brain", {
-    node_type: node.type,
-    text: sourceText,
-    position: `item ${index + 1} of ${nodes.length}`,
-    mode: "narrate",
-  });
+    if (serial !== requestSerial) return;
 
-  runtimeStatus.textContent = result.runtime;
-  liveNarration.textContent = result.narration;
+    runtimeStatus.textContent = result.runtime;
+    liveNarration.textContent = result.narration;
 
-  const speech = await postJson("/api/speak", {
-    text: result.narration,
-    speed: Number(speedControl.value),
-  });
+    const speech = await postJson("/api/speak", {
+      text: result.narration,
+      speed: Number(speedControl.value),
+    });
 
-  if (speech.audio_url) {
-    audio.src = speech.audio_url;
-    await audio.play().catch(() => {});
-    playing = true;
-    controls.play.textContent = "Pause";
+    if (serial !== requestSerial) return;
+
+    if (speech.audio_url) {
+      audio.src = speech.audio_url;
+      await audio.play().catch(() => {
+        liveNarration.textContent = `${result.narration} Audio is ready. Press Play to hear it.`;
+      });
+      playing = !audio.paused;
+      controls.play.textContent = playing ? "Pause" : "Play";
+    }
+  } catch (error) {
+    runtimeStatus.textContent = "Error";
+    liveNarration.textContent = `Narration failed: ${error.message}`;
+  } finally {
+    controls.play.disabled = false;
   }
 }