Build Snap2Sim demo deployment scaffold

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

.env.example

@@ -0,0 +1,9 @@
+# Snap2Sim runtime configuration template.
+# Copy these keys into Hugging Face Space variables/secrets or a local .env file.
+# Do not put real tokens, passwords, or private endpoint URLs in this file.
+
+INFERENCE_BACKEND=modal
+MODAL_ANALYZE_URL=
+MODAL_GENERATE_URL=
+INFERENCE_TIMEOUT_SECONDS=240
+SNAP2SIM_API_TOKEN=

.github/workflows/sync_to_hf.yml

@@ -0,0 +1,60 @@
+# Sync this GitHub repository to an existing Hugging Face Space.
+#
+# Configure before use:
+# - Create the Hugging Face Space first; this workflow does not create it.
+# - Add a GitHub Actions secret named HF_TOKEN with write access to the target
+#   Hugging Face Space repository.
+# - Keep GitHub as the single source of truth. Do not edit files directly on
+#   the Hugging Face Space, because this workflow force-syncs GitHub to HF.
+# - Make sure any required Space variables/secrets, such as MODAL_ANALYZE_URL,
+#   MODAL_GENERATE_URL, and SNAP2SIM_API_TOKEN, are configured in the Space UI.
+
+name: Sync to Hugging Face Space
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: sync-to-hugging-face-space
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    name: Push GitHub main to Hugging Face
+    runs-on: ubuntu-latest
+    env:
+      HF_SPACE_URL: https://huggingface.co/spaces/jasondo111/Snap2Sim
+
+    steps:
+      - name: Checkout full history with LFS
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+
+      - name: Install Git LFS
+        run: |
+          git lfs install
+          git lfs fetch --all
+
+      - name: Configure Hugging Face remote
+        env:
+          HF_TOKEN: ${{ secrets.HF_TOKEN }}
+        run: |
+          if [ -z "$HF_TOKEN" ]; then
+            echo "GitHub secret HF_TOKEN is not configured." >&2
+            exit 1
+          fi
+          git remote remove huggingface 2>/dev/null || true
+          git remote add huggingface "https://hf:${HF_TOKEN}@${HF_SPACE_URL#https://}"
+
+      - name: Push LFS objects to Hugging Face
+        run: git lfs push huggingface --all
+
+      - name: Force-sync main to Hugging Face
+        run: git push --force huggingface HEAD:main

.gitignore

@@ -149,6 +149,8 @@ activemq-data/
 
 # Environments
 .env
+.env.*
+!.env.example
 .envrc
 .venv
 env/
@@ -216,3 +218,14 @@ __marimo__/
 
 # Streamlit
 .streamlit/secrets.toml
+
+# Local credentials and runtime caches
+.modal.toml
+.huggingface/
+hf_cache/
+model_cache/
+*.gguf
+
+# Local verification artifacts
+.playwright-mcp/
+snap2sim-*-scene.png

.hfignore

@@ -0,0 +1,22 @@
+.git/
+.venv/
+env/
+venv/
+__pycache__/
+*.py[codz]
+.pytest_cache/
+.ruff_cache/
+.playwright-mcp/
+
+.env
+.env.*
+!.env.example
+.envrc
+.modal.toml
+.huggingface/
+.netrc
+
+hf_cache/
+model_cache/
+*.gguf
+snap2sim-*-scene.png

AGENTS.md

@@ -0,0 +1,145 @@
+# AGENTS.md
+
+## Project Overview
+
+Snap2Sim / Inside the Machine is a Gradio-based Hugging Face Space scaffold for
+the Build Small Hackathon Backyard AI track. The app is intended to accept a
+photo of a hardware component, infer its internal mechanism, and render an
+annotated technical cutaway animation.
+
+## Runtime Notes
+
+- Preferred model path: `unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF`
+  through llama.cpp.
+- Verification note from June 13, 2026: the Unsloth GGUF repo lists `mmproj`
+  files and llama.cpp usage instructions. Modal GPU smoke testing confirms the
+  selected `UD-Q4_K_M` GGUF and `mmproj-F16.gguf` work with `llama-mtmd-cli`
+  image input.
+- Fallback model path: `nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-NVFP4`
+  through Transformers/custom code for the vision step if GGUF endpoint quality
+  is not reliable enough for the demo.
+- Current code uses placeholder inference so the UI, schema, and endpoint
+  contract can run without downloading large model weights.
+
+## Project Structure
+
+- `PROMPT.md` - original product, model, design, and delivery requirements.
+- `README.md` - quickstart, runtime decision, and repo map.
+- `SECURITY.md` - public/private data handling rules for humans and agents.
+- `.env.example` - public Hugging Face Space / local demo variables.
+- `.hfignore` - excludes local credentials, caches, GGUF files, and artifacts
+  from Hugging Face uploads.
+- `.github/workflows/sync_to_hf.yml` - GitHub Actions workflow that syncs
+  GitHub `main` to an existing Hugging Face Space.
+- `requirements.txt` - Python dependencies for the Gradio Space and Modal
+  scaffold.
+- `app.py` - Hugging Face Space entry point; launches the Gradio app.
+- `modal_app.py` - Modal app scaffold with runtime asset caching, a
+  llama.cpp GPU smoke-test function, a `runtime_probe` diagnostic endpoint, and
+  placeholder plus experimental llama.cpp `analyze_image` / `generate_threejs`
+  web endpoints.
+- `scripts/verify_runtime_assets.py` - Hugging Face metadata preflight for the
+  selected GGUF quant and `mmproj` file.
+- `snap2sim/__init__.py` - package marker.
+- `snap2sim/backend.py` - backend config, local placeholder inference, Modal
+  HTTP client, and image base64 encoding.
+- `snap2sim/fallback_scene.py` - themed animated SVG/CSS fallback shown when
+  generated Three.js is unavailable.
+- `snap2sim/prompts.py` - prompt templates for the vision analysis and Three.js
+  code-generation steps.
+- `snap2sim/schema.py` - structured JSON schema plus a sample mechanism payload.
+- `snap2sim/three_scene.py` - deterministic Three.js scene generation from a
+  validated mechanism payload.
+- `snap2sim/ui.py` - Gradio Blocks UI, blueprint field-manual CSS theme, and
+  pipeline orchestration.
+
+## What Has Been Done
+
+- Read `PROMPT.md` and implemented the requested initial scaffold.
+- Added a modular Gradio app with a two-pane technical cutaway / field manual
+  visual direction.
+- Added loading/status language and a styled fallback visualization path so the
+  viewport is not blank when Three.js generation is unavailable.
+- Added a backend abstraction controlled by `INFERENCE_BACKEND`.
+- Added placeholder Modal endpoints for the two required inference steps.
+- Added a Modal Volume-based runtime asset cache helper and runtime probe.
+- Added `smoke_test_llamacpp_image`, which builds llama.cpp with CUDA on Modal
+  and runs one image prompt through `llama-mtmd-cli` using the selected GGUF and
+  `mmproj-F16.gguf`.
+- Confirmed `smoke_test_llamacpp_image` returns `"ok": true`.
+- Confirmed `run_analysis_endpoint_check` returns a validated mechanism payload
+  from the real llama.cpp analysis task.
+- Changed runtime asset resolution so endpoint calls use cached Modal Volume
+  files directly; repeated `Fetching 3 files` logs were cached Hugging Face
+  metadata checks, not full model downloads.
+- Added `run_runtime_preflight` local entrypoint to cache assets and run the GPU
+  smoke test in one Modal command.
+- Added a local Hugging Face metadata preflight script and confirmed it passes
+  for `UD-Q4_K_M` plus `mmproj-F16.gguf`.
+- Modal is authenticated under the `bigstonks1` workspace; use
+  `$env:PYTHONIOENCODING='utf-8'; python -m modal ...` on Windows to avoid
+  CLI Unicode/charmap errors.
+- Defined the vision-to-scene JSON schema for parts, geometry hints, and motion.
+- Added JSON-schema validation before scene generation.
+- Added deterministic Three.js scene generation for local and Modal placeholder
+  mode, so validated payloads render as an animated 3D cutaway before model
+  code-generation is wired in.
+- Added model response parsing helpers for JSON analysis payloads and complete
+  HTML documents.
+- Added a local coercion fallback for verbose/partial model JSON so the
+  analysis endpoint does not launch a second slow repair generation.
+- Added experimental `analyze_image_llamacpp` and `generate_threejs_llamacpp`
+  Modal GPU endpoints. They are not wired into the Gradio app by default; point
+  `MODAL_ANALYZE_URL` / `MODAL_GENERATE_URL` at them only after the smoke test
+  passes.
+- Fixed Modal packaging for local `snap2sim` imports by adding
+  `add_local_python_source("snap2sim")` as the final image step for both Modal
+  images.
+- Added `check_remote_imports`; `python -m modal run
+  modal_app.py::check_remote_imports` now creates the `PythonPackage:snap2sim`
+  mount and hydrates the web functions without `ModuleNotFoundError`.
+- Added prompt templates for image analysis and Three.js scene generation.
+- Deployed `modal_app.py` to Modal at
+  `https://modal.com/apps/bigstonks1/main/deployed/snap2sim-inside-the-machine`.
+- Production endpoint checks passed for `runtime_probe`,
+  `analyze_image_llamacpp`, and deterministic `generate_threejs`.
+- Modal web endpoints are secured with `Authorization: Bearer
+  SNAP2SIM_API_TOKEN`; the token lives in Modal secret `snap2sim-api-auth` and
+  Hugging Face Space secret `SNAP2SIM_API_TOKEN`.
+- Verified unauthenticated Modal requests return `401 Unauthorized`.
+- Added `SECURITY.md`, `.env.example`, and `.hfignore` so public deployment
+  config is explicit while credentials and runtime caches stay out of uploads.
+- Added Hugging Face Space metadata to `README.md`.
+- Hugging Face auth is now valid for user `jasondo111`.
+- Uploaded the Space to `jasondo111/Snap2Sim`; the Space is `RUNNING` on
+  `cpu-basic` at `https://jasondo111-snap2sim.hf.space`.
+- The Space remains private as of the latest deployment.
+- User decision on June 13, 2026: keep the Hugging Face Space private for now.
+  Do not make it public unless the user explicitly asks.
+- Removed accidentally uploaded Playwright artifacts/screenshots from the Space
+  and expanded `.gitignore` so future `hf upload` runs skip them.
+- Verified the private Space with an authenticated `gradio_client` call using
+  `handle_file`; the `/run_pipeline` API returned `CUTAWAY READY`.
+- Re-verified `/run_pipeline` after endpoint auth was added; it still returns
+  `CUTAWAY READY`.
+- Added `.github/workflows/sync_to_hf.yml` for one-way GitHub to Hugging Face
+  Space sync on pushes to `main`. The workflow targets `jasondo111/Snap2Sim`
+  and requires GitHub secret `HF_TOKEN`.
+- User reported the GitHub Actions `HF_TOKEN` secret has been added.
+- Documented GitHub as the source of truth:
+  `https://github.com/Bigstonks1/Snap2Sim`. Do not edit files directly on the
+  Hugging Face Space; they will be overwritten by the sync workflow.
+- Updated `README.md` with local run instructions, runtime preflight, Modal
+  deployment path, and the current runtime decision.
+
+## Next Work
+
+- Point the Gradio app at `analyze_image_llamacpp` for analysis and the
+  deterministic `generate_threejs` endpoint for scene rendering.
+- Keep the Hugging Face Space private until the user explicitly approves making
+  it public for submission.
+- Commit and push the workflow to GitHub `main`, then verify the GitHub Actions
+  sync run succeeds.
+- If Three.js model generation is too brittle, keep using the deterministic
+  local scene generator for the demo while still using Nemotron for analysis.
+- Document final submission links and bonus claims.

GITHUB_PROMPT.md

@@ -0,0 +1,23 @@
+# Codex Prompt: Sync GitHub Repo to Hugging Face Space
+
+Create a GitHub Actions workflow file that automatically syncs this existing GitHub repository to an already-created Hugging Face Space whenever code is pushed to the `main` branch.
+
+## Important Context
+
+- The Hugging Face Space already exists — do not include any steps to create or initialize it
+- This is a **one-way sync only** (GitHub → Hugging Face). Nothing should ever push back from HF to GitHub
+- GitHub is the single source of truth — all edits should happen here, never directly on the HF Space
+
+## Requirements
+
+- Workflow file at `.github/workflows/sync_to_hf.yml`
+- Triggers on every push to `main`
+- Uses a GitHub secret called `HF_TOKEN` for authentication
+- Pushes full git history (no shallow clone)
+- Includes LFS support
+- Uses placeholders `YOUR_HF_USERNAME` and `YOUR_SPACE_NAME` in the HF Space URL
+- Adds a comment block at the top of the workflow file listing everything that needs to be configured before use
+
+## Additional Output
+
+Also create a short markdown snippet I can paste into my existing README explaining the deployment pipeline and warning contributors not to edit files directly on the Hugging Face Space.

