prompts/PRESENTATION_PROMPT.md

# PRESENTATION_PROMPT.md

Final status, 2026-06-15: the deck has been built at `presentation/deck.html`,
the project is public under `build-small-hackathon/Snap2Sim`, and the final
public links are:

- Demo video: https://youtu.be/nuisDKMyyF8
- X post: https://x.com/Ryno67114241/status/2066660199558152411

> Build instructions for Codex. Goal: produce a **self-contained HTML slide deck**
> that markets Snap2Sim — "Inside the Machine" to **Build Small Hackathon judges**.
> Tone: interesting, intuitive, fun, concise, beautifully formatted. This file is
> a spec, not the deck. Follow the deliverable + slide plan below.

---

## 1. Deliverable

Create `presentation/deck.html` — a single, **self-contained** reveal.js deck.

- Use the [reveal.js](https://revealjs.com/) CDN (`<script src="https://cdn.jsdelivr.net/npm/reveal.js@5/dist/reveal.js">` + matching CSS), so there is **no build step**. Opens in any browser.
- Put any standalone assets (exported screenshots, fonts you self-host if needed) in `presentation/assets/`. Prefer inline SVG over external images so the deck stays portable.
- The architecture diagram must be **inline SVG (or Mermaid rendered to inline SVG)** so the deck has no broken-image risk during a live demo.
- Keyboard nav, speaker notes (`data-notes` / the reveal notes plugin), and a PDF export path (`?print-pdf`) should all work.
- No external API calls, no tracking, no network dependency beyond the reveal.js + font CDNs.

### Match the product's visual identity (this is a "technical field-manual / cutaway" aesthetic)

Pull the theme straight from `index.html` so the deck feels like the same product:

```
--bg:        #0F1318   (near-black blue)
--bg-panel:  #161B22
--bg-lift:   #1E2530
--amber:     #E8A33D   (primary accent — headings, key numbers)
--cyan:      #5FD4D0   (secondary accent — labels, links, diagram lines)
--text:      #C8C0AC   (warm off-white body)
--text-muted:#9CA3AF
--danger:    #F07F5A
--grid:      rgba(255,255,255,0.04)
```

- Fonts: **"Chakra Petch"** for headings/UI and **"Fira Code"** (monospace) for data, labels, code, and stat callouts. Load from Google Fonts.
- Texture cues to carry over from the app: faint blueprint **grid background**, thin **cyan scan-line / divider rules**, amber section kickers, a subtle vignette. Keep it tasteful — readability first, one or two motion flourishes max.
- Every slide: small monospace **kicker label** top-left (e.g. `01 · THE PROBLEM`) and a faint `SNAP2SIM // INSIDE THE MACHINE` watermark. This mirrors the in-app component watermark + reticle styling.

---

## 2. Slide plan (in order)

The user explicitly required slides 1–3 in this order. Build the full deck below.

### Slide 1 — The Problem (REQUIRED, first)
Lead with the product's own hook, verbatim, as the emotional opening:

> "You find a small metal cylinder at a flea market. What is it? How does it work inside?"

Then frame the problem crisply:
- Curious makers, repair hobbyists, thrift scavengers, and robotics students constantly hold **mystery hardware** and can't see what's happening inside.
- Existing image AI **stops at a label** ("this is a valve") — it never answers the real question: *what moves, and why?*
- Teardowns, manuals, and exploded diagrams are scattered, intimidating, or don't exist for that exact part.

Keep it to 3 tight bullets + the hook. Don't over-explain.

### Slide 2 — The Solution (REQUIRED, second)
One-line positioning statement (make it pop in amber):

> **Snap a photo. Watch the mechanism come alive.**

Then: Snap2Sim turns a single photo of a hardware component into a **narrated, animated 3D mechanical cutaway** — it names the internal parts and shows the hidden motion: the plunger sliding, the spring loading, the rotor spinning, the pawl catching, the port opening.

Three short "what you get" pillars (use icon-ish monospace chips):
1. **Identify** — the likely mechanism + confidence, not just a class name.
2. **Explain** — internal parts, the trigger, and the motion sequence in plain language.
3. **Animate** — a moving Three.js field-manual cutaway you can orbit, zoom, and reset.

Add the honesty angle as a one-liner: when a confident 3D reconstruction isn't justified, it **falls back to annotated callouts on the original photo instead of pretending.** (Judges love that it doesn't hallucinate geometry.)

