Expose runtime setup evidence

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

FIELD_NOTES.md

@@ -26,6 +26,8 @@ Tiny Narrator is a small-model accessibility article reader. It is not a generic
 
 The app exposes the same budget through `/api/model-budget`, including numeric `params_billion` values and a boolean `all_models_within_limit` check. The session panel renders that payload so the Tiny Titan claim is visible during the demo.
 
+Runtime setup is also data-backed. `/api/runtime-setup` lists the app command, llama.cpp launch command, model-specific runtime paths, environment values, and fallbacks. The session panel renders a compact version so the demo can distinguish real model wiring from deterministic safety nets.
+
 ## 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.

README.md

@@ -50,7 +50,7 @@ Start the app:
 python app.py
 ```
 
-Open the local URL printed by Gradio. The custom frontend calls `/api/reader-brain`, `/api/image-descriptions`, `/api/describe-image`, `/api/speak`, and `/api/generate-image`.
+Open the local URL printed by Gradio. The custom frontend calls `/api/reader-brain`, `/api/image-descriptions`, `/api/describe-image`, `/api/speak`, `/api/generate-image`, `/api/model-budget`, and `/api/runtime-setup`.
 
 Useful environment variables:
 
@@ -71,6 +71,8 @@ The verifier checks syntax, static assets, deterministic fallback model paths, a
 
 `/api/model-budget` exposes numeric parameter counts for every model role and reports whether the full stack stays within the 4B Tiny Titan limit.
 
+`/api/runtime-setup` exposes the commands, environment values, and fallback paths used for the model stack so the demo can be reproduced from the same data the UI displays.
+
 ## Screen Reader Mode
 
 The frontend builds a reading queue from semantic article nodes. When screen-reader mode is on:
@@ -102,4 +104,6 @@ Reader-brain, image-description, speech, and image-generation responses include
 
 The session panel also renders a manifest-backed demo checklist for Tiny Titan, Llama Champion, Off-Brand, and Field Notes evidence. A model-budget panel reads `/api/model-budget` so judges can see each role's parameter count in the live app.
 
+A runtime-plan panel reads `/api/runtime-setup` and summarizes each model path's runtime plus fallback, keeping the live demo honest about what is online and what is deterministic.
+
 `/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

@@ -146,6 +146,61 @@ def model_budget_core() -> dict[str, Any]:
     }
 
 
