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::pin::Pin;
95use std::sync::Arc;
96use std::task::{Context, Poll};
97
98use futures::channel::mpsc;
99use futures::future::BoxFuture;
100use futures::{FutureExt, Stream, StreamExt};
101use indexmap::IndexMap;
102
103use self::control::{Control, Stop};
104use crate::event::{Event, PauseReason};
105use crate::graph::Graph;
106use crate::node::{Clock, EventSink, Services, default_clock};
107use crate::pool::Selector;
108use crate::snapshot::Snapshot;
109use crate::value::Value;
110
111#[cfg(doc)]
112use crate::node::{NodeError, NodeOutput};
113
114/// Resource limits for a run.
115#[derive(Clone, Debug, PartialEq)]
116pub struct Limits {
117    /// Maximum node executions (including retries and container bodies). Default 10 000.
118    pub max_steps: u64,
119    /// Wall-clock budget for the whole run. Enforced only with a timer-capable clock.
120    pub max_duration_ms: Option<u64>,
121    /// Maximum container nesting depth. Default 8.
122    pub max_depth: u32,
123    /// Timeout applied to nodes without their own `timeout_ms`.
124    pub default_node_timeout_ms: Option<u64>,
125    /// Maximum nodes executing concurrently within one frame. Default 64.
126    pub max_concurrency: usize,
127}
128
129impl Default for Limits {
130    fn default() -> Self {
131        Self {
132            max_steps: 10_000,
133            max_duration_ms: None,
134            max_depth: 8,
135            default_node_timeout_ms: None,
136            max_concurrency: 64,
137        }
138    }
139}
140
141/// Input for a run.
142#[derive(Clone, Debug, Default)]
143pub struct RunInput {
144    /// Values for the start node's declared variables (written into the entry node's namespace).
145    pub inputs: IndexMap<String, Value>,
146    /// System variables (`sys.*`), e.g. `query`, `files`, `user_id`, `conversation_id`.
147    pub sys: IndexMap<String, Value>,
148    /// Environment variables (`env.*`); override document defaults. Never persisted.
149    pub env: IndexMap<String, Value>,
150    /// Conversation variables (`conversation.*`); override document defaults.
151    pub conversation: IndexMap<String, Value>,
152    /// Explicit run id (generated when absent).
153    pub run_id: Option<String>,
154    /// Resume a paused run.
155    pub resume: Option<ResumeFrom>,
156}
157
158impl RunInput {
159    pub fn new() -> Self {
160        Self::default()
161    }
162
163    /// Add a start input.
164    pub fn input(mut self, name: impl Into<String>, value: impl Into<Value>) -> Self {
165        self.inputs.insert(name.into(), value.into());
166        self
167    }
168
169    /// Add a system variable.
170    pub fn sys(mut self, name: impl Into<String>, value: impl Into<Value>) -> Self {
171        self.sys.insert(name.into(), value.into());
172        self
173    }
174
175    /// Add an environment variable.
176    pub fn env(mut self, name: impl Into<String>, value: impl Into<Value>) -> Self {
177        self.env.insert(name.into(), value.into());
178        self
179    }
180
181    /// Resume from a snapshot.
182    pub fn resume(mut self, snapshot: Snapshot, inputs: IndexMap<String, Value>) -> Self {
183        self.resume = Some(ResumeFrom::new(snapshot, inputs));
184        self
185    }
186}
187
188/// Resume information.
189#[derive(Clone, Debug)]
190pub struct ResumeFrom {
191    pub snapshot: Snapshot,
192    /// Host input for paused nodes (e.g. a submitted human-input form), keyed by
193    /// `"<frame>/<node_id>"` for one specific frame or by plain node id for any
194    /// frame. Root-frame nodes use the plain node id.
195    pub inputs: IndexMap<String, Value>,
196    /// Plaintext for secrets outside `env.*` (e.g. secret-typed start inputs or
197    /// conversation variables), keyed by dotted selector (`"start.api_key"`).
198    /// Snapshots never store secret plaintext: such values are restored as
199    /// redacted secrets ([`Value::redacted_secret`]) and nodes that need them fail
200    /// until they are re-supplied here. Only selectors that currently hold a
201    /// redacted secret are overwritten.
202    pub secrets: IndexMap<String, Value>,
203}
204
205impl ResumeFrom {
206    /// Resume `snapshot` with host input for paused nodes.
207    pub fn new(snapshot: Snapshot, inputs: IndexMap<String, Value>) -> Self {
208        Self { snapshot, inputs, secrets: IndexMap::new() }
209    }
210
211    /// Re-supply a secret that is not an environment variable.
212    pub fn secret(mut self, selector: impl Into<String>, value: impl Into<String>) -> Self {
213        self.secrets.insert(selector.into(), Value::Secret(Arc::from(value.into())));
214        self
215    }
216}
217
218/// Executes runs of one graph.
219#[derive(Clone, Debug)]
220pub struct Engine {
221    graph: Arc<Graph>,
222    services: Arc<Services>,
223    clock: Arc<dyn Clock>,
224    limits: Limits,
225}
226
227impl Engine {
228    pub fn new(graph: Arc<Graph>) -> Self {
229        Self { graph, services: Arc::new(Services::new()), clock: default_clock(), limits: Limits::default() }
230    }
231
232    pub fn with_services(mut self, services: Services) -> Self {
233        self.services = Arc::new(services);
234        self
235    }
236
237    /// Share an existing services registry.
238    pub fn with_shared_services(mut self, services: Arc<Services>) -> Self {
239        self.services = services;
240        self
241    }
242
243    pub fn with_clock(mut self, clock: Arc<dyn Clock>) -> Self {
244        self.clock = clock;
245        self
246    }
247
248    pub fn with_limits(mut self, limits: Limits) -> Self {
249        self.limits = limits;
250        self
251    }
252
253    pub fn graph(&self) -> &Arc<Graph> {
254        &self.graph
255    }
256
257    pub fn limits(&self) -> &Limits {
258        &self.limits
259    }
260
261    /// Start a run. The returned stream drives execution when polled (no task is
262    /// spawned), so it works on any executor. The final item is always a terminal
263    /// event (`RunSucceeded`, `RunFailed`, `RunAborted` or `RunPaused`).
264    pub fn run(&self, input: RunInput) -> RunStream {
265        let (tx, rx) = mpsc::unbounded::<Event>();
266        let control = Arc::new(Control::default());
267        let sink: EventSink = Arc::new(move |event| {
268            // The receiver only disappears when the consumer dropped the stream,
269            // in which case the run is being torn down anyway.
270            let _ = tx.unbounded_send(event);
271        });
272        let driver = root::run_root(self.clone(), input, control.clone(), sink).boxed();
273        RunStream { driver: Some(driver), rx, finished: false, handle: RunHandle { control } }
274    }
275
276    /// Run to completion and return the terminal event, discarding the others.
277    pub async fn run_to_end(&self, input: RunInput) -> Event {
278        let mut stream = self.run(input);
279        let mut last = None;
280        while let Some(event) = stream.next().await {
281            last = Some(event);
282        }
283        last.unwrap_or(Event::RunFailed {
284            error: "run produced no events".to_owned(),
285            error_type: "internal".to_owned(),
286            usage: Default::default(),
287            elapsed_ms: 0,
288        })
289    }
290}
291
292/// Stream of run events. `Send + 'static`. Dropping it cancels the run.
293pub struct RunStream {
294    driver: Option<BoxFuture<'static, ()>>,
295    rx: mpsc::UnboundedReceiver<Event>,
296    finished: bool,
297    handle: RunHandle,
298}
299
300impl std::fmt::Debug for RunStream {
301    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
302        f.debug_struct("RunStream").field("finished", &self.finished).finish_non_exhaustive()
303    }
304}
305
306impl RunStream {
307    /// A handle for controlling the run from elsewhere.
308    pub fn handle(&self) -> RunHandle {
309        self.handle.clone()
310    }
311}
312
313impl Stream for RunStream {
314    type Item = Event;
315
316    fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Event>> {
317        if self.finished {
318            return Poll::Ready(None);
319        }
320        if let Some(driver) = self.driver.as_mut() {
321            if driver.as_mut().poll(cx).is_ready() {
322                self.driver = None;
323            }
324        }
325        match self.rx.poll_next_unpin(cx) {
326            Poll::Ready(Some(event)) => {
327                if event.is_terminal() {
328                    self.finished = true;
329                }
330                Poll::Ready(Some(event))
331            }
332            Poll::Ready(None) => {
333                self.finished = true;
334                Poll::Ready(None)
335            }
336            Poll::Pending => {
337                if self.driver.is_none() {
338                    // Every event is sent synchronously, so a finished driver with an
339                    // empty queue means the run is over.
340                    self.finished = true;
341                    Poll::Ready(None)
342                } else {
343                    Poll::Pending
344                }
345            }
346        }
347    }
348}
349
350/// Controls a running run. Cheap to clone, `Send + Sync`.
351#[derive(Clone, Debug)]
352pub struct RunHandle {
353    control: Arc<Control>,
354}
355
356impl RunHandle {
357    /// Cancel immediately: in-flight nodes are dropped. Ends with `RunAborted`.
358    pub fn abort(&self, reason: impl Into<String>) {
359        self.control.stop(Stop::Abort(reason.into()));
360    }
361
362    /// Stop scheduling new nodes, let in-flight nodes finish, then end with `RunPaused`
363    /// (or `RunSucceeded` if nothing was left to run).
364    pub fn pause(&self, reason: impl Into<String>) {
365        self.control.request_pause(Some(PauseReason {
366            frame: Arc::from(""),
367            node_id: None,
368            kind: "external".to_owned(),
369            data: Value::from(reason.into()),
370        }));
371    }
372
373    /// Write a variable into the root frame (applied between node completions).
374    pub fn update_variable(&self, selector: Selector, value: Value) {
375        self.control.push_update(selector, value);
376    }
377}