claude-mpm 3.9.11__py3-none-any.whl → 4.0.3__py3-none-any.whl

claude_mpm/core/cache.py

@@ -1,3 +1,5 @@
+from pathlib import Path
+
 #!/usr/bin/env python3
 """File system caching with LRU eviction for performance optimization.
 
@@ -14,24 +16,23 @@ WHY file system caching:
 import asyncio
 import hashlib
 import json
-import os
 import pickle
 import threading
 import time
 from collections import OrderedDict
 from dataclasses import dataclass, field
 from datetime import datetime, timedelta
-from pathlib import Path
 from typing import Any, Callable, Dict, Optional, Tuple, TypeVar, Union
 
 from ..core.logger import get_logger
 
-T = TypeVar('T')
+T = TypeVar("T")
 
 
 @dataclass
 class CacheEntry:
     """Single cache entry with metadata."""
+
     key: str
     value: Any
     size: int
@@ -39,14 +40,14 @@ class CacheEntry:
     last_accessed: datetime = field(default_factory=datetime.now)
     access_count: int = 0
     ttl: Optional[float] = None
-    
+
     def is_expired(self) -> bool:
         """Check if entry has expired based on TTL."""
         if self.ttl is None:
             return False
         age = (datetime.now() - self.created_at).total_seconds()
         return age > self.ttl
-    
+
     def touch(self):
         """Update last access time and increment counter."""
         self.last_accessed = datetime.now()
@@ -56,12 +57,13 @@ class CacheEntry:
 @dataclass
 class CacheStats:
     """Cache performance statistics."""
+
     hits: int = 0
     misses: int = 0
     evictions: int = 0
     total_size: int = 0
     entry_count: int = 0
-    
+
     @property
     def hit_rate(self) -> float:
         """Calculate cache hit rate."""
@@ -71,19 +73,19 @@ class CacheStats:
 
 class FileSystemCache:
     """LRU cache for file system operations.
-    
+
     WHY this design:
     - OrderedDict provides O(1) LRU operations
     - Thread-safe with fine-grained locking
     - Memory-aware with size limits
     - TTL support for dynamic content
-    
+
     Example:
         cache = FileSystemCache(max_size_mb=100, default_ttl=300)
-        
+
         # Cache file content
         content = cache.get_file('/path/to/file.json')
-        
+
         # Cache expensive computation
         result = cache.get_or_compute(
             'expensive_key',
@@ -91,16 +93,16 @@ class FileSystemCache:
             ttl=60
         )
     """
-    
+
     def __init__(
         self,
         max_size_mb: float = 100,
         max_entries: int = 10000,
         default_ttl: Optional[float] = None,
-        persist_path: Optional[Path] = None
+        persist_path: Optional[Path] = None,
     ):
         """Initialize file system cache.
-        
+
         Args:
             max_size_mb: Maximum cache size in megabytes
             max_entries: Maximum number of cache entries
@@ -111,16 +113,16 @@ class FileSystemCache:
         self.max_entries = max_entries
         self.default_ttl = default_ttl
         self.persist_path = persist_path
-        
+
         self._cache: OrderedDict[str, CacheEntry] = OrderedDict()
         self._lock = threading.RLock()
         self._stats = CacheStats()
         self._logger = get_logger("fs_cache")
-        
+
         # Load persisted cache if available
         if persist_path and persist_path.exists():
             self._load_cache()
-    
+
     def _estimate_size(self, value: Any) -> int:
         """Estimate memory size of a value in bytes."""
         if isinstance(value, (str, bytes)):
@@ -137,13 +139,13 @@ class FileSystemCache:
                 return len(pickle.dumps(value))
             except:
                 return 100  # Default small size
-    
+
     def _evict_lru(self):
         """Evict least recently used entries to make space."""
         with self._lock:
             while self._cache and (
-                self._stats.total_size > self.max_size or
-                self._stats.entry_count > self.max_entries
+                self._stats.total_size > self.max_size
+                or self._stats.entry_count > self.max_entries
             ):
                 # Remove oldest entry (first in OrderedDict)
                 key, entry = self._cache.popitem(last=False)
@@ -151,37 +153,36 @@ class FileSystemCache:
                 self._stats.entry_count -= 1
                 self._stats.evictions += 1
                 self._logger.debug(f"Evicted cache entry: {key}")
-    
+
     def _evict_expired(self):
         """Remove expired entries from cache."""
         with self._lock:
             expired_keys = [
-                key for key, entry in self._cache.items()
-                if entry.is_expired()
+                key for key, entry in self._cache.items() if entry.is_expired()
             ]
