1use std::sync::Arc;
28
29use futures::future::BoxFuture;
30use graphrt_core::dsl::NodeDoc;
31use graphrt_core::file::{DataUrlResolver, FileResolver};
32use graphrt_core::node::{ConfigError, NodeResult, NodeRole, parse_config};
33use graphrt_core::template::{Part, Template};
34use graphrt_core::value::{File, Value};
35use graphrt_core::{Node, NodeContext, NodeError, NodeOutput, Selector, VariablePool};
36use indexmap::IndexMap;
37use serde::Deserialize;
38use serde_json::Value as Json;
39
40use super::common::usage_value;
41use crate::typesafe::{
42 Answer, DEFAULT_MODEL, ImageAsset, NoulCriteria, Question, SystemOneClient, SystemOneRequest, normalize_format,
43};
44
45pub const LOW_CONFIDENCE: &str = "low_confidence";
47
48const MAX_IMAGE_BYTES: u64 = 20 * 1024 * 1024;
50
51#[derive(Clone, Debug, Deserialize)]
53#[serde(untagged)]
54enum ModelSpec {
55 Name(String),
56 Object(ModelObject),
57}
58
59#[derive(Clone, Debug, Deserialize)]
60#[serde(deny_unknown_fields)]
61struct ModelObject {
62 #[serde(default)]
63 provider: Option<String>,
64 name: String,
65}
66
67#[derive(Clone, Debug, Deserialize)]
69#[serde(deny_unknown_fields)]
70pub struct QuestionConfig {
71 #[serde(rename = "type")]
72 pub kind: String,
73 #[serde(default)]
74 pub instructions: Option<Json>,
75 #[serde(default)]
76 pub criteria: Option<Json>,
77}
78
79#[derive(Clone, Debug, Deserialize)]
81#[serde(deny_unknown_fields)]
82pub struct SystemOneNodeConfig {
83 #[serde(default)]
87 pub allow_missing: bool,
88 #[serde(default)]
89 model: Option<ModelSpec>,
90 #[serde(default)]
92 pub state: Option<Json>,
93 #[serde(default)]
95 pub state_selector: Option<Selector>,
96 #[serde(default)]
98 pub images: IndexMap<String, Selector>,
99 pub questions: IndexMap<String, QuestionConfig>,
100 #[serde(default)]
102 pub route_by: Option<String>,
103 #[serde(default)]
104 pub min_confidence: Option<f64>,
105 #[serde(default)]
106 pub min_probability: Option<f64>,
107 #[serde(default)]
109 pub long_context: bool,
110}
111
112#[derive(Debug)]
114pub struct SystemOneNode {
115 config: SystemOneNodeConfig,
116 model: String,
117 handles: Vec<String>,
119}
120
121impl SystemOneNode {
122 pub fn from_doc(doc: &NodeDoc) -> Result<Self, ConfigError> {
123 let config: SystemOneNodeConfig = parse_config(doc)?;
124 let err = |m: String| Err(ConfigError::new(doc, m));
125 if config.questions.is_empty() {
126 return err("questions must not be empty".into());
127 }
128 if config.state.is_some() && config.state_selector.is_some() {
129 return err("set either `state` or `state_selector`, not both".into());
130 }
131 for (name, q) in &config.questions {
132 if name.is_empty() {
133 return err("question names must not be empty".into());
134 }
135 if let Err(message) = build_question(q, None) {
136 return err(format!("question `{name}`: {message}"));
137 }
138 }
139 for (name, value) in [("min_confidence", config.min_confidence), ("min_probability", config.min_probability)] {
140 if let Some(v) = value {
141 if !(0.0..=1.0).contains(&v) {
142 return err(format!("{name} must be between 0 and 1"));
143 }
144 }
145 }
146 let mut handles = Vec::new();
147 match &config.route_by {
148 Some(route) => {
149 let Some(q) = config.questions.get(route) else {
150 return err(format!("route_by `{route}` is not a configured question"));
151 };
152 let Ok(Question::Choice { criteria, .. }) = build_question(q, None) else {
153 return err(format!("route_by `{route}` must name a choice question"));
154 };
155 handles = criteria.keys().cloned().collect();
156 if handles.iter().any(|h| h == LOW_CONFIDENCE) {
157 return err(format!("option name `{LOW_CONFIDENCE}` is reserved for the low-confidence handle"));
158 }
159 }
160 None => {
161 if config.min_confidence.is_some() || config.min_probability.is_some() {
162 return err("min_confidence and min_probability need route_by".into());
163 }
164 }
165 }
166 let model = match &config.model {
167 None => DEFAULT_MODEL.to_owned(),
168 Some(ModelSpec::Name(n)) if n.trim().is_empty() => return err("`model` must not be empty".into()),
169 Some(ModelSpec::Name(n)) => n.trim().to_owned(),
170 Some(ModelSpec::Object(o)) => {
171 if let Some(p) = o.provider.as_deref().filter(|p| *p != "typesafe") {
172 return err(format!("`model.provider` must be `typesafe` for system-one nodes, got `{p}`"));
173 }
174 if o.name.trim().is_empty() {
175 return err("`model.name` must not be empty".into());
176 }
177 o.name.trim().to_owned()
178 }
179 };
180 Ok(Self { config, model, handles })
181 }
182
183 fn has_thresholds(&self) -> bool {
184 self.config.min_confidence.is_some() || self.config.min_probability.is_some()
185 }
186
187 async fn request(&self, ctx: &NodeContext) -> Result<SystemOneRequest, NodeError> {
189 let cfg = &self.config;
190 let pool = &ctx.pool;
191 let mut state = match (&cfg.state_selector, &cfg.state) {
192 (Some(sel), _) => pool
193 .get(sel)
194 .map(|v| v.to_json())
195 .ok_or_else(|| NodeError::invalid_input(format!("state variable `{sel}` is missing")))?,
196 (None, Some(state)) => render_json(state, pool, cfg.allow_missing)
197 .map_err(|m| NodeError::invalid_input(format!("state: {m}")))?,
198 (None, None) => Json::Object(serde_json::Map::new()),
199 };
200
201 let mut request = SystemOneRequest::new(self.model.clone(), Json::Null);
202 request.long_context = cfg.long_context;
203 if !cfg.images.is_empty() {
204 let mut object = match state {
205 Json::Object(map) => map,
206 Json::Null => serde_json::Map::new(),
207 other => {
208 let mut map = serde_json::Map::new();
209 map.insert("text".to_owned(), other);
210 map
211 }
212 };
213 for (name, selector) in &cfg.images {
214 let files = files_at(pool, selector)?;
215 let mut refs = Vec::with_capacity(files.len());
216 for (i, file) in files.iter().enumerate() {
217 let reference = format!("graphrt-image-{}-{name}-{i}", ctx.exec_id);
218 request.assets.insert(reference.clone(), image_asset(ctx, file).await?);
219 refs.push(Json::String(reference));
220 }
221 let value = if refs.len() == 1 { refs.remove(0) } else { Json::Array(refs) };
222 object.insert(name.clone(), value);
223 }
224 state = Json::Object(object);
225 }
226 request.state = state;
227 for (name, q) in &cfg.questions {
228 let question = build_question(q, Some((pool, cfg.allow_missing)))
229 .map_err(|m| NodeError::invalid_input(format!("question `{name}`: {m}")))?;
230 request.questions.insert(name.clone(), question);
231 }
232 Ok(request)
233 }
234
235 async fn execute(&self, ctx: NodeContext) -> NodeResult {
236 let client =
237 ctx.require_service::<Arc<SystemOneClient>>("TypeSafe client (graphrt_llm::typesafe::SystemOneClient)")?;
238 let request = self.request(&ctx).await?;
239 let response = client.ask(&request).await?;
240
241 let usage = response.usage.to_usage();
242 let mut output = NodeOutput::new();
243 let mut all = graphrt_core::value::Map::new();
244 for (name, answer) in &response.answers {
245 if !self.config.questions.contains_key(name) {
246 continue;
247 }
248 let value = serde_json::to_value(answer).map(Value::from_json).unwrap_or(Value::Null);
249 all.insert(name.clone(), value.clone());
250 output = output.with(name.clone(), value);
251 }
252 output = output
253 .with("answers", Value::from(all))
254 .with("usage", usage_value(&usage))
255 .with("model", response.model.as_str())
256 .usage(usage);
257
258 if let Some(route) = &self.config.route_by {
259 let Some(Answer::Choice { choice, confidence, probabilities }) = response.answer(route) else {
260 return Err(NodeError::new("model_decode", format!("no choice answer for routed question `{route}`")));
261 };
262 if !self.handles.iter().any(|h| h == choice) {
263 return Err(NodeError::new("model_decode", format!("System One chose unknown option `{choice}`")));
264 }
265 let probability = probabilities.get(choice).copied().ok_or_else(|| {
266 NodeError::new("model_decode", format!("no probability for the chosen option `{choice}`"))
267 })?;
268 let low = self.config.min_confidence.is_some_and(|m| *confidence < m)
269 || self.config.min_probability.is_some_and(|m| probability < m);
270 if low {
271 output = output.branch(LOW_CONFIDENCE).meta("predicted", choice.as_str());
272 } else {
273 output = output.branch(choice.clone());
274 }
275 }
276 Ok(output.into())
277 }
278}
279
280fn build_question(q: &QuestionConfig, pool: Option<(&VariablePool, bool)>) -> Result<Question, String> {
283 let render = |v: &Json| -> Result<Json, String> {
284 match pool {
285 Some((p, allow_missing)) => render_json(v, p, allow_missing),
286 None => Ok(v.clone()),
287 }
288 };
289 let instructions = q.instructions.as_ref().map(render).transpose()?;
290 match q.kind.as_str() {
291 "choice" => {
292 let criteria = match &q.criteria {
293 Some(Json::Object(map)) => {
294 let mut out = IndexMap::new();
295 for (k, v) in map {
296 out.insert(k.clone(), render(v)?);
297 }
298 out
299 }
300 Some(Json::Array(items)) => {
302 let mut map = IndexMap::new();
303 for item in items {
304 let Some(name) = item.as_str().filter(|s| !s.is_empty()) else {
305 return Err("choice options listed as an array must be non-empty strings".into());
306 };
307 map.insert(name.to_owned(), Json::Null);
308 }
309 map
310 }
311 _ => return Err("choice questions need `criteria` (option -> description)".into()),
312 };
313 if criteria.is_empty() || criteria.len() > crate::typesafe::MAX_CHOICE_OPTIONS {
314 return Err(format!("choice questions need 1 to {} options", crate::typesafe::MAX_CHOICE_OPTIONS));
315 }
316 Ok(Question::Choice { instructions, criteria })
317 }
318 "score" => match &q.criteria {
319 Some(Json::Array(levels)) if !levels.is_empty() && levels.len() <= crate::typesafe::MAX_SCORE_LEVELS => {
320 let criteria = levels.iter().map(render).collect::<Result<Vec<_>, _>>()?;
321 Ok(Question::Score { instructions, criteria })
322 }
323 _ => Err(format!(
324 "score questions need `criteria`: 1 to {} ordered levels",
325 crate::typesafe::MAX_SCORE_LEVELS
326 )),
327 },
328 "noul" => {
329 let criteria = match &q.criteria {
330 None | Some(Json::Null) => None,
331 Some(Json::Object(map)) => {
332 if let Some(key) = map.keys().find(|k| *k != "true" && *k != "false") {
333 return Err(format!("noul `criteria` keys must be `true` / `false`, got `{key}`"));
334 }
335 Some(NoulCriteria {
336 yes: map.get("true").map(render).transpose()?,
337 no: map.get("false").map(render).transpose()?,
338 })
339 }
340 Some(_) => return Err("noul `criteria` must be an object with `true` / `false`".into()),
341 };
342 Ok(Question::Noul { instructions, criteria })
343 }
344 "box" => {
345 if q.criteria.is_some() {
346 return Err("box questions take no criteria".into());
347 }
348 Ok(Question::Box { instructions })
349 }
350 other => Err(format!("unknown question type `{other}` (choice, score, noul or box)")),
351 }
352}
353
354fn render_json(value: &Json, pool: &VariablePool, allow_missing: bool) -> Result<Json, String> {
359 Ok(match value {
360 Json::String(s) => {
361 let template = Template::parse(s);
362 if !allow_missing {
363 if let Some(missing) = template.selectors().find(|sel| pool.get(sel).is_none()) {
364 return Err(format!(
365 "variable `{missing}` is missing (set `allow_missing: true` to send it as null)"
366 ));
367 }
368 }
369 match template.parts() {
370 [Part::Var(sel)] => pool.get(sel).map(|v| v.to_json()).unwrap_or(Json::Null),
371 _ if template.is_static() => value.clone(),
372 _ => Json::String(template.render(pool)),
373 }
374 }
375 Json::Array(items) => {
376 Json::Array(items.iter().map(|v| render_json(v, pool, allow_missing)).collect::<Result<_, _>>()?)
377 }
378 Json::Object(map) => {
379 let mut out = serde_json::Map::new();
380 for (k, v) in map {
381 out.insert(k.clone(), render_json(v, pool, allow_missing)?);
382 }
383 Json::Object(out)
384 }
385 other => other.clone(),
386 })
387}
388
389fn json_selectors(value: &Json, out: &mut Vec<Selector>) {
390 match value {
391 Json::String(s) => out.extend(Template::parse(s).selectors().cloned()),
392 Json::Array(items) => items.iter().for_each(|v| json_selectors(v, out)),
393 Json::Object(map) => map.values().for_each(|v| json_selectors(v, out)),
394 _ => {}
395 }
396}
397
398fn files_at(pool: &VariablePool, selector: &Selector) -> Result<Vec<File>, NodeError> {
400 match pool.get(selector) {
401 Some(Value::File(f)) => Ok(vec![(*f).clone()]),
402 Some(Value::Array(items)) => items
403 .iter()
404 .map(|v| match v {
405 Value::File(f) => Ok((**f).clone()),
406 other => Err(NodeError::invalid_input(format!(
407 "image variable `{selector}` contains a {} instead of a file",
408 other.type_name()
409 ))),
410 })
411 .collect(),
412 Some(other) => Err(NodeError::invalid_input(format!(
413 "image variable `{selector}` is a {}, expected a file",
414 other.type_name()
415 ))),
416 None => Err(NodeError::invalid_input(format!("image variable `{selector}` is missing"))),
417 }
418}
419
420async fn image_asset(ctx: &NodeContext, file: &File) -> Result<ImageAsset, NodeError> {
422 let resolver: Option<&Arc<dyn FileResolver>> = ctx.service::<Arc<dyn FileResolver>>();
423 let read = match resolver {
424 Some(r) => r.read(file, MAX_IMAGE_BYTES).await,
425 None => DataUrlResolver.read(file, MAX_IMAGE_BYTES).await,
426 };
427 let bytes = read.map_err(|e| {
428 let error = NodeError::new("file", e.to_string());
429 if e.is_retryable() { error } else { NodeError::fatal("file", e.to_string()) }
430 })?;
431 let format = bytes
432 .mime_type
433 .as_deref()
434 .and_then(normalize_format)
435 .or_else(|| file.mime_type.as_deref().and_then(normalize_format))
436 .or_else(|| file.extension.as_deref().and_then(normalize_format))
437 .or_else(|| sniff_format(&bytes.bytes))
438 .ok_or_else(|| NodeError::invalid_input(format!("image `{}` must be PNG or JPEG", file.name)))?;
439 ImageAsset::new(format, &bytes.bytes).map_err(NodeError::from)
440}
441
442fn sniff_format(bytes: &[u8]) -> Option<&'static str> {
443 if bytes.starts_with(b"\x89PNG") {
444 Some("png")
445 } else if bytes.starts_with(&[0xFF, 0xD8, 0xFF]) {
446 Some("jpg")
447 } else {
448 None
449 }
450}
451
452impl Node for SystemOneNode {
453 fn role(&self) -> NodeRole {
454 if self.config.route_by.is_some() { NodeRole::Branch } else { NodeRole::Executable }
455 }
456
457 fn run(&self, ctx: NodeContext) -> BoxFuture<'_, NodeResult> {
458 Box::pin(self.execute(ctx))
459 }
460
461 fn inputs(&self) -> Vec<Selector> {
462 let cfg = &self.config;
463 let mut out = Vec::new();
464 if let Some(state) = &cfg.state {
465 json_selectors(state, &mut out);
466 }
467 out.extend(cfg.state_selector.iter().cloned());
468 out.extend(cfg.images.values().cloned());
469 for q in cfg.questions.values() {
470 if let Some(i) = &q.instructions {
471 json_selectors(i, &mut out);
472 }
473 if let Some(c) = &q.criteria {
474 json_selectors(c, &mut out);
475 }
476 }
477 out
478 }
479}
480
481impl SystemOneNode {
482 pub fn handles(&self) -> Vec<String> {
484 let mut handles = self.handles.clone();
485 if self.has_thresholds() {
486 handles.push(LOW_CONFIDENCE.to_owned());
487 }
488 handles
489 }
490}
491
492pub fn factory(doc: &NodeDoc) -> Result<Arc<dyn Node>, ConfigError> {
494 Ok(Arc::new(SystemOneNode::from_doc(doc)?))
495}
496
497#[cfg(test)]
498mod tests {
499 use super::*;
500
501 fn doc(config: Json) -> NodeDoc {
502 NodeDoc::new("s1", "system-one", config)
503 }
504
505 #[test]
506 fn config_validation() {
507 let ok = SystemOneNode::from_doc(&doc(serde_json::json!({
508 "state": "{{#start.text#}}",
509 "questions": {
510 "topic": {"type": "choice", "criteria": {"billing": "Money", "bug": null}},
511 "urgency": {"type": "score", "criteria": ["low", "high"]},
512 "spam": {"type": "noul", "instructions": "Is it spam?", "criteria": {"true": "ads", "false": "real"}}
513 },
514 "route_by": "topic",
515 "min_confidence": 0.5
516 })))
517 .unwrap();
518 assert_eq!(ok.role(), NodeRole::Branch);
519 assert_eq!(ok.handles(), vec!["billing", "bug", LOW_CONFIDENCE]);
520 assert_eq!(ok.model, DEFAULT_MODEL);
521 assert!(ok.inputs().iter().any(|s| s.to_string() == "start.text"));
522
523 for bad in [
524 serde_json::json!({"questions": {}}),
525 serde_json::json!({"questions": {"q": {"type": "choice"}}}),
526 serde_json::json!({"questions": {"q": {"type": "score", "criteria": []}}}),
527 serde_json::json!({"questions": {"q": {"type": "nope"}}}),
528 serde_json::json!({"questions": {"q": {"type": "noul"}}, "route_by": "q"}),
529 serde_json::json!({"questions": {"q": {"type": "noul"}}, "route_by": "missing"}),
530 serde_json::json!({"questions": {"q": {"type": "noul"}}, "min_confidence": 0.5}),
531 serde_json::json!({"questions": {"q": {"type": "choice", "criteria": ["a"]}}, "route_by": "q", "min_confidence": 2}),
532 ] {
533 assert!(SystemOneNode::from_doc(&doc(bad.clone())).is_err(), "{bad}");
534 }
535 }
536
537 #[test]
538 fn renders_templates_typed() {
539 let mut pool = VariablePool::new();
540 pool.insert("n", "obj", Value::from_json(serde_json::json!({"a": 1})));
541 pool.insert("n", "name", Value::from("Ada"));
542 let rendered = render_json(
543 &serde_json::json!({"whole": "{{#n.obj#}}", "text": "hi {{#n.name#}}", "plain": "x", "num": 3}),
544 &pool,
545 false,
546 )
547 .unwrap();
548 assert_eq!(rendered, serde_json::json!({"whole": {"a": 1}, "text": "hi Ada", "plain": "x", "num": 3}));
549 let missing = serde_json::json!({"text": "{{#n.nope#}}"});
551 assert!(render_json(&missing, &pool, false).is_err());
552 assert_eq!(render_json(&missing, &pool, true).unwrap(), serde_json::json!({"text": null}));
553 }
554
555 #[test]
556 fn typos_and_bad_criteria_are_rejected() {
557 for bad in [
558 serde_json::json!({"questions": {"q": {"type": "noul"}}, "min_confidance": 0.5}),
559 serde_json::json!({"questions": {"q": {"type": "noul", "instruction": "x"}}}),
560 serde_json::json!({"questions": {"q": {"type": "noul", "criteria": {"yes": "a", "no": "b"}}}}),
561 serde_json::json!({"model": {"provider": "openai", "name": "jev"}, "questions": {"q": {"type": "noul"}}}),
562 serde_json::json!({"model": {"name": " "}, "questions": {"q": {"type": "noul"}}}),
563 serde_json::json!({"model": "", "questions": {"q": {"type": "noul"}}}),
564 ] {
565 assert!(SystemOneNode::from_doc(&doc(bad.clone())).is_err(), "{bad}");
566 }
567 }
568}