Initial LangGraph architecture blueprints

2026-02-23 12:59:30 -06:00
commit 6046a9a609
3 changed files with 491 additions and 0 deletions
@@ -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*