-            
+
             for key in expired_keys:
                 entry = self._cache.pop(key)
                 self._stats.total_size -= entry.size
                 self._stats.entry_count -= 1
                 self._logger.debug(f"Expired cache entry: {key}")
-    
+
     def get(self, key: str) -> Optional[Any]:
         """Get value from cache.
-        
+
         Args:
             key: Cache key
-        
+
         Returns:
             Cached value or None if not found/expired
         """
         with self._lock:
             entry = self._cache.get(key)
-            
+
             if entry is None:
                 self._stats.misses += 1
                 return None
-            
+
             # Check expiration
             if entry.is_expired():
                 self._cache.pop(key)
@@ -189,70 +190,59 @@ class FileSystemCache:
                 self._stats.entry_count -= 1
                 self._stats.misses += 1
                 return None
-            
+
             # Update LRU order
             self._cache.move_to_end(key)
             entry.touch()
-            
+
             self._stats.hits += 1
             return entry.value
-    
-    def put(
-        self,
-        key: str,
-        value: Any,
-        ttl: Optional[float] = None
-    ) -> None:
+
+    def put(self, key: str, value: Any, ttl: Optional[float] = None) -> None:
         """Store value in cache.
-        
+
         Args:
             key: Cache key
             value: Value to cache
             ttl: Time-to-live in seconds (overrides default)
         """
         size = self._estimate_size(value)
-        
+
         # Don't cache if single item exceeds max size
         if size > self.max_size:
             self._logger.warning(f"Value too large to cache: {key} ({size} bytes)")
             return
-        
+
         with self._lock:
             # Remove existing entry if present
             if key in self._cache:
                 old_entry = self._cache.pop(key)
                 self._stats.total_size -= old_entry.size
                 self._stats.entry_count -= 1
-            
+
             # Create new entry
             entry = CacheEntry(
-                key=key,
-                value=value,
-                size=size,
-                ttl=ttl or self.default_ttl
+                key=key, value=value, size=size, ttl=ttl or self.default_ttl
             )
-            
+
             # Add to cache
             self._cache[key] = entry
             self._stats.total_size += size
             self._stats.entry_count += 1
-            
+
             # Evict if necessary
             self._evict_lru()
-    
+
     def get_or_compute(
-        self,
-        key: str,
-        compute_fn: Callable[[], T],
-        ttl: Optional[float] = None
+        self, key: str, compute_fn: Callable[[], T], ttl: Optional[float] = None
     ) -> T:
         """Get from cache or compute if missing.
-        
+
         Args:
             key: Cache key
             compute_fn: Function to compute value if not cached
             ttl: Time-to-live in seconds
-        
+
         Returns:
             Cached or computed value
         """
@@ -260,46 +250,46 @@ class FileSystemCache:
         value = self.get(key)
         if value is not None:
             return value
-        
+
         # Compute value
         value = compute_fn()
-        
+
         # Cache result
         self.put(key, value, ttl)
-        
+
         return value
-    
+
     def get_file(
         self,
         file_path: Union[str, Path],
-        mode: str = 'r',
-        encoding: str = 'utf-8',
-        ttl: Optional[float] = None
+        mode: str = "r",
+        encoding: str = "utf-8",
+        ttl: Optional[float] = None,
     ) -> Optional[Any]:
         """Get file content from cache or read from disk.
-        
+
         Args:
             file_path: Path to file
             mode: File open mode ('r' for text, 'rb' for binary)
             encoding: Text encoding (for text mode)
             ttl: Time-to-live in seconds
-        
+
         Returns:
             File content or None if file doesn't exist
         """
         file_path = Path(file_path)
-        
+
         # Generate cache key based on file path and modification time
         if file_path.exists():
             mtime = file_path.stat().st_mtime
             cache_key = f"file:{file_path}:{mtime}:{mode}"
         else:
             return None
-        
+
         def read_file():
             """Read file from disk."""
             try:
-                if 'b' in mode:
+                if "b" in mode:
                     with open(file_path, mode) as f:
                         return f.read()
                 else:
@@ -308,39 +298,37 @@ class FileSystemCache:
             except Exception as e:
                 self._logger.error(f"Failed to read file {file_path}: {e}")
                 return None
-        
+
         return self.get_or_compute(cache_key, read_file, ttl)
-    
+
     def get_json(
-        self,
-        file_path: Union[str, Path],
-        ttl: Optional[float] = None
+        self, file_path: Union[str, Path], ttl: Optional[float] = None
     ) -> Optional[Dict[str, Any]]:
         """Get JSON file content from cache or parse from disk.
-        
+
         Args:
             file_path: Path to JSON file
             ttl: Time-to-live in seconds
-        
+
         Returns:
             Parsed JSON or None if file doesn't exist/invalid
         """
