agents.md

Author: lan17

AGENTS.md

@@ -8,13 +8,21 @@ gcache is a fine-grained caching library with multi-layer support (local + Redis
 
 ```
 src/gcache/
-├── __init__.py          # Public API exports
-├── base.py              # Core implementation (~1000 lines)
-└── event_loop_thread.py # Sync/async bridge for threading
+├── __init__.py              # Public API exports
+├── config.py                # GCacheKey, GCacheKeyConfig, GCacheConfig, RedisConfig, Serializer
+├── exceptions.py            # All exception classes
+├── gcache.py                # GCache main class and @cached decorator
+└── _internal/               # Implementation details (not public API)
+    ├── constants.py         # Named constants (cache sizes, TTLs, thresholds)
+    ├── event_loop_thread.py # EventLoopThread, EventLoopThreadPool
+    ├── local_cache.py       # LocalCache (TTLCache-based)
+    ├── metrics.py           # GCacheMetrics (Prometheus)
+    ├── redis_cache.py       # RedisCache
+    └── wrappers.py          # CacheController, CacheChain
+
 tests/
-├── conftest.py          # Fixtures (redis_server, gcache, cache_config_provider)
-├── test_gcache.py       # Main test suite
-└── test_*.py            # Specialized tests
+├── conftest.py              # Fixtures (redis_server, gcache, cache_config_provider)
+└── test_*.py                # Test suites
 ```
 
 ## Key Components
@@ -23,73 +31,40 @@ tests/
 - **CacheLayer**: Enum - `NOOP`, `LOCAL` (TTLCache), `REMOTE` (Redis)
 - **CacheChain**: Chains local → redis with read-through strategy
 - **EventLoopThreadPool**: Runs async code from sync cached functions (16 threads)
-- **GCacheKey**: URN-formatted cache keys with invalidation tracking
-
-## Core Pattern: @cached Decorator
-
-```python
-@gcache.cached(
-    key_type="user_id",           # Entity type
-    id_arg="user_id",             # Arg name for cache key
-    use_case="GetUser",           # Unique identifier
-    arg_adapters={"request": lambda r: r.id},  # Complex arg → string
-    ignore_args=["logger"],       # Args not in cache key
-)
-async def get_user(user_id: str, request: Request, logger: Logger) -> User:
-    ...
-```
+- **GCacheKey**: Frozen dataclass for cache keys (key_type, id, use_case, args)
 
 ## Critical Patterns
 
-1. **Context-based enable**: Cache is disabled by default
-   ```python
-   with gcache.enable():
-       result = cached_func()  # Actually uses cache
-   ```
+1. **Context-based enable**: Cache is disabled by default - use `with gcache.enable():`
 
-2. **Sync functions use thread pool**: Sync `@cached` functions run through `EventLoopThreadPool` to avoid blocking
+2. **Sync functions use thread pool**: Sync `@cached` functions run through `EventLoopThreadPool`
 
-3. **No reentrant sync calls**: Sync cached function calling another sync cached function raises `ReentrantSyncFunctionDetected` - convert to async
+3. **Don't call sync cached functions from async**: Blocks event loop (logs warning)
 
-4. **Thread-local Redis clients**: `RedisCache` stores client per-thread via `threading.local()`
+4. **No reentrant sync calls**: Raises `ReentrantSyncFunctionDetected` - convert to async
 
-5. **Watermark invalidation**: Uses timestamps to invalidate without deleting keys
+5. **Thread-local Redis clients**: `RedisCache` stores client per-thread via `threading.local()`
 
 ## Code Conventions
 
-- **Type hints required**: `mypy --disallow_untyped_defs`
-- **Line length**: 120 chars
-- **Linting**: ruff (E4, E7, E9, F, I, UP, ASYNC)
-- **Docstrings**: Numpy style
-- **Python**: 3.10+ (uses `|` union syntax)
+- Type hints required, line length 120, ruff + mypy
+- Python 3.10+ (uses `|` union syntax)
 
 ## Testing
 
-- pytest + pytest-asyncio
-- `redislite` for in-memory Redis
-- Always test both sync and async paths
-- Key fixtures: `gcache`, `redis_server`, `cache_config_provider`
-
-Run tests:
 ```bash
-pytest tests/
+poetry run pytest tests/
 ```
 
-## When Modifying
-
-1. **Update both sync/async paths** - changes typically affect both
-2. **Preserve context variables** - critical for `gcache.enable()` across threads
-3. **Test both redis_config and redis_client_factory paths**
-4. **Add Prometheus metrics** for new cache behaviors
-5. **Run pre-commit** - ruff format, mypy, poetry-check
-
 ## Common Gotchas
 
 - GCache is singleton - second instantiation raises `GCacheAlreadyInstantiated`
-- "watermark" is a reserved use_case name
-- Local cache cannot be invalidated (TTL-only expiration)
-- Large payloads (>50KB) serialize in executor to avoid blocking
+- "watermark" is reserved use_case name
+- Local cache cannot be invalidated across instances (TTL-only)
+- `WATERMARK_TTL_SECONDS` (4 hours) must exceed your longest cache TTL for invalidation to work
+- uvloop is optional - falls back to asyncio on Windows/PyPy
 
 ## Dependencies
 
-Core: pydantic, prometheus-client, cachetools, redis, uvloop
+Core: pydantic, prometheus-client, cachetools, redis
+Optional: uvloop