1use 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#[derive(Clone, Debug, Deserialize)]
32pub struct ClassConfig {
33 pub id: String,
34 pub name: String,
35 #[serde(default)]
36 pub label: Option<String>,
37 #[serde(default)]
39 pub description: Option<String>,
40}
41
42#[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 #[serde(default)]
57 pub fallback_class: Option<String>,
58 #[serde(default)]
60 pub engine: Option<String>,
61 #[serde(default)]
63 pub min_confidence: Option<f64>,
64 #[serde(default)]
66 pub min_probability: Option<f64>,
67 #[serde(default)]
69 pub companion_noul: bool,
70 #[serde(default = "default_companion_threshold")]
72 pub companion_threshold: f64,
73}
74
75fn default_companion_threshold() -> f64 {
76 0.5
77}
78
79#[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 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 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 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 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 branch_handles(&self) -> Option<Vec<String>> {
415 Some(self.config.classes.iter().map(|c| c.id.clone()).collect())
416 }
417
418 fn inputs(&self) -> Vec<Selector> {
419 let cfg = &self.config;
420 let mut out = vec![cfg.query_variable_selector.clone()];
421 if let Some(instruction) = &cfg.instruction {
422 out.extend(instruction.selectors().cloned());
423 }
424 if let Some(memory) = &cfg.memory {
425 out.extend(memory.selectors());
426 }
427 out.extend(cfg.vision.selectors());
428 out.extend(cfg.model.selectors());
429 out
430 }
431}
432
433pub fn factory(doc: &NodeDoc) -> Result<Arc<dyn Node>, ConfigError> {
435 Ok(Arc::new(ClassifierNode::from_doc(doc)?))
436}
437
438#[cfg(test)]
439mod tests {
440 use super::*;
441 use crate::mock::MockModel;
442 use crate::registry::ModelRegistry;
443 use graphrt_core::value::Value;
444 use graphrt_core::{NodeOutcome, Services, VariablePool};
445
446 fn node(extra: Json) -> ClassifierNode {
447 let mut config = serde_json::json!({
448 "model": {"provider": "openai", "name": "gpt"},
449 "query_variable_selector": ["sys", "query"],
450 "classes": [{"id": "1", "name": "billing"}, {"id": "2", "name": "support", "label": "Help"}],
451 });
452 if let (Some(c), Json::Object(e)) = (config.as_object_mut(), extra) {
453 c.extend(e);
454 }
455 ClassifierNode::from_doc(&NodeDoc::new("qc", "question-classifier", config)).unwrap()
456 }
457
458 async fn classify(node: &ClassifierNode, answer: &str) -> NodeResult {
459 let model = Arc::new(MockModel::new(vec![MockModel::text(answer)]));
460 let mut pool = VariablePool::new();
461 pool.insert("sys", "query", Value::from("my card was charged twice"));
462 let ctx = NodeContext::for_test("qc", pool)
463 .with_services(Arc::new(Services::new().with(ModelRegistry::new().with("openai", model))));
464 node.run(ctx).await
465 }
466
467 fn output(r: NodeResult) -> NodeOutput {
468 match r.unwrap() {
469 NodeOutcome::Completed(o) => o,
470 NodeOutcome::Paused(_) => panic!("paused"),
471 }
472 }
473
474 #[tokio::test]
475 async fn routes_by_id_and_name() {
476 let n = node(serde_json::json!({}));
477 let out = output(classify(&n, "```json\n{\"category_id\": \"2\", \"category_name\": \"support\"}\n```").await);
478 assert_eq!(out.branch.as_deref(), Some("2"));
479 assert_eq!(out.outputs["class_label"], Value::from("Help"));
480 let out = output(classify(&n, "{\"category_name\": \"Billing\"}").await);
481 assert_eq!(out.branch.as_deref(), Some("1"));
482 assert_eq!(out.outputs["class_label"], Value::from("CLASS 1"));
483 }
484
485 #[tokio::test]
486 async fn unknown_class_fails_unless_fallback() {
487 let n = node(serde_json::json!({}));
488 let err = classify(&n, "{\"category_id\": \"9\"}").await.unwrap_err();
489 assert_eq!(err.kind, "classification");
490 let n = node(serde_json::json!({"fallback_class": "2"}));
491 let out = output(classify(&n, "gibberish").await);
492 assert_eq!(out.branch.as_deref(), Some("2"));
493 assert_eq!(out.metadata.get("fallback"), Some(&Value::Bool(true)));
494 assert_eq!(out.metadata.get("raw_answer"), Some(&Value::from("gibberish")));
495 let out = output(classify(&n, "{\"category_id\": \"1\"}").await);
496 assert!(!out.metadata.contains_key("fallback"));
497 }
498
499 #[test]
500 fn config_validation() {
501 let bad = NodeDoc::new(
502 "qc",
503 "question-classifier",
504 serde_json::json!({"model": {"provider": "p", "name": "m"}, "query_variable_selector": "sys.query", "classes": []}),
505 );
506 assert!(ClassifierNode::from_doc(&bad).is_err());
507 let bad = NodeDoc::new(
508 "qc",
509 "question-classifier",
510 serde_json::json!({"model": {"provider": "p", "name": "m"}, "query_variable_selector": "sys.query",
511 "classes": [{"id": "a", "name": "x"}], "fallback_class": "zzz"}),
512 );
513 assert!(ClassifierNode::from_doc(&bad).is_err());
514 }
515
516 #[test]
517 fn typesafe_engine_rejects_chat_only_settings() {
518 let doc = |extra: Json| {
519 let mut config = serde_json::json!({
520 "model": {"provider": "typesafe", "name": "jev-latest"},
521 "query_variable_selector": "sys.query",
522 "classes": [{"id": "a", "name": "x"}],
523 });
524 if let (Some(c), Json::Object(e)) = (config.as_object_mut(), extra) {
525 c.extend(e);
526 }
527 NodeDoc::new("qc", "question-classifier", config)
528 };
529 assert!(ClassifierNode::from_doc(&doc(serde_json::json!({}))).is_ok());
530 for bad in [
531 serde_json::json!({"engine": "chat"}),
532 serde_json::json!({"memory": {"window": {"enabled": true, "size": 3}}}),
533 serde_json::json!({"vision": {"enabled": true}}),
534 serde_json::json!({"model": {"provider": "typesafe", "name": "jev", "completion_params": {"temperature": 0}}}),
535 ] {
536 assert!(ClassifierNode::from_doc(&doc(bad.clone())).is_err(), "{bad}");
537 }
538 }
539}