Skip to main content

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}