langgraph4rust 0.2.0

A powerful Rust implementation of a stateful workflow engine inspired by Python's LangGraph
Documentation
//! Compile-time structural validation of workflow graphs.
//!
//! This module hosts the validation pass that runs inside
//! [`StateGraphBuilder::compile`](crate::StateGraphBuilder::compile). It turns a
//! raw builder definition into a [`ValidatedGraph`] only after every structural
//! rule passes, guaranteeing that a compiled [`StateGraph`](crate::StateGraph)
//! is sound before execution.
//!
//! # Checks performed
//!
//! - `max_steps` is non-zero
//! - start / end node names are valid and distinct
//! - at least one node exists, with non-empty names
//! - the start node is not also a registered node and has outgoing edges
//! - every static edge target refers to a registered node (or the end node)
//! - every conditional edge source is a registered node (or the start node)
//! - **no node has both static and conditional edges** (mutual exclusivity)
//!
//! Note that conditional edge *targets* (the values returned by routers) are
//! resolved at runtime, not here.

use std::collections::{HashMap, HashSet};

use crate::core::RouterFn;
use crate::core::agent_node::AgentNode;
use crate::core::agent_state::AgentState;
use crate::core::error::LangGraphError;

/// A graph definition that has passed all validation checks.
///
/// Produced by [`GraphValidator::validate`] and consumed by
/// [`StateGraphBuilder::compile`](crate::StateGraphBuilder::compile) to construct
/// the final [`StateGraph`](crate::StateGraph). Its fields mirror the builder's,
/// but their invariants are now guaranteed.
pub struct ValidatedGraph<S: AgentState + Send + Sync> {
    pub max_steps: usize,
    pub nodes: HashMap<String, Box<dyn AgentNode<S>>>,
    pub edges: HashMap<String, HashSet<String>>,
    pub conditional_edges: HashMap<String, Vec<RouterFn<S>>>,
    pub start_node: String,
    pub end_node: String,
}

/// Validates a raw graph definition before it becomes executable.
///
/// Constructed internally by
/// [`StateGraphBuilder::compile`](crate::StateGraphBuilder::compile); call
/// [`validate`](GraphValidator::validate) to run every structural check.
pub struct GraphValidator<S: AgentState + Send + Sync> {
    pub max_steps: usize,
    pub nodes: HashMap<String, Box<dyn AgentNode<S>>>,
    pub edges: HashMap<String, HashSet<String>>,
    pub conditional_edges: HashMap<String, Vec<RouterFn<S>>>,
    pub start_node: String,
    pub end_node: String,
}

impl<S: AgentState + Send + Sync> GraphValidator<S> {
    /// Run all structural validation checks.
    ///
    /// # Returns
    ///
    /// - `Ok(ValidatedGraph)` — every check passed; the definition is sound.
    /// - `Err(LangGraphError::GraphError)` — the first violated rule, with a
    ///   descriptive message.
    pub fn validate(self) -> Result<ValidatedGraph<S>, LangGraphError> {
        Self::validate_max_steps(self.max_steps)?;
        Self::validate_start_end_nodes(&self.start_node, &self.end_node)?;
        Self::validate_nodes_exist(&self.nodes)?;
        Self::validate_node_names_not_empty(&self.nodes)?;
        Self::validate_start_not_in_nodes(&self.start_node, &self.nodes)?;
        Self::validate_start_end_different(&self.start_node, &self.end_node)?;
        Self::validate_start_has_outgoing_edges(
            &self.start_node,
            &self.edges,
            &self.conditional_edges,
        )?;
        Self::validate_static_edges_valid(
            &self.edges,
            &self.nodes,
            &self.start_node,
            &self.end_node,
        )?;
        Self::validate_conditional_edges_valid(
            &self.conditional_edges,
            &self.nodes,
            &self.start_node,
        )?;
        Self::validate_no_mixed_edge_types(&self.edges, &self.conditional_edges)?;

        Ok(ValidatedGraph {
            max_steps: self.max_steps,
            nodes: self.nodes,
            edges: self.edges,
            conditional_edges: self.conditional_edges,
            start_node: self.start_node,
            end_node: self.end_node,
        })
    }

