Skip to main content

qualia_client_core/conditioning/
auto_route.rs

1//! Chat-lowering bridge for verified model-precision contracts.
2//!
3//! The bridge runs while assembling a request, before tokenisation and outside
4//! the decode hot path. It never invents a contract: both core registries must
5//! agree on profile ID, version, and specification identity.
6
7use qualia_core_db::inference::conditioning::{
8    select_prioritized_parts, RequestPart, RequestPartKind,
9};
10use qualia_core_db::inference::conditioning_opt::{
11    resolve_global_active_contract, CompressionStrategy, ModelPrecisionContract,
12    PrefixConfiguration,
13};
14
15/// Receipt returned when a verified precision contract changes a chat request.
16#[derive(Debug, Clone, PartialEq, Eq)]
17pub struct AppliedPrecision {
18    pub profile_id: String,
19    pub profile_version: u64,
20    pub spec_identity: u64,
21    pub input_budget_bytes: u32,
22    pub output_budget_tokens: u32,
23    /// Reserved deliberation (`<think>`) tokens for thinking-model decode;
24    /// `None` when the contract makes no deliberation reservation.
25    pub thinking_budget_tokens: Option<u32>,
26    pub prefix: PrefixConfiguration,
27    pub compression: CompressionStrategy,
28    pub original_prompt_bytes: usize,
29    pub lowered_prompt_bytes: usize,
30    pub context_truncated: bool,
31}
32
33/// Resolve and apply the model's verified runtime contract. A missing or stale
34/// contract is deliberately a no-op so ordinary chats retain their established
35/// behaviour until calibration is explicitly promoted.
36pub fn apply_active_model_precision(
37    model_id: &str,
38    augmented_prompt: &mut String,
39    user_prompt: &str,
40) -> Result<Option<AppliedPrecision>, String> {
41    let Some(contract) = resolve_global_active_contract(model_id) else {
42        return Ok(None);
43    };
44    apply_contract_to_prompt(augmented_prompt, user_prompt, &contract).map(Some)
45}
46
47/// Apply one already-verified contract. Public for deterministic tests and
48/// alternate client surfaces; normal chat should use
49/// [`apply_active_model_precision`].
50pub fn apply_contract_to_prompt(
51    augmented_prompt: &mut String,
52    user_prompt: &str,
53    contract: &ModelPrecisionContract,
54) -> Result<AppliedPrecision, String> {
55    let original_prompt_bytes = augmented_prompt.len();
56    let user_tail = format!("{user_prompt}\n---");
57    if !augmented_prompt.ends_with(&user_tail) {
58        return Err(
59            "conditioning lowerer received a prompt with an unexpected user suffix".to_string(),
60        );
61    }
62    let user_content_start = augmented_prompt.len() - user_tail.len();
63    let user_start = augmented_prompt[..user_content_start]
64        .rfind("\n---\nUser")
65        .ok_or("conditioning lowerer could not find the final user boundary")?;
66    let user_suffix = &augmented_prompt[user_start..];
67    let invariant_header = format!(
68        "[qualia:conditioning profile={} version={} strategy={} prefix={}]\n",
69        contract.profile_id,
70        contract.profile_version,
71        contract.compression.as_str(),
72        contract.prefix.as_str(),
73    );
74    let cap = contract.budget.max_bytes as usize;
75    let required_bytes = invariant_header.len().saturating_add(user_suffix.len());
76    if required_bytes > cap {
77        return Err("conditioning input budget cannot retain the final user request".to_string());
78    }
79
80    let prefix = &augmented_prompt[..user_start];
81
82    // Priority-driven validation using typed request parts
83    let header_part = RequestPart::required_instruction(&invariant_header);
84    let user_part = RequestPart::user_prompt(user_suffix);
85    let prefix_part = RequestPart::evidence("context", prefix, None);
86
87    let parts = [header_part, user_part, prefix_part];
88    let mut selected_parts = [RequestPart::required_instruction(""); 3];
89    let selected_count =
90        select_prioritized_parts(&parts, cap, &mut selected_parts).map_err(|_| {
91            "conditioning input budget cannot retain the final user request".to_string()
92        })?;
93
94    let had_evidence = selected_parts[..selected_count]
95        .iter()
96        .any(|p| p.kind == RequestPartKind::Evidence);
97
98    let retained_prefix = if had_evidence {
99        prefix
100    } else {
101        let required_bytes = invariant_header.len().saturating_add(user_suffix.len());
102        let remaining_prefix_bytes = cap.saturating_sub(required_bytes);
103        utf8_prefix(prefix, remaining_prefix_bytes)
104    };
105    let context_truncated =
106        (selected_count < parts.len()) || (retained_prefix.len() < prefix.len());
107
108    let mut lowered = String::with_capacity(
109        invariant_header
110            .len()
111            .saturating_add(retained_prefix.len())
112            .saturating_add(user_suffix.len()),
113    );
114    lowered.push_str(&invariant_header);
115    lowered.push_str(retained_prefix);
116    lowered.push_str(user_suffix);
117
118    let receipt = AppliedPrecision {
119        profile_id: contract.profile_id.clone(),
120        profile_version: contract.profile_version,
121        spec_identity: contract.spec_identity,
122        input_budget_bytes: contract.budget.max_bytes,
123        output_budget_tokens: contract.budget.output_tokens,
124        thinking_budget_tokens: contract.budget.thinking_token_budget,
125        prefix: contract.prefix,
126        compression: contract.compression,
127        original_prompt_bytes,
128        lowered_prompt_bytes: lowered.len(),
129        context_truncated,
130    };
131    *augmented_prompt = lowered;
132    Ok(receipt)
133}
134
135/// Apply verified model-precision contract across explicitly structured request parts.
136pub fn apply_contract_to_parts<'a>(
137    parts: &[RequestPart<'a>],
138    contract: &ModelPrecisionContract,
139) -> Result<(String, AppliedPrecision), String> {
140    let invariant_header = format!(
141        "[qualia:conditioning profile={} version={} strategy={} prefix={}]\n",
142        contract.profile_id,
143        contract.profile_version,
144        contract.compression.as_str(),
145        contract.prefix.as_str(),
146    );
147    let cap = contract.budget.max_bytes as usize;
148    let header_part = RequestPart::required_instruction(&invariant_header);
149
150    let mut all_parts = Vec::with_capacity(parts.len() + 1);
151    all_parts.push(header_part);
152    all_parts.extend_from_slice(parts);
153
154    let mut selected_parts = vec![RequestPart::required_instruction(""); all_parts.len()];
155    let selected_count =
156        select_prioritized_parts(&all_parts, cap, &mut selected_parts).map_err(|e| {
157            format!("conditioning input budget cannot retain mandatory request parts: {e:?}")
158        })?;
159
160    let mut total_rendered_bytes = 0;
161    for part in &selected_parts[..selected_count] {
162        total_rendered_bytes += part.byte_len();
163    }
164
165    let mut rendered = String::with_capacity(total_rendered_bytes);
166    let mut original_bytes = 0;
167    for part in parts {
168        original_bytes += part.byte_len();
169    }
170    for part in &selected_parts[..selected_count] {
171        rendered.push_str(part.content);
172    }
173
174    let receipt = AppliedPrecision {
175        profile_id: contract.profile_id.clone(),
176        profile_version: contract.profile_version,
177        spec_identity: contract.spec_identity,
178        input_budget_bytes: contract.budget.max_bytes,
179        output_budget_tokens: contract.budget.output_tokens,
180        thinking_budget_tokens: contract.budget.thinking_token_budget,
181        prefix: contract.prefix,
182        compression: contract.compression,
183        original_prompt_bytes: original_bytes,
184        lowered_prompt_bytes: rendered.len(),
185        context_truncated: selected_count < all_parts.len(),
186    };
187
188    Ok((rendered, receipt))
189}
190
191fn utf8_prefix(value: &str, max_bytes: usize) -> &str {
192    if value.len() <= max_bytes {
193        return value;
194    }
195    let mut end = max_bytes;
196    while end > 0 && !value.is_char_boundary(end) {
197        end -= 1;
198    }
199    &value[..end]
200}
201
202#[cfg(test)]
203mod tests {
204    use super::*;
205    use qualia_core_db::inference::conditioning::ConditioningBudget;
206
207    fn contract(max_bytes: u32) -> ModelPrecisionContract {
208        ModelPrecisionContract::new(
209            "urn:qualia:profile:model:test",
210            3,
211            0xabc,
212            ConditioningBudget {
213                input_tokens: 1024,
214                output_tokens: 96,
215                tool_rounds: 1,
216                max_bytes,
217                thinking_token_budget: None,
218            },
219            PrefixConfiguration::CanonicalCacheAligned,
220            CompressionStrategy::CompactContext,
221        )
222        .unwrap()
223    }
224
225    #[test]
226    fn lowerer_preserves_user_request_and_applies_budgets() {
227        let mut prompt = format!(
228            "capability:{}\n---\nUser: retain this exact request\n---",
229            "α".repeat(80)
230        );
231        let receipt =
232            apply_contract_to_prompt(&mut prompt, "retain this exact request", &contract(220))
233                .unwrap();
234
235        assert!(prompt.starts_with("[qualia:conditioning profile=urn:qualia:profile:model:test"));
236        assert!(prompt.ends_with("---\nUser: retain this exact request\n---"));
237        assert!(receipt.context_truncated);
238        assert!(receipt.lowered_prompt_bytes <= 220);
239        assert_eq!(receipt.output_budget_tokens, 96);
240        assert_eq!(receipt.prefix, PrefixConfiguration::CanonicalCacheAligned);
241    }
242
243    #[test]
244    fn lowerer_rejects_a_cap_that_cannot_retain_user_request() {
245        let mut prompt =
246            "context\n---\nUser: a request that must not be truncated\n---".to_string();
247        let err = apply_contract_to_prompt(
248            &mut prompt,
249            "a request that must not be truncated",
250            &contract(20),
251        )
252        .unwrap_err();
253
254        assert!(err.contains("cannot retain"));
255        assert!(prompt.starts_with("context"));
256    }
257
258    #[test]
259    fn test_apply_contract_to_parts_prioritizes_and_enforces_budget() {
260        let instr = RequestPart::required_instruction("Instructions: compute answer accurately.");
261        let user = RequestPart::user_prompt("User query: what is 2+2?");
262        let evidence = RequestPart::evidence(
263            "doc1",
264            "Additional background information that is optional.",
265            None,
266        );
267
268        let parts = [instr, user, evidence];
269        // Large enough budget: all fit
270        let (rendered, receipt) = apply_contract_to_parts(&parts, &contract(500)).unwrap();
271        assert!(rendered.contains("Instructions: compute answer accurately."));
272        assert!(rendered.contains("User query: what is 2+2?"));
273        assert!(rendered.contains("Additional background information"));
274        assert!(!receipt.context_truncated);
275
276        // Tight budget: drops optional evidence, retains mandatory parts (172 mandatory bytes <= 200 < 223 total)
277        let (rendered_tight, receipt_tight) =
278            apply_contract_to_parts(&parts, &contract(200)).unwrap();
279        assert!(rendered_tight.contains("Instructions: compute answer accurately."));
280        assert!(rendered_tight.contains("User query: what is 2+2?"));
281        assert!(!rendered_tight.contains("Additional background information"));
282        assert!(receipt_tight.context_truncated);
283
284        // Impossible budget: cannot fit mandatory parts -> Err
285        assert!(apply_contract_to_parts(&parts, &contract(100)).is_err());
286    }
287}