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}