langgraph-architecture/COMPONENTS.md

# 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*