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

empathy_os/memory/mixins/backend_init_mixin.py

@@ -146,7 +146,12 @@ class BackendInitMixin:
             if self.config.redis_required and not (
                 self._redis_status and self._redis_status.available
             ):
-                raise RuntimeError("Redis is required but not available")
+                raise RuntimeError(
+                    "Redis is required but not available. "
+                    f"Config requires Redis (redis_required=True, environment={self.config.environment.value}). "
+                    "Either: (1) Start Redis server, (2) Set REDIS_URL environment variable, "
+                    "or (3) Set redis_required=False in MemoryConfig."
+                )
 
         except RuntimeError:
             raise  # Re-raise required Redis error

empathy_os/memory/mixins/capabilities_mixin.py

@@ -68,7 +68,10 @@ class CapabilitiesMixin:
 
         """
         if self._short_term is None:
-            raise RuntimeError("Short-term memory not initialized")
+            raise RuntimeError(
+                "Short-term memory not initialized. "
+                "Ensure Redis is running and UnifiedMemory was initialized with Redis enabled."
+            )
         return self._short_term
 
     @property
@@ -87,7 +90,10 @@ class CapabilitiesMixin:
 
         """
         if self._simple_long_term is None:
-            raise RuntimeError("Long-term memory not initialized")
+            raise RuntimeError(
+                "Long-term memory not initialized. "
+                "Ensure UnifiedMemory was initialized with long_term_enabled=True."
+            )
         return self._simple_long_term
 
     # =========================================================================
@@ -145,7 +151,10 @@ class CapabilitiesMixin:
             RuntimeError: If file session memory is not initialized
         """
         if self._file_session is None:
-            raise RuntimeError("File session memory not initialized")
+            raise RuntimeError(
+                "File session memory not initialized. "
+                "File session tracking is automatically enabled when UnifiedMemory is initialized."
+            )
         return self._file_session
 
     def supports_realtime(self) -> bool:

empathy_os/memory/short_term.py

@@ -23,6 +23,7 @@ Licensed under Fair Source 0.9
 """
 
 import json
+import os
 import threading
 import time
 from collections.abc import Callable
@@ -138,11 +139,25 @@ class RedisShortTermMemory:
         if config is not None:
             self._config = config
         else:
+            # Check environment variable for Redis enablement (default: disabled)
+            redis_enabled = os.getenv("REDIS_ENABLED", "false").lower() in ("true", "1", "yes")
+
+            # Use environment variables for configuration if available
+            env_host = os.getenv("REDIS_HOST", host)
+            env_port = int(os.getenv("REDIS_PORT", str(port)))
+            env_db = int(os.getenv("REDIS_DB", str(db)))
+            env_password = os.getenv("REDIS_PASSWORD", password)
+
+            # If Redis is not enabled via env var, force mock mode
+            if not redis_enabled and not use_mock:
+                use_mock = True
+                logger.info("redis_disabled_via_env", message="Redis not enabled in environment, using mock mode")
+
             self._config = RedisConfig(
-                host=host,
-                port=port,
-                db=db,
-                password=password,
+                host=env_host,
+                port=env_port,
+                db=env_db,
+                password=env_password if env_password else None,
                 use_mock=use_mock,
             )
 
@@ -193,6 +208,33 @@ class RedisShortTermMemory:
         else:
             self._client = self._create_client_with_retry()
 
+    @property
+    def client(self) -> Any:
+        """Get the Redis client instance.
+
+        Returns:
+            Redis client instance or None if using mock mode
+
+        Example:
+            >>> memory = RedisShortTermMemory()
+            >>> if memory.client:
+            ...     print("Redis connected")
+        """
+        return self._client
+
+    @property
+    def metrics(self) -> "RedisMetrics":
+        """Get Redis metrics instance.
+
+        Returns:
+            RedisMetrics instance with connection and operation statistics
+
+        Example:
+            >>> memory = RedisShortTermMemory()
+            >>> print(f"Retries: {memory.metrics.retries_total}")
+        """
+        return self._metrics
+
     def _create_client_with_retry(self) -> Any:
         """Create Redis client with retry logic."""
         max_attempts = self._config.retry_max_attempts
