feat: recognise 238 LSE signs with a trained model

Author: Endika

.gitignore

@@ -22,3 +22,4 @@ __pycache__
 
 # Staged from node_modules by scripts/copy-wasm.mjs, never committed.
 public/wasm
+tools/train/artifacts

README.md

@@ -15,7 +15,7 @@ Three engines answer through one port, so the app does not care which one produc
 | Engine | What it reads | Where it comes from |
 | --- | --- | --- |
 | **Alphabet** | Fingerspelled letters (dactilológico). Spell anything, letter by letter. | Geometric handshape rules — no training data needed. |
-| **Vocabulary** | Whole LSE signs, one word each. | ONNX model trained on [SWL-LSE](https://zenodo.org/records/13691887): 300 classes, ~180 concepts after merging variants. Health domain. **Not built yet.** |
+| **Vocabulary** | Whole LSE signs, one word each. | GRU trained on [SWL-LSE](https://zenodo.org/records/13691887): 238 health-domain concepts. **63% top-1, 83% top-3** on the dataset's own held-out test split. |
 | **Taught** | Any sign you record yourself, in any sign language. | Nearest-prototype match over 3+ recordings, stored in IndexedDB on your device. Working now. |
 
 ### What it does not do
@@ -27,6 +27,23 @@ Sign `[YO] [CABEZA] [DOLOR]` and you get "yo cabeza dolor", not "me duele la cab
 Continuous sentence-level sign language translation is an open research problem. Treating
 word-level output honestly is a design decision, not a missing feature.
 
+### How good is the vocabulary model, really
+
+63% top-1 and 83% top-3 on 598 held-out samples across 238 classes — against a 0.4% random
+baseline. Useful, not authoritative. The UI says so, and the transcript is editable.
+
+Those numbers come from SWL-LSE's own train/val/test split, never from data the model saw.
+`tools/train/train.py` prints them on every run and writes them into the shipped manifest, so
+the figure in this README cannot drift from the model that is actually deployed.
+
+**There is no inference runtime.** onnxruntime-web needs 13 MB of WASM to run a 2.4 MB model,
+and on GitHub Pages it cannot even use threads — Pages sends no COOP/COEP headers. The
+network is a fixed stack (LayerNorm → 2-layer bidirectional GRU → mean-pool → 2 linear
+layers), so `src/infrastructure/recognition/gru.ts` computes it directly and the weights ship
+as one flat float32 blob. `VocabularySignClassifier.test.ts` checks the whole stack against
+logits PyTorch produced for a fixed input, because a hand-written GRU that is subtly wrong
+still runs and still returns plausible numbers.
+
 ## Architecture
 
 Hexagonal, with constructor injection and no DI framework — a plain `Container` wires
@@ -56,10 +73,17 @@ index point against a Y at 0.962 — no threshold separates those. Distance over
 normalised coordinates gives 0.10 and 0.25 for the same pairs. If taught-sign recognition
 ever starts matching everything, check that this has not been "simplified" back to cosine.
 
-**Normalisation must match training.** `normalizeHand` mirrors what `tools/train` applies to
-the dataset. A model trained on normalised coordinates and fed raw ones predicts noise
-silently rather than failing — if recognition degrades for no visible reason, check this
-first.
+**Normalisation must match training.** `windowSignature` and `tools/train/features.py` must
+produce byte-identical layouts. A model trained on one and fed the other predicts noise
+silently rather than failing — the loader throws on a length mismatch, but a same-length
+reordering would slip through. If recognition degrades for no visible reason, diff those two
+files first.
+
+**Known limitation in taught signs.** The signature carries the wrist position because LSE
+gives location meaning, but it is 3 floats out of 66 per hand, so plain distance matching
+barely weights it. The trained model learns its own weighting and copes; taught-sign matching
+does not, so two taught signs differing only in height will be confused. Covered by a test
+that asserts the real figure rather than a hoped-for one.
 
 ## Development