Buckets:
AnonymousSpottedToad/candidate_bucket / codebase /python /alkimya_gathering /gathering /cache /redis_manager.py
| """ | |
| Redis Cache Manager for GatheRing. | |
| Provides high-performance caching for: | |
| - Embeddings (expensive API calls) | |
| - RAG search results | |
| - Circle context | |
| - LLM responses (optional) | |
| Design principles: | |
| - Simple API (get/set/delete) | |
| - Automatic TTL management | |
| - JSON serialization | |
| - Event-based invalidation | |
| - Graceful degradation (works without Redis) | |
| """ | |
| import os | |
| import json | |
| import hashlib | |
| from dataclasses import dataclass | |
| from typing import Any, Dict, List, Optional | |
| try: | |
| import redis | |
| from redis import Redis | |
| REDIS_AVAILABLE = True | |
| except ImportError: | |
| REDIS_AVAILABLE = False | |
| Redis = None | |
| class CacheConfig: | |
| """Configuration for Redis cache.""" | |
| # Connection | |
| host: str = "localhost" | |
| port: int = 6379 | |
| db: int = 0 | |
| password: Optional[str] = None | |
| # TTL defaults (in seconds) | |
| embedding_ttl: int = 86400 # 24 hours | |
| rag_results_ttl: int = 300 # 5 minutes | |
| circle_context_ttl: int = 600 # 10 minutes | |
| llm_response_ttl: int = 3600 # 1 hour | |
| # Behavior | |
| enabled: bool = True | |
| key_prefix: str = "gathering:" | |
| class CacheManager: | |
| """ | |
| Redis-based cache manager with graceful degradation. | |
| Features: | |
| - Automatic TTL management | |
| - JSON serialization | |
| - Key namespacing | |
| - Graceful degradation (no-op if Redis unavailable) | |
| - Event-based cache invalidation | |
| Example: | |
| cache = CacheManager.from_env() | |
| # Cache an embedding | |
| cache.set_embedding("Hello world", [0.1, 0.2, ...]) | |
| # Retrieve it | |
| embedding = cache.get_embedding("Hello world") | |
| # Cache RAG results | |
| cache.set_rag_results("query", agent_id=1, results=[...]) | |
| # Invalidate on memory change | |
| cache.invalidate_rag_results(agent_id=1) | |
| """ | |
| def __init__(self, config: CacheConfig): | |
| """ | |
| Initialize CacheManager. | |
| Args: | |
| config: Cache configuration. | |
| """ | |
| self.config = config | |
| self._client: Optional[Redis] = None | |
| self._enabled = config.enabled and REDIS_AVAILABLE | |
| if self._enabled: | |
| try: | |
| self._client = redis.Redis( | |
| host=config.host, | |
| port=config.port, | |
| db=config.db, | |
| password=config.password, | |
| decode_responses=False, # We handle JSON encoding | |
| ) | |
| # Test connection | |
| self._client.ping() | |
| except Exception as e: | |
| print(f"[CacheManager] Redis connection failed: {e}") | |
| print("[CacheManager] Running without cache (degraded mode)") | |
| self._enabled = False | |
| self._client = None | |
| def from_env(cls, dotenv_path: Optional[str] = None) -> "CacheManager": | |
| """ | |
| Create CacheManager from environment variables. | |
| Environment variables: | |
| - REDIS_HOST: Redis host (default: localhost) | |
| - REDIS_PORT: Redis port (default: 6379) | |
| - REDIS_DB: Redis database (default: 0) | |
| - REDIS_PASSWORD: Redis password (optional) | |
| - CACHE_ENABLED: Enable cache (default: true) | |
| Args: | |
| dotenv_path: Optional .env file path. | |
| Returns: | |
| Configured CacheManager. | |
| """ | |
| if dotenv_path: | |
| from dotenv import load_dotenv | |
| load_dotenv(dotenv_path) | |
| config = CacheConfig( | |
| host=os.getenv("REDIS_HOST", "localhost"), | |
| port=int(os.getenv("REDIS_PORT", "6379")), | |
| db=int(os.getenv("REDIS_DB", "0")), | |
| password=os.getenv("REDIS_PASSWORD"), | |
| enabled=os.getenv("CACHE_ENABLED", "true").lower() == "true", | |
| ) | |
| return cls(config) | |
| def _make_key(self, namespace: str, *parts: str) -> str: | |
| """ | |
| Create a namespaced cache key. | |
| Args: | |
| namespace: Key namespace (embedding, rag, circle, etc.) | |
| *parts: Key parts to join. | |
| Returns: | |
| Full cache key. | |
| Example: | |
| _make_key("embedding", "text_hash") → "gathering:embedding:text_hash" | |
| """ | |
| key = f"{self.config.key_prefix}{namespace}:" + ":".join(str(p) for p in parts) | |
| return key | |
| def _hash_text(self, text: str) -> str: | |
| """Create a hash of text for cache key.""" | |
| return hashlib.sha256(text.encode()).hexdigest()[:16] | |
| def _serialize(self, value: Any) -> bytes: | |
| """Serialize value to bytes.""" | |
| return json.dumps(value).encode('utf-8') | |
| def _deserialize(self, data: bytes) -> Any: | |
| """Deserialize bytes to value.""" | |
| if data is None: | |
| return None | |
| return json.loads(data.decode('utf-8')) | |
| # ========================================================================= | |
| # GENERIC CACHE OPERATIONS | |
| # ========================================================================= | |
| def get(self, key: str) -> Optional[Any]: | |
| """ | |
| Get value from cache. | |
| Args: | |
| key: Cache key. | |
| Returns: | |
| Cached value or None. | |
| """ | |
| if not self._enabled or not self._client: | |
| return None | |
| try: | |
| data = self._client.get(key) | |
| return self._deserialize(data) | |
| except Exception as e: | |
| print(f"[CacheManager] Get error: {e}") | |
| return None | |
| def set( | |
| self, | |
| key: str, | |
| value: Any, | |
| ttl: Optional[int] = None, | |
| ) -> bool: | |
| """ | |
| Set value in cache with TTL. | |
| Args: | |
| key: Cache key. | |
| value: Value to cache. | |
| ttl: Time-to-live in seconds (optional). | |
| Returns: | |
| True if cached successfully. | |
| """ | |
| if not self._enabled or not self._client: | |
| return False | |
| try: | |
| data = self._serialize(value) | |
| if ttl: | |
| self._client.setex(key, ttl, data) | |
| else: | |
| self._client.set(key, data) | |
| return True | |
| except Exception as e: | |
| print(f"[CacheManager] Set error: {e}") | |
| return False | |
| def delete(self, key: str) -> bool: | |
| """ | |
| Delete key from cache. | |
| Args: | |
| key: Cache key. | |
| Returns: | |
| True if deleted. | |
| """ | |
| if not self._enabled or not self._client: | |
| return False | |
| try: | |
| self._client.delete(key) | |
| return True | |
| except Exception as e: | |
| print(f"[CacheManager] Delete error: {e}") | |
| return False | |
| def delete_pattern(self, pattern: str) -> int: | |
| """ | |
| Delete all keys matching pattern. | |
| Args: | |
| pattern: Key pattern (e.g., "gathering:rag:agent:1:*") | |
| Returns: | |
| Number of keys deleted. | |
| """ | |
| if not self._enabled or not self._client: | |
| return 0 | |
| try: | |
| keys = self._client.keys(pattern) | |
| if keys: | |
| return self._client.delete(*keys) | |
| return 0 | |
| except Exception as e: | |
| print(f"[CacheManager] Delete pattern error: {e}") | |
| return 0 | |
| # ========================================================================= | |
| # EMBEDDING CACHE | |
| # ========================================================================= | |
| def get_embedding(self, text: str) -> Optional[List[float]]: | |
| """ | |
| Get cached embedding for text. | |
| Args: | |
| text: Text to get embedding for. | |
| Returns: | |
| Embedding vector or None. | |
| """ | |
| text_hash = self._hash_text(text) | |
| key = self._make_key("embedding", text_hash) | |
| return self.get(key) | |
| def set_embedding( | |
| self, | |
| text: str, | |
| embedding: List[float], | |
| ttl: Optional[int] = None, | |
| ) -> bool: | |
| """ | |
| Cache an embedding. | |
| Args: | |
| text: Text that was embedded. | |
| embedding: Embedding vector. | |
| ttl: Time-to-live (default: 24h). | |
| Returns: | |
| True if cached. | |
| """ | |
| text_hash = self._hash_text(text) | |
| key = self._make_key("embedding", text_hash) | |
| ttl = ttl or self.config.embedding_ttl | |
| return self.set(key, embedding, ttl) | |
| # ========================================================================= | |
| # RAG RESULTS CACHE | |
| # ========================================================================= | |
| def get_rag_results( | |
| self, | |
| agent_id: int, | |
| query: str, | |
| ) -> Optional[List[Dict[str, Any]]]: | |
| """ | |
| Get cached RAG search results. | |
| Args: | |
| agent_id: Agent ID. | |
| query: Search query. | |
| Returns: | |
| Cached results or None. | |
| """ | |
| query_hash = self._hash_text(query) | |
| key = self._make_key("rag", "agent", str(agent_id), query_hash) | |
| return self.get(key) | |
| def set_rag_results( | |
| self, | |
| agent_id: int, | |
| query: str, | |
| results: List[Dict[str, Any]], | |
| ttl: Optional[int] = None, | |
| ) -> bool: | |
| """ | |
| Cache RAG search results. | |
| Args: | |
| agent_id: Agent ID. | |
| query: Search query. | |
| results: Search results. | |
| ttl: Time-to-live (default: 5min). | |
| Returns: | |
| True if cached. | |
| """ | |
| query_hash = self._hash_text(query) | |
| key = self._make_key("rag", "agent", str(agent_id), query_hash) | |
| ttl = ttl or self.config.rag_results_ttl | |
| return self.set(key, results, ttl) | |
| def invalidate_rag_results(self, agent_id: int) -> int: | |
| """ | |
| Invalidate all RAG results for an agent. | |
| Called when agent's memories change. | |
| Args: | |
| agent_id: Agent ID. | |
| Returns: | |
| Number of keys deleted. | |
| """ | |
| pattern = self._make_key("rag", "agent", str(agent_id), "*") | |
| return self.delete_pattern(pattern) | |
| # ========================================================================= | |
| # CIRCLE CONTEXT CACHE | |
| # ========================================================================= | |
| def get_circle_context(self, circle_id: int) -> Optional[Dict[str, Any]]: | |
| """ | |
| Get cached circle context. | |
| Args: | |
| circle_id: Circle ID. | |
| Returns: | |
| Circle context or None. | |
| """ | |
| key = self._make_key("circle", "context", str(circle_id)) | |
| return self.get(key) | |
| def set_circle_context( | |
| self, | |
| circle_id: int, | |
| context: Dict[str, Any], | |
| ttl: Optional[int] = None, | |
| ) -> bool: | |
| """ | |
| Cache circle context. | |
| Args: | |
| circle_id: Circle ID. | |
| context: Circle context data. | |
| ttl: Time-to-live (default: 10min). | |
| Returns: | |
| True if cached. | |
| """ | |
| key = self._make_key("circle", "context", str(circle_id)) | |
| ttl = ttl or self.config.circle_context_ttl | |
| return self.set(key, context, ttl) | |
| def invalidate_circle_context(self, circle_id: int) -> bool: | |
| """ | |
| Invalidate circle context. | |
| Called when circle state changes. | |
| Args: | |
| circle_id: Circle ID. | |
| Returns: | |
| True if invalidated. | |
| """ | |
| key = self._make_key("circle", "context", str(circle_id)) | |
| return self.delete(key) | |
| # ========================================================================= | |
| # LLM RESPONSE CACHE (Optional) | |
| # ========================================================================= | |
| def get_llm_response( | |
| self, | |
| prompt_hash: str, | |
| ) -> Optional[str]: | |
| """ | |
| Get cached LLM response. | |
| Args: | |
| prompt_hash: Hash of the prompt. | |
| Returns: | |
| Cached response or None. | |
| """ | |
| key = self._make_key("llm", prompt_hash) | |
| return self.get(key) | |
| def set_llm_response( | |
| self, | |
| prompt_hash: str, | |
| response: str, | |
| ttl: Optional[int] = None, | |
| ) -> bool: | |
| """ | |
| Cache LLM response. | |
| Args: | |
| prompt_hash: Hash of the prompt. | |
| response: LLM response. | |
| ttl: Time-to-live (default: 1h). | |
| Returns: | |
| True if cached. | |
| """ | |
| key = self._make_key("llm", prompt_hash) | |
| ttl = ttl or self.config.llm_response_ttl | |
| return self.set(key, response, ttl) | |
| # ========================================================================= | |
| # UTILITIES | |
| # ========================================================================= | |
| def clear_all(self) -> int: | |
| """ | |
| Clear all GatheRing cache. | |
| WARNING: This deletes all keys with the configured prefix. | |
| Returns: | |
| Number of keys deleted. | |
| """ | |
| pattern = f"{self.config.key_prefix}*" | |
| return self.delete_pattern(pattern) | |
| def get_stats(self) -> Dict[str, Any]: | |
| """ | |
| Get cache statistics. | |
| Returns: | |
| Dict with cache stats. | |
| """ | |
| if not self._enabled or not self._client: | |
| return { | |
| "enabled": False, | |
| "reason": "Redis unavailable or disabled", | |
| } | |
| try: | |
| info = self._client.info("stats") | |
| return { | |
| "enabled": True, | |
| "host": self.config.host, | |
| "port": self.config.port, | |
| "db": self.config.db, | |
| "total_keys": len(self._client.keys(f"{self.config.key_prefix}*")), | |
| "hits": info.get("keyspace_hits", 0), | |
| "misses": info.get("keyspace_misses", 0), | |
| "hit_rate": self._calculate_hit_rate(info), | |
| } | |
| except Exception as e: | |
| return { | |
| "enabled": True, | |
| "error": str(e), | |
| } | |
| def _calculate_hit_rate(self, info: Dict[str, Any]) -> float: | |
| """Calculate cache hit rate.""" | |
| hits = info.get("keyspace_hits", 0) | |
| misses = info.get("keyspace_misses", 0) | |
| total = hits + misses | |
| if total == 0: | |
| return 0.0 | |
| return round(hits / total * 100, 2) | |
| def is_enabled(self) -> bool: | |
| """Check if cache is enabled and working.""" | |
| return self._enabled | |
| def close(self) -> None: | |
| """Close Redis connection.""" | |
| if self._client: | |
| self._client.close() | |
Xet Storage Details
- Size:
- 14.5 kB
- Xet hash:
- 60166d4d40630b9befc94d3881356356282b16f875d433ebc5971f0b7c6ad059
·
Xet efficiently stores files, intelligently splitting them into unique chunks and accelerating uploads and downloads. More info.