feat: pose model selector + overlay visualizer

.claude/settings.local.json

@@ -1,20 +1,48 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(git -C /Users/bolyos/Development/FormScout status)",
-      "Bash(git init *)",
-      "Bash(git add *)",
-      "Bash(git commit *)",
-      "Bash(huggingface-cli version *)",
-      "Bash(huggingface-cli whoami *)",
-      "Bash(hf auth *)",
-      "Bash(hf whoami *)",
-      "Bash(git remote *)",
-      "Bash(git push *)",
-      "Bash(git fetch *)",
-      "Bash(git pull *)",
-      "Bash(git lfs *)",
-      "Bash(hf upload *)"
-    ]
-  }
-}
+{
+  "permissions": {
+    "allow": [
+      "Bash(git -C /Users/bolyos/Development/FormScout status)",
+      "Bash(git init *)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(huggingface-cli version *)",
+      "Bash(huggingface-cli whoami *)",
+      "Bash(hf auth *)",
+      "Bash(hf whoami *)",
+      "Bash(git remote *)",
+      "Bash(git push *)",
+      "Bash(git fetch *)",
+      "Bash(git pull *)",
+      "Bash(git lfs *)",
+      "Bash(hf upload *)",
+      "Bash(git merge *)",
+      "Bash(git checkout *)",
+      "Bash(git stash *)",
+      "Bash(python -m pytest tests/test_phase2.py tests/test_types.py tests/test_biomechanics.py -q --tb=short)",
+      "Bash(python3 -m pytest tests/test_phase2.py tests/test_types.py tests/test_biomechanics.py -q --tb=short)",
+      "Bash(python3 *)",
+      "Bash(/Users/bolyos/Development/FormScout/.venv/bin/pip install *)",
+      "Bash(.venv/bin/pip install *)",
+      "Bash(.venv/bin/pytest tests/ -q --tb=short)",
+      "WebFetch(domain:huggingface.co)",
+      "Bash(brew list *)",
+      "Read(//opt/homebrew/bin/**)",
+      "Read(//usr/local/bin/**)",
+      "Bash(pip install *)",
+      "Skill(run)",
+      "Bash(pkill -f \"python3 app.py\")",
+      "Bash(python3 app.py)",
+      "Bash(echo \"PID: $!\")",
+      "Bash(pytest *)",
+      "Bash(ffmpeg -version)",
+      "Bash(file /Users/bolyos/.cache/huggingface/hub/models--qualcomm--MediaPipe-Pose-Estimation/blobs/*)",
+      "Bash(curl -L \"https://storage.googleapis.com/mediapipe-models/pose_landmarker/pose_landmarker_full/float16/latest/pose_landmarker_full.task\" -o /Users/bolyos/Development/FormScout/checkpoints/mediapipe/pose_landmarker_full.task)",
+      "Bash(/opt/homebrew/bin/brew list *)",
+      "Bash(/opt/homebrew/bin/git-lfs version *)",
+      "Read(//usr/local/Cellar/**)",
+      "Read(//usr/**)",
+      "Bash(git ls-remote *)",
+      "Bash(git ls-tree *)"
+    ]
+  }
+}

.gitattributes

@@ -35,3 +35,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
 docs/FormScout-FMS-Spec.md.pdf filter=lfs diff=lfs merge=lfs -text
 docs/plans/FormScout-Build-Prompt.md.pdf filter=lfs diff=lfs merge=lfs -text
+checkpoints/mediapipe/pose_landmarker_full.task filter=lfs diff=lfs merge=lfs -text

CLAUDE.md

@@ -1,149 +1,176 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project overview
-
-FormScout is a Gradio app (Hugging Face Space) that scores Functional Movement Screen (FMS) videos 0–3 per test with a written rationale and an annotated overlay. It is a **screening aid** — not a diagnosis, not an injury predictor. Built for the Build Small Hackathon (Backyard AI track). Full product spec is in `docs/FormScout-FMS-Spec.md`; the engineering contract is in `docs/plans/FormScout-Build-Prompt.md`.
-
-## Common commands
-
-Once the project is scaffolded:
-
-```bash
-# Headless pipeline test (no Gradio)
-python -m formscout.run sample.mp4
-
-# Run the Gradio app locally
-python app.py
-
-# Run all tests
-pytest tests/
-
-# Run a single test
-pytest tests/test_biomechanics.py::test_deep_squat_score
-
-# Lint / format (Python)
-ruff check . && ruff format .
-
-# Run Svelte component tests
-npx vitest run
-```
-
-## Architecture
-
-The pipeline is a sequence of **typed specialist agents**. Each agent accepts and returns a frozen dataclass from `formscout/types.py`. The Director in `formscout/pipeline.py` orchestrates them as a deterministic state machine (not an LLM) and applies quality gating.
-
-### The tiering rule (most important invariant)
-
-**The 2D path is the default and must stand alone as a complete, functional pipeline.** `Body3DAgent` is only activated when `config.enable_3d == True` AND the checkpoint loads successfully. If 3D is off, unavailable, or fails for any reason, `Body3DResult(used=False, ...)` is returned — this is a normal success path, not an error. `BiomechFeatures.view` is `"2d"` or `"3d"` so the `JudgeAgent` can caveat its rationale appropriately. Never put `Body3DAgent` on the critical path.
-
-### Build dependency order
-
-```
-types.py → IngestAgent → SegmentationAgent → Pose2DAgent
-→ [Body3DAgent — optional] → MovementClassifierAgent → BiomechanicsAgent
-→ ScoringAgent → RetrievalAgent → JudgeAgent → ReportAgent → Director
-```
-
-**Minimum working slice (build first):** Ingest → Pose2D → Biomechanics → Judge → Report
-
-### Target repo structure
-
-```
-formscout/
-  app.py                    # Gradio entrypoint
-  formscout/
-    config.py               # model IDs, thresholds, feature flags — no scattered literals
-    pipeline.py             # Director: orchestrates agents, quality-gates
-    run.py                  # headless CLI entrypoint
-    agents/
-      prompts/              # C1 (classifier) and C2 (judge) runtime system prompts — version-controlled
-    rubric/                 # one pure-function scorer per FMS test (deep_squat.py, etc.)
-    types.py                # frozen dataclasses for every agent I/O contract
-    serving/llama_cpp.py    # llama.cpp client wrappers + transformers fallbacks
-    ui/                     # Gradio theme, Svelte custom components, CSS
-    tracing.py              # structured per-agent I/O logging
-  tests/
-  requirements.txt
-  MODEL_BUDGET.md           # running param sum — must stay ≤ 32B
-  RECON.md                  # Phase 0 model/API verification findings
-```
-
-### Model stack (~18B total — stay under 32B)
-
-| Component | Model | Params | HF Access |
-|---|---|---|---|
-| 2D pose (primary) | YOLO26-Pose L/X | ~0.05B | Public (verify AGPL-3.0 implications) |
-| 2D pose (fallback) | `noahcao/sapiens-pose-coco` | — | **Accepted** |
-| Segmentation | `facebookresearch/sam3` (SAM 3.1 base) | ~0.85B | **Accepted** |
-| 3D biomechanics | `facebook/sam-3d-body-dinov3` | ~0.7–1B | **Pending** |
-| Learned scoring | ST-GCN via pyskl (fine-tuned) | ~0.01–0.05B | Apache-2.0 |
-| Judge + Classifier | Qwen3-VL-8B-Instruct (llama.cpp) | 8B | Public |
-| Retrieval | Qwen3-VL-Embedding-8B (llama.cpp) | 8B | Public |
-
-Track the running sum in `MODEL_BUDGET.md`. The two Qwen3-VL-8B models share a backbone. `config.pose_backend` switches between YOLO and Sapiens. ST-GCN training lives in a separate `train_scoring.py`.
-
-**Open question:** whether "≤ 32B" means per-model or summed across the pipeline — confirm via the hackathon Discord AMA. Design for the summed reading (safe either way).
-
-**SAM 3D Body access is pending.** `facebook/sam-3d-body-dinov3` is gated; access was requested June 2026 but not yet granted. Until it arrives, the 2D path is the only path — `Body3DAgent` must immediately return `Body3DResult(used=False, ...)` when `config.enable_3d` is off or the checkpoint is unavailable.
-
-## Key constraints and invariants
-
-- **No cloud model APIs.** All inference runs on-Space (ZeroGPU). No OpenAI/Anthropic/Gemini calls.
-- **Pain is never auto-scored.** Any clearing test or visible distress sets `needs_human=true` — enforced in rubric functions and `JudgeAgent`.
-- **Quality gates (Director, never silently skip):**
-  - Any agent `confidence < config.min_confidence` → mark "low confidence — physio review"
-  - `|ScoringAgent.score - JudgeAgent.score| >= 1` → mark disagreement, require review
-  - `MovementResult.test == "unknown"` → stop pipeline, surface manual override to user
-  - `JudgeAgent.needs_human == True` → no numeric score emitted for that test
-- **Composite is null** when any test is unscored (pain/unknown/deferred). Never show a partial 0–21 as complete.
-- **Bilateral tests** (Hurdle Step, In-Line Lunge, Shoulder Mobility, ASLR): score each side, report the lower, always emit the asymmetry even when scores are equal.
-- **Rubric functions are pure.** Each scorer in `rubric/` is `(features) -> ScoreResult` with no model calls.
-- **Runtime prompts are tunable artifacts.** C1 (movement classifier) and C2 (judge) live in `formscout/agents/prompts/` under version control. Most scoring quality lives in C2.
-- **Pipeline runs headless.** No Gradio imports in any agent file.
-
-## Engineering standards
-
-- Every agent: one public entrypoint, typed dataclass I/O from `types.py`, `confidence: float` and `notes: str` on every result.
-- Models load once at module/instance init — never inside the inference hot path.
-- Every agent module docstring states: purpose, inputs, outputs, failure behavior, model param count, license, and gated status.
-- All model IDs, thresholds, k-values, and feature flags live in `config.py`.
-- `tracing.py` records structured per-agent I/O for any run; one full run gets exported to the Hub.
-- Every agent ships with a pytest in `tests/` that runs on the committed sample fixture and asserts the typed contract.
-- Fix random seeds; cache model loads at startup; warm the pipeline before demo.
-
-## Gradio + Svelte UI guidance
-
-The UI uses **Gradio `gr.Blocks`** with **custom Svelte components** for bespoke UI elements (score dial, asymmetry bars, rubric drawer). Use `gradio-svelte-expert` agent for Svelte component work.
-
-- Default approach: `gr.Blocks` + custom CSS/theme. Escalate to `gradio.Server` only if Blocks can't express the UI.
-- Use `gr.Video`'s `playback_position` to jump the overlay to the decisive frame.
-- Use `gr.Walkthrough`/`gr.Step` for the 7-test session flow; `gr.Navbar` if splitting pages.
-- ZeroGPU: wrap heavy inference in `@spaces.GPU`; load models once at module scope.
-- A **"Screening aid — not a diagnosis. Pain or clearing tests require a clinician."** banner must always be visible.
-- Verify Gradio APIs against current docs before use — the ecosystem moves fast. Pin exact versions in `requirements.txt`.
-- Python: `ruff` + `black`. Svelte: Prettier. Tests: `pytest` (Python), `vitest` + `@testing-library/svelte` (Svelte).
-
-## Build phases
-
-No code exists yet. Start with Phase 0. Do not write implementation code before completing Phase 0 recon.
-
-1. **Phase 0 — Recon:** Verify all models (license, param count, GGUF, ZeroGPU compatibility). Write `RECON.md`. Confirm Gradio version. Confirm SAM 3D Body access status.
-2. **Phase 1 — Spine:** One test (Deep Squat) end-to-end: `video in → score + rationale + overlay`. Headless + Gradio. Deterministic rubric only.
-3. **Phase 2 — All 7 tests:** `MovementClassifierAgent`, `JudgeAgent`, `ReportAgent`, composite scorecard, asymmetry view, PDF export.
-4. **Phase 3 — Learned scoring + retrieval:** ST-GCN fine-tune on physio clips, publish to Hub. Embedding index for RAG via `RetrievalAgent`.
-5. **Phase 4 — Polish + ship:** Custom UI (scout/trail theme), agent trace published to Hub, blog post, demo video.
-
-## Badge checklist (definition of done)
-
-- [ ] Space runs green; upload → scorecard works on real clips
-- [ ] Param sum verified ≤ 32B in `MODEL_BUDGET.md`
-- [ ] 🔌 **Off the Grid** — no cloud model APIs anywhere in the pipeline
-- [ ] 🎯 **Well-Tuned** — fine-tuned ST-GCN head published to Hub with honest model card
-- [ ] 🎨 **Off-Brand** — custom, non-default Gradio UI (scout/trail theme)
-- [ ] 🦙 **Llama Champion** — VLM + embedder served via llama.cpp (GGUF)
-- [ ] 📡 **Sharing is Caring** — one full agent trace (all I/O) published to Hub
-- [ ] 📓 **Field Notes** — blog post written, honesty section (FMS limitations) front-and-center
-- [ ] Demo video + social post recorded
-- [ ] Safety banner present; pain/clearing never auto-scored; low-confidence flagged
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project overview
+
+FormScout is a Gradio app (Hugging Face Space) that scores Functional Movement Screen (FMS) videos 0–3 per test with a written rationale and an annotated overlay. It is a **screening aid** — not a diagnosis, not an injury predictor. Built for the Build Small Hackathon (Backyard AI track). Full product spec is in `docs/FormScout-FMS-Spec.md`; the engineering contract is in `docs/plans/FormScout-Build-Prompt.md`.
+
+**Current status:** Phase 2 complete. All 7 FMS test rubric scorers, JudgeAgent, MovementClassifierAgent, and ReportAgent are implemented and tested (45/46 passing). Phase 3 is next (ST-GCN fine-tune + RAG retrieval).
+
+## Common commands
+
+```bash
+# Run the Gradio app locally
+python3 app.py
+
+# Headless pipeline test (no Gradio)
+python3 -m formscout.run sample.mp4
+
+# Run all tests
+pytest tests/
+
+# Run a single test file or test
+pytest tests/test_phase2.py
+pytest tests/test_biomechanics.py::TestBiomechanicsAgent::test_deep_squat_score
+
+# Lint / format
+ruff check . && ruff format .
+
+# Run Svelte component tests (when frontend work is added)
+npx vitest run
+```
+
+## Architecture
+
+The pipeline is a sequence of **typed specialist agents**. Each agent accepts and returns a frozen dataclass from `formscout/types.py`. The Director in `formscout/pipeline.py` orchestrates them as a deterministic state machine (not an LLM).
+
+### Agent pipeline
+
+```
+IngestAgent → Pose2DAgent → [Body3DAgent — optional]
+→ MovementClassifierAgent → BiomechanicsAgent
+→ rubric/score_test() → JudgeAgent → ReportAgent
+```
+
+The **Director** (`pipeline.py`) owns the flow. `app.py` creates one `Director()` instance and calls `director.run(video_path, test_name, side)` per submission. The Gradio UI passes `test_name` directly (from dropdown), bypassing the classifier.
+
+### The tiering rule (most important invariant)
+
+**The 2D path is the default and must stand alone as a complete, functional pipeline.** `Body3DAgent` is only activated when `config.ENABLE_3D == True` AND the checkpoint loads successfully. If 3D is off or fails, `Body3DResult(used=False, ...)` is returned — this is a normal success path, not an error. `BiomechFeatures.view` is `"2d"` or `"3d"` so the `JudgeAgent` can caveat its rationale appropriately. Never put `Body3DAgent` on the critical path.
+
+### Feature flags in `config.py` and their current state
+
+| Flag | Default | Meaning |
+|------|---------|---------|
+| `ENABLE_JUDGE` | `False` | When False, JudgeAgent falls back to rubric score — no llama.cpp needed |
+| `ENABLE_3D` | `False` | When False, Body3DAgent returns `used=False` immediately |
+| `ENABLE_STGCN` | `False` | Phase 3 — ST-GCN learned scoring head |
+| `ENABLE_RAG` | `False` | Phase 3 — RetrievalAgent exemplar lookup |
+
+All model IDs, thresholds, k-values, and feature flags live in `config.py` — never scattered literals.
+
+### Fallback chain (important for local dev and Spaces)
+
+1. `ENABLE_JUDGE=False` → JudgeAgent returns rubric score wrapped as JudgeResult (no VLM needed)
+2. `ENABLE_JUDGE=True` + llama.cpp server unreachable → same fallback, logs a warning
+3. `ENABLE_JUDGE=True` + server available → calls Qwen3-VL-8B-Instruct at `127.0.0.1:8080`
+
+This means the app is **fully functional without any GPU or llama.cpp** — rubric scoring is pure Python.
+
+### Rubric scorers
+
+Each FMS test has a pure-function scorer in `formscout/rubric/`:
+
+```
+score_deep_squat / score_hurdle_step / score_inline_lunge /
+score_shoulder_mobility / score_active_slr /
+score_trunk_stability_pushup / score_rotary_stability
+```
+
+All accept `BiomechFeatures` and return `ScoreResult`. Dispatch via `rubric.score_test(features)`. **Rubric functions must remain pure** — no model calls, no I/O.
+
+### Bilateral tests
+
+`hurdle_step`, `inline_lunge`, `shoulder_mobility`, `active_slr` are bilateral. `ReportAgent` groups them by test name, takes the **lower** score, and always emits the asymmetry delta even when scores are equal. `composite` is `None` when any test is unscored.
+
+### Types contract
+
+Every agent I/O is a frozen dataclass from `formscout/types.py`. Key types:
+
+- `IngestResult` — decoded frames (np.ndarray list), fps, duration, dimensions
+- `Pose2DResult` — per-frame keypoints as `dict[int, {x, y, conf}]` (COCO 17 joints)
+- `Body3DResult` — optional 3D joints, always has `used: bool`
+- `MovementResult` — `test_name` (validated enum), `side` ("left"|"right"|"na")
+- `BiomechFeatures` — `angles: dict`, `alignments: dict`, `view: "2d"|"3d"`, `symmetry_delta`
+- `ScoreResult` — `score: int` (0–3), `rationale`, `needs_human`
+- `JudgeResult` — same as ScoreResult + `compensation_tags`, `corrective_hint`; `score=None` when `needs_human=True`
+- `PipelineState` — mutable accumulator threaded through the Director
+
+`MovementResult` and `JudgeResult` validate their fields in `__post_init__` — passing invalid values raises immediately.
+
+### YOLO checkpoint location
+
+`config.YOLO_POSE_MODEL` points to `checkpoints/yolo26/yolo26l-pose.pt` (absolute path). Both `yolo26l-pose.pt` and `yolo26x-pose.pt` are committed to the repo. Models load once at module scope via `_get_model()` in `pose2d.py`.
+
+### llama.cpp serving
+
+`formscout/serving/llama_cpp.py` provides `LlamaCppClient` (VLM, port 8080) and `EmbeddingClient` (embeddings, port 8081). Both check `/health` before use and return safe error dicts when unavailable. Only active when the corresponding `ENABLE_*` flag is True.
+
+## Key constraints and invariants
+
+- **No cloud model APIs.** All inference runs on-Space (ZeroGPU). No OpenAI/Anthropic/Gemini calls.
+- **Pain is never auto-scored.** Any clearing test or visible distress sets `needs_human=True` — enforced in rubric functions and JudgeAgent. `JudgeResult.score` must be `None` when `needs_human=True`.
+- **Quality gates (Director, never silently skip):**
+  - Any agent `confidence < config.MIN_CONFIDENCE` (0.6) → warn or stop
+  - `|rubric.score - judge.score| >= 1` → flag disagreement
+  - `MovementResult.test_name == "unknown"` → stop pipeline, surface manual override
+  - `JudgeAgent.needs_human == True` → no numeric score emitted
+- **Composite is null** when any test is unscored. Never show a partial 0–21 as complete.
+- **Pipeline runs headless.** No Gradio imports in any agent file.
+- **Safety banner** ("Screening aid — not a diagnosis…") must always be visible in the UI — appears at top and bottom of `app.py`.
+
+## Engineering standards
+
+- Every agent: one public entrypoint, typed dataclass I/O from `types.py`, `confidence: float` and `notes: str` on every result.
+- Models load once at module/instance init — never inside the inference hot path.
+- Every agent module docstring states: purpose, inputs, outputs, failure behavior, model param count, license, and gated status.
+- `tracing.py` records structured per-agent I/O for any run; one full run gets exported to the Hub.
+- Every agent ships with a pytest in `tests/` that runs without model downloads and asserts the typed contract.
+
+## Model stack (~17.6B total — stay under 32B)
+
+| Component | Model | Params | Status |
+|---|---|---|---|
+| 2D pose (primary) | YOLO26l-Pose | 0.026B | Ready (checkpoint committed) |
+| 2D pose (HQ alt) | YOLO26x-Pose | 0.058B | Ready (checkpoint committed) |
+| 2D pose (fallback) | `noahcao/sapiens-pose-coco` | ~0.6B | Access accepted |
+| Segmentation | SAM 3.1 base | ~0.85B | Access accepted |
+| 3D biomechanics | `facebook/sam-3d-body-dinov3` | ~0.84B | **Access ACCEPTED Jun 4 2026** |
+| Learned scoring | ST-GCN (pyskl) | ~0.03B | Phase 3 |
+| Judge + Classifier | Qwen3-VL-8B-Instruct (llama.cpp) | 8B | Ready (ENABLE_JUDGE=False for now) |
+| Retrieval | Qwen3-VL-Embedding-8B (llama.cpp) | 8B | Phase 3 |
+
+Track the running sum in `MODEL_BUDGET.md`. The two Qwen3-VL-8B models share a backbone.
+
+## Gradio + Svelte UI guidance
+
+The UI uses **Gradio `gr.Blocks`** with custom CSS/theme (`formscout/ui/theme.py`). Custom Svelte components for score dial, asymmetry bars, rubric drawer are planned for Phase 4. Use `gradio-svelte-expert` agent for Svelte component work.
+
+- ZeroGPU: wrap heavy inference (`Pose2DAgent.run`, `Body3DAgent.run`) in `@spaces.GPU` before deploying to Spaces.
+- Verify Gradio APIs against current docs before use — pin exact versions in `requirements.txt`.
+
+## Build phases
+
+1. **Phase 0 — Recon:** ✅ Complete. See `RECON.md`.
+2. **Phase 1 — Spine:** ✅ Complete. Deep Squat end-to-end.
+3. **Phase 2 — All 7 tests:** ✅ Complete. Classifier, Judge, Report agents; all rubric scorers; Gradio UI.
+4. **Phase 3 — Learned scoring + retrieval:** ST-GCN fine-tune on physio clips, publish to Hub. RetrievalAgent with embedding index.
+5. **Phase 4 — Polish + ship:** Custom Svelte UI components, overlay video, PDF export, agent trace to Hub, blog post.
+
+## Known issues
+
+- `tests/test_biomechanics.py::TestBiomechanicsAgent::test_unimplemented_test_returns_low_confidence` fails: expects `"not yet implemented"` in `result.notes` but biomechanics returns empty string. Minor — low priority.
+
+## Badge checklist (definition of done)
+
+- [ ] Space runs green; upload → scorecard works on real clips
+- [ ] Param sum verified ≤ 32B in `MODEL_BUDGET.md`
+- [ ] 🔌 **Off the Grid** — no cloud model APIs anywhere in the pipeline
+- [ ] 🎯 **Well-Tuned** — fine-tuned ST-GCN head published to Hub with honest model card
+- [ ] 🎨 **Off-Brand** — custom, non-default Gradio UI (scout/trail theme)
+- [ ] 🦙 **Llama Champion** — VLM + embedder served via llama.cpp (GGUF)
+- [ ] 📡 **Sharing is Caring** — one full agent trace (all I/O) published to Hub
+- [ ] 📓 **Field Notes** — blog post written, honesty section (FMS limitations) front-and-center
+- [ ] Demo video + social post recorded
+- [ ] Safety banner present; pain/clearing never auto-scored; low-confidence flagged

