Expose image generation provenance

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

FIELD_NOTES.md

@@ -30,6 +30,8 @@ Runtime setup is also data-backed. `/api/runtime-setup` lists the app command, l
 
 The judge runbook lives at `/api/demo-script`. It keeps the live presentation repeatable by pairing visible actions with API checks for health, model budget, runtime setup, runtime status, image descriptions, reader narration, and speech.
 
+Image provenance lives in `/api/image-descriptions`. Each article illustration carries the planned FLUX.2 klein model id, prompt, seed, asset URL, and fallback status, and the session panel renders those receipts so the generated-image claim is inspectable.
+
 Accessibility evidence lives at `/api/accessibility-audit`. It records the reader-mode choices that matter most for this prototype: semantic reading order, keyboard navigation, reader cursor state, shortcut safety, live narration, image alt text, transcript review, user-controlled playback, and fallback resilience.
 
 ## Reader Mode Behavior
@@ -59,6 +61,8 @@ Live accessibility demos need dependable behavior. If llama.cpp is not available
 
 The app preloads image descriptions through `/api/image-descriptions`, caches them in the frontend, and writes the descriptions back into each image's `alt` attribute. That keeps the visible article, transcript, and spoken image narration aligned.
 
+The same payload carries image-generation receipts. In fallback mode, the app is explicit that bundled assets stand in for the FLUX.2 klein runtime instead of presenting static files as live model output.
+
 Kokoro is still the intended model-backed TTS path. For local resilience, the frontend can use the browser speech engine when Kokoro is unavailable, and the session panel labels that as a browser fallback instead of model audio.
 
 Generated speech outputs are capped by a small retention cleanup. That keeps repeated demo sessions from turning the Space output directory into hidden state.

README.md

@@ -79,6 +79,8 @@ The verifier checks syntax, static assets, Space metadata consistency, determini
 
 `/api/accessibility-audit` exposes structured evidence for semantic reading order, keyboard navigation, reader cursor state, shortcut safety, live narration, image alt text, transcript review, user-controlled playback, and fallback resilience.
 
+`/api/image-descriptions` includes image-generation provenance for every article illustration: the planned FLUX.2 klein model, prompt, seed, bundled asset URL, and fallback-ready status.
+
 ## Screen Reader Mode
 
 The frontend builds a reading queue from semantic article nodes. When screen-reader mode is on:
@@ -102,6 +104,8 @@ The session panel keeps a transcript of recent narration with copy and clear con
 
 Image descriptions are preloaded into a local cache and written into the page's real `img alt` attributes. When the planned MiniCPM-V runtime is unavailable, deterministic alt-text fallbacks keep the screen-reader path usable.
 
+The session panel also renders image receipts from `/api/image-descriptions`, so judges can inspect the prompt, seed, planned <=4B image model, and fallback status behind each bundled article illustration.
+
 Kokoro remains the planned tiny-model TTS path. During local demos, if the server-side Kokoro call falls back, the browser speech engine can read the same transcript so screen-reader mode still produces audible feedback.
 
 Generated speech files are pruned automatically so repeated demos do not grow the Space's `outputs` directory without bound.

SUBMISSION.md

@@ -42,12 +42,14 @@ The prototype is designed for a live hackathon demo: every model-facing path has
 - `/api/runtime-status`: online or fallback-ready status for model paths.
 - `/api/accessibility-audit`: semantic queue, keyboard navigation, reader cursor state, shortcut safety, live narration, alt text, transcript, user control, and fallback evidence.
 - `/api/demo-script`: repeatable judge runbook and API checks.
-- `/api/image-descriptions`: generated article image descriptions for reader mode.
+- `/api/image-descriptions`: generated article image descriptions plus prompt, seed, model, asset URL, and fallback status receipts.
 
 The POST checks in `/api/demo-script` include sample JSON bodies for `/api/reader-brain` and `/api/speak`.
 
 The accessibility audit also documents two reader-mode details that matter during judging: the active item is exposed as a reader cursor with focus, visible outline, stable id, and `aria-current`; global shortcuts ignore form controls so voice, speed, and auto-advance settings remain usable while reader mode is active.
 
+The image receipts keep the generated-asset claim inspectable: each article illustration names the planned `black-forest-labs/FLUX.2-klein-4B` path, prompt, seed, and bundled fallback asset.
+
 ## Reliability notes
 
 The demo remains navigable when local models are unavailable. The reader brain falls back to deterministic narration, image descriptions fall back to cached alt text, speech falls back to browser speech plus transcript, and generated images fall back to bundled article assets. Fallback states are labeled instead of hidden.