@@ -560,7 +602,7 @@ class RedisShortTermMemory:
         """
         # Pattern 1: String ID validation
         if not key or not key.strip():
-            raise ValueError("key cannot be empty")
+            raise ValueError(f"key cannot be empty. Got: {key!r}")
 
         if not credentials.can_stage():
             raise PermissionError(
@@ -612,7 +654,7 @@ class RedisShortTermMemory:
         """
         # Pattern 1: String ID validation
         if not key or not key.strip():
-            raise ValueError("key cannot be empty")
+            raise ValueError(f"key cannot be empty. Got: {key!r}")
 
         owner = agent_id or credentials.agent_id
         full_key = f"{self.PREFIX_WORKING}{owner}:{key}"
@@ -703,7 +745,7 @@ class RedisShortTermMemory:
         """
         # Pattern 1: String ID validation
         if not pattern_id or not pattern_id.strip():
-            raise ValueError("pattern_id cannot be empty")
+            raise ValueError(f"pattern_id cannot be empty. Got: {pattern_id!r}")
 
         key = f"{self.PREFIX_STAGED}{pattern_id}"
         raw = self._get(key)
@@ -824,7 +866,7 @@ class RedisShortTermMemory:
         """
         # Pattern 1: String ID validation
         if not conflict_id or not conflict_id.strip():
-            raise ValueError("conflict_id cannot be empty")
+            raise ValueError(f"conflict_id cannot be empty. Got: {conflict_id!r}")
 
         # Pattern 5: Type validation
         if not isinstance(positions, dict):
@@ -874,7 +916,7 @@ class RedisShortTermMemory:
         """
         # Pattern 1: String ID validation
         if not conflict_id or not conflict_id.strip():
-            raise ValueError("conflict_id cannot be empty")
+            raise ValueError(f"conflict_id cannot be empty. Got: {conflict_id!r}")
 
         key = f"{self.PREFIX_CONFLICT}{conflict_id}"
         raw = self._get(key)
@@ -949,7 +991,7 @@ class RedisShortTermMemory:
         """
         # Pattern 1: String ID validation
         if not session_id or not session_id.strip():
-            raise ValueError("session_id cannot be empty")
+            raise ValueError(f"session_id cannot be empty. Got: {session_id!r}")
 
         # Pattern 5: Type validation
         if metadata is not None and not isinstance(metadata, dict):
@@ -985,7 +1027,7 @@ class RedisShortTermMemory:
         """
         # Pattern 1: String ID validation
         if not session_id or not session_id.strip():
-            raise ValueError("session_id cannot be empty")
+            raise ValueError(f"session_id cannot be empty. Got: {session_id!r}")
 
         key = f"{self.PREFIX_SESSION}{session_id}"
         raw = self._get(key)
@@ -2009,7 +2051,7 @@ class RedisShortTermMemory:
         """
         # Pattern 1: String ID validation
         if not pattern_id or not pattern_id.strip():
-            raise ValueError("pattern_id cannot be empty")
+            raise ValueError(f"pattern_id cannot be empty. Got: {pattern_id!r}")
 
         # Pattern 4: Range validation
         if not 0.0 <= min_confidence <= 1.0:

empathy_os/memory/simple_storage.py

@@ -94,7 +94,7 @@ class LongTermMemory:
 
         """
         if not key or not key.strip():
-            raise ValueError("key cannot be empty")
+            raise ValueError(f"key cannot be empty. Got: {key!r}")
 
         # Validate key for path traversal attacks
         if ".." in key or key.startswith("/") or "\x00" in key:
@@ -165,7 +165,7 @@ class LongTermMemory:
 
         """
         if not key or not key.strip():
-            raise ValueError("key cannot be empty")
+            raise ValueError(f"key cannot be empty. Got: {key!r}")
 
         try:
             file_path = self.storage_path / f"{key}.json"
