1use 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
27pub const EXTRACT_TOOL: &str = "extract_parameters";
29
30#[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#[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#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Deserialize)]
92#[serde(rename_all = "snake_case")]
93pub enum ReasoningMode {
94 #[default]
96 FunctionCall,
97 Prompt,
99}
100
101#[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#[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
235fn 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
333pub 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}