silas-therapy/small-functional-movement-screening

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.

Running locally

1. Clone and install

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.

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

FORMSCOUT_JUDGE_GGUF=/path/to/finetuned.gguf ./scripts/serve_judge.sh

3. Launch the Gradio app

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)

python3 -m formscout.run sample.mp4

5. Tests

pytest tests/ -v

6. Upload to Hugging Face

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

License

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