empathy-framework 2.4.0__py3-none-any.whl → 3.8.2__py3-none-any.whl

empathy_os/{monitoring.py → agent_monitoring.py}

@@ -1,5 +1,4 @@
-"""
-Agent Monitoring for Distributed Memory Networks
+"""Agent Monitoring for Distributed Memory Networks
 
 Provides monitoring and metrics collection for multi-agent systems.
 Tracks individual agent performance, pattern contributions, and
@@ -79,8 +78,7 @@ class TeamMetrics:
 
     @property
     def collaboration_efficiency(self) -> float:
-        """
-        Measure of how effectively agents collaborate.
+        """Measure of how effectively agents collaborate.
 
         Higher values indicate more cross-agent pattern reuse,
         meaning agents are learning from each other.
@@ -91,8 +89,7 @@ class TeamMetrics:
 
 
 class AgentMonitor:
-    """
-    Monitors and tracks metrics for multi-agent systems.
+    """Monitors and tracks metrics for multi-agent systems.
 
     Provides insights into:
     - Individual agent performance
@@ -106,7 +103,7 @@ class AgentMonitor:
         >>> # Record agent activity
         >>> monitor.record_interaction("code_reviewer", response_time_ms=150.0)
         >>> monitor.record_pattern_discovery("code_reviewer")
-        >>> monitor.record_pattern_use("test_generator", pattern_agent="code_reviewer", success=True)
+        >>> monitor.record_pattern_use("test_gen", pattern_agent="code_reviewer", success=True)
         >>>
         >>> # Get individual stats
         >>> stats = monitor.get_agent_stats("code_reviewer")
@@ -116,14 +113,15 @@ class AgentMonitor:
         >>> # Get team stats
         >>> team = monitor.get_team_stats()
         >>> print(f"Collaboration efficiency: {team['collaboration_efficiency']:.0%}")
+
     """
 
     def __init__(self, pattern_library: PatternLibrary | None = None):
-        """
-        Initialize the AgentMonitor.
+        """Initialize the AgentMonitor.
 
         Args:
             pattern_library: Optional pattern library to track for shared patterns
+
         """
         self.agents: dict[str, AgentMetrics] = {}
         self.pattern_library = pattern_library
@@ -139,12 +137,12 @@ class AgentMonitor:
         agent_id: str,
         response_time_ms: float = 0.0,
     ):
-        """
-        Record an agent interaction.
+        """Record an agent interaction.
 
         Args:
             agent_id: ID of the agent
             response_time_ms: Response time in milliseconds
+
         """
         agent = self._get_or_create_agent(agent_id)
         agent.total_interactions += 1
@@ -160,12 +158,12 @@ class AgentMonitor:
             )
 
     def record_pattern_discovery(self, agent_id: str, pattern_id: str | None = None):
-        """
-        Record that an agent discovered a new pattern.
+        """Record that an agent discovered a new pattern.
 
         Args:
             agent_id: ID of the agent that discovered the pattern
             pattern_id: Optional pattern ID for tracking
+
         """
         agent = self._get_or_create_agent(agent_id)
         agent.patterns_discovered += 1
@@ -178,14 +176,14 @@ class AgentMonitor:
         pattern_agent: str | None = None,
         success: bool = True,
     ):
-        """
-        Record that an agent used a pattern.
+        """Record that an agent used a pattern.
 
         Args:
             agent_id: ID of the agent using the pattern
             pattern_id: ID of the pattern being used
             pattern_agent: ID of the agent that contributed the pattern
             success: Whether the pattern use was successful
+
         """
         agent = self._get_or_create_agent(agent_id)
         agent.patterns_used += 1
@@ -207,18 +205,18 @@ class AgentMonitor:
                 "cross_agent": is_cross_agent,
                 "success": success,
                 "timestamp": datetime.now(),
-            }
+            },
         )
 
     def get_agent_stats(self, agent_id: str) -> dict[str, Any]:
-        """
-        Get statistics for a specific agent.
+        """Get statistics for a specific agent.
 
         Args:
             agent_id: ID of the agent
 
         Returns:
             Dictionary with agent statistics
+
         """
         agent = self.agents.get(agent_id)
 
@@ -252,11 +250,11 @@ class AgentMonitor:
         }
 
     def get_team_stats(self) -> dict[str, Any]:
