gglib_core/domain/
gguf.rs

1//! GGUF domain types.
2//!
3//! This module contains the domain-facing types for GGUF file metadata
4//! and model capabilities. Parsing logic lives in `gglib-gguf`.
5
6use std::collections::{BTreeSet, HashMap};
7use std::fmt;
8
9// =============================================================================
10// Capabilities (Structured, forward-compatible)
11// =============================================================================
12
13bitflags::bitflags! {
14    /// Known model capabilities detected from GGUF metadata.
15    ///
16    /// Uses bitflags for compile-time safety on stable capabilities.
17    /// Unknown/experimental capabilities go in `GgufCapabilities::extensions`.
18    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
19    pub struct CapabilityFlags: u32 {
20        /// Model supports reasoning/thinking (e.g., DeepSeek R1, QwQ).
21        const REASONING = 0b0000_0001;
22        /// Model supports tool/function calling (e.g., Hermes, Functionary).
23        const TOOL_CALLING = 0b0000_0010;
24        /// Model supports vision/image input.
25        const VISION = 0b0000_0100;
26        /// Model supports code generation.
27        const CODE = 0b0000_1000;
28        /// Model is a mixture-of-experts architecture.
29        const MOE = 0b0001_0000;
30        /// Model contains embedded MTP (Multi-Token Prediction) draft heads.
31        ///
32        /// Detected via the `{arch}.nextn_predict_layers > 0` GGUF metadata key.
33        /// Enables `--spec-type draft-mtp` speculative decoding in llama-server.
34        const MTP = 0b0010_0000;
35    }
36}
37
38/// Model capabilities detected from GGUF metadata.
39///
40/// Combines stable known capabilities (bitflags) with forward-compatible
41/// extension strings for new/experimental capabilities.
42#[derive(Debug, Clone, Default, PartialEq, Eq)]
43pub struct GgufCapabilities {
44    /// Known stable capabilities (compile-time checked).
45    pub flags: CapabilityFlags,
46    /// Unknown/experimental capabilities (forward-compatible).
47    pub extensions: BTreeSet<String>,
48}
49
50impl GgufCapabilities {
51    /// Create empty capabilities.
52    #[must_use]
53    pub const fn empty() -> Self {
54        Self {
55            flags: CapabilityFlags::empty(),
56            extensions: BTreeSet::new(),
57        }
58    }
59
60    /// Check if reasoning is supported.
61    #[must_use]
62    pub const fn has_reasoning(&self) -> bool {
63        self.flags.contains(CapabilityFlags::REASONING)
64    }
65
66    /// Check if tool calling is supported.
67    #[must_use]
68    pub const fn has_tool_calling(&self) -> bool {
69        self.flags.contains(CapabilityFlags::TOOL_CALLING)
70    }
71
72    /// Check if vision is supported.
73    #[must_use]
74    pub const fn has_vision(&self) -> bool {
75        self.flags.contains(CapabilityFlags::VISION)
76    }
77
78    /// Check if MTP (Multi-Token Prediction) draft heads are present.
79    #[must_use]
80    pub const fn has_mtp(&self) -> bool {
81        self.flags.contains(CapabilityFlags::MTP)
82    }
83
84    /// Convert capabilities to tag strings for model metadata.
85    ///
86    /// Returns tags like "reasoning", "agent" (for tool calling), etc.
87    #[must_use]
88    pub fn to_tags(&self) -> Vec<String> {
89        let mut tags = Vec::new();
90
91        if self.has_reasoning() {
92            tags.push("reasoning".to_string());
93        }
94        if self.has_tool_calling() {
95            // "agent" tag triggers --jinja auto-enable
96            tags.push("agent".to_string());
97        }
98        if self.has_vision() {
99            tags.push("vision".to_string());
100        }
101        if self.flags.contains(CapabilityFlags::CODE) {
102            tags.push("code".to_string());
103        }
104        if self.flags.contains(CapabilityFlags::MOE) {
105            tags.push("moe".to_string());
106        }
107        if self.has_mtp() {
108            // "mtp" tag triggers --spec-type draft-mtp auto-enable
109            tags.push("mtp".to_string());
110        }
111
112        // Add extension tags
113        for ext in &self.extensions {
114            if !tags.contains(ext) {
115                tags.push(ext.clone());
116            }
117        }
118
119        tags
120    }
121}
122
123// =============================================================================
124// Metadata value types
125// =============================================================================
126
127/// GGUF metadata value types.
128///
129/// Represents all possible value types that can appear in GGUF metadata.
130#[derive(Debug, Clone)]
131pub enum GgufValue {
132    U8(u8),
133    I8(i8),
134    U16(u16),
135    I16(i16),
136    U32(u32),
137    I32(i32),
138    F32(f32),
139    Bool(bool),
140    String(String),
141    Array(Vec<Self>),
142    U64(u64),
143    I64(i64),
144    F64(f64),
145}
146
147impl fmt::Display for GgufValue {
148    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
149        match self {
150            Self::U8(v) => write!(f, "{v}"),
151            Self::I8(v) => write!(f, "{v}"),
152            Self::U16(v) => write!(f, "{v}"),
153            Self::I16(v) => write!(f, "{v}"),
154            Self::U32(v) => write!(f, "{v}"),
155            Self::I32(v) => write!(f, "{v}"),
156            Self::F32(v) => write!(f, "{v}"),
157            Self::Bool(v) => write!(f, "{v}"),
158            Self::String(v) => write!(f, "{v}"),
159            Self::U64(v) => write!(f, "{v}"),
160            Self::I64(v) => write!(f, "{v}"),
161            Self::F64(v) => write!(f, "{v}"),
162            Self::Array(arr) => {
163                // Limit array output to prevent massive tokenizer vocab dumps
164                if arr.len() > 10 {
165                    write!(f, "[Array with {} elements]", arr.len())
166                } else {
167                    write!(
168                        f,
169                        "[{}]",
170                        arr.iter()
171                            .map(std::string::ToString::to_string)
172                            .collect::<Vec<_>>()
173                            .join(", ")
174                    )
175                }
176            }
177        }
178    }
179}
180
181impl GgufValue {
182    /// Try to convert the value to a u64.
183    ///
184    /// Attempts to convert various numeric GGUF value types to u64.
185    /// Only converts non-negative values to avoid overflow issues.
186    #[must_use]
187    #[allow(clippy::cast_sign_loss)]
188    pub fn as_u64(&self) -> Option<u64> {
189        match self {
190            Self::U8(v) => Some(u64::from(*v)),
191            Self::U16(v) => Some(u64::from(*v)),
192            Self::U32(v) => Some(u64::from(*v)),
193            Self::U64(v) => Some(*v),
194            Self::I8(v) if *v >= 0 => Some(*v as u64),
195            Self::I16(v) if *v >= 0 => Some(*v as u64),
196            Self::I32(v) if *v >= 0 => Some(*v as u64),
197            Self::I64(v) if *v >= 0 => Some(*v as u64),
198            _ => None,
199        }
200    }
201
202    /// Try to convert the value to a f64.
203    #[must_use]
204    #[allow(clippy::cast_precision_loss)]
205    pub fn as_f64(&self) -> Option<f64> {
206        match self {
207            Self::F32(v) => Some(f64::from(*v)),
208            Self::F64(v) => Some(*v),
209            Self::U8(v) => Some(f64::from(*v)),
210            Self::U16(v) => Some(f64::from(*v)),
211            Self::U32(v) => Some(f64::from(*v)),
212            Self::U64(v) => Some(*v as f64),
213            Self::I8(v) => Some(f64::from(*v)),
214            Self::I16(v) => Some(f64::from(*v)),
215            Self::I32(v) => Some(f64::from(*v)),
216            Self::I64(v) => Some(*v as f64),
217            _ => None,
218        }
219    }
220
221    /// Try to get the value as a string reference.
222    #[must_use]
223    pub fn as_str(&self) -> Option<&str> {
224        match self {
225            Self::String(s) => Some(s),
226            _ => None,
227        }
228    }
229}
230
231// =============================================================================
232// Metadata
233// =============================================================================
234
235/// Parsed metadata from a GGUF file.
236///
237/// This is the domain-facing type used by services and ports.
238/// Parsing logic that produces this type lives in `gglib-gguf`.
239#[derive(Debug, Clone, Default)]
240pub struct GgufMetadata {
241    /// Model architecture (e.g., "llama", "mistral").
242    pub architecture: Option<String>,
243    /// Quantization type (e.g., "`Q4_K_M`", "`Q8_0`").
244    pub quantization: Option<String>,
245    /// Number of parameters in billions.
246    pub param_count_b: Option<f64>,
247    /// Maximum context length.
248    pub context_length: Option<u64>,
249    /// Number of experts (for `MoE` models).
250    pub expert_count: Option<u32>,
251    /// Number of experts used during inference (for `MoE` models).
252    pub expert_used_count: Option<u32>,
253    /// Number of shared experts (for `MoE` models).
254    pub expert_shared_count: Option<u32>,
255    /// Additional key-value metadata from the file (string representation).
256    pub metadata: HashMap<String, String>,
257}
258
259/// Raw metadata from GGUF parsing (before string conversion).
260///
261/// Used internally by parsers; services typically use `GgufMetadata`.
262pub type RawMetadata = HashMap<String, GgufValue>;
263
264// =============================================================================
265// Detection results (for detailed analysis)
266// =============================================================================
267
268/// Result of reasoning capability detection.
269#[derive(Debug, Clone, Default)]
270pub struct ReasoningDetection {
271    /// Whether the model appears to support reasoning/thinking.
272    pub supports_reasoning: bool,
273    /// Confidence level of the detection (0.0 to 1.0).
274    pub confidence: f32,
275    /// The specific pattern(s) that matched.
276    pub matched_patterns: Vec<String>,
277    /// Suggested reasoning format for llama-server.
278    pub suggested_format: Option<String>,
279}
280
281/// Result of tool calling capability detection.
282#[derive(Debug, Clone, Default)]
283pub struct ToolCallingDetection {
284    /// Whether the model appears to support tool/function calling.
285    pub supports_tool_calling: bool,
286    /// Confidence level of the detection (0.0 to 1.0).
287    pub confidence: f32,
288    /// The specific pattern(s) that matched.
289    pub matched_patterns: Vec<String>,
290    /// Detected tool calling format (e.g., "hermes", "llama3", "mistral").
291    pub detected_format: Option<String>,
292}
293
294// =============================================================================
295// Tests
296// =============================================================================
297
298#[cfg(test)]
299mod tests {
300    use super::*;
301
302    #[test]
303    fn test_capabilities_empty() {
304        let caps = GgufCapabilities::empty();
305        assert!(!caps.has_reasoning());
306        assert!(!caps.has_tool_calling());
307        assert!(caps.to_tags().is_empty());
308    }
309
310    #[test]
311    fn test_capabilities_flags() {
312        let caps = GgufCapabilities {
313            flags: CapabilityFlags::REASONING | CapabilityFlags::TOOL_CALLING,
314            extensions: BTreeSet::new(),
315        };
316        assert!(caps.has_reasoning());
317        assert!(caps.has_tool_calling());
318
319        let tags = caps.to_tags();
320        assert!(tags.contains(&"reasoning".to_string()));
321        assert!(tags.contains(&"agent".to_string()));
322    }
323
324    #[test]
325    fn test_capabilities_extensions() {
326        let mut extensions = BTreeSet::new();
327        extensions.insert("experimental-feature".to_string());
328
329        let caps = GgufCapabilities {
330            flags: CapabilityFlags::empty(),
331            extensions,
332        };
333
334        let tags = caps.to_tags();
335        assert!(tags.contains(&"experimental-feature".to_string()));
336    }
337
338    #[test]
339    fn test_gguf_value_as_u64() {
340        assert_eq!(GgufValue::U32(4096).as_u64(), Some(4096));
341        assert_eq!(GgufValue::I32(-1).as_u64(), None);
342        assert_eq!(GgufValue::String("hello".to_string()).as_u64(), None);
343        assert_eq!(GgufValue::I32(100).as_u64(), Some(100));
344    }
345
346    #[test]
347    fn test_gguf_value_as_f64() {
348        assert!((GgufValue::F32(7.5).as_f64().unwrap() - 7.5).abs() < f64::EPSILON);
349        assert!((GgufValue::U64(1000).as_f64().unwrap() - 1000.0).abs() < f64::EPSILON);
350        assert_eq!(GgufValue::Bool(true).as_f64(), None);
351    }
352
353    #[test]
354    fn test_gguf_value_display() {
355        assert_eq!(GgufValue::U32(42).to_string(), "42");
356        assert_eq!(GgufValue::String("test".to_string()).to_string(), "test");
357
358        let large_array = GgufValue::Array(vec![GgufValue::U8(0); 100]);
359        assert!(large_array.to_string().contains("100 elements"));
360    }
361}
gglib_core/domain/gguf.rs

gglib_core/domain/
gguf.rs