### Slide 3 — How It Works / Architecture Diagram (REQUIRED, third)
An **inline SVG** flow diagram of the real pipeline. Nodes and flow (left → right), styled with cyan connectors and amber node borders on dark panels:

```
[ Photo upload ]
      │  same-origin POST /analyze_image
      ▼
[ Hugging Face Space  (gradio.Server, cpu-basic) ]
      │  bearer-token, server-side secret
      ▼
[ Modal GPU endpoint ]
      │  llama.cpp + llama-mtmd-cli
      ▼
[ NVIDIA Nemotron 3 Nano Omni 30B-A3B GGUF (UD-Q4_K_M + mmproj-F16) ]
      │  returns structured mechanism JSON
      ▼
[ /generate_scene → JSON schema validation → render-mode select ]
      │
      ▼
[ Browser renders DETERMINISTIC Three.js cutaway ]  ──(low confidence)──▶ [ Annotated-photo fallback ]
```

Caption the key architectural decision under the diagram:
> **The model describes the mechanism. The browser owns the rendering.** No model-authored HTML/JS ever touches the page — that keeps the demo reliable and safe.

If you use Mermaid, render it to inline SVG at build time or load Mermaid from CDN and let it render on slide-ready; either way it must display with zero external image files.

### Slide 4 — Live Demo / "The Moment"
- Frame the demo: photo in → cutaway out, in seconds.
- Use the in-theme demo mockup currently in the deck, or replace it later with intentionally captured product screenshots in `presentation/assets/`.
- Callout the interactivity: orbit / zoom / reset, play-pause, confidence slider.
- Speaker note: "Drop in a valve, lock, pump, gear train, fan, or latch."

### Slide 5 — What Makes It Different
Tight comparison. Most image demos stop at a label; Snap2Sim answers *"what would I see if I cut this open?"*
- Mechanism explanation, not a class name.
- Maps internal parts into a moving technical cutaway.
- Honest uncertainty: confidence threshold + photo-annotation fallback.
- Custom branded maker tool, not a default chat/form UI.
- Secrets + GPU endpoints stay server-side; client calls only same-origin APIs.

### Slide 6 — Tech Stack & Hackathon Fit (the judge-credibility slide)
Two columns.

**Stack** (monospace list):
- Frontend: plain `index.html` + CSS + JS served by `gradio.Server`.
- Rendering: deterministic Three.js primitives (box, cylinder, cone, capsule, sphere, rod, gear, torus, spring), OrbitControls, camera fitting, annotated-photo fallback.
- Model: NVIDIA Nemotron 3 Nano Omni 30B-A3B GGUF (~30B total / ~3B active per MoE token — **under the 32B budget**) via llama.cpp.
- GPU: Modal, weights cached in a Modal Volume, bearer-token protected.
- Contract: JSON schema validation before anything renders.

**Badges we're claiming** (render as themed chips; confirmed ones in amber):
| Badge | Status |
|---|---|
| Backyard AI (track) | core fit |
| Llama Champion | confirmed |
| NVIDIA Nemotron Quest | confirmed |
| Modal Award | confirmed |
| Off-Brand | confirmed |
| OpenAI Codex | confirmed |
| Best Demo / Sharing is Caring | confirmed with public demo video + X post |
| Off the Grid | not claimed (inference runs on Modal) |

### Slide 7 — Closing / Call to Action
- Restate the one-liner: **Snap a photo. See inside the machine.**
- Links: GitHub source of truth `https://github.com/Bigstonks1/Snap2Sim`; Hugging Face Space `https://huggingface.co/spaces/build-small-hackathon/Snap2Sim` (public submission Space under the Build Small Hackathon organization).
- Credit line: "Built by Jason Do with implementation assistance from OpenAI Codex."
- End on the hook image/line for symmetry with slide 1.

---

## 3. Findings from the codebase review (source material — all verified in-repo)

Use these as the factual backbone. Do **not** invent metrics or claims beyond these.