@@ -204,7 +204,7 @@ class LongTermMemory:
 
         """
         if not key or not key.strip():
-            raise ValueError("key cannot be empty")
+            raise ValueError(f"key cannot be empty. Got: {key!r}")
 
         try:
             file_path = self.storage_path / f"{key}.json"

empathy_os/memory/types.py

@@ -188,6 +188,11 @@ class RedisMetrics:
             return 100.0
         return (self.operations_success / self.operations_total) * 100
 
+    @property
+    def total_requests(self) -> int:
+        """Total requests (alias for operations_total for backward compatibility)."""
+        return self.operations_total
+
     def to_dict(self) -> dict:
         """Convert metrics to dictionary for reporting and serialization.
 
@@ -297,11 +302,11 @@ class StagedPattern:
         """Validate fields after initialization"""
         # Pattern 1: String ID validation
         if not self.pattern_id or not self.pattern_id.strip():
-            raise ValueError("pattern_id cannot be empty")
+            raise ValueError(f"pattern_id cannot be empty. Got: {self.pattern_id!r}")
         if not self.agent_id or not self.agent_id.strip():
-            raise ValueError("agent_id cannot be empty")
+            raise ValueError(f"agent_id cannot be empty. Got: {self.agent_id!r}")
         if not self.pattern_type or not self.pattern_type.strip():
-            raise ValueError("pattern_type cannot be empty")
+            raise ValueError(f"pattern_type cannot be empty. Got: {self.pattern_type!r}")
 
         # Pattern 4: Range validation for confidence
         if not 0.0 <= self.confidence <= 1.0:

empathy_os/telemetry/agent_coordination.py

@@ -447,9 +447,8 @@ class CoordinationSignals:
             return None
 
         try:
-            if hasattr(self.memory, "retrieve"):
-                return self.memory.retrieve(key, credentials=None)
-            elif hasattr(self.memory, "_client"):
+            # Use direct Redis access (signal keys are stored without prefix)
+            if hasattr(self.memory, "_client"):
                 import json
 
                 data = self.memory._client.get(key)

empathy_os/telemetry/agent_tracking.py

@@ -53,6 +53,7 @@ class AgentHeartbeat:
     current_task: str
     last_beat: datetime
     metadata: dict[str, Any] = field(default_factory=dict)
+    display_name: str | None = None  # Optional human-readable name for dashboard
 
     def to_dict(self) -> dict[str, Any]:
         """Convert to dictionary for serialization."""
@@ -63,6 +64,7 @@ class AgentHeartbeat:
             "current_task": self.current_task,
             "last_beat": self.last_beat.isoformat() if isinstance(self.last_beat, datetime) else self.last_beat,
             "metadata": self.metadata,
+            "display_name": self.display_name,
         }
 
     @classmethod
@@ -82,6 +84,7 @@ class AgentHeartbeat:
             current_task=data["current_task"],
             last_beat=last_beat,
             metadata=data.get("metadata", {}),
+            display_name=data.get("display_name"),
         )
 
 
@@ -110,6 +113,7 @@ class HeartbeatCoordinator:
         """
         self.memory = memory
         self.agent_id: str | None = None
+        self.display_name: str | None = None
         self._enable_streaming = enable_streaming
         self._event_streamer = None
 
@@ -142,20 +146,28 @@ class HeartbeatCoordinator:
 
         return self._event_streamer
 
-    def start_heartbeat(self, agent_id: str, metadata: dict[str, Any] | None = None) -> None:
+    def start_heartbeat(
+        self, agent_id: str, metadata: dict[str, Any] | None = None, display_name: str | None = None
+    ) -> None:
         """Start heartbeat for an agent.
 
         Args:
             agent_id: Unique agent identifier
             metadata: Initial metadata (workflow, run_id, etc.)