-        content = self.get_file(file_path, mode='r', ttl=ttl)
+        content = self.get_file(file_path, mode="r", ttl=ttl)
         if content is None:
             return None
-        
+
         try:
             return json.loads(content)
         except json.JSONDecodeError as e:
             self._logger.error(f"Invalid JSON in {file_path}: {e}")
             return None
-    
+
     def invalidate(self, key: str) -> bool:
         """Remove entry from cache.
-        
+
         Args:
             key: Cache key to invalidate
-        
+
         Returns:
             True if entry was removed, False if not found
         """
@@ -351,44 +339,43 @@ class FileSystemCache:
                 self._stats.entry_count -= 1
                 return True
             return False
-    
+
     def invalidate_pattern(self, pattern: str) -> int:
         """Invalidate all keys matching pattern.
-        
+
         Args:
             pattern: Pattern to match (supports * wildcard)
-        
+
         Returns:
             Number of entries invalidated
         """
         import fnmatch
-        
+
         with self._lock:
             matching_keys = [
-                key for key in self._cache.keys()
-                if fnmatch.fnmatch(key, pattern)
+                key for key in self._cache.keys() if fnmatch.fnmatch(key, pattern)
             ]
-            
+
             count = 0
             for key in matching_keys:
                 if self.invalidate(key):
                     count += 1
-            
+
             return count
-    
+
     def clear(self):
         """Clear all cache entries."""
         with self._lock:
             self._cache.clear()
             self._stats = CacheStats()
             self._logger.info("Cache cleared")
-    
+
     def get_stats(self) -> Dict[str, Any]:
         """Get cache statistics."""
         with self._lock:
             # Clean up expired entries first
             self._evict_expired()
-            
+
             return {
                 "hits": self._stats.hits,
                 "misses": self._stats.misses,
@@ -396,38 +383,38 @@ class FileSystemCache:
                 "evictions": self._stats.evictions,
                 "entry_count": self._stats.entry_count,
                 "total_size_mb": self._stats.total_size / (1024 * 1024),
-                "max_size_mb": self.max_size / (1024 * 1024)
+                "max_size_mb": self.max_size / (1024 * 1024),
             }
-    
+
     def _save_cache(self):
         """Persist cache to disk."""
         if not self.persist_path:
             return
-        
+
         try:
             self.persist_path.parent.mkdir(parents=True, exist_ok=True)
-            with open(self.persist_path, 'wb') as f:
+            with open(self.persist_path, "wb") as f:
                 pickle.dump(self._cache, f)
             self._logger.debug(f"Cache persisted to {self.persist_path}")
         except Exception as e:
             self._logger.error(f"Failed to persist cache: {e}")
-    
+
     def _load_cache(self):
         """Load cache from disk."""
         if not self.persist_path or not self.persist_path.exists():
             return
-        
+
         try:
-            with open(self.persist_path, 'rb') as f:
+            with open(self.persist_path, "rb") as f:
                 loaded_cache = pickle.load(f)
-            
+
             # Rebuild cache with validation
             for key, entry in loaded_cache.items():
                 if not entry.is_expired():
                     self._cache[key] = entry
                     self._stats.total_size += entry.size
                     self._stats.entry_count += 1
-            
+
             self._logger.info(f"Loaded {len(self._cache)} entries from cache")
         except Exception as e:
             self._logger.error(f"Failed to load cache: {e}")
@@ -435,82 +422,67 @@ class FileSystemCache:
 
 class AsyncFileSystemCache:
     """Async version of FileSystemCache for async applications.
-    
+
     Provides non-blocking cache operations for async contexts.
     """
-    
+
     def __init__(
         self,
         max_size_mb: float = 100,
         max_entries: int = 10000,
-        default_ttl: Optional[float] = None
+        default_ttl: Optional[float] = None,
     ):
         self.sync_cache = FileSystemCache(
-            max_size_mb=max_size_mb,
-            max_entries=max_entries,
-            default_ttl=default_ttl
+            max_size_mb=max_size_mb, max_entries=max_entries, default_ttl=default_ttl
         )
         self._lock = asyncio.Lock()
         self._logger = get_logger("async_fs_cache")
-    
+
     async def get(self, key: str) -> Optional[Any]:
         """Get value from cache asynchronously."""
         async with self._lock:
             # Run in executor to avoid blocking
             loop = asyncio.get_event_loop()
             return await loop.run_in_executor(None, self.sync_cache.get, key)
