Use real Modal analysis path

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

.env.example

@@ -4,6 +4,7 @@
 
 INFERENCE_BACKEND=modal
 MODAL_ANALYZE_URL=
+# Optional compatibility value; scene descriptors are generated locally.
 MODAL_GENERATE_URL=
-INFERENCE_TIMEOUT_SECONDS=240
+INFERENCE_TIMEOUT_SECONDS=300
 SNAP2SIM_API_TOKEN=

AGENTS.md

@@ -209,9 +209,53 @@ technical cutaway animation.
   `/analyze_image` returned a validated mechanism payload through the secured
   Modal bearer-token flow, and `/generate_scene` returned
   `{ "renderer": "three", "analysis": ... }` with no HTML field.
+- Implemented the `REVIEW2.md` local code pass on June 14, 2026: fixed the
+  label-overlay pointer-events bug that blocked OrbitControls, added bounded
+  camera controls plus Reset view and orbit/zoom hint, changed the source-photo
+  preview to a stable contained image box, added optional normalized per-part
+  `annotation` fields, added `render_mode` scene descriptors, and added a
+  browser-side annotated-photo fallback plus an honest unavailable state.
+- Updated model prompting/parsing for longer reasoning: prompts may allow
+  reasoning before the final JSON, parser strips `<think>` blocks and prefers
+  the last complete JSON object, and llama.cpp analysis now uses larger
+  token/context/timeout budgets (`4096` output tokens, `8192` context, `300s`
+  timeout at the analysis call site).
+- Local verification after the `REVIEW2.md` pass: schema/parser checks passed,
+  FastAPI `TestClient` confirmed `/`, `/analyze_image`, and `/generate_scene`,
+  and browser verification confirmed left-drag orbit, right-drag pan, wheel
+  zoom, mobile canvas event targeting, contained source preview, annotated-photo
+  fallback, and unavailable retry state.
+- Modal reasoning-budget follow-up on June 14, 2026: an initial
+  `run_analysis_endpoint_check` returned a generic fallback, so a local-only
+  `run_analysis_raw_check` diagnostic was added. The raw diagnostic showed the
+  model used schema-adjacent fields (`radius`, `height`, string axes). The
+  prompt now explicitly requires `size` vectors and numeric axis vectors, and
+  coercion preserves common radius/height/length/axis-string mistakes instead
+  of accepting nested JSON fragments as generic fallbacks. After the fix,
+  `run_analysis_raw_check` parsed strict JSON successfully in `35.12s`, and
+  `run_analysis_endpoint_check` returned a parsed per-image `targeting reticle`
+  payload at `0.7` confidence.
+- User decision after the `REVIEW2.md` pass: use the real Modal
+  `analyze_image_llamacpp` analysis path for the demo. `INFERENCE_BACKEND` now
+  defaults to `modal`; `INFERENCE_BACKEND=local` is an explicit UI-development
+  sample mode only and should not be used for public submission.
+- Deployed the updated Modal app after the real-analysis decision on June 14,
+  2026. The stable deployment exposes `analyze_image_llamacpp` with the latest
+  prompt/parsing/coercion fixes. A lightweight deployed `runtime_probe` request
+  without credentials returned `401 Unauthorized`. Authenticated deployed web
+  verification could not be run from the local shell because
+  `SNAP2SIM_API_TOKEN` was not set locally; use the Hugging Face Space secret or
+  a local secret store for the normal authenticated check.
 
 ## Next Work
 
+- Deploy/sync the latest GitHub changes through the normal GitHub-to-Hugging
+  Face workflow, then re-run authenticated private Space verification. Do not
+  edit files directly on the Hugging Face Space.
+- Measure the larger llama.cpp reasoning budget with representative real photos;
+  tune token/context/timeout values down if valid JSON remains reliable with
+  lower latency. The synthetic Modal check now succeeds with the current
+  `4096` output token, `8192` context, `300s` timeout settings.
 - Optional polish only after private deployment verification: component
   watermark, noise texture, vignette, then scan-line reveal refinements.
 - Keep the Hugging Face Space private until the user explicitly approves making

README.md

@@ -18,9 +18,10 @@ structured mechanism analysis, and renders an animated technical cutaway
 visualization.
 
 The local app serves a trusted `index.html` shell through `gradio.Server` and
-exposes `/analyze_image` plus a compatibility `/generate_scene` route. It still
-defaults to the placeholder backend locally, while the Modal llama.cpp analysis
-path has been smoke-tested with the selected Nemotron GGUF and projector.
+exposes `/analyze_image` plus a compatibility `/generate_scene` route. The demo
+path uses the real Modal llama.cpp analysis endpoint by default; the fixed local
+sample backend is available only when `INFERENCE_BACKEND=local` is explicitly
+set for development.
 
 ## Run Locally
 
@@ -29,9 +30,14 @@ pip install -r requirements.txt
 python app.py
 ```
 
-Set `INFERENCE_BACKEND=modal`, `MODAL_ANALYZE_URL`, and `MODAL_GENERATE_URL`
-to point the Gradio app at deployed Modal `/analyze_image` and
-`/generate_scene` endpoints.
+Set `INFERENCE_BACKEND=modal`, `MODAL_ANALYZE_URL`, and `SNAP2SIM_API_TOKEN`
+to point the Gradio app at the deployed Modal `analyze_image_llamacpp`
+endpoint. `/generate_scene` is deterministic in the Space process and returns a
+validated scene descriptor.
+
+For quick UI-only development without Modal, explicitly set
+`INFERENCE_BACKEND=local`. That mode returns a sample mechanism and should not
+be used for the public demo.
 
 For the deployed demo configuration, copy `.env.example` into local environment
 variables or Hugging Face Space variables. Do not put tokens in `.env.example`;
@@ -117,10 +123,13 @@ Runtime flow:
 
 1. Browser encodes the uploaded photo and posts it to `/analyze_image`.
 2. Backend returns the validated mechanism JSON.
-3. Browser renders the cutaway directly from that JSON with deterministic
-   Three.js primitives.
-4. `/generate_scene` remains as a compatibility endpoint, but it returns a
-   validated `{ "renderer": "three", "analysis": ... }` scene descriptor
+3. Browser posts the analysis to `/generate_scene` for a validated scene
+   descriptor.
+4. Browser renders deterministic Three.js primitives when geometry is usable,
+   or overlays text-only callouts on the uploaded photo when the model only has
+   image-space annotations.
+5. `/generate_scene` returns a validated
+   `{ "renderer": "...", "render_mode": "...", "analysis": ... }` descriptor
    instead of model-authored HTML.
 
 The shell uses Chakra Petch and Fira Code from Bunny Fonts, an asymmetric
@@ -133,8 +142,8 @@ job is limited to the structured analysis JSON contract in `snap2sim/schema.py`.
 
 ## Modal Deployment Path
 
-The Modal app defaults to placeholder inference so endpoint wiring can be tested
-without loading a 30B model:
+Deploy the Modal app before wiring a public demo so the llama.cpp endpoint uses
+the current prompt, parsing, and coercion code:
 
 ```powershell
 python -m modal deploy modal_app.py
