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

empathy_os/memory/mixins/promotion_mixin.py

@@ -0,0 +1,109 @@
+"""Pattern promotion mixin for UnifiedMemory.
+
+Handles promotion of patterns from short-term to long-term memory.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from typing import TYPE_CHECKING, Any
+
+import structlog
+
+if TYPE_CHECKING:
+    from ..long_term import Classification
+    from ..short_term import AgentCredentials, RedisShortTermMemory
+
+logger = structlog.get_logger(__name__)
+
+
+class PatternPromotionMixin:
+    """Mixin providing pattern promotion capabilities for UnifiedMemory."""
+
+    # Type hints for attributes that will be provided by UnifiedMemory
+    _short_term: "RedisShortTermMemory | None"
+    _long_term: Any  # SecureMemDocsIntegration | None
+
+    # Needs access to methods from other mixins
+    @property
+    def credentials(self) -> "AgentCredentials":
+        """Get credentials - provided by ShortTermOperationsMixin."""
+        ...
+
+    def get_staged_patterns(self) -> list[dict]:
+        """Get staged patterns - provided by ShortTermOperationsMixin."""
+        ...
+
+    def persist_pattern(
+        self,
+        content: str,
+        pattern_type: str,
+        classification: "Classification | str | None" = None,
+        auto_classify: bool = True,
+        metadata: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | None:
+        """Persist pattern - provided by LongTermOperationsMixin."""
+        ...
+
+    # =========================================================================
+    # PATTERN PROMOTION (SHORT-TERM → LONG-TERM)
+    # =========================================================================
+
+    def promote_pattern(
+        self,
+        staged_pattern_id: str,
+        classification: "Classification | str | None" = None,
+        auto_classify: bool = True,
+    ) -> dict[str, Any] | None:
+        """Promote a staged pattern from short-term to long-term memory.
+
+        Args:
+            staged_pattern_id: ID of staged pattern to promote
+            classification: Override classification (or auto-detect)
+            auto_classify: Auto-detect classification from content
+
+        Returns:
+            Long-term storage result, or None if failed
+
+        """
+        if not self._short_term or not self._long_term:
+            logger.error("memory_backends_unavailable")
+            return None
+
+        # Retrieve staged pattern
+        staged_patterns = self.get_staged_patterns()
+        staged = next(
+            (p for p in staged_patterns if p.get("pattern_id") == staged_pattern_id),
+            None,
+        )
+
+        if not staged:
+            logger.warning("staged_pattern_not_found", pattern_id=staged_pattern_id)
+            return None
+
+        # Persist to long-term storage
+        # Content is stored in context dict by stage_pattern
+        context = staged.get("context", {})
+        content = context.get("content", "") or staged.get("description", "")
+        result = self.persist_pattern(
+            content=content,
+            pattern_type=staged.get("pattern_type", "general"),
+            classification=classification,
+            auto_classify=auto_classify,
+            metadata=context,
+        )
+
+        if result:
+            # Remove from staging (use promote_pattern which handles deletion)
+            try:
+                self._short_term.promote_pattern(staged_pattern_id, self.credentials)
+            except PermissionError:
+                # If we can't promote (delete from staging), just log it
+                logger.warning("could_not_remove_from_staging", pattern_id=staged_pattern_id)
+            logger.info(
+                "pattern_promoted",
+                staged_id=staged_pattern_id,
+                long_term_id=result.get("pattern_id"),
+            )
+
+        return result

empathy_os/memory/mixins/short_term_mixin.py

@@ -0,0 +1,182 @@
+"""Short-term memory operations mixin for UnifiedMemory.
+
+Provides working memory operations (stash/retrieve) and pattern staging.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+import uuid
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+import structlog
+
+if TYPE_CHECKING:
+    from ..file_session import FileSessionMemory
+    from ..redis_bootstrap import RedisStatus
+    from ..short_term import (
+        AccessTier,
+        AgentCredentials,
+        RedisShortTermMemory,
+    )
+
+logger = structlog.get_logger(__name__)
+
+
+class ShortTermOperationsMixin:
+    """Mixin providing short-term memory operations for UnifiedMemory."""
+
+    # Type hints for attributes that will be provided by UnifiedMemory
+    user_id: str
+    access_tier: "AccessTier"
+    _file_session: "FileSessionMemory | None"
+    _short_term: "RedisShortTermMemory | None"
+    _redis_status: "RedisStatus | None"
+    config: Any  # MemoryConfig
+
+    @property
+    def credentials(self) -> "AgentCredentials":
+        """Get agent credentials for short-term memory operations."""
+        from ..short_term import AgentCredentials
+
+        return AgentCredentials(agent_id=self.user_id, tier=self.access_tier)
+
+    # =========================================================================
+    # SHORT-TERM MEMORY OPERATIONS (Working Memory)
+    # =========================================================================
+
+    def stash(self, key: str, value: Any, ttl_seconds: int | None = None) -> bool:
+        """Store data in working memory with TTL.
+
+        Uses file-based session as primary storage, with optional Redis for
+        real-time features. Data is persisted to disk automatically.
+
+        Args:
+            key: Storage key
+            value: Data to store (must be JSON-serializable)
+            ttl_seconds: Time-to-live in seconds (default from config)
+
+        Returns:
+            True if stored successfully
+
+        """
+        from ..short_term import TTLStrategy
+
+        ttl = ttl_seconds or self.config.default_ttl_seconds
+
+        # Primary: File session memory (always available)
+        if self._file_session:
+            self._file_session.stash(key, value, ttl=ttl)
+
+        # Optional: Redis for real-time sync
+        if self._short_term and self._redis_status and self._redis_status.available:
+            # Map ttl_seconds to TTLStrategy
+            ttl_strategy = TTLStrategy.WORKING_RESULTS
+            if ttl_seconds is not None:
+                # COORDINATION removed in v5.0 - use SESSION for short-lived data
+                if ttl_seconds <= TTLStrategy.SESSION.value:
+                    ttl_strategy = TTLStrategy.SESSION
+                elif ttl_seconds <= TTLStrategy.WORKING_RESULTS.value:
+                    ttl_strategy = TTLStrategy.WORKING_RESULTS
+                elif ttl_seconds <= TTLStrategy.STAGED_PATTERNS.value:
+                    ttl_strategy = TTLStrategy.STAGED_PATTERNS
+                else:
+                    ttl_strategy = TTLStrategy.CONFLICT_CONTEXT
+
+            try:
+                self._short_term.stash(key, value, self.credentials, ttl_strategy)
+            except Exception as e:
+                logger.debug("redis_stash_failed", key=key, error=str(e))
+
+        # Return True if at least one backend succeeded
+        return self._file_session is not None
+
+    def retrieve(self, key: str) -> Any | None:
+        """Retrieve data from working memory.
+
+        Checks Redis first (if available) for faster access, then falls back
+        to file-based session storage.
+
+        Args:
+            key: Storage key
+
+        Returns:
+            Stored data or None if not found
+
+        """
+        # Try Redis first (faster, if available)
+        if self._short_term and self._redis_status and self._redis_status.available:
+            try:
+                result = self._short_term.retrieve(key, self.credentials)
+                if result is not None:
+                    return result
+            except Exception as e:
+                logger.debug("redis_retrieve_failed", key=key, error=str(e))
+
+        # Fall back to file session (primary storage)
+        if self._file_session:
+            return self._file_session.retrieve(key)
+
+        return None
+
+    # =========================================================================
+    # PATTERN STAGING
+    # =========================================================================
+
+    def stage_pattern(
+        self,
+        pattern_data: dict[str, Any],
+        pattern_type: str = "general",
+        ttl_hours: int = 24,
+    ) -> str | None:
+        """Stage a pattern for validation before long-term storage.
+
+        Args:
+            pattern_data: Pattern content and metadata
+            pattern_type: Type of pattern (algorithm, protocol, etc.)
+            ttl_hours: Hours before staged pattern expires (not used in current impl)
+
+        Returns:
+            Staged pattern ID or None if failed
+
+        """
+        from ..short_term import StagedPattern
+
+        if not self._short_term:
+            logger.warning("short_term_memory_unavailable")
+            return None
+
+        # Create a StagedPattern object from the pattern_data dict
+        pattern_id = f"staged_{uuid.uuid4().hex[:12]}"
+        staged_pattern = StagedPattern(
+            pattern_id=pattern_id,
+            agent_id=self.user_id,
+            pattern_type=pattern_type,
+            name=pattern_data.get("name", f"Pattern {pattern_id[:8]}"),
+            description=pattern_data.get("description", ""),
+            code=pattern_data.get("code"),
+            context=pattern_data.get("context", {}),
+            confidence=pattern_data.get("confidence", 0.5),
+            staged_at=datetime.now(),
+            interests=pattern_data.get("interests", []),
+        )
+        # Store content in context if provided
+        if "content" in pattern_data:
+            staged_pattern.context["content"] = pattern_data["content"]
+
+        success = self._short_term.stage_pattern(staged_pattern, self.credentials)
+        return pattern_id if success else None
+
+    def get_staged_patterns(self) -> list[dict]:
+        """Get all staged patterns awaiting validation.
+
+        Returns:
+            List of staged patterns with metadata
+
+        """
+        if not self._short_term:
+            return []
+
+        staged_list = self._short_term.list_staged_patterns(self.credentials)
+        return [p.to_dict() for p in staged_list]

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:
@@ -2034,6 +2076,9 @@ class RedisShortTermMemory:
                     f"Confidence {pattern.confidence} below threshold {min_confidence}",
                 )
             del self._mock_storage[key]
+            # Also invalidate local cache
+            if key in self._local_cache:
+                del self._local_cache[key]
             return True, pattern, "Pattern promoted successfully"
 
         if self._client is None:
@@ -2063,6 +2108,10 @@ class RedisShortTermMemory:
             pipe.delete(key)
             pipe.execute()
 
+            # Also invalidate local cache
+            if key in self._local_cache:
+                del self._local_cache[key]
+
             return True, pattern, "Pattern promoted successfully"
 
         except redis.WatchError: