langgraph-checkpoint 0.1.0

# langgraph-rust

Rust 版 [LangGraph](https://github.com/langchain-ai/langgraph) 社区移植实现——有状态、图驱动的 Agent 工作流引擎。

> **免责声明**：本项目为社区维护的独立实现，**与 LangChain / LangGraph 官方无隶属关系**。API 与 Python 版 LangGraph 保持概念对齐，但不保证完全兼容。`0.1.x` 版本视为早期预览，公共 API 可能在次要版本中调整。

## 安装

在 `Cargo.toml` 中按需引入：

```toml
[dependencies]
langgraph-core = "0.1"
langgraph-pregel = "0.1"
langgraph-checkpoint = "0.1"
# 可选
langgraph-prebuilt = "0.1"
langgraph-checkpoint-sqlite = "0.1"
```

CLI 与 HTTP 服务：

```bash
cargo install langgraph-cli   # 二进制名: langgraph
cargo install langgraph-http  # 二进制名: langgraph-http
```

## 快速开始

```rust
use langgraph_core::{StateGraph, State};
use langgraph_pregel::SequentialExecutor;
use std::collections::BTreeMap;
use std::sync::Arc;
use serde_json::json;

let mut graph = StateGraph::new();
graph.add_node("append_b", Arc::new(|state: &State| {
    let text = state.get("text").and_then(|v| v.as_str()).unwrap_or("");
    Ok(BTreeMap::from([(String::from("text"), json!(format!("{text}b")))]))
}))?;
graph.set_entry_point("append_b");
graph.set_finish_point("append_b");

let compiled = graph.compile()?;
let result = SequentialExecutor.invoke(
    &compiled,
    BTreeMap::from([(String::from("text"), json!("a"))]),
)?;
assert_eq!(result.get("text"), Some(&json!("ab")));
# Ok::<(), Box<dyn std::error::Error>>(())
```

更多示例见 `crates/langgraph-pregel/examples/minimal_graph.rs` 与 `crates/langgraph-prebuilt/README.md`。

## 当前进度

- [x] Cargo workspace 初始化
- [x] 创建 `langgraph-core`、`langgraph-pregel`、`langgraph-checkpoint`
- [x] 最小 `StateGraph` builder + `compile`
- [x] 顺序执行器 `invoke`
- [x] `{"text":"ab"}` 最小示例测试
- [x] 统一错误类型 `GraphError` 与 `StateValue`
- [x] `CheckpointSaver` trait 草案 + `InMemorySaver`
- [x] `tests/compat/` 第一批 fixture
- [x] channel 抽象（`LastValue` / `BinaryOperatorAggregate` / `Topic`）与 superstep 执行
- [x] `versions_seen` / channel versioning 元数据链路
- [x] checkpoint 恢复闭环（`resume` / `resume_latest` / `pending_writes` materialize）
- [x] 显式中断与恢复（`interrupt_thread`）
- [x] `resume_latest` 最新 checkpoint 选择修复（按数值版本，不依赖返回顺序）
- [x] Phase 4 第一段：`Command::Interrupt` + runtime context 注入（兼容旧 `add_node`）
- [x] Phase 4 第二段：节点触发中断时自动持久化 checkpoint（可直接 resume）
- [x] Phase 4 第三段：`Command::Goto` + `add_conditional_edges` 条件路由衔接
- [x] Phase 4 第四段：组合命令（`GotoMany`/命令链）与 command trace 可观测性
- [x] Phase 4 第五段：命令策略层（`CommandPolicy`）+ bridge 审计钩子
- [x] Phase 5 第一段：异步入口（`ainvoke` / `aresume` 等）与同步语义对齐测试
- [x] Phase 5 第二段：`astream` 事件流模型（节点事件 / 状态片段 / 命令与中断事件）
- [x] Phase 5 第三段：checkpoint bridge thread 维度 `astream`（流式执行 + 自动落盘 + resume 闭环）
- [x] Phase 6：SQLite / Postgres checkpointer 及跨后端一致性测试
- [x] Phase 7 第一段：`langgraph-prebuilt` 最小闭环（`ToolNode` / `ValidationNode`）
- [x] Phase 7 第二段：`ToolNode` 高级能力（路由策略 / 错误策略 / 审计钩子）
- [x] Phase 7 第三段：`ValidationNode` 结构化规则集 + 可组合验证器 + 最小 `ReAct` 编排 API
- [x] Phase 7 第四段：默认 `planner/tool-calling` 模板 API（基于 `ReactAgentBuilder` 封装）
- [x] Phase 7 第五段：默认模板多工具策略（主工具 + 选择器 + 回退工具）
- [x] Phase 8 第一段：最小 `langgraph-cli`（JSON 输入 -> 执行 -> JSON 输出）
- [x] Phase 8 第二段：CLI 执行元数据输出（`--metadata`）
- [x] Phase 8 第三段：CLI 流式事件输出（`--stream` / JSONL）
- [x] Phase 8 第四段：图预设可发现性与输入校验提示（`--list-graphs` + 预设级校验）
- [x] Phase 8 第五段：thread/checkpoint 运行入口（`invoke_thread` / `resume_latest`）
- [x] Phase 8 第六段：thread 精准恢复入口（`resume` by checkpoint_id）
- [x] Phase 8 第七段：thread 显式中断入口（`interrupt_thread` + pending writes 注入）
- [x] Phase 8 第八段：thread 异步 CLI 入口（`--async` 对齐 async bridge）
- [x] crates.io 发布准备（LICENSE、元数据、crate 文档、字段稳定性约定）

## 目录

| Crate | 说明 |
|-------|------|
| `langgraph-core` | 图模型、状态容器、channel、运行时类型 |
| `langgraph-pregel` | Pregel 风格 superstep 执行器（同步 + 异步） |
| `langgraph-checkpoint` | checkpoint trait 与内存实现 |
| `langgraph-checkpoint-sqlite` | SQLite 持久化 |
| `langgraph-checkpoint-postgres` | PostgreSQL 持久化 |
| `langgraph-prebuilt` | `ToolNode` / `ValidationNode` / ReAct 模板（附稳定性约定） |
| `langgraph-cli` | 命令行入口（二进制名 `langgraph`） |
| `langgraph-http` | HTTP PoC（`POST /run`） |
| `tests/compat` | 跨语言行为对照样例 |

## 发布到 crates.io

按依赖顺序发布（每个 crate 执行 `cargo publish -p <name>`）：

1. `langgraph-core`
2. `langgraph-checkpoint`
3. `langgraph-pregel`、`langgraph-prebuilt`、`langgraph-checkpoint-sqlite`、`langgraph-checkpoint-postgres`
4. `langgraph-cli`、`langgraph-http`

发布前本地验证：

```bash
cargo test --workspace
cargo publish --dry-run -p langgraph-core
# ... 对其余 crate 重复
```

## 已知限制

- 无内置 LLM 提供商集成（需自行在节点中调用 LLM SDK）
- 与 Python LangGraph 的 compat fixture 仍较少
- HTTP 入口暂无 stream / SSE 模式

## 下一步

1. 评估 thread 模式下 `--stream` 的分阶段支持方案（含 checkpoint 落盘时机）
2. 为 HTTP 入口补充 stream 模式与 SSE/JSONL 输出选型评估
3. 扩充 `tests/compat/` 与 `examples/`

## License

MIT — 见 [LICENSE](LICENSE)。