+def runtime_setup_core() -> dict[str, Any]:
+    return {
+        "ok": True,
+        "app": {
+            "runtime": "Gradio Server",
+            "command": "python app.py",
+            "env": {
+                "GRADIO_SERVER_NAME": GRADIO_SERVER_NAME,
+                "GRADIO_SERVER_PORT": str(GRADIO_SERVER_PORT),
+            },
+        },
+        "steps": [
+            {
+                "role": "reader_brain",
+                "label": "Reader brain",
+                "model": MODEL_MANIFEST["reader_brain"]["id"],
+                "runtime": "llama.cpp",
+                "command": (
+                    "llama-server -hf nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF:Q4_K_M "
+                    "--alias narrator-brain --port 8080 --host 0.0.0.0"
+                ),
+                "env": {"LLAMA_CPP_BASE_URL": LLAMA_CPP_BASE_URL, "LLAMA_CPP_MODEL": LLAMA_CPP_MODEL},
+                "fallback": "rule-based local narration",
+            },
+            {
+                "role": "speech",
+                "label": "Speech",
+                "model": MODEL_MANIFEST["speech"]["id"],
+                "runtime": "Python Kokoro",
+                "command": "python -m pip install kokoro soundfile",
+                "env": {},
+                "fallback": "browser speech plus visible transcript",
+            },
+            {
+                "role": "vision",
+                "label": "Image descriptions",
+                "model": MODEL_MANIFEST["vision"]["id"],
+                "runtime": "Python integration planned",
+                "command": "planned MiniCPM-V adapter",
+                "env": {},
+                "fallback": "cached deterministic alt text",
+            },
+            {
+                "role": "image_generation",
+                "label": "Article images",
+                "model": MODEL_MANIFEST["image_generation"]["id"],
+                "runtime": "Python integration planned",
+                "command": "planned FLUX.2 klein adapter",
+                "env": {},
+                "fallback": "bundled generated article assets",
+            },
+        ],
+    }
+
+
 ARTICLE_MANIFEST: dict[str, Any] = {
     "title": "A tiny model reader that turns articles into guided narration",
     "reader_controls": [
@@ -162,6 +217,7 @@ ARTICLE_MANIFEST: dict[str, Any] = {
     "images": ARTICLE_IMAGES,
     "models": MODEL_MANIFEST,
     "model_budget": model_budget_core(),
+    "runtime_setup": runtime_setup_core(),
     "reader_settings": READER_SETTINGS,
     "award_evidence": AWARD_EVIDENCE,
 }
@@ -477,6 +533,11 @@ async def model_budget() -> JSONResponse:
     return _json(model_budget_core())
 
 
+@app.get("/api/runtime-setup")
+async def runtime_setup() -> JSONResponse:
+    return _json(runtime_setup_core())
+
+
 @app.get("/api/runtime-status")
 async def runtime_status() -> JSONResponse:
     return _json(_runtime_status_core())
@@ -527,6 +588,11 @@ def model_budget_api() -> str:
     return json.dumps(model_budget_core())
 
 
+@app.api(name="runtime_setup")
+def runtime_setup_api() -> str:
+    return json.dumps(runtime_setup_core())
+
+
 @app.api(name="speak")
 def speak_api(text: str, voice: str = "af_heart", speed: float = 1.0) -> str:
     return json.dumps(speak_core(text, voice, speed))

scripts/verify.py

@@ -101,6 +101,8 @@ def verify_routes() -> None:
     assert_true("awardEvidenceList" in home.text, "Home route should include award evidence list")
     assert_true("budgetStatus" in home.text, "Home route should include model budget status")
     assert_true("modelBudgetList" in home.text, "Home route should include model budget list")
+    assert_true("runtimeSetupStatus" in home.text, "Home route should include runtime setup status")
+    assert_true("runtimeSetupList" in home.text, "Home route should include runtime setup list")
 
     health = client.get("/api/health")
     assert_true(health.status_code == 200, "Health route should return 200")
@@ -143,6 +145,10 @@ def verify_routes() -> None:
         manifest_payload["model_budget"]["all_models_within_limit"],
         "Manifest should prove every model is within the Tiny Titan limit",
     )
+    assert_true(
+        len(manifest_payload["runtime_setup"]["steps"]) == 4,
+        "Manifest should expose setup steps for each model role",
+    )
 
     awards = client.get("/api/award-evidence")
     assert_true(awards.status_code == 200, "Award evidence route should return 200")
@@ -164,6 +170,20 @@ def verify_routes() -> None:
         "Every model budget item should be at or below the limit",
     )
 
+    setup = client.get("/api/runtime-setup")
+    assert_true(setup.status_code == 200, "Runtime setup route should return 200")
+    setup_payload = setup.json()
+    assert_true(setup_payload["ok"], "Runtime setup payload should be ok")
+    assert_true(
+        {item["role"] for item in setup_payload["steps"]}
+        == {"reader_brain", "speech", "vision", "image_generation"},
+        "Runtime setup should cover every model path",
+    )
+    assert_true(
+        "llama-server" in setup_payload["steps"][0]["command"],
+        "Runtime setup should include the llama.cpp launch command",
+    )
+
     runtime = client.get("/api/runtime-status")
     assert_true(runtime.status_code == 200, "Runtime status route should return 200")
     runtime_payload = runtime.json()

static/app.css

@@ -298,7 +298,16 @@ dd {
   margin-top: 22px;
 }
 
