Skip to main content

qualia_core_db/inference/conditioning_opt/
model_target.rs

1//! Model precision targets and mapping registry.
2//!
3//! Represents a model's operational envelope (architecture family, context window,
4//! backend capabilities, template family, target domain, and active precision profile).
5
6use std::collections::BTreeMap;
7use std::sync::{OnceLock, RwLock};
8
9use crate::inference::conditioning::BackendCapabilities;
10use crate::inference::gguf_sharder::ChatFamily;
11
12use super::runtime_contract::ModelPrecisionContract;
13
14/// Model architecture families.
15#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
16pub enum ModelFamily {
17    Llama,
18    Qwen,
19    Mistral,
20    Phi,
21    Gemma,
22    Generic,
23}
24
25impl ModelFamily {
26    /// Stable string form.
27    pub fn as_str(&self) -> &'static str {
28        match self {
29            Self::Llama => "llama",
30            Self::Qwen => "qwen",
31            Self::Mistral => "mistral",
32            Self::Phi => "phi",
33            Self::Gemma => "gemma",
34            Self::Generic => "generic",
35        }
36    }
37
38    /// Default chat-template family for the model target.
39    pub fn default_template_family(&self) -> ChatFamily {
40        match self {
41            Self::Llama => ChatFamily::Llama3,
42            Self::Qwen => ChatFamily::ChatMl,
43            Self::Mistral => ChatFamily::ChatMl,
44            Self::Phi => ChatFamily::ChatMl,
45            Self::Gemma => ChatFamily::Gemma,
46            Self::Generic => ChatFamily::None,
47        }
48    }
49}
50
51/// Operational envelope and precision profile target for a specific model.
52#[derive(Debug, Clone, PartialEq, Eq)]
53pub struct ModelPrecisionTarget {
54    pub model_id: String,
55    pub family: ModelFamily,
56    pub context_window: usize,
57    pub capabilities: BackendCapabilities,
58    pub template_family: ChatFamily,
59    pub target_domain: String,
60    pub active_profile_id: Option<String>,
61    /// Runtime controls may be used only after identity validation against the
62    /// active profile in `ConditioningRegistry`.
63    pub active_contract: Option<ModelPrecisionContract>,
64}
65
66impl ModelPrecisionTarget {
67    /// Creates `ModelPrecisionTarget` with the given state.
68    pub fn new(
69        model_id: impl Into<String>,
70        family: ModelFamily,
71        context_window: usize,
72        capabilities: BackendCapabilities,
73        target_domain: impl Into<String>,
74    ) -> Self {
75        let template_family = family.default_template_family();
76        Self {
77            model_id: model_id.into(),
78            family,
79            context_window,
80            capabilities,
81            template_family,
82            target_domain: target_domain.into(),
83            active_profile_id: None,
84            active_contract: None,
85        }
86    }
87
88    /// Construct a target for a native GGUF local model.
89    pub fn native_gguf(
90        model_id: impl Into<String>,
91        family: ModelFamily,
92        context_window: usize,
93        domain: impl Into<String>,
94    ) -> Self {
95        Self::new(
96            model_id,
97            family,
98            context_window,
99            BackendCapabilities::native_gguf_baseline(),
100            domain,
101        )
102    }
103
104    /// Construct a target for an MCP remote tool/agent endpoint.
105    pub fn mcp_endpoint(
106        model_id: impl Into<String>,
107        context_window: usize,
108        domain: impl Into<String>,
109    ) -> Self {
110        Self::new(
111            model_id,
112            ModelFamily::Generic,
113            context_window,
114            BackendCapabilities::mcp_tool_baseline(),
115            domain,
116        )
117    }
118}
119
120/// Registry mapping model identifiers to precision targets and active profiles.
121#[derive(Debug, Default)]
122pub struct ModelPrecisionRegistry {
123    targets: BTreeMap<String, ModelPrecisionTarget>,
124}
125
126impl ModelPrecisionRegistry {
127    /// Creates a default `ModelPrecisionRegistry`.
128    pub fn new() -> Self {
129        Self::default()
130    }
131
132    /// Register a model precision target.
133    pub fn register(&mut self, target: ModelPrecisionTarget) {
134        self.targets.insert(target.model_id.clone(), target);
135    }
136
137    /// Retrieve a model precision target by ID.
138    pub fn get(&self, model_id: &str) -> Option<&ModelPrecisionTarget> {
139        self.targets.get(model_id)
140    }
141
142    /// Retrieve a mutable reference to a model precision target by ID.
143    pub fn get_mut(&mut self, model_id: &str) -> Option<&mut ModelPrecisionTarget> {
144        self.targets.get_mut(model_id)
145    }
146
147    /// Associate an active conditioning profile with a model.
148    pub fn set_active_profile(
149        &mut self,
150        model_id: &str,
151        profile_id: impl Into<String>,
152    ) -> Result<(), &'static str> {
153        let target = self.targets.get_mut(model_id).ok_or("model not found")?;
154        target.active_profile_id = Some(profile_id.into());
155        target.active_contract = None;
156        Ok(())
157    }
158
159    /// Clear any active conditioning profile and contract from a model target.
160    pub fn clear_active_profile(&mut self, model_id: &str) -> Result<(), &'static str> {
161        let target = self.targets.get_mut(model_id).ok_or("model not found")?;
162        target.active_profile_id = None;
163        target.active_contract = None;
164        Ok(())
165    }
166
167    /// Bind a contract to a target whose profile pointer has already been set.
168    /// A later profile change clears this binding, preventing a stale contract
169    /// from being applied to a new profile version.
170    pub fn bind_active_contract(
171        &mut self,
172        model_id: &str,
173        contract: ModelPrecisionContract,
174    ) -> Result<(), &'static str> {
175        let target = self.targets.get_mut(model_id).ok_or("model not found")?;
176        if target.active_profile_id.as_deref() != Some(contract.profile_id.as_str()) {
177            return Err("contract profile does not match active model profile");
178        }
179        target.active_contract = Some(contract);
180        Ok(())
181    }
182
183    /// Resolve an eligible contract only when the active model mapping and
184    /// conditioning lifecycle record agree exactly on profile ID, version, and
185    /// specification identity.
186    pub fn resolve_active_contract(
187        &self,
188        model_id: &str,
189        conditioning: &crate::inference::conditioning::ConditioningRegistry,
190    ) -> Option<&ModelPrecisionContract> {
191        let target = self.targets.get(model_id)?;
192        let profile_id = target.active_profile_id.as_deref()?;
193        let contract = target.active_contract.as_ref()?;
194        if contract.profile_id != profile_id {
195            return None;
196        }
197        let profile = conditioning.get_active(profile_id)?;
198        if profile.version != contract.profile_version
199            || profile.spec_identity != contract.spec_identity
200        {
201            return None;
202        }
203        Some(contract)
204    }
205
206    /// Returns an iterator over all mapped model targets.
207    pub fn iter(&self) -> impl Iterator<Item = &ModelPrecisionTarget> {
208        self.targets.values()
209    }
210
211    /// Total count of mapped models.
212    pub fn len(&self) -> usize {
213        self.targets.len()
214    }
215
216    /// Whether the registry contains any targets.
217    pub fn is_empty(&self) -> bool {
218        self.targets.is_empty()
219    }
220}
221
222static GLOBAL_MODEL_PRECISION_REGISTRY: OnceLock<RwLock<ModelPrecisionRegistry>> = OnceLock::new();
223
224/// Process-global registry used by model activation and chat lowering. The
225/// registry holds cold-path configuration; it is never accessed in decode loops.
226pub fn global_model_precision_registry() -> &'static RwLock<ModelPrecisionRegistry> {
227    GLOBAL_MODEL_PRECISION_REGISTRY.get_or_init(|| RwLock::new(ModelPrecisionRegistry::new()))
228}
229
230/// Resolve a copy of the active contract from the two lifecycle registries.
231/// Mismatches fail closed by returning `None`, leaving the regular chat path
232/// unchanged until a coherent calibration is registered.
233pub fn resolve_global_active_contract(model_id: &str) -> Option<ModelPrecisionContract> {
234    let precision = global_model_precision_registry().read().ok()?;
235    let conditioning = crate::inference::conditioning::global_registry()
236        .read()
237        .ok()?;
238    precision
239        .resolve_active_contract(model_id, &conditioning)
240        .cloned()
241}
242
243#[cfg(test)]
244mod tests {
245    use super::*;
246    use crate::inference::conditioning::{ConditioningBudget, ConditioningRegistry};
247    use crate::inference::conditioning_opt::{CompressionStrategy, PrefixConfiguration};
248
249    fn contract(profile_id: &str, version: u64, spec_identity: u64) -> ModelPrecisionContract {
250        ModelPrecisionContract::new(
251            profile_id,
252            version,
253            spec_identity,
254            ConditioningBudget {
255                input_tokens: 2048,
256                output_tokens: 128,
257                tool_rounds: 2,
258                max_bytes: 4096,
259                thinking_token_budget: None,
260            },
261            PrefixConfiguration::CanonicalCacheAligned,
262            CompressionStrategy::PreservePrefix,
263        )
264        .unwrap()
265    }
266
267    #[test]
268    fn contract_requires_matching_active_conditioning_identity() {
269        let model_id = "precision-test-model";
270        let profile_id = "urn:qualia:profile:model:precision-test-model";
271        let mut models = ModelPrecisionRegistry::new();
272        models.register(ModelPrecisionTarget::native_gguf(
273            model_id,
274            ModelFamily::Llama,
275            8192,
276            "test",
277        ));
278        models.set_active_profile(model_id, profile_id).unwrap();
279        models
280            .bind_active_contract(model_id, contract(profile_id, 2, 0x22))
281            .unwrap();
282
283        let mut conditioning = ConditioningRegistry::new();
284        conditioning.register(profile_id, 2, 0x22, None).unwrap();
285        conditioning.activate(profile_id, 2).unwrap();
286        assert!(models
287            .resolve_active_contract(model_id, &conditioning)
288            .is_some());
289
290        conditioning.register(profile_id, 3, 0x33, None).unwrap();
291        conditioning.activate(profile_id, 3).unwrap();
292        assert!(models
293            .resolve_active_contract(model_id, &conditioning)
294            .is_none());
295    }
296
297    #[test]
298    fn profile_change_clears_existing_contract() {
299        let model_id = "precision-profile-change";
300        let mut models = ModelPrecisionRegistry::new();
301        models.register(ModelPrecisionTarget::native_gguf(
302            model_id,
303            ModelFamily::Generic,
304            4096,
305            "test",
306        ));
307        models
308            .set_active_profile(model_id, "urn:profile:a")
309            .unwrap();
310        models
311            .bind_active_contract(model_id, contract("urn:profile:a", 1, 1))
312            .unwrap();
313        models
314            .set_active_profile(model_id, "urn:profile:b")
315            .unwrap();
316
317        assert!(models.get(model_id).unwrap().active_contract.is_none());
318    }
319}