|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Development Commands |
| 6 | + |
| 7 | +### Setup and Dependencies |
| 8 | +```bash |
| 9 | +make install # Install all dependencies with poetry |
| 10 | +make redis-start # Start Redis Stack container (includes RedisJSON and RediSearch) |
| 11 | +make redis-stop # Stop Redis container |
| 12 | +``` |
| 13 | + |
| 14 | +### Testing |
| 15 | +```bash |
| 16 | +make test # Run tests with verbose output |
| 17 | +make test-all # Run all tests including API tests |
| 18 | +pytest tests/test_specific.py # Run specific test file |
| 19 | +pytest tests/test_specific.py::test_function # Run specific test |
| 20 | +pytest --run-api-tests # Include API integration tests |
| 21 | +``` |
| 22 | + |
| 23 | +### Code Quality |
| 24 | +```bash |
| 25 | +make lint # Format code and run type checking |
| 26 | +make format # Format code with black and isort |
| 27 | +make check-types # Run mypy type checking |
| 28 | +make check # Run both linting and tests |
| 29 | +``` |
| 30 | + |
| 31 | +### Development |
| 32 | +```bash |
| 33 | +make clean # Remove cache and build artifacts |
| 34 | +``` |
| 35 | + |
| 36 | +## Architecture Overview |
| 37 | + |
| 38 | +### Core Components |
| 39 | + |
| 40 | +**Checkpoint Savers** (`langgraph/checkpoint/redis/`): |
| 41 | +- `base.py`: `BaseRedisSaver` - Abstract base class with shared Redis operations, schemas, and TTL management |
| 42 | +- `__init__.py`: `RedisSaver` - Standard sync implementation |
| 43 | +- `aio.py`: `AsyncRedisSaver` - Async implementation |
| 44 | +- `shallow.py` / `ashallow.py`: Shallow variants that store only latest checkpoint |
| 45 | + |
| 46 | +**Stores** (`langgraph/store/redis/`): |
| 47 | +- `base.py`: `BaseRedisStore` - Abstract base with Redis operations, vector search, and TTL support |
| 48 | +- `__init__.py`: `RedisStore` - Sync store with key-value and vector search |
| 49 | +- `aio.py`: `AsyncRedisStore` - Async store implementation |
| 50 | + |
| 51 | +### Key Architecture Patterns |
| 52 | + |
| 53 | +**Dual Implementation Strategy**: Each major component has both sync and async variants that share common base classes. The base classes (`BaseRedisSaver`, `BaseRedisStore`) contain the bulk of the business logic, while concrete implementations handle Redis client management and specific I/O patterns. |
| 54 | + |
| 55 | +**Redis Module Dependencies**: The library requires RedisJSON and RediSearch modules. Redis 8.0+ includes these by default; earlier versions need Redis Stack. All operations use structured JSON storage with search indices for efficient querying. |
| 56 | + |
| 57 | +**Schema-Driven Indexing**: Both checkpoints and stores use predefined schemas (`SCHEMAS` constants) that define Redis Search indices. Checkpoint indices track thread/namespace/version hierarchies; store indices support both key-value lookup and optional vector similarity search. |
| 58 | + |
| 59 | +**TTL Integration**: Native Redis TTL support is integrated throughout, with configurable defaults and refresh-on-read capabilities. TTL applies to all related keys (main document, vectors, writes) atomically. |
| 60 | + |
| 61 | +**Cluster Support**: Full Redis Cluster support with automatic detection and cluster-aware operations (individual key operations vs. pipelined operations). |
| 62 | + |
| 63 | +**Type System**: Heavy use of generics (`BaseRedisSaver[RedisClientType, IndexType]`) to maintain type safety across sync/async variants while sharing implementation code. |
| 64 | + |
| 65 | +### Redis Key Patterns |
| 66 | +- Checkpoints: `checkpoint:{thread_id}:{namespace}:{checkpoint_id}` |
| 67 | +- Checkpoint blobs: `checkpoint_blob:{thread_id}:{namespace}:{channel}:{version}` |
| 68 | +- Checkpoint writes: `checkpoint_write:{thread_id}:{namespace}:{checkpoint_id}:{task_id}` |
| 69 | +- Store items: `store:{uuid}` |
| 70 | +- Store vectors: `store_vectors:{uuid}` |
| 71 | + |
| 72 | +### Testing Strategy |
| 73 | +Tests are organized by functionality: |
| 74 | +- `test_sync.py` / `test_async.py`: Core checkpoint functionality |
| 75 | +- `test_store.py` / `test_async_store.py`: Store operations |
| 76 | +- `test_cluster_mode.py`: Redis Cluster specific tests |
| 77 | +- `test_*_ttl.py`: TTL functionality |
| 78 | +- `test_key_parsing.py`: Key generation and parsing logic |
| 79 | +- `test_semantic_search_*.py`: Vector search capabilities |
| 80 | + |
| 81 | +### Important Dependencies |
| 82 | +- Requires Redis with RedisJSON and RediSearch modules |
| 83 | +- Uses `redisvl` for vector operations and search index management |
| 84 | +- Uses `python-ulid` for unique document IDs |
| 85 | +- Integrates with LangGraph's checkpoint and store base classes |
0 commit comments