attune-ai 2.0.0__py3-none-any.whl

attune/cache/storage.py

@@ -0,0 +1,285 @@
+"""Persistent disk storage for cache with TTL support.
+
+Provides hybrid in-memory + disk persistence for cache entries.
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+import json
+import logging
+import time
+from pathlib import Path
+from typing import Any
+
+from attune.config import _validate_file_path
+
+from .base import CacheEntry
+
+logger = logging.getLogger(__name__)
+
+
+class CacheStorage:
+    """Hybrid in-memory + disk cache storage with TTL.
+
+    Provides:
+    - In-memory LRU cache for fast access
+    - Persistent disk storage for cache survival across restarts
+    - TTL-based expiration
+    - Automatic cleanup of expired entries
+
+    Example:
+        storage = CacheStorage()
+        storage.put(entry)
+        entry = storage.get(cache_key)
+
+    """
+
+    def __init__(
+        self,
+        cache_dir: Path | None = None,
+        max_disk_mb: int = 500,
+        auto_save: bool = True,
+    ):
+        """Initialize cache storage.
+
+        Args:
+            cache_dir: Directory for cache files (default: ~/.attune/cache/).
+            max_disk_mb: Maximum disk cache size in MB.
+            auto_save: Automatically save to disk on put (default: True).
+
+        """
+        self.cache_dir = cache_dir or Path.home() / ".empathy" / "cache"
+        self.cache_file = self.cache_dir / "responses.json"
+        self.max_disk_mb = max_disk_mb
+        self.auto_save = auto_save
+
+        # Ensure cache directory exists
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+
+        # Load cache from disk
+        self._entries: dict[str, CacheEntry] = {}
+        self.load()
+
+        logger.debug(
+            f"CacheStorage initialized (dir: {self.cache_dir}, "
+            f"max: {max_disk_mb}MB, entries: {len(self._entries)})"
+        )
+
+    def load(self) -> int:
+        """Load cache from disk into memory.
+
+        Returns:
+            Number of entries loaded.
+
+        """
+        if not self.cache_file.exists():
+            logger.debug("No cache file found, starting fresh")
+            return 0
+
+        try:
+            with open(self.cache_file) as f:
+                data = json.load(f)
+
+            version = data.get("version", "unknown")
+            entries_data = data.get("entries", [])
+
+            # Load entries
+            loaded = 0
+            current_time = time.time()
+
+            for entry_data in entries_data:
+                entry = CacheEntry(
+                    key=entry_data["key"],
+                    response=entry_data["response"],
+                    workflow=entry_data["workflow"],
+                    stage=entry_data["stage"],
+                    model=entry_data["model"],
+                    prompt_hash=entry_data["prompt_hash"],
+                    timestamp=entry_data["timestamp"],
+                    ttl=entry_data.get("ttl"),
+                )
+
+                # Skip expired entries
+                if entry.is_expired(current_time):
+                    continue
+
+                self._entries[entry.key] = entry
+                loaded += 1
+
+            logger.info(
+                f"Loaded {loaded} cache entries from disk (version: {version}, "
+                f"skipped {len(entries_data) - loaded} expired)"
+            )
+            return loaded
+
+        except (json.JSONDecodeError, KeyError) as e:
+            logger.warning(f"Failed to load cache from disk: {e}")
+            return 0
+
+    def save(self) -> bool:
+        """Save cache to disk.
+
+        Returns:
+            True if saved successfully, False otherwise.
+
+        """
+        try:
+            # Prepare data
+            data = {
+                "version": "3.8.0",
+                "timestamp": time.time(),
+                "entries": [
+                    {
+                        "key": entry.key,
+                        "response": entry.response,
+                        "workflow": entry.workflow,
+                        "stage": entry.stage,
+                        "model": entry.model,
+                        "prompt_hash": entry.prompt_hash,
+                        "timestamp": entry.timestamp,
+                        "ttl": entry.ttl,
+                    }
+                    for entry in self._entries.values()
+                ],
+            }
+
+            # Write to disk
+            validated_path = _validate_file_path(str(self.cache_file))
+            with open(validated_path, "w") as f:
+                json.dump(data, f, indent=2)
+
+            logger.debug(f"Saved {len(self._entries)} cache entries to disk")
+            return True
+
+        except (OSError, TypeError, ValueError) as e:
+            logger.error(f"Failed to save cache to disk: {e}")
+            return False
+
+    def get(self, cache_key: str) -> CacheEntry | None:
+        """Get entry from storage.
+
+        Args:
+            cache_key: Cache key to lookup.
+
+        Returns:
+            CacheEntry if found and not expired, None otherwise.
+
+        """
+        if cache_key not in self._entries:
+            return None
+
+        entry = self._entries[cache_key]
+
+        # Check expiration
+        if entry.is_expired(time.time()):
+            del self._entries[cache_key]
+            return None
+
+        return entry
+
+    def put(self, entry: CacheEntry) -> None:
+        """Store entry in storage.
+
+        Args:
+            entry: CacheEntry to store.
+
+        """
+        self._entries[entry.key] = entry
+
+        # Auto-save to disk if enabled
+        if self.auto_save:
+            self.save()
+
+    def delete(self, cache_key: str) -> bool:
+        """Delete entry from storage.
+
+        Args:
+            cache_key: Key to delete.
+
+        Returns:
+            True if entry was deleted, False if not found.
+
+        """
+        if cache_key in self._entries:
+            del self._entries[cache_key]
+            if self.auto_save:
+                self.save()
+            return True
+        return False
+
+    def clear(self) -> int:
+        """Clear all entries.
+
+        Returns:
+            Number of entries cleared.
+
+        """
+        count = len(self._entries)
+        self._entries.clear()
+
+        if self.auto_save:
+            self.save()
+
+        return count
+
+    def evict_expired(self) -> int:
+        """Remove all expired entries.
+
+        Returns:
+            Number of entries evicted.
+
+        """
+        current_time = time.time()
+        expired_keys = [
+            key for key, entry in self._entries.items() if entry.is_expired(current_time)
+        ]
+
+        for key in expired_keys:
+            del self._entries[key]
+
+        if expired_keys and self.auto_save:
+            self.save()
+
+        return len(expired_keys)
+
+    def get_all(self) -> list[CacheEntry]:
+        """Get all non-expired entries.
+
+        Returns:
+            List of CacheEntry objects.
+
+        """
+        current_time = time.time()
+        return [entry for entry in self._entries.values() if not entry.is_expired(current_time)]
+
+    def size_mb(self) -> float:
+        """Estimate cache size in MB.
+
+        Returns:
+            Estimated size in megabytes.
+
+        """
+        if not self.cache_file.exists():
+            return 0.0
+
+        return self.cache_file.stat().st_size / (1024 * 1024)
+
+    def stats(self) -> dict[str, Any]:
+        """Get storage statistics.
+
+        Returns:
+            Dictionary with storage metrics.
+
+        """
+        current_time = time.time()
+        expired = sum(1 for entry in self._entries.values() if entry.is_expired(current_time))
+
+        return {
+            "total_entries": len(self._entries),
+            "expired_entries": expired,
+            "active_entries": len(self._entries) - expired,
+            "disk_size_mb": round(self.size_mb(), 2),
+            "max_disk_mb": self.max_disk_mb,
+            "cache_dir": str(self.cache_dir),
+        }

attune/cache_monitor.py

@@ -0,0 +1,356 @@
+"""Cache Performance Monitoring
+
+Tracks cache hit rates, memory usage, and performance metrics for all caches
+in the Empathy Framework.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+
+@dataclass
+class CacheStats:
+    """Statistics for a single cache.
+
+    Tracks hits, misses, evictions, and calculates derived metrics like hit rate.
+    """
+
+    name: str
+    hits: int = 0
+    misses: int = 0
+    evictions: int = 0
+    size: int = 0
+    max_size: int = 0
+    created_at: datetime = field(default_factory=datetime.now)
+    last_updated: datetime = field(default_factory=datetime.now)
+
+    @property
+    def total_requests(self) -> int:
+        """Total cache requests (hits + misses)."""
+        return self.hits + self.misses
+
+    @property
+    def hit_rate(self) -> float:
+        """Cache hit rate (0.0-1.0)."""
+        if self.total_requests == 0:
+            return 0.0
+        return self.hits / self.total_requests
+
+    @property
+    def miss_rate(self) -> float:
+        """Cache miss rate (0.0-1.0)."""
+        return 1.0 - self.hit_rate
+
+    @property
+    def utilization(self) -> float:
+        """Cache utilization (0.0-1.0)."""
+        if self.max_size == 0:
+            return 0.0
+        return self.size / self.max_size
+
+    def record_hit(self) -> None:
+        """Record a cache hit."""
+        self.hits += 1
+        self.last_updated = datetime.now()
+
+    def record_miss(self) -> None:
+        """Record a cache miss."""
+        self.misses += 1
+        self.last_updated = datetime.now()
+
+    def record_eviction(self) -> None:
+        """Record a cache eviction."""
+        self.evictions += 1
+        self.last_updated = datetime.now()
+
+    def update_size(self, size: int, max_size: int | None = None) -> None:
+        """Update cache size metrics."""
+        self.size = size
+        if max_size is not None:
+            self.max_size = max_size
+        self.last_updated = datetime.now()
+
+    def to_dict(self) -> dict[str, Any]:
+        """Export statistics as dictionary."""
+        return {
+            "name": self.name,
+            "hits": self.hits,
+            "misses": self.misses,
+            "evictions": self.evictions,
+            "total_requests": self.total_requests,
+            "hit_rate": round(self.hit_rate, 4),
+            "miss_rate": round(self.miss_rate, 4),
+            "size": self.size,
+            "max_size": self.max_size,
+            "utilization": round(self.utilization, 4),
+            "created_at": self.created_at.isoformat(),
+            "last_updated": self.last_updated.isoformat(),
+        }
+
+
+class CacheMonitor:
+    """Global cache monitoring system.
+
+    Tracks performance of all caches in the framework. Provides centralized
+    reporting and analysis of cache effectiveness.
+
+    Example:
+        >>> monitor = CacheMonitor.get_instance()
+        >>> monitor.register_cache("ast_parse", max_size=500)
+        >>>
+        >>> # Record cache operations
+        >>> monitor.record_hit("ast_parse")
+        >>> monitor.record_miss("ast_parse")
+        >>>
+        >>> # Get statistics
+        >>> stats = monitor.get_stats("ast_parse")
+        >>> print(f"Hit rate: {stats.hit_rate:.1%}")
+        >>>
+        >>> # Generate report
+        >>> print(monitor.get_report())
+    """
+
+    _instance: "CacheMonitor | None" = None
+
+    def __init__(self):
+        """Initialize cache monitor."""
+        self._caches: dict[str, CacheStats] = {}
+
+    @classmethod
+    def get_instance(cls) -> "CacheMonitor":
+        """Get or create singleton instance."""
+        if cls._instance is None:
+            cls._instance = CacheMonitor()
+        return cls._instance
+
+    @classmethod
+    def reset_instance(cls) -> None:
+        """Reset singleton instance (for testing)."""
+        cls._instance = None
+
+    def register_cache(
+        self,
+        name: str,
+        max_size: int = 0,
+    ) -> CacheStats:
+        """Register a new cache for monitoring.
+
+        Args:
+            name: Unique cache identifier
+            max_size: Maximum cache size (0 = unlimited)
+
+        Returns:
+            CacheStats object for this cache
+
+        Raises:
+            ValueError: If cache name already exists
+        """
+        if name in self._caches:
+            raise ValueError(f"Cache '{name}' already registered")
+
+        stats = CacheStats(name=name, max_size=max_size)
+        self._caches[name] = stats
+        return stats
+
+    def get_stats(self, name: str) -> CacheStats | None:
+        """Get statistics for a specific cache.
+
+        Args:
+            name: Cache identifier
+
+        Returns:
+            CacheStats object or None if not found
+        """
+        return self._caches.get(name)
+
+    def record_hit(self, name: str) -> None:
+        """Record a cache hit.
+
+        Args:
+            name: Cache identifier
+        """
+        if stats := self._caches.get(name):
+            stats.record_hit()
+
+    def record_miss(self, name: str) -> None:
+        """Record a cache miss.
+
+        Args:
+            name: Cache identifier
+        """
+        if stats := self._caches.get(name):
+            stats.record_miss()
+
+    def record_eviction(self, name: str) -> None:
+        """Record a cache eviction.
+
+        Args:
+            name: Cache identifier
+        """
+        if stats := self._caches.get(name):
+            stats.record_eviction()
+
+    def update_size(self, name: str, size: int, max_size: int | None = None) -> None:
+        """Update cache size.
+
+        Args:
+            name: Cache identifier
+            size: Current cache size
+            max_size: Maximum cache size (optional)
+        """
+        if stats := self._caches.get(name):
+            stats.update_size(size, max_size)
+
+    def get_all_stats(self) -> dict[str, CacheStats]:
+        """Get statistics for all registered caches.
+
+        Returns:
+            Dict mapping cache names to CacheStats
+        """
+        return dict(self._caches)
+
+    def get_report(self, verbose: bool = False) -> str:
+        """Generate human-readable cache performance report.
+
+        Args:
+            verbose: Include detailed metrics
+
+        Returns:
+            Formatted report string
+        """
+        if not self._caches:
+            return "No caches registered"
+
+        lines = ["=" * 70, "CACHE PERFORMANCE REPORT", "=" * 70, ""]
+
+        # Sort by hit rate (descending)
+        sorted_caches = sorted(
+            self._caches.values(),
+            key=lambda s: s.hit_rate,
+            reverse=True,
+        )
+
+        for stats in sorted_caches:
+            lines.append(f"Cache: {stats.name}")
+            lines.append("-" * 70)
+            lines.append(f"  Hit Rate:        {stats.hit_rate:>6.1%}")
+            lines.append(f"  Total Requests:  {stats.total_requests:>8,}")
+            lines.append(f"  Hits:            {stats.hits:>8,}")
+            lines.append(f"  Misses:          {stats.misses:>8,}")
+
+            if verbose:
+                lines.append(f"  Evictions:       {stats.evictions:>8,}")
+                lines.append(f"  Size:            {stats.size:>8,}/{stats.max_size:<8,}")
+                lines.append(f"  Utilization:     {stats.utilization:>6.1%}")
+                lines.append(f"  Created:         {stats.created_at.strftime('%Y-%m-%d %H:%M:%S')}")
+                lines.append(
+                    f"  Last Updated:    {stats.last_updated.strftime('%Y-%m-%d %H:%M:%S')}"
+                )
+
+            lines.append("")
+
+        # Summary
+        total_requests = sum(s.total_requests for s in sorted_caches)
+        total_hits = sum(s.hits for s in sorted_caches)
+        overall_hit_rate = total_hits / total_requests if total_requests > 0 else 0.0
+
+        lines.append("=" * 70)
+        lines.append("SUMMARY")
+        lines.append("=" * 70)
+        lines.append(f"  Total Caches:    {len(self._caches)}")
+        lines.append(f"  Total Requests:  {total_requests:,}")
+        lines.append(f"  Overall Hit Rate: {overall_hit_rate:.1%}")
+        lines.append("=" * 70)
+
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Export all statistics as dictionary.
+
+        Returns:
+            Dict with all cache statistics
+        """
+        return {
+            "caches": {name: stats.to_dict() for name, stats in self._caches.items()},
+            "summary": {
+                "total_caches": len(self._caches),
+                "total_requests": sum(s.total_requests for s in self._caches.values()),
+                "total_hits": sum(s.hits for s in self._caches.values()),
+                "total_misses": sum(s.misses for s in self._caches.values()),
+                "overall_hit_rate": (
+                    sum(s.hits for s in self._caches.values())
+                    / sum(s.total_requests for s in self._caches.values())
+                    if sum(s.total_requests for s in self._caches.values()) > 0
+                    else 0.0
+                ),
+            },
+        }
+
+    def reset(self) -> None:
+        """Reset all cache statistics."""
+        self._caches.clear()
+
+    def get_high_performers(self, threshold: float = 0.6) -> list[CacheStats]:
+        """Get caches with hit rate above threshold.
+
+        Args:
+            threshold: Minimum hit rate (0.0-1.0)
+
+        Returns:
+            List of CacheStats with hit rate >= threshold, sorted by hit rate
+        """
+        # Use generator expression for memory efficiency
+        return sorted(
+            (s for s in self._caches.values() if s.hit_rate >= threshold),
+            key=lambda s: s.hit_rate,
+            reverse=True,
+        )
+
+    def get_underperformers(self, threshold: float = 0.3) -> list[CacheStats]:
+        """Get caches with hit rate below threshold.
+
+        Args:
+            threshold: Maximum hit rate (0.0-1.0)
+
+        Returns:
+            List of CacheStats with hit rate <= threshold, sorted by hit rate
+        """
+        # Use generator expression for memory efficiency
+        return sorted(
+            (s for s in self._caches.values() if s.hit_rate <= threshold),
+            key=lambda s: s.hit_rate,
+        )
+
+    def get_size_report(self) -> str:
+        """Generate report on cache memory usage.
+
+        Returns:
+            Formatted string with memory usage details
+        """
+        lines = ["=" * 70, "CACHE SIZE REPORT", "=" * 70, ""]
+
+        total_used = 0
+        total_capacity = 0
+
+        for stats in sorted(self._caches.values(), key=lambda s: s.size, reverse=True):
+            used_pct = stats.utilization * 100
+            lines.append(
+                f"{stats.name:<30} {stats.size:>8,} / {stats.max_size:>8,}  ({used_pct:>5.1f}%)"
+            )
+            total_used += stats.size
+            total_capacity += stats.max_size
+
+        lines.append("=" * 70)
+        if total_capacity > 0:
+            lines.append(
+                f"{'TOTAL':<30} {total_used:>8,} / {total_capacity:>8,}  ({total_used / total_capacity * 100:>5.1f}%)"
+            )
+        else:
+            lines.append(f"{'TOTAL':<30} {total_used:>8,} / unlimited")
+        lines.append("=" * 70)
+
+        return "\n".join(lines)