Add live image model integrations

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

.gitignore

@@ -11,3 +11,5 @@ outputs/*.log
 server.pid
 server.out.log
 server.err.log
+.*/skills/
+.*/commands/

FIELD_NOTES.md

@@ -20,9 +20,9 @@ Tiny Narrator is a small-model accessibility article reader. It is not a generic
 | 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. |
+| Vision | `openbmb/MiniCPM-V-4.6` | 1B | Describes generated article images and handles OCR-like image text through an OpenAI-compatible endpoint. |
 | 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. |
+| Image generation | `black-forest-labs/FLUX.2-klein-4B` | 4B | Generates the article illustrations through a Modal-hosted worker, with bundled SVG fallback. |
 
 The app exposes the same budget through `/api/model-budget`, including numeric `params_billion` values, per-model `within_limit` values, and a boolean `all_models_within_limit` check. The sidebar model stack renders each model id, runtime, parameter count, and Tiny Titan pass state so the claim is visible during the demo.
 
@@ -34,15 +34,15 @@ Submission readiness lives at `/api/submission-readiness`. It aggregates the dem
 
 The judge evidence bundle lives at `/api/evidence-bundle`. That endpoint returns the core receipts, including schema version, UTC generation time, `PUBLIC_BASE_URL`, runtime status, and readiness, as formatted JSON.
 
-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 so the generated-image claim is inspectable.
+Image provenance lives in `/api/image-descriptions`. Each article illustration carries the planned FLUX.2 klein generation model id, prompt, seed, asset URL, and fallback status. The same response also reports whether image descriptions came from MiniCPM-V-4.6 or cached fallback alt text.
 
-The Generate route uses `/api/generate-article` to turn a user's topic into a short semantic article. It uses the reader-brain model path for article text when llama.cpp is online, keeps a deterministic fallback draft for demos, and attaches thumbnail provenance from `black-forest-labs/FLUX.2-klein-4B`.
+The Generate route uses `/api/generate-article` to turn a user's topic into a short semantic article. It uses the reader-brain model path for article text when llama.cpp is online, keeps a deterministic fallback draft for demos, and attaches thumbnail provenance from `black-forest-labs/FLUX.2-klein-4B`. When `KLEIN_MODAL_ENDPOINT` is configured, the thumbnail uses live Modal Klein inference. Otherwise, bundled SVG assets are served with explicit fallback runtime metadata.
 
 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
 
-The frontend creates a reading queue from semantic nodes: headings, paragraphs, quotes, figures, captions, and controls. It renders that same queue in the session panel with click-to-read controls, speaks one item at a time, keeps keyboard focus synchronized with the active node, marks that node with `aria-current`, and exposes the current narration through an `aria-live` region.
+The frontend creates an internal 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, marks that node with `aria-current`, and exposes the current narration through an `aria-live` region.
 
 When screen reader mode turns on, the reader cursor starts at the focused article node or the most visible article node. That makes the feature feel connected to what the user is already reading instead of always jumping back to the top of the page.
 
@@ -65,7 +65,7 @@ Keyboard map:
 
 ## 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.
+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 MiniCPM-V-4.6 endpoint is unavailable, image ids map to cached alt text.
 
 The HTML starts with meaningful fallback `alt` text for each generated image. The app then 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 even if the model path is unavailable.
 
@@ -87,4 +87,22 @@ The app exposes `/api/award-evidence`, so the live demo can point directly to th
 
 The app also exposes `/api/submission-readiness`, so the Field Notes story has a single rollup of which submission claims are currently backed by app evidence.
 
-`/api/runtime-status` keeps the demo honest: if llama.cpp or Kokoro is unavailable, the API labels the fallback state instead of silently pretending that every model path is online.
+`/api/runtime-status` keeps the demo honest: if llama.cpp, MiniCPM-V-4.6, Kokoro, or Modal Klein is unavailable, the API labels the fallback state instead of silently pretending that every model path is online. The same endpoint reports whether the Modal Klein image worker is online or fallback-ready, so the demo can distinguish live Klein inference from bundled assets.
+
+## MiniCPM-V-4.6 Image Descriptions
+
+The image-description path uses `openbmb/MiniCPM-V-4.6` through an OpenAI-compatible `/v1/chat/completions` endpoint. Set `MINICPM_VISION_BASE_URL` and `MINICPM_VISION_API_KEY` to enable live alt-text generation. `MINICPM_VISION_MODEL` defaults to `openbmb/MiniCPM-V-4.6`, and `MINICPM_VISION_TIMEOUT_SECONDS` controls the request timeout.
+
+The app sends a multimodal chat message with an accessibility-focused prompt and an `image_url`. It asks for one or two concise screen-reader sentences, visible content, meaningful layout or text, and no implementation details.
+
+If the endpoint is missing, unreachable, or returns invalid content, `/api/describe-image` and `/api/image-descriptions` return deterministic cached alt text with fallback runtime metadata. API keys are never included in runtime setup, runtime status, or evidence bundle responses.
+
+## Modal Klein Image Generation
+
+The image generation path runs `black-forest-labs/FLUX.2-klein-4B` through a Modal worker (`modal_workers/klein_image.py`). The worker exposes `POST /generate` for inference and `GET /media/{filename}` for serving generated PNGs from a persistent Modal volume.
+
+Deploy the worker with `modal deploy modal_workers/klein_image.py`, then set `KLEIN_MODAL_ENDPOINT` to the deployed worker URL. The app's `generate_image_core()` calls the Modal endpoint when configured and falls back to bundled SVG assets on missing endpoint, network errors, timeouts, or invalid responses.
+
+`KLEIN_MODAL_TIMEOUT_SECONDS` defaults to 120 seconds, which accommodates warm inference but avoids blocking local demos indefinitely during cold starts.
+
+This design keeps verification stable without requiring Modal credentials or GPU access: the verifier checks fallback behavior, and live Modal deployment is a manual step documented in the README.

README.md

@@ -28,9 +28,9 @@ For the hackathon form, see [SUBMISSION.md](SUBMISSION.md).
 | Role | Model | Params | Runtime |
 | --- | ---: | ---: | --- |
 | Reader brain | `nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF` | 3.97B | `llama.cpp` |
-| Image understanding | `openbmb/MiniCPM-V-2` | 3B | Python integration planned |
+| Image understanding | `openbmb/MiniCPM-V-4.6` | 1B | OpenAI-compatible chat completions |
 | Text to speech | `hexgrad/Kokoro-82M` | 82M | Python |
-| Image generation | `black-forest-labs/FLUX.2-klein-4B` | 4B | Python integration planned |
+| Image generation | `black-forest-labs/FLUX.2-klein-4B` | 4B | Modal-hosted Klein |
 
 ## Run Locally
 
@@ -54,6 +54,24 @@ python app.py
 
 Open the local URL printed by Gradio. The Reader route calls `/api/reader-brain`, `/api/image-descriptions`, `/api/describe-image`, `/api/speak`, and `/api/model-budget`. The Generate route calls `/api/generate-article`, which drafts an article with the reader-brain model path and attaches a Klein thumbnail receipt.
 
+## Modal Klein Image Generation
+
+The image generation path uses a Modal-hosted `black-forest-labs/FLUX.2-klein-4B` worker. Deploy the worker:
+
+```powershell
+modal deploy modal_workers/klein_image.py
+```
+
+Set `KLEIN_MODAL_ENDPOINT` to the deployed worker URL. When configured, `/api/generate-image` and `/api/generate-article` call the live Modal endpoint for real Klein inference. When the endpoint is not set, unreachable, or returns invalid data, the app falls back to bundled SVG assets with explicit fallback metadata.
+
+`/api/runtime-status` reports whether the Modal Klein worker is online or fallback-ready. `/api/runtime-setup` includes the deploy command and required environment variables.
+
+## MiniCPM-V-4.6 Image Descriptions
+
+The image description path uses `openbmb/MiniCPM-V-4.6` through an OpenAI-compatible `/v1/chat/completions` endpoint. Provide `MINICPM_VISION_BASE_URL` and `MINICPM_VISION_API_KEY` to enable live screen-reader alt text for article images.
+
+When the endpoint is not configured, unreachable, or returns invalid content, `/api/describe-image` and `/api/image-descriptions` fall back to deterministic cached alt text so reader mode remains usable.
+
 Useful environment variables:
 
 | Variable | Default | Purpose |
@@ -63,6 +81,12 @@ Useful environment variables:
 | `GRADIO_SERVER_NAME` | `0.0.0.0` | Bind address for local or Space runtime |
 | `GRADIO_SERVER_PORT` / `PORT` | `7860` | App port |
 | `PUBLIC_BASE_URL` | `http://localhost:7860` | Base URL used in generated judge API commands |
+| `KLEIN_MODAL_ENDPOINT` | *(empty)* | Base URL for the Modal Klein worker, without trailing slash. When set, `/api/generate-image` calls the live worker. |
+| `KLEIN_MODAL_TIMEOUT_SECONDS` | `120` | Request timeout for Modal Klein image generation. |
+| `MINICPM_VISION_BASE_URL` | *(empty)* | OpenAI-compatible MiniCPM-V-4.6 base URL; root or `/v1` both work. |
+| `MINICPM_VISION_API_KEY` | *(empty)* | Bearer token for the MiniCPM vision endpoint. |
+| `MINICPM_VISION_MODEL` | `openbmb/MiniCPM-V-4.6` | Model id sent to chat completions. |
+| `MINICPM_VISION_TIMEOUT_SECONDS` | `45` | Request timeout for image descriptions. |
 
 ## Verification
 
@@ -115,7 +139,7 @@ Reader buttons expose `aria-keyshortcuts`, and the Repeat and Stop shortcuts are
 
 The session panel keeps a transcript of recent narration with reader position, runtime, latency, copy, and clear controls, making the spoken path inspectable during demos and useful for the Field Notes write-up. Copy actions report when browser clipboard access is unavailable, so the visible transcript and commands remain inspectable.
 
