Skip to main content

qualia_core_db/services/
poet_llm_conditioning.rs

1//! Request-boundary lowering for Prompt Precision local-model calls.
2
3use serde::Deserialize;
4
5use super::poet_llm_api::PoetLlmRequest;
6
7const MAX_PROMPT_BYTES: usize = 32 * 1024;
8const MAX_CONDITIONING_REQUIREMENTS: usize = 64;
9const MAX_CONDITIONING_EVIDENCE: usize = 64;
10const MAX_CONDITIONING_DOMAINS: usize = 16;
11
12/// An owned, cold-boundary profile. It is compiled into caller-buffered plan
13/// data before inference starts; no profile changes the original request.
14///
15/// Public so the same profile document can be compiled for the desktop chat,
16/// Ollama and remote-MCP routes — not only the POET HTTP surface.
17#[derive(Debug, Clone, Deserialize)]
18pub struct PromptConditioning {
19    #[serde(default = "default_schema_version")]
20    schema_version: u16,
21    #[serde(default)]
22    profile_id: String,
23    #[serde(default)]
24    objective: String,
25    #[serde(default)]
26    requirements: Vec<PromptRequirement>,
27    #[serde(default)]
28    evidence: Vec<PromptEvidence>,
29    #[serde(default)]
30    domains: Vec<String>,
31    #[serde(default)]
32    allowed_graph_scopes: Vec<u64>,
33    #[serde(default)]
34    disclosure_ceiling: u8,
35    #[serde(default = "default_tools_allowed")]
36    tools_allowed: bool,
37    #[serde(default)]
38    budget: Option<PromptConditioningBudget>,
39}
40
41#[derive(Debug, Clone, Deserialize)]
42pub struct PromptRequirement {
43    id: String,
44    #[serde(default = "default_requirement_class")]
45    class: String,
46    rule: String,
47    #[serde(default)]
48    validator: Option<String>,
49    #[serde(default)]
50    required: bool,
51    #[serde(default)]
52    priority: u8,
53}
54
55#[derive(Debug, Clone, Deserialize)]
56pub struct PromptEvidence {
57    source_id: String,
58    #[serde(default)]
59    scope: u64,
60    #[serde(default)]
61    sensitivity: u8,
62    content: String,
63    #[serde(default)]
64    qualifier: Option<String>,
65}
66
67#[derive(Debug, Clone, Deserialize)]
68pub struct PromptConditioningBudget {
69    #[serde(default)]
70    input_tokens: u32,
71    #[serde(default)]
72    output_tokens: u32,
73    #[serde(default)]
74    tool_rounds: u16,
75    #[serde(default)]
76    max_bytes: u32,
77}
78
79/// The compiled+rendered result of one profile against one request.
80/// `plan_id`/`profile_id` are `None` for the no-conditioning legacy path.
81#[derive(Debug, Clone)]
82pub struct PreparedPrompt {
83    pub text: String,
84    pub plan_id: Option<u64>,
85    pub profile_id: Option<String>,
86    pub selected_evidence: usize,
87    pub token_budget: u32,
88}
89
90fn default_schema_version() -> u16 {
91    1
92}
93fn default_requirement_class() -> String {
94    "guidance".into()
95}
96fn default_tools_allowed() -> bool {
97    true
98}
99
100/// Compile and render the semantic profile into the precise prompt consumed by
101/// local inference. The returned receipt makes the applied plan inspectable.
102/// Thin adapter over [`prepare_conditioned_prompt`] — identical semantics to
103/// the shared route-agnostic entry point.
104pub fn prepare_prompt(request: &PoetLlmRequest) -> Result<PreparedPrompt, String> {
105    let Some(raw) = request.conditioning.as_ref() else {
106        return Ok(PreparedPrompt {
107            text: request.prompt.clone(),
108            plan_id: None,
109            profile_id: None,
110            selected_evidence: 0,
111            token_budget: request.max_tokens,
112        });
113    };
114    prepare_conditioned_prompt(
115        raw,
116        &request.prompt,
117        &request.principal_did,
118        &request.graph_context,
119        request.max_tokens,
120    )
121}
122
123/// Route-agnostic preparation: compile the same profile document for any
124/// inference route (HTTP, desktop chat, Ollama, remote MCP). `prompt` is the
125/// raw user request — used as the objective when the profile omits one —
126/// and `graph_context` supplies the fallback allowed-scope hash.
127pub fn prepare_conditioned_prompt(
128    raw: &serde_json::Value,
129    prompt: &str,
130    principal_did: &str,
131    graph_context: &str,
132    max_tokens: u32,
133) -> Result<PreparedPrompt, String> {
134    let profile: PromptConditioning = serde_json::from_value(raw.clone())
135        .map_err(|error| format!("Invalid conditioning profile: {error}"))?;
136    if profile.requirements.len() > MAX_CONDITIONING_REQUIREMENTS
137        || profile.evidence.len() > MAX_CONDITIONING_EVIDENCE
138        || profile.domains.len() > MAX_CONDITIONING_DOMAINS
139        || profile.allowed_graph_scopes.len() > MAX_CONDITIONING_DOMAINS
140    {
141        return Err("Conditioning profile exceeds its bounded request limits".into());
142    }
143    let profile_id = if profile.profile_id.trim().is_empty() {
144        "urn:qualia:profile:request".to_string()
145    } else {
146        profile.profile_id.trim().to_string()
147    };
148    let objective = if profile.objective.trim().is_empty() {
149        prompt
150    } else {
151        profile.objective.trim()
152    };
153    let input_budget = profile.budget.unwrap_or(PromptConditioningBudget {
154        input_tokens: 4096,
155        output_tokens: max_tokens,
156        tool_rounds: 0,
157        max_bytes: MAX_PROMPT_BYTES as u32,
158    });
159    let budget = crate::inference::conditioning::ConditioningBudget {
160        input_tokens: input_budget.input_tokens.max(1),
161        output_tokens: if input_budget.output_tokens == 0 {
162            max_tokens
163        } else {
164            input_budget.output_tokens
165        },
166        tool_rounds: input_budget.tool_rounds,
167        max_bytes: if input_budget.max_bytes == 0 {
168            MAX_PROMPT_BYTES as u32
169        } else {
170            input_budget.max_bytes.min(MAX_PROMPT_BYTES as u32)
171        },
172        thinking_token_budget: None,
173    };
174    let mut requirements = Vec::with_capacity(profile.requirements.len());
175    for requirement in &profile.requirements {
176        let class = match requirement.class.as_str() {
177            "enforced" => crate::inference::conditioning::RequirementClass::Enforced,
178            "evidence_obligation" | "evidence" => {
179                crate::inference::conditioning::RequirementClass::EvidenceObligation
180            }
181            "guidance" => crate::inference::conditioning::RequirementClass::Guidance,
182            other => return Err(format!("Unknown conditioning requirement class: {other}")),
183        };
184        requirements.push(crate::inference::conditioning::RequirementRef {
185            id: requirement.id.trim(),
186            class,
187            rule: requirement.rule.trim(),
188            validator: requirement.validator.as_deref(),
189            required: requirement.required,
190            priority: requirement.priority,
191        });
192    }
193    let domain_refs: Vec<u64> = profile
194        .domains
195        .iter()
196        .map(|domain| crate::q_hash(domain))
197        .collect();
198    let evidence: Vec<crate::inference::conditioning::EvidencePart<'_>> = profile
199        .evidence
200        .iter()
201        .map(|item| crate::inference::conditioning::EvidencePart {
202            source_id: item.source_id.trim(),
203            scope: item.scope,
204            sensitivity: item.sensitivity,
205            content: item.content.trim(),
206            qualifier: item.qualifier.as_deref(),
207        })
208        .collect();
209    let fallback_scope = crate::q_hash(graph_context);
210    let allowed_scopes = if profile.allowed_graph_scopes.is_empty() && !graph_context.is_empty() {
211        std::slice::from_ref(&fallback_scope)
212    } else {
213        profile.allowed_graph_scopes.as_slice()
214    };
215    let authority = crate::inference::conditioning::AuthorityView {
216        principal_did_hash: crate::q_hash(principal_did),
217        disclosure_ceiling: profile.disclosure_ceiling,
218        allowed_graph_scopes: allowed_scopes,
219        tools_allowed: profile.tools_allowed,
220    };
221    let spec = crate::inference::conditioning::ConditioningSpec {
222        schema_version: profile.schema_version,
223        profile_id: &profile_id,
224        objective,
225        requirements: &requirements,
226        domain_refs: &domain_refs,
227        output_contract: crate::inference::conditioning::OutputContractRef {
228            schema_hint: None,
229            min_citations: 0,
230        },
231        budget,
232    };
233    let mut outcomes = [crate::inference::conditioning::RequirementOutcome::applied("");
234        MAX_CONDITIONING_REQUIREMENTS];
235    let mut selected = [crate::inference::conditioning::EvidencePart {
236        source_id: "",
237        scope: 0,
238        sensitivity: 0,
239        content: "",
240        qualifier: None,
241    }; MAX_CONDITIONING_EVIDENCE];
242    let mut buffers = crate::inference::conditioning::CompileBuffers {
243        outcomes: &mut outcomes[..requirements.len()],
244        selected_evidence: &mut selected[..evidence.len()],
245    };
246    let plan = crate::inference::conditioning::compile_into(
247        &spec,
248        &authority,
249        &crate::inference::conditioning::BackendCapabilities::native_gguf_baseline(),
250        &evidence,
251        &mut buffers,
252    )
253    .map_err(|error| format!("Conditioning profile cannot be compiled: {error:?}"))?;
254    let mut rendered = vec![0u8; budget.max_bytes as usize];
255    let rendered_summary = crate::inference::conditioning::render_into(
256        &plan,
257        &spec,
258        &selected[..plan.evidence_count],
259        crate::inference::conditioning::RenderTarget::NativePlain,
260        &mut rendered,
261    )
262    .map_err(|error| format!("Conditioning profile cannot be rendered: {error:?}"))?;
263    let text = std::str::from_utf8(&rendered[..rendered_summary.bytes_written])
264        .map_err(|_| "Conditioning renderer returned invalid UTF-8".to_string())?
265        .to_string();
266    Ok(PreparedPrompt {
267        text,
268        plan_id: Some(plan.plan_id),
269        profile_id: Some(profile_id.clone()),
270        selected_evidence: plan.evidence_count,
271        token_budget: max_tokens.min(budget.output_tokens),
272    })
273}