Publish v2.1 GGUF decision heads for little-gemma v1.0

.gitattributes

@@ -33,3 +33,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+gemma4-12B-decision-head.gguf filter=lfs diff=lfs merge=lfs -text
+gemma4-E4B-decision-head.gguf filter=lfs diff=lfs merge=lfs -text

12b/contract.json

@@ -0,0 +1,16 @@
+{
+  "answer_channel_seed": false,
+  "calibration_scope": "authored calibration families only",
+  "capture_boundary": "post-output-norm final prompt token; before generated-token forward",
+  "dataset_manifest_sha256": "7840167f3a5dd4ea55c52163953b829232f8525a8a9ef42b2a9d7ce3ec0f0483",
+  "deployment_status": "offline_candidate_not_deployed",
+  "engine_revision": "c304f086a40c46ae4b67d5402738769dc12132a6",
+  "feature_kind": "hidden",
+  "head_sha256": "557d538a1043b7ae3563f217d9b0bee0217672ec48216d9a7f71cef4e9475b22",
+  "hidden_dim": 3840,
+  "input_format": "trio_sound_event_v2_staged_history",
+  "layer": 48,
+  "model": "12b",
+  "model_sha256": "90fd44e29e0d7cffeb0fd00dc73cfdab9ed0b0e95306ecf7821ea634c940c370",
+  "task": "final_prompt-action"
+}

12b/head.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:557d538a1043b7ae3563f217d9b0bee0217672ec48216d9a7f71cef4e9475b22
+size 2768441

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cortexist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,122 @@
+---
+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.

SHA256SUMS

@@ -0,0 +1,8 @@
+fef48fff1263f86e5b85d289c397da47ef6879eb712e70f8197e27a7b0e912e3  12b/contract.json
+557d538a1043b7ae3563f217d9b0bee0217672ec48216d9a7f71cef4e9475b22  12b/head.npz
+6f5ba07f52656a2540b54cb8e93e277e9541601c5d375f585d8945dac5757982  LICENSE
+ea098ae1d0f60b86fa73b31cfe4bbde92b56e2b884afa065548a37eaabf8edba  README.md
+61a92e01a1ffdd096fd7b070cef8a0ed14ac3602428e06b253c500589e79bebc  e4b/contract.json
+5d988f9045047c66621843cd4c24dba18a129346cd33c103a5bc72c504752a48  e4b/head.npz
+b242323de6647b8dabd16f4d92995282174ef12e2dd6abc231595d22dc70b18a  gemma4-12B-decision-head.gguf
+64c71b7e9a5ac99a42890f358e757d64c47c81693d7b975c8c24077ec82626f5  gemma4-E4B-decision-head.gguf

e4b/contract.json

@@ -0,0 +1,16 @@
+{
+  "answer_channel_seed": false,
+  "calibration_scope": "authored calibration families only",
+  "capture_boundary": "post-output-norm final prompt token; before generated-token forward",
+  "dataset_manifest_sha256": "7840167f3a5dd4ea55c52163953b829232f8525a8a9ef42b2a9d7ce3ec0f0483",
+  "deployment_status": "offline_candidate_not_deployed",
+  "engine_revision": "c304f086a40c46ae4b67d5402738769dc12132a6",
+  "feature_kind": "hidden",
+  "head_sha256": "5d988f9045047c66621843cd4c24dba18a129346cd33c103a5bc72c504752a48",
+  "hidden_dim": 2560,
+  "input_format": "trio_sound_event_v2_staged_history",
+  "layer": 42,
+  "model": "e4b",
+  "model_sha256": "df0fd4ee07072c607c29a0a1cb4f98918426cca12f45a2776bdd6ee6d09a4de3",
+  "task": "final_prompt-action"
+}

e4b/head.npz

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5d988f9045047c66621843cd4c24dba18a129346cd33c103a5bc72c504752a48
+size 1850215

gemma4-12B-decision-head.gguf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b242323de6647b8dabd16f4d92995282174ef12e2dd6abc231595d22dc70b18a
+size 2985792

gemma4-E4B-decision-head.gguf

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:64c71b7e9a5ac99a42890f358e757d64c47c81693d7b975c8c24077ec82626f5
+size 1992512