-Images start with meaningful fallback `alt` text in the HTML. Image descriptions are then 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.
+Images start with meaningful fallback `alt` text in the HTML. Image descriptions are then preloaded into a local cache and written into the page's real `img alt` attributes. When the MiniCPM-V-4.6 endpoint is unavailable, deterministic alt-text fallbacks keep the screen-reader path usable.
 
 `/api/image-descriptions` exposes image receipts so judges can inspect the prompt, seed, planned <=4B image model, and fallback status behind each bundled article illustration without lengthening the reader sidebar.
 
@@ -143,4 +167,4 @@ The sidebar model stack reads `/api/model-budget` so judges can see each role's
 
 ## Generate Route
 
-The header exposes two routes: Reader and Generate. Generate lets a user enter a topic, calls `/api/generate-article`, and renders a short semantic article with a thumbnail receipt. The text path uses the configured llama.cpp reader-brain model when available and falls back to deterministic article structure. The thumbnail path uses the planned Klein image model metadata and bundled fallback assets until the full image adapter is online.
+The header exposes two routes: Reader and Generate. Generate lets a user enter a topic, calls `/api/generate-article`, and renders a short semantic article with a thumbnail receipt. The text path uses the configured llama.cpp reader-brain model when available and falls back to deterministic article structure. The thumbnail path calls the Modal Klein worker for live image generation when `KLEIN_MODAL_ENDPOINT` is configured, and falls back to bundled SVG assets with explicit runtime metadata when the worker is unavailable.

SUBMISSION.md

@@ -22,16 +22,16 @@ The prototype is designed for a live hackathon demo: every model-facing path has
 | Role | Model | Size | Runtime |
 | --- | --- | ---: | --- |
 | Reader brain | `nvidia/NVIDIA-Nemotron-3-Nano-4B-GGUF` | 3.97B | `llama.cpp` |
-| Image understanding | `openbmb/MiniCPM-V-2` | 3B | Python integration planned |
+| Image understanding | `openbmb/MiniCPM-V-4.6` | 1B | OpenAI-compatible chat completions |
 | Speech | `hexgrad/Kokoro-82M` | 82M | Python |
-| Image generation | `black-forest-labs/FLUX.2-klein-4B` | 4B | Python integration planned |
+| Image generation | `black-forest-labs/FLUX.2-klein-4B` | 4B | Modal-hosted Klein (bundled fallback when not configured) |
 
 ## Demo flow
 
 1. Open the article and show that the app is a custom article interface, not a stock chatbot page.
 2. Turn on screen-reader mode and press `Space` or `Next` to narrate the first semantic node.
 3. Use `Heading`, `Image`, and `Summary` to navigate by article meaning instead of by raw page order.
-4. Show the reader-first session panel: current item, live narration, reader queue, transcript, and latency.
+4. Show the reader-first session panel: current item, live narration, transcript, model stack, and latency.
 5. Point to the model stack panel for model id, runtime, parameter count, and Tiny Titan pass status.
 6. Open the Generate route, enter a topic, and show the generated article plus `black-forest-labs/FLUX.2-klein-4B` thumbnail receipt.
 7. Mention that `/api/demo-script` exposes the judge runbook and API evidence checks as structured data.
