langgraph4rust 0.1.1

A powerful Rust implementation of a stateful workflow engine inspired by Python's LangGraph
Documentation

langgraph4rust πŸ¦€

CI Crates.io Docs.rs Downloads License: Apache 2.0 Rust

A powerful Rust implementation of a stateful workflow engine inspired by Python's LangGraph library.

langgraph4rust provides a flexible, type-safe, and async-first framework for building, executing, and managing complex workflow graphs with support for parallel execution and conditional routing.

✨ Features

  • πŸ—οΈ Declarative Graph Building: Define workflows using an intuitive builder pattern
  • ⚑ Parallel Execution: Multiple nodes can execute simultaneously when dependencies allow
  • πŸ”€ Conditional Routing: Dynamic path selection based on runtime state conditions
  • πŸ’Ύ State Management: Built-in JSON-based state persistence with full type safety
  • πŸ”Œ Extensible Architecture: Custom node implementations via traits
  • βœ… Comprehensive Validation: Graph structure validation before execution prevents runtime errors
  • 🎯 Async-First Design: Built on Tokio for efficient asynchronous operations

πŸ“¦ Installation

Add this to your Cargo.toml:

[dependencies]
langgraph4rust = "0.1.1"

πŸš€ Quick Start

Basic Example

use langgraph4rust::*;
use std::collections::HashSet;
use std::sync::Arc;
use async_trait::async_trait;

// Define a custom node
#[derive(Clone)]
struct GreetingNode;

#[async_trait]
impl AgentNode<DefaultMemoryState> for GreetingNode {
    async fn apply(&self, state: Arc<DefaultMemoryState>) -> Result<(), LangGraphError> {
        let message = "Hello from langgraph4rust! πŸš€";
        println!("{}", message);
        state.set("greeting", message).await?;
        Ok(())
    }
}

#[tokio::main]
async fn main() -> Result<(), LangGraphError> {
    // Create graph builder
    let mut builder = StateGraphBuilder::new();

    // Add nodes to the graph
    builder.add_node("greet", Box::new(GreetingNode));

    // Define edges (workflow connections)
    builder.add_edge(START_NODE, HashSet::from(["greet".to_string()]));
    builder.add_edge("greet", HashSet::from([END_NODE.to_string()]));

    // Compile and execute
    let graph = builder.compile()?;
    let state = Arc::new(DefaultMemoryState::new());
    
    graph.invoke(state).await?;
    
    Ok(())
}

Run this example:

cargo run --example hello_world

🎯 Core Concepts

Nodes πŸ”·

Nodes are the fundamental building blocks of your workflow. Each node implements the [AgentNode] trait and contains logic to process and modify the shared state.

#[derive(Clone)]
struct MyNode;

#[async_trait]
impl AgentNode<DefaultMemoryState> for MyNode {
    async fn apply(&self, state: Arc<DefaultMemoryState>) -> Result<(), LangGraphError> {
        // Your node logic here
        state.set("result", "processed").await?;
        Ok(())
    }
}

Edges ➑️

Edges define the control flow between nodes:

  • Static edges: Always connect to fixed target nodes
  • Conditional edges: Dynamically choose targets based on current state
// Static edge
builder.add_edge("node_a", HashSet::from(["node_b".to_string()]));

// Conditional routing (see conditional_routing example)
builder.add_conditional_edges(
    "decision_node",
    |state| async move { /* routing logic */ },
    HashMap::from([
        ("option_a".to_string(), HashSet::from(["node_x".to_string()])),
        ("option_b".to_string(), HashSet::from(["node_y".to_string()])),
    ])
)?;

State πŸ’Ύ

The state is shared across all nodes and persists throughout execution:

let state = Arc::new(DefaultMemoryState::new());

// Set values
state.set("key", "value").await?;

// Get typed values
let value: String = state.get("key").await?.unwrap();

πŸ“š Examples

Explore the examples/ directory for complete working examples:

Example Description
hello_world Simple linear workflow - perfect starting point
conditional_routing Dynamic path selection based on state
parallel_execution Concurrent node execution
custom_state Implementing custom state backends
data_pipeline Multi-stage data processing pipeline
error_handling Robust error handling strategies

Run any example:

cargo run --example <example_name>

πŸ—οΈ Architecture

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚              StateGraphBuilder              β”‚
β”‚  (Declarative graph construction API)       β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                   β”‚ compile()
                   β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚               StateGraph                    β”‚
β”‚  (Validated, executable workflow)           β”‚
β”‚  β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”   β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”  β”‚
β”‚  β”‚ Node A  │──▢│ Node B  │──▢│ Node C  β”‚  β”‚
β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜   β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β”‚
β”‚         β–²                         β”‚        β”‚
β”‚         └──────────(state)β”€β”€β”€β”€β”€β”€β”€β”€β”˜        β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                   β”‚ invoke()
                   β–Ό
β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚          DefaultMemoryState                 β”‚
β”‚  (JSON-based persistent state storage)      β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

πŸ”§ API Reference

Core Types

Key Methods

// Building graphs
StateGraphBuilder::new()                          // Create new builder
builder.add_node(name, node)                      // Add a node
builder.add_edge(from, to)                        // Add static edge
builder.add_conditional_edges(from, router, map)  // Add conditional edge
builder.compile()                                 // Validate & build graph

// Executing workflows
graph.invoke(initial_state)                       // Run the workflow

// Managing state
state.set(key, value).await                       // Store value
state.get::<T>(key).await?                        // Retrieve typed value

πŸ§ͺ Testing

Run the test suite:

# Unit tests
cargo test

# Run specific example tests
cargo test --example hello_world

# Integration tests (if available)
cargo test --test integration_test

🀝 Contributing

Contributions are welcome! Please feel free to submit Pull Requests.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/langGraph4rust/langgraph4rust.git
cd langgraph4rust

# Build the project
cargo build

# Run examples
cargo run --example hello_world

# Run tests
cargo test

πŸ“‹ Requirements

  • Rust: 2024 edition or later
  • Tokio: Async runtime (included as dependency)
  • Platform: macOS, Linux, Windows (tested)

πŸ“„ License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

πŸ™ Acknowledgments

πŸ“ž Support


Built with ❀️ using Rust's type system and async capabilities