README.md

@@ -1,3 +1,15 @@
+---
+title: FormScout
+emoji: 🏔️
+colorFrom: green
+colorTo: green
+sdk: gradio
+app_file: app.py
+pinned: false
+license: apache-2.0
+short_description: FMS video scoring — movement screen aid
+---
+
 # FormScout
 
 FMS (Functional Movement Screen) scoring pipeline — a screening aid that scores movement videos 0–3 per test with a written rationale and annotated overlay.

app.py

@@ -8,11 +8,17 @@ rubric breakdown, and persistent safety banner.
 """
 from __future__ import annotations
 
+import tempfile
+
 import gradio as gr
 
 from formscout.pipeline import Director
 from formscout.rubric import score_test
 from formscout.ui.theme import formscout_theme, FORMSCOUT_CSS
+from formscout import config
+from formscout.startup import ensure_checkpoints
+
+ensure_checkpoints()
 
 
 # ─── Constants ───────────────────────────────────────────────────────────────
@@ -42,7 +48,7 @@ SCORE_DESCRIPTIONS = {
 
 # ─── Processing ──────────────────────────────────────────────────────────────
 
-def process_video(video_path: str, test_name: str, side: str):
+def process_video(video_path: str, test_name: str, side: str, model_key: str, layers: list[str]):
     """Process an uploaded video through the FormScout pipeline."""
     if not video_path:
         return (
@@ -50,10 +56,12 @@ def process_video(video_path: str, test_name: str, side: str):
             "Upload a video to begin analysis.",
             "",
             "",
+            None,
+            "",
         )
 
     director = Director()
-    state = director.run(video_path, test_name=test_name, side=side)
+    state = director.run(video_path, test_name=test_name, side=side, model_key=model_key)
 
     # ─── Score card ───
     score_html = _render_empty_state()
@@ -61,7 +69,6 @@ def process_video(video_path: str, test_name: str, side: str):
 
     if state.features:
         result = score_test(state.features)
-        # Use judge result if available, otherwise rubric
         judge = state.judge
         if judge and judge.score is not None:
             score_html = _render_score_card(judge.score, judge.confidence, judge.needs_human)
@@ -79,7 +86,23 @@ def process_video(video_path: str, test_name: str, side: str):
     # ─── Warnings/errors ───
     alerts = _render_alerts(state)
 
-    return score_html, pipeline_md, score_details, alerts
+    # ─── Overlay video ───
+    overlay_path = None
+    vel_summary = ""
+    layer_set = {lbl.lower().replace(" ", "_") for lbl in (layers or [])}
+    if layer_set and state.ingest and state.pose2d:
+        try:
+            from formscout.agents.visualizer import PoseVisualizer, build_velocity_summary
+            vis = PoseVisualizer()
+            with tempfile.NamedTemporaryFile(suffix=".mp4", delete=False) as f:
+                out_path = f.name
+            overlay_path = vis.render_video(state.ingest, state.pose2d, layer_set, out_path)
+            if overlay_path:
+                vel_summary = build_velocity_summary(state.pose2d.keypoints, vis.last_velocities)
+        except Exception as e:
+            alerts = (alerts or "") + f"\n⚠️ Visualizer error: {e}"
+
+    return score_html, pipeline_md, score_details, alerts, overlay_path, vel_summary
 
 
 def _render_score_card(score: int, confidence: float, needs_human: bool) -> str:
@@ -223,11 +246,7 @@ def _render_alerts(state) -> str:
 
 def build_app() -> gr.Blocks:
     """Build the FormScout Gradio app with custom scout/trail theme."""
-    with gr.Blocks(
-        title="FormScout — FMS Screening Aid",
-        theme=formscout_theme(),
-        css=FORMSCOUT_CSS,
-    ) as app:
+    with gr.Blocks(title="FormScout — FMS Screening Aid") as app:
 
         # Header
         gr.HTML("""
@@ -262,6 +281,24 @@ def build_app() -> gr.Blocks:
                         scale=1,
                     )
 