@@ -53,7 +53,9 @@ The checks in `/api/demo-script` include copyable curl and PowerShell-friendly `
 
 The accessibility audit also documents 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; reader controls expose `aria-keyshortcuts` plus visible Repeat and Stop commands.
 
-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.
+The image receipts distinguish live Modal Klein inference from bundled fallback assets. When `KLEIN_MODAL_ENDPOINT` is configured and reachable, generated thumbnails use real `black-forest-labs/FLUX.2-klein-4B` inference through Modal. When the worker is unavailable, bundled SVG assets are used with explicit fallback runtime metadata.
+
+Image descriptions use `openbmb/MiniCPM-V-4.6` through an OpenAI-compatible `/v1/chat/completions` endpoint when `MINICPM_VISION_BASE_URL` and `MINICPM_VISION_API_KEY` are configured. Without that endpoint, cached deterministic alt text keeps screen-reader mode stable.
 
 The submission-readiness panel and API give judges a compact checklist for the whole build, so the live demo can move from individual receipts to an overall readiness view.
 
@@ -61,4 +63,4 @@ The submission-readiness panel and API give judges a compact checklist for the w
 
 ## Reliability notes
 
-The demo remains navigable when local models are unavailable. The reader brain falls back to deterministic narration, generated images start with meaningful HTML alt text, 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.
+The demo remains navigable when local models are unavailable. The reader brain falls back to deterministic narration, generated images start with meaningful HTML alt text, image descriptions fall back to cached alt text, speech falls back to browser speech plus transcript, and image generation falls back to bundled article assets when the Modal Klein worker is not configured or unreachable. Fallback states are labeled instead of hidden.

app.py

@@ -24,11 +24,25 @@ STATIC_DIR = ROOT / "static"
 OUTPUT_DIR = ROOT / "outputs"
 OUTPUT_DIR.mkdir(exist_ok=True)
 
+
+def _int_env(name: str, default: int) -> int:
+    try:
+        return int(os.getenv(name, str(default)))
+    except (TypeError, ValueError):
+        return default
+
+
 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")))
 PUBLIC_BASE_URL = os.getenv("PUBLIC_BASE_URL", f"http://localhost:{GRADIO_SERVER_PORT}").rstrip("/")
+KLEIN_MODAL_ENDPOINT = os.getenv("KLEIN_MODAL_ENDPOINT", "").rstrip("/")
+KLEIN_MODAL_TIMEOUT_SECONDS = _int_env("KLEIN_MODAL_TIMEOUT_SECONDS", 120)
+MINICPM_VISION_BASE_URL = os.getenv("MINICPM_VISION_BASE_URL", "").rstrip("/")
+MINICPM_VISION_API_KEY = os.getenv("MINICPM_VISION_API_KEY", "")
+MINICPM_VISION_MODEL = os.getenv("MINICPM_VISION_MODEL", "openbmb/MiniCPM-V-4.6")
+MINICPM_VISION_TIMEOUT_SECONDS = _int_env("MINICPM_VISION_TIMEOUT_SECONDS", 45)
 TINY_TITAN_LIMIT_B = 4.0
 
 MODEL_MANIFEST: dict[str, dict[str, Any]] = {
@@ -40,10 +54,10 @@ MODEL_MANIFEST: dict[str, dict[str, Any]] = {
         "role": "Plans concise narration and reading-order phrasing.",
     },
     "vision": {
-        "id": "openbmb/MiniCPM-V-2",
-        "params": "3B",
-        "params_billion": 3.0,
-        "runtime": "Python integration planned",
+        "id": "openbmb/MiniCPM-V-4.6",
+        "params": "1B",
+        "params_billion": 1.0,
+        "runtime": "OpenAI-compatible chat completions",
         "role": "Describes images and OCR-like visual details.",
     },
     "speech": {
@@ -57,7 +71,7 @@ MODEL_MANIFEST: dict[str, dict[str, Any]] = {
         "id": "black-forest-labs/FLUX.2-klein-4B",
         "params": "4B",
         "params_billion": 4.0,
-        "runtime": "Python integration planned",
+        "runtime": "Modal-hosted Klein",
         "role": "Creates article illustrations.",
     },
 }
@@ -188,18 +202,26 @@ def runtime_setup_core() -> dict[str, Any]:
                 "role": "vision",
                 "label": "Image descriptions",
                 "model": MODEL_MANIFEST["vision"]["id"],
-                "runtime": "Python integration planned",
-                "command": "planned MiniCPM-V adapter",
-                "env": {},
+                "runtime": "OpenAI-compatible chat completions",
+                "command": "vllm serve openbmb/MiniCPM-V-4.6 --host 0.0.0.0 --port 8000",
+                "env": {
+                    "MINICPM_VISION_BASE_URL": MINICPM_VISION_BASE_URL or "(set to OpenAI-compatible base URL)",
+                    "MINICPM_VISION_API_KEY": "(configured)" if MINICPM_VISION_API_KEY else "(not set)",
+                    "MINICPM_VISION_MODEL": MINICPM_VISION_MODEL,
+                    "MINICPM_VISION_TIMEOUT_SECONDS": str(MINICPM_VISION_TIMEOUT_SECONDS),
+                },
                 "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": {},
+                "runtime": "Modal-hosted Klein",
+                "command": "modal deploy modal_workers/klein_image.py",
+                "env": {
+                    "KLEIN_MODAL_ENDPOINT": KLEIN_MODAL_ENDPOINT or "(set to Modal worker URL)",
+                    "KLEIN_MODAL_TIMEOUT_SECONDS": str(KLEIN_MODAL_TIMEOUT_SECONDS),
+                },
                 "fallback": "bundled generated article assets",
             },
         ],
@@ -229,7 +251,7 @@ def demo_script_core() -> dict[str, Any]:
         {"method": "GET", "path": "/api/runtime-setup", "expect": "llama.cpp, Kokoro, vision, and image paths"},
         {"method": "GET", "path": "/api/runtime-status", "expect": "online or fallback-ready runtime labels"},
         {"method": "GET", "path": "/api/accessibility-audit", "expect": "all reader-mode checks pass"},
-        {"method": "GET", "path": "/api/image-descriptions", "expect": "three article image descriptions"},
+        {"method": "GET", "path": "/api/image-descriptions", "expect": "two article image descriptions with MiniCPM-V-4.6 or fallback alt text"},
         {"method": "GET", "path": "/api/submission-readiness", "expect": "all submission readiness checks pass"},
         {
             "method": "POST",
@@ -528,6 +550,7 @@ class ImageDescriptionRequest(BaseModel):
     image_id: str
     caption: str | None = None
     prompt: str | None = None
+    image_url: str | None = None
 
 
 class SpeechRequest(BaseModel):
@@ -553,6 +576,15 @@ def _elapsed_ms(start: float) -> int:
     return round((time.perf_counter() - start) * 1000)
 
 
+def _validate_modal_klein_health(payload: dict[str, Any]) -> None:
+    if payload.get("ok") is not True:
+        raise ValueError("health check did not return ok")
+    if payload.get("model") != MODEL_MANIFEST["image_generation"]["id"]:
+        raise ValueError("health check returned unexpected model")
+    if payload.get("runtime") != "modal-klein":
+        raise ValueError("health check returned unexpected runtime")
+
+
 def _runtime_status_core() -> dict[str, Any]:
     start = time.perf_counter()
     llama_start = time.perf_counter()
@@ -584,15 +616,46 @@ def _runtime_status_core() -> dict[str, Any]:
     kokoro_available = importlib.util.find_spec("kokoro") is not None
     soundfile_available = importlib.util.find_spec("soundfile") is not None
 
+    klein_status: dict[str, Any]
+    if KLEIN_MODAL_ENDPOINT:
+        try:
+            request = urllib.request.Request(
+                f"{KLEIN_MODAL_ENDPOINT}/health", method="GET",
+            )
+            with urllib.request.urlopen(request, timeout=5) as response:
+                payload = json.loads(response.read().decode("utf-8"))
+            _validate_modal_klein_health(payload)
+            klein_status = {
+                "available": True,
+                "status": "online",
+                "model": MODEL_MANIFEST["image_generation"]["id"],
+                "endpoint": KLEIN_MODAL_ENDPOINT,
+                "elapsed_ms": _elapsed_ms(start),
+            }
+        except (OSError, urllib.error.URLError, TimeoutError, ValueError, json.JSONDecodeError) as exc:
+            klein_status = {
+                "available": False,
+                "status": "fallback-ready",
+                "model": MODEL_MANIFEST["image_generation"]["id"],
+                "endpoint": KLEIN_MODAL_ENDPOINT,
+                "fallback": "bundled generated article assets",
+                "warning": exc.__class__.__name__,
+                "elapsed_ms": _elapsed_ms(start),
+            }
+    else:
+        klein_status = {
+            "available": False,
+            "status": "fallback-ready",
+            "model": MODEL_MANIFEST["image_generation"]["id"],
+            "fallback": "bundled generated article assets",
+        }
+
+    vision_status = _vision_runtime_status()
+
     return {
         "ok": True,
         "reader_brain": llama_status,
-        "vision": {
-            "available": False,
-            "status": "fallback-ready",
-            "model": "OpenBMB MiniCPM-V-2",
-            "fallback": "cached deterministic alt text",
-        },
+        "vision": vision_status,
         "speech": {
             "available": kokoro_available and soundfile_available,
             "status": "online" if kokoro_available and soundfile_available else "fallback-ready",
@@ -601,12 +664,7 @@ def _runtime_status_core() -> dict[str, Any]:
             "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",
-        },
+        "image_generation": klein_status,
         "elapsed_ms": _elapsed_ms(start),
     }
 
@@ -742,10 +800,36 @@ def reader_brain_core(node_type: str, text: str, position: str | None, mode: str
         }
 
 
-def describe_image_core(image_id: str, caption: str | None, prompt: str | None) -> dict[str, Any]:
-    start = time.perf_counter()
-    # The first committed slice keeps the API stable while the MiniCPM-V runtime lands next.
-    # The frontend passes deterministic image ids so cached descriptions can replace this later.
+def _openai_compatible_url(base_url: str, path: str) -> str:
+    normalized = base_url.rstrip("/")
+    if normalized.endswith("/v1/chat/completions"):
+        root = normalized[: -len("/chat/completions")]
+    elif normalized.endswith("/v1"):
+        root = normalized
+    else:
+        root = f"{normalized}/v1"
+    return f"{root}/{path.lstrip('/')}"
+
+
+def _article_image_by_id(image_id: str) -> dict[str, Any] | None:
+    return next((image for image in ARTICLE_IMAGES if image["id"] == image_id), None)
+
+
+def _absolute_image_url(image_url: str | None, image_id: str | None = None) -> str | None:
+    candidate = image_url
+    if not candidate and image_id:
+        image = _article_image_by_id(image_id)
+        candidate = image.get("asset_url") if image else None
+    if not candidate:
+        return None
+    if candidate.startswith(("http://", "https://", "data:")):
+        return candidate
+    if candidate.startswith("/"):
+        return f"{PUBLIC_BASE_URL}{candidate}"
+    return f"{PUBLIC_BASE_URL}/{candidate}"
+
+
+def _vision_fallback_text(image_id: str, caption: str | None, prompt: str | None) -> str:
     descriptions = {
         "desk-reader": (
             "A person reads a long article on a laptop while an accessibility toolbar "
@@ -756,15 +840,136 @@ def describe_image_core(image_id: str, caption: str | None, prompt: str | None)
             "reader brain, speech, and image generation."
         ),
     }
-    alt_text = descriptions.get(
+    return descriptions.get(
         image_id,
         caption or prompt or "A generated article image awaiting model description.",
     )
+
+
+def _clean_alt_text(text: str, limit: int = 260) -> str:
+    return _compact_text(" ".join(text.split()), limit)
+
+
+def _minicpm_vision_prompt(caption: str | None, prompt: str | None) -> str:
+    context = " ".join(part for part in [caption, prompt] if part)
+    context_line = f"\nContext: {context}" if context else ""
+    return (
+        "Describe this image for a screen reader in one or two concise sentences. "
+        "Mention visible content, layout, important text, and purpose when relevant. "
+        "Do not guess hidden intent. Do not mention models, implementation details, or that you are an AI. "
+        "Return plain text only."
+        f"{context_line}"
+    )
+
+
+def _call_minicpm_vision(image_url: str, caption: str | None, prompt: str | None) -> dict[str, Any]:
+    start = time.perf_counter()
+    body = json.dumps(
+        {
+            "model": MINICPM_VISION_MODEL,
+            "messages": [
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": _minicpm_vision_prompt(caption, prompt)},
+                        {"type": "image_url", "image_url": {"url": image_url}},
+                    ],
+                }
+            ],
+            "temperature": 0.1,
+            "max_tokens": 160,
+        }
+    ).encode("utf-8")
+    request = urllib.request.Request(
+        _openai_compatible_url(MINICPM_VISION_BASE_URL, "chat/completions"),
+        data=body,
+        headers={
+            "Authorization": f"Bearer {MINICPM_VISION_API_KEY}",
+            "Content-Type": "application/json",
+        },
+        method="POST",
+    )
+    with urllib.request.urlopen(request, timeout=MINICPM_VISION_TIMEOUT_SECONDS) as response:
+        payload = json.loads(response.read().decode("utf-8"))
+    content = payload["choices"][0]["message"]["content"]
+    if not isinstance(content, str) or not content.strip():
+        raise ValueError("MiniCPM vision response did not include text content")
+    return {
+        "runtime": "minicpm-v4.6",
+        "model": MINICPM_VISION_MODEL,
+        "alt_text": _clean_alt_text(content),
+        "elapsed_ms": _elapsed_ms(start),
+    }
+
+
+def _vision_runtime_status() -> dict[str, Any]:
+    if not MINICPM_VISION_BASE_URL or not MINICPM_VISION_API_KEY:
+        return {
+            "available": False,
+            "status": "fallback-ready",
+            "model": MINICPM_VISION_MODEL,
+            "configured": False,
+            "fallback": "cached deterministic alt text",
+        }
+    start = time.perf_counter()
+    try:
+        request = urllib.request.Request(
+            _openai_compatible_url(MINICPM_VISION_BASE_URL, "models"),
+            headers={"Authorization": f"Bearer {MINICPM_VISION_API_KEY}"},
+            method="GET",
+        )
+        with urllib.request.urlopen(request, timeout=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)
+        ]
+        if model_ids and MINICPM_VISION_MODEL not in model_ids:
+            raise ValueError("MiniCPM vision model was not listed by /models")
+        return {
+            "available": True,
+            "status": "online",
+            "model": MINICPM_VISION_MODEL,
+            "configured": True,
+            "base_url": MINICPM_VISION_BASE_URL,
+            "models": model_ids,
+            "elapsed_ms": _elapsed_ms(start),
+        }
+    except (OSError, urllib.error.URLError, TimeoutError, ValueError, json.JSONDecodeError) as exc:
+        return {
+            "available": False,
+            "status": "fallback-ready",
+            "model": MINICPM_VISION_MODEL,
+            "configured": True,
+            "base_url": MINICPM_VISION_BASE_URL,
+            "fallback": "cached deterministic alt text",
+            "warning": exc.__class__.__name__,
+            "elapsed_ms": _elapsed_ms(start),
+        }
+
+
+def describe_image_core(
+    image_id: str,
+    caption: str | None,
+    prompt: str | None,
+    image_url: str | None = None,
+) -> dict[str, Any]:
+    start = time.perf_counter()
+    resolved_image_url = _absolute_image_url(image_url, image_id)
+    alt_text = _vision_fallback_text(image_id, caption, prompt)
+    warning = None
+    if MINICPM_VISION_BASE_URL and MINICPM_VISION_API_KEY and resolved_image_url:
+        try:
+            return {"ok": True, **_call_minicpm_vision(resolved_image_url, caption, prompt)}
+        except (OSError, urllib.error.URLError, TimeoutError, KeyError, IndexError, TypeError, ValueError, json.JSONDecodeError) as exc:
+            warning = f"MiniCPM vision unavailable: {exc.__class__.__name__}"
     return {
         "ok": True,
-        "runtime": "MiniCPM-V placeholder",
-        "model": "OpenBMB MiniCPM-V-2",
+        "runtime": "fallback",
+        "model": MINICPM_VISION_MODEL,
         "alt_text": alt_text,
+        "warning": warning,
         "elapsed_ms": _elapsed_ms(start),
     }
 
@@ -777,12 +982,14 @@ def describe_article_images_core() -> dict[str, Any]:
             image["id"],
             caption=image.get("caption"),
             prompt=image.get("prompt"),
+            image_url=image.get("asset_url"),
         )
         descriptions.append({**image, **description})
+    runtimes = {item["runtime"] for item in descriptions}
     return {
         "ok": True,
-        "runtime": "MiniCPM-V placeholder",
-        "model": "OpenBMB MiniCPM-V-2",
+        "runtime": runtimes.pop() if len(runtimes) == 1 else "mixed",
+        "model": MINICPM_VISION_MODEL,
         "descriptions": descriptions,
         "elapsed_ms": _elapsed_ms(start),
     }
@@ -845,19 +1052,64 @@ def speak_core(text: str, voice: str, speed: float) -> dict[str, Any]:
     }
 
 
-def generate_image_core(prompt: str, seed: int | None) -> dict[str, Any]:
+def _call_modal_klein(prompt: str, seed: int | None) -> dict[str, Any]:
+    """Call the Modal Klein worker for live image generation."""
+    start = time.perf_counter()
+    body = json.dumps({"prompt": prompt, "seed": seed}).encode("utf-8")
+    request = urllib.request.Request(
+        f"{KLEIN_MODAL_ENDPOINT}/generate",
+        data=body,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    with urllib.request.urlopen(request, timeout=KLEIN_MODAL_TIMEOUT_SECONDS) as response:
+        payload = json.loads(response.read().decode("utf-8"))
+    if payload.get("ok") is not True:
+        raise ValueError(str(payload.get("error") or payload.get("detail") or "Modal Klein returned ok=false"))
+    if payload.get("model") != MODEL_MANIFEST["image_generation"]["id"]:
+        raise ValueError("Modal Klein returned unexpected model")
+    if payload.get("runtime") != "modal-klein":
+        raise ValueError("Modal Klein returned unexpected runtime")
+    image_url = payload.get("image_url", "")
+    if not isinstance(image_url, str) or not image_url:
+        raise ValueError("Modal Klein response did not include image_url")
+    if image_url and image_url.startswith("/media/"):
+        image_url = f"{KLEIN_MODAL_ENDPOINT}{image_url}"
+    return {
+        "ok": True,
+        "runtime": payload.get("runtime", "modal-klein"),
+        "model": payload.get("model", MODEL_MANIFEST["image_generation"]["id"]),
+        "image_url": image_url,
+        "prompt": payload.get("prompt", prompt),
+        "seed": payload.get("seed", seed),
+        "elapsed_ms": payload.get("elapsed_ms", _elapsed_ms(start)),
+    }
+
+
+def _fallback_image(prompt: str, seed: int | None, warning: str | None = None) -> dict[str, Any]:
+    """Return bundled fallback SVG assets when Modal is unavailable."""
     start = time.perf_counter()
     return {
         "ok": True,
-        "runtime": "placeholder",
-        "model": "black-forest-labs/FLUX.2-klein-4B",
+        "runtime": "fallback",
+        "model": MODEL_MANIFEST["image_generation"]["id"],
         "image_url": f"/static/generated/{'desk-reader.svg' if seed and seed % 2 else 'model-map.svg'}",
         "prompt": prompt,
         "seed": seed,
+        "warning": warning,
         "elapsed_ms": _elapsed_ms(start),
     }
 
 
+def generate_image_core(prompt: str, seed: int | None) -> dict[str, Any]:
+    if KLEIN_MODAL_ENDPOINT:
+        try:
+            return _call_modal_klein(prompt, seed)
+        except (OSError, urllib.error.URLError, TimeoutError, ValueError, KeyError, json.JSONDecodeError) as exc:
+            return _fallback_image(prompt, seed, warning=f"Modal Klein unavailable: {exc.__class__.__name__}")
+    return _fallback_image(prompt, seed)
+
+
 def generate_article_core(topic: str) -> dict[str, Any]:
     start = time.perf_counter()
     clean_topic = _compact_text(topic, 100).strip()
@@ -1008,7 +1260,7 @@ async def reader_brain_endpoint(payload: ReaderBrainRequest) -> JSONResponse:
 
 @app.post("/api/describe-image")
 async def describe_image_endpoint(payload: ImageDescriptionRequest) -> JSONResponse:
-    return _json(describe_image_core(payload.image_id, payload.caption, payload.prompt))
+    return _json(describe_image_core(payload.image_id, payload.caption, payload.prompt, payload.image_url))
 
 
 @app.get("/api/image-descriptions")
@@ -1037,8 +1289,8 @@ def reader_brain_api(node_type: str, text: str, position: str = "", mode: str =
 
 
 @app.api(name="describe_image")
-def describe_image_api(image_id: str, caption: str = "", prompt: str = "") -> str:
-    return json.dumps(describe_image_core(image_id, caption, prompt))
+def describe_image_api(image_id: str, caption: str = "", prompt: str = "", image_url: str = "") -> str:
+    return json.dumps(describe_image_core(image_id, caption, prompt, image_url))
 
 
 @app.api(name="describe_article_images")

modal_workers/klein_image.py

@@ -0,0 +1,146 @@
+"""Modal worker for black-forest-labs/FLUX.2-klein-4B image generation.
+
+Deploy:
+    modal deploy modal_workers/klein_image.py
+
+The deployed ASGI app exposes one base URL with:
+    POST /generate - accepts {"prompt": str, "seed": int | None}
+    GET  /health - reports worker readiness
+    GET  /media/{filename} - serves generated PNG files
+
+Tiny Narrator's app.py calls these routes through KLEIN_MODAL_ENDPOINT.
+"""
+
+from __future__ import annotations
+
+import io
+import time
+from pathlib import Path
+from uuid import uuid4
+
+import modal
+
+app = modal.App("tiny-narrator-klein")
+
+output_volume = modal.Volume.from_name("tiny-narrator-klein-outputs", create_if_missing=True)
+MEDIA_DIR = Path("/outputs")
+
+IMAGE_MODEL_ID = "black-forest-labs/FLUX.2-klein-4B"
+_PIPELINE = None
+
+klein_image = (
+    modal.Image.debian_slim(python_version="3.11")
+    .pip_install(
+        "fastapi[standard]",
+        "huggingface-hub[hf-transfer]>=0.36.0",
+        "pillow",
+        "torch",
+        "transformers",
+        "git+https://github.com/huggingface/diffusers.git",
+        "safetensors>=0.8.0rc0",
+        "accelerate",
+        "sentencepiece",
+    )
+    .env({"HF_HUB_ENABLE_HF_TRANSFER": "1"})
+)
+
+
+def _get_pipeline():
+    """Load the Klein pipeline once per warm ASGI container."""
+    global _PIPELINE
+    if _PIPELINE is None:
+        import torch
+        from diffusers import FluxPipeline
+
+        pipe = FluxPipeline.from_pretrained(
+            IMAGE_MODEL_ID,
+            torch_dtype=torch.bfloat16,
+        )
+        pipe.to("cuda")
+        _PIPELINE = pipe
+    return _PIPELINE
+
+
+@app.function(
+    image=klein_image,
+    gpu="A10G",
+    timeout=900,
+    container_idle_timeout=300,
+    volumes={str(MEDIA_DIR): output_volume},
+)
+@modal.asgi_app()
+def klein_api():
+    from fastapi import FastAPI, HTTPException
+    from fastapi.responses import Response
+    import torch
+
+    api = FastAPI(title="Tiny Narrator Klein Worker")
+
+    @api.get("/health")
+    async def health() -> dict:
+        return {
+            "ok": True,
+            "model": IMAGE_MODEL_ID,
+            "runtime": "modal-klein",
+        }
+
+    @api.post("/generate")
+    async def generate(request: dict) -> dict:
+        start = time.perf_counter()
+        prompt = str(request.get("prompt") or "").strip()
+        if not prompt:
+            raise HTTPException(status_code=400, detail="prompt is required")
+
+        seed = request.get("seed")
+        generator = None
+        if seed is not None:
+            try:
+                seed = int(seed)
+            except (TypeError, ValueError) as exc:
+                raise HTTPException(status_code=400, detail="seed must be an integer") from exc
+            generator = torch.Generator(device="cuda").manual_seed(seed)
+
+        result = _get_pipeline()(
+            prompt=prompt,
+            num_inference_steps=28,
+            guidance_scale=3.5,
+            generator=generator,
+        )
+        image = result.images[0]
+
+        filename = f"klein-{uuid4().hex}.png"
+        output_path = MEDIA_DIR / filename
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        buffer = io.BytesIO()
+        image.save(buffer, format="PNG")
+        output_path.write_bytes(buffer.getvalue())
+        output_volume.commit()
+
+        return {
+            "ok": True,
+            "runtime": "modal-klein",
+            "model": IMAGE_MODEL_ID,
+            "image_url": f"/media/{filename}",
+            "prompt": prompt,
+            "seed": seed,
+            "elapsed_ms": round((time.perf_counter() - start) * 1000),
+        }
+
+    @api.get("/media/{filename}")
+    async def media(filename: str):
+        output_volume.reload()
+        media_path = MEDIA_DIR / filename
+        if not media_path.exists() or not media_path.is_file():
+            raise HTTPException(status_code=404, detail=f"Media file not found: {filename}")
+
+        data = media_path.read_bytes()
+        content_type = "image/png"
+        if filename.endswith(".webp"):
+            content_type = "image/webp"
+        elif filename.endswith(".jpg") or filename.endswith(".jpeg"):
+            content_type = "image/jpeg"
+
+        return Response(content=data, media_type=content_type)
+
+    return api

openspec/changes/add-minicpm-v46-image-descriptor/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-15

openspec/changes/add-minicpm-v46-image-descriptor/design.md

@@ -0,0 +1,135 @@
+# Design: MiniCPM-V-4.6 Image Descriptor
+
+## Overview
+
+Tiny Narrator will keep the existing image-description APIs but upgrade the vision role from cached-only placeholder behavior to a live MiniCPM-V-4.6 path when configured.
+
+The backend will call an OpenAI-compatible `/v1/chat/completions` endpoint. The user will provide the base URL and API key. Local development and verification will continue to pass without credentials by using deterministic fallbacks.
+
+## Configuration
+
+Add environment variables:
+
+| Variable | Purpose |
+| --- | --- |
+| `MINICPM_VISION_BASE_URL` | Base URL for the OpenAI-compatible MiniCPM-V-4.6 server. Accept either the server root or a URL ending in `/v1`; app code should normalize to `/v1/chat/completions`. |
+| `MINICPM_VISION_API_KEY` | Bearer token for the MiniCPM vision endpoint. |
+| `MINICPM_VISION_MODEL` | Optional model id, default `openbmb/MiniCPM-V-4.6`. |
+| `MINICPM_VISION_TIMEOUT_SECONDS` | Request timeout, default short enough for UI responsiveness but long enough for warm inference. |
+
+The API key must never be exposed in runtime setup/status payloads. Status may report whether a key is configured.
+
+## Request Shape
+
+The app should send a multimodal chat-completions request:
+
+```json
+{
+  "model": "openbmb/MiniCPM-V-4.6",
+  "messages": [
+    {
+      "role": "user",
+      "content": [
+        {
+          "type": "text",
+          "text": "Describe this image for a screen reader..."
+        },
+        {
+          "type": "image_url",
+          "image_url": {
+            "url": "https://public-base-url/static/generated/model-map.svg"
+          }
+        }
+      ]
+    }
+  ],
+  "temperature": 0.1,
+  "max_tokens": 160
+}
+```
+
+The prompt should ask for concise accessibility alt text:
+
+- one or two sentences
+- no implementation details
+- describe visible content, layout, text, and purpose when relevant
+- avoid guessing hidden intent
+- return plain text only
+
+## Image URL Resolution
+
+For known article images, use the `asset_url` from `ARTICLE_IMAGES`. If it is relative, prefix `PUBLIC_BASE_URL`.
+
+For direct `POST /api/describe-image` calls:
+
+- continue supporting `image_id`, `caption`, and `prompt`
+- optionally add `image_url` to the request schema so future callers can describe external or generated images
+- if no usable image URL is available, use fallback text instead of calling the vision endpoint
+
+## Response Handling
+
+Parse the first chat completion message:
+
+```json
+choices[0].message.content
+```
+
+Validate that the content is a non-empty string. Normalize whitespace and limit length for safe UI/transcript use. Return the existing response shape with live metadata:
+
+```json
+{
+  "ok": true,
+  "runtime": "minicpm-v4.6",
+  "model": "openbmb/MiniCPM-V-4.6",
+  "alt_text": "...",
+  "elapsed_ms": 1234
+}
+```
+
+If the endpoint is missing, credentials are missing, the image URL cannot be resolved, the request fails, or the response is invalid, return deterministic fallback alt text with:
+
+```json
+{
+  "runtime": "fallback",
+  "model": "openbmb/MiniCPM-V-4.6",
+  "warning": "MiniCPM vision unavailable: ..."
+}
+```
+
+When no live call was attempted because configuration is absent, warning can be omitted to keep local demos quiet.
+
+## Runtime Setup And Status
+
+`runtime_setup_core()` should document:
+
+- the expected OpenAI-compatible serving path
+- environment variables
+- example commands for compatible runtimes, such as `vllm serve openbmb/MiniCPM-V-4.6` or `llama-server` with a MiniCPM-V-4.6 GGUF
+- fallback behavior
+
+`_runtime_status_core()` should:
+
+- report `vision.status = "fallback-ready"` when not configured
+- report `vision.status = "online"` only when both base URL and API key are configured and a lightweight readiness check succeeds
+- avoid sending images in the status check; use `/models` if available, or a minimal chat-completions check only if necessary
+- never expose `MINICPM_VISION_API_KEY`
+
+## Frontend Behavior
+
+No major frontend changes are required. The existing reader route already preloads `/api/image-descriptions`, writes returned alt text into image attributes, and uses image descriptions for screen-reader narration.
+
+If live MiniCPM inference is slow, the frontend should still remain usable because the backend returns fallback descriptions on timeout.
+
+## Testing Strategy
+
+Verification should not need network or credentials. Add mocked tests for:
+
+- no configuration returns fallback MiniCPM-V-4.6 metadata
+- successful OpenAI-compatible response returns live alt text
+- invalid response falls back with a warning
+- failed request falls back with a warning
+- runtime setup documents MiniCPM-V-4.6 configuration
+- runtime status does not expose API keys
+- existing `/api/image-descriptions` shape remains stable
+
+Manual testing can cover a real configured endpoint after the user provides base URL and API key.

openspec/changes/add-minicpm-v46-image-descriptor/proposal.md

@@ -0,0 +1,36 @@
+# Add MiniCPM-V-4.6 Image Descriptor
+
+## Why
+
+Tiny Narrator currently lists `openbmb/MiniCPM-V-2` for the image descriptor role, but the implementation still returns deterministic cached alt text. The project needs real visual description inference for generated article images while keeping the existing screen-reader fallback path reliable.
+
+`openbmb/MiniCPM-V-4.6` is a better fit for the role because it is newer, smaller, Tiny Titan-safe, and supports OpenAI-compatible chat-completions deployments through runtimes such as vLLM, SGLang, llama.cpp, or hosted services.
+
+## What Changes
+
+- Switch the planned vision model from `openbmb/MiniCPM-V-2` to `openbmb/MiniCPM-V-4.6`.
+- Add configuration for an OpenAI-compatible `/v1/chat/completions` vision endpoint.
+- Call the configured MiniCPM-V-4.6 endpoint from the image-description path when credentials are available.
+- Preserve deterministic cached alt-text fallbacks when the endpoint is not configured, unreachable, or returns invalid content.
+- Update runtime setup/status, evidence payloads, docs, and verifier expectations to distinguish live MiniCPM-V-4.6 inference from fallback descriptions.
+
+## Capabilities
+
+- `minicpm-v46-image-description`: generate screen-reader-ready image descriptions using MiniCPM-V-4.6 through an OpenAI-compatible chat-completions API.
+- `image-description-fallbacks`: retain deterministic alt text for stable local and hackathon demos.
+- `vision-runtime-evidence`: expose model id, runtime status, latency, fallback state, and setup instructions through the existing evidence APIs.
+
+## Non-Goals
+
+- Do not change the reader-brain llama.cpp path.
+- Do not change Kokoro TTS.
+- Do not change the Modal Klein image-generation worker.
+- Do not require the MiniCPM endpoint or API key for local verification to pass.
+- Do not add a separate evidence UI page.
+
+## Impact
+
+- `app.py` will gain MiniCPM-V-4.6 endpoint configuration and an OpenAI-compatible vision client.
+- Existing `/api/describe-image` and `/api/image-descriptions` responses will keep their current shape but may return live MiniCPM runtime metadata.
+- README, SUBMISSION, and FIELD_NOTES will describe MiniCPM-V-4.6 setup and fallback behavior.
+- `scripts/verify.py` will cover fallback behavior and mocked live MiniCPM responses without making network calls.

openspec/changes/add-minicpm-v46-image-descriptor/tasks.md

@@ -0,0 +1,58 @@
+# Tasks: MiniCPM-V-4.6 Image Descriptor
+
+## 1. Model Metadata And Configuration
+
+- [x] Update `MODEL_MANIFEST["vision"]` to `openbmb/MiniCPM-V-4.6` with Tiny Titan-safe parameter metadata.
+- [x] Add `MINICPM_VISION_BASE_URL`, `MINICPM_VISION_API_KEY`, `MINICPM_VISION_MODEL`, and `MINICPM_VISION_TIMEOUT_SECONDS`.
+- [x] Add safe env parsing so invalid timeout values do not break app import.
+- [x] Ensure no API key value appears in runtime setup/status/evidence responses.
+
+## 2. OpenAI-Compatible Vision Client
+
+- [x] Add a helper to normalize the configured base URL to `/v1/chat/completions`.
+- [x] Add a helper to resolve known article image URLs from `ARTICLE_IMAGES` and `PUBLIC_BASE_URL`.
+- [x] Add a MiniCPM-V-4.6 chat-completions client using `Authorization: Bearer <key>`.
+- [x] Send multimodal messages with accessibility-focused alt-text instructions and `image_url` content.
+- [x] Validate `choices[0].message.content` before using it as `alt_text`.
+- [x] Normalize/compact returned alt text for UI and transcript safety.
+
+## 3. API Behavior
+
+- [x] Update `ImageDescriptionRequest` to optionally accept `image_url`.
+- [x] Update `describe_image_core()` to call MiniCPM-V-4.6 when configuration and image URL are available.
+- [x] Preserve deterministic cached fallback descriptions when not configured.
+- [x] Return fallback descriptions with visible warning metadata when live inference fails or returns invalid content.
+- [x] Update `describe_article_images_core()` so article image receipts include live or fallback vision runtime metadata.
+- [x] Keep `/api/describe-image` and `/api/image-descriptions` response shapes backward compatible.
+
+## 4. Runtime Evidence
+
+- [x] Update `runtime_setup_core()` with OpenAI-compatible MiniCPM-V-4.6 setup guidance and required env vars.
+- [x] Update `_runtime_status_core()` to report MiniCPM-V-4.6 online/fallback-ready status.
+- [x] Use `/models` or another lightweight non-image readiness check where possible.
+- [x] Update `submission_readiness_core()` and `evidence_bundle_core()` only if their expectations need to distinguish live vision from fallback.
+- [x] Ensure `/api/model-budget` still passes Tiny Titan.
+
+## 5. Docs
+
+- [x] Update `README.md` recommended model table and setup section.
+- [x] Update `SUBMISSION.md` to name MiniCPM-V-4.6 for image understanding.
+- [x] Update `FIELD_NOTES.md` with the OpenAI-compatible endpoint design and fallback behavior.
+- [x] Mention that the user supplies `MINICPM_VISION_BASE_URL` and `MINICPM_VISION_API_KEY`.
+
+## 6. Verification
+
+- [x] Add verifier tests for fallback image descriptions with no MiniCPM config.
+- [x] Add mocked tests for successful MiniCPM-V-4.6 chat-completions response.
+- [x] Add mocked tests for failed/invalid MiniCPM responses falling back with warnings.
+- [x] Add tests that runtime status/setup mention MiniCPM-V-4.6 and do not leak API keys.
+- [x] Run `python scripts\verify.py`.
+- [x] Run `python -m py_compile app.py scripts\verify.py`.
+- [x] Run `git diff --check`.
+
+## 7. Manual Endpoint Check
+
+- [ ] Set `MINICPM_VISION_BASE_URL`.
+- [ ] Set `MINICPM_VISION_API_KEY`.
+- [ ] Call `/api/describe-image` for `model-map` and confirm live MiniCPM-V-4.6 runtime metadata.
+- [ ] Open the Reader page and confirm image alt text is updated without breaking screen-reader narration.

openspec/changes/add-modal-klein-image-inference/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-06-14

openspec/changes/add-modal-klein-image-inference/design.md

@@ -0,0 +1,104 @@
+# Design: Modal Klein Image Inference
+
+## Overview
+
+Tiny Narrator will keep its current `POST /api/generate-image` and `/api/generate-article` contracts, but `generate_image_core()` will become a two-path adapter:
+
+1. If a Modal Klein endpoint is configured, call it for live `black-forest-labs/FLUX.2-klein-4B` inference.
+2. If the endpoint is missing or fails, return the current bundled fallback assets with explicit fallback metadata.
+
+This preserves the app's hackathon reliability while making the image-generation claim real when the Modal worker is deployed.
+
+## Modal Worker
+
+Add a new worker module, likely `modal_workers/klein_image.py`, with:
+
+- a Modal `App`
+- a persistent Modal `Volume` for generated images
+- an image/container definition that installs FastAPI, Pillow, torch, transformers/diffusers dependencies, and the Klein runtime dependencies
+- a model class or cached function that loads `black-forest-labs/FLUX.2-klein-4B` once per warm container
+- a FastAPI web endpoint, for example `POST /generate`, accepting:
+  - `prompt: str`
+  - `seed: int | None`
+  - optional generation controls only if needed later
+- a `GET /media/{filename}` endpoint for generated PNG/WebP files
+
+The worker should return:
+
+```json
+{
+  "ok": true,
+  "runtime": "modal-klein",
+  "model": "black-forest-labs/FLUX.2-klein-4B",
+  "image_url": "https://.../media/klein-....png",
+  "prompt": "...",
+  "seed": 123,
+  "elapsed_ms": 12345
+}
+```
+
+From the referenced TinyDeck thread, the important Modal implementation lessons are:
+
+- Use an explicit media helper for `GET /media/{filename}`.
+- Call `output_volume.reload()` before serving media from a web container.
+- Return a clean 404 for missing media instead of letting `FileResponse` crash.
+- Give the web endpoint a long enough timeout for cold starts.
+- If using a GitHub Diffusers build, avoid incompatible `safetensors==0.7.0`; use a compatible lower bound such as `safetensors>=0.8.0rc0` if that dependency path is chosen.
+
+## App Configuration
+
+Add environment variables:
+
+| Variable | Purpose |
+| --- | --- |
+| `KLEIN_MODAL_ENDPOINT` | Base URL for the Modal Klein worker, without trailing slash. |
+| `KLEIN_MODAL_TIMEOUT_SECONDS` | Request timeout for image generation, defaulting high enough for warm inference but not blocking local demos forever. |
+
+No Modal dependency is needed in the main Gradio app unless the implementation chooses a direct Modal SDK client. Prefer plain HTTP from `app.py` so Hugging Face Spaces can call the worker with standard library or already-small dependencies.
+
+## App Integration
+
+`generate_image_core(prompt, seed)` should:
+
+- record a start time
+- call `POST {KLEIN_MODAL_ENDPOINT}/generate` when configured
+- validate the response shape before trusting it
+- preserve the returned prompt, seed, model, runtime, image URL, and elapsed time
+- add a warning and fall back to bundled SVG assets on network errors, bad responses, timeout, or missing endpoint
+
+`generate_article_core()` can keep its current article text behavior and use the upgraded `generate_image_core()` for thumbnails.
+
+`_runtime_status_core()` should report:
+
+- `available: true`, `status: "online"` when the worker health check succeeds
+- `available: false`, `status: "fallback-ready"` when not configured or not reachable
+- endpoint and timeout metadata without exposing secrets
+
+`runtime_setup_core()` should show a copyable `modal deploy modal_workers/klein_image.py` command and the required `KLEIN_MODAL_ENDPOINT` configuration.
+
+## Fallbacks
+
+Fallbacks stay first-class and visible:
+
+- Existing bundled SVGs remain available.
+- Fallback payloads keep `ok: true` because the UI can still render.
+- Payloads should include `runtime: "fallback"` or `generation_runtime: "bundled fallback asset"` and a `warning` when live inference failed.
+- Verification should not require Modal credentials or network access.
+
+## Evidence And Docs
+
+Update evidence APIs and docs so they no longer say "Python integration planned" for image generation once the worker exists. They should say Modal-hosted Klein is supported and report whether the current runtime is online or fallback-ready.
+
+The Generate route can continue showing thumbnail provenance through the existing receipt text. If live Modal inference is active, the receipt should reflect `modal-klein` instead of placeholder/fallback runtime.
+
+## Testing Strategy
+
+Use unit-style tests around `generate_image_core()`:
+
+- no endpoint configured returns deterministic fallback
+- configured endpoint returning valid JSON is surfaced as live Modal inference
+- configured endpoint failure falls back with a warning
+- `/api/runtime-status` and `/api/runtime-setup` mention the Modal Klein path
+- `/api/generate-article` thumbnail provenance remains stable
+
+The Modal worker should be syntax-checked locally. Live deployment testing can be documented as a manual command because CI/local verification should not require GPU infrastructure.

openspec/changes/add-modal-klein-image-inference/proposal.md

@@ -0,0 +1,35 @@
+# Add Modal Klein Image Inference
+
+## Why
+
+Tiny Narrator currently documents `black-forest-labs/FLUX.2-klein-4B` as the image-generation model, but `generate_image_core()` only returns bundled fallback SVG assets with placeholder runtime metadata. That is honest, but it leaves the Generate route short of real image-generation inference.
+
+Adding a Modal-hosted Klein worker gives the project a live image-generation path while preserving the deterministic fallback behavior that keeps hackathon demos reliable.
+
+## What Changes
+
+- Add a Modal worker for `black-forest-labs/FLUX.2-klein-4B` image generation.
+- Expose an HTTP JSON endpoint that accepts a prompt and optional seed, writes generated images to Modal storage, and serves them through a media route.
+- Update Tiny Narrator's image-generation backend path to call the Modal endpoint when configured.
+- Keep bundled fallback assets when Modal is not configured, cold-starts fail, or generation times out.
+- Update runtime setup/status, evidence payloads, docs, and verifier expectations so the app distinguishes live Klein inference from fallback assets.
+
+## Capabilities
+
+- `modal-klein-image-generation`: generate article thumbnails through a Modal-hosted Klein inference endpoint.
+- `image-generation-fallbacks`: retain deterministic local fallback assets and explicit fallback metadata.
+- `image-generation-evidence`: surface runtime status, model id, prompt, seed, latency, and generated media URL in existing evidence APIs.
+
+## Non-Goals
+
+- Do not implement MiniCPM-V image-description inference in this change.
+- Do not replace the existing reader, TTS, or llama.cpp paths.
+- Do not require live Modal inference for local verification to pass.
+- Do not add a separate evidence UI page.
+
+## Impact
+
+- `app.py` will gain Modal endpoint configuration, a small image-generation client, and updated runtime/status metadata.
+- A new `modal_workers/` script will be added for deploying the Klein worker.
+- `README.md`, `SUBMISSION.md`, and `FIELD_NOTES.md` will describe live Modal Klein setup and fallback behavior.
+- `scripts/verify.py` will assert that the API contract and fallback path remain stable without requiring Modal credentials.

openspec/changes/add-modal-klein-image-inference/tasks.md

@@ -0,0 +1,55 @@
+# Tasks: Modal Klein Image Inference
+
+## 1. Modal Worker
+
+- [x] Add `modal_workers/klein_image.py` with a Modal app, persistent output volume, and FastAPI web endpoints.
+- [x] Implement `POST /generate` for `black-forest-labs/FLUX.2-klein-4B` prompt + optional seed inference.
+- [x] Implement `GET /media/{filename}` with volume reload before serving and clean 404 handling for missing files.
+- [x] Add worker-level timeout and dependency pins suitable for cold starts.
+- [x] Document the deploy command and expected endpoint shape in comments or docs.
+
+## 2. App Configuration And Client
+
+- [x] Add `KLEIN_MODAL_ENDPOINT` and `KLEIN_MODAL_TIMEOUT_SECONDS` configuration in `app.py`.
+- [x] Add a small HTTP client/helper for calling the Modal Klein worker.
+- [x] Update `generate_image_core()` to use Modal when configured.
+- [x] Preserve deterministic bundled fallback behavior when Modal is missing, slow, or returns invalid data.
+- [x] Include `warning`, `runtime`, `model`, `prompt`, `seed`, `image_url`, and `elapsed_ms` consistently in live and fallback responses.
+
+## 3. Runtime Evidence
+
+- [x] Update `MODEL_MANIFEST["image_generation"]["runtime"]` from planned integration to Modal-hosted Klein.
+- [x] Update `runtime_setup_core()` with Modal deploy/setup instructions and environment variables.
+- [x] Update `_runtime_status_core()` to report Modal Klein online/fallback-ready status.
+- [x] Update `demo_script_core()`, `submission_readiness_core()`, and `evidence_bundle_core()` expectations as needed.
+- [x] Ensure `/api/model-budget` still proves Tiny Titan <= 4B.
+
+## 4. Generate Route Behavior
+
+- [x] Ensure `/api/generate-image` returns live Modal image URLs when configured.
+- [x] Ensure `/api/generate-article` thumbnail receipts reflect live Modal runtime when available.
+- [x] Keep the Generate page UI stable and screen-reader-compatible with generated thumbnails.
+- [x] Avoid adding a new evidence UI page.
+
+## 5. Docs
+
+- [x] Update `README.md` with Modal Klein setup, environment variables, and fallback behavior.
+- [x] Update `SUBMISSION.md` to distinguish live Modal Klein inference from bundled fallback assets.
+- [x] Update `FIELD_NOTES.md` with architecture notes, runtime honesty, and manual deploy guidance.
+
+## 6. Verification
+
+- [x] Add tests in `scripts/verify.py` for fallback image generation without Modal.
+- [x] Add mocked/stubbed tests for successful Modal worker responses.
+- [x] Add mocked/stubbed tests for Modal failure fallback with a visible warning.
+- [x] Add static checks for the Modal worker file.
+- [x] Run `python scripts\verify.py`.
+- [x] Run `python -m py_compile app.py scripts\verify.py modal_workers\klein_image.py`.
+- [x] Run `git diff --check`.
+
+## 7. Manual Modal Check
+
+- [ ] Deploy with `modal deploy modal_workers/klein_image.py`.
+- [ ] Set `KLEIN_MODAL_ENDPOINT` locally or in the Space runtime.
+- [ ] Call `/api/generate-image` with a sample prompt and confirm it returns a Modal media URL.
+- [ ] Generate an article from `/generate` and confirm the thumbnail receipt reports live Modal Klein runtime.

openspec/config.yaml

@@ -0,0 +1,20 @@
+schema: spec-driven
+
+# Project context (optional)
+# This is shown to AI when creating artifacts.
+# Add your tech stack, conventions, style guides, domain knowledge, etc.
+# Example:
+#   context: |
+#     Tech stack: TypeScript, React, Node.js
+#     We use conventional commits
+#     Domain: e-commerce platform
+
+# Per-artifact rules (optional)
+# Add custom rules for specific artifacts.
+# Example:
+#   rules:
+#     proposal:
+#       - Keep proposals under 500 words
+#       - Always include a "Non-goals" section
+#     tasks:
+#       - Break tasks into chunks of max 2 hours

scripts/verify.py

@@ -1,9 +1,11 @@
 from __future__ import annotations
 
+import json
 import py_compile
 import sys
 import wave
 from pathlib import Path
+from unittest.mock import patch, MagicMock
 
 
 ROOT = Path(__file__).resolve().parents[1]
@@ -202,6 +204,8 @@ def verify_core_fallbacks() -> None:
     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")
+    assert_true(description["runtime"] == "fallback", "Image description without MiniCPM config should use fallback runtime")
+    assert_true(description["model"] == app.MODEL_MANIFEST["vision"]["id"], "Image description should report the vision model id")
     assert_true(isinstance(description["elapsed_ms"], int), "Image description should include elapsed_ms")
 
     article_descriptions = app.describe_article_images_core()
@@ -216,6 +220,8 @@ def verify_core_fallbacks() -> None:
         "Article image descriptions should include generation seeds",
     )
     assert_true(isinstance(article_descriptions["elapsed_ms"], int), "Article image descriptions should include elapsed_ms")
+    assert_true(article_descriptions["model"] == app.MODEL_MANIFEST["vision"]["id"], "Article image descriptions should report vision model id")
+    assert_true(article_descriptions["runtime"] == "fallback", "Article image descriptions should use fallback without MiniCPM config")
 
     speech = app.speak_core("Tiny Narrator verification.", voice="af_heart", speed=1.0)
     assert_true(speech["ok"], "Speech path did not return ok")
@@ -229,6 +235,16 @@ def verify_core_fallbacks() -> None:
     generated = app.generate_image_core("Tiny accessibility article image.", seed=3)
     assert_true(generated["ok"], "Image generation placeholder should return ok")
     assert_true(isinstance(generated["elapsed_ms"], int), "Image generation should include elapsed_ms")
+    assert_true(generated["runtime"] == "fallback", "Image generation without Modal should report fallback runtime")
+    assert_true(generated["model"] == app.MODEL_MANIFEST["image_generation"]["id"], "Image generation should report Klein model id")
+    assert_true(generated["seed"] == 3, "Image generation should preserve the seed")
+    assert_true(generated["image_url"].startswith("/static/generated/"), "Fallback image should use bundled assets")
+    assert_true(generated.get("warning") is None, "Fallback without attempted call should have no warning")
+
+    generated_no_seed = app.generate_image_core("Another image prompt.", seed=None)
+    assert_true(generated_no_seed["ok"], "Image generation without seed should return ok")
+    assert_true(generated_no_seed["runtime"] == "fallback", "Image generation without Modal should report fallback")
+    assert_true(generated_no_seed["seed"] is None, "Image generation should pass through None seed")
 
     article = app.generate_article_core("tiny classroom robotics")
     assert_true(article["ok"], "Article generation should return ok")
@@ -240,6 +256,202 @@ def verify_core_fallbacks() -> None:
     )
 
 
+def verify_modal_klein_integration() -> None:
+    """Test Modal Klein integration with mocked HTTP responses."""
+    # Test: no endpoint configured returns deterministic fallback
+    with patch.object(app, "KLEIN_MODAL_ENDPOINT", ""):
+        result = app.generate_image_core("test prompt", seed=42)
+        assert_true(result["ok"], "No-endpoint fallback should return ok")
+        assert_true(result["runtime"] == "fallback", "No-endpoint should report fallback runtime")
+        assert_true(result["image_url"].startswith("/static/generated/"), "No-endpoint should use bundled assets")
+        assert_true(result["model"] == app.MODEL_MANIFEST["image_generation"]["id"], "Fallback should report Klein model")
+
+    # Test: configured endpoint returning valid JSON is surfaced as live Modal inference
+    mock_response_data = {
+        "ok": True,
+        "runtime": "modal-klein",
+        "model": "black-forest-labs/FLUX.2-klein-4B",
+        "image_url": "/media/klein-abc123.png",
+        "prompt": "test prompt",
+        "seed": 42,
+        "elapsed_ms": 5000,
+    }
+    mock_response = MagicMock()
+    mock_response.read.return_value = json.dumps(mock_response_data).encode("utf-8")
+    mock_response.__enter__ = lambda s: s
+    mock_response.__exit__ = MagicMock(return_value=False)
+
+    with patch.object(app, "KLEIN_MODAL_ENDPOINT", "https://example-modal.modal.run"):
+        with patch("urllib.request.urlopen", return_value=mock_response):
+            result = app.generate_image_core("test prompt", seed=42)
+            assert_true(result["ok"], "Modal success should return ok")
+            assert_true(result["runtime"] == "modal-klein", "Modal success should report modal-klein runtime")
+            assert_true(
+                result["image_url"] == "https://example-modal.modal.run/media/klein-abc123.png",
+                "Modal success should return full media URL",
+            )
+            assert_true(result["prompt"] == "test prompt", "Modal success should preserve prompt")
+            assert_true(result["seed"] == 42, "Modal success should preserve seed")
+
+    # Test: configured endpoint failure falls back with a visible warning
+    with patch.object(app, "KLEIN_MODAL_ENDPOINT", "https://example-modal.modal.run"):
+        with patch("urllib.request.urlopen", side_effect=TimeoutError("Connection timed out")):
+            result = app.generate_image_core("test prompt", seed=42)
+            assert_true(result["ok"], "Modal failure fallback should return ok")
+            assert_true(result["runtime"] == "fallback", "Modal failure should report fallback runtime")
+            assert_true(
+                result["image_url"].startswith("/static/generated/"),
+                "Modal failure should use bundled assets",
+            )
+            assert_true(
+                result.get("warning") is not None and "TimeoutError" in result["warning"],
+                "Modal failure should include a visible warning with the error class",
+            )
+
+    # Test: invalid Modal JSON response falls back instead of pretending success
+    invalid_response = MagicMock()
+    invalid_response.read.return_value = json.dumps({"ok": False, "error": "prompt is required"}).encode("utf-8")
+    invalid_response.__enter__ = lambda s: s
+    invalid_response.__exit__ = MagicMock(return_value=False)
+
+    with patch.object(app, "KLEIN_MODAL_ENDPOINT", "https://example-modal.modal.run"):
+        with patch("urllib.request.urlopen", return_value=invalid_response):
+            result = app.generate_image_core("test prompt", seed=42)
+            assert_true(result["runtime"] == "fallback", "Invalid Modal response should use fallback runtime")
+            assert_true(
+                result.get("warning") is not None and "ValueError" in result["warning"],
+                "Invalid Modal response should include a validation warning",
+            )
+
+    # Test: Modal worker static checks
+    worker_path = ROOT / "modal_workers" / "klein_image.py"
+    assert_true(worker_path.exists(), "Modal worker file should exist")
+    worker_source = worker_path.read_text(encoding="utf-8")
+    assert_true("modal.App" in worker_source, "Modal worker should create a Modal App")
+    assert_true("modal.Volume" in worker_source, "Modal worker should use a Modal Volume")
+    assert_true("FLUX.2-klein-4B" in worker_source, "Modal worker should reference the Klein model")
+    assert_true("modal.asgi_app" in worker_source, "Modal worker should expose one ASGI app")
+    assert_true('@api.post("/generate")' in worker_source, "Modal worker should expose POST /generate")
+    assert_true('@api.get("/health")' in worker_source, "Modal worker should expose GET /health")
+    assert_true('@api.get("/media/{filename}")' in worker_source, "Modal worker should expose GET /media/{filename}")
+    assert_true("404" in worker_source or "not found" in worker_source.lower(), "Modal worker should handle missing media with 404")
+    assert_true("reload" in worker_source, "Modal worker should reload volume before serving")
+
+    # Test: runtime status includes Modal Klein path
+    with patch.object(app, "KLEIN_MODAL_ENDPOINT", ""):
+        status = app._runtime_status_core()
+        assert_true("image_generation" in status, "Runtime status should include image_generation")
+        assert_true(
+            status["image_generation"]["status"] in {"online", "fallback-ready"},
+            "Image generation status should be online or fallback-ready",
+        )
+        assert_true(
+            status["image_generation"]["model"] == app.MODEL_MANIFEST["image_generation"]["id"],
+            "Image generation status should reference the Klein model",
+        )
+
+    # Test: invalid health payload is fallback-ready, not online
+    bad_health = MagicMock()
+    bad_health.read.return_value = json.dumps({"ok": True, "model": "wrong", "runtime": "modal-klein"}).encode("utf-8")
+    bad_health.__enter__ = lambda s: s
+    bad_health.__exit__ = MagicMock(return_value=False)
+    with patch.object(app, "KLEIN_MODAL_ENDPOINT", "https://example-modal.modal.run"):
+        with patch("urllib.request.urlopen", return_value=bad_health):
+            status = app._runtime_status_core()
+            assert_true(
+                status["image_generation"]["status"] == "fallback-ready",
+                "Invalid Modal health should not be marked online",
+            )
+            assert_true("ValueError" in status["image_generation"].get("warning", ""), "Invalid health should report validation warning")
+
+    # Test: runtime setup includes Modal deploy command
+    setup = app.runtime_setup_core()
+    image_step = next(step for step in setup["steps"] if step["role"] == "image_generation")
+    assert_true(
+        "modal deploy" in image_step["command"],
+        "Runtime setup should include modal deploy command for image generation",
+    )
+    assert_true(
+        "KLEIN_MODAL_ENDPOINT" in image_step["env"],
+        "Runtime setup should document KLEIN_MODAL_ENDPOINT",
+    )
+
+
+def verify_minicpm_vision_integration() -> None:
+    with patch.object(app, "MINICPM_VISION_BASE_URL", ""), patch.object(app, "MINICPM_VISION_API_KEY", ""):
+        result = app.describe_image_core("model-map", caption=None, prompt=None)
+        assert_true(result["ok"], "No-config MiniCPM fallback should return ok")
+        assert_true(result["runtime"] == "fallback", "No-config MiniCPM should report fallback runtime")
+        assert_true(result["model"] == app.MODEL_MANIFEST["vision"]["id"], "No-config MiniCPM should report vision model")
+        assert_true(result.get("warning") is None, "No-config MiniCPM fallback should stay quiet")
+
+    mock_response_data = {
+        "choices": [
+            {
+                "message": {
+                    "content": "A compact diagram shows four small AI models connected around an accessibility reader."
+                }
+            }
+        ]
+    }
+    mock_response = MagicMock()
+    mock_response.read.return_value = json.dumps(mock_response_data).encode("utf-8")
+    mock_response.__enter__ = lambda s: s
+    mock_response.__exit__ = MagicMock(return_value=False)
+
+    with patch.object(app, "MINICPM_VISION_BASE_URL", "https://vision.example/v1"):
+        with patch.object(app, "MINICPM_VISION_API_KEY", "secret-key"):
+            with patch("urllib.request.urlopen", return_value=mock_response) as urlopen_mock:
+                result = app.describe_image_core("model-map", caption="diagram", prompt="model map", image_url="/static/generated/model-map.svg")
+                assert_true(result["ok"], "Live MiniCPM response should return ok")
+                assert_true(result["runtime"] == "minicpm-v4.6", "Live MiniCPM response should report runtime")
+                assert_true(result["model"] == app.MINICPM_VISION_MODEL, "Live MiniCPM response should report configured model")
+                assert_true("accessibility reader" in result["alt_text"], "Live MiniCPM response should use returned alt text")
+                request = urlopen_mock.call_args.args[0]
+                assert_true(
+                    request.full_url == "https://vision.example/v1/chat/completions",
+                    "MiniCPM client should normalize base URL to chat completions",
+                )
+                assert_true(
+                    request.headers.get("Authorization") == "Bearer secret-key",
+                    "MiniCPM client should send bearer auth",
+                )
+
+    invalid_response = MagicMock()
+    invalid_response.read.return_value = json.dumps({"choices": [{"message": {"content": ""}}]}).encode("utf-8")
+    invalid_response.__enter__ = lambda s: s
+    invalid_response.__exit__ = MagicMock(return_value=False)
+
+    with patch.object(app, "MINICPM_VISION_BASE_URL", "https://vision.example"):
+        with patch.object(app, "MINICPM_VISION_API_KEY", "secret-key"):
+            with patch("urllib.request.urlopen", return_value=invalid_response):
+                result = app.describe_image_core("custom", caption="fallback caption", prompt=None, image_url="https://example.com/image.png")
+                assert_true(result["runtime"] == "fallback", "Invalid MiniCPM response should fall back")
+                assert_true(result["alt_text"] == "fallback caption", "Invalid MiniCPM response should preserve fallback text")
+                assert_true(
+                    result.get("warning") is not None and "ValueError" in result["warning"],
+                    "Invalid MiniCPM response should include validation warning",
+                )
+
+    models_response = MagicMock()
+    models_response.read.return_value = json.dumps({"data": [{"id": app.MINICPM_VISION_MODEL}]}).encode("utf-8")
+    models_response.__enter__ = lambda s: s
+    models_response.__exit__ = MagicMock(return_value=False)
+
+    with patch.object(app, "MINICPM_VISION_BASE_URL", "https://vision.example/v1"):
+        with patch.object(app, "MINICPM_VISION_API_KEY", "secret-key"):
+            with patch("urllib.request.urlopen", return_value=models_response):
+                status = app._vision_runtime_status()
+                assert_true(status["status"] == "online", "MiniCPM /models response should mark vision online")
+                assert_true("secret-key" not in json.dumps(status), "Vision runtime status should not expose API key")
+
+    setup = app.runtime_setup_core()
+    vision_step = next(step for step in setup["steps"] if step["role"] == "vision")
+    assert_true("MiniCPM-V-4.6" in vision_step["model"], "Runtime setup should document MiniCPM-V-4.6")
+    assert_true("MINICPM_VISION_BASE_URL" in vision_step["env"], "Runtime setup should document MiniCPM base URL")
+    assert_true("secret" not in json.dumps(vision_step).lower(), "Runtime setup should not expose MiniCPM API key")
+
+
 def verify_output_retention() -> None:
     keep_path = app.OUTPUT_DIR / "speech-retention-keep.wav"
     _ = app.speak_core("Tiny Narrator retention check.", voice="af_heart", speed=1.0)
@@ -540,8 +752,8 @@ def verify_routes() -> None:
     )
     assert_true(evidence_payload["runtime_status"]["ok"], "Evidence bundle should include ok runtime status")
     assert_true(
-        {"reader_brain", "speech"} <= set(evidence_payload["runtime_status"]),
-        "Evidence bundle runtime status should include reader brain and speech status",
+        {"reader_brain", "speech", "image_generation"} <= set(evidence_payload["runtime_status"]),
+        "Evidence bundle runtime status should include reader brain, speech, and image generation status",
     )
     assert_true(
         evidence_payload["runtime_status"]["reader_brain"]["status"] in {"online", "fallback-ready"},
@@ -551,6 +763,10 @@ def verify_routes() -> None:
         evidence_payload["runtime_status"]["speech"]["status"] in {"online", "fallback-ready"},
         "Evidence bundle speech status should be online or fallback-ready",
     )
+    assert_true(
+        evidence_payload["runtime_status"]["image_generation"]["status"] in {"online", "fallback-ready"},
+        "Evidence bundle image generation status should be online or fallback-ready",
+    )
 
     runtime = client.get("/api/runtime-status")
     assert_true(runtime.status_code == 200, "Runtime status route should return 200")
@@ -558,15 +774,25 @@ def verify_routes() -> None:
     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("image_generation" in runtime_payload, "Runtime status should include image generation status")
     assert_true(
         runtime_payload["reader_brain"]["status"] in {"online", "fallback-ready"},
         "Reader brain status should be online or fallback-ready",
     )
+    assert_true(
+        runtime_payload["image_generation"]["status"] in {"online", "fallback-ready"},
+        "Image generation status should be online or fallback-ready",
+    )
+    assert_true(
+        runtime_payload["image_generation"]["model"] == app.MODEL_MANIFEST["image_generation"]["id"],
+        "Image generation status should reference the Klein model",
+    )
 
     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()
-    assert_true(image_payload["model"] == "OpenBMB MiniCPM-V-2", "Image route should document MiniCPM-V model")
+    assert_true(image_payload["model"] == app.MODEL_MANIFEST["vision"]["id"], "Image route should document MiniCPM-V model")
+    assert_true(image_payload["runtime"] == "fallback", "Image route should use fallback runtime without MiniCPM config")
     assert_true(
         {item["id"] for item in image_payload["descriptions"]} == {"desk-reader", "model-map"},
         "Image route should describe all visible article images",
@@ -580,12 +806,24 @@ def verify_routes() -> None:
         "Image route should label bundled image fallback status",
     )
 
+    # Verify generate-image endpoint returns fallback when Modal is not configured
+    gen_image = client.post("/api/generate-image", json={"prompt": "test thumbnail", "seed": 7})
+    assert_true(gen_image.status_code == 200, "Generate image route should return 200")
+    gen_image_payload = gen_image.json()
+    assert_true(gen_image_payload["ok"], "Generate image payload should be ok")
+    assert_true(gen_image_payload["model"] == app.MODEL_MANIFEST["image_generation"]["id"], "Generate image should report Klein model")
+    assert_true(gen_image_payload["runtime"] == "fallback", "Generate image without Modal should report fallback")
+    assert_true(isinstance(gen_image_payload["elapsed_ms"], int), "Generate image should include elapsed_ms")
+
 
 def main() -> None:
     py_compile.compile(str(ROOT / "app.py"), doraise=True)
+    py_compile.compile(str(ROOT / "modal_workers" / "klein_image.py"), doraise=True)
     verify_static_assets()
     verify_space_metadata()
     verify_core_fallbacks()
+    verify_modal_klein_integration()
+    verify_minicpm_vision_integration()
     verify_output_retention()
     verify_routes()
     print("Tiny Narrator verification passed.")