Update model card for v3

README.md

@@ -1,62 +1,57 @@
 ---
-license: apache-2.0
-base_model: google/gemma-3-4b-it
 tags:
-  - coaching
   - gymnastics
-  - movement-analysis
+  - coaching
+  - motion-analysis
+  - gemma3
   - lora
-  - unsloth
-  - gemma
-datasets:
-  - custom
-language:
-  - en
-pipeline_tag: text-generation
+  - kim
+license: apache-2.0
+base_model: google/gemma-3-4b-it
 ---
 
-# KIM-coach: Gymnastics Coaching Language Model
+# KIM-Coach v3 — Gymnastics Coaching LLM
 
-Fine-tuned **Gemma 3 4B** for generating coaching cues from movement divergence data.
+Fine-tuned Gemma 3 4B for generating motor-instruction coaching cues from motion analysis data.
 
-## Model Details
+## What Changed in v3
 
-- **Base model**: google/gemma-3-4b-it (4-bit quantized via Unsloth)
-- **Fine-tuning**: LoRA (r=16), merged into base weights
-- **Training data**: 1,538 synthetic coaching pairs across 20 FineGym gymnastics classes
-- **Training**: 3 epochs, 525 steps, ~2h43m on A100
-- **Best val loss**: 0.140 (step 200)
-
-## Part of the KIM Pipeline
+| Version | Training Pairs | Key Improvement | Val Loss |
+|---------|---------------|-----------------|----------|
+| v1 | 1,538 | First fine-tune, assessment-style templates | 0.140 → 0.070 |
+| v2 | 1,538 | Motor instruction templates (action verbs, feel cues) | 0.110 → 0.070 |
+| **v3** | **3,798** | **Directional error taxonomy + output diversity** | **0.110 → 0.067** |
 
-This model is the coaching language component of the **Kinematic Instruction Model (KIM)** pipeline:
+### v3 Improvements
+- **Directional error taxonomy**: 10 categories (insufficient_extension, over_flexion, timing_early/late, balance_loss, etc.) grounded in LucidAction penalties, USAG deductions, and real Habitude app data
+- **2-3 output variations per input**: same divergence pattern gets different coaching language, breaking template memorization
+- **50 gold-standard cues** as style anchors (hand-written by coaching framework)
+- **Novel cue generation**: model composes cues it was never explicitly trained on
 
-1. **Tokenize** — VQ-VAE encodes skeletal motion into discrete tokens ([antking1/KIM](https://huggingface.co/antking1/KIM))
-2. **Compare** — Token sequences are aligned and divergence is computed per body part
-3. **Coach** — This model translates divergence data into natural language coaching cues
+### Evidence of Generalization (v3)
+v1/v2 produced verbatim copies of training data. v3 generates **novel coaching cues**:
+- Input: torso divergence during takeoff
+- Expected: "hips level, midline braced"
+- Predicted: "hips over hands, arched bridge during the takeoff — you should feel hips pushing forward"
+- Both are valid motor instructions — the model learned the *pattern*, not the template
 
-## Input Format
+## Pipeline
 
-```
-### Instruction:
-You are a gymnastics coach. Analyze the movement comparison data and provide specific coaching feedback.
 
-### Input:
-Element: vault_handspring
-Overall divergence: 0.176
-Per-part divergence: torso=0.223, arms=0.195, head=0.149, legs=0.140
-Worst segments: legs frames 11-12 (0.905), head frames 3-4 (0.846)
 
-### Response:
-```
+## Input Format
 
-## Limitations
 
-- Coaching cues are currently **assessments** ("your arms need correction") rather than **motor instructions** ("squeeze your elbows to your ribs")
-- Element IDs may be hallucinated
-- Trained on synthetic data generated by the same pipeline — circular validation risk
-- V1 proof-of-concept; not yet validated by qualified coaches
+## Output Format
 
-## Citation
 
-Part of the Motis Research project — [motis.pro](https://motis.pro)
+## Training Details
+- **Base model**: google/gemma-3-4b-it (4-bit quantized via Unsloth)
+- **Method**: LoRA (r=16, alpha=16, dropout=0)
+- **Data**: 3,427 train / 371 val pairs from KIM VQ-VAE codec + directional error taxonomy
+- **Training**: 3 epochs, batch size 8, lr 2e-4, A100 GPU, ~77 minutes
+- **Best val loss**: 0.067 at step 1200
+
+## Part of KIM (Kinematic Instruction Model)
+- Codec: [antking1/KIM](https://huggingface.co/antking1/KIM)
+- Coach: [antking1/KIM-coach](https://huggingface.co/antking1/KIM-coach) (this model)