-        """
-        Get aggregated statistics for the entire agent team.
+        """Get aggregated statistics for the entire agent team.
 
         Returns:
             Dictionary with team-wide statistics
+
         """
         if not self.agents:
             # Get shared patterns count from library even if no agents
@@ -319,39 +317,41 @@ class AgentMonitor:
         }
 
     def get_top_contributors(self, n: int = 5) -> list[dict[str, Any]]:
-        """
-        Get the top pattern-contributing agents.
+        """Get the top pattern-contributing agents.
 
         Args:
             n: Number of agents to return
 
         Returns:
             List of agent stats, sorted by patterns discovered
+
         """
         sorted_agents = sorted(
-            self.agents.values(), key=lambda a: a.patterns_discovered, reverse=True
+            self.agents.values(),
+            key=lambda a: a.patterns_discovered,
+            reverse=True,
         )
 
         return [self.get_agent_stats(agent.agent_id) for agent in sorted_agents[:n]]
 
     def get_alerts(self, limit: int = 100) -> list[dict[str, Any]]:
-        """
-        Get recent alerts.
+        """Get recent alerts.
 
         Args:
             limit: Maximum number of alerts to return
 
         Returns:
             List of alert dictionaries
+
         """
         return self.alerts[-limit:]
 
     def check_health(self) -> dict[str, Any]:
-        """
-        Check overall system health.
+        """Check overall system health.
 
         Returns:
             Health status dictionary
+
         """
         team_stats = self.get_team_stats()
         recent_alerts = [
@@ -400,7 +400,7 @@ class AgentMonitor:
                 "message": message,
                 "severity": severity,
                 "timestamp": datetime.now(),
-            }
+            },
         )
 
         # Keep alerts bounded

empathy_os/cache/__init__.py