@@ -160,8 +169,9 @@ Useful deployment functions/endpoints:
 - `run_analysis_endpoint_check` calls the real llama.cpp analysis task with a
   synthetic image and confirms it returns a validated mechanism payload.
 - `runtime_probe` reports the configured model repo, quant, projector file, and
-  whether placeholder inference is still active.
-- `analyze_image` preserves the HTTP contract for the Gradio app.
+  whether placeholder inference is active on the compatibility endpoint.
+- `analyze_image` preserves the HTTP contract for old wiring, but the demo
+  should use `analyze_image_llamacpp`.
 - `generate_scene` and `generate_scene_llamacpp` are compatibility endpoints
   that return the deterministic Three.js scene descriptor.
 - `analyze_image_llamacpp` is the experimental GPU endpoint for the llama.cpp
@@ -177,9 +187,10 @@ Runtime environment knobs:
 - `SNAP2SIM_SMOKE_GPU`, default `L40S`
 - `SNAP2SIM_RUNTIME_GPU`, default `L40S`
 
-Keep `SNAP2SIM_RUNTIME_MODE=placeholder` for the public demo unless you point
-`MODAL_ANALYZE_URL` at the validated `analyze_image_llamacpp` endpoint. The
-browser renders scenes deterministically from the validated analysis JSON.
+For the public demo, point `MODAL_ANALYZE_URL` at the validated
+`analyze_image_llamacpp` endpoint. `SNAP2SIM_RUNTIME_MODE=placeholder` can stay
+set because only the legacy `analyze_image` compatibility endpoint reads it.
+The browser renders scenes deterministically from the validated analysis JSON.
 
 Run the deployment preflight in this order:
 
@@ -215,8 +226,8 @@ The Space is configured as a Gradio SDK app with these variables:
 ```text
 INFERENCE_BACKEND=modal
 MODAL_ANALYZE_URL=<stored in Hugging Face Space variables>
-MODAL_GENERATE_URL=<stored in Hugging Face Space variables>
-INFERENCE_TIMEOUT_SECONDS=240
+MODAL_GENERATE_URL=<optional compatibility value>
+INFERENCE_TIMEOUT_SECONDS=300
 ```
 
 The Space also needs `SNAP2SIM_API_TOKEN` as a Hugging Face Space secret. The

index.html

@@ -166,6 +166,7 @@
       top: 18px;
       z-index: 10;
       display: flex;
+      flex-wrap: wrap;
       gap: 8px;
     }
 
@@ -193,6 +194,25 @@
       cursor: default;
     }
 
+    .viewport-hint {
+      position: absolute;
+      left: 18px;
+      bottom: 18px;
+      z-index: 10;
+      max-width: min(320px, calc(100% - 36px));
+      border-left: 1px solid var(--cyan-dim);
+      padding: 6px 0 6px 10px;
+      color: var(--text-muted);
+      background: rgba(15, 19, 24, 0.78);
+      font: 0.78rem/1.3 "Fira Code", monospace;
+      text-transform: uppercase;
+      pointer-events: none;
+    }
+
+    .viewport-hint[hidden] {
+      display: none;
+    }
+
     .panel {
       min-width: 0;
       overflow: auto;
@@ -274,8 +294,8 @@
 
     .source-image {
       width: 100%;
-      max-height: 150px;
-      object-fit: cover;
+      height: 180px;
+      object-fit: contain;
       border: 1px solid rgba(122, 84, 32, 0.72);
       background: var(--bg);
     }
@@ -374,6 +394,64 @@
       pointer-events: none;
     }
 
+    .label-layer {
+      pointer-events: none;
+    }
+
+    .annotated-stage {
+      display: grid;
+      place-items: center;
+      padding: 58px 18px 44px;
+      background: rgba(15, 19, 24, 0.72);
+    }
+
+    .annotation-frame {
+      position: relative;
+      width: 100%;
+      height: 100%;
+      display: grid;
+      place-items: center;
+    }
+
+    .annotation-image {
+      width: 100%;
+      height: 100%;
+      object-fit: contain;
+      border: 1px solid rgba(122, 84, 32, 0.72);
+      background: var(--bg);
+    }
+
+    .photo-label {
+      max-width: min(220px, 42vw);
+      white-space: normal;
+      text-transform: none;
+    }
+
+    .label-title {
+      display: block;
+      color: var(--cyan);
+      text-transform: uppercase;
+    }
+
+    .label-note {
+      display: block;
+      color: var(--text);
+      margin-top: 2px;
+    }
+
+    .empty-state {
+      position: absolute;
+      inset: 18px;
+      display: grid;
+      place-items: center;
+      border: 1px dashed var(--danger);
+      color: var(--danger);
+      background: rgba(15, 19, 24, 0.72);
+      text-align: center;
+      text-transform: uppercase;
+      font-weight: 600;
+    }
+
     @keyframes loading {
       from { transform: translateX(-100%); }
       to { transform: translateX(300%); }
@@ -401,6 +479,10 @@
         border-left: 0;
         border-top: 1px solid var(--amber-dim);
       }
+
+      .source-image {
+        height: 220px;
+      }
     }
   </style>
 </head>
@@ -411,8 +493,10 @@
       <div class="toolbar">
         <button id="uploadButton" class="tool-button" type="button">Load</button>
         <button id="playButton" class="tool-button" type="button" disabled>Play</button>
+        <button id="resetViewButton" class="tool-button" type="button" disabled>Reset view</button>
       </div>
       <div id="viewport" aria-hidden="true"></div>
+      <div id="viewportHint" class="viewport-hint" hidden>Drag to orbit / scroll to zoom</div>
       <label id="dropZone" class="drop-zone" for="fileInput" tabindex="0">Drop component photo</label>
       <div id="scanLine" class="scan-line"></div>
       <input id="fileInput" type="file" accept="image/*" capture="environment" hidden>
@@ -461,8 +545,10 @@
     const fileInput = document.getElementById("fileInput");
     const uploadButton = document.getElementById("uploadButton");
     const playButton = document.getElementById("playButton");
+    const resetViewButton = document.getElementById("resetViewButton");
     const dropZone = document.getElementById("dropZone");
     const viewport = document.getElementById("viewport");
+    const viewportHint = document.getElementById("viewportHint");
     const progress = document.getElementById("progress");
     const scanLine = document.getElementById("scanLine");
     const statusEl = document.getElementById("status");
