Skip to main content

graphrt_llm/nodes/
system_one.rs

1//! `system-one` node: asks TypeSafe's System One API typed questions about a state.
2//!
3//! ```yaml
4//! - id: triage
5//!   type: system-one
6//!   model: jev-latest
7//!   state: "{{#start.message#}}"
8//!   questions:
9//!     topic:   { type: choice, instructions: "What is the message about?",
10//!                criteria: { billing: "Payments, refunds, invoices", bug: "Something is broken" } }
11//!     urgency: { type: score, instructions: "How urgent is it?",
12//!                criteria: ["Can wait", "This week", "Today"] }
13//!     spam:    { type: noul, instructions: "Is this message spam?" }
14//!   route_by: topic          # optional: branch on the `topic` choice
15//!   min_confidence: 0.6      # optional: below it, take the `low_confidence` handle
16//! ```
17//!
18//! Every string in `state`, `instructions` and `criteria` is a template; a string
19//! that is exactly one `{{#..#}}` placeholder is replaced by the typed value.
20//! `images` maps names to file variables; each image is attached as an asset and
21//! referenced from `state` under its name, so questions can say "`photo`".
22//!
23//! Outputs: one object per question (the typed answer), `answers` (all of them),
24//! `usage` and `model`. With `route_by`, the node is a branch node whose handles
25//! are the routed question's options, plus `low_confidence` when a threshold is set.
26
27use 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
45/// Handle taken when a routed decision falls below `min_confidence` / `min_probability`.
46pub const LOW_CONFIDENCE: &str = "low_confidence";
47
48/// Largest image read from a file variable.
49const MAX_IMAGE_BYTES: u64 = 20 * 1024 * 1024;
50
51/// `model` as a plain name or a `{provider, name}` object.
52#[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/// One configured question.
68#[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/// Configuration of the `system-one` node.
80#[derive(Clone, Debug, Deserialize)]
81#[serde(deny_unknown_fields)]
82pub struct SystemOneNodeConfig {
83    /// Allow placeholders that refer to missing variables (they become `null`).
84    /// Off by default: asking questions about missing input yields confident
85    /// answers about nothing.
86    #[serde(default)]
87    pub allow_missing: bool,
88    #[serde(default)]
89    model: Option<ModelSpec>,
90    /// The content questions refer to (string, object or array; strings are templates).
91    #[serde(default)]
92    pub state: Option<Json>,
93    /// Alternatively, take the state from a variable.
94    #[serde(default)]
95    pub state_selector: Option<Selector>,
96    /// Image variables (file or array of files), keyed by the name used in `state`.
97    #[serde(default)]
98    pub images: IndexMap<String, Selector>,
99    pub questions: IndexMap<String, QuestionConfig>,
100    /// Name of a choice question to branch on.
101    #[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    /// Send the long-context header (262k-token limits; slower).
108    #[serde(default)]
109    pub long_context: bool,
110}
111
112/// The `system-one` node.
113#[derive(Debug)]
114pub struct SystemOneNode {
115    config: SystemOneNodeConfig,
116    model: String,
117    /// Routed question's option names (branch handles), when `route_by` is set.
118    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    /// Build the request: render templates, resolve images.
188    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
280/// Convert a question config to a typed question. With a pool, templates are rendered;
281/// without one, only the shape is validated.
282fn 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                // A list of option names: each option is interpreted by its name alone.
301                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
354/// Render every string in a JSON value as a template. A string that is exactly one
355/// placeholder becomes the typed value; secrets stay masked.
356///
357/// A placeholder whose variable is missing is an error unless `allow_missing`.
358fn 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
398/// Files referenced by an image variable.
399fn 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
420/// Read an image file and turn it into an asset (png or jpg).
421async 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    /// Branch handles (routed options, plus `low_confidence` when thresholds are set).
483    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
492/// Factory for the node registry.
493pub 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        // Missing variables are errors unless explicitly allowed.
550        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}