    fn validate_max_steps(max_steps: usize) -> Result<(), LangGraphError> {
        if max_steps == 0 {
            return Err(LangGraphError::GraphError(
                "max_steps must be greater than 0".to_string(),
            ));
        }
        Ok(())
    }

    fn validate_start_end_nodes(start_node: &str, end_node: &str) -> Result<(), LangGraphError> {
        if start_node.is_empty() {
            return Err(LangGraphError::GraphError(
                "Start node cannot be empty".to_string(),
            ));
        }
        if end_node.is_empty() {
            return Err(LangGraphError::GraphError(
                "End node cannot be empty".to_string(),
            ));
        }
        Ok(())
    }

    fn validate_nodes_exist(
        nodes: &HashMap<String, Box<dyn AgentNode<S>>>,
    ) -> Result<(), LangGraphError> {
        if nodes.is_empty() {
            return Err(LangGraphError::GraphError(
                "Graph must contain at least one node".to_string(),
            ));
        }
        Ok(())
    }

    fn validate_node_names_not_empty(
        nodes: &HashMap<String, Box<dyn AgentNode<S>>>,
    ) -> Result<(), LangGraphError> {
        for name in nodes.keys() {
            if name.is_empty() {
                return Err(LangGraphError::GraphError(
                    "Node name cannot be empty".to_string(),
                ));
            }
        }
        Ok(())
    }

    fn validate_start_not_in_nodes(
        start_node: &str,
        nodes: &HashMap<String, Box<dyn AgentNode<S>>>,
    ) -> Result<(), LangGraphError> {
        if nodes.contains_key(start_node) {
            return Err(LangGraphError::GraphError(format!(
                "Start node '{}' cannot be a normal node",
                start_node
            )));
        }
        Ok(())
    }

    fn validate_start_end_different(
        start_node: &str,
        end_node: &str,
    ) -> Result<(), LangGraphError> {
        if start_node == end_node {
            return Err(LangGraphError::GraphError(
                "Start node and end node cannot be the same".to_string(),
            ));
        }
        Ok(())
    }

    fn validate_start_has_outgoing_edges(
        start_node: &str,
        edges: &HashMap<String, HashSet<String>>,
        conditional_edges: &HashMap<String, Vec<RouterFn<S>>>,
    ) -> Result<(), LangGraphError> {
        let start_has_edge =
            edges.contains_key(start_node) || conditional_edges.contains_key(start_node);
        if !start_has_edge {
            return Err(LangGraphError::GraphError(format!(
                "Start node '{}' must have at least one outgoing edge",
                start_node
            )));
        }
        Ok(())
    }

    fn validate_static_edges_valid(
        edges: &HashMap<String, HashSet<String>>,
        nodes: &HashMap<String, Box<dyn AgentNode<S>>>,
        start_node: &str,
        end_node: &str,
    ) -> Result<(), LangGraphError> {
        for (from, targets) in edges {
            if from != start_node && from != end_node && !nodes.contains_key(from) {
                return Err(LangGraphError::GraphError(format!(
                    "Static edge source '{}' is not a registered node",
                    from
                )));
            }
            for target in targets {
                if target != start_node && target != end_node && !nodes.contains_key(target) {
                    return Err(LangGraphError::GraphError(format!(
                        "Static edge target '{}' (from '{}') is not a registered node",
                        target, from
                    )));
                }
            }
        }
        Ok(())
    }

    fn validate_conditional_edges_valid(
        conditional_edges: &HashMap<String, Vec<RouterFn<S>>>,
        nodes: &HashMap<String, Box<dyn AgentNode<S>>>,
        start_node: &str,
    ) -> Result<(), LangGraphError> {
        for from in conditional_edges.keys() {
            if from != start_node && !nodes.contains_key(from) {
                return Err(LangGraphError::GraphError(format!(
                    "Conditional edge source '{}' is not a registered node",
                    from
                )));
            }
        }
        Ok(())
    }

    fn validate_no_mixed_edge_types(
        edges: &HashMap<String, HashSet<String>>,
        conditional_edges: &HashMap<String, Vec<RouterFn<S>>>,
    ) -> Result<(), LangGraphError> {
        for from in edges.keys() {
            if conditional_edges.contains_key(from) {
                return Err(LangGraphError::GraphError(format!(
                    "Node '{}' cannot have both static edges and conditional edges",
                    from
                )));
            }
        }
        Ok(())
    }
}