Expose Tiny Titan model budget

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

FIELD_NOTES.md

@@ -24,6 +24,8 @@ Tiny Narrator is a small-model accessibility article reader. It is not a generic
 | 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. |
 
+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.
+
 ## 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

@@ -69,6 +69,8 @@ python scripts/verify.py
 
 The verifier checks syntax, static assets, deterministic fallback model paths, and generated speech file behavior.
 
+`/api/model-budget` exposes numeric parameter counts for every model role and reports whether the full stack stays within the 4B Tiny Titan limit.
+
 ## Screen Reader Mode
 
 The frontend builds a reading queue from semantic article nodes. When screen-reader mode is on:
@@ -98,6 +100,6 @@ Navigation commands interrupt current speech before starting the next request, m
 
 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.
+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.
 
 `/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

@@ -27,29 +27,34 @@ 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")))
+TINY_TITAN_LIMIT_B = 4.0
 
-MODEL_MANIFEST: dict[str, dict[str, str]] = {
+MODEL_MANIFEST: dict[str, dict[str, Any]] = {
     "reader_brain": {
         "id": "nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF",
         "params": "3.97B",
+        "params_billion": 3.97,
         "runtime": "llama.cpp",
         "role": "Plans concise narration and reading-order phrasing.",
     },
     "vision": {
         "id": "openbmb/MiniCPM-V-2",
         "params": "3B",
+        "params_billion": 3.0,
         "runtime": "Python integration planned",
         "role": "Describes images and OCR-like visual details.",
     },
     "speech": {
         "id": "hexgrad/Kokoro-82M",
         "params": "82M",
+        "params_billion": 0.082,
         "runtime": "Python",
         "role": "Speaks the final narration.",
     },
     "image_generation": {
         "id": "black-forest-labs/FLUX.2-klein-4B",
         "params": "4B",
+        "params_billion": 4.0,
         "runtime": "Python integration planned",
         "role": "Creates article illustrations.",
     },
@@ -116,6 +121,31 @@ AWARD_EVIDENCE: list[dict[str, str]] = [
     },
 ]
 
+
+def model_budget_core() -> dict[str, Any]:
+    models = []
+    for role, model in MODEL_MANIFEST.items():
+        params_billion = float(model["params_billion"])
+        models.append(
+            {
+                "role": role,
+                "id": model["id"],
+                "runtime": model["runtime"],
+                "params": model["params"],
+                "params_billion": params_billion,
+                "limit_billion": TINY_TITAN_LIMIT_B,
+                "within_limit": params_billion <= TINY_TITAN_LIMIT_B,
+            }
+        )
+    return {
+        "ok": True,
+        "award": "Tiny Titan",
+        "limit_billion": TINY_TITAN_LIMIT_B,
+        "all_models_within_limit": all(model["within_limit"] for model in models),
+        "models": models,
+    }
+
+
 ARTICLE_MANIFEST: dict[str, Any] = {
     "title": "A tiny model reader that turns articles into guided narration",
     "reader_controls": [
@@ -131,6 +161,7 @@ ARTICLE_MANIFEST: dict[str, Any] = {
     "bonus_targets": ["Tiny Titan", "Llama Champion", "Off-Brand", "Field Notes"],
     "images": ARTICLE_IMAGES,
     "models": MODEL_MANIFEST,
+    "model_budget": model_budget_core(),
     "reader_settings": READER_SETTINGS,
     "award_evidence": AWARD_EVIDENCE,
 }
@@ -441,6 +472,11 @@ async def award_evidence() -> JSONResponse:
     return _json({"ok": True, "items": AWARD_EVIDENCE})
 
 
+@app.get("/api/model-budget")
+async def model_budget() -> JSONResponse:
+    return _json(model_budget_core())
+
+
 @app.get("/api/runtime-status")
 async def runtime_status() -> JSONResponse:
     return _json(_runtime_status_core())
@@ -486,6 +522,11 @@ def describe_article_images_api() -> str:
     return json.dumps(describe_article_images_core())
 
 
+@app.api(name="model_budget")
+def model_budget_api() -> str:
+    return json.dumps(model_budget_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

@@ -99,6 +99,8 @@ def verify_routes() -> None:
     assert_true("autoAdvanceControl" in home.text, "Home route should include auto-advance control")
     assert_true("transcriptLog" in home.text, "Home route should include transcript log")
     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")
 
     health = client.get("/api/health")
     assert_true(health.status_code == 200, "Health route should return 200")
@@ -137,6 +139,10 @@ def verify_routes() -> None:
         len(manifest_payload["award_evidence"]) == 4,
         "Manifest should expose four award evidence items",
     )
+    assert_true(
+        manifest_payload["model_budget"]["all_models_within_limit"],
+        "Manifest should prove every model is within the Tiny Titan limit",
+    )
 
     awards = client.get("/api/award-evidence")
     assert_true(awards.status_code == 200, "Award evidence route should return 200")
@@ -147,6 +153,17 @@ def verify_routes() -> None:
         "Award evidence route should cover the targeted bonuses",
     )
 
+    budget = client.get("/api/model-budget")
+    assert_true(budget.status_code == 200, "Model budget route should return 200")
+    budget_payload = budget.json()
+    assert_true(budget_payload["ok"], "Model budget payload should be ok")
+    assert_true(budget_payload["limit_billion"] == 4.0, "Tiny Titan limit should be 4B")
+    assert_true(budget_payload["all_models_within_limit"], "All models should stay within the Tiny Titan limit")
+    assert_true(
+        all(item["params_billion"] <= budget_payload["limit_billion"] for item in budget_payload["models"]),
+        "Every model budget item should be at or below the limit",
+    )
+
     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

@@ -290,6 +290,21 @@ dd {
   margin-top: 22px;
 }
 
+.budget-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 10px;
+  margin-top: 22px;
+}
+
+.budget-header span {
+  color: var(--accent-strong);
+  font-size: 0.76rem;
+  font-weight: 850;
+  text-transform: uppercase;
+}
+
 .history-header button {
   min-height: 34px;
   border-radius: 6px;
@@ -346,6 +361,46 @@ dd {
   background: var(--surface);
 }
 
+.budget-list {
+  display: grid;
+  gap: 8px;
+  margin: 12px 0 0;
+  padding: 0;
+  list-style: none;
+}
+
+.budget-list li {
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  padding: 10px 12px;
+  background: var(--surface);
+}
+
+.budget-row {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+  font-size: 0.82rem;
+  font-weight: 850;
+  text-transform: uppercase;
+}
+
+.budget-pill {
+  border-radius: 999px;
+  background: rgba(197, 69, 44, 0.12);
+  color: var(--focus);
+  padding: 2px 8px;
+  font-size: 0.7rem;
+}
+
+.budget-list p {
+  margin: 6px 0 0;
+  color: var(--muted);
+  font-size: 0.78rem;
+  overflow-wrap: anywhere;
+}
+
 .award-title {
   display: flex;
   align-items: center;

static/app.js

@@ -18,6 +18,8 @@ const transcriptLog = document.querySelector("#transcriptLog");
 const copyTranscriptButton = document.querySelector("#copyTranscriptButton");
 const clearTranscriptButton = document.querySelector("#clearTranscriptButton");
 const awardEvidenceList = document.querySelector("#awardEvidenceList");
+const budgetStatus = document.querySelector("#budgetStatus");
+const modelBudgetList = document.querySelector("#modelBudgetList");
 
 const controls = {
   prev: document.querySelector("#prevButton"),
@@ -156,6 +158,44 @@ async function loadAwardEvidence() {
   }
 }
 
+function roleLabel(role) {
+  return role
+    .split("_")
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+async function loadModelBudget() {
+  try {
+    const payload = await postJson("/api/model-budget");
+    budgetStatus.textContent = payload.all_models_within_limit
+      ? `All <= ${payload.limit_billion}B`
+      : "Review needed";
+    modelBudgetList.innerHTML = payload.models
+      .map((model) => `
+        <li>
+          <div class="budget-row">
+            <span>${escapeHtml(roleLabel(model.role))}</span>
+            <span class="budget-pill">${escapeHtml(model.params)}</span>
+          </div>
+          <p>${escapeHtml(model.id)}</p>
+        </li>
+      `)
+      .join("");
+  } catch {
+    budgetStatus.textContent = "Unavailable";
+    modelBudgetList.innerHTML = `
+      <li>
+        <div class="budget-row">
+          <span>Model budget</span>
+          <span class="budget-pill">offline</span>
+        </div>
+        <p>Tiny Titan evidence is unavailable.</p>
+      </li>
+    `;
+  }
+}
+
 async function loadRuntimeStatus() {
   try {
     const payload = await postJson("/api/runtime-status");
@@ -477,6 +517,7 @@ controls.play.addEventListener("click", () => {
 
 loadManifest();
 loadAwardEvidence();
+loadModelBudget();
 loadRuntimeStatus();
 loadImageDescriptions();
 updateSpeedValue();

static/index.html

@@ -126,6 +126,11 @@
           <h3>Demo Checklist</h3>
         </div>
         <ul id="awardEvidenceList" class="award-list" aria-label="Hackathon bonus evidence"></ul>
+        <div class="budget-header">
+          <h3>Model Budget</h3>
+          <span id="budgetStatus">Checking</span>
+        </div>
+        <ul id="modelBudgetList" class="budget-list" aria-label="Tiny Titan model budget"></ul>
       </aside>
     </main>