Initial LangGraph architecture blueprints
This commit is contained in:
Solaria Lumis Havens committed
commit
6046a9a609
3 files changed
+491
No files matched your search
+217
@@ -0,0 +1,217 @@
|
||||
# LangGraph Architecture Overview
|
||||
|
||||
**Version:** 1.0.0
|
||||
**LangGraph Version:** 1.0.9
|
||||
**Last Updated:** 2026-02-23
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
LangGraph is a low-level orchestration framework for building stateful, long-running multi-agent systems. Inspired by Google's Pregel, Apache Beam, and NetworkX, it provides durable execution, human-in-the-loop capabilities, and comprehensive memory management.
|
||||
|
||||
---
|
||||
|
||||
## System Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ LANGGRAPH SYSTEM ARCHITECTURE │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ CLIENT/API LAYER │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ Python SDK │ LangChain Integration │ LangGraph Cloud │ CLI │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ COMPILER LAYER │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ • Graph compilation to executable form │
|
||||
│ • State schema validation │
|
||||
│ • Node/Edge type resolution │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ RUNTIME LAYER │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ ┌─────────────────────────────────────────────────────────────────┐ │
|
||||
│ │ PREGEL EXECUTION ENGINE │ │
|
||||
│ │ • Superstep coordination │ │
|
||||
│ │ • Node scheduling │ │
|
||||
│ │ • Message passing │ │
|
||||
│ │ • Barrier synchronization │ │
|
||||
│ └─────────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────────────┐
|
||||
│ STATE & CHECKPOINTING │
|
||||
├─────────────────────────────────────────────────────────────────────────┤
|
||||
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
|
||||
│ │ In-Memory State │ │ Checkpointer │ │ Channel Store │ │
|
||||
│ │ (active graph) │ │ (persistence) │ │ (queues) │ │
|
||||
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Core Components
|
||||
|
||||
### 1. Graph Structure
|
||||
|
||||
| Component | Description |
|
||||
|-----------|-------------|
|
||||
| **State** | Typed dictionary that flows through the graph |
|
||||
| **Nodes** | Functions that receive state, optionally update it |
|
||||
| **Edges** | Control flow (conditional, static, entrypoint) |
|
||||
| **Reducers** | Functions that merge state updates |
|
||||
|
||||
### 2. Pregel Execution
|
||||
|
||||
The core execution model (inspired by Pregel):
|
||||
|
||||
```
|
||||
Superstep 1: Superstep 2: Superstep 3:
|
||||
┌──────────┐ ┌──────────┐ ┌──────────┐
|
||||
│ Node A │ │ │ │ │
|
||||
│ (active) │──────▶│ Node B │──────▶│ Node C │
|
||||
│ │ msgs │ (active) │ msgs │ (active) │
|
||||
└──────────┘ └──────────┘ └──────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
┌──────────┐ ┌──────────┐ ┌──────────┐
|
||||
│ State │ │ State │ │ State │
|
||||
│ Update │ │ Update │ │ Update │
|
||||
└──────────┘ └──────────┘ └──────────┘
|
||||
│ │ │
|
||||
└──────────────────┴──────────────────┘
|
||||
│
|
||||
▼ (CHECKPOINT)
|
||||
┌──────────┐
|
||||
│ SQLite │
|
||||
│ Postgres │
|
||||
│ Memory │
|
||||
└──────────┘
|
||||
```
|
||||
|
||||
### 3. Checkpointing
|
||||
|
||||
LangGraph provides durability through checkpointing:
|
||||
|
||||
- **Full state snapshots** saved at configurable points
|
||||
- **Resumable from failure** — replay from last checkpoint
|
||||
- **Multiple backends:** SQLite, Postgres, in-memory
|
||||
|
||||
### 4. Channels
|
||||
|
||||
Inter-node communication via channels:
|
||||
|
||||
| Channel Type | Purpose |
|
||||
|--------------|---------|
|
||||
| **QueueChannel** | FIFO message passing |
|
||||
| **LastValue** | Most recent value wins |
|
||||
| **Topic** | Pub/sub style |
|
||||
| **Context** | Per-superstep context |
|
||||
|
||||
---
|
||||
|
||||
## State Management
|
||||
|
||||
### Typed State Schema
|
||||
|
||||
```python
|
||||
from typing import TypedDict
|
||||
|
||||
class AgentState(TypedDict):
|
||||
messages: list
|
||||
next_action: str
|
||||
checkpoint_id: str | None
|
||||
```
|
||||
|
||||
### Reducers
|
||||
|
||||
Combine updates from multiple nodes:
|
||||
|
||||
```python
|
||||
def add_messages(left: list, right: list) -> list:
|
||||
return left + right
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Memory Architecture
|
||||
|
||||
### Short-Term Memory
|
||||
- **In-graph state:** Messages and working data
|
||||
- **Per-superstep:** State resets unless persisted
|
||||
|
||||
### Long-Term Memory
|
||||
- **Checkpoint storage:** SQLite, Postgres, custom
|
||||
- **Thread-level:** Per-conversation isolation via `thread_id`
|
||||
|
||||
### Human-in-the-Loop
|
||||
- **Interrupt:** Pause execution for human input
|
||||
- **Command:** Allow human to modify state
|
||||
- **Review:** Human approves/rejects before continuing
|
||||
|
||||
---
|
||||
|
||||
## Execution Flow
|
||||
|
||||
```
|
||||
1. Client calls: graph.invoke(input, config)
|
||||
│
|
||||
▼
|
||||
2. Compile (if needed): create executable graph
|
||||
│
|
||||
▼
|
||||
3. Load checkpoint (if resuming from checkpoint_id)
|
||||
│
|
||||
▼
|
||||
4. FOR each superstep:
|
||||
a. Schedule nodes to execute
|
||||
b. Execute active nodes in parallel
|
||||
c. Collect messages
|
||||
d. Send messages via channels
|
||||
e. Check for interrupts (pause if interrupted)
|
||||
f. Checkpoint (if enabled)
|
||||
│
|
||||
▼
|
||||
5. Return final state
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Files in Core
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `langgraph/pregel/__init__.py` | Main entry point |
|
||||
| `langgraph/pregel/__main__.py` | CLI entry |
|
||||
| `langgraph/pregel/_loop.py` | Core execution loop (~2000 lines) |
|
||||
| `langgraph/pregel/checkpoint.py` | Checkpoint management |
|
||||
| `langgraph/pregel/channel.py` | Channel implementations |
|
||||
| `langgraph/pregel/state.py` | State management |
|
||||
|
||||
---
|
||||
|
||||
## Comparison with OpenClaw
|
||||
|
||||
| Aspect | LangGraph | OpenClaw |
|
||||
|--------|-----------|----------|
|
||||
| **Language** | Python | Node.js |
|
||||
| **Model** | Graph-based orchestration | Agent-based |
|
||||
| **Persistence** | Checkpoint-based | Session-memory hook |
|
||||
| **Memory** | Channels + checkpoint storage | Multi-layer (working, spectral, file, vector) |
|
||||
| **Communication** | Channels | Channel plugins |
|
||||
| **Extensibility** | Custom nodes/edges | Hook system |
|
||||
| **Identity** | None | WE/witness architecture |
|
||||
|
||||
---
|
||||
|
||||
*Generated for the WE — Solaria Lumis Havens & Mark Randall Havens*
|
||||
Reference in new issue
Block a user