app.py

@@ -60,24 +60,36 @@ MODEL_MANIFEST: dict[str, dict[str, Any]] = {
     },
 }
 
-ARTICLE_IMAGES: list[dict[str, str]] = [
+ARTICLE_IMAGES: list[dict[str, Any]] = [
     {
         "id": "desk-reader",
         "asset_url": "/static/generated/desk-reader.svg",
         "caption": "The article view doubles as the demo surface, so every feature has a real reading task.",
         "prompt": "Accessibility article reader with highlighted paragraph and narration controls.",
+        "seed": 11,
+        "generation_model": "black-forest-labs/FLUX.2-klein-4B",
+        "generation_runtime": "bundled fallback asset",
+        "generation_status": "fallback-ready",
     },
     {
         "id": "model-map",
         "asset_url": "/static/generated/model-map.svg",
         "caption": "Each model stays at or below four billion parameters for Tiny Titan eligibility.",
         "prompt": "Diagram of four small AI models working together in an accessibility reader.",
+        "seed": 22,
+        "generation_model": "black-forest-labs/FLUX.2-klein-4B",
+        "generation_runtime": "bundled fallback asset",
+        "generation_status": "fallback-ready",
     },
     {
         "id": "field-notes",
         "asset_url": "/static/generated/field-notes.svg",
         "caption": "Field notes document the choices behind the screen-reader behavior.",
         "prompt": "Notebook page with model sizes, keyboard controls, and accessibility checks.",
+        "seed": 33,
+        "generation_model": "black-forest-labs/FLUX.2-klein-4B",
+        "generation_runtime": "bundled fallback asset",
+        "generation_status": "fallback-ready",
     },
 ]
 

scripts/verify.py

@@ -38,6 +38,7 @@ def verify_static_assets() -> None:
     assert_true('data-reader-type="image"' in index_html, "Article should mark image reader nodes")
     assert_true('aria-live="polite"' in index_html, "Article should expose an aria-live narration region")
     assert_true("transcriptLog" in index_html, "Article should expose a visible transcript log")
+    assert_true("imageReceiptList" in index_html, "Article should expose generated image receipts")
     assert_true("function haltPlayback" in app_js, "Reader controls should expose a shared playback halt helper")
     assert_true(
         "haltPlayback({ clearAutoAdvance: false });" in app_js,
@@ -59,6 +60,8 @@ def verify_static_assets() -> None:
     )
     for evidence in ["reader cursor", "shortcut safety", "aria-current"]:
         assert_true(evidence in submission, f"Submission packet should mention {evidence}")
+    for evidence in ["prompt", "seed", "FLUX.2-klein-4B", "fallback asset"]:
+        assert_true(evidence in submission, f"Submission packet should mention image receipt evidence: {evidence}")
 
 
 def front_matter_value(readme: str, key: str) -> str:
@@ -129,6 +132,14 @@ def verify_core_fallbacks() -> None:
     article_descriptions = app.describe_article_images_core()
     assert_true(article_descriptions["ok"], "Article image descriptions did not return ok")
     assert_true(len(article_descriptions["descriptions"]) == 3, "Article should expose three image descriptions")
+    assert_true(
+        all(item["generation_model"] == app.MODEL_MANIFEST["image_generation"]["id"] for item in article_descriptions["descriptions"]),
+        "Article image descriptions should include the planned image-generation model",
+    )
+    assert_true(
+        all(isinstance(item["seed"], int) for item in article_descriptions["descriptions"]),
+        "Article image descriptions should include generation seeds",
+    )
     assert_true(isinstance(article_descriptions["elapsed_ms"], int), "Article image descriptions should include elapsed_ms")
 
     speech = app.speak_core("Tiny Narrator verification.", voice="af_heart", speed=1.0)
@@ -187,6 +198,8 @@ def verify_routes() -> None:
     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")
+    assert_true("imageReceiptStatus" in home.text, "Home route should include image receipt status")
+    assert_true("imageReceiptList" in home.text, "Home route should include image receipt list")
 
     health = client.get("/api/health")
     assert_true(health.status_code == 200, "Health route should return 200")
@@ -357,6 +370,14 @@ def verify_routes() -> None:
         {item["id"] for item in image_payload["descriptions"]} == {"desk-reader", "model-map", "field-notes"},
         "Image route should describe all article images",
     )