+            display_name: Optional human-readable name for dashboard display
         """
         if not self.memory:
             logger.debug("Heartbeat tracking disabled (no memory backend)")
             return
 
         self.agent_id = agent_id
+        self.display_name = display_name
         self._publish_heartbeat(
-            status="starting", progress=0.0, current_task="initializing", metadata=metadata or {}
+            status="starting",
+            progress=0.0,
+            current_task="initializing",
+            metadata=metadata or {},
+            display_name=display_name,
         )
 
     def beat(self, status: str = "running", progress: float = 0.0, current_task: str = "") -> None:
@@ -169,7 +181,13 @@ class HeartbeatCoordinator:
         if not self.agent_id or not self.memory:
             return
 
-        self._publish_heartbeat(status=status, progress=progress, current_task=current_task, metadata={})
+        self._publish_heartbeat(
+            status=status,
+            progress=progress,
+            current_task=current_task,
+            metadata={},
+            display_name=self.display_name,
+        )
 
     def stop_heartbeat(self, final_status: str = "completed") -> None:
         """Stop heartbeat (agent finished).
@@ -192,7 +210,7 @@ class HeartbeatCoordinator:
         self.agent_id = None
 
     def _publish_heartbeat(
-        self, status: str, progress: float, current_task: str, metadata: dict[str, Any]
+        self, status: str, progress: float, current_task: str, metadata: dict[str, Any], display_name: str | None = None
     ) -> None:
         """Publish heartbeat to Redis with TTL and optionally to event stream."""
         if not self.memory or not self.agent_id:
@@ -205,10 +223,11 @@ class HeartbeatCoordinator:
             current_task=current_task,
             last_beat=datetime.utcnow(),
             metadata=metadata,
+            display_name=display_name,
         )
 
         # Store in Redis with TTL (Pattern 1)
-        key = f"heartbeat:{self.agent_id}"
+        key = f"empathy:heartbeat:{self.agent_id}"
         try:
             # Use direct Redis access for heartbeats (need custom 30s TTL)
             if hasattr(self.memory, "_client") and self.memory._client:
@@ -243,9 +262,9 @@ class HeartbeatCoordinator:
             return []
 
         try:
-            # Scan for heartbeat:* keys
+            # Scan for empathy:heartbeat:* keys
             if hasattr(self.memory, "_client") and self.memory._client:
-                keys = self.memory._client.keys("heartbeat:*")
+                keys = self.memory._client.keys("empathy:heartbeat:*")
             else:
                 logger.warning("Cannot scan for heartbeats: no Redis access")
                 return []

empathy_os/telemetry/approval_gates.py

@@ -458,19 +458,16 @@ class ApprovalGate:
                 if isinstance(key, bytes):
                     key = key.decode("utf-8")
 
-                # Retrieve request
-                if hasattr(self.memory, "retrieve"):
-                    data = self.memory.retrieve(key, credentials=None)
-                else:
-                    import json
+                # Retrieve request - use direct Redis access (approval keys are stored without prefix)
+                import json
 
-                    raw_data = self.memory._client.get(key)
-                    if raw_data:
-                        if isinstance(raw_data, bytes):
-                            raw_data = raw_data.decode("utf-8")
-                        data = json.loads(raw_data)
-                    else:
-                        data = None
+                raw_data = self.memory._client.get(key)
+                if raw_data:
+                    if isinstance(raw_data, bytes):
+                        raw_data = raw_data.decode("utf-8")
+                    data = json.loads(raw_data)
+                else:
+                    data = None
 
                 if not data:
                     continue
@@ -513,19 +510,16 @@ class ApprovalGate:
                 if isinstance(key, bytes):
                     key = key.decode("utf-8")
 
-                # Retrieve request
-                if hasattr(self.memory, "retrieve"):
-                    data = self.memory.retrieve(key, credentials=None)
-                else:
-                    import json
+                # Retrieve request - use direct Redis access (approval keys are stored without prefix)
+                import json
 
-                    raw_data = self.memory._client.get(key)
-                    if raw_data:
-                        if isinstance(raw_data, bytes):
-                            raw_data = raw_data.decode("utf-8")
-                        data = json.loads(raw_data)
-                    else:
-                        data = None
+                raw_data = self.memory._client.get(key)
+                if raw_data:
+                    if isinstance(raw_data, bytes):
+                        raw_data = raw_data.decode("utf-8")
+                    data = json.loads(raw_data)
+                else:
+                    data = None
 
                 if not data:
                     continue

