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

empathy_os/redis_memory.py

@@ -1,5 +1,4 @@
-"""
-Redis Short-Term Memory for Empathy Framework
+"""Redis Short-Term Memory for Empathy Framework
 
 Per EMPATHY_PHILOSOPHY.md v1.1.0:
 - Implements fast, TTL-based working memory for agent coordination
@@ -25,25 +24,12 @@ except ImportError:
     REDIS_AVAILABLE = False
 
 
-class AccessTier(Enum):
-    """
-    Role-based access tiers per EMPATHY_PHILOSOPHY.md
-
-    Tier 1 - Observer: Read-only access to validated patterns
-    Tier 2 - Contributor: Can stage patterns for validation
-    Tier 3 - Validator: Can promote staged patterns to active
-    Tier 4 - Steward: Full access including deprecation and audit
-    """
-
-    OBSERVER = 1
-    CONTRIBUTOR = 2
-    VALIDATOR = 3
-    STEWARD = 4
+# Import AccessTier from the canonical location to avoid duplicate enums
+from .memory.short_term import AccessTier
 
 
 class TTLStrategy(Enum):
-    """
-    TTL strategies for different memory types
+    """TTL strategies for different memory types
 
     Per EMPATHY_PHILOSOPHY.md Section 9.3:
     - Working results: 1 hour
@@ -132,8 +118,7 @@ class StagedPattern:
 
 @dataclass
 class ConflictContext:
-    """
-    Context for principled negotiation
+    """Context for principled negotiation
 
     Per Getting to Yes framework:
     - Positions: What each party says they want
@@ -174,8 +159,7 @@ class ConflictContext:
 
 
 class RedisShortTermMemory:
-    """
-    Redis-backed short-term memory for agent coordination
+    """Redis-backed short-term memory for agent coordination
 
     Features:
     - Fast read/write with automatic TTL expiration
@@ -189,6 +173,7 @@ class RedisShortTermMemory:
         >>> creds = AgentCredentials("agent_1", AccessTier.CONTRIBUTOR)
         >>> memory.stash("analysis_results", {"issues": 3}, creds)
         >>> data = memory.retrieve("analysis_results", creds)
+
     """
 
     # Key prefixes for namespacing
@@ -206,8 +191,7 @@ class RedisShortTermMemory:
         password: str | None = None,
         use_mock: bool = False,
     ):
-        """
-        Initialize Redis connection
+        """Initialize Redis connection
 
         Args:
             host: Redis host
@@ -215,6 +199,7 @@ class RedisShortTermMemory:
             db: Redis database number
             password: Redis password (optional)
             use_mock: Use in-memory mock for testing
+
         """
         self.use_mock = use_mock or not REDIS_AVAILABLE
 
@@ -236,10 +221,13 @@ class RedisShortTermMemory:
             if key in self._mock_storage:
                 value, expires = self._mock_storage[key]
                 if expires is None or datetime.now().timestamp() < expires:
-                    return value
+                    return str(value) if value is not None else None
                 del self._mock_storage[key]
             return None
-        return self._client.get(key)
+        if self._client is None:
+            return None
+        result = self._client.get(key)
+        return str(result) if result else None
 
     def _set(self, key: str, value: str, ttl: int | None = None) -> bool:
         """Set value in Redis or mock"""
@@ -247,9 +235,13 @@ class RedisShortTermMemory:
             expires = datetime.now().timestamp() + ttl if ttl else None
             self._mock_storage[key] = (value, expires)
             return True
+        if self._client is None:
+            return False
         if ttl:
-            return self._client.setex(key, ttl, value)
-        return self._client.set(key, value)
+            self._client.setex(key, ttl, value)
+            return True
+        result = self._client.set(key, value)
+        return bool(result)
 
     def _delete(self, key: str) -> bool:
         """Delete key from Redis or mock"""
@@ -258,6 +250,8 @@ class RedisShortTermMemory:
                 del self._mock_storage[key]
                 return True
             return False
+        if self._client is None:
+            return False
         return self._client.delete(key) > 0
 
     def _keys(self, pattern: str) -> list[str]:
@@ -266,7 +260,10 @@ class RedisShortTermMemory:
             import fnmatch
 
             return [k for k in self._mock_storage.keys() if fnmatch.fnmatch(k, pattern)]
-        return self._client.keys(pattern)
+        if self._client is None:
+            return []
+        keys = self._client.keys(pattern)
+        return [k.decode() if isinstance(k, bytes) else str(k) for k in keys]
 
     # === Working Memory (Stash/Retrieve) ===
 
@@ -277,8 +274,7 @@ class RedisShortTermMemory:
         credentials: AgentCredentials,
         ttl: TTLStrategy = TTLStrategy.WORKING_RESULTS,
     ) -> bool:
-        """
-        Stash data in short-term memory
+        """Stash data in short-term memory
 
         Args:
             key: Unique key for the data
@@ -291,11 +287,12 @@ class RedisShortTermMemory:
 
         Example:
             >>> memory.stash("analysis_v1", {"findings": [...]}, creds)
+
         """
         if not credentials.can_stage():
             raise PermissionError(
                 f"Agent {credentials.agent_id} (Tier {credentials.tier.name}) "
-                "cannot write to memory. Requires CONTRIBUTOR or higher."
+                "cannot write to memory. Requires CONTRIBUTOR or higher.",
             )
 
         full_key = f"{self.PREFIX_WORKING}{credentials.agent_id}:{key}"
@@ -312,8 +309,7 @@ class RedisShortTermMemory:
         credentials: AgentCredentials,
         agent_id: str | None = None,
     ) -> Any | None:
-        """
-        Retrieve data from short-term memory
+        """Retrieve data from short-term memory
 
         Args:
             key: Key to retrieve
@@ -325,6 +321,7 @@ class RedisShortTermMemory:
 
         Example:
             >>> data = memory.retrieve("analysis_v1", creds)
+
         """
         owner = agent_id or credentials.agent_id
         full_key = f"{self.PREFIX_WORKING}{owner}:{key}"
@@ -337,14 +334,14 @@ class RedisShortTermMemory:
         return payload.get("data")
 
     def clear_working_memory(self, credentials: AgentCredentials) -> int:
-        """
-        Clear all working memory for an agent
+        """Clear all working memory for an agent
 
         Args:
             credentials: Agent credentials (must own the memory or be Steward)
 
         Returns:
             Number of keys deleted
+
         """
         pattern = f"{self.PREFIX_WORKING}{credentials.agent_id}:*"
         keys = self._keys(pattern)
@@ -361,8 +358,7 @@ class RedisShortTermMemory:
         pattern: StagedPattern,
         credentials: AgentCredentials,
     ) -> bool:
-        """
-        Stage a pattern for validation
+        """Stage a pattern for validation
 
         Per EMPATHY_PHILOSOPHY.md: Patterns must be staged before
         being promoted to the active library.
@@ -373,11 +369,12 @@ class RedisShortTermMemory:
 
         Returns:
             True if staged successfully
+
         """
         if not credentials.can_stage():
             raise PermissionError(
                 f"Agent {credentials.agent_id} cannot stage patterns. "
-                "Requires CONTRIBUTOR tier or higher."
+                "Requires CONTRIBUTOR tier or higher.",
             )
 
         key = f"{self.PREFIX_STAGED}{pattern.pattern_id}"
@@ -392,8 +389,7 @@ class RedisShortTermMemory:
         pattern_id: str,
         credentials: AgentCredentials,
     ) -> StagedPattern | None:
-        """
-        Retrieve a staged pattern
+        """Retrieve a staged pattern
 
         Args:
             pattern_id: Pattern ID
@@ -401,6 +397,7 @@ class RedisShortTermMemory:
 
         Returns:
             StagedPattern or None
+
         """
         key = f"{self.PREFIX_STAGED}{pattern_id}"
         raw = self._get(key)
@@ -414,14 +411,14 @@ class RedisShortTermMemory:
         self,
         credentials: AgentCredentials,
     ) -> list[StagedPattern]:
-        """
-        List all staged patterns awaiting validation
+        """List all staged patterns awaiting validation
 
         Args:
             credentials: Any tier can read
 
         Returns:
             List of staged patterns
+
         """
         pattern = f"{self.PREFIX_STAGED}*"
         keys = self._keys(pattern)
@@ -439,8 +436,7 @@ class RedisShortTermMemory:
         pattern_id: str,
         credentials: AgentCredentials,
     ) -> StagedPattern | None:
-        """
-        Promote staged pattern (remove from staging for library add)
+        """Promote staged pattern (remove from staging for library add)
 
         Args:
             pattern_id: Pattern to promote
@@ -448,11 +444,12 @@ class RedisShortTermMemory:
 
         Returns:
             The promoted pattern (for adding to PatternLibrary)