@@ -522,6 +608,9 @@
       playButton.textContent = paused ? "Resume" : "Pause";
       if (fallbackRuntime) fallbackRuntime.playing = !paused;
     });
+    resetViewButton.addEventListener("click", () => {
+      if (fallbackRuntime && fallbackRuntime.resetView) fallbackRuntime.resetView();
+    });
 
     async function runPipeline(file) {
       const validationError = validateFile(file);
@@ -545,13 +634,13 @@
         populateAnalysis(analysis);
 
         setStatus("RENDERING CUTAWAY...");
-        buildDeterministicScene(analysis);
+        const scenePayload = await postJson("/generate_scene", { analysis });
+        renderScenePayload(scenePayload);
       } catch (error) {
         window.clearTimeout(coldStartTimer);
         setStatus(error.message || String(error), true);
         retryButton.hidden = false;
         dropZone.classList.remove("hidden");
-        if (window.lastAnalysis) buildDeterministicScene(window.lastAnalysis);
       } finally {
         setBusy(false);
       }
@@ -564,6 +653,8 @@
       paused = false;
       playButton.textContent = "Play";
       playButton.disabled = true;
+      resetViewButton.disabled = true;
+      viewportHint.hidden = true;
       retryButton.hidden = true;
       viewport.replaceChildren();
       dropZone.classList.add("hidden");
@@ -594,6 +685,55 @@
       }));
     }
 