empathy_os/telemetry/event_streaming.py

@@ -66,13 +66,17 @@ class StreamEvent:
 
         Args:
             event_id: Redis stream entry ID
-            entry_data: Raw entry data from Redis (bytes dict)
+            entry_data: Raw entry data from Redis (bytes dict or str dict)
 
         Returns:
             StreamEvent instance
         """
-        # Decode bytes to strings
-        decoded = {k.decode("utf-8"): v.decode("utf-8") for k, v in entry_data.items()}
+        # Decode bytes to strings (handle both bytes and str)
+        decoded = {}
+        for k, v in entry_data.items():
+            key = k.decode("utf-8") if isinstance(k, bytes) else k
+            value = v.decode("utf-8") if isinstance(v, bytes) else v
+            decoded[key] = value
 
         # Parse timestamp
         timestamp_str = decoded.get("timestamp", "")

empathy_os/telemetry/feedback_loop.py

@@ -93,8 +93,13 @@ class FeedbackEntry:
         elif not isinstance(timestamp, datetime):
             timestamp = datetime.utcnow()
 
+        # Handle missing feedback_id (legacy entries)
+        feedback_id = data.get("feedback_id")
+        if not feedback_id:
+            feedback_id = f"fb-{int(timestamp.timestamp()*1000)}"
+
         return cls(
-            feedback_id=data["feedback_id"],
+            feedback_id=feedback_id,
             workflow_name=data["workflow_name"],
             stage_name=data["stage_name"],
             tier=data["tier"],
@@ -284,7 +289,11 @@ class FeedbackLoop:
                 # Retrieve entry
                 data = self._retrieve_feedback(key)
                 if data:
-                    entries.append(FeedbackEntry.from_dict(data))
+                    try:
+                        entries.append(FeedbackEntry.from_dict(data))
+                    except Exception as e:
+                        logger.error(f"Failed to parse feedback entry {key}: {e}, data={data}")
+                        continue
 
                 if len(entries) >= limit:
                     break
@@ -303,9 +312,8 @@ class FeedbackLoop:
             return None
 
         try:
-            if hasattr(self.memory, "retrieve"):
-                return self.memory.retrieve(key, credentials=None)
-            elif hasattr(self.memory, "_client"):
+            # Use direct Redis access (feedback keys are stored without prefix)
+            if hasattr(self.memory, "_client"):
                 import json
 
                 data = self.memory._client.get(key)
@@ -482,14 +490,15 @@ class FeedbackLoop:
     def get_underperforming_stages(
         self, workflow_name: str, quality_threshold: float = 0.7
     ) -> list[tuple[str, QualityStats]]:
-        """Get workflow stages with poor quality scores.
+        """Get workflow stages/tiers with poor quality scores.
 
         Args:
             workflow_name: Name of workflow
-            quality_threshold: Threshold below which stage is considered underperforming
+            quality_threshold: Threshold below which stage/tier is considered underperforming
 
         Returns:
-            List of (stage_name, stats) tuples for underperforming stages
+            List of (stage_name, stats) tuples for underperforming stage/tier combinations
+            The stage_name includes the tier for clarity (e.g., "analysis/cheap")
         """
         if not self.memory or not hasattr(self.memory, "_client"):
             return []
@@ -499,22 +508,26 @@ class FeedbackLoop:
             pattern = f"feedback:{workflow_name}:*"
             keys = self.memory._client.keys(pattern)
 
-            # Extract unique stages
-            stages = set()
+            # Extract unique stage/tier combinations
+            stage_tier_combos = set()
             for key in keys:
                 if isinstance(key, bytes):
                     key = key.decode("utf-8")
                 # Parse key: feedback:{workflow}:{stage}:{tier}:{id}
                 parts = key.split(":")
                 if len(parts) >= 4:
