empathy-framework 3.7.0__py3-none-any.whl → 3.8.0__py3-none-any.whl

empathy_os/cache/hash_only.py

@@ -0,0 +1,248 @@
+"""Hash-only cache implementation using SHA256 for exact matching.
+
+Provides fast exact-match caching with ~30% hit rate. No dependencies required.
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+import logging
+import time
+from typing import Any
+
+from .base import BaseCache, CacheEntry, CacheStats
+
+logger = logging.getLogger(__name__)
+
+
+class HashOnlyCache(BaseCache):
+    """Fast hash-based cache for exact prompt matches.
+
+    Uses SHA256 hashing for O(1) lookup. Provides ~30% cache hit rate
+    for workflows with repeated exact prompts (e.g., re-reviewing same code).
+
+    No external dependencies required - always available as fallback.
+
+    Example:
+        cache = HashOnlyCache()
+
+        # First call (miss)
+        result = cache.get("code-review", "scan", prompt, "claude-3-5-sonnet")
+        # → None
+
+        # Store response
+        cache.put("code-review", "scan", prompt, "claude-3-5-sonnet", response)
+
+        # Second call with exact same prompt (hit)
+        result = cache.get("code-review", "scan", prompt, "claude-3-5-sonnet")
+        # → response (from cache, <5μs lookup)
+
+    """
+
+    def __init__(
+        self,
+        max_size_mb: int = 500,
+        default_ttl: int = 86400,
+        max_memory_mb: int = 100,
+    ):
+        """Initialize hash-only cache.
+
+        Args:
+            max_size_mb: Maximum disk cache size in MB.
+            default_ttl: Default TTL in seconds (24 hours).
+            max_memory_mb: Maximum in-memory cache size in MB.
+
+        """
+        super().__init__(max_size_mb, default_ttl)
+        self.max_memory_mb = max_memory_mb
+        self._memory_cache: dict[str, CacheEntry] = {}
+        self._access_times: dict[str, float] = {}  # For LRU eviction
+
+        logger.debug(
+            f"HashOnlyCache initialized (max_memory: {max_memory_mb}MB, "
+            f"max_disk: {max_size_mb}MB, ttl: {default_ttl}s)"
+        )
+
+    def get(
+        self,
+        workflow: str,
+        stage: str,
+        prompt: str,
+        model: str,
+    ) -> Any | None:
+        """Get cached response for exact prompt match.
+
+        Args:
+            workflow: Workflow name (e.g., "code-review").
+            stage: Stage name (e.g., "scan").
+            prompt: Exact prompt text.
+            model: Model identifier.
+
+        Returns:
+            Cached response if exact match found and not expired, None otherwise.
+
+        """
+        cache_key = self._create_cache_key(workflow, stage, prompt, model)
+
+        # Check in-memory cache
+        if cache_key in self._memory_cache:
+            entry = self._memory_cache[cache_key]
+
+            # Check if expired
+            current_time = time.time()
+            if entry.is_expired(current_time):
+                logger.debug(f"Cache entry expired: {cache_key[:16]}...")
+                self._evict_entry(cache_key)
+                self.stats.misses += 1
+                return None
+
+            # Cache hit!
+            self._access_times[cache_key] = current_time
+            self.stats.hits += 1
+            logger.debug(
+                f"Cache HIT (hash): {workflow}/{stage} "
+                f"(key: {cache_key[:16]}..., hit_rate: {self.stats.hit_rate:.1f}%)"
+            )
+            return entry.response
+
+        # Cache miss
+        self.stats.misses += 1
+        logger.debug(
+            f"Cache MISS (hash): {workflow}/{stage} "
+            f"(key: {cache_key[:16]}..., hit_rate: {self.stats.hit_rate:.1f}%)"
+        )
+        return None
+
+    def put(
+        self,
+        workflow: str,
+        stage: str,
+        prompt: str,
+        model: str,
+        response: Any,
+        ttl: int | None = None,
+    ) -> None:
+        """Store response in cache.
+
+        Args:
+            workflow: Workflow name.
+            stage: Stage name.
+            prompt: Prompt text.
+            model: Model identifier.
+            response: LLM response to cache.
+            ttl: Optional custom TTL (uses default if None).
+
+        """
+        cache_key = self._create_cache_key(workflow, stage, prompt, model)
+        prompt_hash = self._create_cache_key("", "", prompt, "")  # Hash of prompt only
+
+        # Create cache entry
+        entry = CacheEntry(
+            key=cache_key,
+            response=response,
+            workflow=workflow,
+            stage=stage,
+            model=model,
+            prompt_hash=prompt_hash,
+            timestamp=time.time(),
+            ttl=ttl or self.default_ttl,
+        )
+
+        # Check if we need to evict entries
+        self._maybe_evict_lru()
+
+        # Store in memory
+        self._memory_cache[cache_key] = entry
+        self._access_times[cache_key] = entry.timestamp
+
+        logger.debug(
+            f"Cache PUT: {workflow}/{stage} (key: {cache_key[:16]}..., "
+            f"entries: {len(self._memory_cache)})"
+        )
+
+    def clear(self) -> None:
+        """Clear all cached entries."""
+        count = len(self._memory_cache)
+        self._memory_cache.clear()
+        self._access_times.clear()
+        logger.info(f"Cache cleared ({count} entries removed)")
+
+    def get_stats(self) -> CacheStats:
+        """Get cache statistics.
+
+        Returns:
+            CacheStats with hit/miss/eviction counts.
+
+        """
+        return self.stats
+
+    def _evict_entry(self, cache_key: str) -> None:
+        """Remove entry from cache.
+
+        Args:
+            cache_key: Key to evict.
+
+        """
+        if cache_key in self._memory_cache:
+            del self._memory_cache[cache_key]
+        if cache_key in self._access_times:
+            del self._access_times[cache_key]
+        self.stats.evictions += 1
+
+    def _maybe_evict_lru(self) -> None:
+        """Evict least recently used entries if cache is too large.
+
+        Uses LRU (Least Recently Used) eviction policy.
+
+        """
+        # Estimate memory usage (rough)
+        estimated_mb = len(self._memory_cache) * 0.01  # Rough estimate: 10KB per entry
+
+        if estimated_mb > self.max_memory_mb:
+            # Evict 10% of entries (LRU)
+            num_to_evict = max(1, len(self._memory_cache) // 10)
+
+            # Sort by access time (oldest first)
+            sorted_keys = sorted(self._access_times.items(), key=lambda x: x[1])
+
+            for cache_key, _ in sorted_keys[:num_to_evict]:
+                self._evict_entry(cache_key)
+                logger.debug(f"LRU eviction: {cache_key[:16]}...")
+
+            logger.info(
+                f"LRU eviction: removed {num_to_evict} entries "
+                f"(cache size: {len(self._memory_cache)} entries)"
+            )
+
+    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._memory_cache.items() if entry.is_expired(current_time)
+        ]
+
+        for key in expired_keys:
+            self._evict_entry(key)
+
+        if expired_keys:
+            logger.info(f"Expired eviction: removed {len(expired_keys)} entries")
+
+        return len(expired_keys)
+
+    def size_info(self) -> dict[str, Any]:
+        """Get cache size information.
+
+        Returns:
+            Dictionary with cache size metrics.
+
+        """
+        return {
+            "entries": len(self._memory_cache),
+            "estimated_mb": len(self._memory_cache) * 0.01,
+            "max_memory_mb": self.max_memory_mb,
+        }

empathy_os/cache/hybrid.py

@@ -0,0 +1,390 @@
+"""Hybrid cache with hash + semantic similarity matching.
+
+Combines fast hash-based exact matching with intelligent semantic similarity
+for maximum cache hit rate (~70%).
+
+Requires optional dependencies:
+- sentence-transformers
+- torch
+- numpy
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+import hashlib
+import logging
+import time
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from .base import BaseCache, CacheEntry, CacheStats
+
+if TYPE_CHECKING:
+    from sentence_transformers import SentenceTransformer
+
+logger = logging.getLogger(__name__)
+
+
+def cosine_similarity(a: np.ndarray, b: np.ndarray) -> float:
+    """Calculate cosine similarity between two vectors.
+
+    Args:
+        a: First vector.
+        b: Second vector.
+
+    Returns:
+        Similarity score (0.0 to 1.0).
+
+    """
+    return float(np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b)))
+
+
+class HybridCache(BaseCache):
+    """Hybrid hash + semantic similarity cache for maximum hit rate.
+
+    Provides two-tier caching:
+    1. Fast path: Hash-based exact matching (~1-5μs lookup)
+    2. Smart path: Semantic similarity matching (~50ms lookup)
+
+    Achieves ~70% cache hit rate vs ~30% for hash-only.
+
+    Example:
+        cache = HybridCache(similarity_threshold=0.95)
+
+        # First call (miss)
+        result = cache.get("code-review", "scan", "Add auth middleware", "sonnet")
+        # → None (cache miss)
+
+        cache.put("code-review", "scan", "Add auth middleware", "sonnet", response1)
+
+        # Exact match (hash hit, <5μs)
+        result = cache.get("code-review", "scan", "Add auth middleware", "sonnet")
+        # → response1 (hash cache hit)
+
+        # Similar prompt (semantic hit, ~50ms)
+        result = cache.get("code-review", "scan", "Add logging middleware", "sonnet")
+        # → response1 (92% similar, semantic cache hit)
+
+    """
+
+    def __init__(
+        self,
+        max_size_mb: int = 500,
+        default_ttl: int = 86400,
+        max_memory_mb: int = 100,
+        similarity_threshold: float = 0.95,
+        model_name: str = "all-MiniLM-L6-v2",
+        device: str = "cpu",
+    ):
+        """Initialize hybrid cache.
+
+        Args:
+            max_size_mb: Maximum disk cache size in MB.
+            default_ttl: Default TTL in seconds (24 hours).
+            max_memory_mb: Maximum in-memory cache size in MB.
+            similarity_threshold: Semantic similarity threshold (0.0-1.0, default: 0.95).
+            model_name: Sentence transformer model (default: all-MiniLM-L6-v2).
+            device: Device for embeddings ("cpu" or "cuda").
+
+        """
+        super().__init__(max_size_mb, default_ttl)
+        self.max_memory_mb = max_memory_mb
+        self.similarity_threshold = similarity_threshold
+        self.model_name = model_name
+        self.device = device
+
+        # Hash cache (fast path)
+        self._hash_cache: dict[str, CacheEntry] = {}
+        self._access_times: dict[str, float] = {}
+
+        # Semantic cache (smart path)
+        self._semantic_cache: list[tuple[np.ndarray, CacheEntry]] = []
+
+        # Load sentence transformer model
+        self._model: SentenceTransformer | None = None
+        self._load_model()
+
+        logger.info(
+            f"HybridCache initialized (model: {model_name}, threshold: {similarity_threshold}, "
+            f"device: {device}, max_memory: {max_memory_mb}MB)"
+        )
+
+    def _load_model(self) -> None:
+        """Load sentence transformer model for embeddings."""
+        try:
+            from sentence_transformers import SentenceTransformer
+
+            logger.debug(f"Loading sentence transformer model: {self.model_name}")
+            self._model = SentenceTransformer(self.model_name, device=self.device)
+            logger.info(f"Sentence transformer loaded successfully on {self.device}")
+
+        except ImportError as e:
+            logger.error(
+                f"Failed to load sentence-transformers: {e}. "
+                "Install with: pip install empathy-framework[cache]"
+            )
+            raise
+        except Exception as e:
+            logger.warning(f"Failed to load model {self.model_name}: {e}")
+            logger.warning("Falling back to hash-only mode")
+            self._model = None
+
+    def get(
+        self,
+        workflow: str,
+        stage: str,
+        prompt: str,
+        model: str,
+    ) -> Any | None:
+        """Get cached response using hybrid hash + semantic matching.
+
+        Args:
+            workflow: Workflow name.
+            stage: Stage name.
+            prompt: Prompt text.
+            model: Model identifier.
+
+        Returns:
+            Cached response if found (hash or semantic match), None otherwise.
+
+        """
+        cache_key = self._create_cache_key(workflow, stage, prompt, model)
+        current_time = time.time()
+
+        # Step 1: Try hash cache (fast path, <5μs)
+        if cache_key in self._hash_cache:
+            entry = self._hash_cache[cache_key]
+
+            if entry.is_expired(current_time):
+                self._evict_entry(cache_key)
+                self.stats.misses += 1
+                return None
+
+            # Hash hit!
+            self._access_times[cache_key] = current_time
+            self.stats.hits += 1
+            logger.debug(
+                f"Cache HIT (hash): {workflow}/{stage} " f"(hit_rate: {self.stats.hit_rate:.1f}%)"
+            )
+            return entry.response
+
+        # Step 2: Try semantic cache (smart path, ~50ms)
+        if self._model is not None:
+            semantic_result = self._semantic_lookup(prompt, workflow, stage, model)
+            if semantic_result is not None:
+                # Semantic hit! Add to hash cache for future fast lookups
+                entry, similarity = semantic_result
+                self._hash_cache[cache_key] = entry
+                self._access_times[cache_key] = current_time
+
+                self.stats.hits += 1
+                logger.debug(
+                    f"Cache HIT (semantic): {workflow}/{stage} "
+                    f"(similarity: {similarity:.3f}, hit_rate: {self.stats.hit_rate:.1f}%)"
+                )
+                return entry.response
+
+        # Step 3: Cache miss
+        self.stats.misses += 1
+        logger.debug(
+            f"Cache MISS (hybrid): {workflow}/{stage} " f"(hit_rate: {self.stats.hit_rate:.1f}%)"
+        )
+        return None
+
+    def _semantic_lookup(
+        self,
+        prompt: str,
+        workflow: str,
+        stage: str,
+        model: str,
+    ) -> tuple[CacheEntry, float] | None:
+        """Perform semantic similarity lookup.
+
+        Args:
+            prompt: Prompt text.
+            workflow: Workflow name.
+            stage: Stage name.
+            model: Model identifier.
+
+        Returns:
+            Tuple of (CacheEntry, similarity_score) if match found, None otherwise.
+
+        """
+        if not self._semantic_cache:
+            return None
+
+        if self._model is None:
+            raise RuntimeError("Sentence transformer model not loaded")
+
+        # Encode prompt
+        prompt_embedding = self._model.encode(prompt, convert_to_numpy=True)
+
+        # Find best match
+        best_similarity = 0.0
+        best_entry = None
+        current_time = time.time()
+
+        for cached_embedding, entry in self._semantic_cache:
+            # Only match same workflow, stage, and model
+            if entry.workflow != workflow or entry.stage != stage or entry.model != model:
+                continue
+
+            # Skip expired
+            if entry.is_expired(current_time):
+                continue
+
+            # Calculate similarity
+            similarity = cosine_similarity(prompt_embedding, cached_embedding)
+
+            if similarity > best_similarity:
+                best_similarity = similarity
+                best_entry = entry
+
+        # Check if best match exceeds threshold
+        if best_similarity >= self.similarity_threshold and best_entry is not None:
+            return (best_entry, best_similarity)
+
+        return None
+
+    def put(
+        self,
+        workflow: str,
+        stage: str,
+        prompt: str,
+        model: str,
+        response: Any,
+        ttl: int | None = None,
+    ) -> None:
+        """Store response in both hash and semantic caches.
+
+        Args:
+            workflow: Workflow name.
+            stage: Stage name.
+            prompt: Prompt text.
+            model: Model identifier.
+            response: LLM response to cache.
+            ttl: Optional custom TTL.
+
+        """
+        cache_key = self._create_cache_key(workflow, stage, prompt, model)
+        prompt_hash = hashlib.sha256(prompt.encode()).hexdigest()
+
+        # Create cache entry
+        entry = CacheEntry(
+            key=cache_key,
+            response=response,
+            workflow=workflow,
+            stage=stage,
+            model=model,
+            prompt_hash=prompt_hash,
+            timestamp=time.time(),
+            ttl=ttl or self.default_ttl,
+        )
+
+        # Maybe evict before adding
+        self._maybe_evict_lru()
+
+        # Store in hash cache
+        self._hash_cache[cache_key] = entry
+        self._access_times[cache_key] = entry.timestamp
+
+        # Store in semantic cache (if model available)
+        if self._model is not None:
+            prompt_embedding = self._model.encode(prompt, convert_to_numpy=True)
+            self._semantic_cache.append((prompt_embedding, entry))
+
+        logger.debug(
+            f"Cache PUT (hybrid): {workflow}/{stage} "
+            f"(hash_entries: {len(self._hash_cache)}, "
+            f"semantic_entries: {len(self._semantic_cache)})"
+        )
+
+    def clear(self) -> None:
+        """Clear all cached entries."""
+        hash_count = len(self._hash_cache)
+        semantic_count = len(self._semantic_cache)
+
+        self._hash_cache.clear()
+        self._access_times.clear()
+        self._semantic_cache.clear()
+
+        logger.info(f"Cache cleared (hash: {hash_count}, semantic: {semantic_count} entries)")
+
+    def get_stats(self) -> CacheStats:
+        """Get cache statistics."""
+        return self.stats
+
+    def _evict_entry(self, cache_key: str) -> None:
+        """Remove entry from both caches.
+
+        Args:
+            cache_key: Key to evict.
+
+        """
+        # Remove from hash cache
+        if cache_key in self._hash_cache:
+            entry = self._hash_cache[cache_key]
+            del self._hash_cache[cache_key]
+
+            # Remove from semantic cache
+            self._semantic_cache = [
+                (emb, e) for emb, e in self._semantic_cache if e.key != entry.key
+            ]
+
+        if cache_key in self._access_times:
+            del self._access_times[cache_key]
+
+        self.stats.evictions += 1
+
+    def _maybe_evict_lru(self) -> None:
+        """Evict least recently used entries if cache too large."""
+        # Estimate memory (rough)
+        estimated_mb = (len(self._hash_cache) * 0.01) + (len(self._semantic_cache) * 0.1)
+
+        if estimated_mb > self.max_memory_mb:
+            # Evict 10% of entries
+            num_to_evict = max(1, len(self._hash_cache) // 10)
+
+            # Sort by access time
+            sorted_keys = sorted(self._access_times.items(), key=lambda x: x[1])
+
+            for cache_key, _ in sorted_keys[:num_to_evict]:
+                self._evict_entry(cache_key)
+
+            logger.info(
+                f"LRU eviction: removed {num_to_evict} entries "
+                f"(hash: {len(self._hash_cache)}, semantic: {len(self._semantic_cache)})"
+            )
+
+    def evict_expired(self) -> int:
+        """Remove all expired entries."""
+        current_time = time.time()
+        expired_keys = [
+            key for key, entry in self._hash_cache.items() if entry.is_expired(current_time)
+        ]
+
+        for key in expired_keys:
+            self._evict_entry(key)
+
+        if expired_keys:
+            logger.info(f"Expired eviction: removed {len(expired_keys)} entries")
+
+        return len(expired_keys)
+
+    def size_info(self) -> dict[str, Any]:
+        """Get cache size information."""
+        hash_mb = len(self._hash_cache) * 0.01
+        semantic_mb = len(self._semantic_cache) * 0.1
+
+        return {
+            "hash_entries": len(self._hash_cache),
+            "semantic_entries": len(self._semantic_cache),
+            "hash_size_mb": round(hash_mb, 2),
+            "semantic_size_mb": round(semantic_mb, 2),
+            "total_size_mb": round(hash_mb + semantic_mb, 2),
+            "max_memory_mb": self.max_memory_mb,
+            "model": self.model_name,
+            "threshold": self.similarity_threshold,
+        }