@@ -0,0 +1,117 @@
+"""Response caching for Empathy Framework workflows.
+
+Provides hybrid hash + semantic similarity caching to reduce API costs by 70%.
+
+Usage:
+    from empathy_os.cache import create_cache
+
+    # Auto-detect best cache (hybrid if deps available, hash-only otherwise)
+    cache = create_cache()
+
+    # Manual cache selection
+    from empathy_os.cache import HashOnlyCache, HybridCache
+
+    cache = HashOnlyCache()  # Always available
+    cache = HybridCache()    # Requires sentence-transformers
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+import logging
+from typing import Optional
+
+from .base import BaseCache, CacheEntry, CacheStats
+from .hash_only import HashOnlyCache
+
+logger = logging.getLogger(__name__)
+
+# Try to import HybridCache (requires optional dependencies)
+try:
+    from .hybrid import HybridCache
+
+    HYBRID_AVAILABLE = True
+except ImportError:
+    HYBRID_AVAILABLE = False
+    HybridCache = None  # type: ignore
+
+
+def create_cache(
+    cache_type: str | None = None,
+    **kwargs,
+) -> BaseCache:
+    """Create appropriate cache based on available dependencies.
+
+    Auto-detects if sentence-transformers is available and creates
+    HybridCache if possible, otherwise falls back to HashOnlyCache.
+
+    Args:
+        cache_type: Force specific cache type ("hash" | "hybrid" | None for auto).
+        **kwargs: Additional arguments passed to cache constructor.
+
+    Returns:
+        BaseCache instance (HybridCache or HashOnlyCache).
+
+    Example:
+        # Auto-detect (recommended)
+        cache = create_cache()
+
+        # Force hash-only
+        cache = create_cache(cache_type="hash")
+
+        # Force hybrid (raises ImportError if deps missing)
+        cache = create_cache(cache_type="hybrid")
+
+    """
+    # Force hash-only
+    if cache_type == "hash":
+        logger.info("Using hash-only cache (explicit)")
+        return HashOnlyCache(**kwargs)
+
+    # Force hybrid
+    if cache_type == "hybrid":
+        if not HYBRID_AVAILABLE:
+            raise ImportError(
+                "HybridCache requires sentence-transformers. "
+                "Install with: pip install empathy-framework[cache]"
+            )
+        logger.info("Using hybrid cache (explicit)")
+        return HybridCache(**kwargs)
+
+    # Auto-detect (default)
+    if HYBRID_AVAILABLE:
+        logger.info("Using hybrid cache (auto-detected)")
+        return HybridCache(**kwargs)
+    else:
+        logger.info(
+            "Using hash-only cache (sentence-transformers not available). "
+            "For 70% cost savings, install with: pip install empathy-framework[cache]"
+        )
+        return HashOnlyCache(**kwargs)
+
+
+def auto_setup_cache() -> None:
+    """Auto-setup cache with one-time prompt if dependencies missing.
+
+    Called automatically by BaseWorkflow on first run.
+    Prompts user to install cache dependencies if not available.
+
+    """
+    from .dependency_manager import DependencyManager
+
+    manager = DependencyManager()
+
+    if manager.should_prompt_cache_install():
+        manager.prompt_cache_install()
+
+
+__all__ = [
+    "BaseCache",
+    "CacheEntry",
+    "CacheStats",
+    "HashOnlyCache",
+    "HybridCache",
+    "create_cache",
+    "auto_setup_cache",
+    "HYBRID_AVAILABLE",
+]

empathy_os/cache/base.py

@@ -0,0 +1,166 @@
+"""Base cache interface for Empathy Framework response caching.
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class CacheEntry:
+    """Cached LLM response with metadata."""
+
+    key: str
+    response: Any
+    workflow: str
+    stage: str
+    model: str
+    prompt_hash: str
+    timestamp: float
+    ttl: int | None = None  # Time-to-live in seconds
+
+    def is_expired(self, current_time: float) -> bool:
+        """Check if entry has expired."""
+        if self.ttl is None:
+            return False
+        return (current_time - self.timestamp) > self.ttl
+
+
+@dataclass
+class CacheStats:
+    """Cache hit/miss statistics."""
+
+    hits: int = 0
+    misses: int = 0
+    evictions: int = 0
+
+    @property
+    def total(self) -> int:
+        """Total cache lookups."""
+        return self.hits + self.misses
+
+    @property
+    def hit_rate(self) -> float:
+        """Cache hit rate percentage."""
+        if self.total == 0:
+            return 0.0
+        return (self.hits / self.total) * 100.0
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for logging."""
+        return {
+            "hits": self.hits,
+            "misses": self.misses,
+            "evictions": self.evictions,
+            "total": self.total,
+            "hit_rate": round(self.hit_rate, 1),
+        }
+
+
+class BaseCache(ABC):
+    """Abstract base class for LLM response caching."""
+
+    def __init__(self, max_size_mb: int = 500, default_ttl: int = 86400):
+        """Initialize cache.
+
+        Args:
+            max_size_mb: Maximum cache size in megabytes.
+            default_ttl: Default time-to-live in seconds (default: 24 hours).
+
+        """
+        self.max_size_mb = max_size_mb
+        self.default_ttl = default_ttl
+        self.stats = CacheStats()
+
+    @abstractmethod
+    def get(
+        self,
+        workflow: str,
+        stage: str,
+        prompt: str,
+        model: str,
+    ) -> Any | None:
+        """Get cached response.
+
+        Args:
+            workflow: Workflow name (e.g., "code-review").
+            stage: Stage name (e.g., "scan").
+            prompt: Prompt text.
+            model: Model identifier (e.g., "claude-3-5-sonnet-20241022").
+
+        Returns:
+            Cached response if found, None otherwise.
+
+        """
+        pass
+
+    @abstractmethod
+    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).
+
+        """
+        pass
+
+    @abstractmethod
+    def clear(self) -> None:
+        """Clear all cached entries."""
+        pass
+
+    @abstractmethod
+    def get_stats(self) -> CacheStats:
+        """Get cache statistics.
+
+        Returns:
+            CacheStats with hit/miss counts.
+
+        """
+        pass
+
+    def _create_cache_key(
+        self,
+        workflow: str,
+        stage: str,
+        prompt: str,
+        model: str,
+    ) -> str:
+        """Create cache key from workflow, stage, prompt, and model.
+
+        Uses SHA256 hash of concatenated values.
+
+        Args:
+            workflow: Workflow name.
+            stage: Stage name.
+            prompt: Prompt text.
+            model: Model identifier.
+
+        Returns:
+            Cache key (SHA256 hash).
+
+        """
+        import hashlib
+
+        # Combine all inputs for cache key
+        key_parts = [workflow, stage, prompt, model]
+        key_string = "|".join(key_parts)
+
+        # SHA256 hash for consistent key length
+        return hashlib.sha256(key_string.encode()).hexdigest()