Weavegraph

Graph-driven, concurrent agent workflow framework for Rust.

---

Pre-1.0 Status
Weavegraph core APIs are stable and production-ready. However, as we approach 1.0, minor versions may introduce targeted refinements to APIs or behaviors. See MIGRATION.md for upgrade guidance between releases.
Your feedback shapes the future—please report issues and suggest improvements as you use the framework.

---

Weavegraph lets you build robust, concurrent, stateful workflows using a graph-based execution model. Ideal for AI agents, data pipelines, and any application needing versioned state and rich diagnostics.

Features

• Concurrent graph execution with dependency resolution
• Type-safe, role-based message system
• Versioned state with snapshot isolation
• Typed state slots for schema-versioned JSON payloads
• Structured error handling and diagnostics
• Built-in event streaming and observability
• Flexible persistence: SQLite, PostgreSQL, or in-memory
• Conditional routing and dynamic edges
• Iterative checkpointed sessions for repeated invocations
• Replay conformance helpers and deterministic graph/run metadata
• Ergonomic APIs and comprehensive examples

Install

Add to your Cargo.toml:

[dependencies]
weavegraph = "0.5"

Note: Examples and instructions in this README are current as of 0.5.x. For upgrade notes across pre-1.0 releases, see MIGRATION.md.

Dependency Compatibility

Weavegraph targets Rust 1.90+ (MSRV). The following table shows compatibility with key dependencies:

Rust Version	Tokio	Serde	SQLx
1.90 (MSRV)	1.40+	1.0+	0.8+
Stable	1.40+	1.0+	0.8+
Nightly	1.40+	1.0+	0.8+

Optional dependencies: SQLx 0.8 (postgres/sqlite features), miette 7.x (diagnostics feature), rig-core 0.30 (rig feature).

See Cargo.toml for complete dependency versions and feature configuration.

Documentation

• Quickstart - Fast path to building and running workflows
• Operations Guide - Event streaming, persistence, testing, and production
• Architecture - Core architecture and custom reducers
• Documentation Index - Complete topic reference with anchor links
• Examples - Runnable code for all patterns

Minimal Example

use weavegraph::{
    graphs::GraphBuilder,
    message::Message,
    node::{Node, NodeContext, NodePartial},
    state::VersionedState,
};
use async_trait::async_trait;

struct HelloNode;

#[async_trait]
impl Node for HelloNode {
    async fn run(
        &self,
        _snapshot: weavegraph::state::StateSnapshot,
        _ctx: NodeContext,
    ) -> Result<NodePartial, weavegraph::node::NodeError> {
        Ok(NodePartial::new().with_messages(vec![Message::assistant("Hello, world!")]))
    }
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    use weavegraph::types::NodeKind;
    let app = GraphBuilder::new()
        .add_node(NodeKind::Custom("hello".into()), HelloNode)
        .add_edge(NodeKind::Start, NodeKind::Custom("hello".into()))
        .add_edge(NodeKind::Custom("hello".into()), NodeKind::End)
        .compile()?;
    let state = VersionedState::new_with_user_message("Hi!");
    let result = app.invoke(state).await?;
    for message in result.messages.snapshot() {
        println!("{}: {}", message.role, message.content);
    }
    Ok(())
}

NOTE: NodeKind::Start and NodeKind::End are virtual structural endpoints.
You never register them with add_node; attempts to do so are ignored with a warning.

🧪 Testing

For testing and ephemeral workflows use the InMemory checkpointer:

use weavegraph::runtimes::{AppRunner, CheckpointerType};

// After compiling the graph into an `App`:
let runner = AppRunner::builder()
    .app(app)
    .checkpointer(CheckpointerType::InMemory)
    .build()
    .await;

Run the comprehensive test suite:

# Full integration test suite
cargo nextest run

# Documentation examples
cargo test --doc

# Lints used by CI
cargo clippy --all-features --all-targets -- -D warnings
cargo clippy --no-default-features --lib -- -D warnings

# Specific test categories
cargo test --test schedulers
cargo test --test event_bus
cargo test --test runtimes_runner

Property-based testing with proptest and fuzz harnesses under fuzz/ exercise edge cases across graph routing, event serialization, replay comparison, and typed state slots.

CI Parity

To minimize local/CI drift, this repository pins Rust with rust-toolchain.toml to 1.90.0 and runs required CI checks on that version.

Before opening a PR, run:

./scripts/ci-quick.sh

Before merging or cutting a release, run full local parity checks:

./scripts/ci-local.sh

ci-local.sh intentionally fails if required tools are missing (cargo-semver-checks, cargo-deny) so a local pass is a meaningful signal for CI.

Resources

• Migration Guide - Upgrade paths between pre-1.0 releases
• Architecture Guide - Deep dive into core design and internals
• Examples Directory - Runnable patterns: graph execution, scheduling, streaming, persistence, and more

Related Crates

• wg-ragsmith - Semantic chunking and RAG utilities for Weavegraph nodes

Contributing

We welcome contributions! See CONTRIBUTING.md.

License

MIT — see LICENSE.

🔗 Links

• Documentation
• Crates.io
• Repository
• Issues