Skip to main content

qualia_core_db/inference/
safetensor.rs

1//! Phase 6 / task #12 — **safetensor (+ MLX) source parsing + dtype gate** for the streaming
2//! transcoder (`p64_weight::transcode_safetensor_to_p64`).
3//!
4//! This module only **parses + validates** a source; the streaming **emit** to the P64 container
5//! lives in `p64_weight` (it owns the container's private serializers). The split keeps the format
6//! writer encapsulated.
7//!
8//! ## Scope (honest)
9//! * **safetensor** — the on-disk layout is parsed here: an 8-byte little-endian header length,
10//!   then a JSON header `{ name: { dtype, shape, data_offsets:[begin,end] }, … }`, then the raw
11//!   tensor bytes. The JSON header is small (KBs); the tensor bytes are **never** read here — only
12//!   their offsets — so a multi-GB file is *not* loaded to plan the transcode.
13//! * **MLX** — Apple MLX exports are safetensor-format (often with `__metadata__.format = "mlx"`);
14//!   they parse through this path. MLX `.npz` archives are **deferred** (a different container).
15//! * **high-fidelity only** — [`is_high_fidelity_ggml`] accepts `F32 / F16 / BF16 / Q8_0` and
16//!   **rejects** `Q4_*` and other low-precision quant types (the "Q4 rejected" rail).
17
18/// A detected model source container.
19#[derive(Debug, Clone, Copy, PartialEq, Eq)]
20pub enum SourceFormat {
21    /// safetensor (incl. MLX-safetensor).
22    Safetensor,
23    /// GGUF (the established path — `p64_weight::compile_gguf_to_p64`).
24    Gguf,
25    /// Unrecognised.
26    Unknown,
27}
28
29/// Sniff the container format from the first bytes. GGUF starts with the ASCII magic `GGUF`;
30/// safetensor starts with an 8-byte LE header length immediately followed by a `{` (the JSON).
31pub fn detect_format(head: &[u8]) -> SourceFormat {
32    if head.len() >= 4 && &head[0..4] == b"GGUF" {
33        return SourceFormat::Gguf;
34    }
35    if head.len() >= 9 {
36        let hlen = u64::from_le_bytes(head[0..8].try_into().unwrap()) as usize;
37        // a sane JSON header length, and the JSON object opens right after the 8-byte length.
38        if hlen > 0 && hlen < (1 << 30) && head[8] == b'{' {
39            return SourceFormat::Safetensor;
40        }
41    }
42    SourceFormat::Unknown
43}
44
45/// One tensor declared in a safetensor header.
46#[derive(Debug, Clone, PartialEq, Eq)]
47pub struct SafeTensorEntry {
48    pub name: String,
49    pub dtype: String,
50    pub shape: Vec<usize>,
51    /// Byte range of the tensor within the data region (relative to `data_start`).
52    pub begin: usize,
53    pub end: usize,
54}
55
56impl SafeTensorEntry {
57    #[inline]
58    /// `SafeTensorEntry::byte_len`.
59    pub fn byte_len(&self) -> usize {
60        self.end - self.begin
61    }
62}
63
64/// The parsed plan: every tensor's metadata + the absolute offset where tensor data begins.
65#[derive(Debug, Clone)]
66pub struct SafeTensorPlan {
67    pub tensors: Vec<SafeTensorEntry>,
68    /// Absolute byte offset (in the source) of the start of the tensor-data region.
69    pub data_start: usize,
70    /// `true` if `__metadata__.format == "mlx"`.
71    pub is_mlx: bool,
72}
73
74/// Parse a safetensor header (the small JSON prefix only — never the tensor bytes). Validates that
75/// every declared byte range lies within `src`.
76pub fn parse_safetensor_header(src: &[u8]) -> Result<SafeTensorPlan, String> {
77    if src.len() < 8 {
78        return Err("safetensor: too small for 8-byte header length".to_string());
79    }
80    let hlen = u64::from_le_bytes(src[0..8].try_into().unwrap()) as usize;
81    let data_start = 8usize
82        .checked_add(hlen)
83        .ok_or("safetensor: header length overflow")?;
84    if data_start > src.len() {
85        return Err("safetensor: header length exceeds file".to_string());
86    }
87    let json: serde_json::Value = serde_json::from_slice(&src[8..data_start])
88        .map_err(|e| format!("safetensor: header JSON parse error: {e}"))?;
89    let obj = json
90        .as_object()
91        .ok_or("safetensor: header is not a JSON object")?;
92
93    let is_mlx = obj
94        .get("__metadata__")
95        .and_then(|m| m.get("format"))
96        .and_then(|f| f.as_str())
97        .map(|s| s.eq_ignore_ascii_case("mlx"))
98        .unwrap_or(false);
99
100    let data_len = src.len() - data_start;
101    let mut tensors = Vec::new();
102    for (name, spec) in obj {
103        if name == "__metadata__" {
104            continue;
105        }
106        let dtype = spec
107            .get("dtype")
108            .and_then(|d| d.as_str())
109            .ok_or_else(|| format!("safetensor: tensor '{name}' missing dtype"))?
110            .to_string();
111        let shape = spec
112            .get("shape")
113            .and_then(|s| s.as_array())
114            .ok_or_else(|| format!("safetensor: tensor '{name}' missing shape"))?
115            .iter()
116            .map(|v| v.as_u64().unwrap_or(0) as usize)
117            .collect::<Vec<_>>();
118        let offs = spec
119            .get("data_offsets")
120            .and_then(|o| o.as_array())
121            .ok_or_else(|| format!("safetensor: tensor '{name}' missing data_offsets"))?;
122        if offs.len() != 2 {
123            return Err(format!(
124                "safetensor: tensor '{name}' data_offsets must be [begin,end]"
125            ));
126        }
127        let begin = offs[0].as_u64().unwrap_or(0) as usize;
128        let end = offs[1].as_u64().unwrap_or(0) as usize;
129        if end < begin || end > data_len {
130            return Err(format!("safetensor: tensor '{name}' offsets out of bounds"));
131        }
132        tensors.push(SafeTensorEntry {
133            name: name.clone(),
134            dtype,
135            shape,
136            begin,
137            end,
138        });
139    }
140    // Deterministic order (header JSON object order is not guaranteed).
141    tensors.sort_by(|a, b| a.begin.cmp(&b.begin));
142    Ok(SafeTensorPlan {
143        tensors,
144        data_start,
145        is_mlx,
146    })
147}
148
149// ── dtype gate (high-fidelity only) ──────────────────────────────────────────────────────────────
150
151/// GGML element type codes used here (mirrors `gguf_sharder`): `0=F32, 1=F16, 8=Q8_0, 30=BF16`;
152/// low-precision quants are `Q4_0=2, Q4_1=3, Q4_K=12, …`.
153pub const GGML_F32: u32 = 0;
154pub const GGML_F16: u32 = 1;
155pub const GGML_Q8_0: u32 = 8;
156pub const GGML_BF16: u32 = 30;
157
158/// Map a safetensor dtype string to a GGML element type. `None` for anything not a supported
159/// high-fidelity weight dtype (so unknown / low-precision safetensor dtypes are rejected upstream).
160pub fn safetensor_dtype_to_ggml(dtype: &str) -> Option<u32> {
161    match dtype {
162        "F32" => Some(GGML_F32),
163        "F16" => Some(GGML_F16),
164        "BF16" => Some(GGML_BF16),
165        _ => None, // F8/I8/U8/BOOL/F64/… are not high-fidelity weight inputs for this path
166    }
167}
168
169/// Whether a GGML element type is a **high-fidelity** source this versioned path accepts.
170/// Accepts `F32 / F16 / BF16 / Q8_0`; **rejects** `Q4_*` and every other low-precision quant — the
171/// "ingest high-fidelity sources only; Q4 rejected/warned" rail.
172pub fn is_high_fidelity_ggml(ggml_type: u32) -> bool {
173    matches!(ggml_type, GGML_F32 | GGML_F16 | GGML_Q8_0 | GGML_BF16)
174}
175
176/// Bytes per element for the dtypes this path accepts (used to validate declared tensor sizes).
177pub fn ggml_elem_bytes(ggml_type: u32) -> Option<usize> {
178    match ggml_type {
179        GGML_F32 => Some(4),
180        GGML_F16 | GGML_BF16 => Some(2),
181        GGML_Q8_0 => Some(1), // block-quantised; treated per-byte for verbatim repackage
182        _ => None,
183    }
184}
185
186#[cfg(test)]
187mod tests {
188    use super::*;
189
190    /// Build a minimal safetensor: two F16 tensors of given element counts.
191    fn synth_safetensor(t: &[(&str, &str, Vec<usize>, usize)]) -> Vec<u8> {
192        // assign contiguous byte ranges
193        let mut entries = serde_json::Map::new();
194        let mut cursor = 0usize;
195        for (name, dtype, shape, nbytes) in t {
196            let begin = cursor;
197            let end = cursor + nbytes;
198            cursor = end;
199            entries.insert(
200                (*name).to_string(),
201                serde_json::json!({ "dtype": dtype, "shape": shape, "data_offsets": [begin, end] }),
202            );
203        }
204        let header = serde_json::Value::Object(entries);
205        let header_bytes = serde_json::to_vec(&header).unwrap();
206        let mut out = Vec::new();
207        out.extend_from_slice(&(header_bytes.len() as u64).to_le_bytes());
208        out.extend_from_slice(&header_bytes);
209        out.resize(out.len() + cursor, 0u8); // zeroed tensor data
210        out
211    }
212
213    #[test]
214    fn detects_formats() {
215        let st = synth_safetensor(&[("w", "F16", vec![2, 2], 8)]);
216        assert_eq!(detect_format(&st), SourceFormat::Safetensor);
217        assert_eq!(detect_format(b"GGUF\0\0\0\0"), SourceFormat::Gguf);
218        assert_eq!(detect_format(b"not a model"), SourceFormat::Unknown);
219    }
220
221    #[test]
222    fn parses_header_and_offsets() {
223        let st = synth_safetensor(&[("a", "F16", vec![4], 8), ("b", "F32", vec![2, 2], 16)]);
224        let plan = parse_safetensor_header(&st).unwrap();
225        assert_eq!(plan.tensors.len(), 2);
226        assert_eq!(plan.tensors[0].name, "a");
227        assert_eq!(plan.tensors[0].byte_len(), 8);
228        assert_eq!(plan.tensors[1].dtype, "F32");
229        assert_eq!(plan.tensors[1].byte_len(), 16);
230        assert!(!plan.is_mlx);
231    }
232
233    #[test]
234    fn dtype_gate_accepts_high_fidelity_rejects_q4() {
235        assert_eq!(safetensor_dtype_to_ggml("F16"), Some(GGML_F16));
236        assert_eq!(safetensor_dtype_to_ggml("BF16"), Some(GGML_BF16));
237        assert_eq!(safetensor_dtype_to_ggml("U8"), None);
238
239        assert!(is_high_fidelity_ggml(GGML_F16));
240        assert!(is_high_fidelity_ggml(GGML_Q8_0));
241        assert!(!is_high_fidelity_ggml(12)); // Q4_K — rejected
242        assert!(!is_high_fidelity_ggml(2)); // Q4_0 — rejected
243    }
244}