PROMPT.md

@@ -0,0 +1,185 @@
+PROJECT: "Inside the Machine" — AI-powered teardown visualizer for the
+Build Small Hackathon (Backyard AI track, huggingface.co/build-small-hackathon)
+
+GOAL
+Build a Gradio app, deployed as a Hugging Face Space, that takes a photo of
+a hardware component (e.g. a gear, valve, hinge, pump, lock, engine part)
+and produces an animated 3D visualization showing how that component works
+internally at a finer-grained scale than the photo shows — i.e. "open it up
+and show me the moving parts and the physics/mechanism."
+
+HARD CONSTRAINTS
+- Total model parameters across the entire pipeline must be ≤ 32B.
+- Must be a Gradio app, hosted as a Hugging Face Space.
+- Prefer local/open-weight models (target the "Off the Grid" bonus: no
+  cloud APIs at inference time, where deployment allows).
+
+MODEL STACK
+Primary model: NVIDIA Nemotron 3 Nano Omni (30B-A3B, MoE, ~3B active
+params), used for both the vision-understanding step AND the Three.js
+code generation step (two prompts/turns against the same model). This
+targets the NVIDIA Nemotron Quest sponsor award and stays comfortably
+under the 32B cap as a single model.
+
+Fallback split pipeline (use only if the primary path's code-gen quality
+is too weak, or if the multimodal runtime issue below can't be resolved):
+- NVIDIA Nemotron Nano V2 VL (12B) for image understanding/analysis.
+- Qwen2.5-Coder-14B for Three.js/animation code generation.
+- Total ~26B, still leaves headroom and still qualifies for the Nemotron
+  Quest award via the vision step.
+
+MODEL RUNTIME
+- Primary path (targets "Llama Champion" bonus): use
+  unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF via llama.cpp.
+  Start with a mid-size quant (e.g. UD-Q4_K_M, ~24 GB) for quality, and
+  have a smaller quant (e.g. UD-IQ2_M, ~18.5 GB) ready as a fallback for
+  constrained hardware.
+- IMPORTANT — verify multimodal support first: as a setup/diagnostic step,
+  confirm whether this GGUF repo includes a vision-encoder ("mmproj") file
+  for the CRADIO v4-H encoder, and whether llama.cpp's current build
+  actually accepts image input for this architecture (nemotron_h_moe).
+  Multimodal GGUF conversions often ship the LLM only, with vision support
+  lagging behind.
+  - If image input works end-to-end via llama.cpp: use this single model
+    for both the vision-analysis step and the Three.js code-gen step —
+    this is the ideal "Llama Champion" + Nemotron Quest combo.
+  - If image input is NOT yet supported in the GGUF/llama.cpp path: use
+    the NVFP4 safetensors checkpoint (nvidia/Nemotron-3-Nano-Omni-30B-A3B-
+    Reasoning-NVFP4, ~20.9 GB) via vLLM or transformers for the vision-
+    analysis step only, and use the GGUF + llama.cpp build for the
+    Three.js code-gen step (text-only, so GGUF support is solid). Note
+    in the README that "Llama Champion" applies to the code-gen stage.
+- Either way, total parameters stay at ~31B (single model), comfortably
+  under the 32B cap, and the project remains eligible for the NVIDIA
+  Nemotron Quest award.
+
+DEPLOYMENT ARCHITECTURE — two-tier with Modal
+- Tier 1 (frontend): the Gradio app, hosted as a HF Space on the standard
+  CPU tier. Handles UI, image upload, calling the inference backend, and
+  rendering the returned JSON + Three.js HTML.
+- Tier 2 (inference backend): a Modal app exposing two functions as web
+  endpoints, running on a Modal GPU container:
+  - analyze_image(image) -> structured JSON (vision step, per the
+    pipeline below)
+  - generate_threejs(json) -> Three.js scene HTML/JS (code-gen step)
+  Both load Nemotron 3 Nano Omni once at container start (use a Modal
+  Volume to cache model weights across cold starts so they aren't
+  re-downloaded every time). Use whichever runtime (llama.cpp/GGUF or
+  vLLM/NVFP4) was determined in the MODEL RUNTIME verification step.
+- The Gradio app calls these endpoints over HTTP (e.g. via `requests`),
+  passing the image as base64 and receiving JSON/HTML back.
+- Make the inference backend swappable via a config flag (e.g.
+  INFERENCE_BACKEND=modal | zerogpu | local), so the same Gradio code can
+  run against:
+  - a Modal endpoint (primary path — generous credits, no VRAM
+    constraints, targets the Modal Award)
+  - HF Spaces ZeroGPU (alternative — model loads inside the Space itself
+    on an A10G; try the smallest GGUF quant here)
+  - a local GPU (for development/testing)
+- Surface Modal cold-start latency in the UI — e.g. a "WAKING THE
+  WORKSHOP..." loading message in the established visual theme, since
+  cold starts on a 30B model can take tens of seconds.
+- README must state which backend the submitted Space actually uses, and
+  adjust bonus-quest claims accordingly: if Modal is the deployed backend,
+  "Off the Grid" is not claimed (inference happens on Modal's cloud GPUs),
+  but "Llama Champion", "Nemotron Quest", and the Modal Award still apply.
+  If ZeroGPU ends up sufficient, "Off the Grid" can additionally be claimed.
+
+PIPELINE / APPLICATION FLOW
+1. User uploads a photo of a hardware component via gr.Image.
+2. Vision step (Nemotron VL): identify the component, enumerate its
+   internal parts, and describe its operating mechanism in structured
+   terms — e.g. part names, how each part moves (rotate/translate/
+   oscillate), axes/pivots, sequence of motion, and what triggers it
+   (e.g. "input shaft rotates → cam lobe pushes follower → valve opens").
+   Output this as structured JSON (part list with geometry hints: shape,
+   approximate size/position, motion type, motion parameters).
+3. Code-gen step: feed that JSON into the second prompt/model with
+   instructions to generate a single self-contained Three.js scene (HTML
+   + inline JS/CSS) that:
+   - builds simple primitive-based 3D representations of each part
+     (boxes, cylinders, gears via extruded shapes, etc.)
+   - animates them according to the described motion (rotation speed,
+     translation range, timing/sequence)
+   - includes basic camera controls (OrbitControls) and a play/pause toggle
+   - includes on-screen labels for each part
+4. Gradio renders the generated HTML via gr.HTML (sandboxed iframe).
+5. Below the visualization, display the structured explanation text from
+   step 2 (plain-language "how it works" writeup) so the app is useful
+   even if the 3D fails to render.
+
+VISUAL DESIGN DIRECTION — "Technical Cutaway / Field Manual" (Off-Brand bonus)
+Commit fully to this aesthetic; do not fall back to default Gradio styling.
+
+- Concept: the app should feel like a page from a vintage engineering
+  service manual or a reverse-engineering field notebook — the kind of
+  diagram you'd find annotating a cutaway drawing of an engine.
+- Theme: dark "blueprint" canvas as the dominant surface — deep navy/
+  charcoal background (not pure black), with fine 1px grid lines at low
+  opacity to evoke graph/blueprint paper.
+- Color system (define as CSS variables, used consistently):
+  - Background: deep charcoal-navy (e.g. #14181F)
+  - Primary accent: warm amber/safety-orange (e.g. #E8A33D) for
+    annotations, active states, and the "how it works" highlights
+  - Secondary accent: cool cyan (e.g. #5FD4D0) for part labels and
+    motion-path indicators in the 3D scene
+  - Text: off-white / warm gray, never pure white
+- Typography: pair a condensed, slightly industrial display/grotesk font
+  (e.g. for headings/labels — something like a stencil-adjacent or
+  technical condensed sans) with a monospace font (e.g. for the part
+  list, JSON-derived data, and annotations) — avoid Inter, Roboto, Arial,
+  and system-default fonts entirely.
+- Layout: two-pane, asymmetric split (3D viewport larger/left, analysis
+  panel narrower/right or as an overlay drawer). Part labels in the 3D
+  scene should look like annotation callouts (thin leader lines + small
+  monospace tags), echoing real exploded-diagram conventions.
+- Motion: one signature moment — when the model finishes analysis and
+  the 3D scene loads, animate a "power-on" reveal (e.g. parts fade/slide
+  into place sequentially, or a scanning-line sweep across the blueprint
+  grid before the model appears). Avoid scattered micro-animations
+  elsewhere; spend the motion budget on this one moment.
+- Texture/atmosphere: subtle grid-paper background, faint scanline or
+  vignette effect on the canvas edges — restrained, not noisy.
+- Loading states should reinforce the theme (e.g. "ANALYZING ASSEMBLY...",
+  "RENDERING CUTAWAY...", "WAKING THE WORKSHOP...") in the monospace font
+  rather than generic spinners.
+
+UI / UX REQUIREMENTS
+- Clean two-pane layout per the design direction above: 3D visualization
+  + part-by-part "how it works" panel.
+- Loading states for both inference steps (vision analysis can be slow,
+  Modal cold starts add latency), styled per the theme above.
+- Graceful fallback: if Three.js code generation fails or errors, show
+  the textual explanation plus a simple 2D animated SVG/CSS fallback
+  instead of a blank pane — keep this fallback in the same visual theme.
+- Investigate gr.Server if needed to achieve full styling control beyond
+  what gr.HTML / custom CSS in Blocks allows.
+
+DELIVERABLES
+- Working Gradio app code (app.py + requirements.txt) ready to push to a
+  Hugging Face Space under the build-small-hackathon org.
+- Modal app code (modal_app.py or similar) implementing the two inference
+  endpoints described above.
+- README explaining: the problem this solves and for whom (Backyard AI
+  track requires a real person/use case — e.g. a hobbyist mechanic, a
+  shop teacher, a repair-cafe volunteer who wants to explain how parts
+  work to customers/students), the model stack and parameter count
+  (must total ≤32B, state the exact breakdown), the deployment
+  architecture, and which bonus quests/sponsor awards are targeted
+  (Llama Champion, Off-Brand, NVIDIA Nemotron Quest, Modal Award, Field
+  Notes, and "Off the Grid" if applicable to the final deployment).
+- Keep code modular: separate files/functions for (1) vision analysis,
+  (2) code generation, (3) Gradio UI/styling, (4) inference backend
+  client/config, so each piece can be swapped or debugged independently.
+
+START by:
+1. Verifying the llama.cpp multimodal support question above for the
+   Nemotron 3 Nano Omni GGUF — this determines the runtime path for the
+   rest of the build.
+2. Scaffolding the Modal app with the two inference endpoints (using
+   placeholder/echo logic initially), and the Gradio app structure with
+   the backend-config flag and CSS theme/variables for the visual design
+   direction above.
+3. Designing the JSON schema for step 2 of the pipeline — this is the
+   critical interface between the vision and code-gen steps.
+4. Iterating on prompt templates for steps 2 and 3.

README.md

@@ -1 +1,207 @@
-# Snap2Sim
+---
+title: Snap2Sim Inside The Machine
+sdk: gradio
+app_file: app.py
+license: mit
+colorFrom: blue
+colorTo: yellow
+---
+
+# Snap2Sim
+
+Inside the Machine is a Gradio app scaffold for the Build Small Hackathon
+Backyard AI track. It takes a hardware component photo, produces a structured
+mechanism analysis, and renders a technical cutaway visualization.
+
+The local app still defaults to the placeholder backend, but the Modal
+llama.cpp path has been smoke-tested with the selected Nemotron GGUF and
+projector.
+
+## Run Locally
+
+```powershell
+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 endpoints.
+
+For the deployed demo configuration, copy `.env.example` into local environment
+variables or Hugging Face Space variables. Do not put tokens in `.env.example`;
+see `SECURITY.md`.
+
+## Runtime Preflight
+
+Run the metadata preflight before spending GPU time:
+
+```powershell
+python scripts/verify_runtime_assets.py
+```
+
+This confirms the selected GGUF quant and `mmproj` projector are present in the
+Hugging Face repo without downloading the model. It does not prove image input
+works in llama.cpp.
+
+## Runtime Decision
+
+Verification on June 13, 2026 found:
+
+- `unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF` includes GGUF
+  quant files, `mmproj-BF16.gguf`, `mmproj-F16.gguf`, and `mmproj-F32.gguf`.
+- The same model card includes llama.cpp launch instructions.
+- llama.cpp source includes the `nemotron_h_moe` text architecture.
+- llama.cpp public docs list multimodal server support, but the visible
+  supported-model list does not explicitly name Nemotron Omni or CRADIO v4-H.
+
+So the preferred path is single-model GGUF via llama.cpp. The Modal GPU smoke
+test passed on June 13, 2026 with `UD_Q4_K_M` and `mmproj-F16.gguf`, confirming
+that `llama-mtmd-cli` accepts image input for this pairing.
+
+If endpoint quality is not strong enough for the demo, use
+`nvidia/Nemotron-3-Nano-Omni-30B-A3B-Reasoning-NVFP4` through vLLM or
+Transformers/custom code for vision analysis, and keep the GGUF path for
+text-only Three.js generation.
+
+Primary references:
+
+- https://huggingface.co/unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF
+- https://github.com/ggml-org/llama.cpp
+
+## Project Structure
+
+- `.env.example` - public runtime variables for the deployed Modal demo.
+- `SECURITY.md` - public/private data handling guidance for humans and agents.
+- `app.py` - Hugging Face Space entry point.
+- `modal_app.py` - Modal web endpoint scaffold.
+- `scripts/verify_runtime_assets.py` - GGUF/mmproj metadata preflight.
+- `snap2sim/backend.py` - backend selection and HTTP client.
+- `snap2sim/fallback_scene.py` - themed 2D fallback animation.
+- `snap2sim/prompts.py` - prompt templates for vision and Three.js generation.
+- `snap2sim/schema.py` - JSON schema and sample analysis payload.
+- `snap2sim/three_scene.py` - deterministic Three.js scene generation from the
+  validated mechanism JSON.
+- `snap2sim/ui.py` - Gradio Blocks UI and visual theme.
+
+## Modal Deployment Path
+
+The Modal app defaults to placeholder inference so endpoint wiring can be tested
+without loading a 30B model:
+
+```powershell
+python -m modal deploy modal_app.py
+```
+
+If Modal is not authenticated on the machine, run `python -m modal token new`
+first.
+
+Current production deployment:
+
+- Deployment: https://modal.com/apps/bigstonks1/main/deployed/snap2sim-inside-the-machine
+- Web endpoint URLs are configured in Hugging Face Space variables and protected
+  by the `SNAP2SIM_API_TOKEN` bearer-token secret.
+
+Useful deployment functions/endpoints:
+
+- `check_remote_imports` verifies Modal can import the local `snap2sim` package
+  before running expensive GPU/model work.
+- `download_runtime_assets` caches the selected GGUF quant and `mmproj` file in
+  the `snap2sim-hf-cache` Modal Volume.
+- `smoke_test_llamacpp_image` builds llama.cpp with CUDA and runs one image
+  prompt through `llama-mtmd-cli` using the cached GGUF and `mmproj`.
+- `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` and `generate_threejs` preserve the current HTTP contract for
+  the Gradio app.
+- `analyze_image_llamacpp` and `generate_threejs_llamacpp` are experimental GPU
+  endpoints for the llama.cpp runtime path after the smoke test passes.
+
+Runtime environment knobs:
+
+- `SNAP2SIM_MODEL_REPO`, default
+  `unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF`
+- `SNAP2SIM_GGUF_QUANT`, default `UD-Q4_K_M`
+- `SNAP2SIM_MMPROJ_FILE`, default `mmproj-F16.gguf`
+- `SNAP2SIM_RUNTIME_MODE`, default `placeholder`
+- `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 and keep
+`MODAL_GENERATE_URL` on deterministic `generate_threejs`.
+
+Run the deployment preflight in this order:
+
+```powershell
+python -m modal run modal_app.py::check_remote_imports
+python -m modal run modal_app.py::download_runtime_assets
+python -m modal run modal_app.py::smoke_test_llamacpp_image
+python -m modal run modal_app.py::run_analysis_endpoint_check
+```
+
+Or run both steps together:
+
+```powershell
+python -m modal run modal_app.py::run_runtime_preflight
+```
+
+The smoke test returns a JSON object. Treat `"ok": true` as evidence that
+llama.cpp accepted image input with the selected GGUF and `mmproj`. The analysis
+endpoint has a bounded generation path and a local coercion fallback because the
+reasoning model can emit verbose `<think>` text before JSON.
+
+## Hugging Face Space Configuration
+
+Current Space:
+
+- Hub repo: https://huggingface.co/spaces/jasondo111/Snap2Sim
+- App host: https://jasondo111-snap2sim.hf.space
+- Visibility: private as of the latest deployment
+- Runtime: `RUNNING` on `cpu-basic`
+
+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
+```
+
+The Space also needs `SNAP2SIM_API_TOKEN` as a Hugging Face Space secret. The
+same value must be present in the Modal `snap2sim-api-auth` secret. Do not put
+that token in `.env.example`, README, logs, or prompts.
+
+From this repo, deploy after authenticating with Hugging Face:
+
+```powershell
+hf auth login --force
+hf repos create jasondo111/Snap2Sim --type space --space-sdk gradio --exist-ok --env-file .env.example
+hf upload jasondo111/Snap2Sim . . --repo-type space --commit-message "Deploy Snap2Sim demo"
+```
+
+The `.hfignore` file excludes local credentials, caches, downloaded model
+weights, and Playwright artifacts from uploads.
+
+For an authenticated API check against this private Space, use `handle_file`
+with `gradio_client`; plain string file paths are rejected by the Gradio 6 image
+input schema.
+
+## GitHub to Hugging Face Sync
+
+GitHub is the source of truth for this project:
+
+- GitHub repo: https://github.com/Bigstonks1/Snap2Sim
+- Hugging Face Space: configured separately as the sync target
+
+The workflow at `.github/workflows/sync_to_hf.yml` syncs pushes to the `main`
+branch into `jasondo111/Snap2Sim`. It requires a GitHub Actions secret named
+`HF_TOKEN` with write access to that Space.
+
+Do not edit files directly in the Hugging Face Space. Those changes are not the
+source of truth and will be overwritten by the next GitHub-to-Hugging Face sync.
+Configure runtime values such as `MODAL_ANALYZE_URL`, `MODAL_GENERATE_URL`, and
+`SNAP2SIM_API_TOKEN` through Hugging Face Space variables/secrets instead of
+committing them.

SECURITY.md

@@ -0,0 +1,98 @@
+# Security Notes
+
+This project is intended to become a public hackathon demo, but the deployed
+Hugging Face Space is private right now by user decision. Treat the repo,
+README, screenshots, and Codex-visible files as public unless explicitly told
+otherwise, and do not make the Space public until the user explicitly approves
+that change.
+
+## Do Not Commit Or Expose
+
+- Modal tokens, Hugging Face tokens, API keys, passwords, OAuth credentials, or
+  private SSH keys.
+- Local credential files such as `.modal.toml`, `.huggingface/token`,
+  `.netrc`, `.env`, `.envrc`, or shell profile exports containing secrets.
+- Modal or Hugging Face dashboard pages that include account-private billing,
+  workspace settings, tokens, or secret values.
+- Raw user-uploaded photos unless the user explicitly asks to add sample images
+  to the repo.
+- Full model outputs if they include private user content, uploaded image
+  details, or long traces that are not needed for debugging.
+- Modal Volume contents, downloaded GGUF files, Hugging Face cache directories,
+  or any other large runtime assets.
+
+## Endpoint Access
+
+The deployed Modal endpoint URLs are public HTTP entry points at the network
+level, but every Modal web endpoint must require:
+
+```text
+Authorization: Bearer <SNAP2SIM_API_TOKEN>
+```
+
+`SNAP2SIM_API_TOKEN` must be stored only as:
+
+- Modal secret: `snap2sim-api-auth`
+- Hugging Face Space secret: `SNAP2SIM_API_TOKEN`
+
+Do not document the live Modal endpoint URLs in public files unless the user
+explicitly asks. The URLs are not credentials, but keeping them out of public
+docs reduces casual discovery, and the bearer token is the real protection
+against credit-spending spam.
+
+The Hugging Face Space at `jasondo111/Snap2Sim` is private as of the latest
+deployment. Future agents must not change the Space visibility to public unless
+the user explicitly asks for that action.
+
+## Environment Variables
+
+Safe to expose in public docs or `.env.example`:
+
+- `INFERENCE_BACKEND`
+- `MODAL_ANALYZE_URL`
+- `MODAL_GENERATE_URL`
+- `INFERENCE_TIMEOUT_SECONDS`
+- `SNAP2SIM_MODEL_REPO`
+- `SNAP2SIM_GGUF_QUANT`
+- `SNAP2SIM_MMPROJ_FILE`
+- `SNAP2SIM_RUNTIME_GPU`
+
+Keep private and configure only through local secret stores, Modal secrets, or
+Hugging Face Space secrets:
+
+- `MODAL_TOKEN_ID`
+- `MODAL_TOKEN_SECRET`
+- `SNAP2SIM_API_TOKEN`
+- `HF_TOKEN`
+- `HUGGING_FACE_HUB_TOKEN`
+- Any future provider key such as `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or
+  hosted inference credentials.
+
+## GitHub Actions
+
+The GitHub-to-Hugging Face sync workflow uses a GitHub Actions secret named
+`HF_TOKEN`. Store that token only in GitHub repository or organization secrets.
+Do not hardcode it in `.github/workflows/sync_to_hf.yml`, README files,
+environment templates, prompts, or local scripts.
+
+The workflow is one-way only: GitHub `main` pushes to the Hugging Face Space.
+Do not configure jobs that pull changes back from Hugging Face into GitHub.
+
+## Agent Guidance
+
+- Prefer Hugging Face Space variables for public configuration and Space secrets
+  for credentials.
+- Do not print secret-bearing environment variables in logs.
+- Do not paste full Modal or Hugging Face auth files into issues, docs, prompts,
+  or Codex summaries.
+- When sharing logs, trim them to the failing stack trace and remove uploaded
+  image payloads, base64 strings, tokens, cookies, and account-private URLs.
+- Before adding new dependencies or services, document whether they require
+  credentials and where those credentials should live.
+
+## Reporting
+
+For this hackathon repo, report suspected leaks directly to the repository owner
+or workspace owner. If a token was exposed, rotate it immediately in the
+provider dashboard and remove the leaked value from git history before making
+the repository public.

app.py

@@ -0,0 +1,11 @@
+"""Hugging Face Space entry point."""
+
+from snap2sim.ui import build_app
+
+
+demo = build_app()
+
+
+if __name__ == "__main__":
+    demo.launch()
+

modal_app.py

@@ -0,0 +1,469 @@
+"""Modal inference service scaffold for Snap2Sim.
+
+The endpoints intentionally keep placeholder inference as the default until the
+Nemotron runtime passes a GPU smoke test. The deployment helpers here pin the
+target model assets and make that smoke test explicit instead of silently
+claiming multimodal GGUF support before image input has been proven.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+import secrets as token_secrets
+
+import modal
+from fastapi import Header, HTTPException
+
+from snap2sim.model_io import coerce_analysis_response, parse_analysis_response, parse_html_response
+from snap2sim.prompts import build_threejs_prompt, build_vision_prompt
+from snap2sim.schema import EXAMPLE_ANALYSIS, validate_analysis
+from snap2sim.three_scene import build_threejs_html
+
+
+DEFAULT_MODEL_REPO = "unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF"
+DEFAULT_GGUF_QUANT = "UD-Q4_K_M"
+DEFAULT_MMPROJ_FILE = "mmproj-F16.gguf"
+DEFAULT_RUNTIME_MODE = "placeholder"
+CACHE_DIR = "/cache"
+HF_CACHE_DIR = f"{CACHE_DIR}/huggingface"
+MODEL_ASSET_DIR = f"{CACHE_DIR}/models"
+
+
+model_cache = modal.Volume.from_name("snap2sim-hf-cache", create_if_missing=True)
+api_auth_secret = modal.Secret.from_name("snap2sim-api-auth")
+
+image = (
+    modal.Image.debian_slim(python_version="3.11")
+    .pip_install(
+        "fastapi[standard]",
+        "huggingface_hub[hf_xet]",
+        "pillow",
+        "requests",
+    )
+    .env(
+        {
+            "HF_HUB_CACHE": HF_CACHE_DIR,
+            "HF_XET_HIGH_PERFORMANCE": "1",
+        }
+    )
+    .add_local_python_source("snap2sim")
+)
+
+llamacpp_image = (
+    modal.Image.from_registry("nvidia/cuda:12.9.0-devel-ubuntu22.04", add_python="3.11")
+    .entrypoint([])
+    .apt_install("build-essential", "cmake", "curl", "git", "libcurl4-openssl-dev")
+    .pip_install("fastapi[standard]", "huggingface_hub[hf_xet]", "pillow")
+    .env(
+        {
+            "HF_HUB_CACHE": HF_CACHE_DIR,
+            "HF_XET_HIGH_PERFORMANCE": "1",
+            "LIBRARY_PATH": "/usr/local/cuda/lib64/stubs:/usr/local/cuda/targets/x86_64-linux/lib/stubs",
+        }
+    )
+    .run_commands(
+        "if [ -f /usr/local/cuda/lib64/stubs/libcuda.so ] && [ ! -f /usr/local/cuda/lib64/stubs/libcuda.so.1 ]; then ln -s /usr/local/cuda/lib64/stubs/libcuda.so /usr/local/cuda/lib64/stubs/libcuda.so.1; fi",
+        "if [ -f /usr/local/cuda/targets/x86_64-linux/lib/stubs/libcuda.so ] && [ ! -f /usr/local/cuda/targets/x86_64-linux/lib/stubs/libcuda.so.1 ]; then ln -s /usr/local/cuda/targets/x86_64-linux/lib/stubs/libcuda.so /usr/local/cuda/targets/x86_64-linux/lib/stubs/libcuda.so.1; fi",
+        "git clone --depth 1 https://github.com/ggml-org/llama.cpp.git /opt/llama.cpp",
+        "cmake -S /opt/llama.cpp -B /opt/llama.cpp/build -DGGML_CUDA=ON -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXE_LINKER_FLAGS='-L/usr/local/cuda/lib64/stubs -L/usr/local/cuda/targets/x86_64-linux/lib/stubs -Wl,-rpath-link,/usr/local/cuda/lib64/stubs -Wl,-rpath-link,/usr/local/cuda/targets/x86_64-linux/lib/stubs'",
+        "cmake --build /opt/llama.cpp/build --target llama-mtmd-cli llama-cli -j",
+    )
+    .add_local_python_source("snap2sim")
+)
+
+app = modal.App("snap2sim-inside-the-machine")
+
+
+@app.function(image=image, timeout=120)
+def check_remote_imports() -> dict[str, Any]:
+    """Lightweight Modal check that local project modules are packaged."""
+    import snap2sim.model_io
+    import snap2sim.schema
+    import snap2sim.three_scene
+
+    return {
+        "ok": True,
+        "modules": [
+            snap2sim.model_io.__name__,
+            snap2sim.schema.__name__,
+            snap2sim.three_scene.__name__,
+        ],
+    }
+
+
+def runtime_config() -> dict[str, str]:
+    return {
+        "model_repo": os.getenv("SNAP2SIM_MODEL_REPO", DEFAULT_MODEL_REPO),
+        "gguf_quant": os.getenv("SNAP2SIM_GGUF_QUANT", DEFAULT_GGUF_QUANT),
+        "mmproj_file": os.getenv("SNAP2SIM_MMPROJ_FILE", DEFAULT_MMPROJ_FILE),
+        "runtime_mode": os.getenv("SNAP2SIM_RUNTIME_MODE", DEFAULT_RUNTIME_MODE),
+    }
+
+
+def require_authorization(authorization: str) -> None:
+    expected_token = os.getenv("SNAP2SIM_API_TOKEN", "")
+    if not expected_token:
+        raise HTTPException(status_code=503, detail="API authentication is not configured.")
+    scheme, separator, provided_token = authorization.partition(" ")
+    if (
+        not separator
+        or scheme.lower() != "bearer"
+        or not token_secrets.compare_digest(provided_token, expected_token)
+    ):
+        raise HTTPException(status_code=401, detail="Unauthorized")
+
+
+def asset_patterns(config: dict[str, str]) -> list[str]:
+    """Return the repo file patterns needed by the llama.cpp runtime."""
+    return [
+        f"*{config['gguf_quant']}*.gguf",
+        config["mmproj_file"],
+        "README.md",
+    ]
+
+
+def cached_asset_paths(config: dict[str, str]) -> tuple[Path, Path] | None:
+    """Return cached model paths when both required runtime files exist."""
+    local_dir = Path(MODEL_ASSET_DIR) / config["model_repo"]
+    model_matches = sorted(local_dir.glob(f"*{config['gguf_quant']}*.gguf"))
+    mmproj_path = local_dir / config["mmproj_file"]
+    if model_matches and mmproj_path.exists():
+        return model_matches[0], mmproj_path
+    return None
+
+
+@app.function(
+    image=image,
+    volumes={CACHE_DIR: model_cache},
+    timeout=60 * 60,
+)
+def download_runtime_assets() -> dict[str, Any]:
+    """Cache the selected GGUF quant and projector on the Modal Volume."""
+    from huggingface_hub import snapshot_download
+
+    config = runtime_config()
+    patterns = asset_patterns(config)
+    path = snapshot_download(
+        repo_id=config["model_repo"],
+        local_dir=f"{MODEL_ASSET_DIR}/{config['model_repo']}",
+        allow_patterns=patterns,
+    )
+    model_cache.commit()
+    return {
+        "repo": config["model_repo"],
+        "quant": config["gguf_quant"],
+        "mmproj": config["mmproj_file"],
+        "path": path,
+        "patterns": patterns,
+    }
+
+
+def ensure_runtime_assets() -> tuple[Path, Path]:
+    """Download configured model assets if needed and return local paths."""
+    from huggingface_hub import snapshot_download
+
+    config = runtime_config()
+    cached_paths = cached_asset_paths(config)
+    if cached_paths:
+        return cached_paths
+
+    local_dir = Path(MODEL_ASSET_DIR) / config["model_repo"]
+    snapshot_download(
+        repo_id=config["model_repo"],
+        local_dir=local_dir,
+        allow_patterns=asset_patterns(config),
+    )
+    cached_paths = cached_asset_paths(config)
+    if not cached_paths:
+        raise FileNotFoundError(f"No GGUF file matched {config['gguf_quant']} in {local_dir}")
+    return cached_paths
+
+
+@app.function(
+    image=llamacpp_image,
+    gpu=os.getenv("SNAP2SIM_SMOKE_GPU", "L40S"),
+    volumes={CACHE_DIR: model_cache},
+    timeout=60 * 60,
+)
+def smoke_test_llamacpp_image() -> dict[str, Any]:
+    """Run one image prompt through llama.cpp's multimodal CLI on a GPU."""
+    import base64
+    import subprocess
+    import time
+
+    from PIL import Image, ImageDraw
+
+    model_path, mmproj_path = ensure_runtime_assets()
+    test_image = Path("/tmp/snap2sim-smoke-input.jpg")
+    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)
+    img.save(test_image, format="JPEG", quality=92)
+
+    prompt = """Answer with only this compact JSON shape. Do not include markdown.
+{
+  "component": "short component name",
+  "confidence": 0.7,
+  "summary": "one sentence about the visible test image mechanism",
+  "trigger": "manual alignment",
+  "motion_sequence": ["first motion", "second motion"],
+  "parts": [
+    {
+      "id": "ring",
+      "name": "outer ring",
+      "role": "frames the mechanism",
+      "geometry": {"shape": "cylinder", "size": [1, 0.1, 1], "position": [0, 0, 0]},
+      "motion": {"type": "rotate", "axis": [0, 1, 0], "speed": 0.2}
+    },
+    {
+      "id": "crossbar",
+      "name": "crossbar",
+      "role": "shows alignment",
+      "geometry": {"shape": "rod", "size": [0.05, 0.05, 1], "position": [0, 0.05, 0]},
+      "motion": {"type": "static"}
+    }
+  ]
+}"""
+    cmd = [
+        "/opt/llama.cpp/build/bin/llama-mtmd-cli",
+        "-m",
+        str(model_path),
+        "--mmproj",
+        str(mmproj_path),
+        "--image",
+        str(test_image),
+        "-p",
+        prompt,
+        "-n",
+        "1024",
+        "--temp",
+        "0.2",
+    ]
+    start = time.monotonic()
+    proc = subprocess.run(cmd, capture_output=True, text=True, timeout=45 * 60)
+    elapsed_seconds = round(time.monotonic() - start, 2)
+    stdout = proc.stdout.strip()
+    stderr = proc.stderr.strip()
+    combined_output = "\n".join(part for part in [stdout, stderr] if part).strip()
+    parsed_component = ""
+    valid_json = False
+    parse_error = ""
+    try:
+        parsed_component = parse_analysis_response(stdout)["component"]
+        valid_json = True
+    except Exception as exc:
+        parse_error = str(exc)
+
+    image_supported = (
+        proc.returncode == 0
+        and bool(stdout)
+        and "image input is not supported" not in combined_output.lower()
+        and "failed to load projector" not in combined_output.lower()
+    )
+    return {
+        "ok": image_supported and valid_json,
+        "image_supported": image_supported,
+        "valid_json": valid_json,
+        "parsed_component": parsed_component,
+        "parse_error": parse_error,
+        "returncode": proc.returncode,
+        "elapsed_seconds": elapsed_seconds,
+        "model_path": str(model_path),
+        "mmproj_path": str(mmproj_path),
+        "image_base64_prefix": base64.b64encode(test_image.read_bytes()).decode("ascii")[:80],
+        "stdout_tail": stdout[-4000:],
+        "stderr_tail": stderr[-4000:],
+    }
+
+
+def run_llamacpp_prompt(
+    prompt: str,
+    image_path: Path | None = None,
+    max_tokens: int = 1024,
+    timeout_seconds: int = 180,
+) -> str:
+    """Run one prompt through the llama.cpp multimodal CLI."""
+    import subprocess
+
+    model_path, mmproj_path = ensure_runtime_assets()
+    cmd = [
+        "/opt/llama.cpp/build/bin/llama-mtmd-cli",
+        "-m",
+        str(model_path),
+        "--mmproj",
+        str(mmproj_path),
+        "-p",
+        prompt,
+        "-n",
+        str(max_tokens),
+        "--temp",
+        "0.2",
+    ]
+    if image_path is not None:
+        cmd.extend(["--image", str(image_path)])
+
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout_seconds)
+    except subprocess.TimeoutExpired as exc:
+        partial_output = "\n".join(
+            part.decode("utf-8", errors="replace") if isinstance(part, bytes) else part
+            for part in [exc.stdout, exc.stderr]
+            if part
+        ).strip()
+        raise TimeoutError(
+            f"llama.cpp timed out after {timeout_seconds}s: {partial_output[-2000:]}"
+        ) from exc
+    output = "\n".join(part for part in [proc.stdout, proc.stderr] if part).strip()
+    if proc.returncode != 0:
+        raise RuntimeError(f"llama.cpp exited with {proc.returncode}: {output[-2000:]}")
+    return output
+
+
+def write_payload_image(payload: dict[str, Any]) -> Path:
+    """Decode an image_base64 payload into a temporary RGB JPEG."""
+    import base64
+    from io import BytesIO
+
+    from PIL import Image
+
+    image_base64 = payload.get("image_base64")
+    if not isinstance(image_base64, str) or not image_base64:
+        raise ValueError("Request payload must include image_base64.")
+    if "," in image_base64 and image_base64.lstrip().startswith("data:"):
+        image_base64 = image_base64.split(",", 1)[1]
+
+    raw = base64.b64decode(image_base64)
+    image = Image.open(BytesIO(raw)).convert("RGB")
+    path = Path("/tmp/snap2sim-request-image.jpg")
+    image.save(path, format="JPEG", quality=92)
+    return path
+
+
+def analyze_image_llamacpp_payload(payload: dict[str, Any]) -> dict[str, Any]:
+    image_path = write_payload_image(payload)
+    response = run_llamacpp_prompt(
+        build_vision_prompt(),
+        image_path=image_path,
+        max_tokens=1536,
+        timeout_seconds=180,
+    )
+    try:
+        return parse_analysis_response(response)
+    except Exception:
+        return coerce_analysis_response(response)
+
+
+@app.local_entrypoint()
+def run_runtime_preflight() -> None:
+    """Cache assets, then run the Modal GPU llama.cpp image smoke test."""
+    print(download_runtime_assets.remote())
+    print(smoke_test_llamacpp_image.remote())
+
+
+@app.local_entrypoint()
+def run_smoke_test() -> None:
+    """Run and print the Modal GPU llama.cpp image smoke test result."""
+    import json
+
+    print(json.dumps(smoke_test_llamacpp_image.remote(), indent=2))
+
+
+@app.local_entrypoint()
+def run_analysis_endpoint_check() -> None:
+    """Run the experimental image-analysis endpoint logic with a test image."""
+    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)
+    result = analyze_image_llamacpp_task.remote(
+        {"image_base64": base64.b64encode(buffer.getvalue()).decode("ascii")}
+    )
+    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]:
+    """Expose the currently selected runtime path for deployment diagnostics."""
+    require_authorization(authorization)
+    config = runtime_config()
+    return {
+        "runtime_mode": config["runtime_mode"],
+        "model_repo": config["model_repo"],
+        "gguf_quant": config["gguf_quant"],
+        "mmproj_file": config["mmproj_file"],
+        "status": (
+            "placeholder endpoint active; llama.cpp endpoint verified separately"
+            if config["runtime_mode"] == "placeholder"
+            else "runtime selected"
+        ),
+        "verified_endpoint": "analyze_image_llamacpp",
+        "recommended_generate_endpoint": "generate_threejs",
+    }
+
+
+@app.function(image=image, volumes={CACHE_DIR: model_cache}, timeout=600, secrets=[api_auth_secret])
+@modal.fastapi_endpoint(method="POST")
+def analyze_image(payload: dict[str, Any], authorization: str = Header(default="")) -> dict[str, Any]:
+    require_authorization(authorization)
+    _ = payload.get("image_base64", "")
+    _prompt = build_vision_prompt()
+    if runtime_config()["runtime_mode"] != "placeholder":
+        raise NotImplementedError(
+            "Use the analyze_image_llamacpp endpoint for the verified Nemotron "
+            "llama.cpp runtime path."
+        )
+    return validate_analysis(dict(EXAMPLE_ANALYSIS))
+
+
+@app.function(image=llamacpp_image, gpu=os.getenv("SNAP2SIM_RUNTIME_GPU", "L40S"), volumes={CACHE_DIR: model_cache}, timeout=60 * 60)
+def analyze_image_llamacpp_task(payload: dict[str, Any]) -> dict[str, Any]:
+    """Remote-callable task for testing the llama.cpp image analysis path."""
+    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, secrets=[api_auth_secret])
+@modal.fastapi_endpoint(method="POST")
+def analyze_image_llamacpp(payload: dict[str, Any], authorization: str = Header(default="")) -> dict[str, Any]:
+    """Experimental GPU endpoint for llama.cpp multimodal image analysis."""
+    require_authorization(authorization)
+    return analyze_image_llamacpp_payload(payload)
+
+
+@app.function(image=image, volumes={CACHE_DIR: model_cache}, timeout=600, secrets=[api_auth_secret])
+@modal.fastapi_endpoint(method="POST")
+def generate_threejs(payload: dict[str, Any], authorization: str = Header(default="")) -> dict[str, str]:
+    require_authorization(authorization)
+    analysis = validate_analysis(payload.get("analysis") or EXAMPLE_ANALYSIS)
+    _prompt = build_threejs_prompt(analysis)
+    if runtime_config()["runtime_mode"] != "placeholder":
+        raise NotImplementedError(
+            "Nemotron runtime is selected but not wired yet. Keep placeholder "
+            "mode active until the llama.cpp/vLLM adapter is implemented."
+        )
+    return {"html": build_threejs_html(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])
+@modal.fastapi_endpoint(method="POST")
+def generate_threejs_llamacpp(payload: dict[str, Any], authorization: str = Header(default="")) -> dict[str, str]:
+    """Experimental GPU endpoint for llama.cpp Three.js code generation."""
+    require_authorization(authorization)
+    analysis = validate_analysis(payload.get("analysis") or EXAMPLE_ANALYSIS)
+    response = run_llamacpp_prompt(build_threejs_prompt(analysis), max_tokens=4096)
+    return {"html": parse_html_response(response)}