+    function renderScenePayload(payload) {
+      const analysis = payload && payload.analysis ? payload.analysis : payload;
+      const renderMode = payload && payload.render_mode ? payload.render_mode : chooseRenderMode(analysis);
+      if (renderMode === "three" && hasUsableGeometry(analysis)) {
+        buildDeterministicScene(analysis);
+      } else if (renderMode === "annotate" && hasAnnotations(analysis)) {
+        buildAnnotatedPhoto(analysis);
+      } else {
+        buildUnavailableScene();
+      }
+    }
+
+    function chooseRenderMode(analysis) {
+      const confidence = typeof analysis.confidence === "number" ? analysis.confidence : 1;
+      if (hasAnnotations(analysis) && (confidence < 0.5 || !hasUsableGeometry(analysis))) {
+        return "annotate";
+      }
+      if (hasUsableGeometry(analysis) && confidence >= 0.5) {
+        return "three";
+      }
+      if (hasAnnotations(analysis)) {
+        return "annotate";
+      }
+      return "unavailable";
+    }
+
+    function hasUsableGeometry(analysis) {
+      return Boolean(analysis && Array.isArray(analysis.parts) && analysis.parts.some((part) => {
+        const geometry = part && part.geometry;
+        return geometry
+          && ["box", "cylinder", "sphere", "gear", "rod"].includes(geometry.shape)
+          && isNumberList(geometry.size, 3)
+          && isNumberList(geometry.position, 3);
+      }));
+    }
+
+    function hasAnnotations(analysis) {
+      return Boolean(analysis && Array.isArray(analysis.parts) && analysis.parts.some((part) => {
+        const point = part && part.annotation && part.annotation.point;
+        return isNumberList(point, 2);
+      }));
+    }
+
+    function isNumberList(value, length) {
+      return Array.isArray(value)
+        && value.length === length
+        && value.every((item) => typeof item === "number" && Number.isFinite(item));
+    }
+
     function buildDeterministicScene(analysis) {
       const threeRuntime = window.THREE;
       if (!threeRuntime) {
@@ -607,6 +747,8 @@
       paused = false;
       playButton.textContent = "Pause";
       playButton.disabled = false;
+      resetViewButton.disabled = false;
+      viewportHint.hidden = false;
       viewport.replaceChildren();
       const stage = document.createElement("div");
       stage.className = "fallback-stage";
@@ -619,20 +761,34 @@
 
       const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
       renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
+      renderer.domElement.style.touchAction = "none";
       mount.appendChild(renderer.domElement);
 
       const scene = new THREE.Scene();
       scene.fog = new THREE.Fog(0x0f1318, 8, 20);
 
       const camera = new THREE.PerspectiveCamera(42, 1, 0.1, 100);
-      camera.position.set(5.4, 3.9, 6.2);
+      const defaultCameraPosition = new THREE.Vector3(5.4, 3.9, 6.2);
+      const defaultTarget = new THREE.Vector3(0, 0.1, 0);
+      camera.position.copy(defaultCameraPosition);
 
       const controls = window.THREE.OrbitControls
         ? new THREE.OrbitControls(camera, renderer.domElement)
         : null;
       if (controls) {
         controls.enableDamping = true;
-        controls.target.set(0, 0.1, 0);
+        controls.minDistance = 2.4;
+        controls.maxDistance = 12;
+        controls.maxPolarAngle = Math.PI * 0.48;
+        controls.target.copy(defaultTarget);
+        if (window.THREE.TOUCH) {
+          controls.touches = {
+            ONE: THREE.TOUCH.ROTATE,
+            TWO: THREE.TOUCH.DOLLY_PAN
+          };
+        }
+        controls.update();
+        controls.saveState();
       }
 
       scene.add(new THREE.HemisphereLight(0x5fd4d0, 0x0f1318, 1.2));
@@ -665,6 +821,13 @@
       let disposed = false;
       fallbackRuntime = {
         playing: true,
+        resetView() {
+          camera.position.copy(defaultCameraPosition);
+          if (controls) {
+            controls.target.copy(defaultTarget);
+            controls.update();
+          }
+        },
         cleanup() {
           disposed = true;
           cancelAnimationFrame(frameId);
@@ -705,6 +868,133 @@
       setStatus("CUTAWAY READY");
     }
 
+    function buildAnnotatedPhoto(analysis) {
+      if (!currentPreviewUrl) {
+        buildUnavailableScene();
+        return;
+      }
+      if (fallbackRuntime && fallbackRuntime.cleanup) fallbackRuntime.cleanup();
+      activeMode = "annotate";
+      paused = true;
+      playButton.textContent = "Play";
+      playButton.disabled = true;
+      resetViewButton.disabled = true;
+      viewportHint.hidden = true;
+      viewport.replaceChildren();
+
+      const stage = document.createElement("div");
+      stage.className = "fallback-stage annotated-stage";
+      const frame = document.createElement("div");
+      frame.className = "annotation-frame";
+      const image = document.createElement("img");
+      image.className = "annotation-image";
+      image.alt = "";
+      image.src = currentPreviewUrl;
+      const labelLayer = document.createElement("div");
+      labelLayer.className = "label-layer";
+      frame.append(image, labelLayer);
+      stage.append(frame);
+      viewport.append(stage);
+
+      let disposed = false;
+      const annotatedParts = (analysis.parts || []).filter((part) => {
+        const point = part && part.annotation && part.annotation.point;
+        return isNumberList(point, 2);
+      });
+
+      function updatePhotoLabels() {
+        if (disposed) return;
+        const imageRect = containedImageRect(image);
+        const layerRect = labelLayer.getBoundingClientRect();
+        labelLayer.replaceChildren(...annotatedParts.map((part, index) => {
+          const annotation = part.annotation || {};
+          const point = annotation.point || [0.5, 0.5];
+          const label = document.createElement("div");
+          label.className = "scene-label photo-label";
+          label.style.left = Math.min(
+            layerRect.width - 72,
+            Math.max(72, imageRect.left - layerRect.left + clamp01(point[0]) * imageRect.width)
+          ) + "px";
+          label.style.top = Math.min(
+            layerRect.height - 36,
+            Math.max(56, imageRect.top - layerRect.top + clamp01(point[1]) * imageRect.height)
+          ) + "px";
+
+          const title = document.createElement("span");
+          title.className = "label-title";
+          title.textContent = (index + 1) + ". " + (annotation.label || part.name || part.id || "part");
+          label.append(title);
+          const noteText = annotation.note || part.role || "";
+          if (noteText) {
+            const note = document.createElement("span");
+            note.className = "label-note";
+            note.textContent = noteText;
+            label.append(note);
+          }
+          return label;
+        }));
+      }
+
+      image.addEventListener("load", updatePhotoLabels, { once: true });
+      window.addEventListener("resize", updatePhotoLabels);
+      fallbackRuntime = {
+        playing: false,
+        cleanup() {
+          disposed = true;
+          window.removeEventListener("resize", updatePhotoLabels);
+        }
+      };
+      window.requestAnimationFrame(updatePhotoLabels);
+      revealScan();
+      setStatus("ANNOTATED PHOTO READY");
+    }
+
+    function buildUnavailableScene() {
+      if (fallbackRuntime && fallbackRuntime.cleanup) fallbackRuntime.cleanup();
+      fallbackRuntime = null;
+      activeMode = "unavailable";
+      paused = true;
+      playButton.textContent = "Play";
+      playButton.disabled = true;
+      resetViewButton.disabled = true;
+      viewportHint.hidden = true;
+      viewport.replaceChildren();
+      const empty = document.createElement("div");
+      empty.className = "empty-state";
+      empty.textContent = "Could not analyze this photo. Try another angle.";
+      viewport.append(empty);
+      retryButton.hidden = false;
+      setStatus("COULD NOT ANALYZE", true);
+    }
+
+    function containedImageRect(image) {
+      const rect = image.getBoundingClientRect();
+      const naturalWidth = image.naturalWidth || rect.width || 1;
+      const naturalHeight = image.naturalHeight || rect.height || 1;
+      const rectAspect = rect.width / Math.max(1, rect.height);
+      const imageAspect = naturalWidth / Math.max(1, naturalHeight);
+      if (rectAspect > imageAspect) {
+        const width = rect.height * imageAspect;
+        return {
+          left: rect.left + (rect.width - width) / 2,
+          top: rect.top,
+          width,
+          height: rect.height
+        };
+      }
+      const height = rect.width / imageAspect;
+      return {
+        left: rect.left,
+        top: rect.top + (rect.height - height) / 2,
+        width: rect.width,
+        height
+      };
+    }
+
+    function clamp01(value) {
+      return Math.max(0, Math.min(1, Number(value) || 0));
+    }
+
     function validateFile(file) {
       if (!file.type || !file.type.startsWith("image/")) {
         return "Upload an image file.";

modal_app.py

@@ -18,7 +18,7 @@ from fastapi import Header, HTTPException
 
 from snap2sim.model_io import coerce_analysis_response, parse_analysis_response
 from snap2sim.prompts import build_vision_prompt
-from snap2sim.schema import EXAMPLE_ANALYSIS, validate_analysis
+from snap2sim.schema import EXAMPLE_ANALYSIS, select_render_mode, validate_analysis
 
 
 DEFAULT_MODEL_REPO = "unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF"
@@ -244,6 +244,8 @@ def smoke_test_llamacpp_image() -> dict[str, Any]:
         prompt,
         "-n",
         "1024",
+        "-c",
+        "4096",
         "--temp",
         "0.2",
     ]
@@ -289,8 +291,9 @@ def smoke_test_llamacpp_image() -> dict[str, Any]:
 def run_llamacpp_prompt(
     prompt: str,
     image_path: Path | None = None,
-    max_tokens: int = 1024,
-    timeout_seconds: int = 180,
+    max_tokens: int = 3072,
+    timeout_seconds: int = 300,
+    ctx_size: int = 8192,
 ) -> str:
     """Run one prompt through the llama.cpp multimodal CLI."""
     import subprocess
@@ -306,6 +309,8 @@ def run_llamacpp_prompt(
         prompt,
         "-n",
         str(max_tokens),
+        "-c",
+        str(ctx_size),
         "--temp",
         "0.2",
     ]
@@ -383,8 +388,9 @@ def analyze_image_llamacpp_payload(payload: dict[str, Any]) -> dict[str, Any]:
         response = run_llamacpp_prompt(
             build_vision_prompt(),
             image_path=image_path,
-            max_tokens=1536,
-            timeout_seconds=180,
+            max_tokens=4096,
+            timeout_seconds=300,
+            ctx_size=8192,
         )
         try:
             return parse_analysis_response(response)
@@ -432,6 +438,28 @@ def run_analysis_endpoint_check() -> None:
     print(json.dumps(result, indent=2))
 
 
+@app.local_entrypoint()
+def run_analysis_raw_check() -> None:
+    """Print raw llama.cpp analysis output diagnostics for prompt tuning."""
+    import base64
+    import json
+    from io import BytesIO
+
+    from PIL import Image, ImageDraw
+
+    img = Image.new("RGB", (512, 384), "#d8d0bd")
+    draw = ImageDraw.Draw(img)
+    draw.rectangle((82, 96, 430, 288), outline="#2c3138", width=8)
+    draw.ellipse((178, 112, 334, 268), outline="#b06c23", width=14)
+    draw.line((256, 112, 256, 268), fill="#2c3138", width=6)
+    draw.line((178, 190, 334, 190), fill="#2c3138", width=6)
+    buffer = BytesIO()
+    img.save(buffer, format="JPEG", quality=92)
+    payload = {"image_base64": base64.b64encode(buffer.getvalue()).decode("ascii")}
+    result = analyze_image_llamacpp_raw_task.remote(payload)
+    print(json.dumps(result, indent=2))
+
+
 @app.function(image=image, timeout=120, secrets=[api_auth_secret])
 @modal.fastapi_endpoint(method="GET")
 def runtime_probe(authorization: str = Header(default="")) -> dict[str, Any]:
@@ -473,6 +501,44 @@ def analyze_image_llamacpp_task(payload: dict[str, Any]) -> dict[str, Any]:
     return analyze_image_llamacpp_payload(payload)
 
 
+@app.function(image=llamacpp_image, gpu=os.getenv("SNAP2SIM_RUNTIME_GPU", "L40S"), volumes={CACHE_DIR: model_cache}, timeout=60 * 60)
+def analyze_image_llamacpp_raw_task(payload: dict[str, Any]) -> dict[str, Any]:
+    """Remote-callable diagnostic task for prompt and budget tuning."""
+    import time
+
+    image_path = write_payload_image(payload)
+    start = time.monotonic()
+    try:
+        response = run_llamacpp_prompt(
+            build_vision_prompt(),
+            image_path=image_path,
+            max_tokens=4096,
+            timeout_seconds=300,
+            ctx_size=8192,
+        )
+    finally:
+        image_path.unlink(missing_ok=True)
+
+    elapsed_seconds = round(time.monotonic() - start, 2)
+    parse_error = ""
+    parsed: dict[str, Any] | None = None
+    try:
+        parsed = parse_analysis_response(response)
+    except Exception as exc:
+        parse_error = str(exc)
+    coerced = coerce_analysis_response(response)
+    return {
+        "elapsed_seconds": elapsed_seconds,
+        "parse_ok": parsed is not None,
+        "parse_error": parse_error,
+        "parsed_component": parsed["component"] if parsed else "",
+        "coerced_component": coerced["component"],
+        "coerced_render_mode": select_render_mode(coerced),
+        "coerced_confidence": coerced.get("confidence"),
+        "stdout_tail": response[-4000:],
+    }
+
+
 @app.function(image=llamacpp_image, gpu=os.getenv("SNAP2SIM_RUNTIME_GPU", "L40S"), volumes={CACHE_DIR: model_cache}, timeout=60 * 60, secrets=[api_auth_secret])
 @modal.fastapi_endpoint(method="POST")
 def analyze_image_llamacpp(payload: dict[str, Any], authorization: str = Header(default="")) -> dict[str, Any]:
@@ -490,7 +556,9 @@ def generate_scene(payload: dict[str, Any], authorization: str = Header(default=
         raise NotImplementedError(
             "Scene generation is deterministic in the browser from validated JSON."
         )
-    return {"renderer": "three", "analysis": analysis}
+    render_mode = select_render_mode(analysis)
+    renderer = "three" if render_mode == "three" else "photo"
+    return {"renderer": renderer, "render_mode": render_mode, "analysis": analysis}
 
 
 @app.function(image=llamacpp_image, gpu=os.getenv("SNAP2SIM_RUNTIME_GPU", "L40S"), volumes={CACHE_DIR: model_cache}, timeout=60 * 60, secrets=[api_auth_secret])
@@ -499,4 +567,6 @@ def generate_scene_llamacpp(payload: dict[str, Any], authorization: str = Header
     """Compatibility endpoint; scene rendering is deterministic browser-side."""
     require_authorization(authorization)
     analysis = validate_analysis(payload.get("analysis") or EXAMPLE_ANALYSIS)
-    return {"renderer": "three", "analysis": analysis}
+    render_mode = select_render_mode(analysis)
+    renderer = "three" if render_mode == "three" else "photo"
+    return {"renderer": renderer, "render_mode": render_mode, "analysis": analysis}

snap2sim/backend.py

@@ -1,4 +1,4 @@
-"""Backend client and local placeholder inference."""
+"""Backend client for Modal inference with explicit local sample mode."""
 
 from __future__ import annotations
 
@@ -11,16 +11,16 @@ from typing import Any
 import requests
 from PIL import Image
 
-from snap2sim.schema import EXAMPLE_ANALYSIS, validate_analysis
+from snap2sim.schema import EXAMPLE_ANALYSIS, select_render_mode, validate_analysis
 
 
 @dataclass(frozen=True)
 class Settings:
-    backend: str = os.getenv("INFERENCE_BACKEND", "local")
+    backend: str = os.getenv("INFERENCE_BACKEND", "modal")
     analyze_url: str = os.getenv("MODAL_ANALYZE_URL", "")
     generate_url: str = os.getenv("MODAL_GENERATE_URL", "")
     api_token: str = os.getenv("SNAP2SIM_API_TOKEN", "")
-    timeout_seconds: int = int(os.getenv("INFERENCE_TIMEOUT_SECONDS", "180"))
+    timeout_seconds: int = int(os.getenv("INFERENCE_TIMEOUT_SECONDS", "300"))
 
 
 def encode_image(image: Image.Image) -> str:
@@ -46,7 +46,9 @@ class InferenceClient:
 
     def generate_scene(self, analysis: dict[str, Any]) -> dict[str, Any]:
         valid_analysis = validate_analysis(analysis)
-        return {"renderer": "three", "analysis": valid_analysis}
+        render_mode = select_render_mode(valid_analysis)
+        renderer = "three" if render_mode == "three" else "photo"
+        return {"renderer": renderer, "render_mode": render_mode, "analysis": valid_analysis}
 
     def _post_json(self, url: str, payload: dict[str, Any]) -> dict[str, Any]:
         if not url:

snap2sim/model_io.py

@@ -10,13 +10,14 @@ from snap2sim.schema import validate_analysis
 
 
 _FENCE_RE = re.compile(r"^```(?:json|html)?\s*|\s*```$", re.IGNORECASE)
+_THINK_RE = re.compile(r"<think\b[^>]*>.*?</think>", re.IGNORECASE | re.DOTALL)
 
 
 def parse_analysis_response(text: str) -> dict[str, Any]:
     """Extract and validate a JSON object from a model response."""
     raw = _strip_fences(text)
     errors: list[str] = []
-    for start, json_text in _json_object_candidates(raw):
+    for start, json_text in reversed(_json_object_candidates(raw)):
         try:
             payload = json.loads(json_text)
             return validate_analysis(payload)
@@ -32,13 +33,15 @@ def coerce_analysis_response(text: str) -> dict[str, Any]:
     """Best-effort conversion of partial model output into a valid analysis."""
     raw = _strip_fences(text)
     fallback_component = _infer_component(raw)
-    for _, json_text in _json_object_candidates(raw):
+    for _, json_text in reversed(_json_object_candidates(raw)):
         try:
             payload = json.loads(json_text)
         except json.JSONDecodeError:
             continue
         if not isinstance(payload, dict):
             continue
+        if not _looks_like_analysis_payload(payload):
+            continue
         try:
             return validate_analysis(_coerce_analysis_payload(payload, fallback_component))
         except ValueError:
@@ -47,7 +50,21 @@ def coerce_analysis_response(text: str) -> dict[str, Any]:
 
 
 def _strip_fences(text: str) -> str:
-    return _FENCE_RE.sub("", text.strip()).strip()
+    raw = _FENCE_RE.sub("", text.strip()).strip()
+    return _strip_reasoning(raw)
+
+
+def _strip_reasoning(text: str) -> str:
+    cleaned = _THINK_RE.sub("", text)
+    unclosed = re.search(r"<think\b[^>]*>", cleaned, re.IGNORECASE)
+    if unclosed:
+        after = cleaned[unclosed.end() :]
+        json_start = after.find("{")
+        if json_start >= 0:
+            cleaned = cleaned[: unclosed.start()] + after[json_start:]
+        else:
+            cleaned = cleaned[: unclosed.start()]
+    return cleaned.strip()
 
 
 def _json_object_candidates(text: str) -> list[tuple[int, str]]:
@@ -89,6 +106,10 @@ def _balanced_json_object(text: str, start: int) -> str:
     raise ValueError("Model response contained an unterminated JSON object.")
 
 
+def _looks_like_analysis_payload(payload: dict[str, Any]) -> bool:
+    return any(key in payload for key in ["component", "summary", "trigger", "motion_sequence", "parts"])
+
+
 def _coerce_analysis_payload(payload: dict[str, Any], fallback_component: str) -> dict[str, Any]:
     parts = payload.get("parts")
     if not isinstance(parts, list):
@@ -102,7 +123,7 @@ def _coerce_analysis_payload(payload: dict[str, Any], fallback_component: str) -
     if not isinstance(confidence, (int, float)) or isinstance(confidence, bool):
         confidence = 0.55
 
-    return {
+    result = {
         "component": _non_empty_string(payload.get("component"), fallback_component),
         "confidence": max(0.0, min(1.0, float(confidence))),
         "summary": _non_empty_string(
@@ -116,16 +137,31 @@ def _coerce_analysis_payload(payload: dict[str, Any], fallback_component: str) -
         ),
         "parts": coerced_parts,
     }
+    if payload.get("render_mode") in {"three", "annotate", "unavailable"}:
+        result["render_mode"] = payload["render_mode"]
+    return result
 
 
 def _coerce_part(part: dict[str, Any], index: int) -> dict[str, Any] | None:
+    annotation = _coerce_annotation(part.get("annotation"))
     geometry = part.get("geometry")
-    if not isinstance(geometry, dict):
+    has_geometry_input = isinstance(geometry, dict) and bool(geometry)
+    if not has_geometry_input:
         geometry = {}
     motion = part.get("motion")
     if not isinstance(motion, dict):
         motion = {}
 
+    base_part: dict[str, Any] = {
+        "id": _identifier(part.get("id"), f"part_{index + 1}"),
+        "name": _non_empty_string(part.get("name"), f"part {index + 1}"),
+        "role": _non_empty_string(part.get("role"), "inferred mechanical element"),
+    }
+    if annotation:
+        base_part["annotation"] = annotation
+    if annotation and not has_geometry_input:
+        return base_part
+
     shape = geometry.get("shape")
     if shape not in {"box", "cylinder", "sphere", "gear", "rod"}:
         shape = "box"
@@ -134,10 +170,9 @@ def _coerce_part(part: dict[str, Any], index: int) -> dict[str, Any] | None:
         motion_type = "static"
 
     coerced_motion: dict[str, Any] = {"type": motion_type}
-    for key in ["axis"]:
-        values = _number_list(motion.get(key), 3)
-        if values:
-            coerced_motion[key] = values
+    axis = _axis_vector(motion.get("axis"))
+    if axis:
+        coerced_motion["axis"] = axis
     for key in ["speed", "amplitude", "phase"]:
         if isinstance(motion.get(key), (int, float)) and not isinstance(motion.get(key), bool):
             coerced_motion[key] = float(motion[key])
@@ -147,7 +182,7 @@ def _coerce_part(part: dict[str, Any], index: int) -> dict[str, Any] | None:
 
     coerced_geometry: dict[str, Any] = {
         "shape": shape,
-        "size": _number_list(geometry.get("size"), 3) or [1.0, 0.4, 1.0],
+        "size": _geometry_size(geometry, shape),
         "position": _number_list(geometry.get("position"), 3) or [float(index) - 1.0, 0.0, 0.0],
     }
     values = _number_list(geometry.get("rotation"), 3)
@@ -158,13 +193,9 @@ def _coerce_part(part: dict[str, Any], index: int) -> dict[str, Any] | None:
     if isinstance(geometry.get("color"), str) and geometry["color"].strip():
         coerced_geometry["color"] = geometry["color"].strip()
 
-    return {
-        "id": _identifier(part.get("id"), f"part_{index + 1}"),
-        "name": _non_empty_string(part.get("name"), f"part {index + 1}"),
-        "role": _non_empty_string(part.get("role"), "inferred mechanical element"),
-        "geometry": coerced_geometry,
-        "motion": coerced_motion,
-    }
+    base_part["geometry"] = coerced_geometry
+    base_part["motion"] = coerced_motion
+    return base_part
 
 
 def _generic_analysis(component: str) -> dict[str, Any]:
@@ -235,6 +266,71 @@ def _number_list(value: Any, length: int) -> list[float] | None:
     return [float(item) for item in value]
 
 
+def _geometry_size(geometry: dict[str, Any], shape: str) -> list[float]:
+    size = _number_list(geometry.get("size"), 3)
+    if size:
+        return size
+
+    radius = _number_value(geometry.get("radius"))
+    height = _number_value(geometry.get("height"))
+    length = _number_value(geometry.get("length"))
+    width = _number_value(geometry.get("width"))
+    depth = _number_value(geometry.get("depth"))
+    if shape in {"cylinder", "gear"} and radius and height:
+        diameter = radius * 2
+        return [diameter, height, diameter]
+    if shape == "rod" and (length or height) and radius:
+        diameter = radius * 2
+        return [diameter, diameter, length or height or 1.0]
+    if width and height and depth:
+        return [width, height, depth]
+    return [1.0, 0.4, 1.0]
+
+
+def _axis_vector(value: Any) -> list[float] | None:
+    vector = _number_list(value, 3)
+    if vector:
+        return vector
+    if isinstance(value, str):
+        key = value.strip().lower()
+        if key == "x":
+            return [1.0, 0.0, 0.0]
+        if key == "y":
+            return [0.0, 1.0, 0.0]
+        if key == "z":
+            return [0.0, 0.0, 1.0]
+    return None
+
+
+def _number_value(value: Any) -> float | None:
+    if isinstance(value, (int, float)) and not isinstance(value, bool):
+        return float(value)
+    return None
+
+
+def _unit_number_list(value: Any, length: int) -> list[float] | None:
+    values = _number_list(value, length)
+    if not values or not all(0 <= item <= 1 for item in values):
+        return None
+    return values
+
+
+def _coerce_annotation(value: Any) -> dict[str, Any] | None:
+    if not isinstance(value, dict):
+        return None
+    point = _unit_number_list(value.get("point"), 2)
+    if not point:
+        return None
+    annotation: dict[str, Any] = {"point": point}
+    box = _unit_number_list(value.get("box"), 4)
+    if box:
+        annotation["box"] = box
+    for key in ["label", "note"]:
+        if isinstance(value.get(key), str) and value[key].strip():
+            annotation[key] = value[key].strip()
+    return annotation
+
+
 def _identifier(value: Any, fallback: str) -> str:
     text = _non_empty_string(value, fallback).lower()
     text = re.sub(r"[^a-z0-9_]+", "_", text).strip("_")

snap2sim/prompts.py

@@ -6,21 +6,32 @@ VISION_SYSTEM_PROMPT = """You are a mechanical teardown analyst.
 Given an image of a hardware component, infer the most likely internal
 mechanism and return only JSON matching the provided schema. Prefer clear,
 physically plausible primitive geometry over speculative detail. If the photo is
-ambiguous, state lower confidence and model the most likely mechanism."""
+ambiguous, state lower confidence and identify visible components with photo
+annotations instead of forcing a speculative 3D mechanism."""
 
 
 def build_vision_prompt() -> str:
     return (
         "Analyze the uploaded hardware component as a cutaway mechanism. "
-        "Answer with only one JSON object. Do not include markdown. Do not "
-        "include a reasoning trace or <think> tags. Keep the payload compact and physically "
-        "plausible for primitive Three.js rendering.\n\n"
+        "You may reason first if needed, but the final answer must be one JSON "
+        "object. Do not include markdown. Keep the final payload compact and "
+        "physically plausible for primitive Three.js rendering.\n\n"
         "Required top-level keys: component, confidence, summary, trigger, "
-        "motion_sequence, parts.\n"
-        "Each part requires: id, name, role, geometry, motion.\n"
+        "motion_sequence, parts. Optional top-level render_mode is three, "
+        "annotate, or unavailable.\n"
+        "Each part requires: id, name, role, and either geometry plus motion, "
+        "or annotation when the visible component can be located but 3D "
+        "geometry is uncertain.\n"
         "Allowed geometry.shape values: box, cylinder, sphere, gear, rod.\n"
-        "Allowed motion.type values: rotate, translate, oscillate, static.\n\n"
-        "Use 2 to 4 parts. Keep names and descriptions short.\n\n"
+        "Allowed motion.type values: rotate, translate, oscillate, static.\n"
+        "Every geometry must use size: [x, y, z] and position: [x, y, z]. "
+        "Do not use radius, height, length, width, or depth fields. Every "
+        "motion axis must be a numeric vector such as [0, 1, 0], never a string "
+        "like x, y, or z.\n\n"
+        "Use 2 to 4 parts. Keep names and descriptions short. When possible, "
+        "include annotation.point in normalized image coordinates [x, y] with "
+        "origin at top-left, plus a short annotation.note. Optional "
+        "annotation.box is [x, y, width, height], also normalized from 0 to 1.\n\n"
         "Use this shape:\n"
         "{\n"
         '  "component": "short component name",\n'
@@ -34,7 +45,8 @@ def build_vision_prompt() -> str:
         '      "name": "part name",\n'
         '      "role": "mechanical role",\n'
         '      "geometry": {"shape": "box", "size": [1, 1, 1], "position": [0, 0, 0]},\n'
-        '      "motion": {"type": "static"}\n'
+        '      "motion": {"type": "static"},\n'
+        '      "annotation": {"point": [0.5, 0.5], "label": "visible label", "note": "short visible clue"}\n'
         "    }\n"
         "  ]\n"
         "}\n\n"

snap2sim/schema.py

@@ -35,6 +35,11 @@ EXAMPLE_ANALYSIS: dict[str, Any] = {
                 "color": "steel",
             },
             "motion": {"type": "static"},
+            "annotation": {
+                "point": [0.5, 0.55],
+                "label": "head housing",
+                "note": "visible outer shell around the ratchet mechanism",
+            },
         },
         {
             "id": "ratchet_gear",
@@ -53,6 +58,11 @@ EXAMPLE_ANALYSIS: dict[str, Any] = {
                 "speed": 0.95,
                 "phase": 0,
             },
+            "annotation": {
+                "point": [0.5, 0.48],
+                "label": "ratchet gear",
+                "note": "central rotating socket carrier",
+            },
         },
         {
             "id": "pawl",
@@ -72,6 +82,11 @@ EXAMPLE_ANALYSIS: dict[str, Any] = {
                 "speed": 3.2,
                 "phase": 0.6,
             },
+            "annotation": {
+                "point": [0.67, 0.44],
+                "label": "spring pawl",
+                "note": "locking tooth that alternates grip and slip",
+            },
         },
         {
             "id": "selector",
@@ -84,6 +99,11 @@ EXAMPLE_ANALYSIS: dict[str, Any] = {
                 "color": "orange",
             },
             "motion": {"type": "static"},
+            "annotation": {
+                "point": [0.5, 0.28],
+                "label": "selector",
+                "note": "external control that reverses drive direction",
+            },
         },
     ],
 }
@@ -95,6 +115,7 @@ ANALYSIS_SCHEMA: dict[str, Any] = {
     "properties": {
         "component": {"type": "string"},
         "confidence": {"type": "number", "minimum": 0, "maximum": 1},
+        "render_mode": {"type": "string", "enum": ["three", "annotate", "unavailable"]},
         "summary": {"type": "string"},
         "trigger": {"type": "string"},
         "motion_sequence": {"type": "array", "items": {"type": "string"}},
@@ -102,7 +123,7 @@ ANALYSIS_SCHEMA: dict[str, Any] = {
             "type": "array",
             "items": {
                 "type": "object",
-                "required": ["id", "name", "role", "geometry", "motion"],
+                "required": ["id", "name", "role"],
                 "properties": {
                     "id": {"type": "string"},
                     "name": {"type": "string"},
@@ -162,6 +183,26 @@ ANALYSIS_SCHEMA: dict[str, Any] = {
                             },
                         },
                     },
+                    "annotation": {
+                        "type": "object",
+                        "required": ["point"],
+                        "properties": {
+                            "point": {
+                                "type": "array",
+                                "items": {"type": "number", "minimum": 0, "maximum": 1},
+                                "minItems": 2,
+                                "maxItems": 2,
+                            },
+                            "box": {
+                                "type": "array",
+                                "items": {"type": "number", "minimum": 0, "maximum": 1},
+                                "minItems": 4,
+                                "maxItems": 4,
+                            },
+                            "label": {"type": "string"},
+                            "note": {"type": "string"},
+                        },
+                    },
                 },
             },
         },
@@ -171,6 +212,27 @@ ANALYSIS_SCHEMA: dict[str, Any] = {
 
 _SHAPES = {"box", "cylinder", "sphere", "gear", "rod"}
 _MOTIONS = {"rotate", "translate", "oscillate", "static"}
+_RENDER_MODES = {"three", "annotate", "unavailable"}
+
+
+def select_render_mode(analysis: dict[str, Any]) -> str:
+    """Pick the safest renderer for a validated analysis payload."""
+    explicit_mode = analysis.get("render_mode")
+    if explicit_mode in _RENDER_MODES:
+        return str(explicit_mode)
+
+    parts = analysis.get("parts") if isinstance(analysis, dict) else []
+    has_geometry = any(isinstance(part, dict) and isinstance(part.get("geometry"), dict) for part in parts)
+    has_annotation = any(isinstance(part, dict) and isinstance(part.get("annotation"), dict) for part in parts)
+    confidence = analysis.get("confidence", 1)
+    low_confidence = _is_number(confidence) and float(confidence) < 0.5
+    if has_annotation and (low_confidence or not has_geometry):
+        return "annotate"
+    if has_geometry and not low_confidence:
+        return "three"
+    if has_annotation:
+        return "annotate"
+    return "unavailable"
 
 
 def validate_analysis(payload: dict[str, Any]) -> dict[str, Any]:
@@ -181,6 +243,8 @@ def validate_analysis(payload: dict[str, Any]) -> dict[str, Any]:
     for key in ["component", "summary", "trigger"]:
         _require_string(payload, key, key)
     _require_string_list(payload, "motion_sequence", "motion_sequence")
+    if "render_mode" in payload and payload["render_mode"] not in _RENDER_MODES:
+        raise ValueError("Invalid analysis payload at render_mode: unsupported mode")
 
     parts = payload.get("parts")
     if not isinstance(parts, list) or not parts:
@@ -193,32 +257,56 @@ def validate_analysis(payload: dict[str, Any]) -> dict[str, Any]:
         for key in ["id", "name", "role"]:
             _require_string(part, key, f"{path}.{key}")
 
+        has_geometry = False
         geometry = part.get("geometry")
-        if not isinstance(geometry, dict):
-            raise ValueError(f"Invalid analysis payload at {path}.geometry: expected an object")
-        shape = geometry.get("shape")
-        if shape not in _SHAPES:
-            raise ValueError(f"Invalid analysis payload at {path}.geometry.shape: unsupported shape")
-        _require_number_list(geometry, "size", f"{path}.geometry.size", 3)
-        _require_number_list(geometry, "position", f"{path}.geometry.position", 3)
-        if "rotation" in geometry:
-            _require_number_list(geometry, "rotation", f"{path}.geometry.rotation", 3)
-        if "teeth" in geometry and not isinstance(geometry["teeth"], int):
-            raise ValueError(f"Invalid analysis payload at {path}.geometry.teeth: expected an integer")
+        if geometry is not None:
+            if not isinstance(geometry, dict):
+                raise ValueError(f"Invalid analysis payload at {path}.geometry: expected an object")
+            shape = geometry.get("shape")
+            if shape not in _SHAPES:
+                raise ValueError(f"Invalid analysis payload at {path}.geometry.shape: unsupported shape")
+            _require_number_list(geometry, "size", f"{path}.geometry.size", 3)
+            _require_number_list(geometry, "position", f"{path}.geometry.position", 3)
+            if "rotation" in geometry:
+                _require_number_list(geometry, "rotation", f"{path}.geometry.rotation", 3)
+            if "teeth" in geometry and not isinstance(geometry["teeth"], int):
+                raise ValueError(f"Invalid analysis payload at {path}.geometry.teeth: expected an integer")
+            has_geometry = True
+
+        has_annotation = False
+        annotation = part.get("annotation")
+        if annotation is not None:
+            if not isinstance(annotation, dict):
+                raise ValueError(f"Invalid analysis payload at {path}.annotation: expected an object")
+            _require_unit_number_list(annotation, "point", f"{path}.annotation.point", 2)
+            if "box" in annotation:
+                _require_unit_number_list(annotation, "box", f"{path}.annotation.box", 4)
+            for key in ["label", "note"]:
+                if key in annotation and not isinstance(annotation[key], str):
+                    raise ValueError(f"Invalid analysis payload at {path}.annotation.{key}: expected a string")
+            has_annotation = True
+
+        if not has_geometry and not has_annotation:
+            raise ValueError(
+                f"Invalid analysis payload at {path}: expected geometry or annotation"
+            )
 
         motion = part.get("motion")
-        if not isinstance(motion, dict):
+        if motion is not None:
+            if not isinstance(motion, dict):
+                raise ValueError(f"Invalid analysis payload at {path}.motion: expected an object")
+            motion_type = motion.get("type")
+            if motion_type not in _MOTIONS:
+                raise ValueError(f"Invalid analysis payload at {path}.motion.type: unsupported motion")
+            if "axis" in motion:
+                _require_number_list(motion, "axis", f"{path}.motion.axis", 3)
+            if "range" in motion:
+                _require_number_list(motion, "range", f"{path}.motion.range", 2)
+            for key in ["speed", "amplitude", "phase"]:
+                if key in motion and not _is_number(motion[key]):
+                    raise ValueError(f"Invalid analysis payload at {path}.motion.{key}: expected a number")
+        elif has_geometry:
             raise ValueError(f"Invalid analysis payload at {path}.motion: expected an object")
-        motion_type = motion.get("type")
-        if motion_type not in _MOTIONS:
-            raise ValueError(f"Invalid analysis payload at {path}.motion.type: unsupported motion")
-        if "axis" in motion:
-            _require_number_list(motion, "axis", f"{path}.motion.axis", 3)
-        if "range" in motion:
-            _require_number_list(motion, "range", f"{path}.motion.range", 2)
-        for key in ["speed", "amplitude", "phase"]:
-            if key in motion and not _is_number(motion[key]):
-                raise ValueError(f"Invalid analysis payload at {path}.motion.{key}: expected a number")
 
     return payload
 
@@ -240,5 +328,15 @@ def _require_number_list(payload: dict[str, Any], key: str, path: str, length: i
         raise ValueError(f"Invalid analysis payload at {path}: expected {length} numbers")
 
 
+def _require_unit_number_list(payload: dict[str, Any], key: str, path: str, length: int) -> None:
+    value = payload.get(key)
+    if (
+        not isinstance(value, list)
+        or len(value) != length
+        or not all(_is_number(item) and 0 <= item <= 1 for item in value)
+    ):
+        raise ValueError(f"Invalid analysis payload at {path}: expected {length} numbers from 0 to 1")
+
+
 def _is_number(value: Any) -> bool:
     return isinstance(value, (int, float)) and not isinstance(value, bool)