Skip to main content

qualia_core_db/agent_runtime/
planner.rs

1//! Symbolic agent planner.
2//!
3//! Given a task description and a set of available capabilities, produces a
4//! DAG plan by matching task verbs to capability names. This is a
5//! deterministic, rule-based planner — no LLM inference is used.
6//!
7//! The planner recognises a fixed set of task verbs (research, analyse,
8//! synthesise, verify, report) and maps them to capability patterns. Each
9//! planned node carries an effect label and a budget derived from the task
10//! complexity heuristic.
11
12use std::collections::BTreeMap;
13
14/// A single planned step in the agent plan.
15#[derive(Debug, Clone, PartialEq)]
16pub struct PlannedStep {
17    /// Node ID within the plan DAG.
18    pub id: u32,
19    /// Human-readable step name.
20    pub name: String,
21    /// Capability invoke-ID this step will call.
22    pub capability: String,
23    /// Effect class: "pure", "hot", "cold", "async", or "external".
24    pub effect: &'static str,
25    /// Token/cycle budget for this step.
26    pub budget: u32,
27    /// Input channel names this step consumes.
28    pub inputs: Vec<String>,
29    /// Output channel names this step produces.
30    pub outputs: Vec<String>,
31    /// IDs of steps this step depends on.
32    pub depends_on: Vec<u32>,
33}
34
35/// A complete agent plan — a topologically-ordered sequence of steps.
36#[derive(Debug, Clone, PartialEq)]
37pub struct AgentPlan {
38    pub steps: Vec<PlannedStep>,
39    pub task: String,
40    pub total_budget: u32,
41}
42
43/// Task verb recognised by the planner.
44#[derive(Debug, Clone, Copy, PartialEq, Eq)]
45pub enum TaskVerb {
46    Research,
47    Analyse,
48    Synthesise,
49    Verify,
50    Report,
51}
52
53impl TaskVerb {
54    /// Classify a task description's primary verb.
55    pub fn classify(task: &str) -> Option<TaskVerb> {
56        let lower = task.to_ascii_lowercase();
57        if lower.contains("research") || lower.contains("investigate") || lower.contains("explore")
58        {
59            Some(TaskVerb::Research)
60        } else if lower.contains("analy") || lower.contains("exam") || lower.contains("inspect") {
61            Some(TaskVerb::Analyse)
62        } else if lower.contains("synth") || lower.contains("compos") || lower.contains("creat") {
63            Some(TaskVerb::Synthesise)
64        } else if lower.contains("verif") || lower.contains("valid") || lower.contains("check") {
65            Some(TaskVerb::Verify)
66        } else if lower.contains("report") || lower.contains("summary") || lower.contains("output")
67        {
68            Some(TaskVerb::Report)
69        } else {
70            None
71        }
72    }
73}
74
75/// Match a capability name from the available set for a given verb.
76fn match_capability(verb: TaskVerb, available: &[String]) -> Option<String> {
77    let patterns: &[&str] = match verb {
78        TaskVerb::Research => &[
79            "NLP.substrate_extract",
80            "NLP.graphrag_query",
81            "GraphReasoning",
82        ],
83        TaskVerb::Analyse => &["NLP.analyze", "NLP.frame_extract", "NLP.relation_extract"],
84        TaskVerb::Synthesise => &["NLP.coref_resolve", "NLP.fst_lookup"],
85        TaskVerb::Verify => &[
86            "Inference.verify_turn",
87            "Inference.grounding",
88            "Sentinel.gate",
89        ],
90        TaskVerb::Report => &["Asset.create", "Render.scene", "Scene.create"],
91    };
92    for pat in patterns {
93        for cap in available {
94            if cap.starts_with(*pat) || cap == *pat {
95                return Some(cap.clone());
96            }
97        }
98    }
99    // Fallback: if no specific match, use the first available capability.
100    available.first().cloned()
101}
102
103/// Heuristic budget based on task length and verb complexity.
104fn budget_for(verb: TaskVerb, task: &str) -> u32 {
105    let base = match verb {
106        TaskVerb::Research => 500,
107        TaskVerb::Analyse => 300,
108        TaskVerb::Synthesise => 400,
109        TaskVerb::Verify => 200,
110        TaskVerb::Report => 150,
111    };
112    // Add 1 token per 10 chars of task description, capped at 200.
113    let length_bonus = (task.len() / 10).min(200) as u32;
114    base + length_bonus
115}
116
117/// Plan an agent task given a task description and available capabilities.
118///
119/// Produces a DAG of planned steps. The plan always starts with a research/
120/// analysis step (if capabilities allow), followed by synthesis, verification,
121/// and reporting steps as capabilities permit.
122pub fn plan_task(task: &str, capabilities: &[String]) -> AgentPlan {
123    let primary_verb = TaskVerb::classify(task).unwrap_or(TaskVerb::Research);
124    let mut steps = Vec::new();
125    let mut id = 0u32;
126    let mut total_budget = 0u32;
127
128    // Build a pipeline: research → analyse → synthesise → verify → report
129    let pipeline_verbs = match primary_verb {
130        TaskVerb::Research => vec![TaskVerb::Research, TaskVerb::Analyse, TaskVerb::Report],
131        TaskVerb::Analyse => vec![TaskVerb::Analyse, TaskVerb::Report],
132        TaskVerb::Synthesise => vec![TaskVerb::Research, TaskVerb::Synthesise, TaskVerb::Report],
133        TaskVerb::Verify => vec![TaskVerb::Verify, TaskVerb::Report],
134        TaskVerb::Report => vec![TaskVerb::Report],
135    };
136
137    let mut prev_output: Option<(u32, String)> = None;
138
139    for (i, verb) in pipeline_verbs.iter().enumerate() {
140        if let Some(cap) = match_capability(*verb, capabilities) {
141            let step_name = format!("{verb:?}_step_{i}").to_lowercase();
142            let budget = budget_for(*verb, task);
143            let output_channel = format!("{step_name}_out");
144
145            let inputs = if let Some((_, ref prev_ch)) = prev_output {
146                vec![prev_ch.clone()]
147            } else {
148                vec![]
149            };
150
151            let depends_on = if let Some((prev_id, _)) = prev_output {
152                vec![prev_id]
153            } else {
154                vec![]
155            };
156
157            let effect = match verb {
158                TaskVerb::Research | TaskVerb::Analyse => "cold",
159                TaskVerb::Synthesise => "hot",
160                TaskVerb::Verify => "pure",
161                TaskVerb::Report => "cold",
162            };
163
164            steps.push(PlannedStep {
165                id,
166                name: step_name.clone(),
167                capability: cap,
168                effect,
169                budget,
170                inputs,
171                outputs: vec![output_channel.clone()],
172                depends_on,
173            });
174
175            total_budget += budget;
176            prev_output = Some((id, output_channel));
177            id += 1;
178        }
179    }
180
181    // If no steps were planned (no capabilities matched), create a minimal
182    // noop step so the plan is never empty.
183    if steps.is_empty() {
184        steps.push(PlannedStep {
185            id: 0,
186            name: "noop".into(),
187            capability: "noop".into(),
188            effect: "pure",
189            budget: 10,
190            inputs: vec![],
191            outputs: vec!["noop_out".into()],
192            depends_on: vec![],
193        });
194        total_budget = 10;
195    }
196
197    AgentPlan {
198        steps,
199        task: task.to_string(),
200        total_budget,
201    }
202}
203
204/// Convert a plan to a VibeScript-compatible record value map.
205pub fn plan_to_record_map(plan: &AgentPlan) -> BTreeMap<String, BTreeMap<String, String>> {
206    let mut map = BTreeMap::new();
207    for step in &plan.steps {
208        let mut rec = BTreeMap::new();
209        rec.insert("capability".into(), step.capability.clone());
210        rec.insert("effect".into(), step.effect.to_string());
211        rec.insert("budget".into(), step.budget.to_string());
212        rec.insert("inputs".into(), step.inputs.join(","));
213        rec.insert("outputs".into(), step.outputs.join(","));
214        rec.insert(
215            "depends_on".into(),
216            step.depends_on
217                .iter()
218                .map(|d| d.to_string())
219                .collect::<Vec<_>>()
220                .join(","),
221        );
222        map.insert(step.name.clone(), rec);
223    }
224    map
225}
226
227#[cfg(test)]
228mod tests {
229    use super::*;
230
231    #[test]
232    fn classify_research() {
233        assert_eq!(
234            TaskVerb::classify("research the topic"),
235            Some(TaskVerb::Research)
236        );
237        assert_eq!(
238            TaskVerb::classify("investigate the claim"),
239            Some(TaskVerb::Research)
240        );
241    }
242
243    #[test]
244    fn classify_analyse() {
245        assert_eq!(
246            TaskVerb::classify("analyse the data"),
247            Some(TaskVerb::Analyse)
248        );
249        assert_eq!(
250            TaskVerb::classify("examine the results"),
251            Some(TaskVerb::Analyse)
252        );
253    }
254
255    #[test]
256    fn classify_verify() {
257        assert_eq!(
258            TaskVerb::classify("verify the output"),
259            Some(TaskVerb::Verify)
260        );
261        assert_eq!(
262            TaskVerb::classify("validate the claim"),
263            Some(TaskVerb::Verify)
264        );
265    }
266
267    #[test]
268    fn classify_unknown() {
269        assert_eq!(TaskVerb::classify("do something"), None);
270    }
271
272    #[test]
273    fn plan_research_task() {
274        let caps = vec![
275            "NLP.substrate_extract".into(),
276            "NLP.analyze".into(),
277            "Asset.create".into(),
278        ];
279        let plan = plan_task("research the topic and report", &caps);
280        assert!(!plan.steps.is_empty());
281        assert!(plan.total_budget > 0);
282        // Research task should have at least 2 steps (research + report)
283        assert!(plan.steps.len() >= 2);
284    }
285
286    #[test]
287    fn plan_with_matching_capabilities() {
288        let caps = vec![
289            "NLP.analyze".into(),
290            "Inference.verify_turn".into(),
291            "Asset.create".into(),
292        ];
293        let plan = plan_task("analyse the data and verify", &caps);
294        assert!(!plan.steps.is_empty());
295        // Each step should have a non-empty capability
296        for step in &plan.steps {
297            assert!(!step.capability.is_empty());
298        }
299    }
300
301    #[test]
302    fn plan_with_no_matching_capabilities() {
303        let caps: Vec<String> = vec![];
304        let plan = plan_task("unknown task", &caps);
305        // Should produce a noop step
306        assert_eq!(plan.steps.len(), 1);
307        assert_eq!(plan.steps[0].name, "noop");
308    }
309
310    #[test]
311    fn plan_dag_has_topological_order() {
312        let caps = vec![
313            "NLP.substrate_extract".into(),
314            "NLP.analyze".into(),
315            "Asset.create".into(),
316        ];
317        let plan = plan_task("research and report", &caps);
318        // Each step's depends_on should only reference earlier step IDs
319        for (i, step) in plan.steps.iter().enumerate() {
320            for dep in &step.depends_on {
321                assert!(*dep < step.id, "step {i} depends on future step {dep}");
322            }
323            assert_eq!(step.id, i as u32);
324        }
325    }
326
327    #[test]
328    fn plan_budget_scales_with_task_length() {
329        let caps = vec!["NLP.analyze".into()];
330        let short = plan_task("analyse", &caps);
331        let long = plan_task(&"analyse ".repeat(100), &caps);
332        assert!(long.total_budget >= short.total_budget);
333    }
334
335    #[test]
336    fn plan_to_record_map_roundtrip() {
337        let caps = vec!["NLP.analyze".into()];
338        let plan = plan_task("analyse the data", &caps);
339        let map = plan_to_record_map(&plan);
340        assert!(!map.is_empty());
341        for (_, rec) in &map {
342            assert!(rec.contains_key("capability"));
343            assert!(rec.contains_key("budget"));
344        }
345    }
346}