requirements.txt

@@ -0,0 +1,5 @@
+gradio>=4.44
+huggingface_hub[hf_xet]>=0.36
+requests>=2.32
+pillow>=10.4
+modal>=0.64

scripts/verify_runtime_assets.py

@@ -0,0 +1,53 @@
+"""Preflight checks for the preferred Nemotron GGUF runtime assets.
+
+This script only lists Hugging Face repository metadata. It does not download
+model weights and it does not prove image input works in llama.cpp.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+from huggingface_hub import HfApi
+
+
+MODEL_REPO = os.getenv(
+    "SNAP2SIM_MODEL_REPO",
+    "unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF",
+)
+GGUF_QUANT = os.getenv("SNAP2SIM_GGUF_QUANT", "UD-Q4_K_M")
+MMPROJ_FILE = os.getenv("SNAP2SIM_MMPROJ_FILE", "mmproj-F16.gguf")
+
+
+def main() -> int:
+    files = HfApi().list_repo_files(MODEL_REPO)
+    quant_matches = [name for name in files if name.endswith(".gguf") and GGUF_QUANT in name]
+    mmproj_matches = [name for name in files if name.startswith("mmproj") and name.endswith(".gguf")]
+
+    print(f"repo: {MODEL_REPO}")
+    print(f"quant selector: {GGUF_QUANT}")
+    print(f"quant files: {', '.join(quant_matches) or 'NONE'}")
+    print(f"mmproj files: {', '.join(mmproj_matches) or 'NONE'}")
+    print(f"selected mmproj: {MMPROJ_FILE}")
+
+    missing = []
+    if not quant_matches:
+        missing.append(f"GGUF quant containing {GGUF_QUANT}")
+    if MMPROJ_FILE not in files:
+        missing.append(MMPROJ_FILE)
+
+    if missing:
+        print(f"missing: {', '.join(missing)}", file=sys.stderr)
+        return 1
+
+    print("preflight: PASS")
+    print(
+        "next: run a GPU smoke test with llama.cpp using the selected GGUF and "
+        "mmproj, then send one image prompt through the server."
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

snap2sim/__init__.py

@@ -0,0 +1,2 @@
+"""Snap2Sim application package."""
+

snap2sim/backend.py

@@ -0,0 +1,74 @@
+"""Backend client and local placeholder inference."""
+
+from __future__ import annotations
+
+import base64
+import os
+from dataclasses import dataclass
+from io import BytesIO
+from typing import Any
+
+import requests
+from PIL import Image
+
+from snap2sim.schema import EXAMPLE_ANALYSIS, validate_analysis
+from snap2sim.three_scene import build_threejs_html
+
+
+@dataclass(frozen=True)
+class Settings:
+    backend: str = os.getenv("INFERENCE_BACKEND", "local")
+    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"))
+
+
+def encode_image(image: Image.Image) -> str:
+    buffer = BytesIO()
+    image.convert("RGB").save(buffer, format="JPEG", quality=92)
+    return base64.b64encode(buffer.getvalue()).decode("ascii")
+
+
+class InferenceClient:
+    def __init__(self, settings: Settings | None = None) -> None:
+        self.settings = settings or Settings()
+
+    def analyze_image(self, image: Image.Image | None) -> dict[str, Any]:
+        if self.settings.backend == "modal":
+            if image is None:
+                raise ValueError("Upload an image before analysis.")
+            return self._post_json(
+                self.settings.analyze_url,
+                {"image_base64": encode_image(image)},
+            )
+
+        return validate_analysis(dict(EXAMPLE_ANALYSIS))
+
+    def generate_threejs(self, analysis: dict[str, Any]) -> str:
+        valid_analysis = validate_analysis(analysis)
+        if self.settings.backend == "modal":
+            response = self._post_json(self.settings.generate_url, {"analysis": valid_analysis})
+            html = response.get("html", "")
+            if not html:
+                raise RuntimeError("Modal response did not include generated HTML.")
+            return str(html)
+
+        return build_threejs_html(valid_analysis)
+
+    def _post_json(self, url: str, payload: dict[str, Any]) -> dict[str, Any]:
+        if not url:
+            raise RuntimeError("Modal backend selected but endpoint URL is not configured.")
+        if not self.settings.api_token:
+            raise RuntimeError("Modal backend selected but SNAP2SIM_API_TOKEN is not configured.")
+        response = requests.post(
+            url,
+            json=payload,
+            headers={"Authorization": f"Bearer {self.settings.api_token}"},
+            timeout=self.settings.timeout_seconds,
+        )
+        response.raise_for_status()
+        data = response.json()
+        if not isinstance(data, dict):
+            raise RuntimeError("Inference backend returned a non-object JSON payload.")
+        return data

snap2sim/fallback_scene.py

@@ -0,0 +1,72 @@
+"""Themed fallback visualization used when generated Three.js is unavailable."""
+
+from __future__ import annotations
+
+
+def build_fallback_html(component: str) -> str:
+    title = component.upper()
+    return f"""
+<div class="fallback-cutaway" role="img" aria-label="Fallback mechanism animation for {component}">
+  <div class="scan"></div>
+  <svg viewBox="0 0 760 430" xmlns="http://www.w3.org/2000/svg">
+    <defs>
+      <pattern id="grid" width="24" height="24" patternUnits="userSpaceOnUse">
+        <path d="M 24 0 L 0 0 0 24" fill="none" stroke="rgba(95,212,208,.14)" stroke-width="1"/>
+      </pattern>
+    </defs>
+    <rect width="760" height="430" fill="#14181F"/>
+    <rect width="760" height="430" fill="url(#grid)"/>
+    <g transform="translate(380 220)">
+      <circle r="104" fill="none" stroke="#5FD4D0" stroke-width="2" opacity=".8"/>
+      <circle class="fallback-gear" r="72" fill="none" stroke="#E8A33D" stroke-width="18"
+        stroke-dasharray="18 10"/>
+      <rect class="fallback-pawl" x="72" y="-16" width="132" height="32" rx="2"
+        fill="#E8A33D" opacity=".9"/>
+      <line x1="108" y1="-54" x2="215" y2="-112" stroke="#5FD4D0" stroke-width="1"/>
+      <text x="224" y="-116" fill="#5FD4D0" font-family="monospace" font-size="15">LOCKING PAWL</text>
+      <line x1="-54" y1="52" x2="-198" y2="122" stroke="#5FD4D0" stroke-width="1"/>
+      <text x="-342" y="132" fill="#5FD4D0" font-family="monospace" font-size="15">DRIVE GEAR</text>
+    </g>
+    <text x="32" y="44" fill="#D9D3C7" font-family="monospace" font-size="18">{title}</text>
+    <text x="32" y="394" fill="#E8A33D" font-family="monospace" font-size="13">2D FALLBACK: GENERATED 3D SCENE UNAVAILABLE</text>
+  </svg>
+</div>
+<style>
+  .fallback-cutaway {{
+    position: relative;
+    overflow: hidden;
+    border: 1px solid rgba(95, 212, 208, .28);
+    background: #14181F;
+    min-height: 430px;
+  }}
+  .fallback-cutaway svg {{
+    display: block;
+    width: 100%;
+    height: min(58vh, 560px);
+  }}
+  .fallback-gear {{
+    transform-origin: center;
+    animation: fallback-spin 3.8s linear infinite;
+  }}
+  .fallback-pawl {{
+    transform-origin: 74px 0;
+    animation: fallback-pawl 1.05s steps(2, end) infinite;
+  }}
+  .scan {{
+    position: absolute;
+    inset: 0;
+    background: linear-gradient(180deg, transparent, rgba(95, 212, 208, .16), transparent);
+    height: 26%;
+    animation: fallback-scan 2.6s ease-in-out infinite;
+    pointer-events: none;
+  }}
+  @keyframes fallback-spin {{ to {{ transform: rotate(360deg); }} }}
+  @keyframes fallback-pawl {{ 50% {{ transform: rotate(-10deg); }} }}
+  @keyframes fallback-scan {{
+    0% {{ transform: translateY(-120%); opacity: 0; }}
+    20%, 80% {{ opacity: 1; }}
+    100% {{ transform: translateY(430%); opacity: 0; }}
+  }}
+</style>
+"""
+

snap2sim/model_io.py

@@ -0,0 +1,257 @@
+"""Parsing helpers for model responses."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from snap2sim.schema import validate_analysis
+
+
+_FENCE_RE = re.compile(r"^```(?:json|html)?\s*|\s*```$", re.IGNORECASE)
+
+
+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):
+        try:
+            payload = json.loads(json_text)
+            return validate_analysis(payload)
+        except (json.JSONDecodeError, ValueError) as exc:
+            errors.append(f"object at {start}: {exc}")
+
+    if errors:
+        raise ValueError("Model response did not contain a valid analysis JSON object. " + errors[-1])
+    raise ValueError("Model response did not contain a complete JSON object.")
+
+
+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):
+        try:
+            payload = json.loads(json_text)
+        except json.JSONDecodeError:
+            continue
+        if not isinstance(payload, dict):
+            continue
+        try:
+            return validate_analysis(_coerce_analysis_payload(payload, fallback_component))
+        except ValueError:
+            continue
+    return validate_analysis(_generic_analysis(fallback_component))
+
+
+def parse_html_response(text: str) -> str:
+    """Extract a complete HTML document from a model response."""
+    raw = _strip_fences(text).strip()
+    html_start = _find_html_start(raw)
+    html_end = raw.lower().rfind("</html>")
+    if html_start < 0 or html_end < 0:
+        raise ValueError("Model response did not contain a complete HTML document.")
+    return raw[html_start : html_end + len("</html>")]
+
+
+def _strip_fences(text: str) -> str:
+    return _FENCE_RE.sub("", text.strip()).strip()
+
+
+def _find_html_start(text: str) -> int:
+    lowered = text.lower()
+    starts = [index for index in [lowered.find("<!doctype"), lowered.find("<html")] if index >= 0]
+    return min(starts) if starts else -1
+
+
+def _json_object_candidates(text: str) -> list[tuple[int, str]]:
+    candidates = []
+    for index, char in enumerate(text):
+        if char != "{":
+            continue
+        try:
+            candidates.append((index, _balanced_json_object(text, index)))
+        except ValueError:
+            continue
+    return candidates
+
+
+def _balanced_json_object(text: str, start: int) -> str:
+    depth = 0
+    in_string = False
+    escaped = False
+    for index in range(start, len(text)):
+        char = text[index]
+        if in_string:
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == '"':
+                in_string = False
+            continue
+
+        if char == '"':
+            in_string = True
+        elif char == "{":
+            depth += 1
+        elif char == "}":
+            depth -= 1
+            if depth == 0:
+                return text[start : index + 1]
+
+    raise ValueError("Model response contained an unterminated JSON object.")
+
+
+def _coerce_analysis_payload(payload: dict[str, Any], fallback_component: str) -> dict[str, Any]:
+    parts = payload.get("parts")
+    if not isinstance(parts, list):
+        parts = []
+    coerced_parts = [_coerce_part(part, index) for index, part in enumerate(parts[:4]) if isinstance(part, dict)]
+    coerced_parts = [part for part in coerced_parts if part is not None]
+    if not coerced_parts:
+        coerced_parts = _generic_analysis(fallback_component)["parts"]
+
+    confidence = payload.get("confidence", 0.55)
+    if not isinstance(confidence, (int, float)) or isinstance(confidence, bool):
+        confidence = 0.55
+
+    return {
+        "component": _non_empty_string(payload.get("component"), fallback_component),
+        "confidence": max(0.0, min(1.0, float(confidence))),
+        "summary": _non_empty_string(
+            payload.get("summary"),
+            f"{fallback_component.title()} approximated as primitive cutaway parts.",
+        ),
+        "trigger": _non_empty_string(payload.get("trigger"), "manual input"),
+        "motion_sequence": _string_list(
+            payload.get("motion_sequence"),
+            ["input is applied", "internal parts move through the inferred mechanism"],
+        ),
+        "parts": coerced_parts,
+    }
+
+
+def _coerce_part(part: dict[str, Any], index: int) -> dict[str, Any] | None:
+    geometry = part.get("geometry")
+    if not isinstance(geometry, dict):
+        geometry = {}
+    motion = part.get("motion")
+    if not isinstance(motion, dict):
+        motion = {}
+
+    shape = geometry.get("shape")
+    if shape not in {"box", "cylinder", "sphere", "gear", "rod"}:
+        shape = "box"
+    motion_type = motion.get("type")
+    if motion_type not in {"rotate", "translate", "oscillate", "static"}:
+        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
+    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])
+    values = _number_list(motion.get("range"), 2)
+    if values:
+        coerced_motion["range"] = values
+
+    coerced_geometry: dict[str, Any] = {
+        "shape": shape,
+        "size": _number_list(geometry.get("size"), 3) or [1.0, 0.4, 1.0],
+        "position": _number_list(geometry.get("position"), 3) or [float(index) - 1.0, 0.0, 0.0],
+    }
+    values = _number_list(geometry.get("rotation"), 3)
+    if values:
+        coerced_geometry["rotation"] = values
+    if isinstance(geometry.get("teeth"), int):
+        coerced_geometry["teeth"] = geometry["teeth"]
+    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,
+    }
+
+
+def _generic_analysis(component: str) -> dict[str, Any]:
+    return {
+        "component": component,
+        "confidence": 0.45,
+        "summary": f"{component.title()} rendered as a conservative generic cutaway.",
+        "trigger": "manual input",
+        "motion_sequence": [
+            "input is applied to the housing",
+            "central rotor transfers motion",
+            "guide elements hold alignment",
+        ],
+        "parts": [
+            {
+                "id": "housing",
+                "name": "outer housing",
+                "role": "supports the internal mechanism",
+                "geometry": {"shape": "box", "size": [2.4, 0.45, 1.4], "position": [0, 0, 0]},
+                "motion": {"type": "static"},
+            },
+            {
+                "id": "rotor",
+                "name": "central rotor",
+                "role": "transfers motion through the assembly",
+                "geometry": {"shape": "cylinder", "size": [0.9, 0.35, 0.9], "position": [0, 0.18, 0]},
+                "motion": {"type": "rotate", "axis": [0, 1, 0], "speed": 0.55},
+            },
+            {
+                "id": "guide",
+                "name": "guide rail",
+                "role": "keeps the moving part aligned",
+                "geometry": {"shape": "rod", "size": [1.6, 0.12, 0.12], "position": [0, 0.42, 0.48]},
+                "motion": {"type": "static"},
+            },
+        ],
+    }
+
+
+def _infer_component(text: str) -> str:
+    match = re.search(r'"component"\s*:\s*"([^"]+)"', text)
+    if match and match.group(1).strip():
+        return match.group(1).strip()
+    lowered = text.lower()
+    for name in ["ratchet", "gear", "hinge", "motor", "lens", "target", "switch", "bearing"]:
+        if name in lowered:
+            return name
+    return "observed component"
+
+
+def _non_empty_string(value: Any, fallback: str) -> str:
+    return value.strip() if isinstance(value, str) and value.strip() else fallback
+
+
+def _string_list(value: Any, fallback: list[str]) -> list[str]:
+    if isinstance(value, list):
+        values = [item.strip() for item in value if isinstance(item, str) and item.strip()]
+        if values:
+            return values
+    return fallback
+
+
+def _number_list(value: Any, length: int) -> list[float] | None:
+    if not isinstance(value, list) or len(value) != length:
+        return None
+    if not all(isinstance(item, (int, float)) and not isinstance(item, bool) for item in value):
+        return None
+    return [float(item) for item in value]
+
+
+def _identifier(value: Any, fallback: str) -> str:
+    text = _non_empty_string(value, fallback).lower()
+    text = re.sub(r"[^a-z0-9_]+", "_", text).strip("_")
+    return text or fallback

