Skip to main content

graphrt_llm/nodes/
extractor.rs

1//! `parameter-extractor` node: extracts typed parameters from text with a model.
2//!
3//! Each declared parameter becomes an output. Values are validated and coerced
4//! to their declared type. Validation problems do not fail the node: they set
5//! `__is_success` to 0 and explain the problem in `__reason`, so a graph can
6//! branch on them. This includes malformed function-call arguments, which are
7//! never treated as an empty (successful) result. Model invocation errors fail
8//! the node.
9
10use std::sync::Arc;
11
12use futures::future::BoxFuture;
13use graphrt_core::dsl::NodeDoc;
14use graphrt_core::node::{ConfigError, NodeResult, parse_config};
15use graphrt_core::template::Template;
16use graphrt_core::tool::ToolSpec;
17use graphrt_core::value::Value;
18use graphrt_core::{Node, NodeContext, NodeError, NodeOutput, Selector};
19use serde::Deserialize;
20use serde_json::{Map, Value as Json, json};
21
22use super::common::{
23    MemoryConfig, ModelConfig, StreamMode, VisionConfig, extract_json_where, invoke, model_for, usage_value,
24};
25use crate::types::{Message, ToolChoice};
26
27/// Name of the synthetic function used in function-call mode.
28pub const EXTRACT_TOOL: &str = "extract_parameters";
29
30/// Declared parameter type.
31#[derive(Clone, Copy, Debug, PartialEq, Eq, Deserialize)]
32#[non_exhaustive]
33pub enum ParamType {
34    #[serde(rename = "string")]
35    String,
36    #[serde(rename = "number")]
37    Number,
38    #[serde(rename = "boolean", alias = "bool")]
39    Boolean,
40    #[serde(rename = "object")]
41    Object,
42    #[serde(rename = "select")]
43    Select,
44    #[serde(rename = "array[string]")]
45    ArrayString,
46    #[serde(rename = "array[number]")]
47    ArrayNumber,
48    #[serde(rename = "array[boolean]")]
49    ArrayBoolean,
50    #[serde(rename = "array[object]")]
51    ArrayObject,
52}
53
54impl ParamType {
55    fn element(self) -> Option<ParamType> {
56        match self {
57            ParamType::ArrayString => Some(ParamType::String),
58            ParamType::ArrayNumber => Some(ParamType::Number),
59            ParamType::ArrayBoolean => Some(ParamType::Boolean),
60            ParamType::ArrayObject => Some(ParamType::Object),
61            _ => None,
62        }
63    }
64
65    fn json_type(self) -> &'static str {
66        match self {
67            ParamType::String | ParamType::Select => "string",
68            ParamType::Number => "number",
69            ParamType::Boolean => "boolean",
70            ParamType::Object => "object",
71            _ => "array",
72        }
73    }
74}
75
76/// One parameter to extract.
77#[derive(Clone, Debug, Deserialize)]
78pub struct ParamConfig {
79    pub name: String,
80    #[serde(rename = "type")]
81    pub ty: ParamType,
82    #[serde(default)]
83    pub description: String,
84    #[serde(default)]
85    pub required: bool,
86    #[serde(default)]
87    pub options: Vec<String>,
88}
89
90/// How the model is asked to answer.
91#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Deserialize)]
92#[serde(rename_all = "snake_case")]
93pub enum ReasoningMode {
94    /// A forced function call whose schema is the parameter list.
95    #[default]
96    FunctionCall,
97    /// A JSON answer requested in the prompt.
98    Prompt,
99}
100
101/// Configuration of the `parameter-extractor` node.
102#[derive(Clone, Debug, Deserialize)]
103pub struct ExtractorConfig {
104    pub model: ModelConfig,
105    pub query: Selector,
106    pub parameters: Vec<ParamConfig>,
107    #[serde(default)]
108    pub instruction: Option<Template>,
109    #[serde(default)]
110    pub reasoning_mode: ReasoningMode,
111    #[serde(default)]
112    pub memory: Option<MemoryConfig>,
113    #[serde(default)]
114    pub vision: VisionConfig,
115}
116
117/// The `parameter-extractor` node.
118#[derive(Debug)]
119pub struct ExtractorNode {
120    config: ExtractorConfig,
121    schema: Json,
122}
123
124const RESERVED: &[&str] = &["__is_success", "__reason", "__usage", "usage"];
125
126impl ExtractorNode {
127    pub fn from_doc(doc: &NodeDoc) -> Result<Self, ConfigError> {
128        let config: ExtractorConfig = parse_config(doc)?;
129        if config.parameters.is_empty() {
130            return Err(ConfigError::new(doc, "parameters must not be empty"));
131        }
132        let mut seen = std::collections::HashSet::new();
133        for p in &config.parameters {
134            if p.name.is_empty() || RESERVED.contains(&p.name.as_str()) || !seen.insert(p.name.as_str()) {
135                return Err(ConfigError::new(doc, format!("invalid or duplicate parameter name `{}`", p.name)));
136            }
137        }
138        let schema = parameters_schema(&config.parameters);
139        Ok(Self { config, schema })
140    }
141
142    async fn execute(&self, ctx: NodeContext) -> NodeResult {
143        let cfg = &self.config;
144        let pool = &ctx.pool;
145        let query = pool
146            .get(&cfg.query)
147            .map(|v| v.to_text())
148            .ok_or_else(|| NodeError::invalid_input(format!("query variable `{}` is missing", cfg.query)))?;
149        let instruction = cfg.instruction.as_ref().map(|t| t.render(pool)).unwrap_or_default();
150
151        let mut system = match cfg.reasoning_mode {
152            ReasoningMode::FunctionCall => {
153                format!(
154                    "Extract the requested parameters from the user's input by calling the `{EXTRACT_TOOL}` function."
155                )
156            }
157            ReasoningMode::Prompt => format!(
158                "Extract the requested parameters from the user's input. Respond only with a JSON object matching this JSON Schema:\n{}",
159                self.schema
160            ),
161        };
162        system.push_str(" Omit parameters that are not present in the input; never invent values.");
163        if !instruction.trim().is_empty() {
164            system.push_str("\n\nAdditional instructions:\n");
165            system.push_str(instruction.trim());
166        }
167        let mut messages = vec![Message::system(system)];
168        if let Some(memory) = &cfg.memory {
169            messages.extend(memory.history(pool)?);
170        }
171        let mut user = Message::user(query);
172        user.content.extend(cfg.vision.image_parts(pool)?);
173        messages.push(user);
174
175        let mut request = cfg.model.request(messages, pool)?;
176        if cfg.reasoning_mode == ReasoningMode::FunctionCall {
177            request.tools = vec![ToolSpec {
178                name: EXTRACT_TOOL.to_owned(),
179                description: "Record the parameters extracted from the user's input.".to_owned(),
180                parameters: self.schema.clone(),
181            }];
182            request.tool_choice = Some(ToolChoice::Tool(EXTRACT_TOOL.to_owned()));
183        }
184
185        let model = model_for(&ctx, &cfg.model)?;
186        let response = invoke(&ctx, model.as_ref(), request, StreamMode::Off).await?;
187        let raw: Result<Map<String, Json>, String> = match response.tool_calls.iter().find(|c| c.name == EXTRACT_TOOL) {
188            Some(call) => call.arguments_json().map_err(|e| format!("model returned invalid function arguments: {e}")),
189            None => match extract_json_where(&response.text, Json::is_object) {
190                Some(Json::Object(values)) => Ok(values),
191                _ => Err("model did not return a JSON object of parameters".to_owned()),
192            },
193        };
194
195        let mut output = NodeOutput::new();
196        let mut problems: Vec<String> = Vec::new();
197        match raw {
198            Ok(values) => {
199                for p in &cfg.parameters {
200                    let value = match values.get(&p.name).filter(|v| !v.is_null()) {
201                        None if p.required => {
202                            problems.push(format!("missing required parameter `{}`", p.name));
203                            Value::Null
204                        }
205                        None => Value::Null,
206                        Some(v) => match coerce(p, v) {
207                            Ok(v) => v,
208                            Err(e) => {
209                                problems.push(format!("parameter `{}`: {e}", p.name));
210                                Value::Null
211                            }
212                        },
213                    };
214                    output.outputs.insert(p.name.clone(), value);
215                }
216            }
217            Err(problem) => {
218                problems.push(problem);
219                for p in &cfg.parameters {
220                    output.outputs.insert(p.name.clone(), Value::Null);
221                }
222            }
223        }
224        let usage = usage_value(&response.usage);
225        Ok(output
226            .with("__is_success", i64::from(problems.is_empty()))
227            .with("__reason", problems.join("; "))
228            .with("__usage", usage.clone())
229            .with("usage", usage)
230            .usage(response.usage)
231            .into())
232    }
233}
234
235/// JSON Schema object describing all parameters.
236fn parameters_schema(params: &[ParamConfig]) -> Json {
237    let mut properties = Map::new();
238    let mut required = Vec::new();
239    for p in params {
240        let mut prop = Map::new();
241        prop.insert("type".into(), json!(p.ty.json_type()));
242        if let Some(elem) = p.ty.element() {
243            prop.insert("items".into(), json!({"type": elem.json_type()}));
244        }
245        if p.ty == ParamType::Select && !p.options.is_empty() {
246            prop.insert("enum".into(), json!(p.options));
247        }
248        if !p.description.is_empty() {
249            prop.insert("description".into(), json!(p.description));
250        }
251        properties.insert(p.name.clone(), Json::Object(prop));
252        if p.required {
253            required.push(json!(p.name));
254        }
255    }
256    json!({"type": "object", "properties": properties, "required": required})
257}
258
259fn coerce_scalar(ty: ParamType, options: &[String], v: &Json) -> Result<Value, String> {
260    match (ty, v) {
261        (ParamType::String, Json::String(_)) => Ok(Value::from_json(v.clone())),
262        (ParamType::String, Json::Number(n)) => Ok(Value::from(n.to_string())),
263        (ParamType::String, Json::Bool(b)) => Ok(Value::from(b.to_string())),
264        (ParamType::Select, Json::String(s)) => {
265            if options.is_empty() || options.iter().any(|o| o == s) {
266                Ok(Value::from(s.as_str()))
267            } else {
268                Err(format!("`{s}` is not one of {options:?}"))
269            }
270        }
271        (ParamType::Number, Json::Number(_)) => Ok(Value::from_json(v.clone())),
272        (ParamType::Number, Json::String(s)) => {
273            let t = s.trim();
274            t.parse::<i64>()
275                .map(Value::Int)
276                .or_else(|_| t.parse::<f64>().map(Value::Float))
277                .map_err(|_| format!("`{s}` is not a number"))
278        }
279        (ParamType::Boolean, Json::Bool(b)) => Ok(Value::Bool(*b)),
280        (ParamType::Boolean, Json::String(s)) => match s.trim().to_ascii_lowercase().as_str() {
281            "true" | "yes" => Ok(Value::Bool(true)),
282            "false" | "no" => Ok(Value::Bool(false)),
283            _ => Err(format!("`{s}` is not a boolean")),
284        },
285        (ParamType::Object, Json::Object(_)) => Ok(Value::from_json(v.clone())),
286        (t, other) => Err(format!("expected {}, got {}", t.json_type(), json_kind(other))),
287    }
288}
289
290fn json_kind(v: &Json) -> &'static str {
291    match v {
292        Json::Null => "null",
293        Json::Bool(_) => "boolean",
294        Json::Number(_) => "number",
295        Json::String(_) => "string",
296        Json::Array(_) => "array",
297        Json::Object(_) => "object",
298    }
299}
300
301fn coerce(p: &ParamConfig, v: &Json) -> Result<Value, String> {
302    match p.ty.element() {
303        None => coerce_scalar(p.ty, &p.options, v),
304        Some(elem) => match v {
305            Json::Array(items) => {
306                items.iter().map(|i| coerce_scalar(elem, &[], i)).collect::<Result<Vec<_>, _>>().map(Value::from)
307            }
308            other => Err(format!("expected array, got {}", json_kind(other))),
309        },
310    }
311}
312
313impl Node for ExtractorNode {
314    fn run(&self, ctx: NodeContext) -> BoxFuture<'_, NodeResult> {
315        Box::pin(self.execute(ctx))
316    }
317
318    fn inputs(&self) -> Vec<Selector> {
319        let cfg = &self.config;
320        let mut out = vec![cfg.query.clone()];
321        if let Some(instruction) = &cfg.instruction {
322            out.extend(instruction.selectors().cloned());
323        }
324        if let Some(memory) = &cfg.memory {
325            out.extend(memory.selectors());
326        }
327        out.extend(cfg.vision.selectors());
328        out.extend(cfg.model.selectors());
329        out
330    }
331}
332
333/// Factory for the node registry.
334pub fn factory(doc: &NodeDoc) -> Result<Arc<dyn Node>, ConfigError> {
335    Ok(Arc::new(ExtractorNode::from_doc(doc)?))
336}
337
338#[cfg(test)]
339mod tests {
340    use super::*;
341    use crate::mock::MockModel;
342    use crate::registry::ModelRegistry;
343    use crate::types::ChatDelta;
344    use graphrt_core::{NodeOutcome, Services, VariablePool};
345
346    fn node(mode: &str) -> ExtractorNode {
347        ExtractorNode::from_doc(&NodeDoc::new(
348            "pe",
349            "parameter-extractor",
350            json!({
351                "model": {"provider": "openai", "name": "gpt"},
352                "query": ["sys", "query"],
353                "reasoning_mode": mode,
354                "parameters": [
355                    {"name": "city", "type": "string", "required": true},
356                    {"name": "days", "type": "number", "required": true},
357                    {"name": "unit", "type": "select", "options": ["c", "f"]},
358                    {"name": "tags", "type": "array[string]"},
359                    {"name": "note", "type": "string"}
360                ]
361            }),
362        ))
363        .unwrap()
364    }
365
366    async fn run(node: &ExtractorNode, response: Vec<ChatDelta>) -> (NodeOutput, Arc<MockModel>) {
367        let model = Arc::new(MockModel::new(vec![response]));
368        let mut pool = VariablePool::new();
369        pool.insert("sys", "query", Value::from("weather in Paris for 3 days"));
370        let ctx = NodeContext::for_test("pe", pool).with_services(Arc::new(
371            Services::new().with(ModelRegistry::new().with("openai", Arc::clone(&model) as Arc<dyn crate::ChatModel>)),
372        ));
373        match node.run(ctx).await.unwrap() {
374            NodeOutcome::Completed(o) => (o, model),
375            NodeOutcome::Paused(_) => panic!("paused"),
376        }
377    }
378
379    #[tokio::test]
380    async fn function_call_mode_coerces_types() {
381        let n = node("function_call");
382        let (out, model) = run(
383            &n,
384            MockModel::tool_calls(&[("c", EXTRACT_TOOL, r#"{"city":"Paris","days":"3","unit":"c","tags":["a"]}"#)]),
385        )
386        .await;
387        assert_eq!(out.outputs["__is_success"], Value::Int(1));
388        assert_eq!(out.outputs["days"], Value::Int(3));
389        assert_eq!(out.outputs["note"], Value::Null, "missing optional parameters are fine");
390        let req = &model.requests()[0];
391        assert_eq!(req.tool_choice, Some(ToolChoice::Tool(EXTRACT_TOOL.into())));
392        assert_eq!(req.tools[0].parameters["properties"]["unit"]["enum"][1], "f");
393        assert_eq!(req.tools[0].parameters["required"][0], "city");
394    }
395
396    #[tokio::test]
397    async fn prompt_mode_reports_validation_problems() {
398        let n = node("prompt");
399        let (out, model) = run(&n, MockModel::text("Here: {\"city\": \"Paris\", \"unit\": \"k\"}")).await;
400        assert_eq!(out.outputs["__is_success"], Value::Int(0));
401        let reason = out.outputs["__reason"].to_text();
402        assert!(reason.contains("days"));
403        assert!(reason.contains("unit"));
404        assert_eq!(out.outputs["city"], Value::from("Paris"));
405        assert!(model.requests()[0].tools.is_empty());
406    }
407
408    #[tokio::test]
409    async fn malformed_function_arguments_are_not_a_success() {
410        let n = node("function_call");
411        let (out, _) = run(&n, MockModel::tool_calls(&[("c", EXTRACT_TOOL, r#"{"city":"Par"#)])).await;
412        assert_eq!(out.outputs["__is_success"], Value::Int(0));
413        assert!(out.outputs["__reason"].to_text().contains("invalid function arguments"));
414        assert_eq!(out.outputs["city"], Value::Null);
415    }
416
417    #[tokio::test]
418    async fn non_json_answer_is_soft_failure() {
419        let (out, _) = run(&node("prompt"), MockModel::text("sorry")).await;
420        assert_eq!(out.outputs["__is_success"], Value::Int(0));
421    }
422
423    #[test]
424    fn rejects_reserved_names() {
425        let doc = NodeDoc::new(
426            "pe",
427            "parameter-extractor",
428            json!({"model": {"provider": "p", "name": "m"}, "query": "sys.query",
429                   "parameters": [{"name": "__reason", "type": "string"}]}),
430        );
431        assert!(ExtractorNode::from_doc(&doc).is_err());
432    }
433}