graphrt_core/engine/mod.rs
1//! The execution engine.
2//!
3//! # Model
4//!
5//! - The [`Graph`] is immutable and shared; each run keeps its own per-frame
6//! node and edge state.
7//! - A node becomes ready once **every** incoming edge is resolved and **at
8//! least one** is taken. A node whose incoming edges are all skipped is
9//! skipped too (`NodeSkipped`), and the skip propagates downstream.
10//! - Non-branch nodes take every outgoing edge except `fail-branch` edges.
11//! Branch nodes take the edges whose handle equals [`NodeOutput::branch`];
12//! a branch node that selects no handle fails (subject to its error strategy).
13//! A selected handle with no edges simply skips every outgoing path.
14//! - Response nodes (answer / end) merge their outputs into the frame outputs:
15//! `answer` is concatenated, other keys overwrite. The root frame outputs are
16//! the run outputs.
17//! - Nodes of one frame run concurrently (up to [`Limits::max_concurrency`]) as
18//! futures polled by the run itself. Nothing is spawned, so the engine runs on
19//! any executor, including single-threaded and wasm ones.
20//!
21//! # Run bootstrap
22//!
23//! The root pool receives `env.*` (document defaults coerced to their declared
24//! types, overridden by [`RunInput::env`]), `conversation.*` (same rule; missing
25//! values get their type's zero value), `sys.*` from [`RunInput::sys`] plus
26//! `sys.run_id`. [`RunInput::inputs`] are written into the **namespace of the
27//! root entry node** (normally the `start` node) before it runs; the start
28//! node validates them and re-emits them as its outputs. Inputs are never
29//! copied into `sys`, so an input cannot shadow a system variable.
30//!
31//! # Failures
32//!
33//! - **Retries** apply to every node kind when `retry.max_retries > 0` and the
34//! error is [`NodeError::retryable`]. The delay is the larger of the policy
35//! delay and [`NodeError::retry_after_ms`] (capped at five minutes), awaited
36//! inside the node's own future, so other nodes keep running. The execution id is stable across
37//! attempts, and a retry that eventually succeeds is not a handled error.
38//! - **Timeouts** (`timeout_ms`, else [`Limits::default_node_timeout_ms`]) apply
39//! per attempt when the clock supports timers. The attempt deadline is also
40//! exposed as [`NodeContext::deadline_ms`](crate::node::NodeContext) so nodes
41//! that block synchronously can bound themselves.
42//! - After retries, the error strategy applies:
43//! - `fail`: the frame fails. In the root frame the run ends with `RunFailed`
44//! and in-flight nodes are dropped. In a container body, the container node
45//! receives [`SubgraphResult::Failed`](crate::node::SubgraphResult).
46//! - `fail-branch`: outputs `error_message` / `error_type`; only `fail-branch`
47//! edges are taken.
48//! - `default-value`: outputs are the defaults plus `error_message` /
49//! `error_type`; non-branch nodes then continue as on success. Branch nodes
50//! follow the handle named by a `branch` default value, or skip every
51//! outgoing path if there is none.
52//!
53//! Handled failures are counted in `RunSucceeded::handled_errors`.
54//! - A panicking node fails with error type `panic` (when unwinding is enabled).
55//!
56//! # Limits
57//!
58//! `max_steps` counts every node attempt in every frame and persists across
59//! pause / resume. `max_duration_ms` covers the whole run (including time before
60//! a pause) and is enforced by a timer race. `max_depth` bounds container nesting.
61//!
62//! # Containers
63//!
64//! Container nodes receive [`NodeContext::subgraph`](crate::node::NodeContext),
65//! which runs the container's body as a child frame (`"<parent>/<container>[i]"`)
66//! with the same scheduler, event sink, step budget and control signals. Writes
67//! to namespaces outside the body (container variables, conversation variables)
68//! are returned in `SubgraphResult::Completed::writes`; `broke` reports whether a
69//! `loop-end` node completed. Usage of container nodes themselves is not added
70//! to the run total (their children are already counted).
71//!
72//! # Pause / resume / abort
73//!
74//! - [`RunHandle::pause`] stops scheduling everywhere, lets in-flight nodes
75//! finish and then ends with `RunPaused` carrying a [`Snapshot`].
76//! - A node returning [`NodeOutcome::Paused`](crate::node::NodeOutcome) pauses
77//! only itself: independent branches keep running until nothing else can make
78//! progress, then the run pauses.
79//! - On resume ([`RunInput::resume`]) the snapshot's graph fingerprint and
80//! format are verified, env / sys / conversation values from the new
81//! [`RunInput`] are applied, pending nodes re-run and paused nodes are resumed
82//! with their saved state plus their entry in [`ResumeFrom::inputs`].
83//! Inputs are looked up by the frame-qualified key `"<frame>/<node_id>"`
84//! first (e.g. `"review[2]/approve"` for a node paused inside the third
85//! item of iteration `review`; the frame is [`PauseReason::frame`]), then by
86//! the plain node id, which applies to every frame.
87//! - [`RunHandle::abort`] drops every in-flight node future immediately.
88
89mod control;
90mod frame;
91mod ids;
92mod root;
93
94use std::collections::VecDeque;
95use std::pin::Pin;
96use std::sync::atomic::{AtomicBool, Ordering};
97use std::sync::{Arc, Mutex, PoisonError};
98use std::task::{Context, Poll};
99
100use futures::future::BoxFuture;
101use futures::task::AtomicWaker;
102use futures::{FutureExt, Stream, StreamExt};
103use indexmap::IndexMap;
104
105use self::control::{Control, Stop};
106use crate::event::{Event, PauseReason};
107use crate::graph::Graph;
108use crate::node::{Clock, EventSink, Services, default_clock};
109use crate::pool::Selector;
110use crate::snapshot::Snapshot;
111use crate::value::Value;
112
113#[cfg(doc)]
114use crate::node::{NodeError, NodeOutput};
115
116/// Resource limits for a run.
117#[derive(Clone, Debug, PartialEq)]
118pub struct Limits {
119 /// Maximum node executions (including retries and container bodies). Default 10 000.
120 pub max_steps: u64,
121 /// Wall-clock budget for the whole run. Enforced only with a timer-capable clock.
122 pub max_duration_ms: Option<u64>,
123 /// Maximum container nesting depth. Default 8.
124 pub max_depth: u32,
125 /// Timeout applied to nodes without their own `timeout_ms`.
126 pub default_node_timeout_ms: Option<u64>,
127 /// Maximum nodes executing concurrently within one frame. Default 64.
128 pub max_concurrency: usize,
129}
130
131impl Default for Limits {
132 fn default() -> Self {
133 Self {
134 max_steps: 10_000,
135 max_duration_ms: None,
136 max_depth: 8,
137 default_node_timeout_ms: None,
138 max_concurrency: 64,
139 }
140 }
141}
142
143/// Input for a run.
144#[derive(Clone, Debug, Default)]
145pub struct RunInput {
146 /// Values for the start node's declared variables (written into the entry node's namespace).
147 pub inputs: IndexMap<String, Value>,
148 /// System variables (`sys.*`), e.g. `query`, `files`, `user_id`, `conversation_id`.
149 pub sys: IndexMap<String, Value>,
150 /// Environment variables (`env.*`); override document defaults. Never persisted.
151 pub env: IndexMap<String, Value>,
152 /// Conversation variables (`conversation.*`); override document defaults.
153 pub conversation: IndexMap<String, Value>,
154 /// Explicit run id (generated when absent).
155 pub run_id: Option<String>,
156 /// Resume a paused run.
157 pub resume: Option<ResumeFrom>,
158}
159
160impl RunInput {
161 pub fn new() -> Self {
162 Self::default()
163 }
164
165 /// Add a start input.
166 pub fn input(mut self, name: impl Into<String>, value: impl Into<Value>) -> Self {
167 self.inputs.insert(name.into(), value.into());
168 self
169 }
170
171 /// Add a system variable.
172 pub fn sys(mut self, name: impl Into<String>, value: impl Into<Value>) -> Self {
173 self.sys.insert(name.into(), value.into());
174 self
175 }
176
177 /// Add an environment variable.
178 pub fn env(mut self, name: impl Into<String>, value: impl Into<Value>) -> Self {
179 self.env.insert(name.into(), value.into());
180 self
181 }
182
183 /// Resume from a snapshot.
184 pub fn resume(mut self, snapshot: Snapshot, inputs: IndexMap<String, Value>) -> Self {
185 self.resume = Some(ResumeFrom::new(snapshot, inputs));
186 self
187 }
188}
189
190/// Resume information.
191#[derive(Clone, Debug)]
192pub struct ResumeFrom {
193 pub snapshot: Snapshot,
194 /// Host input for paused nodes (e.g. a submitted human-input form), keyed by
195 /// `"<frame>/<node_id>"` for one specific frame or by plain node id for any
196 /// frame. Root-frame nodes use the plain node id.
197 pub inputs: IndexMap<String, Value>,
198 /// Plaintext for secrets outside `env.*` (e.g. secret-typed start inputs or
199 /// conversation variables), keyed by dotted selector (`"start.api_key"`).
200 /// Snapshots never store secret plaintext: such values are restored as
201 /// redacted secrets ([`Value::redacted_secret`]) and nodes that need them fail
202 /// until they are re-supplied here. Only selectors that currently hold a
203 /// redacted secret are overwritten.
204 pub secrets: IndexMap<String, Value>,
205}
206
207impl ResumeFrom {
208 /// Resume `snapshot` with host input for paused nodes.
209 pub fn new(snapshot: Snapshot, inputs: IndexMap<String, Value>) -> Self {
210 Self { snapshot, inputs, secrets: IndexMap::new() }
211 }
212
213 /// Re-supply a secret that is not an environment variable.
214 pub fn secret(mut self, selector: impl Into<String>, value: impl Into<String>) -> Self {
215 self.secrets.insert(selector.into(), Value::Secret(Arc::from(value.into())));
216 self
217 }
218}
219
220/// Executes runs of one graph.
221#[derive(Clone, Debug)]
222pub struct Engine {
223 graph: Arc<Graph>,
224 services: Arc<Services>,
225 clock: Arc<dyn Clock>,
226 limits: Limits,
227}
228
229impl Engine {
230 pub fn new(graph: Arc<Graph>) -> Self {
231 Self { graph, services: Arc::new(Services::new()), clock: default_clock(), limits: Limits::default() }
232 }
233
234 pub fn with_services(mut self, services: Services) -> Self {
235 self.services = Arc::new(services);
236 self
237 }
238
239 /// Share an existing services registry.
240 pub fn with_shared_services(mut self, services: Arc<Services>) -> Self {
241 self.services = services;
242 self
243 }
244
245 pub fn with_clock(mut self, clock: Arc<dyn Clock>) -> Self {
246 self.clock = clock;
247 self
248 }
249
250 pub fn with_limits(mut self, limits: Limits) -> Self {
251 self.limits = limits;
252 self
253 }
254
255 pub fn graph(&self) -> &Arc<Graph> {
256 &self.graph
257 }
258
259 pub fn limits(&self) -> &Limits {
260 &self.limits
261 }
262
263 /// Start a run. The returned stream drives execution when polled (no task is
264 /// spawned), so it works on any executor. The final item is always a terminal
265 /// event (`RunSucceeded`, `RunFailed`, `RunAborted` or `RunPaused`).
266 pub fn run(&self, input: RunInput) -> RunStream {
267 let queue = Arc::new(EventQueue::default());
268 let control = Arc::new(Control::default());
269 let sink_queue = Arc::clone(&queue);
270 let sink: EventSink = Arc::new(move |event| sink_queue.push(event));
271 let driver = root::run_root(self.clone(), input, control.clone(), sink).boxed();
272 RunStream { driver: Some(driver), queue, finished: false, handle: RunHandle { control } }
273 }
274
275 /// Run to completion and return the terminal event, discarding the others.
276 pub async fn run_to_end(&self, input: RunInput) -> Event {
277 let mut stream = self.run(input);
278 let mut last = None;
279 while let Some(event) = stream.next().await {
280 last = Some(event);
281 }
282 last.unwrap_or(Event::RunFailed {
283 error: "run produced no events".to_owned(),
284 error_type: "internal".to_owned(),
285 usage: Default::default(),
286 elapsed_ms: 0,
287 })
288 }
289}
290
291/// Events waiting for the stream's consumer.
292///
293/// Most events are produced while [`RunStream::poll_next`] polls the driver, on
294/// the consumer's own task; nodes may also emit from tasks of their own (e.g. a
295/// plugin's reader), which the waker covers. A `VecDeque` reuses its buffer, so
296/// unlike a channel no allocation is made per event.
297#[derive(Default)]
298struct EventQueue {
299 events: Mutex<VecDeque<Event>>,
300 waker: AtomicWaker,
301 /// Set when the stream is dropped: later events are discarded, not queued.
302 closed: AtomicBool,
303}
304
305impl EventQueue {
306 fn push(&self, event: Event) {
307 if self.closed.load(Ordering::Acquire) {
308 return;
309 }
310 self.events.lock().unwrap_or_else(PoisonError::into_inner).push_back(event);
311 self.waker.wake();
312 }
313
314 fn pop(&self) -> Option<Event> {
315 self.events.lock().unwrap_or_else(PoisonError::into_inner).pop_front()
316 }
317}
318
319/// Stream of run events. `Send + 'static`. Dropping it cancels the run.
320pub struct RunStream {
321 driver: Option<BoxFuture<'static, ()>>,
322 queue: Arc<EventQueue>,
323 finished: bool,
324 handle: RunHandle,
325}
326
327impl Drop for RunStream {
328 fn drop(&mut self) {
329 self.queue.closed.store(true, Ordering::Release);
330 }
331}
332
333impl std::fmt::Debug for RunStream {
334 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
335 f.debug_struct("RunStream").field("finished", &self.finished).finish_non_exhaustive()
336 }
337}
338
339impl RunStream {
340 /// A handle for controlling the run from elsewhere.
341 pub fn handle(&self) -> RunHandle {
342 self.handle.clone()
343 }
344}
345
346impl Stream for RunStream {
347 type Item = Event;
348
349 fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Event>> {
350 if self.finished {
351 return Poll::Ready(None);
352 }
353 if let Some(driver) = self.driver.as_mut() {
354 if driver.as_mut().poll(cx).is_ready() {
355 self.driver = None;
356 }
357 }
358 let event = match self.queue.pop() {
359 Some(event) => Some(event),
360 None if self.driver.is_none() => None,
361 None => {
362 // Only register when about to sleep (registering on every poll makes
363 // events pushed by this very task wake it again), then look once more
364 // so an event pushed from another task in between is not missed.
365 self.queue.waker.register(cx.waker());
366 match self.queue.pop() {
367 Some(event) => Some(event),
368 None => return Poll::Pending,
369 }
370 }
371 };
372 match event {
373 Some(event) => {
374 if event.is_terminal() {
375 self.finished = true;
376 }
377 Poll::Ready(Some(event))
378 }
379 None => {
380 // Every event is sent synchronously, so a finished driver with an
381 // empty queue means the run is over.
382 self.finished = true;
383 Poll::Ready(None)
384 }
385 }
386 }
387}
388
389/// Controls a running run. Cheap to clone, `Send + Sync`.
390#[derive(Clone, Debug)]
391pub struct RunHandle {
392 control: Arc<Control>,
393}
394
395impl RunHandle {
396 /// Cancel immediately: in-flight nodes are dropped. Ends with `RunAborted`.
397 pub fn abort(&self, reason: impl Into<String>) {
398 self.control.stop(Stop::Abort(reason.into()));
399 }
400
401 /// Stop scheduling new nodes, let in-flight nodes finish, then end with `RunPaused`
402 /// (or `RunSucceeded` if nothing was left to run).
403 pub fn pause(&self, reason: impl Into<String>) {
404 self.control.request_pause(Some(PauseReason {
405 frame: Arc::from(""),
406 node_id: None,
407 kind: "external".to_owned(),
408 data: Value::from(reason.into()),
409 }));
410 }
411
412 /// Write a variable into the root frame (applied between node completions).
413 pub fn update_variable(&self, selector: Selector, value: Value) {
414 self.control.push_update(selector, value);
415 }
416}