1use std::collections::HashMap;
2
3use async_trait::async_trait;
4use serde::{Deserialize, Serialize};
5use serde_json::Value;
6use simple_agent_type::message::Role;
7use simple_agent_type::tool::{ToolChoice, ToolType};
8use thiserror::Error;
9
10use super::{TraceContext, YamlToolTraceMode, YamlWorkflowTraceTenantContext};
11
12#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
13#[serde(rename_all = "snake_case")]
14pub enum YamlWorkflowTokenKind {
15 Output,
16 Thinking,
17}
18
19#[derive(Debug, Clone, PartialEq, Serialize)]
20pub struct YamlWorkflowEvent {
21 pub event_type: String,
22 #[serde(skip_serializing_if = "Option::is_none")]
23 pub node_id: Option<String>,
24 #[serde(skip_serializing_if = "Option::is_none")]
25 pub step_id: Option<String>,
26 #[serde(skip_serializing_if = "Option::is_none")]
27 pub node_kind: Option<String>,
28 #[serde(skip_serializing_if = "Option::is_none")]
29 pub streamable: Option<bool>,
30 #[serde(skip_serializing_if = "Option::is_none")]
31 pub message: Option<String>,
32 #[serde(skip_serializing_if = "Option::is_none")]
33 pub delta: Option<String>,
34 #[serde(skip_serializing_if = "Option::is_none")]
35 pub token_kind: Option<YamlWorkflowTokenKind>,
36 #[serde(skip_serializing_if = "Option::is_none")]
37 pub is_terminal_node_token: Option<bool>,
38 #[serde(skip_serializing_if = "Option::is_none")]
39 pub elapsed_ms: Option<u128>,
40 #[serde(skip_serializing_if = "Option::is_none")]
41 pub metadata: Option<Value>,
42}
43
44pub type WorkflowMessageRole = Role;
45
46#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
47pub struct WorkflowMessage {
48 pub role: WorkflowMessageRole,
49 pub content: String,
50 #[serde(default)]
51 pub name: Option<String>,
52 #[serde(default, alias = "toolCallId")]
53 pub tool_call_id: Option<String>,
54}
55
56#[derive(Debug, Clone, PartialEq, Serialize)]
57pub struct YamlTemplateBinding {
58 pub index: usize,
59 pub expression: String,
60 pub source_path: String,
61 pub resolved: Value,
62 pub resolved_type: String,
63 pub missing: bool,
64}
65
66#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
67pub enum YamlWorkflowDiagnosticSeverity {
68 Error,
69 Warning,
70}
71
72#[derive(Debug, Clone, PartialEq, Eq, Serialize)]
73pub struct YamlWorkflowDiagnostic {
74 pub node_id: Option<String>,
75 pub code: String,
76 pub severity: YamlWorkflowDiagnosticSeverity,
77 pub message: String,
78}
79
80#[derive(Debug, Error)]
81pub enum YamlWorkflowRunError {
82 #[error("failed to read workflow yaml '{path}': {source}")]
83 Read {
84 path: String,
85 source: std::io::Error,
86 },
87 #[error("failed to parse workflow yaml '{path}': {source}")]
88 Parse {
89 path: String,
90 source: serde_yaml::Error,
91 },
92 #[error("rejected workflow yaml '{path}': {reason}")]
93 FileRejected { path: String, reason: String },
94 #[error("workflow '{workflow_id}' has no nodes")]
95 EmptyNodes { workflow_id: String },
96 #[error("entry node '{entry_node}' does not exist")]
97 MissingEntry { entry_node: String },
98 #[error("unknown node id '{node_id}'")]
99 MissingNode { node_id: String },
100 #[error("unsupported node type in '{node_id}'")]
101 UnsupportedNodeType { node_id: String },
102 #[error("unsupported switch condition format: {condition}")]
103 UnsupportedCondition { condition: String },
104 #[error("switch node '{node_id}' has no valid next target")]
105 InvalidSwitchTarget { node_id: String },
106 #[error("llm returned non-object payload for node '{node_id}'")]
107 LlmPayloadNotObject { node_id: String },
108 #[error("custom worker handler '{handler}' is not supported")]
109 UnsupportedCustomHandler { handler: String },
110 #[error("llm execution failed for node '{node_id}': {message}")]
111 Llm { node_id: String, message: String },
112 #[error("custom worker execution failed for node '{node_id}': {message}")]
113 CustomWorker { node_id: String, message: String },
114 #[error("workflow validation failed with {diagnostics_count} error(s)")]
115 Validation {
116 diagnostics_count: usize,
117 diagnostics: Vec<YamlWorkflowDiagnostic>,
118 },
119 #[error("invalid workflow input: {message}")]
120 InvalidInput { message: String },
121 #[error("ir runtime execution failed: {message}")]
122 IrRuntime { message: String },
123 #[error("workflow event stream cancelled: {message}")]
124 EventSinkCancelled { message: String },
125}
126
127pub trait YamlWorkflowEventSink: Send + Sync {
128 fn emit(&self, event: &YamlWorkflowEvent);
129
130 fn is_cancelled(&self) -> bool {
131 false
132 }
133}
134
135pub struct NoopYamlWorkflowEventSink;
136
137impl YamlWorkflowEventSink for NoopYamlWorkflowEventSink {
138 fn emit(&self, _event: &YamlWorkflowEvent) {}
139}
140
141pub(super) fn workflow_event_sink_cancelled_message() -> &'static str {
142 "workflow event callback cancelled"
143}
144
145pub(super) fn event_sink_is_cancelled(event_sink: Option<&dyn YamlWorkflowEventSink>) -> bool {
146 event_sink.map(|sink| sink.is_cancelled()).unwrap_or(false)
147}
148
149#[derive(Debug, Clone, PartialEq, Eq, Error)]
150pub enum YamlToIrError {
151 #[error("entry node '{entry_node}' does not exist")]
152 MissingEntry { entry_node: String },
153 #[error("node '{node_id}' has multiple outgoing edges in YAML; IR llm/tool nodes require one")]
154 MultipleOutgoingEdge { node_id: String },
155 #[error("node '{node_id}' is unsupported for IR conversion: {reason}")]
156 UnsupportedNode { node_id: String, reason: String },
157}
158
159#[derive(Debug, Clone)]
160pub struct YamlLlmExecutionRequest {
161 pub node_id: String,
162 pub is_terminal_node: bool,
163 pub stream_json_as_text: bool,
164 pub model: String,
165 pub max_tokens: Option<u32>,
166 pub temperature: Option<f32>,
167 pub top_p: Option<f32>,
168 pub messages: Option<Vec<super::Message>>,
169 pub append_prompt_as_user: bool,
170 pub prompt: String,
171 pub prompt_template: String,
172 pub prompt_bindings: Vec<YamlTemplateBinding>,
173 pub schema: Value,
174 pub stream: bool,
175 pub heal: bool,
176 pub tools: Vec<YamlResolvedTool>,
177 pub tool_choice: Option<ToolChoice>,
178 pub max_tool_roundtrips: u8,
179 pub tool_calls_global_key: Option<String>,
180 pub tool_trace_mode: YamlToolTraceMode,
181 pub execution_context: Value,
182 pub input_text: String,
183 pub trace_id: Option<String>,
184 pub trace_context: Option<TraceContext>,
185 pub tenant_context: YamlWorkflowTraceTenantContext,
186 pub trace_sampled: bool,
187}
188
189#[derive(Debug, Clone)]
190pub struct YamlResolvedTool {
191 pub definition: super::ToolDefinition,
192 pub output_schema: Option<Value>,
193}
194
195#[async_trait]
196pub trait YamlWorkflowLlmExecutor: Send + Sync {
197 async fn complete_structured(
198 &self,
199 request: YamlLlmExecutionRequest,
200 event_sink: Option<&dyn YamlWorkflowEventSink>,
201 ) -> Result<super::YamlLlmExecutionResult, String>;
202}
203
204#[async_trait]
205pub trait YamlWorkflowCustomWorkerExecutor: Send + Sync {
206 async fn execute(
207 &self,
208 handler: &str,
209 handler_file: Option<&str>,
210 payload: &Value,
211 input_text: &str,
212 context: &Value,
213 ) -> Result<Value, String>;
214}
215
216#[derive(Debug, Clone, Deserialize)]
217#[serde(deny_unknown_fields)]
218pub struct YamlGlobalUpdate {
219 pub op: String,
220 pub from: Option<String>,
221 pub by: Option<f64>,
222}
223
224#[derive(Debug, Clone, Deserialize)]
225#[serde(deny_unknown_fields)]
226pub struct YamlNodeConfig {
227 pub prompt: Option<String>,
228 #[serde(default, alias = "schema")]
229 pub output_schema: Option<Value>,
230 pub payload: Option<Value>,
231 pub set_globals: Option<HashMap<String, String>>,
232 pub update_globals: Option<HashMap<String, YamlGlobalUpdate>>,
233}
234
235#[derive(Debug, Clone, Deserialize)]
236#[serde(deny_unknown_fields)]
237pub struct YamlCustomWorker {
238 pub handler: String,
239 pub handler_file: Option<String>,
240}
241
242#[derive(Debug, Clone, Deserialize)]
243#[serde(deny_unknown_fields)]
244pub struct YamlSwitchBranch {
245 pub condition: String,
246 pub target: String,
247}
248
249#[derive(Debug, Clone, Deserialize)]
250#[serde(deny_unknown_fields)]
251pub struct YamlSwitch {
252 #[serde(default)]
253 pub branches: Vec<YamlSwitchBranch>,
254 pub default: String,
255}
256
257#[derive(Debug, Clone, Deserialize)]
258#[serde(untagged)]
259pub enum YamlToolChoiceConfig {
260 Mode(super::ToolChoiceMode),
261 Function(YamlToolChoiceFunction),
262 OpenAi(super::ToolChoiceTool),
263}
264
265#[derive(Debug, Clone, Deserialize)]
266#[serde(deny_unknown_fields)]
267pub struct YamlToolChoiceFunction {
268 pub function: String,
269}
270
271#[derive(Debug, Clone, Deserialize)]
272#[serde(deny_unknown_fields)]
273pub struct YamlSimplifiedToolDeclaration {
274 pub name: String,
275 pub description: Option<String>,
276 pub input_schema: Value,
277 pub output_schema: Option<Value>,
278}
279
280#[derive(Debug, Clone, Deserialize)]
281#[serde(deny_unknown_fields)]
282pub struct YamlOpenAiToolFunction {
283 pub name: String,
284 pub description: Option<String>,
285 pub parameters: Option<Value>,
286 pub output_schema: Option<Value>,
287}
288
289#[derive(Debug, Clone, Deserialize)]
290#[serde(deny_unknown_fields)]
291pub struct YamlOpenAiToolDeclaration {
292 #[serde(rename = "type")]
293 pub tool_type: Option<ToolType>,
294 pub function: YamlOpenAiToolFunction,
295}
296
297#[derive(Debug, Clone, Deserialize)]
298#[serde(untagged)]
299pub enum YamlToolDeclaration {
300 OpenAi(YamlOpenAiToolDeclaration),
301 Simplified(YamlSimplifiedToolDeclaration),
302}
303
304#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize, Serialize, Default)]
305#[serde(rename_all = "snake_case")]
306pub enum YamlToolFormat {
307 #[default]
308 Openai,
309 Simplified,
310}
311
312#[derive(Debug, Clone, Deserialize)]
313#[serde(deny_unknown_fields)]
314pub struct YamlLlmCall {
315 pub model: String,
316 pub max_tokens: Option<u32>,
317 pub temperature: Option<f32>,
318 pub top_p: Option<f32>,
319 pub stream: Option<bool>,
320 pub stream_json_as_text: Option<bool>,
321 pub heal: Option<bool>,
322 pub messages_path: Option<String>,
323 pub append_prompt_as_user: Option<bool>,
324 #[serde(default)]
325 pub tools_format: YamlToolFormat,
326 #[serde(default)]
327 pub tools: Vec<YamlToolDeclaration>,
328 pub tool_choice: Option<YamlToolChoiceConfig>,
329 pub max_tool_roundtrips: Option<u8>,
330 pub tool_calls_global_key: Option<String>,
331}
332
333#[derive(Debug, Clone, Deserialize)]
334#[serde(deny_unknown_fields)]
335pub struct YamlNodeType {
336 pub llm_call: Option<YamlLlmCall>,
337 pub switch: Option<YamlSwitch>,
338 pub custom_worker: Option<YamlCustomWorker>,
339 pub end: Option<Value>,
340}
341
342#[derive(Debug, Clone, Deserialize)]
343#[serde(deny_unknown_fields)]
344pub struct YamlNode {
345 pub id: String,
346 #[serde(default)]
347 pub name: Option<String>,
348 pub node_type: YamlNodeType,
349 pub config: Option<YamlNodeConfig>,
350}
351
352impl YamlNode {
353 pub(super) fn kind_name(&self) -> &'static str {
354 if self.node_type.llm_call.is_some() {
355 "llm_call"
356 } else if self.node_type.switch.is_some() {
357 "switch"
358 } else if self.node_type.custom_worker.is_some() {
359 "custom_worker"
360 } else if self.node_type.end.is_some() {
361 "end"
362 } else {
363 "unknown"
364 }
365 }
366}
367
368#[derive(Debug, Clone, Deserialize)]
369#[serde(deny_unknown_fields)]
370pub struct YamlEdge {
371 pub from: String,
372 pub to: String,
373}
374
375#[derive(Debug, Clone, Deserialize)]
376#[serde(deny_unknown_fields)]
377pub struct YamlWorkflow {
378 pub id: String,
379 #[serde(default)]
380 pub version: Option<String>,
381 #[serde(default)]
382 pub metadata: Option<HashMap<String, Value>>,
383 pub entry_node: String,
384 #[serde(default)]
385 pub nodes: Vec<YamlNode>,
386 #[serde(default)]
387 pub edges: Vec<YamlEdge>,
388}