Report runtime readiness in demo

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

FIELD_NOTES.md

@@ -54,3 +54,5 @@ Reader settings are manifest-backed: the app exposes known Kokoro voices and spe
 Every model-facing backend path reports `elapsed_ms`. The frontend surfaces the latest end-to-end reader latency and stores per-item timing in the transcript, giving the build report concrete evidence for the small-model responsiveness claim.
 
 The app exposes `/api/award-evidence` and renders that data in the session panel, so the live demo can point directly to the hackathon bonus targets it is designed to satisfy.
+
+`/api/runtime-status` keeps the demo honest: if llama.cpp or Kokoro is unavailable, the UI labels the fallback state instead of silently pretending that every model path is online.

README.md

@@ -95,3 +95,5 @@ The reader bar exposes Kokoro voice selection and speaking speed controls. Defau
 Reader-brain, image-description, speech, and image-generation responses include `elapsed_ms`. The session panel and transcript show recent latency so the Field Notes can discuss responsiveness with concrete numbers.
 
 The session panel also renders a manifest-backed demo checklist for Tiny Titan, Llama Champion, Off-Brand, and Field Notes evidence.
+
+`/api/runtime-status` performs a short readiness check for llama.cpp and local speech dependencies, then reports which fallback paths are ready for a live demo.

app.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import importlib.util
 import json
 import os
 import time
@@ -170,6 +171,64 @@ def _elapsed_ms(start: float) -> int:
     return round((time.perf_counter() - start) * 1000)
 
 
+def _runtime_status_core() -> dict[str, Any]:
+    start = time.perf_counter()
+    llama_start = time.perf_counter()
+    llama_status: dict[str, Any]
+    try:
+        request = urllib.request.Request(f"{LLAMA_CPP_BASE_URL}/models", method="GET")
+        with urllib.request.urlopen(request, timeout=1.5) as response:
+            payload = json.loads(response.read().decode("utf-8"))
+        model_ids = [item.get("id", "") for item in payload.get("data", []) if isinstance(item, dict)]
+        llama_status = {
+            "available": True,
+            "status": "online",
+            "base_url": LLAMA_CPP_BASE_URL,
+            "model": LLAMA_CPP_MODEL,
+            "models": model_ids,
+            "elapsed_ms": _elapsed_ms(llama_start),
+        }
+    except (OSError, urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
+        llama_status = {
+            "available": False,
+            "status": "fallback-ready",
+            "base_url": LLAMA_CPP_BASE_URL,
+            "model": LLAMA_CPP_MODEL,
+            "fallback": "rule-based local narration",
+            "warning": exc.__class__.__name__,
+            "elapsed_ms": _elapsed_ms(llama_start),
+        }
+
+    kokoro_available = importlib.util.find_spec("kokoro") is not None
+    soundfile_available = importlib.util.find_spec("soundfile") is not None
+
+    return {
+        "ok": True,
+        "reader_brain": llama_status,
+        "vision": {
+            "available": False,
+            "status": "fallback-ready",
+            "model": "OpenBMB MiniCPM-V-2",
+            "fallback": "cached deterministic alt text",
+        },
+        "speech": {
+            "available": kokoro_available and soundfile_available,
+            "status": "online" if kokoro_available and soundfile_available else "fallback-ready",
+            "model": "hexgrad/Kokoro-82M",
+            "kokoro_installed": kokoro_available,
+            "soundfile_installed": soundfile_available,
+            "fallback": "browser speech plus transcript",
+        },
+        "image_generation": {
+            "available": False,
+            "status": "placeholder-ready",
+            "model": "black-forest-labs/FLUX.2-klein-4B",
+            "fallback": "bundled generated article assets",
+        },
+        "elapsed_ms": _elapsed_ms(start),
+    }
+
+
 def _compact_text(text: str, limit: int = 220) -> str:
     normalized = " ".join(text.split())
     if len(normalized) <= limit:
@@ -381,6 +440,11 @@ async def award_evidence() -> JSONResponse:
     return _json({"ok": True, "items": AWARD_EVIDENCE})
 
 
+@app.get("/api/runtime-status")
+async def runtime_status() -> JSONResponse:
+    return _json(_runtime_status_core())
+
+
 @app.post("/api/reader-brain")
 async def reader_brain_endpoint(payload: ReaderBrainRequest) -> JSONResponse:
     return _json(reader_brain_core(payload.node_type, payload.text, payload.position, payload.mode))

scripts/verify.py

@@ -84,6 +84,7 @@ def verify_routes() -> None:
     assert_true("readerToggle" in home.text, "Home route should include reader toggle")
     assert_true("summaryButton" in home.text, "Home route should include summary control")
     assert_true("imageStatus" in home.text, "Home route should include image status")
+    assert_true("readinessStatus" in home.text, "Home route should include readiness status")
     assert_true("voiceStatus" in home.text, "Home route should include voice status")
     assert_true("latencyStatus" in home.text, "Home route should include latency status")
     assert_true("voiceControl" in home.text, "Home route should include voice control")
@@ -134,6 +135,17 @@ def verify_routes() -> None:
         "Award evidence route should cover the targeted bonuses",
     )
 