-.budget-header span {
+.runtime-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  margin-top: 22px;
+}
+
+.budget-header span,
+.runtime-header span {
   color: var(--accent-strong);
   font-size: 0.76rem;
   font-weight: 850;
@@ -369,14 +378,24 @@ dd {
   list-style: none;
 }
 
-.budget-list li {
+.runtime-list {
+  display: grid;
+  gap: 8px;
+  margin: 12px 0 0;
+  padding: 0;
+  list-style: none;
+}
+
+.budget-list li,
+.runtime-list li {
   border: 1px solid var(--line);
   border-radius: 8px;
   padding: 10px 12px;
   background: var(--surface);
 }
 
-.budget-row {
+.budget-row,
+.runtime-row {
   display: flex;
   align-items: center;
   justify-content: space-between;
@@ -386,7 +405,8 @@ dd {
   text-transform: uppercase;
 }
 
-.budget-pill {
+.budget-pill,
+.runtime-pill {
   border-radius: 999px;
   background: rgba(197, 69, 44, 0.12);
   color: var(--focus);
@@ -394,7 +414,13 @@ dd {
   font-size: 0.7rem;
 }
 
-.budget-list p {
+.runtime-pill {
+  background: rgba(31, 111, 104, 0.12);
+  color: var(--accent-strong);
+}
+
+.budget-list p,
+.runtime-list p {
   margin: 6px 0 0;
   color: var(--muted);
   font-size: 0.78rem;

static/app.js

@@ -20,6 +20,8 @@ const clearTranscriptButton = document.querySelector("#clearTranscriptButton");
 const awardEvidenceList = document.querySelector("#awardEvidenceList");
 const budgetStatus = document.querySelector("#budgetStatus");
 const modelBudgetList = document.querySelector("#modelBudgetList");
+const runtimeSetupStatus = document.querySelector("#runtimeSetupStatus");
+const runtimeSetupList = document.querySelector("#runtimeSetupList");
 
 const controls = {
   prev: document.querySelector("#prevButton"),
@@ -196,6 +198,35 @@ async function loadModelBudget() {
   }
 }
 
+async function loadRuntimeSetup() {
+  try {
+    const payload = await postJson("/api/runtime-setup");
+    runtimeSetupStatus.textContent = `${payload.steps.length} paths`;
+    runtimeSetupList.innerHTML = payload.steps
+      .map((step) => `
+        <li>
+          <div class="runtime-row">
+            <span>${escapeHtml(step.label)}</span>
+            <span class="runtime-pill">${escapeHtml(step.runtime)}</span>
+          </div>
+          <p>${escapeHtml(step.fallback)}</p>
+        </li>
+      `)
+      .join("");
+  } catch {
+    runtimeSetupStatus.textContent = "Unavailable";
+    runtimeSetupList.innerHTML = `
+      <li>
+        <div class="runtime-row">
+          <span>Runtime plan</span>
+          <span class="runtime-pill">offline</span>
+        </div>
+        <p>Setup evidence is unavailable.</p>
+      </li>
+    `;
+  }
+}
+
 async function loadRuntimeStatus() {
   try {
     const payload = await postJson("/api/runtime-status");
@@ -518,6 +549,7 @@ controls.play.addEventListener("click", () => {
 loadManifest();
 loadAwardEvidence();
 loadModelBudget();
+loadRuntimeSetup();
 loadRuntimeStatus();
 loadImageDescriptions();
 updateSpeedValue();

static/index.html

@@ -131,6 +131,11 @@
           <span id="budgetStatus">Checking</span>
         </div>
         <ul id="modelBudgetList" class="budget-list" aria-label="Tiny Titan model budget"></ul>
+        <div class="runtime-header">
+          <h3>Runtime Plan</h3>
+          <span id="runtimeSetupStatus">Loading</span>
+        </div>
+        <ul id="runtimeSetupList" class="runtime-list" aria-label="Model runtime setup plan"></ul>
       </aside>
     </main>