snap2sim/prompts.py

@@ -0,0 +1,64 @@
+"""Prompt templates for the two model calls."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+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."""
+
+
+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"
+        "Required top-level keys: component, confidence, summary, trigger, "
+        "motion_sequence, parts.\n"
+        "Each part requires: id, name, role, geometry, motion.\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"
+        "Use this shape:\n"
+        "{\n"
+        '  "component": "short component name",\n'
+        '  "confidence": 0.7,\n'
+        '  "summary": "one or two sentences",\n'
+        '  "trigger": "what starts the mechanism",\n'
+        '  "motion_sequence": ["step one", "step two"],\n'
+        '  "parts": [\n'
+        "    {\n"
+        '      "id": "part_id",\n'
+        '      "name": "part name",\n'
+        '      "role": "mechanical role",\n'
+        '      "geometry": {"shape": "box", "size": [1, 1, 1], "position": [0, 0, 0]},\n'
+        '      "motion": {"type": "static"}\n'
+        "    }\n"
+        "  ]\n"
+        "}\n\n"
+        "Optional geometry fields: rotation, teeth, color. Optional motion "
+        "fields: axis, speed, amplitude, phase, range. Include optional fields "
+        "only when useful."
+    )
+
+
+THREEJS_SYSTEM_PROMPT = """You generate self-contained Three.js cutaway scenes.
+Return a complete HTML document with inline CSS and JavaScript only. Use
+primitive geometry, labels, OrbitControls, a play/pause control, and one
+power-on reveal animation. Do not include markdown fences."""
+
+
+def build_threejs_prompt(analysis: dict[str, Any]) -> str:
+    return (
+        "Build a technical cutaway / field manual Three.js animation for this "
+        "mechanism analysis. Use a deep navy blueprint surface, warm amber "
+        "annotations, cool cyan motion paths, and monospace labels. Include "
+        "a robust fallback message inside the HTML if WebGL fails.\n\n"
+        f"Mechanism JSON:\n{json.dumps(analysis, indent=2)}"
+    )

