Skip to main content

qualia_audio/models/speech_p64/
head.rs

1//! Speech CTC encoder head (P64, fail-closed) — AU-LEARNED.
2//!
3//! `SpeechHead` performs **greedy CTC decoding** over learned weights loaded through the common
4//! fail-closed loader. It abstains (`BackendUnavailable`) when (a) no weights are present, or
5//! (b) the loaded model declares an **unknown language** (`language_slot == 0`). There is **no
6//! silent fallback map**: without a real model the head produces no tokens rather than inventing a
7//! transcription.
8//!
9//! Blob convention: `dims = [vocab, feat_dim, language_slot]`. Token index `0` is the CTC blank.
10//! `data` is a row-major projection of `vocab * feat_dim` weights followed by `vocab` biases. Per
11//! log-mel frame the head computes `logit_v = bias_v + Σ_f proj[v,f] * logmel[f]`, takes the argmax
12//! token, then applies the standard CTC collapse (drop repeats, then drop blanks). Decoding is the
13//! hot path and allocates nothing — collapse state is a single previous-index register, and tokens
14//! are written straight into the caller's buffer.
15
16use crate::models::loader::{parse_weight_blob, require_weights, WeightBlob, WeightState};
17use crate::types::{AudioError, TranscriptToken};
18
19/// Base for synthesized token-form hashes (low-assurance proposal, not a curated lexicon URI).
20const SPEECH_FORM_BASE: u64 = 0xC2B2_AE3D_27D4_EB4F;
21/// CTC blank token index.
22const BLANK: usize = 0;
23/// `language_slot` value meaning "unknown language" — forces abstention.
24const LANG_UNKNOWN: u32 = 0;
25
26/// Learned speech CTC head. Fail-closed: `Absent` state or unknown language ⇒ abstain.
27#[derive(Debug, Default)]
28pub struct SpeechHead {
29    pub state: WeightState,
30}
31
32impl SpeechHead {
33    /// Construct with no weights — fails closed until [`SpeechHead::load`] succeeds.
34    pub fn new() -> Self {
35        Self {
36            state: WeightState::Absent,
37        }
38    }
39
40    /// Load weights from a P64 blob (cold path).
41    pub fn load(&mut self, bytes: &[u8]) -> Result<(), AudioError> {
42        let blob = parse_weight_blob(bytes)?;
43        validate_shape(&blob)?;
44        self.state = WeightState::Loaded(blob);
45        Ok(())
46    }
47
48    /// Whether a real forward pass is available (weights present *and* a known language).
49    pub fn is_ready(&self) -> bool {
50        match &self.state {
51            WeightState::Loaded(blob) => language_slot(blob) != LANG_UNKNOWN,
52            WeightState::Absent => false,
53        }
54    }
55
56    /// Greedy-CTC decode `logmel` (row-major `frames × feat_dim`) into `out_tokens`.
57    ///
58    /// - No weights ⇒ `Err(BackendUnavailable)` (abstain).
59    /// - Unknown language (`language_slot == 0`) ⇒ `Err(BackendUnavailable)` (no silent map).
60    /// - `logmel.len()` must be a whole multiple of `feat_dim`, else `InvalidParameter`.
61    /// - If more tokens survive collapse than `out_tokens` can hold ⇒ `OutputBufferTooSmall`.
62    ///
63    /// Returns the number of tokens written. Hot path: no allocation.
64    pub fn infer_ctc(
65        &self,
66        logmel: &[f32],
67        out_tokens: &mut [TranscriptToken],
68    ) -> Result<usize, AudioError> {
69        let blob = require_weights(&self.state)?;
70        let (vocab, feat_dim, lang) = shape(blob)?;
71        if lang == LANG_UNKNOWN {
72            // Weights present but no language mapping — abstain, do not guess.
73            return Err(AudioError::BackendUnavailable);
74        }
75        if feat_dim == 0 || !logmel.len().is_multiple_of(feat_dim) {
76            return Err(AudioError::InvalidParameter);
77        }
78        let frames = logmel.len() / feat_dim;
79        let bias_off = vocab * feat_dim;
80
81        let mut written = 0usize;
82        let mut prev_arg = usize::MAX; // sentinel: no previous emission
83        for frame in 0..frames {
84            let base = frame * feat_dim;
85            let logmel_frame = &logmel[base..base + feat_dim];
86
87            // Streaming argmax over vocab logits (zero-heap).
88            let mut best_tok = 0usize;
89            let mut best_logit = f32::NEG_INFINITY;
90            for v in 0..vocab {
91                let logit = token_logit(blob, v, feat_dim, bias_off, logmel_frame);
92                if logit > best_logit {
93                    best_logit = logit;
94                    best_tok = v;
95                }
96            }
97
98            // CTC collapse: skip repeats of the immediately previous argmax, then skip blanks.
99            if best_tok == prev_arg {
100                continue;
101            }
102            prev_arg = best_tok;
103            if best_tok == BLANK {
104                continue;
105            }
106
107            // Softmax confidence of the emitted token.
108            let mut sum_exp = 0.0f32;
109            for v in 0..vocab {
110                let logit = token_logit(blob, v, feat_dim, bias_off, logmel_frame);
111                sum_exp += (logit - best_logit).exp();
112            }
113            let prob = if sum_exp > 0.0 { 1.0 / sum_exp } else { 0.0 };
114            let confidence_u16 = (prob.clamp(0.0, 1.0) * 65535.0) as u16;
115
116            if written >= out_tokens.len() {
117                return Err(AudioError::OutputBufferTooSmall);
118            }
119            out_tokens[written] = TranscriptToken {
120                form_hash: form_hash(best_tok),
121                proposed_meaning_hash: 0,
122                confidence_u16,
123                language_slot: lang as u16,
124                start_frame: frame as u64,
125                end_frame: frame as u64 + 1,
126                speaker_track: 0,
127                flags: 0,
128            };
129            written += 1;
130        }
131        Ok(written)
132    }
133}
134
135#[inline]
136fn token_logit(
137    blob: &WeightBlob,
138    v: usize,
139    feat_dim: usize,
140    bias_off: usize,
141    frame: &[f32],
142) -> f32 {
143    let row = v * feat_dim;
144    let mut acc = blob.data[bias_off + v];
145    for f in 0..feat_dim {
146        acc += blob.data[row + f] * frame[f];
147    }
148    acc
149}
150
151#[inline]
152fn form_hash(idx: usize) -> u64 {
153    SPEECH_FORM_BASE
154        ^ (idx as u64)
155            .wrapping_add(1)
156            .wrapping_mul(0x9E37_79B9_7F4A_7C15)
157}
158
159#[inline]
160fn language_slot(blob: &WeightBlob) -> u32 {
161    blob.dims.get(2).copied().unwrap_or(LANG_UNKNOWN)
162}
163
164fn shape(blob: &WeightBlob) -> Result<(usize, usize, u32), AudioError> {
165    if blob.dims.len() != 3 {
166        return Err(AudioError::BackendUnavailable);
167    }
168    Ok((blob.dims[0] as usize, blob.dims[1] as usize, blob.dims[2]))
169}
170
171fn validate_shape(blob: &WeightBlob) -> Result<(), AudioError> {
172    let (vocab, feat_dim, _lang) = shape(blob)?;
173    if vocab == 0 || feat_dim == 0 {
174        return Err(AudioError::BackendUnavailable);
175    }
176    let need = vocab * feat_dim + vocab;
177    if blob.data.len() != need {
178        return Err(AudioError::BackendUnavailable);
179    }
180    Ok(())
181}
182
183#[cfg(test)]
184mod tests {
185    use super::*;
186    use crate::models::loader::{make_blob, write_weight_blob};
187
188    // vocab=3 (0=blank,1,2), feat_dim=2, language=7 (known).
189    // token 1 fires on feature[0]; token 2 fires on feature[1]; blank is small everywhere.
190    fn known_lang_blob() -> Vec<u8> {
191        let data = vec![
192            // proj rows (vocab-major): blank, tok1, tok2
193            0.0, 0.0, // blank
194            3.0, 0.0, // tok1
195            0.0, 3.0, // tok2
196            // biases
197            0.1, 0.0, 0.0,
198        ];
199        write_weight_blob(&make_blob(vec![3, 2, 7], data))
200    }
201
202    fn unknown_lang_blob() -> Vec<u8> {
203        let data = vec![0.0, 0.0, 3.0, 0.0, 0.0, 3.0, 0.1, 0.0, 0.0];
204        write_weight_blob(&make_blob(vec![3, 2, 0], data)) // language_slot 0 = unknown
205    }
206
207    #[test]
208    fn absent_abstains_never_fabricates() {
209        let head = SpeechHead::new();
210        let mut out = [TranscriptToken::empty(); 8];
211        let logmel = [1.0, 0.0, 0.0, 1.0];
212        assert_eq!(
213            head.infer_ctc(&logmel, &mut out),
214            Err(AudioError::BackendUnavailable)
215        );
216        assert_eq!(out[0], TranscriptToken::empty());
217    }
218
219    #[test]
220    fn unknown_language_abstains() {
221        let mut head = SpeechHead::new();
222        head.load(&unknown_lang_blob()).expect("load");
223        assert!(!head.is_ready());
224        let mut out = [TranscriptToken::empty(); 8];
225        let logmel = [1.0, 0.0];
226        assert_eq!(
227            head.infer_ctc(&logmel, &mut out),
228            Err(AudioError::BackendUnavailable)
229        );
230    }
231
232    #[test]
233    fn greedy_ctc_collapses_and_decodes() {
234        let mut head = SpeechHead::new();
235        head.load(&known_lang_blob()).expect("load");
236        assert!(head.is_ready());
237        let mut out = [TranscriptToken::empty(); 8];
238        // frames: tok1, tok1(repeat→collapse), blank(→drop), tok2  => [tok1, tok2]
239        let logmel = [
240            5.0, 0.0, // -> tok1
241            5.0, 0.0, // -> tok1 (repeat)
242            0.0, 0.0, // -> blank
243            0.0, 5.0, // -> tok2
244        ];
245        let n = head.infer_ctc(&logmel, &mut out).expect("infer");
246        assert_eq!(n, 2);
247        assert_eq!(out[0].form_hash, form_hash(1));
248        assert_eq!(out[1].form_hash, form_hash(2));
249        assert_eq!(out[0].language_slot, 7);
250    }
251
252    #[test]
253    fn ragged_input_is_invalid() {
254        let mut head = SpeechHead::new();
255        head.load(&known_lang_blob()).expect("load");
256        let mut out = [TranscriptToken::empty(); 8];
257        // length 3 is not a multiple of feat_dim=2.
258        assert_eq!(
259            head.infer_ctc(&[1.0, 0.0, 1.0], &mut out),
260            Err(AudioError::InvalidParameter)
261        );
262    }
263
264    #[test]
265    fn output_overflow_reported() {
266        let mut head = SpeechHead::new();
267        head.load(&known_lang_blob()).expect("load");
268        let mut out = [TranscriptToken::empty(); 1];
269        // decodes tok1 then tok2 -> needs 2 slots, only 1 provided.
270        let logmel = [5.0, 0.0, 0.0, 5.0];
271        assert_eq!(
272            head.infer_ctc(&logmel, &mut out),
273            Err(AudioError::OutputBufferTooSmall)
274        );
275    }
276}