+    runtime = client.get("/api/runtime-status")
+    assert_true(runtime.status_code == 200, "Runtime status route should return 200")
+    runtime_payload = runtime.json()
+    assert_true(runtime_payload["ok"], "Runtime status payload should be ok")
+    assert_true("reader_brain" in runtime_payload, "Runtime status should include reader brain status")
+    assert_true("speech" in runtime_payload, "Runtime status should include speech status")
+    assert_true(
+        runtime_payload["reader_brain"]["status"] in {"online", "fallback-ready"},
+        "Reader brain status should be online or fallback-ready",
+    )
+
     image_descriptions = client.get("/api/image-descriptions")
     assert_true(image_descriptions.status_code == 200, "Image descriptions route should return 200")
     image_payload = image_descriptions.json()

static/app.js

@@ -4,6 +4,7 @@ const modeStatus = document.querySelector("#modeStatus");
 const currentStatus = document.querySelector("#currentStatus");
 const runtimeStatus = document.querySelector("#runtimeStatus");
 const modelStatus = document.querySelector("#modelStatus");
+const readinessStatus = document.querySelector("#readinessStatus");
 const imageStatus = document.querySelector("#imageStatus");
 const voiceStatus = document.querySelector("#voiceStatus");
 const latencyStatus = document.querySelector("#latencyStatus");
@@ -151,6 +152,19 @@ async function loadAwardEvidence() {
   }
 }
 
+async function loadRuntimeStatus() {
+  try {
+    const payload = await postJson("/api/runtime-status");
+    const brain = payload.reader_brain;
+    const speech = payload.speech;
+    const brainLabel = brain.available ? "llama.cpp online" : "llama.cpp fallback";
+    const speechLabel = speech.available ? "Kokoro online" : "voice fallback";
+    readinessStatus.textContent = `${brainLabel}, ${speechLabel}`;
+  } catch {
+    readinessStatus.textContent = "Fallback ready";
+  }
+}
+
 async function loadImageDescriptions() {
   imageStatus.textContent = "Describing";
   try {
@@ -432,6 +446,7 @@ controls.play.addEventListener("click", () => {
 
 loadManifest();
 loadAwardEvidence();
+loadRuntimeStatus();
 loadImageDescriptions();
 updateSpeedValue();
 

static/index.html

@@ -96,6 +96,10 @@
             <dt>Model Stack</dt>
             <dd id="modelStatus">Loading</dd>
           </div>
+          <div>
+            <dt>Readiness</dt>
+            <dd id="readinessStatus">Checking</dd>
+          </div>
           <div>
             <dt>Image Alt</dt>
             <dd id="imageStatus">Waiting</dd>