weavegraph 0.1.3

Graph-driven, concurrent agent workflow framework with versioned state, deterministic barrier merges, and rich diagnostics.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

# Weavegraph

[![Crates.io](https://img.shields.io/crates/v/weavegraph.svg)](https://crates.io/crates/weavegraph)
[![Documentation](https://docs.rs/weavegraph/badge.svg)](https://docs.rs/weavegraph)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

**Graph-driven, concurrent agent workflow framework for Rust.**

---

> **EARLY BETA**  
> This framework is in active development (v0.1.x). APIs are evolving rapidly, and **breaking changes will happen** between minor versions.  
> The core architecture is solid, but expect rough edges, API churn, and occasional surprises. Pin exact versions if stability matters.  
> Use in production at your own risk—or better yet, help us shape the future by reporting issues and suggesting improvements.

---

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
- Structured error handling and diagnostics
- Built-in event streaming and observability
- Flexible persistence: SQLite or in-memory
- Conditional routing and dynamic edges
- Ergonomic APIs and comprehensive examples

## Install

Add to your `Cargo.toml`:

```toml
[dependencies]
weavegraph = "0.1"
```

## Documentation

- **[Developer Guide](docs/GUIDE.md)** - Messages, state, and graph building
- **[Operations Guide](docs/OPERATIONS.md)** - Event streaming, persistence, testing, and production
- **[Architecture](docs/ARCHITECTURE.md)** - Core architecture and custom reducers
- **[Documentation Index](docs/INDEX.md)** - Complete topic reference with anchor links
- **[Examples](weavegraph/examples/)** - Runnable code for all patterns

## Minimal Example

```rust
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() -> miette::Result<()> {
        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:

```rust
// After compiling the graph into an `App`:
let runner = AppRunner::new(app, CheckpointerType::InMemory).await; // In-memory state
```

Run the comprehensive test suite:

```bash
# All tests with output
cargo test --all -- --nocapture

# Specific test categories
cargo test schedulers:: -- --nocapture
cargo test channels:: -- --nocapture
cargo test integration:: -- --nocapture
```

Property-based testing with `proptest` ensures correctness across edge cases.




## Contributing

We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT — see [LICENSE](LICENSE).

## 🔗 Links

- [Documentation](https://docs.rs/weavegraph)
- [Crates.io](https://crates.io/crates/weavegraph)
- [Repository](https://github.com/Idleness76/weavegraph)
- [Issues](https://github.com/Idleness76/weavegraph/issues)