Skip to main content

graphrt_llm/nodes/
classifier.rs

1//! `question-classifier` node: routes to the branch of the class chosen by a model.
2//!
3//! The selected class id is the branch handle. Outputs: `class_id`,
4//! `class_name`, `class_label`, `usage`. An answer that names no configured
5//! class fails the node, unless `fallback_class` names the class to use; a
6//! fallback is marked with metadata `fallback: true` and `raw_answer`.
7//!
8//! With `model.provider: typesafe` (or `engine: typesafe`) the node asks
9//! TypeSafe's System One API one choice question instead of prompting a chat
10//! model. That path adds the `probabilities` (class id -> probability) and
11//! `confidence` outputs and honours `min_confidence`, `min_probability` and the
12//! optional `companion_noul` check; a decision below a threshold routes to
13//! `fallback_class`, or fails with the non-retryable `low_confidence` error.
14
15use std::sync::Arc;
16
17use futures::future::BoxFuture;
18use graphrt_core::dsl::NodeDoc;
19use graphrt_core::node::{ConfigError, NodeResult, NodeRole, parse_config};
20use graphrt_core::template::Template;
21use graphrt_core::{Node, NodeContext, NodeError, NodeOutput, Selector};
22use serde::Deserialize;
23use serde_json::Value as Json;
24
25use super::common::{
26    MemoryConfig, ModelConfig, StreamMode, VisionConfig, extract_json, invoke, model_for, usage_value,
27};
28use crate::types::{ContentPart, Message};
29
30/// One class.
31#[derive(Clone, Debug, Deserialize)]
32pub struct ClassConfig {
33    pub id: String,
34    pub name: String,
35    #[serde(default)]
36    pub label: Option<String>,
37    /// When this class applies (System One engine: used as the option description).
38    #[serde(default)]
39    pub description: Option<String>,
40}
41
42/// Configuration of the `question-classifier` node.
43#[derive(Clone, Debug, Deserialize)]
44pub struct ClassifierConfig {
45    pub model: ModelConfig,
46    #[serde(alias = "query")]
47    pub query_variable_selector: Selector,
48    pub classes: Vec<ClassConfig>,
49    #[serde(default)]
50    pub instruction: Option<Template>,
51    #[serde(default)]
52    pub memory: Option<MemoryConfig>,
53    #[serde(default)]
54    pub vision: VisionConfig,
55    /// Class id used when the model's answer matches no class. Without it, such answers fail the node.
56    #[serde(default)]
57    pub fallback_class: Option<String>,
58    /// `chat` (default) or `typesafe`. `model.provider: typesafe` also selects the System One engine.
59    #[serde(default)]
60    pub engine: Option<String>,
61    /// System One engine: minimum confidence of the decision (0..1).
62    #[serde(default)]
63    pub min_confidence: Option<f64>,
64    /// System One engine: minimum probability of the chosen class (0..1).
65    #[serde(default)]
66    pub min_probability: Option<f64>,
67    /// System One engine: also ask whether any class fits at all (a yes/no question).
68    #[serde(default)]
69    pub companion_noul: bool,
70    /// System One engine: minimum probability of "some class fits" when `companion_noul` is on.
71    #[serde(default = "default_companion_threshold")]
72    pub companion_threshold: f64,
73}
74
75fn default_companion_threshold() -> f64 {
76    0.5
77}
78
79/// The `question-classifier` node.
80#[derive(Debug)]
81pub struct ClassifierNode {
82    config: ClassifierConfig,
83}
84
85impl ClassifierNode {
86    pub fn from_doc(doc: &NodeDoc) -> Result<Self, ConfigError> {
87        let config: ClassifierConfig = parse_config(doc)?;
88        if config.classes.is_empty() {
89            return Err(ConfigError::new(doc, "classes must not be empty"));
90        }
91        let mut seen = std::collections::HashSet::new();
92        for class in &config.classes {
93            if class.id.is_empty() || !seen.insert(class.id.as_str()) {
94                return Err(ConfigError::new(doc, format!("class ids must be unique and non-empty (`{}`)", class.id)));
95            }
96        }
97        if let Some(fallback) = &config.fallback_class {
98            if !config.classes.iter().any(|c| &c.id == fallback) {
99                return Err(ConfigError::new(doc, format!("fallback_class `{fallback}` is not a configured class")));
100            }
101        }
102        match config.engine.as_deref() {
103            None | Some("chat" | "typesafe") => {}
104            Some(other) => {
105                return Err(ConfigError::new(doc, format!("unknown engine `{other}` (expected `chat` or `typesafe`)")));
106            }
107        }
108        for (name, value) in [
109            ("min_confidence", config.min_confidence),
110            ("min_probability", config.min_probability),
111            ("companion_threshold", Some(config.companion_threshold)),
112        ] {
113            if let Some(v) = value {
114                if !(0.0..=1.0).contains(&v) {
115                    return Err(ConfigError::new(doc, format!("{name} must be between 0 and 1")));
116                }
117            }
118        }
119        if config.engine.as_deref() == Some("chat") && config.model.provider == "typesafe" {
120            return Err(ConfigError::new(
121                doc,
122                "`engine: chat` conflicts with `model.provider: typesafe` (TypeSafe is not a chat model)",
123            ));
124        }
125        let node = Self { config };
126        if node.uses_system_one() {
127            if node.config.classes.len() > 255 {
128                return Err(ConfigError::new(doc, "the typesafe engine supports at most 255 classes"));
129            }
130            // Chat-only settings would be silently ignored by the System One engine.
131            let unsupported = [
132                ("memory", node.config.memory.is_some()),
133                ("vision", node.config.vision.enabled),
134                ("model.completion_params", !node.config.model.completion_params.is_empty()),
135            ];
136            if let Some((name, _)) = unsupported.iter().find(|(_, set)| *set) {
137                return Err(ConfigError::new(
138                    doc,
139                    format!("`{name}` is not supported by the typesafe engine (it only applies to chat models)"),
140                ));
141            }
142        } else if node.config.min_confidence.is_some()
143            || node.config.min_probability.is_some()
144            || node.config.companion_noul
145        {
146            return Err(ConfigError::new(
147                doc,
148                "min_confidence, min_probability and companion_noul need the typesafe engine",
149            ));
150        }
151        Ok(node)
152    }
153
154    /// Whether this node uses TypeSafe's System One API instead of a chat model.
155    pub fn uses_system_one(&self) -> bool {
156        self.config.engine.as_deref() == Some("typesafe") || self.config.model.provider == "typesafe"
157    }
158
159    fn system_prompt(&self, instruction: &str) -> String {
160        let categories: Vec<Json> = self
161            .config
162            .classes
163            .iter()
164            .map(|c| serde_json::json!({"category_id": c.id, "category_name": c.name}))
165            .collect();
166        let mut prompt = String::from(
167            "You are a text classification engine. Classify the user's input into exactly one of these categories:\n",
168        );
169        prompt.push_str(&Json::Array(categories).to_string());
170        if !instruction.trim().is_empty() {
171            prompt.push_str("\n\nAdditional instructions:\n");
172            prompt.push_str(instruction.trim());
173        }
174        prompt.push_str(
175            "\n\nRespond only with a JSON object of the form {\"category_id\": \"<id>\", \"category_name\": \"<name>\"}.",
176        );
177        prompt
178    }
179
180    /// Map a model answer to a configured class index.
181    fn match_class(&self, answer: &str) -> Option<usize> {
182        let classes = &self.config.classes;
183        let by_id = |id: &str| classes.iter().position(|c| c.id == id.trim());
184        let by_name = |name: &str| classes.iter().position(|c| c.name.trim().eq_ignore_ascii_case(name.trim()));
185        if let Some(json) = extract_json(answer) {
186            let field = |key: &str| match json.get(key) {
187                Some(Json::String(s)) => Some(s.clone()),
188                Some(Json::Number(n)) => Some(n.to_string()),
189                _ => None,
190            };
191            if let Some(i) = field("category_id").as_deref().and_then(by_id) {
192                return Some(i);
193            }
194            if let Some(i) = field("category_name").as_deref().and_then(by_name) {
195                return Some(i);
196            }
197        }
198        by_id(answer).or_else(|| by_name(answer))
199    }
200
201    async fn execute(&self, ctx: NodeContext) -> NodeResult {
202        if self.uses_system_one() {
203            return self.execute_system_one(ctx).await;
204        }
205        let cfg = &self.config;
206        let pool = &ctx.pool;
207        let query = pool.get(&cfg.query_variable_selector).map(|v| v.to_text()).ok_or_else(|| {
208            NodeError::invalid_input(format!("query variable `{}` is missing", cfg.query_variable_selector))
209        })?;
210        let instruction = cfg.instruction.as_ref().map(|t| t.render(pool)).unwrap_or_default();
211
212        let mut messages = vec![Message::system(self.system_prompt(&instruction))];
213        if let Some(memory) = &cfg.memory {
214            messages.extend(memory.history(pool)?);
215        }
216        let mut user = Message::user(query);
217        user.content
218            .extend(cfg.vision.image_parts(pool)?.into_iter().filter(|p| matches!(p, ContentPart::Image { .. })));
219        messages.push(user);
220
221        let model = model_for(&ctx, &cfg.model)?;
222        let request = cfg.model.request(messages, pool)?;
223        let response = invoke(&ctx, model.as_ref(), request, StreamMode::Off).await?;
224
225        let (index, fallback) = match self.match_class(&response.text) {
226            Some(i) => (i, false),
227            None => match &cfg.fallback_class {
228                Some(fallback) => {
229                    let i = cfg.classes.iter().position(|c| &c.id == fallback).ok_or_else(|| {
230                        NodeError::fatal("classification", format!("fallback class `{fallback}` is not configured"))
231                    })?;
232                    (i, true)
233                }
234                None => {
235                    return Err(NodeError::new(
236                        "classification",
237                        format!("model answer matched no configured class: {}", response.text.trim()),
238                    ));
239                }
240            },
241        };
242        let class =
243            cfg.classes.get(index).ok_or_else(|| NodeError::fatal("classification", "class index out of range"))?;
244        let label = class.label.clone().filter(|l| !l.is_empty()).unwrap_or_else(|| format!("CLASS {}", index + 1));
245        let mut output = NodeOutput::new()
246            .with("class_id", class.id.as_str())
247            .with("class_name", class.name.as_str())
248            .with("class_label", label)
249            .with("usage", usage_value(&response.usage))
250            .usage(response.usage)
251            .branch(class.id.clone());
252        if fallback {
253            output = output.meta("fallback", true).meta("raw_answer", response.text.trim());
254        }
255        Ok(output.into())
256    }
257}
258
259#[cfg(not(feature = "typesafe"))]
260impl ClassifierNode {
261    async fn execute_system_one(&self, _ctx: NodeContext) -> NodeResult {
262        Err(NodeError::fatal("missing_feature", "this build has no TypeSafe support (feature `typesafe`)"))
263    }
264}
265
266#[cfg(feature = "typesafe")]
267impl ClassifierNode {
268    const CHOICE: &'static str = "category";
269    const FITS: &'static str = "fits_any_category";
270
271    /// Build the System One request: one choice question (plus the companion yes/no question).
272    fn system_one_request(&self, query: String, instruction: &str) -> crate::typesafe::SystemOneRequest {
273        use crate::typesafe::{DEFAULT_MODEL, NoulCriteria, Question, SystemOneRequest};
274        let cfg = &self.config;
275        let criteria: indexmap::IndexMap<String, Json> = cfg
276            .classes
277            .iter()
278            .map(|c| {
279                let text = match c.description.as_deref().map(str::trim).filter(|d| !d.is_empty()) {
280                    Some(d) => format!("{}: {d}", c.name),
281                    None => c.name.clone(),
282                };
283                (c.id.clone(), Json::String(text))
284            })
285            .collect();
286        let mut instructions = String::from("Which category does `state` belong to?");
287        if !instruction.trim().is_empty() {
288            instructions.push('\n');
289            instructions.push_str(instruction.trim());
290        }
291        let model = if cfg.model.name.trim().is_empty() { DEFAULT_MODEL } else { cfg.model.name.as_str() };
292        let mut request = SystemOneRequest::new(model, Json::String(query))
293            .question(Self::CHOICE, Question::choice(instructions, criteria));
294        if cfg.companion_noul {
295            let names: Vec<&str> = cfg.classes.iter().map(|c| c.name.as_str()).collect();
296            let statement = format!("`state` clearly fits one of these categories: {}.", names.join(", "));
297            let fits = NoulCriteria {
298                yes: Some(Json::from("The message is about one of the listed categories.")),
299                no: Some(Json::from("The message is about something else, or none of the categories apply.")),
300            };
301            request = request.question(Self::FITS, Question::noul_with(statement, fits));
302        }
303        request
304    }
305
306    async fn execute_system_one(&self, ctx: NodeContext) -> NodeResult {
307        use crate::typesafe::{Answer, SystemOneClient};
308        let cfg = &self.config;
309        let pool = &ctx.pool;
310        let query = pool.get(&cfg.query_variable_selector).map(|v| v.to_text()).ok_or_else(|| {
311            NodeError::invalid_input(format!("query variable `{}` is missing", cfg.query_variable_selector))
312        })?;
313        let instruction = cfg.instruction.as_ref().map(|t| t.render(pool)).unwrap_or_default();
314        let client =
315            ctx.require_service::<Arc<SystemOneClient>>("TypeSafe client (graphrt_llm::typesafe::SystemOneClient)")?;
316        let request = self.system_one_request(query, &instruction);
317        let response = client.ask(&request).await?;
318
319        let Some(Answer::Choice { choice, confidence, probabilities }) = response.answer(Self::CHOICE) else {
320            return Err(NodeError::new("model_decode", "System One returned no choice answer"));
321        };
322        let chosen =
323            cfg.classes.iter().position(|c| &c.id == choice).ok_or_else(|| {
324                NodeError::new("classification", format!("System One chose unknown class `{choice}`"))
325            })?;
326        let probability = probabilities.get(choice).copied().ok_or_else(|| {
327            NodeError::new("model_decode", format!("System One gave no probability for the chosen class `{choice}`"))
328        })?;
329        let fits = match response.answer(Self::FITS) {
330            Some(Answer::Noul { noul }) => Some(*noul),
331            _ => None,
332        };
333
334        let mut reasons: Vec<String> = Vec::new();
335        if let Some(min) = cfg.min_confidence {
336            if *confidence < min {
337                reasons.push(format!("confidence {confidence:.3} < {min}"));
338            }
339        }
340        if let Some(min) = cfg.min_probability {
341            if probability < min {
342                reasons.push(format!("probability {probability:.3} < {min}"));
343            }
344        }
345        if cfg.companion_noul {
346            match fits {
347                Some(p) if p < cfg.companion_threshold => {
348                    reasons.push(format!("fits-any probability {p:.3} < {}", cfg.companion_threshold));
349                }
350                Some(_) => {}
351                None => return Err(NodeError::new("model_decode", "System One returned no companion answer")),
352            }
353        }
354
355        let (index, low_confidence) = if reasons.is_empty() {
356            (chosen, false)
357        } else {
358            match &cfg.fallback_class {
359                Some(fallback) => {
360                    let i = cfg.classes.iter().position(|c| &c.id == fallback).ok_or_else(|| {
361                        NodeError::fatal("classification", format!("fallback class `{fallback}` is not configured"))
362                    })?;
363                    (i, true)
364                }
365                None => {
366                    return Err(NodeError::fatal(
367                        "low_confidence",
368                        format!("classification below threshold: {}", reasons.join(", ")),
369                    ));
370                }
371            }
372        };
373
374        let class =
375            cfg.classes.get(index).ok_or_else(|| NodeError::fatal("classification", "class index out of range"))?;
376        let label = class.label.clone().filter(|l| !l.is_empty()).unwrap_or_else(|| format!("CLASS {}", index + 1));
377        let usage = response.usage.to_usage();
378        let probability_map: graphrt_core::value::Map =
379            probabilities.iter().map(|(k, v)| (k.clone(), graphrt_core::Value::Float(*v))).collect();
380        let mut output = NodeOutput::new()
381            .with("class_id", class.id.as_str())
382            .with("class_name", class.name.as_str())
383            .with("class_label", label)
384            .with("probabilities", graphrt_core::Value::from(probability_map))
385            .with("confidence", *confidence)
386            .with("usage", usage_value(&usage))
387            .usage(usage)
388            .branch(class.id.clone())
389            .meta("engine", "typesafe")
390            .meta("model", response.model.as_str());
391        if let Some(p) = fits {
392            output = output.meta("fits_any_probability", p);
393        }
394        if low_confidence {
395            output = output
396                .meta("fallback", true)
397                .meta("low_confidence", true)
398                .meta("predicted_class", choice.as_str())
399                .meta("reasons", reasons.join(", "));
400        }
401        Ok(output.into())
402    }
403}
404
405impl Node for ClassifierNode {
406    fn role(&self) -> NodeRole {
407        NodeRole::Branch
408    }
409
410    fn run(&self, ctx: NodeContext) -> BoxFuture<'_, NodeResult> {
411        Box::pin(self.execute(ctx))
412    }
413
414    fn inputs(&self) -> Vec<Selector> {
415        let cfg = &self.config;
416        let mut out = vec![cfg.query_variable_selector.clone()];
417        if let Some(instruction) = &cfg.instruction {
418            out.extend(instruction.selectors().cloned());
419        }
420        if let Some(memory) = &cfg.memory {
421            out.extend(memory.selectors());
422        }
423        out.extend(cfg.vision.selectors());
424        out.extend(cfg.model.selectors());
425        out
426    }
427}
428
429/// Factory for the node registry.
430pub fn factory(doc: &NodeDoc) -> Result<Arc<dyn Node>, ConfigError> {
431    Ok(Arc::new(ClassifierNode::from_doc(doc)?))
432}
433
434#[cfg(test)]
435mod tests {
436    use super::*;
437    use crate::mock::MockModel;
438    use crate::registry::ModelRegistry;
439    use graphrt_core::value::Value;
440    use graphrt_core::{NodeOutcome, Services, VariablePool};
441
442    fn node(extra: Json) -> ClassifierNode {
443        let mut config = serde_json::json!({
444            "model": {"provider": "openai", "name": "gpt"},
445            "query_variable_selector": ["sys", "query"],
446            "classes": [{"id": "1", "name": "billing"}, {"id": "2", "name": "support", "label": "Help"}],
447        });
448        if let (Some(c), Json::Object(e)) = (config.as_object_mut(), extra) {
449            c.extend(e);
450        }
451        ClassifierNode::from_doc(&NodeDoc::new("qc", "question-classifier", config)).unwrap()
452    }
453
454    async fn classify(node: &ClassifierNode, answer: &str) -> NodeResult {
455        let model = Arc::new(MockModel::new(vec![MockModel::text(answer)]));
456        let mut pool = VariablePool::new();
457        pool.insert("sys", "query", Value::from("my card was charged twice"));
458        let ctx = NodeContext::for_test("qc", pool)
459            .with_services(Arc::new(Services::new().with(ModelRegistry::new().with("openai", model))));
460        node.run(ctx).await
461    }
462
463    fn output(r: NodeResult) -> NodeOutput {
464        match r.unwrap() {
465            NodeOutcome::Completed(o) => o,
466            NodeOutcome::Paused(_) => panic!("paused"),
467        }
468    }
469
470    #[tokio::test]
471    async fn routes_by_id_and_name() {
472        let n = node(serde_json::json!({}));
473        let out = output(classify(&n, "```json\n{\"category_id\": \"2\", \"category_name\": \"support\"}\n```").await);
474        assert_eq!(out.branch.as_deref(), Some("2"));
475        assert_eq!(out.outputs["class_label"], Value::from("Help"));
476        let out = output(classify(&n, "{\"category_name\": \"Billing\"}").await);
477        assert_eq!(out.branch.as_deref(), Some("1"));
478        assert_eq!(out.outputs["class_label"], Value::from("CLASS 1"));
479    }
480
481    #[tokio::test]
482    async fn unknown_class_fails_unless_fallback() {
483        let n = node(serde_json::json!({}));
484        let err = classify(&n, "{\"category_id\": \"9\"}").await.unwrap_err();
485        assert_eq!(err.kind, "classification");
486        let n = node(serde_json::json!({"fallback_class": "2"}));
487        let out = output(classify(&n, "gibberish").await);
488        assert_eq!(out.branch.as_deref(), Some("2"));
489        assert_eq!(out.metadata.get("fallback"), Some(&Value::Bool(true)));
490        assert_eq!(out.metadata.get("raw_answer"), Some(&Value::from("gibberish")));
491        let out = output(classify(&n, "{\"category_id\": \"1\"}").await);
492        assert!(!out.metadata.contains_key("fallback"));
493    }
494
495    #[test]
496    fn config_validation() {
497        let bad = NodeDoc::new(
498            "qc",
499            "question-classifier",
500            serde_json::json!({"model": {"provider": "p", "name": "m"}, "query_variable_selector": "sys.query", "classes": []}),
501        );
502        assert!(ClassifierNode::from_doc(&bad).is_err());
503        let bad = NodeDoc::new(
504            "qc",
505            "question-classifier",
506            serde_json::json!({"model": {"provider": "p", "name": "m"}, "query_variable_selector": "sys.query",
507                "classes": [{"id": "a", "name": "x"}], "fallback_class": "zzz"}),
508        );
509        assert!(ClassifierNode::from_doc(&bad).is_err());
510    }
511
512    #[test]
513    fn typesafe_engine_rejects_chat_only_settings() {
514        let doc = |extra: Json| {
515            let mut config = serde_json::json!({
516                "model": {"provider": "typesafe", "name": "jev-latest"},
517                "query_variable_selector": "sys.query",
518                "classes": [{"id": "a", "name": "x"}],
519            });
520            if let (Some(c), Json::Object(e)) = (config.as_object_mut(), extra) {
521                c.extend(e);
522            }
523            NodeDoc::new("qc", "question-classifier", config)
524        };
525        assert!(ClassifierNode::from_doc(&doc(serde_json::json!({}))).is_ok());
526        for bad in [
527            serde_json::json!({"engine": "chat"}),
528            serde_json::json!({"memory": {"window": {"enabled": true, "size": 3}}}),
529            serde_json::json!({"vision": {"enabled": true}}),
530            serde_json::json!({"model": {"provider": "typesafe", "name": "jev", "completion_params": {"temperature": 0}}}),
531        ] {
532            assert!(ClassifierNode::from_doc(&doc(bad.clone())).is_err(), "{bad}");
533        }
534    }
535}