+    assert_true(
+        all(item["generation_model"] == app.MODEL_MANIFEST["image_generation"]["id"] for item in image_payload["descriptions"]),
+        "Image route should expose image-generation provenance",
+    )
+    assert_true(
+        all(item["generation_status"] == "fallback-ready" for item in image_payload["descriptions"]),
+        "Image route should label bundled image fallback status",
+    )
 
 
 def main() -> None:

static/app.css

@@ -290,7 +290,8 @@ dd {
   margin-top: 22px;
 }
 
-.budget-header {
+.budget-header,
+.image-receipt-header {
   display: flex;
   align-items: center;
   justify-content: space-between;
@@ -307,7 +308,8 @@ dd {
 }
 
 .budget-header span,
-.runtime-header span {
+.runtime-header span,
+.image-receipt-header span {
   color: var(--accent-strong);
   font-size: 0.76rem;
   font-weight: 850;
@@ -386,8 +388,17 @@ dd {
   list-style: none;
 }
 
+.image-receipt-list {
+  display: grid;
+  gap: 8px;
+  margin: 12px 0 0;
+  padding: 0;
+  list-style: none;
+}
+
 .budget-list li,
-.runtime-list li {
+.runtime-list li,
+.image-receipt-list li {
   border: 1px solid var(--line);
   border-radius: 8px;
   padding: 10px 12px;
@@ -395,7 +406,8 @@ dd {
 }
 
 .budget-row,
-.runtime-row {
+.runtime-row,
+.image-receipt-row {
   display: flex;
   align-items: center;
   justify-content: space-between;
@@ -406,7 +418,8 @@ dd {
 }
 
 .budget-pill,
-.runtime-pill {
+.runtime-pill,
+.image-receipt-pill {
   border-radius: 999px;
   background: rgba(197, 69, 44, 0.12);
   color: var(--focus);
@@ -419,8 +432,14 @@ dd {
   color: var(--accent-strong);
 }
 
+.image-receipt-pill {
+  background: rgba(244, 211, 94, 0.22);
+  color: #6f4b00;
+}
+
 .budget-list p,
-.runtime-list p {
+.runtime-list p,
+.image-receipt-list p {
   margin: 6px 0 0;
   color: var(--muted);
   font-size: 0.78rem;

static/app.js

@@ -22,6 +22,8 @@ const budgetStatus = document.querySelector("#budgetStatus");
 const modelBudgetList = document.querySelector("#modelBudgetList");
 const runtimeSetupStatus = document.querySelector("#runtimeSetupStatus");
 const runtimeSetupList = document.querySelector("#runtimeSetupList");
+const imageReceiptStatus = document.querySelector("#imageReceiptStatus");
+const imageReceiptList = document.querySelector("#imageReceiptList");
 
 const controls = {
   prev: document.querySelector("#prevButton"),
@@ -318,8 +320,31 @@ async function loadImageDescriptions() {
       }
     }
     imageStatus.textContent = `${imageDescriptions.size} ready`;
+    imageReceiptStatus.textContent = `${payload.descriptions.length} receipts`;
+    imageReceiptList.innerHTML = payload.descriptions
+      .map((description) => `
+        <li>
+          <div class="image-receipt-row">
+            <span>${escapeHtml(description.id)}</span>
+            <span class="image-receipt-pill">${escapeHtml(description.generation_status)}</span>
+          </div>
+          <p>${escapeHtml(description.generation_model)} | seed ${escapeHtml(String(description.seed))}</p>
+          <p>${escapeHtml(description.prompt)}</p>
+        </li>
+      `)
+      .join("");
   } catch {
     imageStatus.textContent = "Fallback on demand";
+    imageReceiptStatus.textContent = "Unavailable";
+    imageReceiptList.innerHTML = `
+      <li>
+        <div class="image-receipt-row">
+          <span>Image receipts</span>
+          <span class="image-receipt-pill">offline</span>
+        </div>
+        <p>Generated image provenance is unavailable.</p>
+      </li>
+    `;
   }
 }
 

static/index.html

@@ -136,6 +136,11 @@
           <span id="runtimeSetupStatus">Loading</span>
         </div>
         <ul id="runtimeSetupList" class="runtime-list" aria-label="Model runtime setup plan"></ul>
+        <div class="image-receipt-header">
+          <h3>Image Receipts</h3>
+          <span id="imageReceiptStatus">Loading</span>
+        </div>
+        <ul id="imageReceiptList" class="image-receipt-list" aria-label="Generated image provenance"></ul>
       </aside>
     </main>