- **Product**: Snap2Sim / "Inside the Machine" — photo of a hardware component → identified mechanism → animated 3D technical cutaway with named internal parts, trigger, and motion sequence. (`README.md`, `AGENTS.md`)
- **The hook** (keep verbatim, per AGENTS.md final-state notes — do not alter): *"You find a small metal cylinder at a flea market. What is it? How does it work inside?"*
- **Audience**: garage tinkerers, repair hobbyists, thrift-store scavengers, robotics students — "people who learn by taking things apart." (`README.md` Hackathon Fit)
- **Pipeline** (`README.md` How It Works): browser → same-origin `/analyze_image` on the HF Space → secured Modal endpoint → Nemotron via llama.cpp/`llama-mtmd-cli` → structured mechanism JSON → `/generate_scene` validates + picks render mode → browser renders deterministic Three.js, or annotated-photo fallback.
- **Key safety/architecture decision**: "The model describes the mechanism. The browser owns the rendering." No model-authored HTML/JS injection. Schema validation in `snap2sim/schema.py` gates rendering. (`README.md`, `AGENTS.md`)
- **Renderer vocabulary** (`snap2sim/prompts.py`, `snap2sim/schema.py`): shapes = box, cylinder, cone, capsule, sphere, rod, gear, torus, spring; motions = static, rotate, oscillate, translate, screw, orbit, pulse; 2–6 parts per scene.
- **Honesty features**: confidence threshold slider (default 0.5), render-mode selection (`three` / `annotate` / `unavailable`), annotated-photo fallback with numbered markers + leader lines. (`docs/features/`)
- **Model**: `unsloth/NVIDIA-Nemotron-3-Nano-Omni-30B-A3B-Reasoning-GGUF`, quant `UD-Q4_K_M` + `mmproj-F16.gguf`. ~30B total / ~3B active per MoE token → under the hackathon's 32B budget. (`README.md` Tech Stack)
- **Infra**: HF Space on `cpu-basic`; GPU inference on Modal with Modal Volume asset caching; bearer-token auth between Space and Modal (secret `snap2sim-api-auth` / `SNAP2SIM_API_TOKEN`); unauthenticated requests return `401`. Space is public for submission. (`AGENTS.md`, `SECURITY.md`)
- **Security posture** (`docs/reviews/security-hardening.md`): rate limiting on both endpoints, upload-size caps, PIL decompression-bomb handling, temp-file cleanup, no model-authored scene HTML.
- **Badges** confirmed per AGENTS.md: Llama Champion, NVIDIA Nemotron Quest, Modal Award, Off-Brand, OpenAI Codex, Best Demo, and Sharing is Caring. Off the Grid is explicitly **not** claimed (Modal inference).
- **Visual identity tokens**: see Section 1 (sourced from `index.html`).
- **Credit**: Built by Jason Do with implementation assistance from OpenAI Codex. Commit trailer convention: `Co-authored-by: OpenAI Codex <codex@openai.com>`.

### Marketing angles worth leaning into (for tone)
- The emotional payoff: "the moment a curious maker gets to **see the hidden motion**." (Pulled from README — this is the strongest line in the repo.)
- "Most image demos stop at a label. Snap2Sim answers the next question: *what would I see if I cut this open?*"
- The honesty differentiator: it shows uncertainty instead of hallucinating geometry. Judges reward this.

---

## 4. Completed build order

The requested deck was built and synced with the public Space. The original
build order is retained below for traceability.

1. Scaffold `presentation/deck.html` with reveal.js CDN, the theme tokens from Section 1, Chakra Petch + Fira Code fonts, grid/scan-line/vignette texture, and the per-slide kicker + watermark chrome.
2. Build slides 1–3 exactly as specified (Problem → Solution → inline-SVG architecture diagram). These are the required core.
3. Build the inline-SVG (or CDN-Mermaid-to-SVG) pipeline diagram for slide 3 from the flow in Section 2.
4. Add slides 4–7.
5. Keep the in-theme demo mockup on slide 4 unless real product screenshots are intentionally captured and added later.
6. Verify: open in a browser, arrow through all slides, confirm the diagram renders inline with no broken images, confirm `?print-pdf` exports cleanly, confirm no horizontal overflow at 1280×720 and 1920×1080.
7. Keep all private endpoint URLs and tokens **out** of the deck; only public
   GitHub, Hugging Face Space, demo video, and social links belong in public
   presentation materials.
8. Do not claim Off the Grid while inference runs on Modal. Best Demo and
   Sharing is Caring now have public demo and X post links.

### Final public links
- Space is public under `build-small-hackathon/Snap2Sim`.
- Demo video: https://youtu.be/nuisDKMyyF8
- X post: https://x.com/Ryno67114241/status/2066660199558152411