snap2sim/schema.py

@@ -0,0 +1,244 @@
+"""Shared data contract between vision analysis and scene generation."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+MotionType = Literal["rotate", "translate", "oscillate", "static"]
+
+
+EXAMPLE_ANALYSIS: dict[str, Any] = {
+    "component": "ratchet wrench head",
+    "confidence": 0.72,
+    "summary": (
+        "A ratchet head converts a back-and-forth handle motion into one-way "
+        "socket rotation. A pawl locks against the gear teeth during the drive "
+        "stroke and slips over the teeth during the return stroke."
+    ),
+    "trigger": "handle swings clockwise and counterclockwise",
+    "motion_sequence": [
+        "handle applies torque to the outer head",
+        "pawl tooth locks into the ratchet gear",
+        "gear and socket rotate on the drive stroke",
+        "pawl rides over gear teeth on the return stroke",
+    ],
+    "parts": [
+        {
+            "id": "housing",
+            "name": "head housing",
+            "role": "keeps the mechanism aligned",
+            "geometry": {
+                "shape": "cylinder",
+                "size": [3.2, 0.55, 3.2],
+                "position": [0, 0, 0],
+                "rotation": [1.5708, 0, 0],
+                "color": "steel",
+            },
+            "motion": {"type": "static"},
+        },
+        {
+            "id": "ratchet_gear",
+            "name": "ratchet gear",
+            "role": "carries the socket and teeth",
+            "geometry": {
+                "shape": "gear",
+                "teeth": 24,
+                "size": [1.45, 0.4, 1.45],
+                "position": [0, 0.15, 0],
+                "color": "cyan",
+            },
+            "motion": {
+                "type": "rotate",
+                "axis": [0, 1, 0],
+                "speed": 0.95,
+                "phase": 0,
+            },
+        },
+        {
+            "id": "pawl",
+            "name": "spring pawl",
+            "role": "locks and releases against gear teeth",
+            "geometry": {
+                "shape": "box",
+                "size": [0.32, 0.35, 1.1],
+                "position": [1.25, 0.3, 0.18],
+                "rotation": [0, 0.35, 0],
+                "color": "amber",
+            },
+            "motion": {
+                "type": "oscillate",
+                "axis": [0, 1, 0],
+                "amplitude": 0.28,
+                "speed": 3.2,
+                "phase": 0.6,
+            },
+        },
+        {
+            "id": "selector",
+            "name": "direction selector",
+            "role": "flips the pawl angle for reverse drive",
+            "geometry": {
+                "shape": "box",
+                "size": [0.9, 0.2, 0.32],
+                "position": [0, 0.68, -1.05],
+                "color": "orange",
+            },
+            "motion": {"type": "static"},
+        },
+    ],
+}
+
+
+ANALYSIS_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "required": ["component", "summary", "trigger", "motion_sequence", "parts"],
+    "properties": {
+        "component": {"type": "string"},
+        "confidence": {"type": "number", "minimum": 0, "maximum": 1},
+        "summary": {"type": "string"},
+        "trigger": {"type": "string"},
+        "motion_sequence": {"type": "array", "items": {"type": "string"}},
+        "parts": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "required": ["id", "name", "role", "geometry", "motion"],
+                "properties": {
+                    "id": {"type": "string"},
+                    "name": {"type": "string"},
+                    "role": {"type": "string"},
+                    "geometry": {
+                        "type": "object",
+                        "required": ["shape", "size", "position"],
+                        "properties": {
+                            "shape": {
+                                "type": "string",
+                                "enum": ["box", "cylinder", "sphere", "gear", "rod"],
+                            },
+                            "size": {
+                                "type": "array",
+                                "items": {"type": "number"},
+                                "minItems": 3,
+                                "maxItems": 3,
+                            },
+                            "position": {
+                                "type": "array",
+                                "items": {"type": "number"},
+                                "minItems": 3,
+                                "maxItems": 3,
+                            },
+                            "rotation": {
+                                "type": "array",
+                                "items": {"type": "number"},
+                                "minItems": 3,
+                                "maxItems": 3,
+                            },
+                            "teeth": {"type": "integer", "minimum": 6, "maximum": 80},
+                            "color": {"type": "string"},
+                        },
+                    },
+                    "motion": {
+                        "type": "object",
+                        "required": ["type"],
+                        "properties": {
+                            "type": {
+                                "type": "string",
+                                "enum": ["rotate", "translate", "oscillate", "static"],
+                            },
+                            "axis": {
+                                "type": "array",
+                                "items": {"type": "number"},
+                                "minItems": 3,
+                                "maxItems": 3,
+                            },
+                            "speed": {"type": "number"},
+                            "amplitude": {"type": "number"},
+                            "phase": {"type": "number"},
+                            "range": {
+                                "type": "array",
+                                "items": {"type": "number"},
+                                "minItems": 2,
+                                "maxItems": 2,
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+}
+
+
+_SHAPES = {"box", "cylinder", "sphere", "gear", "rod"}
+_MOTIONS = {"rotate", "translate", "oscillate", "static"}
+
+
+def validate_analysis(payload: dict[str, Any]) -> dict[str, Any]:
+    """Validate a model analysis payload against the scene-generation contract."""
+    if not isinstance(payload, dict):
+        raise ValueError("Analysis payload must be a JSON object.")
+
+    for key in ["component", "summary", "trigger"]:
+        _require_string(payload, key, key)
+    _require_string_list(payload, "motion_sequence", "motion_sequence")
+
+    parts = payload.get("parts")
+    if not isinstance(parts, list) or not parts:
+        raise ValueError("Invalid analysis payload at parts: expected a non-empty list")
+
+    for index, part in enumerate(parts):
+        path = f"parts.{index}"
+        if not isinstance(part, dict):
+            raise ValueError(f"Invalid analysis payload at {path}: expected an object")
+        for key in ["id", "name", "role"]:
+            _require_string(part, key, f"{path}.{key}")
+
+        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")
+
+        motion = part.get("motion")
+        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")
+
+    return payload
+
+
+def _require_string(payload: dict[str, Any], key: str, path: str) -> None:
+    if not isinstance(payload.get(key), str) or not payload[key].strip():
+        raise ValueError(f"Invalid analysis payload at {path}: expected a non-empty string")
+
+
+def _require_string_list(payload: dict[str, Any], key: str, path: str) -> None:
+    value = payload.get(key)
+    if not isinstance(value, list) or not value or not all(isinstance(item, str) and item.strip() for item in value):
+        raise ValueError(f"Invalid analysis payload at {path}: expected a non-empty list of strings")
+
+
+def _require_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) for item in value):
+        raise ValueError(f"Invalid analysis payload at {path}: expected {length} numbers")
+
+
+def _is_number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)

snap2sim/three_scene.py

@@ -0,0 +1,397 @@
+"""Deterministic Three.js scene generation from a validated mechanism payload."""
+
+from __future__ import annotations
+
+import html
+import json
+from typing import Any
+
+from snap2sim.schema import validate_analysis
+
+
+def build_threejs_html(analysis: dict[str, Any]) -> str:
+    """Return a sandboxed iframe containing a self-contained scene document."""
+    valid_analysis = validate_analysis(analysis)
+    document = _build_scene_document(valid_analysis)
+    escaped = html.escape(document, quote=True)
+    title = html.escape(str(valid_analysis.get("component", "mechanism")), quote=True)
+    return (
+        f'<iframe class="snap-scene-frame" title="Animated cutaway of {title}" '
+        'sandbox="allow-scripts allow-same-origin" '
+        f'srcdoc="{escaped}"></iframe>'
+    )
+
+
+def _build_scene_document(analysis: dict[str, Any]) -> str:
+    analysis_json = json.dumps(analysis)
+    component = html.escape(str(analysis.get("component", "mechanism")).upper())
+    return f"""<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <style>
+    :root {{
+      --bg: #14181F;
+      --panel: #1B222B;
+      --amber: #E8A33D;
+      --cyan: #5FD4D0;
+      --text: #D9D3C7;
+      --muted: #8F968F;
+    }}
+    * {{ box-sizing: border-box; }}
+    html, body {{
+      width: 100%;
+      height: 100%;
+      margin: 0;
+      overflow: hidden;
+      color: var(--text);
+      background:
+        linear-gradient(rgba(95, 212, 208, .07) 1px, transparent 1px),
+        linear-gradient(90deg, rgba(95, 212, 208, .07) 1px, transparent 1px),
+        var(--bg);
+      background-size: 28px 28px;
+      font-family: "IBM Plex Mono", "Consolas", monospace;
+    }}
+    #scene {{
+      position: fixed;
+      inset: 0;
+    }}
+    .hud {{
+      position: fixed;
+      left: 18px;
+      right: 18px;
+      top: 16px;
+      z-index: 3;
+      display: flex;
+      align-items: flex-start;
+      justify-content: space-between;
+      gap: 16px;
+      pointer-events: none;
+    }}
+    .title {{
+      max-width: min(680px, 70vw);
+    }}
+    .title b {{
+      display: block;
+      color: var(--text);
+      font-size: 14px;
+      letter-spacing: 0;
+      text-transform: uppercase;
+    }}
+    .title span {{
+      display: block;
+      margin-top: 6px;
+      color: var(--muted);
+      font-size: 12px;
+      line-height: 1.45;
+    }}
+    #toggle {{
+      pointer-events: auto;
+      min-width: 92px;
+      border: 1px solid rgba(232, 163, 61, .8);
+      border-radius: 2px;
+      padding: 8px 12px;
+      color: #16130E;
+      background: linear-gradient(180deg, #F0B65B, #C97923);
+      font: 700 12px "IBM Plex Mono", monospace;
+      text-transform: uppercase;
+      cursor: pointer;
+    }}
+    #labels {{
+      position: fixed;
+      inset: 0;
+      z-index: 2;
+      pointer-events: none;
+    }}
+    .tag {{
+      position: absolute;
+      max-width: min(190px, 42vw);
+      transform: translate(-50%, -50%);
+      border-left: 1px solid var(--cyan);
+      padding: 4px 0 4px 8px;
+      color: var(--cyan);
+      background: rgba(20, 24, 31, .76);
+      font-size: 11px;
+      line-height: 1.25;
+      text-transform: uppercase;
+      white-space: normal;
+    }}
+    .tag::before {{
+      content: "";
+      position: absolute;
+      left: -42px;
+      top: 50%;
+      width: 40px;
+      border-top: 1px solid rgba(95, 212, 208, .7);
+    }}
+    .scan {{
+      position: fixed;
+      inset: -30% 0 auto;
+      height: 28%;
+      z-index: 4;
+      background: linear-gradient(180deg, transparent, rgba(95, 212, 208, .18), transparent);
+      animation: scan 2.2s ease-in-out 1;
+      pointer-events: none;
+    }}
+    .failure {{
+      position: fixed;
+      left: 50%;
+      top: 50%;
+      width: min(520px, calc(100vw - 40px));
+      transform: translate(-50%, -50%);
+      border: 1px solid rgba(232, 163, 61, .62);
+      padding: 18px;
+      color: var(--amber);
+      background: rgba(20, 24, 31, .92);
+      font-size: 13px;
+      line-height: 1.55;
+    }}
+    .hidden {{ display: none; }}
+    @keyframes scan {{
+      0% {{ transform: translateY(-100%); opacity: 0; }}
+      20%, 75% {{ opacity: 1; }}
+      100% {{ transform: translateY(430%); opacity: 0; }}
+    }}
+  </style>
+</head>
+<body>
+  <div id="scene"></div>
+  <div id="labels"></div>
+  <div class="scan"></div>
+  <div class="hud">
+    <div class="title">
+      <b>{component}</b>
+      <span>Primitive cutaway generated from the validated mechanism schema.</span>
+    </div>
+    <button id="toggle" type="button">Pause</button>
+  </div>
+  <div id="failure" class="failure hidden">WebGL scene failed to initialize.</div>
+  <script type="module">
+    const analysis = {analysis_json};
+    const failure = document.getElementById("failure");
+
+    function fail(error) {{
+      failure.classList.remove("hidden");
+      failure.textContent = "3D renderer unavailable: " + (error && error.message ? error.message : error);
+    }}
+
+    try {{
+      const [threeModule, controlsModule] = await Promise.all([
+        import("https://esm.sh/three@0.166.1"),
+        import("https://esm.sh/three@0.166.1/examples/jsm/controls/OrbitControls.js?deps=three@0.166.1")
+      ]);
+      initialize(threeModule, controlsModule.OrbitControls);
+    }} catch (error) {{
+      fail(error);
+    }}
+
+    function initialize(THREE, OrbitControls) {{
+      const root = document.getElementById("scene");
+      const labelsRoot = document.getElementById("labels");
+      const renderer = new THREE.WebGLRenderer({{ antialias: true, alpha: true, preserveDrawingBuffer: true }});
+      renderer.setPixelRatio(Math.min(window.devicePixelRatio || 1, 2));
+      renderer.setSize(window.innerWidth, window.innerHeight);
+      renderer.outputColorSpace = THREE.SRGBColorSpace;
+      root.appendChild(renderer.domElement);
+
+      const scene = new THREE.Scene();
+      scene.fog = new THREE.Fog(0x14181f, 9, 22);
+
+      const camera = new THREE.PerspectiveCamera(42, window.innerWidth / window.innerHeight, 0.1, 100);
+      camera.position.set(5.8, 4.6, 6.8);
+
+      const controls = new OrbitControls(camera, renderer.domElement);
+      controls.enableDamping = true;
+      controls.target.set(0, 0.15, 0);
+
+      scene.add(new THREE.HemisphereLight(0x5fd4d0, 0x14181f, 1.35));
+      const key = new THREE.DirectionalLight(0xffc36a, 2.15);
+      key.position.set(4, 7, 5);
+      scene.add(key);
+
+      const grid = new THREE.GridHelper(8, 32, 0x5fd4d0, 0x24505a);
+      grid.material.transparent = true;
+      grid.material.opacity = 0.42;
+      scene.add(grid);
+
+      const motionLineMaterial = new THREE.LineBasicMaterial({{ color: 0x5fd4d0, transparent: true, opacity: 0.56 }});
+      const parts = [];
+
+      for (const [index, part] of analysis.parts.entries()) {{
+        const mesh = buildMesh(THREE, part, index);
+        mesh.position.fromArray(part.geometry.position);
+        if (Array.isArray(part.geometry.rotation)) mesh.rotation.fromArray(part.geometry.rotation);
+        mesh.userData.basePosition = mesh.position.clone();
+        mesh.userData.baseRotation = mesh.rotation.clone();
+        mesh.userData.part = part;
+        mesh.scale.setScalar(0.001);
+        scene.add(mesh);
+        parts.push(mesh);
+
+        if (part.motion && part.motion.type !== "static") {{
+          const curve = motionCurve(THREE, part);
+          const line = new THREE.Line(
+            new THREE.BufferGeometry().setFromPoints(curve),
+            motionLineMaterial
+          );
+          scene.add(line);
+        }}
+      }}
+
+      let playing = true;
+      document.getElementById("toggle").addEventListener("click", (event) => {{
+        playing = !playing;
+        event.currentTarget.textContent = playing ? "Pause" : "Play";
+      }});
+
+      const clock = new THREE.Clock();
+      function animate() {{
+        requestAnimationFrame(animate);
+        const elapsed = clock.getElapsedTime();
+        const t = playing ? elapsed : 0;
+        for (const [index, mesh] of parts.entries()) {{
+          reveal(mesh, elapsed, index);
+          applyMotion(THREE, mesh, t);
+        }}
+        controls.update();
+        renderer.render(scene, camera);
+        updateLabels(THREE, camera, labelsRoot, parts);
+      }}
+      animate();
+
+      window.addEventListener("resize", () => {{
+        camera.aspect = window.innerWidth / window.innerHeight;
+        camera.updateProjectionMatrix();
+        renderer.setSize(window.innerWidth, window.innerHeight);
+      }});
+    }}
+
+    function buildMesh(THREE, part, index) {{
+      const g = part.geometry || {{}};
+      const size = Array.isArray(g.size) ? g.size : [1, 1, 1];
+      let geometry;
+      if (g.shape === "cylinder") {{
+        geometry = new THREE.CylinderGeometry(size[0] / 2, size[2] / 2, size[1], 48);
+      }} else if (g.shape === "sphere") {{
+        geometry = new THREE.SphereGeometry(Math.max(size[0], size[1], size[2]) / 2, 36, 18);
+      }} else if (g.shape === "rod") {{
+        geometry = new THREE.CylinderGeometry(size[0] / 2, size[0] / 2, size[2], 24);
+        geometry.rotateX(Math.PI / 2);
+      }} else if (g.shape === "gear") {{
+        geometry = gearGeometry(THREE, Math.max(size[0], size[2]) / 2, size[1], g.teeth || 18);
+      }} else {{
+        geometry = new THREE.BoxGeometry(size[0], size[1], size[2]);
+      }}
+      const color = colorFor(g.color, index);
+      const material = new THREE.MeshStandardMaterial({{
+        color,
+        metalness: 0.55,
+        roughness: 0.36,
+        emissive: color,
+        emissiveIntensity: 0.05
+      }});
+      return new THREE.Mesh(geometry, material);
+    }}
+
+    function gearGeometry(THREE, radius, depth, teeth) {{
+      const shape = new THREE.Shape();
+      const steps = teeth * 2;
+      for (let i = 0; i <= steps; i++) {{
+        const angle = (i / steps) * Math.PI * 2;
+        const r = radius * (i % 2 === 0 ? 1.0 : 0.84);
+        const x = Math.cos(angle) * r;
+        const y = Math.sin(angle) * r;
+        if (i === 0) shape.moveTo(x, y);
+        else shape.lineTo(x, y);
+      }}
+      const hole = new THREE.Path();
+      hole.absarc(0, 0, radius * 0.28, 0, Math.PI * 2, true);
+      shape.holes.push(hole);
+      const geometry = new THREE.ExtrudeGeometry(shape, {{ depth, bevelEnabled: false }});
+      geometry.center();
+      geometry.rotateX(Math.PI / 2);
+      return geometry;
+    }}
+
+    function colorFor(name, index) {{
+      const key = String(name || "").toLowerCase();
+      if (key.includes("amber") || key.includes("orange")) return 0xe8a33d;
+      if (key.includes("cyan")) return 0x5fd4d0;
+      if (key.includes("steel")) return 0x9aa4a6;
+      const palette = [0x5fd4d0, 0xe8a33d, 0xd9d3c7, 0x80b8ff, 0xf07f5a];
+      return palette[index % palette.length];
+    }}
+
+    function motionCurve(THREE, part) {{
+      const p = part.geometry.position || [0, 0, 0];
+      const points = [];
+      for (let i = 0; i < 48; i++) {{
+        const a = (i / 47) * Math.PI * 2;
+        points.push(new THREE.Vector3(p[0] + Math.cos(a) * 0.52, p[1] + 0.04, p[2] + Math.sin(a) * 0.52));
+      }}
+      return points;
+    }}
+
+    function reveal(mesh, elapsed, index) {{
+      const local = Math.max(0, Math.min(1, (elapsed - index * 0.12) / 0.75));
+      const eased = 1 - Math.pow(1 - local, 3);
+      mesh.scale.setScalar(eased);
+    }}
+
+    function applyMotion(THREE, mesh, elapsed) {{
+      const motion = mesh.userData.part.motion || {{ type: "static" }};
+      const speed = Number(motion.speed ?? 1);
+      const phase = Number(motion.phase ?? 0);
+      const axis = new THREE.Vector3(...(motion.axis || [0, 1, 0])).normalize();
+      mesh.position.copy(mesh.userData.basePosition);
+      mesh.rotation.copy(mesh.userData.baseRotation);
+      if (motion.type === "rotate") {{
+        mesh.rotateOnAxis(axis, elapsed * speed + phase);
+      }} else if (motion.type === "oscillate") {{
+        mesh.rotateOnAxis(axis, Math.sin(elapsed * speed + phase) * Number(motion.amplitude ?? 0.25));
+      }} else if (motion.type === "translate") {{
+        const range = motion.range || [-0.35, 0.35];
+        const offset = range[0] + (range[1] - range[0]) * ((Math.sin(elapsed * speed + phase) + 1) / 2);
+        mesh.position.add(axis.multiplyScalar(offset));
+      }}
+    }}
+
+    function updateLabels(THREE, camera, labelsRoot, parts) {{
+      labelsRoot.replaceChildren();
+      const width = window.innerWidth;
+      const height = window.innerHeight;
+      const entries = [];
+      for (const mesh of parts) {{
+        const pos = mesh.position.clone().project(camera);
+        if (pos.z < -1 || pos.z > 1) continue;
+        entries.push({{
+          x: clamp((pos.x * 0.5 + 0.5) * width, 76, Math.max(76, width - 76)),
+          y: clamp((-pos.y * 0.5 + 0.5) * height, 72, Math.max(72, height - 32)),
+          text: mesh.userData.part.name || mesh.userData.part.id || "part"
+        }});
+      }}
+      entries.sort((a, b) => a.y - b.y);
+      for (let i = 1; i < entries.length; i++) {{
+        entries[i].y = Math.max(entries[i].y, entries[i - 1].y + 38);
+      }}
+      const overflow = entries.length ? entries[entries.length - 1].y - (height - 32) : 0;
+      if (overflow > 0) {{
+        for (const entry of entries) entry.y -= overflow;
+      }}
+      for (const entry of entries) {{
+        const label = document.createElement("div");
+        label.className = "tag";
+        label.style.left = entry.x + "px";
+        label.style.top = entry.y + "px";
+        label.textContent = entry.text;
+        labelsRoot.appendChild(label);
+      }}
+    }}
+
+    function clamp(value, min, max) {{
+      return Math.min(max, Math.max(min, value));
+    }}
+  </script>
+</body>
+</html>"""

snap2sim/ui.py

@@ -0,0 +1,225 @@
+"""Gradio interface for Snap2Sim."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import gradio as gr
+from PIL import Image
+
+from snap2sim.backend import InferenceClient, Settings
+from snap2sim.fallback_scene import build_fallback_html
+from snap2sim.schema import EXAMPLE_ANALYSIS
+
+
+CSS = """
+:root {
+  --snap-bg: #14181F;
+  --snap-panel: #1B222B;
+  --snap-line: rgba(95, 212, 208, 0.22);
+  --snap-amber: #E8A33D;
+  --snap-cyan: #5FD4D0;
+  --snap-text: #D9D3C7;
+  --snap-muted: #8F968F;
+}
+
+.gradio-container {
+  min-height: 100vh;
+  color: var(--snap-text);
+  background:
+    linear-gradient(rgba(95, 212, 208, .055) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(95, 212, 208, .055) 1px, transparent 1px),
+    radial-gradient(circle at 85% 15%, rgba(232, 163, 61, .12), transparent 30%),
+    var(--snap-bg) !important;
+  background-size: 28px 28px, 28px 28px, auto, auto !important;
+  font-family: 'IBM Plex Mono', monospace !important;
+}
+
+.snap-shell {
+  max-width: 1540px;
+  margin: 0 auto;
+}
+
+.snap-title h1 {
+  margin: 0 0 4px;
+  color: var(--snap-text);
+  font-family: 'Archivo Narrow', sans-serif;
+  font-size: clamp(38px, 5vw, 76px);
+  line-height: .9;
+  letter-spacing: 0;
+  text-transform: uppercase;
+}
+
+.snap-title p {
+  max-width: 860px;
+  color: var(--snap-muted);
+  font-size: 14px;
+  line-height: 1.6;
+}
+
+.snap-frame {
+  border: 1px solid var(--snap-line);
+  background: rgba(20, 24, 31, .8);
+  box-shadow: inset 0 0 0 1px rgba(232, 163, 61, .06);
+}
+
+.snap-frame label,
+.snap-frame .label-wrap span {
+  color: var(--snap-cyan) !important;
+  font-family: 'IBM Plex Mono', monospace !important;
+  text-transform: uppercase;
+}
+
+.snap-frame textarea,
+.snap-frame input {
+  background: #10141A !important;
+  color: var(--snap-text) !important;
+  border-color: var(--snap-line) !important;
+  font-family: 'IBM Plex Mono', monospace !important;
+}
+
+.snap-run {
+  border: 1px solid rgba(232, 163, 61, .7) !important;
+  background: linear-gradient(180deg, #F0B65B, #C97923) !important;
+  color: #16130E !important;
+  font-family: 'Archivo Narrow', sans-serif !important;
+  font-size: 18px !important;
+  font-weight: 700 !important;
+  text-transform: uppercase;
+  border-radius: 2px !important;
+}
+
+.snap-run:hover {
+  filter: brightness(1.08);
+}
+
+.snap-status {
+  min-height: 42px;
+  color: var(--snap-amber);
+  font-size: 13px;
+  text-transform: uppercase;
+}
+
+.snap-html iframe,
+.snap-html > div {
+  min-height: 560px;
+}
+
+.snap-scene-frame {
+  display: block;
+  width: 100%;
+  min-height: 560px;
+  border: 0;
+  background: #14181F;
+}
+
+.snap-json pre {
+  color: var(--snap-text) !important;
+  background: #10141A !important;
+}
+
+.snap-explain {
+  color: var(--snap-text);
+  line-height: 1.65;
+}
+"""
+
+
+def format_explanation(analysis: dict[str, Any]) -> str:
+    parts = analysis.get("parts", [])
+    part_lines = "\n".join(
+        f"- **{part.get('name', 'part')}**: {part.get('role', 'role unknown')}"
+        for part in parts
+    )
+    sequence = "\n".join(f"{index + 1}. {step}" for index, step in enumerate(analysis.get("motion_sequence", [])))
+    return (
+        f"### {analysis.get('component', 'Component')}\n\n"
+        f"{analysis.get('summary', '')}\n\n"
+        f"**Trigger:** {analysis.get('trigger', 'unknown')}\n\n"
+        f"**Motion sequence**\n{sequence}\n\n"
+        f"**Parts**\n{part_lines}"
+    )
+
+
+def initial_status() -> str:
+    settings = Settings()
+    if settings.backend == "modal":
+        configured = bool(settings.analyze_url and settings.generate_url)
+        return "STANDBY: MODAL BACKEND CONFIGURED" if configured else "STANDBY: MODAL BACKEND MISSING URLS"
+    return "STANDBY: LOCAL PLACEHOLDER BACKEND"
+
+
+def run_pipeline(image: Image.Image | None) -> tuple[str, str, str, str]:
+    client = InferenceClient(Settings())
+    try:
+        analysis = client.analyze_image(image)
+        html = client.generate_threejs(analysis)
+        status = "CUTAWAY READY"
+    except Exception as exc:
+        analysis = dict(EXAMPLE_ANALYSIS)
+        html = build_fallback_html(str(analysis.get("component", "mechanism")))
+        status = f"FALLBACK RENDER ACTIVE: {exc}"
+
+    return (
+        html,
+        format_explanation(analysis),
+        json.dumps(analysis, indent=2),
+        status,
+    )
+
+
+def build_app() -> gr.Blocks:
+    with gr.Blocks(css=CSS, title="Inside the Machine") as demo:
+        with gr.Column(elem_classes=["snap-shell"]):
+            gr.HTML(
+                """
+                <link rel="preconnect" href="https://fonts.googleapis.com">
+                <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+                <link href="https://fonts.googleapis.com/css2?family=Archivo+Narrow:wght@500;700&family=IBM+Plex+Mono:wght@400;500;700&display=swap" rel="stylesheet">
+                <section class="snap-title">
+                  <h1>Inside the Machine</h1>
+                  <p>Upload a component photo. Snap2Sim drafts a mechanical teardown,
+                  then renders an annotated cutaway animation for repair cafes,
+                  shop classrooms, and curious builders.</p>
+                </section>
+                """
+            )
+
+            with gr.Row(equal_height=False):
+                with gr.Column(scale=5, elem_classes=["snap-frame"]):
+                    scene = gr.HTML(
+                        build_fallback_html("waiting for upload"),
+                        label="Cutaway viewport",
+                        elem_classes=["snap-html"],
+                    )
+                with gr.Column(scale=3, elem_classes=["snap-frame"]):
+                    image = gr.Image(type="pil", label="Component photo")
+                    run = gr.Button("Analyze Assembly", elem_classes=["snap-run"])
+                    status = gr.Textbox(
+                        value=initial_status(),
+                        label="Workshop status",
+                        interactive=False,
+                        elem_classes=["snap-status"],
+                    )
+                    explanation = gr.Markdown(
+                        "Upload a photo and run the analyzer.",
+                        elem_classes=["snap-explain"],
+                    )
+
+            with gr.Accordion("Structured mechanism JSON", open=False):
+                raw_json = gr.Code(
+                    value="{}",
+                    language="json",
+                    label="Vision-to-scene contract",
+                    elem_classes=["snap-json"],
+                )
+
+            run.click(
+                fn=run_pipeline,
+                inputs=[image],
+                outputs=[scene, explanation, raw_json, status],
+                show_progress="full",
+            )
+
+    return demo