Skip to main content

qualia_core_db/inference/gguf_sharder/
hyperparams.rs

1//! Qualia architecture admission policy over canonical numerical metadata.
2
3pub use etalon_model::inference::{
4    parse_architecture_id, ARCH_DEEPSEEK_MOE, ARCH_FLAG_HAS_PLE, ARCH_FLAG_HAS_QK_NORM,
5    ARCH_FLAG_HAS_SHARED_KV, ARCH_FLAG_HAS_SOFTCAP, ARCH_FLAG_HAS_SWA, ARCH_GEMMA, ARCH_GEMMA2,
6    ARCH_GEMMA3, ARCH_GEMMA4, ARCH_GLM4, ARCH_GRANITE_HYBRID, ARCH_LLAMA, ARCH_OTHER, ARCH_PHI4,
7    ARCH_QWEN2, ARCH_QWEN35_MOE, ARCH_QWEN4EXP, ARCH_UNKNOWN, DEFAULT_ROPE_FREQ_BASE,
8};
9
10/// Architecture hyper-parameters parsed from the GGUF KV section.
11#[derive(Debug, Clone, Copy, Default, PartialEq)]
12pub struct GgufHyperparams {
13    pub n_layer: u32,
14    pub n_embd: u32,
15    pub n_head: u32,
16    /// Grouped-query KV heads; `0` means MHA (`n_kv_head == n_head`).
17    pub n_kv_head: u32,
18    /// `llama.rope.freq_base` (FLOAT32 in GGUF); `0` → [`DEFAULT_ROPE_FREQ_BASE`].
19    pub rope_freq_base: f32,
20    /// Linear RoPE scale from `llama.rope.scale_linear` / `llama.rope.scaling.factor`; `0` → `1.0`.
21    pub rope_scale: f32,
22    /// Explicit head dim (`*.attention.key_length`); `0` → derive `n_embd / n_head`.
23    pub head_dim: u32,
24    /// SWA / local-attention head dim (`*.attention.key_length_swa`); `0` → same as `head_dim`.
25    pub head_dim_swa: u32,
26    /// Sliding-window size in tokens; `0` → full context attention only.
27    pub sliding_window: u32,
28    /// Last N layers share KV from the last non-shared layer of the same type (Gemma 4).
29    pub shared_kv_layers: u32,
30    /// Final logit softcapping (Gemma 2+); `0` → disabled.
31    pub logit_softcap: f32,
32    /// Qwen hybrid SSM causal-convolution kernel width.
33    pub ssm_conv_kernel: u32,
34    /// Qwen GatedDeltaNet recurrent state width.
35    pub ssm_state_size: u32,
36    /// Qwen SSM groups and timestep rank.
37    pub ssm_group_count: u32,
38    pub ssm_time_step_rank: u32,
39    /// Qwen SSM inner projection width.
40    pub ssm_inner_size: u32,
41    /// Full-attention cadence among hybrid SSM layers (`0` means unspecified).
42    pub full_attention_interval: u32,
43    /// `ARCH_*()` id from `general.architecture` (and tensor-feature refinement).
44    pub architecture: u32,
45    /// `ARCH_FLAG_*()` bitmask.
46    pub arch_flags: u32,
47    pub rope_dim: u32,
48    pub rope_dim_swa: u32,
49    pub rope_freq_base_swa: f32,
50    pub rms_norm_eps: f32,
51    pub ple_embd_per_layer: u32,
52}
53
54impl GgufHyperparams {
55    pub fn effective_rope_freq_base(&self) -> f32 {
56        etalon_model::inference::ModelHyperparams::from(*self).effective_rope_freq_base()
57    }
58    pub fn effective_rope_scale(&self) -> f32 {
59        etalon_model::inference::ModelHyperparams::from(*self).effective_rope_scale()
60    }
61    pub fn effective_head_dim(&self) -> u32 {
62        etalon_model::inference::ModelHyperparams::from(*self).effective_head_dim()
63    }
64    pub fn head_dim(&self) -> u32 {
65        etalon_model::inference::ModelHyperparams::from(*self).head_dim()
66    }
67    pub fn effective_n_kv_head(&self) -> u32 {
68        etalon_model::inference::ModelHyperparams::from(*self).effective_n_kv_head()
69    }
70    pub fn q_heads_per_kv(&self) -> u32 {
71        etalon_model::inference::ModelHyperparams::from(*self).q_heads_per_kv()
72    }
73    pub fn gqa_ratio(&self) -> u32 {
74        etalon_model::inference::ModelHyperparams::from(*self).gqa_ratio()
75    }
76    pub fn head_dim_swa_or(&self) -> u32 {
77        etalon_model::inference::ModelHyperparams::from(*self).head_dim_swa_or()
78    }
79    pub fn architecture_name(&self) -> &'static str {
80        etalon_model::inference::ModelHyperparams::from(*self).architecture_name()
81    }
82    pub fn decode_supported(&self) -> Result<(), String> {
83        etalon_model::inference::ModelHyperparams::from(*self).decode_supported_with_override(
84            std::env::var_os("QUALIA_LLM_FORCE_UNSUPPORTED_ARCH").is_some(),
85        )
86    }
87}
88
89impl From<etalon_model::inference::ModelHyperparams> for GgufHyperparams {
90    fn from(value: etalon_model::inference::ModelHyperparams) -> Self {
91        Self {
92            n_layer: value.n_layer,
93            n_embd: value.n_embd,
94            n_head: value.n_head,
95            n_kv_head: value.n_kv_head,
96            rope_freq_base: value.rope_freq_base,
97            rope_scale: value.rope_scale,
98            head_dim: value.head_dim,
99            head_dim_swa: value.head_dim_swa,
100            sliding_window: value.sliding_window,
101            shared_kv_layers: value.shared_kv_layers,
102            logit_softcap: value.logit_softcap,
103            ssm_conv_kernel: value.ssm_conv_kernel,
104            ssm_state_size: value.ssm_state_size,
105            ssm_group_count: value.ssm_group_count,
106            ssm_time_step_rank: value.ssm_time_step_rank,
107            ssm_inner_size: value.ssm_inner_size,
108            full_attention_interval: value.full_attention_interval,
109            architecture: value.architecture,
110            arch_flags: value.arch_flags,
111            // Pinned etalon 6ace6cc ModelHyperparams does not carry Gemma 4 extras.
112            // Keep them on the Qualia wrapper; fill from GGUF names at dispatch.
113            rope_dim: 0,
114            rope_dim_swa: 0,
115            rope_freq_base_swa: 0.0,
116            rms_norm_eps: 0.0,
117            ple_embd_per_layer: 0,
118        }
119    }
120}
121
122impl From<GgufHyperparams> for etalon_model::inference::ModelHyperparams {
123    fn from(value: GgufHyperparams) -> Self {
124        Self {
125            n_layer: value.n_layer,
126            n_embd: value.n_embd,
127            n_head: value.n_head,
128            n_kv_head: value.n_kv_head,
129            rope_freq_base: value.rope_freq_base,
130            rope_scale: value.rope_scale,
131            head_dim: value.head_dim,
132            head_dim_swa: value.head_dim_swa,
133            sliding_window: value.sliding_window,
134            shared_kv_layers: value.shared_kv_layers,
135            logit_softcap: value.logit_softcap,
136            ssm_conv_kernel: value.ssm_conv_kernel,
137            ssm_state_size: value.ssm_state_size,
138            ssm_group_count: value.ssm_group_count,
139            ssm_time_step_rank: value.ssm_time_step_rank,
140            ssm_inner_size: value.ssm_inner_size,
141            full_attention_interval: value.full_attention_interval,
142            architecture: value.architecture,
143            arch_flags: value.arch_flags,
144            ..Default::default()
145        }
146    }
147}