Struct CompiledGraph 

pub struct CompiledGraph<S: State> { /* private fields */ }

A validated, executable graph. Produced by StateGraph::compile().

This is the primary execution handle. Use invoke() to run a graph from initial state, resume() to continue after an interrupt, and get_state() to inspect the current checkpoint.

Example

let outcome = graph.invoke(initial_state, GraphConfig::default()).await?;
match outcome {
    ExecutionOutcome::Completed(state) => println!("Done: {:?}", state),
    ExecutionOutcome::Interrupted { state, request } => {
        println!("Paused: {}", request.reason);
    }
}

Implementations

impl<S: State> CompiledGraph<S>

pub fn with_checkpointer(self, cp: impl Checkpointer + 'static) -> Self

Attach a checkpointer for durable state persistence.

Without a checkpointer, resume() and get_state() will return errors.

pub fn with_agent(self, agent: Agent) -> Self

Bind an agent to this compiled graph.

The agent’s identity, system prompt, and boundaries are preserved on the compiled graph for runtime inspection and enforcement.

pub fn agent(&self) -> Option<&Agent>

Get the bound agent, if any.

pub fn with_checkpointer_arc(self, cp: Arc<dyn Checkpointer>) -> Self

Attach a shared checkpointer (already behind Arc).

pub fn with_matrix_hook(self, hook: MatrixHookHandle) -> Self

Attach a matrix layer hook for convergence tracking and learned routing.

When attached, the Pregel engine will:

• Record ConvergenceSignal metadata via the hook
• Consult the hook for conditional edge routing decisions
• Record transitions for learning

Without a hook, NodeResult::Converge degrades to Update and conditional edges use the user’s router function directly.

pub fn matrix_hook(&self) -> Option<&MatrixHookHandle>

Get a reference to the matrix hook (if attached).

pub async fn invoke( &self, state: S, config: GraphConfig, ) -> Result<ExecutionOutcome<S>, PeError>

Run graph from START with initial state.

If config.checkpoint_id is set and a checkpointer is attached, the graph resumes from that specific checkpoint (time travel) instead of running from the provided state.

Executes the BSP loop until END, interrupt, or recursion limit.

pub async fn invoke_with_lobe_runtime_services( &self, state: S, config: GraphConfig, lobe_runtime_service_factory: Option<Arc<dyn LobeRuntimeServiceFactory>>, ) -> Result<ExecutionOutcome<S>, PeError>

Run graph from START with optional runtime-owned services for lobes.

pub async fn invoke_with_observer_and_lobe_runtime_services( &self, state: S, config: GraphConfig, observer: Option<Arc<dyn NodeObserver>>, tool_observer: Option<Arc<dyn ToolObserver>>, lobe_runtime_service_factory: Option<Arc<dyn LobeRuntimeServiceFactory>>, ) -> Result<ExecutionOutcome<S>, PeError>

Run graph from START with optional observer, tool observer, and runtime-owned services.

pub async fn invoke_with_stream( &self, state: S, config: GraphConfig, stream_sender: Arc<dyn Any + Send + Sync>, ) -> Result<ExecutionOutcome<S>, PeError>

Run graph from START with streaming support.

Like invoke, but injects a type-erased stream sender into every NodeContext and an optional NodeObserver for phase lifecycle events.

Supports time-travel: if config.checkpoint_id is set, loads and resumes from that checkpoint (mirroring invoke).

Called by pe-runtime’s streaming layer — not typically used directly.

pub async fn invoke_with_stream_and_observer( &self, state: S, config: GraphConfig, stream_sender: Arc<dyn Any + Send + Sync>, observer: Option<Arc<dyn NodeObserver>>, tool_observer: Option<Arc<dyn ToolObserver>>, ) -> Result<ExecutionOutcome<S>, PeError>

Run graph with streaming and a NodeObserver for lifecycle events.

The observer receives on_node_start / on_node_complete / on_node_error callbacks. pe-runtime provides StreamingObserver which converts these to StreamEvent.

pub async fn invoke_with_stream_observer_and_lobe_runtime_services( &self, state: S, config: GraphConfig, stream_sender: Arc<dyn Any + Send + Sync>, observer: Option<Arc<dyn NodeObserver>>, tool_observer: Option<Arc<dyn ToolObserver>>, lobe_runtime_service_factory: Option<Arc<dyn LobeRuntimeServiceFactory>>, ) -> Result<ExecutionOutcome<S>, PeError>

Run graph with streaming, observers, and optional runtime-owned lobe services.

pub async fn resume( &self, thread_id: &str, input: S::Update, config: GraphConfig, ) -> Result<ExecutionOutcome<S>, PeError>

Resume a previously interrupted graph with human input.

Loads the latest checkpoint for the thread, applies the input update, and continues execution from where it paused.

pub async fn resume_with( &self, thread_id: &str, command: Command, config: GraphConfig, ) -> Result<ExecutionOutcome<S>, PeError>

Resume a previously interrupted graph using a Command.

This is the preferred resume API. It loads the latest checkpoint, applies the command (human input, goto, or state update), and continues execution.

For Command::Resume, the human input is stored in the phase state so nodes can access it via PhaseStateStore::get::<HumanInput>().

Example

let cmd = Command::resume(HumanInput { approved: true, feedback: None, data: None });
let outcome = graph.resume_with("thread-1", cmd, config).await?;

pub async fn resume_with_stream( &self, thread_id: &str, command: Command, config: GraphConfig, stream_sender: Arc<dyn Any + Send + Sync>, observer: Option<Arc<dyn NodeObserver>>, tool_observer: Option<Arc<dyn ToolObserver>>, ) -> Result<ExecutionOutcome<S>, PeError>

Resume with streaming and observer support.

Like resume_with, but injects a stream sender and optional observer for lifecycle events.

pub async fn get_state( &self, thread_id: &str, ) -> Result<Option<StateSnapshot<S>>, PeError>

Get the current state snapshot for a thread.

Returns None if no checkpoints exist for this thread.

pub async fn get_state_history( &self, thread_id: &str, ) -> Result<Vec<StateSnapshot<S>>, PeError>

Get full history of all checkpoints for a thread (time travel).

Returns snapshots oldest-first. Each snapshot contains the full state at that point, which nodes were scheduled next, and metadata.

Trait Implementations

impl<S: State> Debug for CompiledGraph<S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.