README.md

---
title: FormScout
emoji: 📈
colorFrom: green
colorTo: yellow
sdk: gradio
app_file: app.py
pinned: true
license: apache-2.0
short_description: FMS video scoring — movement screen aid
thumbnail: >-
  https://cdn-uploads.huggingface.co/production/uploads/6632220a9163a52438fbd1b2/1PbdV1pyKOpyY58LIh9_N.png
sdk_version: 6.18.0
models:
  - Qwen/Qwen3-VL-8B-Instruct-GGUF
  - YOLO26
tags:
  - backyard-ai
  - off-the-grid
  - llama-champion
  - track:backyard
  - achievement:offgrid
  - achievement:llama
---

# 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.

**⚠️ Screening aid — not a diagnosis. Pain or clearing tests require a clinician.**

# Submission details

## Demo
- [YouTube](https://youtu.be/MvuOyj6mMCA)

## Social media posts
- [Instagram](https://www.instagram.com/p/DZkwSenDcvv/?utm_source=ig_web_copy_link)
- [LinkedIn](https://www.linkedin.com/posts/csaba-boly%C3%B3s-00a11767_hackathon-movement-screening-activity-7472141949278543872-Q_DI?utm_source=share&utm_medium=member_desktop&rcm=ACoAAA4TvEoBG6xaPCej-4MULwosVpspO1XW__c)

## Teammembers
 - [ajakab](https://huggingface.co/ajakab)
 - [BladeSzaSza](https://huggingface.co/BladeSzaSza)




## Running locally

### 1. Clone and install

```bash
git clone https://huggingface.co/silas-therapy/small-functional-movement-screening
cd small-functional-movement-screening
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
```

### 2. Start the VLM judge (optional but recommended)

The judge uses Qwen3-VL-8B-Instruct via llama.cpp. Without it the app falls back to the deterministic rubric score — fully functional, no GPU needed.

```bash
# Install llama.cpp once
brew install llama.cpp

# Download the model (one-time, ~6 GB)
python3 -c "
from huggingface_hub import hf_hub_download
for f in ['Qwen3VL-8B-Instruct-Q4_K_M.gguf', 'mmproj-Qwen3VL-8B-Instruct-F16.gguf']:
    hf_hub_download('Qwen/Qwen3-VL-8B-Instruct-GGUF', f, local_dir='checkpoints/qwen3-vl')
"

# Start the server (keep this terminal open)
./scripts/serve_judge.sh
```

To use a fine-tuned GGUF instead of the default:
```bash
FORMSCOUT_JUDGE_GGUF=/path/to/finetuned.gguf ./scripts/serve_judge.sh
```

### 3. Launch the Gradio app

```bash
python3 app.py
# → http://127.0.0.1:7860
```

Upload a video, select the FMS test from the dropdown, and click **Analyze**.

### 4. Headless pipeline (no Gradio)

```bash
python3 -m formscout.run sample.mp4
```

### 5. Tests

```bash
pytest tests/ -v
```

### 6. Upload to Hugging Face

```bash
# Pushes source to both model repo and Space, opens a PR on each
./scripts/hf_upload.sh

# Or with a custom commit message
./scripts/hf_upload.sh "feat: my change"
```

## Architecture

Typed specialist agents orchestrated by a deterministic Director:

```
Ingest → Pose2D → [Body3D optional] → Biomechanics → Rubric Score → [Judge] → Report
```

| Agent | Model | Status |
|---|---|---|
| Pose2D | YOLO26l-Pose (0.026B) + MediaPipe fallback | ✅ |
| Body3D | SAM 3D Body DINOv3 (0.84B) | gated, off by default |
| Judge + Classifier | Qwen3-VL-8B-Instruct via llama.cpp (8B) | ✅ |
| Scoring Head | ST-GCN (0.03B) | Phase 3 |
| Retrieval | Qwen3-VL-Embedding-8B (8B) | Phase 3 |

See [CLAUDE.md](CLAUDE.md) for full architecture and invariants.

## Feature flags (`formscout/config.py`)

| Flag | Default | Meaning |
|---|---|---|
| `ENABLE_JUDGE` | `True` | VLM judge via llama-server; rubric fallback when server is down |
| `ENABLE_3D` | `False` | SAM 3D Body — off until integrated |
| `ENABLE_STGCN` | `False` | Phase 3 |
| `ENABLE_RAG` | `False` | Phase 3 |

## Model budget

~18B params total (under 32B cap). See [MODEL_BUDGET.md](MODEL_BUDGET.md).

## License

Apache-2.0. Built for the Build Small Hackathon (Backyard AI track).