empathy-framework 5.3.0__py3-none-any.whl → 5.4.0__py3-none-any.whl

empathy_os/cache/storage.py

@@ -1,285 +0,0 @@
-"""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 empathy_os.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: ~/.empathy/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),
-        }

empathy_os/cache_monitor.py

@@ -1,356 +0,0 @@
-"""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)