-                    stages.add(parts[2])
+                    stage_name = parts[2]
+                    tier = parts[3]
+                    stage_tier_combos.add((stage_name, tier))
 
-            # Get stats for each stage
+            # Get stats for each stage/tier combination
             underperforming = []
-            for stage_name in stages:
-                stats = self.get_quality_stats(workflow_name, stage_name)
+            for stage_name, tier in stage_tier_combos:
+                stats = self.get_quality_stats(workflow_name, stage_name, tier=tier)
                 if stats and stats.avg_quality < quality_threshold:
-                    underperforming.append((stage_name, stats))
+                    # Include tier in the stage name for clarity
+                    stage_label = f"{stage_name}/{tier}"
+                    underperforming.append((stage_label, stats))
 
             # Sort by quality (worst first)
             underperforming.sort(key=lambda x: x[1].avg_quality)

empathy_os/workflows/output.py

@@ -326,7 +326,10 @@ class MetricsPanel:
             Rich Panel with formatted score
         """
         if not RICH_AVAILABLE or Panel is None:
-            raise RuntimeError("Rich is not available")
+            raise RuntimeError(
+                "Rich library not available. "
+                "Install with: pip install rich"
+            )
 
         style = cls.get_style(score)
         icon = cls.get_icon(score)

empathy_os/workflows/progress.py

@@ -590,7 +590,10 @@ class RichProgressReporter:
             stage_names: List of stage names for progress tracking
         """
         if not RICH_AVAILABLE:
-            raise RuntimeError("Rich library required for RichProgressReporter")
+            raise RuntimeError(
+                "Rich library required for RichProgressReporter. "
+                "Install with: pip install rich"
+            )
 
         self.workflow_name = workflow_name
         self.stage_names = stage_names
@@ -674,7 +677,10 @@ class RichProgressReporter:
             Rich Panel containing progress information
         """
         if not RICH_AVAILABLE or Panel is None or Table is None:
-            raise RuntimeError("Rich not available")
+            raise RuntimeError(
+                "Rich library not available. "
+                "Install with: pip install rich"
+            )
 
         # Build metrics table
         metrics = Table(show_header=False, box=None, padding=(0, 2))

empathy_os/cli/parsers/cache 2.py

@@ -1,65 +0,0 @@
-"""Argument parser for cache commands.
-
-Copyright 2025 Smart-AI-Memory
-Licensed under Fair Source License 0.9
-"""
-
-
-def register_parsers(subparsers):
-    """Register cache command parsers.
-
-    Args:
-        subparsers: Subparser object from main argument parser
-
-    Returns:
-        None: Adds cache subparser with stats and clear subcommands
-    """
-    from ..commands.cache import cmd_cache_clear, cmd_cache_stats
-    # Main cache command
-    cache_parser = subparsers.add_parser(
-        "cache",
-        help="Cache monitoring and management",
-        description="Monitor prompt caching performance and cost savings",
-    )
-
-    # Cache subcommands
-    cache_subparsers = cache_parser.add_subparsers(dest="cache_command", required=True)
-
-    # cache stats command
-    stats_parser = cache_subparsers.add_parser(
-        "stats",
-        help="Show cache performance statistics",
-        description="Display prompt caching metrics including hit rate and cost savings",
-    )
-
-    stats_parser.add_argument(
-        "--days",
-        type=int,
-        default=7,
-        help="Number of days to analyze (default: 7)",
-    )
-
-    stats_parser.add_argument(
-        "--format",
-        choices=["table", "json"],
-        default="table",
-        help="Output format (default: table)",
-    )
-
-    stats_parser.add_argument(
-        "--verbose",
-        "-v",
-        action="store_true",
-        help="Show detailed token metrics",
-    )
-
-    stats_parser.set_defaults(func=cmd_cache_stats)
-
-    # cache clear command (placeholder)
-    clear_parser = cache_subparsers.add_parser(
-        "clear",
-        help="Clear cache (note: Anthropic cache is server-side with 5min TTL)",
-        description="Information about cache clearing",
-    )
-
-    clear_parser.set_defaults(func=cmd_cache_clear)