+                _available_models = config.available_pose_models() or config.POSE_MODELS
+                _default_model = (
+                    config.DEFAULT_POSE_MODEL
+                    if config.DEFAULT_POSE_MODEL in _available_models
+                    else list(_available_models.keys())[0]
+                )
+                pose_model_dropdown = gr.Dropdown(
+                    choices=list(_available_models.keys()),
+                    value=_default_model,
+                    label="Pose Model",
+                )
+
+                overlay_layers = gr.CheckboxGroup(
+                    choices=["Skeleton", "Trails", "Velocity arrows"],
+                    value=["Skeleton", "Trails"],
+                    label="Overlay Layers",
+                )
+
                 submit_btn = gr.Button(
                     "🎯 Score Movement",
                     variant="primary",
@@ -292,6 +329,10 @@ def build_app() -> gr.Blocks:
                     with gr.TabItem("⚠️ Alerts"):
                         alerts_md = gr.Markdown("")
 
+                    with gr.TabItem("🎬 Overlay Video"):
+                        overlay_video = gr.Video(label="Annotated Movement")
+                        velocity_md = gr.Markdown("")
+
         # Footer safety banner
         gr.HTML(f'<div class="safety-banner" style="margin-top: 20px;">{DISCLAIMER}</div>')
 
@@ -304,17 +345,17 @@ def build_app() -> gr.Blocks:
 
         # ─── Event wiring ────────────────────────────────────────────────────
 
-        def _map_inputs(video, test_display_name, side_display):
+        def _map_inputs(video, test_display_name, side_display, pose_model_key, overlay_layers):
             """Map UI display values to internal values."""
             test_map = {name: val for name, val in FMS_TESTS}
             test_name = test_map.get(test_display_name, "deep_squat")
             side = {"N/A": "na", "Left": "left", "Right": "right"}.get(side_display, "na")
-            return process_video(video, test_name, side)
+            return process_video(video, test_name, side, pose_model_key, overlay_layers)
 
         submit_btn.click(
             fn=_map_inputs,
-            inputs=[video_input, test_dropdown, side_dropdown],
-            outputs=[score_html, pipeline_md, score_details, alerts_md],
+            inputs=[video_input, test_dropdown, side_dropdown, pose_model_dropdown, overlay_layers],
+            outputs=[score_html, pipeline_md, score_details, alerts_md, overlay_video, velocity_md],
         )
 
     return app
@@ -322,4 +363,4 @@ def build_app() -> gr.Blocks:
 
 if __name__ == "__main__":
     app = build_app()
-    app.launch()
+    app.launch(theme=formscout_theme(), css=FORMSCOUT_CSS)

checkpoints/mediapipe/pose_landmarker_full.task

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4eaa5eb7a98365221087693fcc286334cf0858e2eb6e15b506aa4a7ecdcec4ad
+size 9398198

docs/superpowers/plans/2026-06-09-pose-model-selector.md

@@ -0,0 +1,734 @@
+# Pose Model Selector Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Replace the hard-coded YOLO26l default with a 10-model dropdown (MediaPipe, YOLO26 n→x, Sapiens2 0.4B→5B) wired end-to-end from UI through the Director to `Pose2DAgent`.
+
+**Architecture:** Unified `POSE_MODELS` registry in `config.py` drives a `gr.Dropdown` in `app.py`; the selected key flows through `Director.run()` into `Pose2DAgent.run(model_key)`, which dispatches to one of three private sub-runners (`_run_yolo`, `_run_mediapipe`, `_run_sapiens2`), all producing the same COCO-17 `list[dict]` contract.
+
+**Tech Stack:** `ultralytics` (YOLO), `onnxruntime` + `huggingface_hub` (MediaPipe), `transformers` (Sapiens2), `gradio` (UI).
+
+---
+
+## File map
+
+| File | Change |
+|---|---|
+| `formscout/config.py` | Replace `YOLO_POSE_MODELS` with `POSE_MODELS` dict + `DEFAULT_POSE_MODEL` |
+| `formscout/agents/pose2d.py` | Add `_run_yolo`, `_run_mediapipe`, `_run_sapiens2`; update `run()` signature |
+| `formscout/pipeline.py` | Change `pose_model_path` param to `model_key` |
+| `app.py` | Add `pose_model_dropdown`, fix `_map_inputs` + `process_video` |
+| `requirements.txt` | Add `onnxruntime>=1.18` |
+| `tests/test_pose2d.py` | Add mocked tests for each backend |
+
+---
+
+## Task 1: Add unified `POSE_MODELS` registry to `config.py`
+
+**Files:**
+- Modify: `formscout/config.py`
+
+- [ ] **Step 1: Open `formscout/config.py` and replace the `YOLO_POSE_MODELS` block**
+
+Replace lines 12–20 (the `YOLO_POSE_MODELS` dict and `YOLO_POSE_MODEL` / `YOLO_POSE_MODEL_HQ` lines) with:
+
+```python
+_YOLO_DIR = ROOT / "checkpoints" / "yolo26"
+
+POSE_MODELS: dict[str, dict] = {
+    # ── MediaPipe (Qualcomm HF, ONNX Runtime) ──────────────────────────────
+    "MediaPipe-Pose ⬇ ~16 MB, CPU-friendly": {
+        "backend": "mediapipe",
+        "hf_id": "qualcomm/MediaPipe-Pose-Estimation",
+        "params_m": 4.2,
+    },
+    # ── YOLO26 (local checkpoints) ─────────────────────────────────────────
+    "YOLO26n — nano (0.7M, fastest)": {
+        "backend": "yolo",
+        "path": str(_YOLO_DIR / "yolo26n-pose.pt"),
+        "params_m": 0.7,
+    },
+    "YOLO26s — small (3.5M)": {
+        "backend": "yolo",
+        "path": str(_YOLO_DIR / "yolo26s-pose.pt"),
+        "params_m": 3.5,
+    },
+    "YOLO26m — medium (9M)": {
+        "backend": "yolo",
+        "path": str(_YOLO_DIR / "yolo26m-pose.pt"),
+        "params_m": 9.0,
+    },
+    "YOLO26l — large (25.9M)": {
+        "backend": "yolo",
+        "path": str(_YOLO_DIR / "yolo26l-pose.pt"),
+        "params_m": 25.9,
+    },
+    "YOLO26x — extra-large (57.6M)": {
+        "backend": "yolo",
+        "path": str(_YOLO_DIR / "yolo26x-pose.pt"),
+        "params_m": 57.6,
+    },
+    # ── Sapiens2 (HF download, transformers) ───────────────────────────────
+    "Sapiens2-0.4B ⬇ ~1.6 GB": {
+        "backend": "sapiens2",
+        "hf_id": "facebook/sapiens2-pose-0.4b",
+        "params_m": 400,
+    },
+    "Sapiens2-0.8B ⬇ ~3.2 GB": {
+        "backend": "sapiens2",
+        "hf_id": "facebook/sapiens2-pose-0.8b",
+        "params_m": 800,
+    },
+    "Sapiens2-1B ⬇ ~4 GB": {
+        "backend": "sapiens2",
+        "hf_id": "facebook/sapiens2-pose-1b",
+        "params_m": 1000,
+    },
+    "Sapiens2-5B ⬇ ~20 GB, large GPU": {
+        "backend": "sapiens2",
+        "hf_id": "facebook/sapiens2-pose-5b",
+        "params_m": 5000,
+    },
+}
+
+DEFAULT_POSE_MODEL = "YOLO26n — nano (0.7M, fastest)"
+
+# Backward-compat aliases — kept for any direct references outside the agent
+YOLO_POSE_MODEL = str(_YOLO_DIR / "yolo26l-pose.pt")
+YOLO_POSE_MODEL_HQ = str(_YOLO_DIR / "yolo26x-pose.pt")
+```
+
+- [ ] **Step 2: Verify import is clean**
+
+```bash
+python3 -c "from formscout import config; print(list(config.POSE_MODELS.keys()))"
+```
+
+Expected: list of 10 model labels, starting with `MediaPipe-Pose...`
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add formscout/config.py
+git commit -m "feat: unified POSE_MODELS registry with MediaPipe, YOLO26 n-x, Sapiens2 0.4-5B"
+git push
+```
+
+---
+
+## Task 2: Refactor `Pose2DAgent` — YOLO sub-runner + new `run()` signature
+
+**Files:**
+- Modify: `formscout/agents/pose2d.py`
+- Modify: `tests/test_pose2d.py`
+
+- [ ] **Step 1: Write failing test for the new `model_key` signature**
+
+Add to `tests/test_pose2d.py`:
+
+```python
+def test_run_accepts_model_key(pose2d_agent):
+    """run() must accept model_key kwarg, not model_path."""
+    import inspect
+    sig = inspect.signature(pose2d_agent.run)
+    assert "model_key" in sig.parameters
+    assert "model_path" not in sig.parameters
+```
+
+- [ ] **Step 2: Run to confirm it fails**
+
+```bash
+pytest tests/test_pose2d.py::TestPose2DAgent::test_run_accepts_model_key -v
+```
+
+Expected: FAIL — `model_path` still present in signature.
+
+- [ ] **Step 3: Rewrite `formscout/agents/pose2d.py`**
+
+Replace the entire file with:
+
+```python
+"""
+Pose2DAgent — 2D per-frame keypoint extraction.
+
+Backends: yolo (local ONNX), mediapipe (Qualcomm HF/ONNX Runtime),
+          sapiens2 (Meta HF/transformers).
+All backends output COCO-17 keypoints: dict[int, {x, y, conf}] per frame.
+
+Input:  IngestResult
+Output: Pose2DResult(keypoints per frame, fps, confidence)
+Failure: Pose2DResult(confidence=0.0, notes=<reason>) — never raises.
+"""
+from __future__ import annotations
+
+import logging
+import numpy as np
+
+from formscout import config
+from formscout.types import IngestResult, Pose2DResult
+
+logger = logging.getLogger(__name__)
+
+COCO_KEYPOINTS = [
+    "nose", "left_eye", "right_eye", "left_ear", "right_ear",
+    "left_shoulder", "right_shoulder", "left_elbow", "right_elbow",
+    "left_wrist", "right_wrist", "left_hip", "right_hip",
+    "left_knee", "right_knee", "left_ankle", "right_ankle",
+]
+
+# BlazePose-33 → COCO-17 index mapping
+_BLAZEPOSE_TO_COCO: dict[int, int] = {
+    0: 0,   # nose
+    1: 2,   # left_eye (inner → left_eye)
+    2: 1,   # right_eye (inner → right_eye) — swapped: BlazePose 1=left_eye_inner
+    3: 3,   # left_ear
+    4: 4,   # right_ear
+    5: 5,   # left_shoulder → COCO left_shoulder... wait
+    # Correct BlazePose-33 COCO mapping (canonical):
+    # BlazePose idx : COCO idx
+    # 0  nose           → COCO 0
+    # 2  left_eye       → COCO 1
+    # 5  right_eye      → COCO 2
+    # 7  left_ear       → COCO 3
+    # 8  right_ear      → COCO 4
+    # 11 left_shoulder  → COCO 5
+    # 12 right_shoulder → COCO 6
+    # 13 left_elbow     → COCO 7
+    # 14 right_elbow    → COCO 8
+    # 15 left_wrist     → COCO 9
+    # 16 right_wrist    → COCO 10
+    # 23 left_hip       → COCO 11
+    # 24 right_hip      → COCO 12
+    # 25 left_knee      → COCO 13
+    # 26 right_knee     → COCO 14
+    # 27 left_ankle     → COCO 15
+    # 28 right_ankle    → COCO 16
+}
+
+# BlazePose source index → COCO target index (correct mapping, no duplicates)
+_BP_SRC = [0, 2, 5, 7, 8, 11, 12, 13, 14, 15, 16, 23, 24, 25, 26, 27, 28]
+_BP_DST = list(range(17))  # COCO 0..16
+
+_model_cache: dict[str, object] = {}
+
+
+# ── YOLO backend ─────────────────────────────────────────────────────────────
+
+def _get_yolo(path: str) -> object:
+    if path not in _model_cache:
+        from ultralytics import YOLO
+        _model_cache[path] = YOLO(path)
+    return _model_cache[path]
+
+
+def _run_yolo(frames: list, path: str) -> list[dict]:
+    model = _get_yolo(path)
+    out = []
+    for frame in frames:
+        try:
+            results = model(frame, verbose=False)
+            kps: dict[int, dict] = {}
+            if results and results[0].keypoints is not None:
+                kp = results[0].keypoints
+                if kp.xy is not None and len(kp.xy) > 0:
+                    xy = kp.xy[0].cpu().numpy()
+                    conf = kp.conf[0].cpu().numpy()
+                    for j in range(min(len(xy), 17)):
+                        kps[j] = {"x": float(xy[j, 0]), "y": float(xy[j, 1]), "conf": float(conf[j])}
+            out.append(kps)
+        except Exception:
+            out.append({})
+    return out
+
+
+# ── MediaPipe backend ────────────────────────────────────────────────────────
+
+def _get_mediapipe_sessions(hf_id: str):
+    """Return (detector_session, landmark_session) cached by hf_id."""
+    cache_key = f"mp:{hf_id}"
+    if cache_key not in _model_cache:
+        from huggingface_hub import snapshot_download
+        import onnxruntime as ort
+        from pathlib import Path
+
+        snap = Path(snapshot_download(hf_id))
+        onnx_files = sorted(snap.glob("**/*.onnx"), key=lambda p: p.stat().st_size)
+        if len(onnx_files) < 2:
+            raise RuntimeError(f"Expected 2 ONNX files in {snap}, found {len(onnx_files)}")
+        # Smaller file = pose detector; larger = pose landmark detector
+        det_sess = ort.InferenceSession(str(onnx_files[0]))
+        lmk_sess = ort.InferenceSession(str(onnx_files[-1]))
+        _model_cache[cache_key] = (det_sess, lmk_sess)
+    return _model_cache[cache_key]
+
+
+def _preprocess_mediapipe(frame: np.ndarray, size: int = 256) -> np.ndarray:
+    """Resize to size×size, normalize to [0,1], add batch dim → (1,3,H,W)."""
+    import cv2
+    img = cv2.resize(frame, (size, size)).astype(np.float32) / 255.0
+    return img.transpose(2, 0, 1)[None]  # (1, 3, 256, 256)
+
+
+def _run_mediapipe(frames: list, hf_id: str) -> list[dict]:
+    try:
+        det_sess, lmk_sess = _get_mediapipe_sessions(hf_id)
+    except Exception as e:
+        logger.warning("mediapipe load failed: %s", e)
+        return [{} for _ in frames]
+
+    import cv2
+    h_orig, w_orig = frames[0].shape[:2] if frames else (480, 640)
+    out = []
+
+    for frame in frames:
+        try:
+            h, w = frame.shape[:2]
+            inp = _preprocess_mediapipe(frame)
+
+            # Run landmark detector directly on full frame (single-person FMS use-case)
+            lmk_input_name = lmk_sess.get_inputs()[0].name
+            lmk_out = lmk_sess.run(None, {lmk_input_name: inp})
+
+            # lmk_out[0] shape: (1, 33, 3) — [x, y, visibility] normalized 0..1
+            landmarks = lmk_out[0][0]  # (33, 3)
+
+            kps: dict[int, dict] = {}
+            for coco_idx, bp_idx in zip(_BP_DST, _BP_SRC):
+                if bp_idx < len(landmarks):
+                    lm = landmarks[bp_idx]
+                    kps[coco_idx] = {
+                        "x": float(lm[0] * w),
+                        "y": float(lm[1] * h),
+                        "conf": float(lm[2]),  # visibility score
+                    }
+            out.append(kps)
+        except Exception:
+            out.append({})
+
+    return out
+
+
+# ── Sapiens2 backend ─────────────────────────────────────────────────────────
+
+# COCO-17 keypoint names in order (used to map Sapiens2 named output → COCO index)
+_COCO_NAMES = [
+    "nose", "left_eye", "right_eye", "left_ear", "right_ear",
+    "left_shoulder", "right_shoulder", "left_elbow", "right_elbow",
+    "left_wrist", "right_wrist", "left_hip", "right_hip",
+    "left_knee", "right_knee", "left_ankle", "right_ankle",
+]
+
+
+def _get_sapiens2(hf_id: str) -> object:
+    if hf_id not in _model_cache:
+        from transformers import pipeline as hf_pipeline
+        _model_cache[hf_id] = hf_pipeline("pose-estimation", model=hf_id)
+    return _model_cache[hf_id]
+
+
+def _run_sapiens2(frames: list, hf_id: str) -> list[dict]:
+    try:
+        pipe = _get_sapiens2(hf_id)
+    except Exception as e:
+        logger.warning("sapiens2 load failed: %s", e)
+        return [{} for _ in frames]
+
+    from PIL import Image
+    out = []
+
+    for frame in frames:
+        try:
+            pil_img = Image.fromarray(frame)
+            result = pipe(pil_img)
+
+            # result is a list of person dicts; take the first (highest confidence)
+            if not result:
+                out.append({})
+                continue
+
+            person = result[0]
+            keypoints = person.get("keypoints", [])
+            scores = person.get("keypoint_scores", [])
+
+            # Build name→(x,y,score) lookup from pipeline output
+            kp_lookup: dict[str, tuple] = {}
+            for i, kp in enumerate(keypoints):
+                name = kp.get("label", "") if isinstance(kp, dict) else ""
+                x = kp.get("x", 0.0) if isinstance(kp, dict) else float(kp[0])
+                y = kp.get("y", 0.0) if isinstance(kp, dict) else float(kp[1])
+                score = scores[i] if i < len(scores) else 0.0
+                if name:
+                    kp_lookup[name] = (x, y, float(score))
+
+            kps: dict[int, dict] = {}
+            for coco_idx, name in enumerate(_COCO_NAMES):
+                if name in kp_lookup:
+                    x, y, s = kp_lookup[name]
+                    kps[coco_idx] = {"x": x, "y": y, "conf": s}
+
+            out.append(kps)
+        except Exception:
+            out.append({})
+
+    return out
+
+
+# ── Agent ────────────────────────────────────────────────────────────────────
+
+class Pose2DAgent:
+    """Extracts COCO-17 keypoints per frame; dispatches to YOLO, MediaPipe, or Sapiens2."""
+
+    def run(self, ingest: IngestResult, model_key: str | None = None) -> Pose2DResult:
+        if not ingest.frames:
+            return Pose2DResult(keypoints=[], fps=ingest.fps, confidence=0.0, notes="no frames in ingest")
+
+        key = model_key or config.DEFAULT_POSE_MODEL
+        spec = config.POSE_MODELS.get(key)
+        if spec is None:
+            logger.warning("Unknown model_key %r — falling back to %s", key, config.DEFAULT_POSE_MODEL)
+            spec = config.POSE_MODELS[config.DEFAULT_POSE_MODEL]
+
+        backend = spec["backend"]
+        try:
+            if backend == "yolo":
+                kps_per_frame = _run_yolo(ingest.frames, spec["path"])
+            elif backend == "mediapipe":
+                kps_per_frame = _run_mediapipe(ingest.frames, spec["hf_id"])
+            elif backend == "sapiens2":
+                kps_per_frame = _run_sapiens2(ingest.frames, spec["hf_id"])
+            else:
+                return Pose2DResult(
+                    keypoints=[{} for _ in ingest.frames],
+                    fps=ingest.fps, confidence=0.0,
+                    notes=f"unknown backend: {backend}",
+                )
+        except Exception as e:
+            return Pose2DResult(
+                keypoints=[{} for _ in ingest.frames],
+                fps=ingest.fps, confidence=0.0,
+                notes=str(e),
+            )
+
+        n_detected = sum(1 for f in kps_per_frame if f)
+        total_conf = sum(
+            sum(kp["conf"] for kp in f.values()) / len(f)
+            for f in kps_per_frame if f
+        )
+        overall_conf = (total_conf / n_detected) if n_detected > 0 else 0.0
+        notes = "" if n_detected > 0 else "no person detected in any frame"
+
+        return Pose2DResult(
+            keypoints=kps_per_frame,
+            fps=ingest.fps,
+            confidence=overall_conf,
+            notes=notes,
+        )
+```
+
+- [ ] **Step 4: Run the new signature test**
+
+```bash
+pytest tests/test_pose2d.py::TestPose2DAgent::test_run_accepts_model_key -v
+```
+
+Expected: PASS
+
+- [ ] **Step 5: Run full existing pose2d test suite**
+
+```bash
+pytest tests/test_pose2d.py -v
+```
+
+Expected: all existing tests pass (they will skip if YOLO model unavailable in env — that's OK).
+
+- [ ] **Step 6: Commit and push**
+
+```bash
+git add formscout/agents/pose2d.py tests/test_pose2d.py
+git commit -m "feat: Pose2DAgent — three backends (yolo/mediapipe/sapiens2), model_key dispatch"
+git push
+```
+
+---
+
+## Task 3: Add `onnxruntime` to requirements
+
+**Files:**
+- Modify: `requirements.txt`
+
+- [ ] **Step 1: Add onnxruntime**
+
+Open `requirements.txt` and add after the existing `transformers` line:
+
+```
+onnxruntime>=1.18
+```
+
+- [ ] **Step 2: Verify it installs**
+
+```bash
+pip install onnxruntime --quiet && python3 -c "import onnxruntime; print(onnxruntime.__version__)"
+```
+
+Expected: version string printed, no errors.
+
+- [ ] **Step 3: Commit and push**
+
+```bash
+git add requirements.txt
+git commit -m "chore: add onnxruntime for MediaPipe ONNX backend"
+git push
+```
+
+---
+
+## Task 4: Update `Director.run()` — `pose_model_path` → `model_key`
+
+**Files:**
+- Modify: `formscout/pipeline.py`
+
+- [ ] **Step 1: Update the signature and the `pose2d` call**
+
+In `formscout/pipeline.py`, change `Director.run()`:
+
+```python
+def run(self, video_path: str, test_name: str = "deep_squat", side: str = "na", model_key: str | None = None) -> PipelineState:
+    """
+    Run the full pipeline on a single video.
+    test_name/side serve as manual override when provided (skips classifier).
+    model_key selects the pose backend (see config.POSE_MODELS).
+    """
+    state = PipelineState(video_path=video_path)
+
+    # ─── Ingest ───
+    state.ingest = self._ingest.run(video_path)
+    if state.ingest.confidence < config.MIN_CONFIDENCE:
+        state.errors.append("ingest: low confidence — video may be corrupt")
+        return state
+
+    # ─── Pose 2D ───
+    state.pose2d = self._pose2d.run(state.ingest, model_key=model_key)
+    # ... rest of method unchanged
+```
+
+(Only the signature line and the `self._pose2d.run(...)` call change — everything else stays the same.)
+
+- [ ] **Step 2: Verify import is clean**
+
+```bash
+python3 -c "from formscout.pipeline import Director; d = Director(); print('ok')"
+```
+
+Expected: `ok` (models load lazily so no crash here).
+
+- [ ] **Step 3: Commit and push**
+
+```bash
+git add formscout/pipeline.py
+git commit -m "feat: Director.run() accepts model_key, threads to Pose2DAgent"
+git push
+```
+
+---
+
+## Task 5: Wire the UI — pose model dropdown in `app.py`
+
+**Files:**
+- Modify: `app.py`
+
+- [ ] **Step 1: Update `process_video` to use `model_key` and the unified registry**
+
+Replace the existing `process_video` function signature and the old `YOLO_POSE_MODELS.get()` lookup:
+
+```python
+def process_video(video_path: str, test_name: str, side: str, model_key: str):
+    """Process an uploaded video through the FormScout pipeline."""
+    if not video_path:
+        return (
+            _render_empty_state(),
+            "Upload a video to begin analysis.",
+            "",
+            "",
+        )
+
+    director = Director()
+    state = director.run(video_path, test_name=test_name, side=side, model_key=model_key)
+```
+
+(Remove the `pose_model_path = config.YOLO_POSE_MODELS.get(...)` line entirely.)
+
+- [ ] **Step 2: Add the `pose_model_dropdown` in `build_app()`**
+
+Inside `build_app()`, after the `side_dropdown` block (around line 265) and before `submit_btn`, add:
+
+```python
+pose_model_dropdown = gr.Dropdown(
+    choices=list(config.POSE_MODELS.keys()),
+    value=config.DEFAULT_POSE_MODEL,
+    label="Pose Model",
+)
+```
+
+- [ ] **Step 3: Update `_map_inputs` to pass the model key**
+
+Replace the existing `_map_inputs` closure:
+
+```python
+def _map_inputs(video, test_display_name, side_display, pose_model_key):
+    """Map UI display values to internal values."""
+    test_map = {name: val for name, val in FMS_TESTS}
+    test_name = test_map.get(test_display_name, "deep_squat")
+    side = {"N/A": "na", "Left": "left", "Right": "right"}.get(side_display, "na")
+    return process_video(video, test_name, side, pose_model_key)
+```
+
+- [ ] **Step 4: Update `submit_btn.click` to include `pose_model_dropdown`**
+
+Replace the existing `.click(...)` call:
+
+```python
+submit_btn.click(
+    fn=_map_inputs,
+    inputs=[video_input, test_dropdown, side_dropdown, pose_model_dropdown],
+    outputs=[score_html, pipeline_md, score_details, alerts_md],
+)
+```
+
+- [ ] **Step 5: Smoke-test the app starts**
+
+```bash
+python3 -c "from app import build_app; app = build_app(); print('app built ok')"
+```
+
+Expected: `app built ok` — no import or config errors.
+
+- [ ] **Step 6: Commit and push**
+
+```bash
+git add app.py
+git commit -m "feat: pose model dropdown in UI, wired through process_video → Director"
+git push
+```
+
+---
+
+## Task 6: Add mocked backend tests
+
+**Files:**
+- Modify: `tests/test_pose2d.py`
+
+- [ ] **Step 1: Add mocked YOLO test**
+
+Append to `tests/test_pose2d.py`:
+
+```python
+import unittest.mock as mock
+import numpy as np
+from formscout.types import IngestResult, Pose2DResult
+
+
+def _blank_ingest_3():
+    frames = [np.zeros((480, 640, 3), dtype=np.uint8) for _ in range(3)]
+    return IngestResult(frames=frames, fps=30.0, duration=0.1, n_people=1, width=640, height=480)
+
+
+class TestPose2DBackendsMocked:
+    """Backend dispatch tests — no real model downloads."""
+
+    def test_yolo_backend_dispatches(self):
+        from formscout.agents.pose2d import Pose2DAgent, _run_yolo
+        fake_kps = [{0: {"x": 10.0, "y": 20.0, "conf": 0.9}} for _ in range(3)]
+        with mock.patch("formscout.agents.pose2d._run_yolo", return_value=fake_kps) as m:
+            agent = Pose2DAgent()
+            result = agent.run(_blank_ingest_3(), model_key="YOLO26n — nano (0.7M, fastest)")
+        m.assert_called_once()
+        assert isinstance(result, Pose2DResult)
+        assert len(result.keypoints) == 3
+        assert result.confidence > 0.0
+
+    def test_mediapipe_backend_dispatches(self):
+        from formscout.agents.pose2d import Pose2DAgent
+        fake_kps = [{i: {"x": float(i), "y": float(i), "conf": 0.8} for i in range(17)} for _ in range(3)]
+        with mock.patch("formscout.agents.pose2d._run_mediapipe", return_value=fake_kps) as m:
+            agent = Pose2DAgent()
+            result = agent.run(_blank_ingest_3(), model_key="MediaPipe-Pose ⬇ ~16 MB, CPU-friendly")
+        m.assert_called_once()
+        assert isinstance(result, Pose2DResult)
+        assert len(result.keypoints) == 3
+        assert all(len(f) == 17 for f in result.keypoints)
+
+    def test_sapiens2_backend_dispatches(self):
+        from formscout.agents.pose2d import Pose2DAgent
+        fake_kps = [{i: {"x": float(i), "y": float(i), "conf": 0.85} for i in range(17)} for _ in range(3)]
+        with mock.patch("formscout.agents.pose2d._run_sapiens2", return_value=fake_kps) as m:
+            agent = Pose2DAgent()
+            result = agent.run(_blank_ingest_3(), model_key="Sapiens2-0.4B ⬇ ~1.6 GB")
+        m.assert_called_once()
+        assert isinstance(result, Pose2DResult)
+        assert len(result.keypoints) == 3
+
+    def test_unknown_model_key_falls_back(self):
+        from formscout.agents.pose2d import Pose2DAgent
+        fake_kps = [{0: {"x": 1.0, "y": 2.0, "conf": 0.7}} for _ in range(3)]
+        with mock.patch("formscout.agents.pose2d._run_yolo", return_value=fake_kps):
+            agent = Pose2DAgent()
+            result = agent.run(_blank_ingest_3(), model_key="nonexistent-model-xyz")
+        assert isinstance(result, Pose2DResult)  # graceful fallback, no crash
+
+    def test_confidence_zero_on_empty_keypoints(self):
+        from formscout.agents.pose2d import Pose2DAgent
+        with mock.patch("formscout.agents.pose2d._run_yolo", return_value=[{}, {}, {}]):
+            agent = Pose2DAgent()
+            result = agent.run(_blank_ingest_3(), model_key="YOLO26n — nano (0.7M, fastest)")
+        assert result.confidence == 0.0
+        assert "no person" in result.notes.lower()
+```
+
+- [ ] **Step 2: Run the new tests**
+
+```bash
+pytest tests/test_pose2d.py::TestPose2DBackendsMocked -v
+```
+
+Expected: all 5 tests PASS.
+
+- [ ] **Step 3: Run the full test suite to check for regressions**
+
+```bash
+pytest tests/ -v --tb=short 2>&1 | tail -30
+```
+
+Expected: same pass/fail ratio as before (45/46 known passing). The one known failure (`test_unimplemented_test_returns_low_confidence`) is pre-existing — ignore it.
+
+- [ ] **Step 4: Commit and push**
+
+```bash
+git add tests/test_pose2d.py
+git commit -m "test: mocked backend dispatch tests for YOLO, MediaPipe, Sapiens2"
+git push
+```
+
+---
+
+## Self-review
+
+**Spec coverage:**
+- ✅ Unified `POSE_MODELS` registry (Task 1)
+- ✅ `DEFAULT_POSE_MODEL = YOLO26n` (Task 1)
+- ✅ Backward-compat `YOLO_POSE_MODEL` / `YOLO_POSE_MODEL_HQ` aliases (Task 1)
+- ✅ `_run_yolo` sub-runner (Task 2)
+- ✅ `_run_mediapipe` with ONNX Runtime + BlazePose→COCO-17 mapping (Task 2)
+- ✅ `_run_sapiens2` with transformers pipeline + named-keypoint→COCO-17 mapping (Task 2)
+- ✅ `Pose2DAgent.run(model_key)` dispatch + fallback on unknown key (Task 2)
+- ✅ `onnxruntime` added to requirements (Task 3)
+- ✅ `Director.run(model_key)` threads key to agent (Task 4)
+- ✅ `pose_model_dropdown` in UI (Task 5)
+- ✅ `_map_inputs` + `submit_btn.click` wired (Task 5)
+- ✅ Error handling: unknown key → warning + fallback; download failure → confidence=0 (Task 2)
+- ✅ Mocked tests for all three backends (Task 6)
+
+**Placeholder scan:** None found.
+
+**Type consistency:** `model_key: str | None` used consistently across `Pose2DAgent.run`, `Director.run`, `process_video`. `config.POSE_MODELS` and `config.DEFAULT_POSE_MODEL` referenced consistently.
+
+**Note on Sapiens2 keypoint format:** The `_run_sapiens2` implementation uses **named keypoint lookup** (by label string) rather than assuming fixed indices 0–16 = COCO. This is the safe approach — the transformers pipeline returns labeled keypoints and the code maps by name. If the pipeline returns unnamed keypoints (index-only), the `kp_lookup` will be empty and the frame will gracefully return `{}`.

docs/superpowers/plans/2026-06-09-pose-visualizer.md

@@ -0,0 +1,914 @@
+# Pose Overlay Visualizer Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a pose overlay video output to FormScout with skeleton, motion trails, and velocity arrows, plus a per-joint velocity summary table.
+
+**Architecture:** A new `formscout/agents/visualizer.py` runs after `director.run()` in `process_video()`; it uses Kalman-filtered per-joint velocity and OpenCV rendering. `app.py` gains a `gr.CheckboxGroup` for layer selection, a new `gr.Video` output tab, and a `gr.Markdown` velocity summary.
+
+**Tech Stack:** `opencv-python`, `numpy`, `colorsys` (stdlib), `gradio`.
+
+---
+
+## File map
+
+| File | Change |
+|---|---|
+| `formscout/agents/visualizer.py` | Create — Kalman filter, velocity, PoseVisualizer, summary |
+| `tests/test_visualizer.py` | Create — all visualizer tests |
+| `app.py` | Modify — overlay_layers checkbox, new tab, wiring |
+
+---
+
+## Task 1: `SimpleKalmanFilter` + `compute_joint_velocity`
+
+**Files:**
+- Create: `formscout/agents/visualizer.py`
+- Create: `tests/test_visualizer.py`
+
+- [ ] **Step 1: Write failing tests**
+
+Create `tests/test_visualizer.py`:
+
+```python
+"""Tests for PoseVisualizer — no GPU, no model downloads."""
+import numpy as np
+import pytest
+from formscout.types import IngestResult, Pose2DResult
+
+
+def _make_ingest(n=5, h=480, w=640, fps=30.0):
+    frames = [np.zeros((h, w, 3), dtype=np.uint8) for _ in range(n)]
+    return IngestResult(frames=frames, fps=fps, duration=n/fps, n_people=1, width=w, height=h)
+
+
+def _make_pose(n=5, w=640, h=480):
+    """Synthetic Pose2DResult: 17 joints at fixed pixel positions, conf=0.9."""
+    kps_per_frame = []
+    for i in range(n):
+        frame_kps = {}
+        for j in range(17):
+            frame_kps[j] = {
+                "x": float(50 + j * 30 + i * 2),  # slight movement each frame
+                "y": float(100 + j * 20),
+                "conf": 0.9,
+            }
+        kps_per_frame.append(frame_kps)
+    return Pose2DResult(keypoints=kps_per_frame, fps=30.0, confidence=0.9, notes="")
+
+
+class TestComputeJointVelocity:
+    def test_returns_17_joints(self):
+        from formscout.agents.visualizer import compute_joint_velocity
+        pose = _make_pose(n=5)
+        result = compute_joint_velocity(pose.keypoints, fps=30.0)
+        assert len(result) == 17
+
+    def test_each_list_has_n_frames(self):
+        from formscout.agents.visualizer import compute_joint_velocity
+        pose = _make_pose(n=5)
+        result = compute_joint_velocity(pose.keypoints, fps=30.0)
+        for joint_idx, speeds in result.items():
+            assert len(speeds) == 5, f"joint {joint_idx} has {len(speeds)} speeds, expected 5"
+
+    def test_speeds_are_non_negative(self):
+        from formscout.agents.visualizer import compute_joint_velocity
+        pose = _make_pose(n=5)
+        result = compute_joint_velocity(pose.keypoints, fps=30.0)
+        for speeds in result.values():
+            assert all(s >= 0.0 for s in speeds)
+
+    def test_missing_keypoints_give_zero_speed(self):
+        from formscout.agents.visualizer import compute_joint_velocity
+        # All frames empty
+        empty_kps = [{} for _ in range(5)]
+        result = compute_joint_velocity(empty_kps, fps=30.0)
+        for speeds in result.values():
+            assert all(s == 0.0 for s in speeds)
+```
+
+- [ ] **Step 2: Run to confirm failure**
+
+```bash
+pytest tests/test_visualizer.py::TestComputeJointVelocity -v
+```
+
+Expected: `ERROR` — `ModuleNotFoundError: No module named 'formscout.agents.visualizer'`
+
+- [ ] **Step 3: Create `formscout/agents/visualizer.py` with Kalman + velocity**
+
+```python
+"""
+PoseVisualizer — annotated overlay video with skeleton, trails, velocity arrows.
+
+Input:  IngestResult + Pose2DResult
+Output: .mp4 path (or None on failure/empty layers)
+Failure: returns None, never raises.
+"""
+from __future__ import annotations
+
+import colorsys
+import logging
+import math
+import tempfile
+from collections import deque
+
+import cv2
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+# ── COCO constants ────────────────────────────────────────────────────────────
+
+COCO_KEYPOINTS = [
+    "nose", "left_eye", "right_eye", "left_ear", "right_ear",
+    "left_shoulder", "right_shoulder", "left_elbow", "right_elbow",
+    "left_wrist", "right_wrist", "left_hip", "right_hip",
+    "left_knee", "right_knee", "left_ankle", "right_ankle",
+]
+
+COCO_SKELETON = [
+    (0, 1), (0, 2), (1, 3), (2, 4),          # face
+    (5, 6), (5, 7), (7, 9), (6, 8), (8, 10), # arms
+    (5, 11), (6, 12), (11, 12),               # torso
+    (11, 13), (13, 15), (12, 14), (14, 16),  # legs
+]
+
+TRAIL_LENGTH = 10
+MAX_ARROW_PX = 40
+CONF_THRESHOLD = 0.3
+
+
+# ── Kalman filter ─────────────────────────────────────────────────────────────
+
+class SimpleKalmanFilter:
+    """4-state Kalman filter (x, y, vx, vy) for joint tracking."""
+
+    def __init__(self, process_noise: float = 0.01, measurement_noise: float = 0.1):
+        self.is_initialized = False
+        self.state = np.zeros(4)
+        self.cov = np.eye(4) * 0.1
+        self.Q = np.eye(4) * process_noise
+        self.R = np.eye(2) * measurement_noise
+        self.H = np.array([[1, 0, 0, 0], [0, 1, 0, 0]], dtype=float)
+
+    def predict(self, dt: float = 1.0):
+        F = np.array([[1, 0, dt, 0], [0, 1, 0, dt], [0, 0, 1, 0], [0, 0, 0, 1]], dtype=float)
+        self.state = F @ self.state
+        self.cov = F @ self.cov @ F.T + self.Q
+
+    def update(self, x: float, y: float):
+        z = np.array([x, y])
+        if not self.is_initialized:
+            self.state[:2] = z
+            self.is_initialized = True
+            return
+        S = self.H @ self.cov @ self.H.T + self.R
+        K = self.cov @ self.H.T @ np.linalg.inv(S)
+        self.state = self.state + K @ (z - self.H @ self.state)
+        self.cov = (np.eye(4) - K @ self.H) @ self.cov
+
+    def velocity_magnitude(self) -> float:
+        vx, vy = self.state[2], self.state[3]
+        return math.sqrt(vx * vx + vy * vy)
+
+    def velocity_vector(self) -> tuple[float, float]:
+        return float(self.state[2]), float(self.state[3])
+
+
+# ── Velocity computation ──────────────────────────────────────────────────────
+
+def compute_joint_velocity(
+    keypoints_per_frame: list[dict],
+    fps: float,
+) -> dict[int, list[float]]:
+    """
+    Compute Kalman-filtered per-joint speed (px/s) for each frame.
+
+    Returns dict[joint_idx, [speed_frame0, speed_frame1, ...]] for all 17 COCO joints.
+    Missing/low-confidence keypoints yield speed=0.0 for that frame.
+    """
+    dt = 1.0 / fps if fps > 0 else 1.0
+    filters: dict[int, SimpleKalmanFilter] = {j: SimpleKalmanFilter() for j in range(17)}
+    result: dict[int, list[float]] = {j: [] for j in range(17)}
+
+    for frame_kps in keypoints_per_frame:
+        for j in range(17):
+            kf = filters[j]
+            kp = frame_kps.get(j)
+            kf.predict(dt)
+            if kp and kp.get("conf", 0.0) >= CONF_THRESHOLD:
+                kf.update(kp["x"], kp["y"])
+                speed = kf.velocity_magnitude()
+            else:
+                speed = 0.0
+            result[j].append(speed)
+
+    return result
+```
+
+- [ ] **Step 4: Run tests**
+
+```bash
+pytest tests/test_visualizer.py::TestComputeJointVelocity -v
+```
+
+Expected: 4 PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add formscout/agents/visualizer.py tests/test_visualizer.py
+git commit -m "feat: SimpleKalmanFilter + compute_joint_velocity (4 tests pass)"
+```
+
+---
+
+## Task 2: `PoseVisualizer._draw_skeleton`
+
+**Files:**
+- Modify: `formscout/agents/visualizer.py`
+- Modify: `tests/test_visualizer.py`
+
+- [ ] **Step 1: Write failing test**
+
+Append to `tests/test_visualizer.py`:
+
+```python
+class TestDrawSkeleton:
+    def test_skeleton_draws_without_error(self):
+        from formscout.agents.visualizer import PoseVisualizer
+        vis = PoseVisualizer()
+        frame = np.zeros((480, 640, 3), dtype=np.uint8)
+        kps = {j: {"x": float(50 + j * 30), "y": float(100 + j * 20), "conf": 0.9}
+               for j in range(17)}
+        result = vis._draw_skeleton(frame.copy(), kps)
+        assert result.shape == frame.shape
+        # Frame must be modified (not all zeros after drawing)
+        assert not np.array_equal(result, frame)
+
+    def test_low_confidence_keypoints_not_drawn(self):
+        from formscout.agents.visualizer import PoseVisualizer
+        vis = PoseVisualizer()
+        frame = np.zeros((480, 640, 3), dtype=np.uint8)
+        # All keypoints below threshold
+        kps = {j: {"x": float(50 + j * 30), "y": 100.0, "conf": 0.1} for j in range(17)}
+        result = vis._draw_skeleton(frame.copy(), kps)
+        # Nothing drawn — frame stays all zeros
+        assert np.array_equal(result, frame)
+```
+
+- [ ] **Step 2: Run to confirm failure**
+
+```bash
+pytest tests/test_visualizer.py::TestDrawSkeleton -v
+```
+
+Expected: FAIL — `AttributeError: 'PoseVisualizer' object has no attribute '_draw_skeleton'`
+
+- [ ] **Step 3: Add `PoseVisualizer` class with `_draw_skeleton` to `visualizer.py`**
+
+Append after `compute_joint_velocity`:
+
+```python
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _conf_to_bgr(conf: float) -> tuple[int, int, int]:
+    """Map confidence 0→1 to BGR color red→green via HSV."""
+    hue = conf * 120.0 / 360.0
+    r, g, b = colorsys.hsv_to_rgb(hue, 1.0, 1.0)
+    return (int(b * 255), int(g * 255), int(r * 255))
+
+
+# ── PoseVisualizer ────────────────────────────────────────────────────────────
+
+class PoseVisualizer:
+    """Renders skeleton, trails, and velocity arrows onto video frames."""
+
+    def __init__(self):
+        self.last_velocities: dict[int, list[float]] = {}
+
+    # ── Skeleton ──────────────────────────────────────────────────────────────
+
+    def _draw_skeleton(self, frame: np.ndarray, kps: dict) -> np.ndarray:
+        """Draw COCO-17 bones (white) and joints (confidence-colored) onto frame."""
+        visible = {j: kp for j, kp in kps.items() if kp.get("conf", 0.0) >= CONF_THRESHOLD}
+
+        # Bones
+        for j1, j2 in COCO_SKELETON:
+            if j1 in visible and j2 in visible:
+                p1 = (int(visible[j1]["x"]), int(visible[j1]["y"]))
+                p2 = (int(visible[j2]["x"]), int(visible[j2]["y"]))
+                cv2.line(frame, p1, p2, (255, 255, 255), 2)
+
+        # Joints
+        for j, kp in visible.items():
+            pt = (int(kp["x"]), int(kp["y"]))
+            color = _conf_to_bgr(kp["conf"])
+            cv2.circle(frame, pt, 4, color, -1)
+            cv2.circle(frame, pt, 5, (255, 255, 255), 1)
+
+        return frame
+```
+
+- [ ] **Step 4: Run tests**
+
+```bash
+pytest tests/test_visualizer.py::TestDrawSkeleton -v
+```
+
+Expected: 2 PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add formscout/agents/visualizer.py tests/test_visualizer.py
+git commit -m "feat: PoseVisualizer._draw_skeleton with confidence-colored joints"
+```
+
+---
+
+## Task 3: `PoseVisualizer._draw_trails`
+
+**Files:**
+- Modify: `formscout/agents/visualizer.py`
+- Modify: `tests/test_visualizer.py`
+
+- [ ] **Step 1: Write failing test**
+
+Append to `tests/test_visualizer.py`:
+
+```python
+class TestDrawTrails:
+    def test_trails_draw_without_error(self):
+        from formscout.agents.visualizer import PoseVisualizer, TRAIL_LENGTH
+        from collections import deque
+        vis = PoseVisualizer()
+        frame = np.zeros((480, 640, 3), dtype=np.uint8)
+        # Build a trail history for joint 0 with 5 positions
+        trail_history = {
+            0: deque([(100 + i * 5, 200 + i * 3) for i in range(5)], maxlen=TRAIL_LENGTH)
+        }
+        result = vis._draw_trails(frame.copy(), trail_history)
+        assert result.shape == frame.shape
+        # Trail should modify at least some pixels
+        assert not np.array_equal(result, frame)
+
+    def test_short_trail_no_crash(self):
+        from formscout.agents.visualizer import PoseVisualizer, TRAIL_LENGTH
+        from collections import deque
+        vis = PoseVisualizer()
+        frame = np.zeros((480, 640, 3), dtype=np.uint8)
+        # Only one point — no line possible
+        trail_history = {0: deque([(100, 200)], maxlen=TRAIL_LENGTH)}
+        result = vis._draw_trails(frame.copy(), trail_history)
+        # No crash, frame unchanged (single point = no segment)
+        assert np.array_equal(result, frame)
+```
+
+- [ ] **Step 2: Run to confirm failure**
+
+```bash
+pytest tests/test_visualizer.py::TestDrawTrails -v
+```
+
+Expected: FAIL — `AttributeError: 'PoseVisualizer' object has no attribute '_draw_trails'`
+
+- [ ] **Step 3: Add `_draw_trails` to `PoseVisualizer`**
+
+Inside the `PoseVisualizer` class, after `_draw_skeleton`:
+
+```python
+    # ── Trails ───────────────────────────────────────────────────────────────
+
+    def _draw_trails(self, frame: np.ndarray, trail_history: dict) -> np.ndarray:
+        """Draw fading motion trails for each joint."""
+        for joint_idx, trail in trail_history.items():
+            pts = list(trail)
+            if len(pts) < 2:
+                continue
+            for i in range(1, len(pts)):
+                alpha = i / len(pts)
+                brightness = int(255 * alpha)
+                color = (brightness, brightness, brightness)
+                thickness = max(1, int(3 * alpha))
+                p1 = (int(pts[i - 1][0]), int(pts[i - 1][1]))
+                p2 = (int(pts[i][0]), int(pts[i][1]))
+                cv2.line(frame, p1, p2, color, thickness)
+        return frame
+```
+
+- [ ] **Step 4: Run tests**
+
+```bash
+pytest tests/test_visualizer.py::TestDrawTrails -v
+```
+
+Expected: 2 PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add formscout/agents/visualizer.py tests/test_visualizer.py
+git commit -m "feat: PoseVisualizer._draw_trails with fading alpha"
+```
+
+---
+
+## Task 4: `PoseVisualizer._draw_velocity_arrows`
+
+**Files:**
+- Modify: `formscout/agents/visualizer.py`
+- Modify: `tests/test_visualizer.py`
+
+- [ ] **Step 1: Write failing test**
+
+Append to `tests/test_visualizer.py`:
+
+```python
+class TestDrawVelocityArrows:
+    def test_arrows_draw_without_error(self):
+        from formscout.agents.visualizer import PoseVisualizer
+        vis = PoseVisualizer()
+        frame = np.zeros((480, 640, 3), dtype=np.uint8)
+        kps = {j: {"x": float(50 + j * 30), "y": float(100 + j * 20), "conf": 0.9}
+               for j in range(17)}
+        prev_kps = {j: {"x": float(48 + j * 30), "y": float(98 + j * 20), "conf": 0.9}
+                    for j in range(17)}
+        # velocities: joint 5 moving fast
+        velocities = {j: [0.0] * 5 for j in range(17)}
+        velocities[5] = [0.0, 10.0, 50.0, 80.0, 120.0]
+        result = vis._draw_velocity_arrows(frame.copy(), kps, prev_kps, velocities, frame_idx=4)
+        assert result.shape == frame.shape
+
+    def test_no_prev_kps_no_crash(self):
+        from formscout.agents.visualizer import PoseVisualizer
+        vis = PoseVisualizer()
+        frame = np.zeros((480, 640, 3), dtype=np.uint8)
+        kps = {j: {"x": float(50 + j * 30), "y": 100.0, "conf": 0.9} for j in range(17)}
+        velocities = {j: [50.0] * 5 for j in range(17)}
+        # prev_kps is None — should skip without crash
+        result = vis._draw_velocity_arrows(frame.copy(), kps, None, velocities, frame_idx=0)
+        assert result.shape == frame.shape
+```
+
+- [ ] **Step 2: Run to confirm failure**
+
+```bash
+pytest tests/test_visualizer.py::TestDrawVelocityArrows -v
+```
+
+Expected: FAIL — `AttributeError: 'PoseVisualizer' object has no attribute '_draw_velocity_arrows'`
+
+- [ ] **Step 3: Add `_draw_velocity_arrows` to `PoseVisualizer`**
+
+Inside the `PoseVisualizer` class, after `_draw_trails`:
+
+```python
+    # ── Velocity arrows ───────────────────────────────────────────────────────
+
+    def _draw_velocity_arrows(
+        self,
+        frame: np.ndarray,
+        kps: dict,
+        prev_kps: dict | None,
+        velocities: dict[int, list[float]],
+        frame_idx: int,
+    ) -> np.ndarray:
+        """Draw per-joint velocity arrows scaled by speed."""
+        if prev_kps is None:
+            return frame
+
+        all_speeds = [velocities[j][frame_idx] for j in range(17) if frame_idx < len(velocities.get(j, []))]
+        peak = max(all_speeds) if all_speeds else 1.0
+        if peak == 0.0:
+            return frame
+
+        for j in range(17):
+            kp = kps.get(j)
+            pk = prev_kps.get(j)
+            if not kp or not pk:
+                continue
+            if kp.get("conf", 0.0) < CONF_THRESHOLD:
+                continue
+            speeds = velocities.get(j, [])
+            if frame_idx >= len(speeds):
+                continue
+            speed = speeds[frame_idx]
+            if speed == 0.0:
+                continue
+
+            dx = kp["x"] - pk["x"]
+            dy = kp["y"] - pk["y"]
+            mag = math.sqrt(dx * dx + dy * dy)
+            if mag < 1e-6:
+                continue
+
+            # Normalize direction, scale to arrow length
+            length = min(speed / peak * MAX_ARROW_PX, MAX_ARROW_PX)
+            nx, ny = dx / mag, dy / mag
+            start = (int(kp["x"]), int(kp["y"]))
+            end = (int(kp["x"] + nx * length), int(kp["y"] + ny * length))
+
+            ratio = speed / peak
+            if ratio < 0.33:
+                color = (0, 200, 0)     # green
+            elif ratio < 0.66:
+                color = (0, 140, 255)   # orange
+            else:
+                color = (0, 0, 255)     # red
+
+            cv2.arrowedLine(frame, start, end, color, 2, tipLength=0.35)
+
+        return frame
+```
+
+- [ ] **Step 4: Run tests**
+
+```bash
+pytest tests/test_visualizer.py::TestDrawVelocityArrows -v
+```
+
+Expected: 2 PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add formscout/agents/visualizer.py tests/test_visualizer.py
+git commit -m "feat: PoseVisualizer._draw_velocity_arrows speed-colored"
+```
+
+---
+
+## Task 5: `render_video` + `build_velocity_summary`
+
+**Files:**
+- Modify: `formscout/agents/visualizer.py`
+- Modify: `tests/test_visualizer.py`
+
+- [ ] **Step 1: Write failing tests**
+
+Append to `tests/test_visualizer.py`:
+
+```python
+class TestRenderVideo:
+    def test_creates_mp4_file(self, tmp_path):
+        from formscout.agents.visualizer import PoseVisualizer
+        vis = PoseVisualizer()
+        ingest = _make_ingest(n=5)
+        pose = _make_pose(n=5)
+        out = str(tmp_path / "out.mp4")
+        result = vis.render_video(ingest, pose, {"skeleton"}, out)
+        assert result is not None
+        import os
+        assert os.path.exists(result)
+        assert os.path.getsize(result) > 0
+
+    def test_empty_layers_returns_none(self, tmp_path):
+        from formscout.agents.visualizer import PoseVisualizer
+        vis = PoseVisualizer()
+        out = str(tmp_path / "out.mp4")
+        result = vis.render_video(_make_ingest(), _make_pose(), set(), out)
+        assert result is None
+
+    def test_no_detections_returns_none(self, tmp_path):
+        from formscout.agents.visualizer import PoseVisualizer
+        vis = PoseVisualizer()
+        ingest = _make_ingest(n=5)
+        empty_pose = Pose2DResult(
+            keypoints=[{} for _ in range(5)], fps=30.0, confidence=0.0, notes=""
+        )
+        out = str(tmp_path / "out.mp4")
+        result = vis.render_video(ingest, empty_pose, {"skeleton"}, out)
+        assert result is None
+
+    def test_last_velocities_set_after_render(self, tmp_path):
+        from formscout.agents.visualizer import PoseVisualizer
+        vis = PoseVisualizer()
+        out = str(tmp_path / "out.mp4")
+        vis.render_video(_make_ingest(n=5), _make_pose(n=5), {"skeleton"}, out)
+        assert len(vis.last_velocities) == 17
+
+
+class TestBuildVelocitySummary:
+    def test_returns_markdown_table(self):
+        from formscout.agents.visualizer import build_velocity_summary, compute_joint_velocity
+        pose = _make_pose(n=10)
+        vels = compute_joint_velocity(pose.keypoints, fps=30.0)
+        result = build_velocity_summary(pose.keypoints, vels)
+        assert "|" in result
+        # At least one COCO joint name appears
+        assert any(name in result for name in ["knee", "shoulder", "hip", "ankle"])
+
+    def test_empty_keypoints_returns_empty_string(self):
+        from formscout.agents.visualizer import build_velocity_summary
+        empty_kps = [{} for _ in range(5)]
+        vels = {j: [0.0] * 5 for j in range(17)}
+        result = build_velocity_summary(empty_kps, vels)
+        assert result == ""
+```
+
+- [ ] **Step 2: Run to confirm failure**
+
+```bash
+pytest tests/test_visualizer.py::TestRenderVideo tests/test_visualizer.py::TestBuildVelocitySummary -v
+```
+
+Expected: FAIL — `AttributeError: 'PoseVisualizer' object has no attribute 'render_video'`
+
+- [ ] **Step 3: Add `render_video` to `PoseVisualizer`**
+
+Inside the `PoseVisualizer` class, after `_draw_velocity_arrows`:
+
+```python
+    # ── Public ────────────────────────────────────────────────────────────────
+
+    def render_video(
+        self,
+        ingest,
+        pose2d,
+        layers: set[str],
+        output_path: str,
+    ) -> str | None:
+        """
+        Render annotated video. Returns output_path on success, None otherwise.
+        layers: subset of {"skeleton", "trails", "velocity_arrows"}
+        """
+        if not layers:
+            return None
+
+        # Require at least one detected frame
+        if not any(pose2d.keypoints):
+            return None
+
+        try:
+            velocities = compute_joint_velocity(pose2d.keypoints, ingest.fps)
+            self.last_velocities = velocities
+
+            frames = ingest.frames
+            h, w = frames[0].shape[:2]
+            fps = ingest.fps or 30.0
+
+            fourcc = cv2.VideoWriter_fourcc(*"mp4v")
+            writer = cv2.VideoWriter(output_path, fourcc, fps, (w, h))
+            if not writer.isOpened():
+                logger.warning("VideoWriter failed to open: %s", output_path)
+                return None
+
+            trail_history: dict[int, deque] = {j: deque(maxlen=TRAIL_LENGTH) for j in range(17)}
+            prev_kps: dict | None = None
+
+            for frame_idx, (frame, kps) in enumerate(zip(frames, pose2d.keypoints)):
+                out_frame = frame.copy()
+
+                if "trails" in layers:
+                    # Update trail history before drawing
+                    for j, kp in kps.items():
+                        if kp.get("conf", 0.0) >= CONF_THRESHOLD:
+                            trail_history[j].append((kp["x"], kp["y"]))
+                    out_frame = self._draw_trails(out_frame, trail_history)
+
+                if "skeleton" in layers:
+                    out_frame = self._draw_skeleton(out_frame, kps)
+
+                if "velocity_arrows" in layers:
+                    out_frame = self._draw_velocity_arrows(
+                        out_frame, kps, prev_kps, velocities, frame_idx
+                    )
+
+                writer.write(out_frame)
+                prev_kps = kps
+
+            writer.release()
+            return output_path
+
+        except Exception as e:
+            logger.warning("render_video failed: %s", e)
+            return None
+```
+
+- [ ] **Step 4: Add `build_velocity_summary` after the class**
+
+After the `PoseVisualizer` class definition, add:
+
+```python
+# ── Velocity summary ──────────────────────────────────────────────────────────
+
+def build_velocity_summary(
+    keypoints_per_frame: list[dict],
+    velocities: dict[int, list[float]],
+) -> str:
+    """Return markdown table of per-joint avg/peak velocity. Empty string if no valid joints."""
+    n_frames = len(keypoints_per_frame)
+    if n_frames == 0:
+        return ""
+
+    rows = []
+    for j in range(17):
+        # Count frames where this joint is detected
+        detected = sum(
+            1 for kps in keypoints_per_frame
+            if kps.get(j, {}).get("conf", 0.0) >= CONF_THRESHOLD
+        )
+        if detected < n_frames * 0.5:
+            continue  # skip joints present in <50% of frames
+
+        speeds = velocities.get(j, [])
+        if not speeds:
+            continue
+
+        avg_speed = sum(speeds) / len(speeds)
+        peak_speed = max(speeds)
+        rows.append((COCO_KEYPOINTS[j], avg_speed, peak_speed))
+
+    if not rows:
+        return ""
+
+    rows.sort(key=lambda r: r[2], reverse=True)  # sort by peak descending
+    lines = [
+        "| Joint | Avg (px/s) | Peak (px/s) |",
+        "|---|---|---|",
+    ]
+    for name, avg, peak in rows:
+        lines.append(f"| {name} | {avg:.1f} | {peak:.1f} |")
+    return "\n".join(lines)
+```
+
+- [ ] **Step 5: Run all visualizer tests**
+
+```bash
+pytest tests/test_visualizer.py -v
+```
+
+Expected: all tests PASS (4 + 2 + 2 + 2 + 4 + 2 = 16 total)
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add formscout/agents/visualizer.py tests/test_visualizer.py
+git commit -m "feat: PoseVisualizer.render_video + build_velocity_summary (16 tests pass)"
+```
+
+---
+
+## Task 6: Wire `app.py`
+
+**Files:**
+- Modify: `app.py`
+
+- [ ] **Step 1: Add `import tempfile` if not present and import visualizer in `process_video`**
+
+Check the top of `app.py` for `import tempfile`. If missing, add it alongside the other stdlib imports. (Look at the existing import block and add `import tempfile` there.)
+
+- [ ] **Step 2: Update `process_video()` signature and body**
+
+Replace the existing `process_video` function (lines 46–83) with:
+
+```python
+def process_video(video_path: str, test_name: str, side: str, model_key: str, layers: list[str]):
+    """Process an uploaded video through the FormScout pipeline."""
+    if not video_path:
+        return (
+            _render_empty_state(),
+            "Upload a video to begin analysis.",
+            "",
+            "",
+            None,
+            "",
+        )
+
+    director = Director()
+    state = director.run(video_path, test_name=test_name, side=side, model_key=model_key)
+
+    # ─── Score card ───
+    score_html = _render_empty_state()
+    score_details = ""
+
+    if state.features:
+        result = score_test(state.features)
+        judge = state.judge
+        if judge and judge.score is not None:
+            score_html = _render_score_card(judge.score, judge.confidence, judge.needs_human)
+            score_details = _render_score_details_judge(judge, result, state.features)
+        elif judge and judge.needs_human:
+            score_html = _render_score_card(0, 0, True)
+            score_details = f"### Needs Clinician Review\n{judge.rationale}"
+        else:
+            score_html = _render_score_card(result.score, result.confidence, result.needs_human)
+            score_details = _render_score_details(result, state.features)
+
+    # ─── Pipeline info ───
+    pipeline_md = _render_pipeline_status(state)
+
+    # ─── Warnings/errors ───
+    alerts = _render_alerts(state)
+
+    # ─── Overlay video ───
+    overlay_path = None
+    vel_summary = ""
+    layer_set = {lbl.lower().replace(" ", "_") for lbl in (layers or [])}
+    if layer_set and state.ingest and state.pose2d:
+        try:
+            from formscout.agents.visualizer import PoseVisualizer, build_velocity_summary
+            vis = PoseVisualizer()
+            with tempfile.NamedTemporaryFile(suffix=".mp4", delete=False) as f:
+                out_path = f.name
+            overlay_path = vis.render_video(state.ingest, state.pose2d, layer_set, out_path)
+            if overlay_path:
+                vel_summary = build_velocity_summary(state.pose2d.keypoints, vis.last_velocities)
+        except Exception as e:
+            alerts = (alerts or "") + f"\n⚠️ Visualizer error: {e}"
+
+    return score_html, pipeline_md, score_details, alerts, overlay_path, vel_summary
+```
+
+- [ ] **Step 3: Add `overlay_layers` CheckboxGroup in `build_app()`**
+
+After the `pose_model_dropdown` block (around line 270), and before `submit_btn`:
+
+```python
+                overlay_layers = gr.CheckboxGroup(
+                    choices=["Skeleton", "Trails", "Velocity arrows"],
+                    value=["Skeleton", "Trails"],
+                    label="Overlay Layers",
+                )
+```
+
+- [ ] **Step 4: Add overlay tab in the results panel**
+
+Inside the `with gr.Tabs():` block (after the `⚠️ Alerts` tab):
+
+```python
+                    with gr.TabItem("🎬 Overlay Video"):
+                        overlay_video = gr.Video(label="Annotated Movement")
+                        velocity_md = gr.Markdown("")
+```
+
+- [ ] **Step 5: Update `_map_inputs` and `submit_btn.click`**
+
+Replace the `_map_inputs` closure and `submit_btn.click` call:
+
+```python
+        def _map_inputs(video, test_display_name, side_display, pose_model_key, overlay_layers):
+            """Map UI display values to internal values."""
+            test_map = {name: val for name, val in FMS_TESTS}
+            test_name = test_map.get(test_display_name, "deep_squat")
+            side = {"N/A": "na", "Left": "left", "Right": "right"}.get(side_display, "na")
+            return process_video(video, test_name, side, pose_model_key, overlay_layers)
+
+        submit_btn.click(
+            fn=_map_inputs,
+            inputs=[video_input, test_dropdown, side_dropdown, pose_model_dropdown, overlay_layers],
+            outputs=[score_html, pipeline_md, score_details, alerts_md, overlay_video, velocity_md],
+        )
+```
+
+- [ ] **Step 6: Smoke-test the app builds**
+
+```bash
+python3 -c "from app import build_app; build_app(); print('ok')"
+```
+
+Expected: `ok` (Gradio UserWarning about theme is fine, not an error)
+
+- [ ] **Step 7: Run full test suite to check for regressions**
+
+```bash
+pytest tests/ -v --tb=short 2>&1 | tail -15
+```
+
+Expected: all previous tests still pass (62 passing, 1 pre-existing fail in biomechanics), plus 16 new visualizer tests = 78 passing.
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add app.py
+git commit -m "feat: overlay video tab + velocity summary wired in Gradio UI"
+```
+
+---
+
+## Self-review
+
+**Spec coverage:**
+- ✅ `SimpleKalmanFilter` 4-state (Task 1)
+- ✅ `compute_joint_velocity` Kalman-filtered px/s (Task 1)
+- ✅ `_draw_skeleton` COCO bones, confidence-colored joints (Task 2)
+- ✅ `_draw_trails` fading deque-based trails (Task 3)
+- ✅ `_draw_velocity_arrows` speed-colored, direction from consecutive frames (Task 4)
+- ✅ `render_video` layer dispatch, trail history, VideoWriter (Task 5)
+- ✅ `build_velocity_summary` markdown table, >50% detection filter (Task 5)
+- ✅ `overlay_layers` CheckboxGroup in UI (Task 6)
+- ✅ New `🎬 Overlay Video` tab with `gr.Video` + `gr.Markdown` (Task 6)
+- ✅ `process_video` wired with layers param (Task 6)
+- ✅ `vis.last_velocities` stored on instance after `render_video` (Task 5)
+- ✅ Error handling: empty layers → None, empty detections → None, exception → alerts (Task 5 + 6)
+- ✅ All 5 spec test cases covered across Tasks 1–5
+
+**Placeholder scan:** None found. All code blocks are complete.
+
+**Type consistency:**
+- `compute_joint_velocity` returns `dict[int, list[float]]` — used identically in `render_video`, `_draw_velocity_arrows`, and `build_velocity_summary`. ✓
+- `layers: set[str]` in `render_video`; converted from `list[str]` in `process_video` via set comprehension. ✓
+- `vis.last_velocities` set in `render_video`, read in `process_video`. ✓
+- `_draw_velocity_arrows(frame, kps, prev_kps, velocities, frame_idx)` — signature matches call in `render_video`. ✓

docs/superpowers/specs/2026-06-09-pose-model-selector-design.md

@@ -0,0 +1,171 @@
+# Pose Model Selector — Design Spec
+
+**Date:** 2026-06-09  
+**Status:** Approved
+
+## Goal
+
+Expose all available pose estimation models as a selectable dropdown in the Gradio UI, replacing the hard-coded YOLO26l default. Supported families: MediaPipe (Qualcomm HF/ONNX), YOLO26 n→x (local), Sapiens2 0.4B→5B (HF/transformers).
+
+---
+
+## Architecture
+
+### Unified model registry (`config.py`)
+
+Replace `YOLO_POSE_MODELS` with a single `POSE_MODELS` dict. Each entry:
+
+```python
+{
+    "backend": "yolo" | "mediapipe" | "sapiens2",
+    "path": str,        # yolo only — absolute path to local .pt
+    "hf_id": str,       # mediapipe + sapiens2 — HuggingFace repo id
+    "params_m": float,  # millions of parameters
+}
+```
+
+Ordered as displayed in the UI:
+
+| Label | backend | source |
+|---|---|---|
+| `MediaPipe-Pose ⬇ ~16 MB, CPU-friendly` | mediapipe | `qualcomm/MediaPipe-Pose-Estimation` |
+| `YOLO26n — nano (0.7M, fastest)` ★ default | yolo | local checkpoint |
+| `YOLO26s — small (3.5M)` | yolo | local checkpoint |
+| `YOLO26m — medium (9M)` | yolo | local checkpoint |
+| `YOLO26l — large (25.9M)` | yolo | local checkpoint |
+| `YOLO26x — extra-large (57.6M)` | yolo | local checkpoint |
+| `Sapiens2-0.4B ⬇ ~1.6 GB` | sapiens2 | `facebook/sapiens2-pose-0.4b` |
+| `Sapiens2-0.8B ⬇ ~3.2 GB` | sapiens2 | `facebook/sapiens2-pose-0.8b` |
+| `Sapiens2-1B ⬇ ~4 GB` | sapiens2 | `facebook/sapiens2-pose-1b` |
+| `Sapiens2-5B ⬇ ~20 GB, large GPU` | sapiens2 | `facebook/sapiens2-pose-5b` |
+
+```python
+DEFAULT_POSE_MODEL = "YOLO26n — nano (0.7M, fastest)"
+```
+
+Keep `YOLO_POSE_MODEL` and `YOLO_POSE_MODEL_HQ` as string aliases for backward compat with any direct references outside the agent.
+
+---
+
+### Pose2DAgent (`formscout/agents/pose2d.py`)
+
+Three private sub-runners, all returning `list[dict[int, dict]]` (COCO 17 keypoints per frame, same format as today):
+
+#### `_run_yolo(frames, path) -> list[dict]`
+Existing logic, lifted into a named function. Model cached in `_model_cache[path]`.
+
+#### `_run_mediapipe(frames, hf_id) -> list[dict]`
+- Download repo snapshot via `huggingface_hub.snapshot_download(hf_id)`
+- Locate the pose landmark `.onnx` file in the snapshot
+- Load with `onnxruntime.InferenceSession`
+- Preprocess each frame: resize to 256×256, normalize
+- Run inference → 33 BlazePose landmarks
+- Map BlazePose 33 → COCO 17 via fixed index table:
+  ```
+  COCO  0=nose        → BlazePose 0
+  COCO  1=left_eye    → BlazePose 2
+  COCO  2=right_eye   → BlazePose 5
+  COCO  3=left_ear    → BlazePose 7
+  COCO  4=right_ear   → BlazePose 8
+  COCO  5=left_shld   → BlazePose 11
+  COCO  6=right_shld  → BlazePose 12
+  COCO  7=left_elbow  → BlazePose 13
+  COCO  8=right_elbow → BlazePose 14
+  COCO  9=left_wrist  → BlazePose 15
+  COCO 10=right_wrist → BlazePose 16
+  COCO 11=left_hip    → BlazePose 23
+  COCO 12=right_hip   → BlazePose 24
+  COCO 13=left_knee   → BlazePose 25
+  COCO 14=right_knee  → BlazePose 26
+  COCO 15=left_ankle  → BlazePose 27
+  COCO 16=right_ankle → BlazePose 28
+  ```
+- Session cached in `_model_cache[hf_id]`
+
+#### `_run_sapiens2(frames, hf_id) -> list[dict]`
+- Load via `transformers.pipeline("pose-estimation", model=hf_id)`
+- Sapiens2 outputs 308 whole-body keypoints; map first 17 (indices 0–16) to COCO 17 — Sapiens2 preserves COCO ordering for the body subset
+- Pipeline cached in `_model_cache[hf_id]`
+
+#### `Pose2DAgent.run(ingest, model_key)`
+- `model_key: str` replaces `model_path: str` (old param)
+- Looks up `config.POSE_MODELS[model_key]` (falls back to `DEFAULT_POSE_MODEL` if key missing)
+- Dispatches to the appropriate sub-runner
+- Returns `Pose2DResult` — identical contract as today
+
+---
+
+### UI (`app.py`)
+
+Add `gr.Dropdown` for pose model in the input column, below the test/side row:
+
+```python
+pose_model_dropdown = gr.Dropdown(
+    choices=list(config.POSE_MODELS.keys()),
+    value=config.DEFAULT_POSE_MODEL,
+    label="Pose Model",
+)
+```
+
+Update `_map_inputs` to accept and forward `pose_model_key`:
+
+```python
+def _map_inputs(video, test_display_name, side_display, pose_model_key):
+    ...
+    return process_video(video, test_name, side, pose_model_key)
+```
+
+Update `submit_btn.click` inputs to include `pose_model_dropdown`.
+
+`process_video(video_path, test_name, side, pose_model_key)` passes `pose_model_key` through to `director.run()`, which passes it to `Pose2DAgent.run()`. Remove the old `YOLO_POSE_MODELS.get()` lookup from `process_video`.
+
+---
+
+## Data flow
+
+```
+UI dropdown (pose_model_key: str)
+  → process_video()
+  → Director.run(pose_model_key=...)
+  → Pose2DAgent.run(ingest, model_key=pose_model_key)
+  → config.POSE_MODELS[model_key] → {backend, path|hf_id}
+  → _run_yolo / _run_mediapipe / _run_sapiens2
+  → list[dict[int, {x, y, conf}]]  (COCO 17, same contract)
+  → Pose2DResult
+```
+
+---
+
+## Error handling
+
+- Unknown `model_key`: log warning, fall back to `DEFAULT_POSE_MODEL`
+- ONNX file not found in MediaPipe snapshot: `Pose2DResult(confidence=0.0, notes="mediapipe onnx not found")`
+- Sapiens2 / MediaPipe download failure: `Pose2DResult(confidence=0.0, notes=str(e))`
+- All failures are non-fatal; pipeline continues with 0-confidence result and surfaces alert in UI
+
+---
+
+## Dependencies to add (`requirements.txt`)
+
+- `onnxruntime` — MediaPipe ONNX inference
+- `huggingface_hub` — snapshot download for MediaPipe (already likely present via transformers)
+
+Sapiens2 uses `transformers`, already a dependency.
+
+---
+
+## Testing
+
+Each new backend gets a pytest in `tests/test_pose2d.py` that:
+- Mocks the model load (no actual HF download in CI)
+- Passes a 3-frame synthetic IngestResult
+- Asserts `Pose2DResult.keypoints` has 3 entries, each a dict with at most 17 int keys
+- Asserts `confidence` is a float in [0, 1]
+
+---
+
+## Out of scope
+
+- Sapiens2 / MediaPipe accuracy benchmarking
+- Automatic backend selection based on hardware
+- Downloading Sapiens2/MediaPipe checkpoints to local `checkpoints/` directory

docs/superpowers/specs/2026-06-09-pose-visualizer-design.md

@@ -0,0 +1,197 @@
+# Pose Overlay Visualizer — Design Spec
+
+**Date:** 2026-06-09  
+**Status:** Approved
+
+## Goal
+
+Add an annotated overlay video output to the FormScout UI showing skeleton, motion trails, and velocity arrows on top of the original footage, alongside a per-joint velocity summary table. Overlay layers are user-selectable via checkboxes. Adapted from the Laban Movement Analysis project.
+
+---
+
+## Architecture
+
+Three files change or are created. No changes to `pipeline.py`, `types.py`, or any existing agent.
+
+```
+formscout/agents/visualizer.py    ← new
+tests/test_visualizer.py          ← new
+app.py                            ← overlay_layers checkbox, new tab, wiring
+```
+
+The visualizer runs **after** `director.run()` returns in `process_video()` — it is a pure post-processing step, never on the critical scoring path.
+
+---
+
+## Module: `formscout/agents/visualizer.py`
+
+### `compute_joint_velocity(keypoints_per_frame, fps) → dict[int, list[float]]`
+
+- Input: `list[dict[int, {x, y, conf}]]` (COCO-17 pixel coords per frame), `fps: float`
+- Output: `dict[int, list[float]]` — per-joint per-frame speed in **px/s**
+- Method: for each joint index, run a `SimpleKalmanFilter` (1D per axis, constant-velocity model, same structure as Laban's engine) over the (x, y) series. Speed = `sqrt(vx² + vy²)` from the filter's velocity state.
+- Missing keypoints (conf < 0.3 or absent) → speed = 0.0 for that frame, filter state held.
+
+### `SimpleKalmanFilter`
+
+Minimal 4-state Kalman (x, y, vx, vy), identical in structure to the Laban `SimpleKalmanFilter`:
+- Transition: constant-velocity model
+- Measurement: position only (x, y)
+- One instance per joint per video run
+
+### `PoseVisualizer`
+
+#### Constants
+```python
+COCO_SKELETON = [
+    (0,1),(0,2),(1,3),(2,4),          # face
+    (5,6),(5,7),(7,9),(6,8),(8,10),   # arms
+    (5,11),(6,12),(11,12),             # torso
+    (11,13),(13,15),(12,14),(14,16),  # legs
+]
+TRAIL_LENGTH = 10       # frames of trail history
+MAX_ARROW_PX = 40       # arrow scaled so peak velocity → 40px length
+CONF_THRESHOLD = 0.3    # min confidence to draw a keypoint
+```
+
+#### Private methods
+
+**`_draw_skeleton(frame, kps)`**
+- Draw each COCO bone as a line if both endpoints have conf > CONF_THRESHOLD
+- Joint dots: color green→red by confidence using HSV (same as Laban `_confidence_to_color`)
+- Bone color: white
+
+**`_draw_trails(frame, trail_history, frame_idx)`**
+- `trail_history: dict[int, deque(maxlen=TRAIL_LENGTH)]` keyed by joint index
+- Each deque holds `(x, y)` pixel positions from previous frames
+- Draw fading line segments: alpha = segment_position / TRAIL_LENGTH, color white
+
+**`_draw_velocity_arrows(frame, kps, velocities, frame_idx)`**
+- `velocities: dict[int, list[float]]` — speeds per joint per frame
+- Direction vector from consecutive keypoint positions (x[t] - x[t-1], y[t] - y[t-1])
+- Arrow length = `speed / peak_speed * MAX_ARROW_PX` (clamped)
+- Drawn only for joints with conf > CONF_THRESHOLD and speed > 0
+- Color: green=slow, orange=medium, red=fast (same thresholds as Laban intensity)
+
+#### Public method
+
+**`render_video(ingest, pose2d, layers: set[str], output_path: str) → str | None`**
+- `layers`: subset of `{"skeleton", "trails", "velocity_arrows"}`
+- If `layers` is empty → return `None` immediately
+- Pre-computes `compute_joint_velocity(pose2d.keypoints, ingest.fps)`
+- Iterates frames, updates `trail_history`, calls selected `_draw_*` methods
+- Writes output via `cv2.VideoWriter` (codec: `mp4v`, same fps as ingest)
+- Returns output path on success; `None` on any exception (logs warning)
+
+#### Velocity summary
+
+**`build_velocity_summary(keypoints_per_frame, velocities) → str`**
+- For each joint with conf > 0.3 in >50% of frames:
+  - Compute avg and peak speed (px/s)
+- Return markdown table sorted by peak speed descending:
+  ```
+  | Joint         | Avg (px/s) | Peak (px/s) |
+  |---------------|-----------|-------------|
+  | left_knee     | 42.3      | 118.7       |
+  ```
+- Returns empty string if no valid joints
+
+---
+
+## UI changes: `app.py`
+
+### Input column — overlay layer checkboxes
+
+Below `pose_model_dropdown`, add:
+
+```python
+overlay_layers = gr.CheckboxGroup(
+    choices=["Skeleton", "Trails", "Velocity arrows"],
+    value=["Skeleton", "Trails"],
+    label="Overlay Layers",
+)
+```
+
+### Results panel — new tab
+
+Inside the existing `gr.Tabs()` block, add a fourth tab:
+
+```python
+with gr.TabItem("🎬 Overlay Video"):
+    overlay_video = gr.Video(label="Annotated Movement")
+    velocity_md = gr.Markdown("")
+```
+
+### `process_video()` signature
+
+```python
+def process_video(video_path, test_name, side, model_key, layers: list[str]):
+```
+
+After `director.run()`:
+```python
+from formscout.agents.visualizer import PoseVisualizer, build_velocity_summary
+layer_set = {l.lower().replace(" ", "_") for l in layers}
+# map UI labels to internal names:
+# "Skeleton" → "skeleton", "Trails" → "trails", "Velocity arrows" → "velocity_arrows"
+overlay_path = None
+vel_summary = ""
+if layer_set and state.ingest and state.pose2d:
+    try:
+        vis = PoseVisualizer()
+        with tempfile.NamedTemporaryFile(suffix=".mp4", delete=False) as f:
+            out_path = f.name
+        overlay_path = vis.render_video(state.ingest, state.pose2d, layer_set, out_path)
+        if overlay_path:
+            vel_summary = build_velocity_summary(state.pose2d.keypoints, vis.last_velocities)
+    except Exception as e:
+        alerts += f"\n⚠️ Visualizer error: {e}"
+return score_html, pipeline_md, score_details, alerts, overlay_path, vel_summary
+```
+
+`vis.last_velocities` is stored on the instance after `render_video()` to avoid recomputing.
+
+### Event wiring
+
+```python
+submit_btn.click(
+    fn=_map_inputs,
+    inputs=[video_input, test_dropdown, side_dropdown, pose_model_dropdown, overlay_layers],
+    outputs=[score_html, pipeline_md, score_details, alerts_md, overlay_video, velocity_md],
+)
+```
+
+`_map_inputs` gains `overlay_layers` as fifth parameter.
+
+---
+
+## Error handling
+
+| Failure | Behaviour |
+|---|---|
+| All frames have no detections | `render_video()` returns `None`, tab empty, no crash |
+| `cv2.VideoWriter` fails | logs warning, returns `None` |
+| Any exception in visualizer | caught in `process_video()`, appended to alerts, `overlay_path = None` |
+| `layers` is empty | returns `None` immediately, no processing |
+
+The score is always returned regardless of visualizer outcome.
+
+---
+
+## Testing: `tests/test_visualizer.py`
+
+- Synthetic `IngestResult`: 5 blank 480×640 BGR frames, fps=30
+- Synthetic `Pose2DResult`: 17 keypoints per frame at fixed positions with conf=0.9
+- `test_render_video_creates_file`: assert output `.mp4` exists and size > 0
+- `test_compute_joint_velocity_shape`: assert 17-key dict, each list length == 5
+- `test_empty_layers_returns_none`: assert `render_video(..., layers=set())` returns `None`
+- `test_no_detections_returns_none`: all-empty keypoints → `None`
+- `test_velocity_summary_markdown`: assert output contains `|` (table) and at least one joint name
+
+---
+
+## Out of scope
+
+- Frame-by-frame metrics synced to video playback (Phase 4 / custom Svelte)
+- Multi-person tracking
+- Saving overlay video to Hugging Face Hub (tracing feature, Phase 4)

formscout.egg-info/PKG-INFO

@@ -1,4 +1,4 @@
-Metadata-Version: 2.4
-Name: formscout
-Version: 0.1.0
-Requires-Python: >=3.11
+Metadata-Version: 2.4
+Name: formscout
+Version: 0.1.0
+Requires-Python: >=3.11

formscout.egg-info/SOURCES.txt

@@ -1,26 +1,38 @@
-README.md
-pyproject.toml
-formscout/__init__.py
-formscout/config.py
-formscout/pipeline.py
-formscout/run.py
-formscout/tracing.py
-formscout/types.py
-formscout.egg-info/PKG-INFO
-formscout.egg-info/SOURCES.txt
-formscout.egg-info/dependency_links.txt
-formscout.egg-info/top_level.txt
-formscout/agents/__init__.py
-formscout/agents/biomechanics.py
-formscout/agents/body3d.py
-formscout/agents/ingest.py
-formscout/agents/pose2d.py
-formscout/rubric/__init__.py
-formscout/rubric/deep_squat.py
-formscout/serving/__init__.py
-formscout/ui/__init__.py
-tests/test_biomechanics.py
-tests/test_body3d.py
-tests/test_ingest.py
-tests/test_pose2d.py
+README.md
+pyproject.toml
+formscout/__init__.py
+formscout/config.py
+formscout/pipeline.py
+formscout/run.py
+formscout/tracing.py
+formscout/types.py
+formscout.egg-info/PKG-INFO
+formscout.egg-info/SOURCES.txt
+formscout.egg-info/dependency_links.txt
+formscout.egg-info/top_level.txt
+formscout/agents/__init__.py
+formscout/agents/biomechanics.py
+formscout/agents/body3d.py
+formscout/agents/classifier.py
+formscout/agents/ingest.py
+formscout/agents/judge.py
+formscout/agents/pose2d.py
+formscout/agents/report.py
+formscout/rubric/__init__.py
+formscout/rubric/active_slr.py
+formscout/rubric/deep_squat.py
+formscout/rubric/hurdle_step.py
+formscout/rubric/inline_lunge.py
+formscout/rubric/rotary_stability.py
+formscout/rubric/shoulder_mobility.py
+formscout/rubric/trunk_stability_pushup.py
+formscout/serving/__init__.py
+formscout/serving/llama_cpp.py
+formscout/ui/__init__.py
+formscout/ui/theme.py
+tests/test_biomechanics.py
+tests/test_body3d.py
+tests/test_ingest.py
+tests/test_phase2.py
+tests/test_pose2d.py
 tests/test_types.py

formscout.egg-info/dependency_links.txt

@@ -1 +1 @@
-
+

formscout.egg-info/top_level.txt

@@ -1 +1 @@
-formscout
+formscout

formscout/agents/pose2d.py

@@ -1,95 +1,232 @@
-"""
-Pose2DAgent — 2D per-frame keypoint extraction using YOLO or Sapiens2 backends.
-
-Input:  IngestResult
-Output: Pose2DResult(keypoints per frame, fps, confidence)
-Failure: returns Pose2DResult with confidence=0.0 and notes.
-Model:  YOLO26l-Pose (AGPL-3.0, 25.9M params, mAP50 90.5, public).
-        Alt: YOLO26x-Pose (57.6M, mAP50 91.6) via config.YOLO_POSE_MODEL_HQ.
-        Fallback: Sapiens2 Pose (CC-BY-NC-4.0, ~0.6B, gated — access accepted).
-Gated: Primary no; fallback yes (accepted).
-"""
-from __future__ import annotations
-
-import numpy as np
-
-from formscout import config
-from formscout.types import IngestResult, Pose2DResult
-
-# COCO 17-keypoint names for downstream consumers
-COCO_KEYPOINTS = [
-    "nose", "left_eye", "right_eye", "left_ear", "right_ear",
-    "left_shoulder", "right_shoulder", "left_elbow", "right_elbow",
-    "left_wrist", "right_wrist", "left_hip", "right_hip",
-    "left_knee", "right_knee", "left_ankle", "right_ankle",
-]
-
-_model = None
-
-
-def _get_model():
-    """Load YOLO pose model once at module level."""
-    global _model
-    if _model is None:
-        try:
-            from ultralytics import YOLO
-            _model = YOLO(config.YOLO_POSE_MODEL)
-        except Exception as e:
-            raise RuntimeError(f"Failed to load YOLO pose model: {e}")
-    return _model
-
-
-class Pose2DAgent:
-    """Extracts 2D keypoints per frame from ingested video."""
-
-    def run(self, ingest: IngestResult) -> Pose2DResult:
-        if not ingest.frames:
-            return Pose2DResult(
-                keypoints=[], fps=ingest.fps,
-                confidence=0.0, notes="no frames in ingest",
-            )
-
-        try:
-            model = _get_model()
-        except RuntimeError as e:
-            return Pose2DResult(
-                keypoints=[{} for _ in ingest.frames],
-                fps=ingest.fps,
-                confidence=0.0,
-                notes=str(e),
-            )
-
-        keypoints_per_frame: list[dict] = []
-        total_conf = 0.0
-        n_detected = 0
-
-        for frame in ingest.frames:
-            try:
-                results = model(frame, verbose=False)
-                frame_kps: dict[int, dict] = {}
-                if results and results[0].keypoints is not None:
-                    kps = results[0].keypoints
-                    if kps.xy is not None and len(kps.xy) > 0:
-                        # Take highest-confidence person (index 0 after NMS sort)
-                        xy = kps.xy[0].cpu().numpy()      # (17, 2)
-                        conf = kps.conf[0].cpu().numpy()  # (17,)
-                        for j in range(len(xy)):
-                            frame_kps[j] = {
-                                "x": float(xy[j, 0]),
-                                "y": float(xy[j, 1]),
-                                "conf": float(conf[j]),
-                            }
-                        total_conf += float(conf.mean())
-                        n_detected += 1
-                keypoints_per_frame.append(frame_kps)
-            except Exception:
-                keypoints_per_frame.append({})
-
-        overall_conf = (total_conf / n_detected) if n_detected > 0 else 0.0
-        notes = "" if n_detected > 0 else "no person detected in any frame"
-        return Pose2DResult(
-            keypoints=keypoints_per_frame,
-            fps=ingest.fps,
-            confidence=overall_conf,
-            notes=notes,
-        )
+"""
+Pose2DAgent — 2D per-frame keypoint extraction.
+
+Backends: yolo (local checkpoints, ultralytics), mediapipe (official Tasks API,
+          local .task checkpoint), sapiens2 (Meta HF/transformers).
+All backends output COCO-17 keypoints: dict[int, {x, y, conf}] per frame.
+
+Input:  IngestResult
+Output: Pose2DResult(keypoints per frame, fps, confidence)
+Failure: Pose2DResult(confidence=0.0, notes=<reason>) — never raises.
+Gated: yolo=no; mediapipe=no (local checkpoint); sapiens2=yes (access accepted).
+"""
+from __future__ import annotations
+
+import logging
+import numpy as np
+
+from formscout import config
+from formscout.types import IngestResult, Pose2DResult
+
+logger = logging.getLogger(__name__)
+
+COCO_KEYPOINTS = [
+    "nose", "left_eye", "right_eye", "left_ear", "right_ear",
+    "left_shoulder", "right_shoulder", "left_elbow", "right_elbow",
+    "left_wrist", "right_wrist", "left_hip", "right_hip",
+    "left_knee", "right_knee", "left_ankle", "right_ankle",
+]
+
+# BlazePose-33 source indices → COCO-17 target indices
+# BlazePose: 0=nose, 2=left_eye, 5=right_eye, 7=left_ear, 8=right_ear,
+#            11=left_shoulder, 12=right_shoulder, 13=left_elbow, 14=right_elbow,
+#            15=left_wrist, 16=right_wrist, 23=left_hip, 24=right_hip,
+#            25=left_knee, 26=right_knee, 27=left_ankle, 28=right_ankle
+_BP_SRC = [0, 2, 5, 7, 8, 11, 12, 13, 14, 15, 16, 23, 24, 25, 26, 27, 28]
+_BP_DST = list(range(17))  # COCO indices 0..16
+
+_model_cache: dict[str, object] = {}
+
+
+# ── YOLO backend ──────────────────────────────────────────────────────────────
+
+def _get_yolo(path: str) -> object:
+    if path not in _model_cache:
+        from ultralytics import YOLO
+        _model_cache[path] = YOLO(path)
+    return _model_cache[path]
+
+
+def _run_yolo(frames: list, path: str) -> list[dict]:
+    model = _get_yolo(path)
+    out = []
+    for frame in frames:
+        try:
+            results = model(frame, verbose=False)
+            kps: dict[int, dict] = {}
+            if results and results[0].keypoints is not None:
+                kp = results[0].keypoints
+                if kp.xy is not None and len(kp.xy) > 0:
+                    xy = kp.xy[0].cpu().numpy()
+                    conf = kp.conf[0].cpu().numpy()
+                    for j in range(min(len(xy), 17)):
+                        kps[j] = {"x": float(xy[j, 0]), "y": float(xy[j, 1]), "conf": float(conf[j])}
+            out.append(kps)
+        except Exception:
+            out.append({})
+    return out
+
+
+# ── MediaPipe backend (official Tasks API, local .task checkpoint) ────────────
+
+def _get_mediapipe_landmarker(path: str) -> object:
+    """Return PoseLandmarker cached by model path."""
+    cache_key = f"mp:{path}"
+    if cache_key not in _model_cache:
+        from mediapipe.tasks import python as mp_tasks
+        from mediapipe.tasks.python import vision
+
+        options = vision.PoseLandmarkerOptions(
+            base_options=mp_tasks.BaseOptions(model_asset_path=path),
+            running_mode=vision.RunningMode.IMAGE,
+            num_poses=1,
+            min_pose_detection_confidence=0.4,
+            min_pose_presence_confidence=0.4,
+            min_tracking_confidence=0.4,
+        )
+        _model_cache[cache_key] = vision.PoseLandmarker.create_from_options(options)
+    return _model_cache[cache_key]
+
+
+def _run_mediapipe(frames: list, path: str) -> list[dict]:
+    import cv2
+    import mediapipe as mp
+
+    try:
+        landmarker = _get_mediapipe_landmarker(path)
+    except Exception as e:
+        logger.warning("mediapipe load failed: %s", e)
+        return [{} for _ in frames]
+
+    out = []
+    for frame in frames:
+        try:
+            h, w = frame.shape[:2]
+            rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
+            mp_image = mp.Image(image_format=mp.ImageFormat.SRGB, data=rgb)
+            detection = landmarker.detect(mp_image)
+
+            kps: dict[int, dict] = {}
+            if detection.pose_landmarks:
+                lms = detection.pose_landmarks[0]
+                for coco_idx, bp_idx in zip(_BP_DST, _BP_SRC):
+                    if bp_idx < len(lms):
+                        lm = lms[bp_idx]
+                        kps[coco_idx] = {
+                            "x": float(lm.x * w),
+                            "y": float(lm.y * h),
+                            "conf": float(lm.visibility),
+                        }
+            out.append(kps)
+        except Exception:
+            out.append({})
+    return out
+
+
+# ── Sapiens2 backend (Meta HF, transformers) ──────────────────────────────────
+
+def _get_sapiens2(hf_id: str) -> object:
+    if hf_id not in _model_cache:
+        from transformers import pipeline as hf_pipeline
+        _model_cache[hf_id] = hf_pipeline("pose-estimation", model=hf_id)
+    return _model_cache[hf_id]
+
+
+def _run_sapiens2(frames: list, hf_id: str) -> list[dict]:
+    try:
+        pipe = _get_sapiens2(hf_id)
+    except Exception as e:
+        logger.warning("sapiens2 load failed: %s", e)
+        return [{} for _ in frames]
+
+    from PIL import Image
+
+    out = []
+    for frame in frames:
+        try:
+            pil_img = Image.fromarray(frame)
+            result = pipe(pil_img)
+
+            if not result:
+                out.append({})
+                continue
+
+            # Take highest-confidence person (first result)
+            person = result[0]
+            keypoints = person.get("keypoints", [])
+            scores = person.get("keypoint_scores", [])
+
+            # Build name→(x, y, score) lookup from pipeline output
+            kp_lookup: dict[str, tuple] = {}
+            for i, kp in enumerate(keypoints):
+                if isinstance(kp, dict):
+                    name = kp.get("label", "")
+                    x, y = kp.get("x", 0.0), kp.get("y", 0.0)
+                else:
+                    name = ""
+                    x, y = float(kp[0]), float(kp[1])
+                score = float(scores[i]) if i < len(scores) else 0.0
+                if name:
+                    kp_lookup[name] = (x, y, score)
+
+            kps: dict[int, dict] = {}
+            for coco_idx, name in enumerate(COCO_KEYPOINTS):
+                if name in kp_lookup:
+                    x, y, s = kp_lookup[name]
+                    kps[coco_idx] = {"x": x, "y": y, "conf": s}
+            out.append(kps)
+        except Exception:
+            out.append({})
+    return out
+
+
+# ── Agent ─────────────────────────────────────────────────────────────────────
+
+class Pose2DAgent:
+    """Extracts COCO-17 keypoints per frame; dispatches to YOLO, MediaPipe, or Sapiens2."""
+
+    def run(self, ingest: IngestResult, model_key: str | None = None) -> Pose2DResult:
+        if not ingest.frames:
+            return Pose2DResult(keypoints=[], fps=ingest.fps, confidence=0.0, notes="no frames in ingest")
+
+        key = model_key or config.DEFAULT_POSE_MODEL
+        spec = config.POSE_MODELS.get(key)
+        if spec is None:
+            logger.warning("Unknown model_key %r — falling back to %s", key, config.DEFAULT_POSE_MODEL)
+            spec = config.POSE_MODELS[config.DEFAULT_POSE_MODEL]
+
+        backend = spec["backend"]
+        try:
+            if backend == "yolo":
+                kps_per_frame = _run_yolo(ingest.frames, spec["path"])
+            elif backend == "mediapipe":
+                kps_per_frame = _run_mediapipe(ingest.frames, spec["path"])
+            elif backend == "sapiens2":
+                kps_per_frame = _run_sapiens2(ingest.frames, spec["hf_id"])
+            else:
+                return Pose2DResult(
+                    keypoints=[{} for _ in ingest.frames],
+                    fps=ingest.fps, confidence=0.0,
+                    notes=f"unknown backend: {backend}",
+                )
+        except Exception as e:
+            return Pose2DResult(
+                keypoints=[{} for _ in ingest.frames],
+                fps=ingest.fps, confidence=0.0,
+                notes=str(e),
+            )
+
+        n_detected = sum(1 for f in kps_per_frame if f)
+        total_conf = sum(
+            sum(kp["conf"] for kp in f.values()) / len(f)
+            for f in kps_per_frame if f
+        )
+        overall_conf = (total_conf / n_detected) if n_detected > 0 else 0.0
+        notes = "" if n_detected > 0 else "no person detected in any frame"
+
+        return Pose2DResult(
+            keypoints=kps_per_frame,
+            fps=ingest.fps,
+            confidence=overall_conf,
+            notes=notes,
+        )

formscout/agents/visualizer.py

@@ -0,0 +1,371 @@
+"""
+PoseVisualizer — annotated overlay video with skeleton, trails, velocity arrows.
+
+Input:  IngestResult + Pose2DResult
+Output: .mp4 path (or None on failure/empty layers)
+Failure: returns None, never raises.
+"""
+from __future__ import annotations
+
+import colorsys
+import logging
+import math
+import tempfile
+from collections import deque
+
+import cv2
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+# ── COCO constants ────────────────────────────────────────────────────────────
+
+COCO_KEYPOINTS = [
+    "nose", "left_eye", "right_eye", "left_ear", "right_ear",
+    "left_shoulder", "right_shoulder", "left_elbow", "right_elbow",
+    "left_wrist", "right_wrist", "left_hip", "right_hip",
+    "left_knee", "right_knee", "left_ankle", "right_ankle",
+]
+
+COCO_SKELETON = [
+    (0, 1), (0, 2), (1, 3), (2, 4),          # face
+    (5, 6), (5, 7), (7, 9), (6, 8), (8, 10), # arms
+    (5, 11), (6, 12), (11, 12),               # torso
+    (11, 13), (13, 15), (12, 14), (14, 16),  # legs
+]
+
+TRAIL_LENGTH = 10
+MAX_ARROW_PX = 40
+CONF_THRESHOLD = 0.3
+
+
+# ── Kalman filter ─────────────────────────────────────────────────────────────
+
+class SimpleKalmanFilter:
+    """4-state Kalman filter (x, y, vx, vy) for joint tracking."""
+
+    def __init__(self, process_noise: float = 0.01, measurement_noise: float = 0.1):
+        self.is_initialized = False
+        self.state = np.zeros(4)
+        self.cov = np.eye(4) * 0.1
+        self.Q = np.eye(4) * process_noise
+        self.R = np.eye(2) * measurement_noise
+        self.H = np.array([[1, 0, 0, 0], [0, 1, 0, 0]], dtype=float)
+
+    def predict(self, dt: float = 1.0):
+        F = np.array([[1, 0, dt, 0], [0, 1, 0, dt], [0, 0, 1, 0], [0, 0, 0, 1]], dtype=float)
+        self.state = F @ self.state
+        self.cov = F @ self.cov @ F.T + self.Q
+
+    def update(self, x: float, y: float):
+        z = np.array([x, y])
+        if not self.is_initialized:
+            self.state[:2] = z
+            self.is_initialized = True
+            return
+        S = self.H @ self.cov @ self.H.T + self.R
+        K = self.cov @ self.H.T @ np.linalg.inv(S)
+        self.state = self.state + K @ (z - self.H @ self.state)
+        self.cov = (np.eye(4) - K @ self.H) @ self.cov
+
+    def velocity_magnitude(self) -> float:
+        vx, vy = self.state[2], self.state[3]
+        return math.sqrt(vx * vx + vy * vy)
+
+    def velocity_vector(self) -> tuple[float, float]:
+        return float(self.state[2]), float(self.state[3])
+
+
+# ── Velocity computation ──────────────────────────────────────────────────────
+
+def compute_joint_velocity(
+    keypoints_per_frame: list[dict],
+    fps: float,
+) -> dict[int, list[float]]:
+    """
+    Compute Kalman-filtered per-joint speed (px/s) for each frame.
+
+    Returns dict[joint_idx, [speed_frame0, ...]] for all 17 COCO joints.
+    Missing/low-confidence keypoints yield speed=0.0 for that frame.
+    """
+    dt = 1.0 / fps if fps > 0 else 1.0
+    filters: dict[int, SimpleKalmanFilter] = {j: SimpleKalmanFilter() for j in range(17)}
+    result: dict[int, list[float]] = {j: [] for j in range(17)}
+
+    for frame_kps in keypoints_per_frame:
+        for j in range(17):
+            kf = filters[j]
+            kp = frame_kps.get(j)
+            kf.predict(dt)
+            if kp and kp.get("conf", 0.0) >= CONF_THRESHOLD:
+                kf.update(kp["x"], kp["y"])
+                speed = kf.velocity_magnitude()
+            else:
+                speed = 0.0
+            result[j].append(speed)
+
+    return result
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _conf_to_bgr(conf: float) -> tuple[int, int, int]:
+    """Map confidence 0→1 to BGR color red→green via HSV."""
+    hue = conf * 120.0 / 360.0
+    r, g, b = colorsys.hsv_to_rgb(hue, 1.0, 1.0)
+    return (int(b * 255), int(g * 255), int(r * 255))
+
+
+# ── PoseVisualizer ────────────────────────────────────────────────────────────
+
+class PoseVisualizer:
+    """Renders skeleton, trails, and velocity arrows onto video frames."""
+
+    def __init__(self):
+        self.last_velocities: dict[int, list[float]] = {}
+
+    # ── Skeleton ──────────────────────────────────────────────────────────────
+
+    def _draw_skeleton(self, frame: np.ndarray, kps: dict) -> np.ndarray:
+        """Draw COCO-17 bones (white) and joints (confidence-colored) onto frame."""
+        visible = {j: kp for j, kp in kps.items() if kp.get("conf", 0.0) >= CONF_THRESHOLD}
+
+        # Bones
+        for j1, j2 in COCO_SKELETON:
+            if j1 in visible and j2 in visible:
+                p1 = (int(visible[j1]["x"]), int(visible[j1]["y"]))
+                p2 = (int(visible[j2]["x"]), int(visible[j2]["y"]))
+                cv2.line(frame, p1, p2, (255, 255, 255), 2)
+
+        # Joints
+        for j, kp in visible.items():
+            pt = (int(kp["x"]), int(kp["y"]))
+            color = _conf_to_bgr(kp["conf"])
+            cv2.circle(frame, pt, 4, color, -1)
+            cv2.circle(frame, pt, 5, (255, 255, 255), 1)
+
+        return frame
+
+    # ── Trails ───────────────────────────────────────────────────────────────
+
+    def _draw_trails(self, frame: np.ndarray, trail_history: dict) -> np.ndarray:
+        """Draw fading motion trails for each joint."""
+        for joint_idx, trail in trail_history.items():
+            pts = list(trail)
+            if len(pts) < 2:
+                continue
+            for i in range(1, len(pts)):
+                alpha = i / len(pts)
+                brightness = int(255 * alpha)
+                color = (brightness, brightness, brightness)
+                thickness = max(1, int(3 * alpha))
+                p1 = (int(pts[i - 1][0]), int(pts[i - 1][1]))
+                p2 = (int(pts[i][0]), int(pts[i][1]))
+                cv2.line(frame, p1, p2, color, thickness)
+        return frame
+
+    # ── Velocity arrows ───────────────────────────────────────────────────────
+
+    def _draw_velocity_arrows(
+        self,
+        frame: np.ndarray,
+        kps: dict,
+        prev_kps: dict | None,
+        velocities: dict[int, list[float]],
+        frame_idx: int,
+    ) -> np.ndarray:
+        """Draw per-joint velocity arrows scaled by speed."""
+        if prev_kps is None:
+            return frame
+
+        all_speeds = [velocities[j][frame_idx] for j in range(17) if frame_idx < len(velocities.get(j, []))]
+        peak = max(all_speeds) if all_speeds else 1.0
+        if peak == 0.0:
+            return frame
+
+        for j in range(17):
+            kp = kps.get(j)
+            pk = prev_kps.get(j)
+            if not kp or not pk:
+                continue
+            if kp.get("conf", 0.0) < CONF_THRESHOLD:
+                continue
+            speeds = velocities.get(j, [])
+            if frame_idx >= len(speeds):
+                continue
+            speed = speeds[frame_idx]
+            if speed == 0.0:
+                continue
+
+            dx = kp["x"] - pk["x"]
+            dy = kp["y"] - pk["y"]
+            mag = math.sqrt(dx * dx + dy * dy)
+            if mag < 1e-6:
+                continue
+
+            length = min(speed / peak * MAX_ARROW_PX, MAX_ARROW_PX)
+            nx, ny = dx / mag, dy / mag
+            start = (int(kp["x"]), int(kp["y"]))
+            end = (int(kp["x"] + nx * length), int(kp["y"] + ny * length))
+
+            ratio = speed / peak
+            if ratio < 0.33:
+                color = (0, 200, 0)     # green
+            elif ratio < 0.66:
+                color = (0, 140, 255)   # orange
+            else:
+                color = (0, 0, 255)     # red
+
+            cv2.arrowedLine(frame, start, end, color, 2, tipLength=0.35)
+
+        return frame
+
+    # ── Public ────────────────────────────────────────────────────────────────
+
+    def render_video(
+        self,
+        ingest,
+        pose2d,
+        layers: set[str],
+        output_path: str,
+    ) -> str | None:
+        """
+        Render annotated video. Returns output_path on success, None otherwise.
+        layers: subset of {"skeleton", "trails", "velocity_arrows"}
+        """
+        if not layers:
+            return None
+
+        if not any(pose2d.keypoints):
+            return None
+
+        try:
+            velocities = compute_joint_velocity(pose2d.keypoints, ingest.fps)
+            self.last_velocities = velocities
+
+            frames = ingest.frames
+            orig_h, orig_w = frames[0].shape[:2]
+            fps = ingest.fps or 30.0
+
+            # Cap at 1280px wide — big frames are slow and don't need to be HQ
+            max_w = 1280
+            if orig_w > max_w:
+                scale = max_w / orig_w
+                out_w = max_w
+                out_h = int(orig_h * scale)
+            else:
+                scale = 1.0
+                out_w, out_h = orig_w, orig_h
+
+            # Scale keypoint coordinates to match resized frames
+            def _scale_kps(kps: dict) -> dict:
+                if scale == 1.0:
+                    return kps
+                return {
+                    j: {**kp, "x": kp["x"] * scale, "y": kp["y"] * scale}
+                    for j, kp in kps.items()
+                }
+
+            scaled_keypoints = [_scale_kps(k) for k in pose2d.keypoints]
+
+            # Write raw mp4v to a temp file, then remux with ffmpeg faststart
+            import subprocess
+            import tempfile as _tf
+            tmp = _tf.NamedTemporaryFile(suffix="_raw.mp4", delete=False)
+            tmp_path = tmp.name
+            tmp.close()
+
+            fourcc = cv2.VideoWriter_fourcc(*"mp4v")
+            writer = cv2.VideoWriter(tmp_path, fourcc, fps, (out_w, out_h))
+            if not writer.isOpened():
+                logger.warning("VideoWriter failed to open: %s", tmp_path)
+                return None
+
+            trail_history: dict[int, deque] = {j: deque(maxlen=TRAIL_LENGTH) for j in range(17)}
+            prev_kps: dict | None = None
+
+            for frame_idx, (frame, kps) in enumerate(zip(frames, scaled_keypoints)):
+                if scale != 1.0:
+                    out_frame = cv2.resize(frame, (out_w, out_h), interpolation=cv2.INTER_AREA)
+                else:
+                    out_frame = frame.copy()
+
+                if "trails" in layers:
+                    for j, kp in kps.items():
+                        if kp.get("conf", 0.0) >= CONF_THRESHOLD:
+                            trail_history[j].append((kp["x"], kp["y"]))
+                    out_frame = self._draw_trails(out_frame, trail_history)
+
+                if "skeleton" in layers:
+                    out_frame = self._draw_skeleton(out_frame, kps)
+
+                if "velocity_arrows" in layers:
+                    out_frame = self._draw_velocity_arrows(
+                        out_frame, kps, prev_kps, velocities, frame_idx
+                    )
+
+                writer.write(out_frame)
+                prev_kps = kps
+
+            writer.release()
+
+            # Remux with faststart so browsers can seek without downloading the whole file
+            try:
+                subprocess.run(
+                    ["ffmpeg", "-y", "-i", tmp_path, "-c", "copy",
+                     "-movflags", "+faststart", output_path],
+                    check=True, capture_output=True,
+                )
+                import os
+                os.unlink(tmp_path)
+            except Exception as ffmpeg_err:
+                logger.warning("ffmpeg remux failed (%s) — using raw mp4v", ffmpeg_err)
+                import shutil
+                shutil.move(tmp_path, output_path)
+
+            return output_path
+
+        except Exception as e:
+            logger.warning("render_video failed: %s", e)
+            return None
+
+
+# ── Velocity summary ──────────────────────────────────────────────────────────
+
+def build_velocity_summary(
+    keypoints_per_frame: list[dict],
+    velocities: dict[int, list[float]],
+) -> str:
+    """Return markdown table of per-joint avg/peak velocity. Empty string if no valid joints."""
+    n_frames = len(keypoints_per_frame)
+    if n_frames == 0:
+        return ""
+
+    rows = []
+    for j in range(17):
+        detected = sum(
+            1 for kps in keypoints_per_frame
+            if kps.get(j, {}).get("conf", 0.0) >= CONF_THRESHOLD
+        )
+        if detected < n_frames * 0.5:
+            continue
+
+        speeds = velocities.get(j, [])
+        if not speeds:
+            continue
+
+        avg_speed = sum(speeds) / len(speeds)
+        peak_speed = max(speeds)
+        rows.append((COCO_KEYPOINTS[j], avg_speed, peak_speed))
+
+    if not rows:
+        return ""
+
+    rows.sort(key=lambda r: r[2], reverse=True)
+    lines = [
+        "| Joint | Avg (px/s) | Peak (px/s) |",
+        "|---|---|---|",
+    ]
+    for name, avg, peak in rows:
+        lines.append(f"| {name} | {avg:.1f} | {peak:.1f} |")
+    return "\n".join(lines)

formscout/config.py

@@ -8,8 +8,89 @@ from pathlib import Path
 ROOT = Path(__file__).parent.parent
 
 # ─── Model IDs ───────────────────────────────────────────────────────────────
-YOLO_POSE_MODEL = str(ROOT / "checkpoints" / "yolo26" / "yolo26l-pose.pt")
-YOLO_POSE_MODEL_HQ = str(ROOT / "checkpoints" / "yolo26" / "yolo26x-pose.pt")
+_YOLO_DIR = ROOT / "checkpoints" / "yolo26"
+
+POSE_MODELS: dict[str, dict] = {
+    # ── MediaPipe (official Tasks API, local checkpoint) ───────────────────
+    "MediaPipe-Pose — full (~9 MB, CPU-friendly)": {
+        "backend": "mediapipe",
+        "path": str(ROOT / "checkpoints" / "mediapipe" / "pose_landmarker_full.task"),
+        "params_m": 4.2,
+    },
+    # ── YOLO26 (local checkpoints) ─────────────────────────────────────────
+    "YOLO26n — nano (0.7M, fastest)": {
+        "backend": "yolo",
+        "path": str(_YOLO_DIR / "yolo26n-pose.pt"),
+        "params_m": 0.7,
+    },
+    "YOLO26s — small (3.5M)": {
+        "backend": "yolo",
+        "path": str(_YOLO_DIR / "yolo26s-pose.pt"),
+        "params_m": 3.5,
+    },
+    "YOLO26m — medium (9M)": {
+        "backend": "yolo",
+        "path": str(_YOLO_DIR / "yolo26m-pose.pt"),
+        "params_m": 9.0,
+    },
+    "YOLO26l — large (25.9M)": {
+        "backend": "yolo",
+        "path": str(_YOLO_DIR / "yolo26l-pose.pt"),
+        "params_m": 25.9,
+    },
+    "YOLO26x — extra-large (57.6M)": {
+        "backend": "yolo",
+        "path": str(_YOLO_DIR / "yolo26x-pose.pt"),
+        "params_m": 57.6,
+    },
+    # ── Sapiens2 (Phase 3 — needs custom repo + detector, 308-kp Sociopticon) ─
+    "Sapiens2-0.4B [Phase 3, ~1.6 GB]": {
+        "backend": "sapiens2",
+        "hf_id": "facebook/sapiens2-pose-0.4b",
+        "params_m": 400,
+    },
+    "Sapiens2-0.8B [Phase 3, ~3.2 GB]": {
+        "backend": "sapiens2",
+        "hf_id": "facebook/sapiens2-pose-0.8b",
+        "params_m": 800,
+    },
+    "Sapiens2-1B [Phase 3, ~6 GB]": {
+        "backend": "sapiens2",
+        "hf_id": "facebook/sapiens2-pose-1b",
+        "params_m": 1000,
+    },
+    "Sapiens2-5B [Phase 3, ~20 GB, large GPU]": {
+        "backend": "sapiens2",
+        "hf_id": "facebook/sapiens2-pose-5b",
+        "params_m": 5000,
+    },
+}
+
+DEFAULT_POSE_MODEL = "YOLO26n — nano (0.7M, fastest)"
+
+
+def _is_model_available(spec: dict) -> bool:
+    """Return True if the model checkpoint is present and the backend is importable."""
+    backend = spec["backend"]
+    if backend in ("yolo", "mediapipe"):
+        return Path(spec["path"]).exists()
+    if backend == "sapiens2":
+        try:
+            import sapiens  # noqa: F401  — custom repo must be installed
+            return True
+        except ImportError:
+            return False
+    return False
+
+
+def available_pose_models() -> dict[str, dict]:
+    """Subset of POSE_MODELS whose checkpoints/backends are actually ready."""
+    return {name: spec for name, spec in POSE_MODELS.items() if _is_model_available(spec)}
+
+
+# Backward-compat aliases
+YOLO_POSE_MODEL = str(_YOLO_DIR / "yolo26l-pose.pt")
+YOLO_POSE_MODEL_HQ = str(_YOLO_DIR / "yolo26x-pose.pt")
 SAM_CHECKPOINT = "sam2.1_hiera_base_plus.pt"
 SAM_3D_CHECKPOINT = ROOT / "checkpoints" / "sam-3d-body-dinov3" / "model.ckpt"
 SAM_3D_HF_REPO = "facebook/sam-3d-body-dinov3"

formscout/pipeline.py

@@ -37,10 +37,11 @@ class Director:
         self._judge = JudgeAgent()
         self._report = ReportAgent()
 
-    def run(self, video_path: str, test_name: str = "deep_squat", side: str = "na") -> PipelineState:
+    def run(self, video_path: str, test_name: str = "deep_squat", side: str = "na", model_key: str | None = None) -> PipelineState:
         """
         Run the full pipeline on a single video.
         test_name/side serve as manual override when provided (skips classifier).
+        model_key selects the pose backend (see config.POSE_MODELS).
         """
         state = PipelineState(video_path=video_path)
 
@@ -51,7 +52,7 @@ class Director:
             return state
 
         # ─── Pose 2D ───
-        state.pose2d = self._pose2d.run(state.ingest)
+        state.pose2d = self._pose2d.run(state.ingest, model_key=model_key)
         if state.pose2d.confidence < config.MIN_CONFIDENCE:
             state.warnings.append("pose2d: low confidence — no clear person detected")
 

formscout/startup.py

@@ -0,0 +1,47 @@
+"""
+Checkpoint bootstrap — downloads missing model files from HF model repo on first run.
+Called once at app startup before build_app(); no-ops if files already present.
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+CHECKPOINT_REPO = "silas-therapy/formscout-checkpoints"
+ROOT = Path(__file__).parent.parent
+
+_CHECKPOINTS = [
+    "checkpoints/yolo26/yolo26n-pose.pt",
+    "checkpoints/yolo26/yolo26s-pose.pt",
+    "checkpoints/yolo26/yolo26m-pose.pt",
+    "checkpoints/yolo26/yolo26l-pose.pt",
+    "checkpoints/yolo26/yolo26x-pose.pt",
+    "checkpoints/mediapipe/pose_landmarker_full.task",
+]
+
+
+def ensure_checkpoints() -> None:
+    """Download any missing checkpoints from silas-therapy/formscout-checkpoints."""
+    try:
+        from huggingface_hub import hf_hub_download
+    except ImportError:
+        logger.warning("huggingface_hub not installed — skipping checkpoint download")
+        return
+
+    for rel_path in _CHECKPOINTS:
+        local = ROOT / rel_path
+        if local.exists():
+            continue
+        logger.info("Downloading %s ...", rel_path)
+        try:
+            local.parent.mkdir(parents=True, exist_ok=True)
+            hf_hub_download(
+                repo_id=CHECKPOINT_REPO,
+                filename=rel_path,
+                local_dir=str(ROOT),
+            )
+            logger.info("Downloaded %s", rel_path)
+        except Exception as e:
+            logger.warning("Failed to download %s: %s", rel_path, e)

requirements.txt

@@ -11,3 +11,5 @@ ruff>=0.4
 black>=24.4
 huggingface_hub>=0.23
 transformers>=4.44
+onnxruntime>=1.18
+mediapipe>=0.10

tests/test_pose2d.py

@@ -1,6 +1,9 @@
 """Tests for Pose2DAgent — model-dependent, skips if YOLO unavailable."""
-import pytest
+import inspect
+import unittest.mock as mock
+
 import numpy as np
+import pytest
 
 from formscout.types import IngestResult, Pose2DResult
 
@@ -46,3 +49,60 @@ class TestPose2DAgent:
         result = pose2d_agent.run(empty)
         assert result.confidence == 0.0
         assert "no frames" in result.notes.lower()
+
+    def test_run_accepts_model_key(self, pose2d_agent):
+        sig = inspect.signature(pose2d_agent.run)
+        assert "model_key" in sig.parameters
+        assert "model_path" not in sig.parameters
+
+
+def _blank_ingest_3():
+    frames = [np.zeros((480, 640, 3), dtype=np.uint8) for _ in range(3)]
+    return IngestResult(frames=frames, fps=30.0, duration=0.1, n_people=1, width=640, height=480)
+
+
+class TestPose2DBackendsMocked:
+    """Backend dispatch tests — no real model downloads."""
+
+    def test_yolo_backend_dispatches(self):
+        from formscout.agents.pose2d import Pose2DAgent
+        fake_kps = [{0: {"x": 10.0, "y": 20.0, "conf": 0.9}} for _ in range(3)]
+        with mock.patch("formscout.agents.pose2d._run_yolo", return_value=fake_kps) as m:
+            result = Pose2DAgent().run(_blank_ingest_3(), model_key="YOLO26n — nano (0.7M, fastest)")
+        m.assert_called_once()
+        assert isinstance(result, Pose2DResult)
+        assert len(result.keypoints) == 3
+        assert result.confidence > 0.0
+
+    def test_mediapipe_backend_dispatches(self):
+        from formscout.agents.pose2d import Pose2DAgent
+        fake_kps = [{i: {"x": float(i), "y": float(i), "conf": 0.8} for i in range(17)} for _ in range(3)]
+        with mock.patch("formscout.agents.pose2d._run_mediapipe", return_value=fake_kps) as m:
+            result = Pose2DAgent().run(_blank_ingest_3(), model_key="MediaPipe-Pose — full (~9 MB, CPU-friendly)")
+        m.assert_called_once()
+        assert isinstance(result, Pose2DResult)
+        assert len(result.keypoints) == 3
+        assert all(len(f) == 17 for f in result.keypoints)
+
+    def test_sapiens2_backend_dispatches(self):
+        from formscout.agents.pose2d import Pose2DAgent
+        fake_kps = [{i: {"x": float(i), "y": float(i), "conf": 0.85} for i in range(17)} for _ in range(3)]
+        with mock.patch("formscout.agents.pose2d._run_sapiens2", return_value=fake_kps) as m:
+            result = Pose2DAgent().run(_blank_ingest_3(), model_key="Sapiens2-0.4B [Phase 3, ~1.6 GB]")
+        m.assert_called_once()
+        assert isinstance(result, Pose2DResult)
+        assert len(result.keypoints) == 3
+
+    def test_unknown_model_key_falls_back(self):
+        from formscout.agents.pose2d import Pose2DAgent
+        fake_kps = [{0: {"x": 1.0, "y": 2.0, "conf": 0.7}} for _ in range(3)]
+        with mock.patch("formscout.agents.pose2d._run_yolo", return_value=fake_kps):
+            result = Pose2DAgent().run(_blank_ingest_3(), model_key="nonexistent-model-xyz")
+        assert isinstance(result, Pose2DResult)
+
+    def test_confidence_zero_on_empty_keypoints(self):
+        from formscout.agents.pose2d import Pose2DAgent
+        with mock.patch("formscout.agents.pose2d._run_yolo", return_value=[{}, {}, {}]):
+            result = Pose2DAgent().run(_blank_ingest_3(), model_key="YOLO26n — nano (0.7M, fastest)")
+        assert result.confidence == 0.0
+        assert "no person" in result.notes.lower()

tests/test_visualizer.py

@@ -0,0 +1,176 @@
+"""Tests for PoseVisualizer — no GPU, no model downloads."""
+import numpy as np
+import pytest
+from formscout.types import IngestResult, Pose2DResult
+
+
+def _make_ingest(n=5, h=480, w=640, fps=30.0):
+    frames = [np.zeros((h, w, 3), dtype=np.uint8) for _ in range(n)]
+    return IngestResult(frames=frames, fps=fps, duration=n / fps, n_people=1, width=w, height=h)
+
+
+def _make_pose(n=5, w=640, h=480):
+    """Synthetic Pose2DResult: 17 joints at fixed pixel positions, conf=0.9."""
+    kps_per_frame = []
+    for i in range(n):
+        frame_kps = {}
+        for j in range(17):
+            frame_kps[j] = {
+                "x": float(50 + j * 30 + i * 2),
+                "y": float(100 + j * 20),
+                "conf": 0.9,
+            }
+        kps_per_frame.append(frame_kps)
+    return Pose2DResult(keypoints=kps_per_frame, fps=30.0, confidence=0.9, notes="")
+
+
+class TestComputeJointVelocity:
+    def test_returns_17_joints(self):
+        from formscout.agents.visualizer import compute_joint_velocity
+        pose = _make_pose(n=5)
+        result = compute_joint_velocity(pose.keypoints, fps=30.0)
+        assert len(result) == 17
+
+    def test_each_list_has_n_frames(self):
+        from formscout.agents.visualizer import compute_joint_velocity
+        pose = _make_pose(n=5)
+        result = compute_joint_velocity(pose.keypoints, fps=30.0)
+        for joint_idx, speeds in result.items():
+            assert len(speeds) == 5, f"joint {joint_idx} has {len(speeds)} speeds, expected 5"
+
+    def test_speeds_are_non_negative(self):
+        from formscout.agents.visualizer import compute_joint_velocity
+        pose = _make_pose(n=5)
+        result = compute_joint_velocity(pose.keypoints, fps=30.0)
+        for speeds in result.values():
+            assert all(s >= 0.0 for s in speeds)
+
+    def test_missing_keypoints_give_zero_speed(self):
+        from formscout.agents.visualizer import compute_joint_velocity
+        empty_kps = [{} for _ in range(5)]
+        result = compute_joint_velocity(empty_kps, fps=30.0)
+        for speeds in result.values():
+            assert all(s == 0.0 for s in speeds)
+
+
+class TestDrawSkeleton:
+    def test_skeleton_draws_without_error(self):
+        from formscout.agents.visualizer import PoseVisualizer
+        vis = PoseVisualizer()
+        frame = np.zeros((480, 640, 3), dtype=np.uint8)
+        kps = {j: {"x": float(50 + j * 30), "y": float(100 + j * 20), "conf": 0.9}
+               for j in range(17)}
+        result = vis._draw_skeleton(frame.copy(), kps)
+        assert result.shape == frame.shape
+        assert not np.array_equal(result, frame)
+
+    def test_low_confidence_keypoints_not_drawn(self):
+        from formscout.agents.visualizer import PoseVisualizer
+        vis = PoseVisualizer()
+        frame = np.zeros((480, 640, 3), dtype=np.uint8)
+        kps = {j: {"x": float(50 + j * 30), "y": 100.0, "conf": 0.1} for j in range(17)}
+        result = vis._draw_skeleton(frame.copy(), kps)
+        assert np.array_equal(result, frame)
+
+
+class TestDrawTrails:
+    def test_trails_draw_without_error(self):
+        from formscout.agents.visualizer import PoseVisualizer, TRAIL_LENGTH
+        from collections import deque
+        vis = PoseVisualizer()
+        frame = np.zeros((480, 640, 3), dtype=np.uint8)
+        trail_history = {
+            0: deque([(100 + i * 5, 200 + i * 3) for i in range(5)], maxlen=TRAIL_LENGTH)
+        }
+        result = vis._draw_trails(frame.copy(), trail_history)
+        assert result.shape == frame.shape
+        assert not np.array_equal(result, frame)
+
+    def test_short_trail_no_crash(self):
+        from formscout.agents.visualizer import PoseVisualizer, TRAIL_LENGTH
+        from collections import deque
+        vis = PoseVisualizer()
+        frame = np.zeros((480, 640, 3), dtype=np.uint8)
+        trail_history = {0: deque([(100, 200)], maxlen=TRAIL_LENGTH)}
+        result = vis._draw_trails(frame.copy(), trail_history)
+        assert np.array_equal(result, frame)
+
+
+class TestDrawVelocityArrows:
+    def test_arrows_draw_without_error(self):
+        from formscout.agents.visualizer import PoseVisualizer
+        vis = PoseVisualizer()
+        frame = np.zeros((480, 640, 3), dtype=np.uint8)
+        kps = {j: {"x": float(50 + j * 30), "y": float(100 + j * 20), "conf": 0.9}
+               for j in range(17)}
+        prev_kps = {j: {"x": float(48 + j * 30), "y": float(98 + j * 20), "conf": 0.9}
+                    for j in range(17)}
+        velocities = {j: [0.0] * 5 for j in range(17)}
+        velocities[5] = [0.0, 10.0, 50.0, 80.0, 120.0]
+        result = vis._draw_velocity_arrows(frame.copy(), kps, prev_kps, velocities, frame_idx=4)
+        assert result.shape == frame.shape
+
+    def test_no_prev_kps_no_crash(self):
+        from formscout.agents.visualizer import PoseVisualizer
+        vis = PoseVisualizer()
+        frame = np.zeros((480, 640, 3), dtype=np.uint8)
+        kps = {j: {"x": float(50 + j * 30), "y": 100.0, "conf": 0.9} for j in range(17)}
+        velocities = {j: [50.0] * 5 for j in range(17)}
+        result = vis._draw_velocity_arrows(frame.copy(), kps, None, velocities, frame_idx=0)
+        assert result.shape == frame.shape
+
+
+class TestRenderVideo:
+    def test_creates_mp4_file(self, tmp_path):
+        from formscout.agents.visualizer import PoseVisualizer
+        vis = PoseVisualizer()
+        ingest = _make_ingest(n=5)
+        pose = _make_pose(n=5)
+        out = str(tmp_path / "out.mp4")
+        result = vis.render_video(ingest, pose, {"skeleton"}, out)
+        assert result is not None
+        import os
+        assert os.path.exists(result)
+        assert os.path.getsize(result) > 0
+
+    def test_empty_layers_returns_none(self, tmp_path):
+        from formscout.agents.visualizer import PoseVisualizer
+        vis = PoseVisualizer()
+        out = str(tmp_path / "out.mp4")
+        result = vis.render_video(_make_ingest(), _make_pose(), set(), out)
+        assert result is None
+
+    def test_no_detections_returns_none(self, tmp_path):
+        from formscout.agents.visualizer import PoseVisualizer
+        vis = PoseVisualizer()
+        ingest = _make_ingest(n=5)
+        empty_pose = Pose2DResult(
+            keypoints=[{} for _ in range(5)], fps=30.0, confidence=0.0, notes=""
+        )
+        out = str(tmp_path / "out.mp4")
+        result = vis.render_video(ingest, empty_pose, {"skeleton"}, out)
+        assert result is None
+
+    def test_last_velocities_set_after_render(self, tmp_path):
+        from formscout.agents.visualizer import PoseVisualizer
+        vis = PoseVisualizer()
+        out = str(tmp_path / "out.mp4")
+        vis.render_video(_make_ingest(n=5), _make_pose(n=5), {"skeleton"}, out)
+        assert len(vis.last_velocities) == 17
+
+
+class TestBuildVelocitySummary:
+    def test_returns_markdown_table(self):
+        from formscout.agents.visualizer import build_velocity_summary, compute_joint_velocity
+        pose = _make_pose(n=10)
+        vels = compute_joint_velocity(pose.keypoints, fps=30.0)
+        result = build_velocity_summary(pose.keypoints, vels)
+        assert "|" in result
+        assert any(name in result for name in ["knee", "shoulder", "hip", "ankle"])
+
+    def test_empty_keypoints_returns_empty_string(self):
+        from formscout.agents.visualizer import build_velocity_summary
+        empty_kps = [{} for _ in range(5)]
+        vels = {j: [0.0] * 5 for j in range(17)}
+        result = build_velocity_summary(empty_kps, vels)
+        assert result == ""