+
         """
         if not credentials.can_validate():
             raise PermissionError(
                 f"Agent {credentials.agent_id} cannot promote patterns. "
-                "Requires VALIDATOR tier or higher."
+                "Requires VALIDATOR tier or higher.",
             )
 
         pattern = self.get_staged_pattern(pattern_id, credentials)
@@ -467,8 +464,7 @@ class RedisShortTermMemory:
         credentials: AgentCredentials,
         reason: str = "",
     ) -> bool:
-        """
-        Reject a staged pattern
+        """Reject a staged pattern
 
         Args:
             pattern_id: Pattern to reject
@@ -477,11 +473,12 @@ class RedisShortTermMemory:
 
         Returns:
             True if rejected
+
         """
         if not credentials.can_validate():
             raise PermissionError(
                 f"Agent {credentials.agent_id} cannot reject patterns. "
-                "Requires VALIDATOR tier or higher."
+                "Requires VALIDATOR tier or higher.",
             )
 
         key = f"{self.PREFIX_STAGED}{pattern_id}"
@@ -497,8 +494,7 @@ class RedisShortTermMemory:
         credentials: AgentCredentials,
         batna: str | None = None,
     ) -> ConflictContext:
-        """
-        Create context for principled negotiation
+        """Create context for principled negotiation
 
         Per Getting to Yes framework:
         - Separate positions from interests
@@ -513,11 +509,12 @@ class RedisShortTermMemory:
 
         Returns:
             ConflictContext for resolution
+
         """
         if not credentials.can_stage():
             raise PermissionError(
                 f"Agent {credentials.agent_id} cannot create conflict context. "
-                "Requires CONTRIBUTOR tier or higher."
+                "Requires CONTRIBUTOR tier or higher.",
             )
 
         context = ConflictContext(
@@ -541,8 +538,7 @@ class RedisShortTermMemory:
         conflict_id: str,
         credentials: AgentCredentials,
     ) -> ConflictContext | None:
-        """
-        Retrieve conflict context
+        """Retrieve conflict context
 
         Args:
             conflict_id: Conflict identifier
@@ -550,6 +546,7 @@ class RedisShortTermMemory:
 
         Returns:
             ConflictContext or None
+
         """
         key = f"{self.PREFIX_CONFLICT}{conflict_id}"
         raw = self._get(key)
@@ -565,8 +562,7 @@ class RedisShortTermMemory:
         resolution: str,
         credentials: AgentCredentials,
     ) -> bool:
-        """
-        Mark conflict as resolved
+        """Mark conflict as resolved
 
         Args:
             conflict_id: Conflict to resolve
@@ -575,11 +571,12 @@ class RedisShortTermMemory:
 
         Returns:
             True if resolved
+
         """
         if not credentials.can_validate():
             raise PermissionError(
                 f"Agent {credentials.agent_id} cannot resolve conflicts. "
-                "Requires VALIDATOR tier or higher."
+                "Requires VALIDATOR tier or higher.",
             )
 
         context = self.get_conflict_context(conflict_id, credentials)
@@ -603,8 +600,7 @@ class RedisShortTermMemory:
         credentials: AgentCredentials,
         target_agent: str | None = None,
     ) -> bool:
-        """
-        Send coordination signal to other agents
+        """Send coordination signal to other agents
 
         Args:
             signal_type: Type of signal (e.g., "ready", "blocking", "complete")
@@ -614,11 +610,12 @@ class RedisShortTermMemory:
 
         Returns:
             True if sent
+
         """
         if not credentials.can_stage():
             raise PermissionError(
                 f"Agent {credentials.agent_id} cannot send signals. "
-                "Requires CONTRIBUTOR tier or higher."
+                "Requires CONTRIBUTOR tier or higher.",
             )
 
         target = target_agent or "broadcast"
@@ -637,8 +634,7 @@ class RedisShortTermMemory:
         credentials: AgentCredentials,
         signal_type: str | None = None,
     ) -> list[dict]:
-        """
-        Receive coordination signals
+        """Receive coordination signals
 
         Args:
             credentials: Agent receiving signals
@@ -646,6 +642,7 @@ class RedisShortTermMemory:
 
         Returns:
             List of signals
+
         """
         if signal_type:
             pattern = f"{self.PREFIX_COORDINATION}{signal_type}:*:{credentials.agent_id}"
@@ -673,8 +670,7 @@ class RedisShortTermMemory:
         credentials: AgentCredentials,
         metadata: dict | None = None,
     ) -> bool:
-        """
-        Create a collaboration session
+        """Create a collaboration session
 
         Args:
             session_id: Unique session identifier
@@ -683,6 +679,7 @@ class RedisShortTermMemory:
 
         Returns:
             True if created
+
         """
         key = f"{self.PREFIX_SESSION}{session_id}"
         payload = {
@@ -699,8 +696,7 @@ class RedisShortTermMemory:
         session_id: str,
         credentials: AgentCredentials,
     ) -> bool:
