refactor: extract closed vocabulary into signbridge.vocab module

Single source of truth eliminates the drift risk between the VLM
recognizer (string-prompt vocab) and the trained-classifier head (list
order maps to logit indices). Also exports VOCAB_PROMPT_LITERAL for
prompt embedding and VOCAB_SET for membership checks.

Addresses deep-check finding A.F10 / D.F10 (vocab drift across modules).

signbridge/recognizer/classifier.py

@@ -14,23 +14,13 @@ from pathlib import Path
 
 import numpy as np
 
+# Vocabulary imported from the shared module — must match the order the
+# trained classifier head was trained against.
+from signbridge.vocab import VOCAB
+
 logger = logging.getLogger(__name__)
 
-# WLASL Top-50 + ASL fingerspelling alphabet + digits 0-9.
-# Exact list will be finalised when we lock training data on Day 2.
-VOCABULARY: list[str] = [
-    # ASL fingerspelling
-    *list("ABCDEFGHIJKLMNOPQRSTUVWXYZ"),
-    *list("0123456789"),
-    # WLASL Top-50 (approximate; exact set fixed by the dataset slice)
-    "hello", "thank_you", "name", "please", "sorry", "yes", "no", "good",
-    "bad", "help", "want", "like", "love", "family", "friend", "mother",
-    "father", "sister", "brother", "child", "home", "school", "work",
-    "eat", "drink", "water", "food", "more", "finish", "today", "tomorrow",
-    "yesterday", "where", "what", "who", "why", "when", "how", "go", "come",
-    "see", "know", "understand", "think", "feel", "happy", "sad", "tired",
-    "hungry", "wait",
-]
+VOCABULARY = list(VOCAB)
 VOCAB_SIZE = len(VOCABULARY)
 
 

signbridge/recognizer/vlm.py

@@ -25,28 +25,16 @@ import re
 
 import numpy as np
 
+# Closed vocabulary the VLM is asked to choose from. Imported from the
+# shared `signbridge.vocab` module so the recognizer and the trained
+# classifier (`signbridge.recognizer.classifier`) can never drift.
+from signbridge.vocab import VOCAB_PROMPT_LITERAL as _VLM_VOCAB
+from signbridge.vocab import VOCAB_SET as _VLM_VOCAB_SET
+
 logger = logging.getLogger(__name__)
 
 DEFAULT_VLM_MODEL = os.getenv("SIGNBRIDGE_VLM_MODEL", "Qwen/Qwen2-VL-7B-Instruct")
 
-# Closed vocabulary the VLM is asked to choose from. Same shape as
-# `classifier.VOCABULARY` but expressed as a prompt, not a softmax.
-_VLM_VOCAB = (
-    "A B C D E F G H I J K L M N O P Q R S T U V W X Y Z "
-    "0 1 2 3 4 5 6 7 8 9 "
-    "hello thank_you name please sorry yes no good bad help "
-    "want like love family friend mother father sister brother child "
-    "home school work eat drink water food more finish today tomorrow "
-    "yesterday where what who why when how go come "
-    "see know understand think feel happy sad tired hungry wait "
-    "unknown"
-)
-# Pre-built set for membership tests at recognition time. Tokens not in this
-# set get suppressed (confidence 0.0) — VLMs hallucinate strings like
-# "letter", "no_sign", "n/a" that would otherwise leak into the demo with a
-# fake 0.85 confidence.
-_VLM_VOCAB_SET = frozenset(_VLM_VOCAB.split())
-
 _PROMPT = (
     "You are an expert in American Sign Language (ASL). Look at this image of a "
     "single signed gesture. Identify which ASL sign or fingerspelled letter is "

signbridge/vocab.py

@@ -0,0 +1,30 @@
+"""Shared closed-vocabulary constants for SignBridge.
+
+Single source of truth so the VLM recognizer (`signbridge.recognizer.vlm`)
+and the trained-classifier path (`signbridge.recognizer.classifier`) can
+never drift. The classifier head must produce logits in this exact order;
+the VLM prompt forces the model to choose only from this set.
+"""
+
+from __future__ import annotations
+
+ALPHABET: tuple[str, ...] = tuple("ABCDEFGHIJKLMNOPQRSTUVWXYZ")
+DIGITS: tuple[str, ...] = tuple("0123456789")
+WLASL_TOP50: tuple[str, ...] = (
+    "hello", "thank_you", "name", "please", "sorry", "yes", "no", "good",
+    "bad", "help", "want", "like", "love", "family", "friend", "mother",
+    "father", "sister", "brother", "child", "home", "school", "work",
+    "eat", "drink", "water", "food", "more", "finish", "today", "tomorrow",
+    "yesterday", "where", "what", "who", "why", "when", "how", "go", "come",
+    "see", "know", "understand", "think", "feel", "happy", "sad", "tired",
+    "hungry", "wait",
+)
+
+# Sentinel returned by the VLM when no recognized sign is present.
+UNKNOWN: str = "unknown"
+
+VOCAB: tuple[str, ...] = ALPHABET + DIGITS + WLASL_TOP50 + (UNKNOWN,)
+VOCAB_SET: frozenset[str] = frozenset(VOCAB)
+
+# Pre-rendered space-separated string for prompt embedding.
+VOCAB_PROMPT_LITERAL: str = " ".join(VOCAB)

tests/test_vocab.py

@@ -0,0 +1,42 @@
+"""Tests for the shared vocabulary module."""
+
+from signbridge.vocab import VOCAB, VOCAB_SET, ALPHABET, DIGITS, WLASL_TOP50
+
+
+def test_vocab_is_tuple_of_strings():
+    assert isinstance(VOCAB, tuple)
+    assert all(isinstance(t, str) for t in VOCAB)
+    assert len(VOCAB) == len(set(VOCAB))  # no duplicates
+
+
+def test_vocab_set_matches_tuple():
+    assert VOCAB_SET == frozenset(VOCAB)
+
+
+def test_alphabet_subset():
+    assert all(letter in VOCAB_SET for letter in ALPHABET)
+    assert len(ALPHABET) == 26
+
+
+def test_digits_subset():
+    assert all(d in VOCAB_SET for d in DIGITS)
+    assert len(DIGITS) == 10
+
+
+def test_wlasl_top50_subset():
+    assert all(sign in VOCAB_SET for sign in WLASL_TOP50)
+    assert len(WLASL_TOP50) >= 49
+
+
+def test_unknown_sentinel_present():
+    assert "unknown" in VOCAB_SET
+
+
+def test_recognizer_uses_shared_vocab():
+    from signbridge.recognizer.vlm import _VLM_VOCAB_SET
+    assert _VLM_VOCAB_SET is VOCAB_SET
+
+
+def test_classifier_uses_shared_vocab():
+    from signbridge.recognizer.classifier import VOCABULARY
+    assert tuple(VOCABULARY) == VOCAB