-    
-    async def put(
-        self,
-        key: str,
-        value: Any,
-        ttl: Optional[float] = None
-    ) -> None:
+
+    async def put(self, key: str, value: Any, ttl: Optional[float] = None) -> None:
         """Store value in cache asynchronously."""
         async with self._lock:
             loop = asyncio.get_event_loop()
             await loop.run_in_executor(None, self.sync_cache.put, key, value, ttl)
-    
+
     async def get_or_compute(
-        self,
-        key: str,
-        compute_fn: Callable[[], T],
-        ttl: Optional[float] = None
+        self, key: str, compute_fn: Callable[[], T], ttl: Optional[float] = None
     ) -> T:
         """Get from cache or compute asynchronously."""
         # Try cache first
         value = await self.get(key)
         if value is not None:
             return value
-        
+
         # Compute value (handle both sync and async functions)
         if asyncio.iscoroutinefunction(compute_fn):
             value = await compute_fn()
         else:
             loop = asyncio.get_event_loop()
             value = await loop.run_in_executor(None, compute_fn)
-        
+
         # Cache result
         await self.put(key, value, ttl)
-        
+
         return value
-    
+
     async def get_file(
         self,
         file_path: Union[str, Path],
-        mode: str = 'r',
-        encoding: str = 'utf-8',
-        ttl: Optional[float] = None
+        mode: str = "r",
+        encoding: str = "utf-8",
+        ttl: Optional[float] = None,
     ) -> Optional[Any]:
         """Get file content asynchronously."""
         loop = asyncio.get_event_loop()
         return await loop.run_in_executor(
-            None,
-            self.sync_cache.get_file,
-            file_path,
-            mode,
-            encoding,
-            ttl
+            None, self.sync_cache.get_file, file_path, mode, encoding, ttl
         )
 
 
@@ -520,15 +492,14 @@ _async_cache: Optional[AsyncFileSystemCache] = None
 
 
 def get_file_cache(
-    max_size_mb: float = 100,
-    default_ttl: Optional[float] = 300
+    max_size_mb: float = 100, default_ttl: Optional[float] = 300
 ) -> FileSystemCache:
     """Get or create global file cache instance.
-    
+
     Args:
         max_size_mb: Maximum cache size in MB
         default_ttl: Default TTL in seconds
-    
+
     Returns:
         Global FileSystemCache instance
     """
@@ -537,60 +508,55 @@ def get_file_cache(
         # Use project cache directory
         cache_dir = Path.home() / ".claude-mpm" / "cache"
         cache_dir.mkdir(parents=True, exist_ok=True)
-        
+
         _file_cache = FileSystemCache(
             max_size_mb=max_size_mb,
             default_ttl=default_ttl,
-            persist_path=cache_dir / "fs_cache.pkl"
+            persist_path=cache_dir / "fs_cache.pkl",
         )
     return _file_cache
 
 
 def get_async_cache(
-    max_size_mb: float = 100,
-    default_ttl: Optional[float] = 300
+    max_size_mb: float = 100, default_ttl: Optional[float] = 300
 ) -> AsyncFileSystemCache:
     """Get or create global async cache instance."""
     global _async_cache
     if _async_cache is None:
         _async_cache = AsyncFileSystemCache(
-            max_size_mb=max_size_mb,
-            default_ttl=default_ttl
+            max_size_mb=max_size_mb, default_ttl=default_ttl
         )
     return _async_cache
 
 
-def cache_decorator(
-    ttl: Optional[float] = None,
-    key_prefix: str = ""
-):
+def cache_decorator(ttl: Optional[float] = None, key_prefix: str = ""):
     """Decorator for caching function results.
-    
+
     Args:
         ttl: Time-to-live in seconds
         key_prefix: Optional prefix for cache keys
-    
+
     Example:
         @cache_decorator(ttl=60)
         def expensive_function(param):
             return compute_result(param)
     """
+
     def decorator(func: Callable) -> Callable:
         cache = get_file_cache()
-        
+
         def wrapper(*args, **kwargs):
             # Generate cache key from function name and arguments
             key_parts = [key_prefix, func.__name__]
             key_parts.extend(str(arg) for arg in args)
             key_parts.extend(f"{k}={v}" for k, v in sorted(kwargs.items()))
             cache_key = ":".join(key_parts)
-            
+
             # Use cache
             return cache.get_or_compute(
-                cache_key,
-                lambda: func(*args, **kwargs),
-                ttl=ttl
+                cache_key, lambda: func(*args, **kwargs), ttl=ttl
             )
-        
+
         return wrapper
-    return decorator
+
+    return decorator