-        """
-        Join an existing session
+        """Join an existing session
 
         Args:
             session_id: Session to join
@@ -708,6 +704,7 @@ class RedisShortTermMemory:
 
         Returns:
             True if joined
+
         """
         key = f"{self.PREFIX_SESSION}{session_id}"
         raw = self._get(key)
@@ -726,8 +723,7 @@ class RedisShortTermMemory:
         session_id: str,
         credentials: AgentCredentials,
     ) -> dict | None:
-        """
-        Get session information
+        """Get session information
 
         Args:
             session_id: Session identifier
@@ -735,6 +731,7 @@ class RedisShortTermMemory:
 
         Returns:
             Session data or None
+
         """
         key = f"{self.PREFIX_SESSION}{session_id}"
         raw = self._get(key)
@@ -742,46 +739,51 @@ class RedisShortTermMemory:
         if raw is None:
             return None
 
-        return json.loads(raw)
+        result: dict = json.loads(raw)
+        return result
 
     # === Health Check ===
 
     def ping(self) -> bool:
-        """
-        Check Redis connection health
+        """Check Redis connection health
 
         Returns:
             True if connected and responsive
+
         """
         if self.use_mock:
             return True
+        if self._client is None:
+            return False
         try:
-            return self._client.ping()
+            return bool(self._client.ping())
         except Exception:
             return False
 
     def get_stats(self) -> dict:
-        """
-        Get memory statistics
+        """Get memory statistics
 
         Returns:
             Dict with memory stats
+
         """
         if self.use_mock:
             return {
                 "mode": "mock",
                 "total_keys": len(self._mock_storage),
                 "working_keys": len(
-                    [k for k in self._mock_storage if k.startswith(self.PREFIX_WORKING)]
+                    [k for k in self._mock_storage if k.startswith(self.PREFIX_WORKING)],
                 ),
                 "staged_keys": len(
-                    [k for k in self._mock_storage if k.startswith(self.PREFIX_STAGED)]
+                    [k for k in self._mock_storage if k.startswith(self.PREFIX_STAGED)],
                 ),
                 "conflict_keys": len(
-                    [k for k in self._mock_storage if k.startswith(self.PREFIX_CONFLICT)]
+                    [k for k in self._mock_storage if k.startswith(self.PREFIX_CONFLICT)],
                 ),
             }
 
+        if self._client is None:
+            return {"mode": "disconnected", "error": "No Redis client"}
         info = self._client.info("memory")
         return {
             "mode": "redis",

empathy_os/resilience/__init__.py

@@ -0,0 +1,56 @@
+"""Empathy Framework Resilience Module
+
+Provides reliability patterns for fault-tolerant wizard operations.
+
+Usage:
+    from empathy_os.resilience import retry, circuit_breaker, timeout, fallback
+
+    @retry(max_attempts=3, backoff_factor=2.0)
+    async def call_llm(prompt: str) -> str:
+        ...
+
+    @circuit_breaker(failure_threshold=5, reset_timeout=60)
+    async def external_api_call():
+        ...
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from .circuit_breaker import (
+                              CircuitBreaker,
+                              CircuitOpenError,
+                              CircuitState,
+                              circuit_breaker,
+                              get_circuit_breaker,
+)
+from .fallback import Fallback, fallback, with_fallback
+from .health import HealthCheck, HealthStatus, SystemHealth
+from .retry import RetryConfig, retry, retry_with_backoff
+from .timeout import TimeoutError as ResilienceTimeoutError
+from .timeout import timeout, with_timeout
+
+__all__ = [
+    "CircuitBreaker",
+    "CircuitOpenError",
+    "CircuitState",
+    "Fallback",
+    # Health
+    "HealthCheck",
+    "HealthStatus",
+    "ResilienceTimeoutError",
+    "RetryConfig",
+    "SystemHealth",
+    # Circuit Breaker
+    "circuit_breaker",
+    # Fallback
+    "fallback",
+    "get_circuit_breaker",
+    # Retry
+    "retry",
+    "retry_with_backoff",
+    # Timeout
+    "timeout",
+    "with_fallback",
+    "with_timeout",
+]