Revised from direct source code analysis

COMPONENTS.md

@@ -0,0 +1,219 @@
+# LangGraph Components
+
+**Version:** 1.0.0  
+**Last Updated:** 2026-02-23
+
+---
+
+## Overview
+
+This document lists and describes the key components in the LangGraph codebase.
+
+---
+
+## Directory Structure
+
+```
+langgraph/libs/langgraph/langgraph/
+├── pregel/           # Core execution engine
+├── channels/         # Inter-node communication
+├── graph/            # Graph building DSL
+├── checkpoint/       # Persistence (in separate lib)
+├── managed/          # Managed values
+├── _internal/        # Internal utilities
+├── utils/           # Helper utilities
+├── types.py         # Core types
+├── config.py        # Configuration
+├── constants.py     # Constants
+└── errors.py       # Error definitions
+```
+
+---
+
+## Core Components
+
+### 1. Pregel Engine (`pregel/`)
+
+The heart of LangGraph - execution engine.
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| `main.py` | ~4400 | Public API, entry point |
+| `_loop.py` | ~1300 | Core PregelLoop class |
+| `_algo.py` | ~1500 | Task scheduling, write application |
+| `_runner.py` | ~1000 | Async execution |
+| `_read.py` | ~300 | PregelNode (node wrapper) |
+| `_write.py` | ~250 | Write application |
+| `_checkpoint.py` | ~100 | Checkpoint creation |
+| `_executor.py` | ~250 | Task execution |
+| `_retry.py` | ~250 | Retry logic |
+| `_validate.py` | ~150 | Graph validation |
+
+### 2. Channels (`channels/`)
+
+Inter-node communication.
+
+| File | Purpose |
+|------|---------|
+| `base.py` | Abstract BaseChannel |
+| `last_value.py` | LastValue channel |
+| `any_value.py` | AnyValue channel |
+| `topic.py` | Topic (pub/sub) |
+| `named_barrier_value.py` | Barrier synchronization |
+| `binop.py` | Binary operation |
+| `ephemeral_value.py` | One-time values |
+| `untracked_value.py` | Non-checkpointed values |
+
+### 3. Graph Building (`graph/`)
+
+DSL for building graphs.
+
+| File | Purpose |
+|------|---------|
+| `state.py` | StateGraph builder (~1800 lines) |
+| `_node.py` | Node definition |
+| `_branch.py` | Conditional edges |
+| `message.py` | Message graph utilities |
+| `ui.py` | Graph visualization |
+
+### 4. Core Types (`types.py`)
+
+~600 lines of type definitions.
+
+Key types:
+
+```python
+# Durability
+Durability = Literal["sync", "async", "exit"]
+
+# Checkpointer
+Checkpointer = None | bool | BaseCheckpointSaver
+
+# Streaming
+StreamMode = Literal["values", "updates", "checkpoints", "tasks", "debug"]
+
+# Execution
+class Send(NamedTuple):
+    node: str
+    arg: Any
+
+class Interrupt(NamedTuple):
+    value: Any
+    when: str
+
+class Command(NamedTuple):
+    update: dict | None
+    resume: dict | None
+```
+
+### 5. Errors (`errors.py`)
+
+```python
+class GraphRuntimeException(Exception):
+    """Base exception."""
+    pass
+
+class EmptyInputError(GraphRuntimeException):
+    """No input provided."""
+    pass
+
+class GraphInterrupt(GraphRuntimeException):
+    """Graph interrupted."""
+    pass
+```
+
+---
+
+## Public API
+
+### From `pregel/__init__.py`
+
+```python
+# Main classes
+class Pregel:
+    """Main graph executor."""
+    
+    def invoke(self, input: Any, config: RunnableConfig) -> Any: ...
+    def stream(self, input: Any, config: RunnableConfig) -> Iterator: ...
+    async def ainvoke(self, input: Any, config: RunnableConfig) -> Any: ...
+    async def astream(self, input: Any, config: RunnableConfig) -> AsyncIterator: ...
+    def get_state(self, config: RunnableConfig) -> StateSnapshot | None: ...
+    def get_state_history(self, config: RunnableConfig) -> Iterator[StateSnapshot]: ...
+    def update_state(self, config: RunnableConfig, values: dict) -> StateSnapshot: ...
+
+# Graph builders
+class StateGraph:
+    """Build a stateful graph."""
+    
+    def add_node(self, name: str, action: Callable) -> Self: ...
+    def add_edge(self, start: str, end: str) -> Self: ...
+    def add_conditional_edges(self, source: str, path: Callable) -> Self: ...
+    def compile(self) -> Pregel: ...
+```
+
+---
+
+## Configuration
+
+### RunnableConfig
+
+From `config.py`:
+
+```python
+class RunnableConfig:
+    """Configuration for graph execution."""
+    
+    configurable: dict = {}
+    tags: list[str] = []
+    metadata: dict = {}
+    recursion_limit: int = 25
+    max_concurrency: int = None
+```
+
+### Config Keys
+
+From `constants.py`:
+
+```python
+CONFIG_KEY_THREAD_ID = "thread_id"
+CONFIG_KEY_CHECKPOINT_ID = "checkpoint_id"
+CONFIG_KEY_CHECKPOINTER = "checkpointer"
+CONFIG_KEY_CHECKPOINT_MAP = "checkpoint_map"
+CONFIG_KEY_DURABILITY = "durability"
+CONFIG_KEY_RESUMING = "resuming"
+CONFIG_KEY_RESUME_MAP = "resume_map"
+```
+
+---
+
+## Dependencies
+
+### External
+
+- `langchain-core` — Core utilities
+- `langchain` — LangChain integration
+- `pydantic` — Type validation
+- `xxhash` — Fast hashing
+- `typing_extensions` — Type extensions
+
+### Internal
+
+- `langgraph.checkpoint.*` — Checkpoint backends
+- `langgraph.store` — Long-term storage
+
+---
+
+## Key Files Summary
+
+| Component | Main File | Key Classes |
+|-----------|-----------|--------------|
+| Execution | `pregel/main.py` | `Pregel` |
+| Loop | `pregel/_loop.py` | `PregelLoop` |
+| Channels | `channels/base.py` | `BaseChannel` |
+| Graph | `graph/state.py` | `StateGraph` |
+| Types | `types.py` | `Send`, `Interrupt`, `Command` |
+| Config | `config.py` | `RunnableConfig` |
+
+---
+
+*Generated from source code analysis*