| --- |
| language: |
| - en |
| license: mit |
| library_name: little-gemma |
| tags: |
| - gemma4 |
| - decision-head |
| - gguf |
| - voice-classroom |
| - turn-taking |
| --- |
| # Gemma 4 classroom decision heads |
|
|
| Small CPU classifiers that map a Gemma 4 **final-prompt hidden vector** to |
| `speak`, `defer` or `wait`. These are auxiliary heads, not language models or |
| voice weights. They accompany the GGUF-based |
| [little-gemma v1.0 engine](https://github.com/cortexist/little-gemma/tree/v1.0) |
| and [little-gemma-tools v1.0 classroom](https://github.com/cortexist/little-gemma-tools/tree/v1.0). |
| The classifier training revision is **v2.1 (2026-10-05)**; it is independent of |
| the software's v1.0 version. This package replaces `gemma4-decision-head_v0.9`. |
|
|
| ## Files |
|
|
| | File | Use | |
| | --- | --- | |
| | `gemma4-E4B-decision-head.gguf` | E4B native C runtime head | |
| | `gemma4-12B-decision-head.gguf` | 12B native C runtime head | |
| | `e4b/head.npz`, `e4b/contract.json` | E4B NumPy reference and feature contract | |
| | `12b/head.npz`, `12b/contract.json` | 12B NumPy reference and feature contract | |
| | `SHA256SUMS` | Checksums of release files | |
|
|
| The GGUFs are byte-identical to the validated v2.1 exports, with plain public |
| filenames. Their embedded contracts retain original training provenance. |
| In particular, `deployment_status` records export-time status, not current |
| runtime permission. E4B subsequently ran in the GGUF classroom; the supplied |
| 12B revision is the latest offline-validated candidate, not a claim that every |
| live 12B deployment used it. |
|
|
| ## Feature compatibility |
|
|
| | Head | Hidden width | Layer | Required backbone GGUF SHA-256 | |
| | --- | ---: | ---: | --- | |
| | E4B | 2560 | 42 | `df0fd4ee07072c607c29a0a1cb4f98918426cca12f45a2776bdd6ee6d09a4de3` | |
| | 12B | 3840 | 48 | `90fd44e29e0d7cffeb0fd00dc73cfdab9ed0b0e95306ecf7821ea634c940c370` | |
|
|
| Capture **after output normalization at the final prompt token, before any |
| generated-token forward**, without answer-channel seeding. The input contract |
| is `trio_sound_event_v2_staged_history` and task is `final_prompt-action`. |
| Extraction used little-gemma revision `c304f086a40c46ae4b67d5402738769dc12132a6`; |
| its serving support is included in v1.0. Matching dimensions alone is not enough: |
| check backbone hash, layer, normalization, prompt format, and capture boundary. |
| Other quantizations/backends, including EXL3, require separate validation or |
| refitting. Do not bypass feature-contract checks to force an incompatible model. |
|
|
| Each head is a three-seed ensemble of 64-unit tanh MLPs with standardized, |
| clipped inputs, mean logits and temperature softmax. Labels and numerical |
| parameters are stored in the package; use them rather than hardcoding order. |
| Training/dev/calibration support contains 5,751 authored examples, including |
| 3,943 training rows across 37 training families. Probabilities are calibrated |
| only on authored calibration families, not on unconstrained live conversations. |
|
|
| ## Use |
|
|
| ```sh |
| hf download cortexist/gemma4-decision-head --local-dir decision-heads |
| cd decision-heads |
| sha256sum -c SHA256SUMS |
| ``` |
|
|
| Build the engine's `decision_head` shared library and `decision-head` CLI: |
|
|
| ```sh |
| cmake -S little-gemma -B little-gemma/build -DCMAKE_BUILD_TYPE=Release |
| cmake --build little-gemma/build --target decision_head decision-head |
| little-gemma/build/decision-head inspect decision-heads/gemma4-E4B-decision-head.gguf |
| ``` |
|
|
| Configure the classroom's `turn_head.backend` as `c`, `library` as the absolute |
| shared-library path, and each `models` entry as a head `path` plus its SHA-256. |
| Use `mode: control`, `text_decision_tags: true` and `prompt_lane: v2_sound_event` |
| with the compatible `whisper_at_v2` acoustic adapter. The engine snapshots the |
| prompt feature, runs the CPU head, then applies the decision to the **same** turn. |
| The head itself does not synthesize audio, schedule speakers or detect overlap. |
| See [runtime configuration](https://github.com/cortexist/little-gemma-tools/blob/v1.0/script/deviceui/TURN_HEAD.md) |
| and [classroom setup](https://github.com/cortexist/little-gemma-tools/blob/v1.0/docs/trio-setup.md). |
|
|
| ## Evaluation and limitations |
|
|
| | Authored panel | E4B | 12B | |
| | --- | ---: | ---: | |
| | Reserved invitation cases, three views | 360 / 360 | 360 / 360 | |
| | Previously exposed retention cases | 1,212 / 1,212 | 1,211 / 1,212 | |
| | Required-wait compact cases | 40 / 40 | 40 / 40 | |
| | Follow-up compact cases | 30 / 30 | 30 / 30 | |
|
|
| Views are correlated renderings, not independent real-world trials. The 360-row |
| panel contains 120 compact cases. The older retention set was exposed during |
| development and is not a fresh holdout. The 12B retention error is a teacher-role |
| case without sound metadata: a guest's own-name correction predicts **Speak** |
| instead of **Defer**. Guest-role retention views passed. A previously exposed |
| live E4B case was included in training and is not held-out evidence. |
|
|
| The original export check found identical C/NumPy choices on 6,111 vectors per |
| model. These results establish narrow authored classroom behavior and export |
| parity, not general conversational accuracy, interruption detection, live audio |
| robustness or end-to-end latency. Sound metadata in the authored evaluation is |
| synthetic; live ASR, identity, acoustics and prompt shifts can change outcomes. |
| No private hidden vectors, transcripts, voice recordings or raw training corpus |
| are distributed here. |
|
|
| ## Voices and licenses |
|
|
| [Agent Voice](https://huggingface.co/cortexist/agent-voice) provides the public |
| guest voice separately. Users must choose **two additional voices** for teacher |
| and student, prepare phoneme timing and split `.enc.onnx`/`.dec.onnx` graphs, |
| and generate matching identity references. **Chey's voice is private and |
| closed-weight; it is not included or available for download.** |
|
|
| The decision-head package is MIT licensed. Gemma backbones, voice models and |
| external ASR/identity components retain their own terms; this license does not |
| relicense those artifacts. |
|
|
