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

empathy_os/memory/mixins/handoff_mixin.py

@@ -1,208 +0,0 @@
-"""Session handoff and export mixin for UnifiedMemory.
-
-Provides compact state generation and Claude Code integration.
-
-Copyright 2025 Smart AI Memory, LLC
-Licensed under Fair Source 0.9
-"""
-
-from datetime import datetime
-from pathlib import Path
-from typing import TYPE_CHECKING, Any
-
-import structlog
-
-if TYPE_CHECKING:
-    from ..file_session import FileSessionMemory
-
-logger = structlog.get_logger(__name__)
-
-
-class HandoffAndExportMixin:
-    """Mixin providing session handoff and export capabilities for UnifiedMemory."""
-
-    # Type hints for attributes that will be provided by UnifiedMemory
-    _file_session: "FileSessionMemory | None"
-    config: Any  # MemoryConfig
-
-    # Needs access to capabilities from CapabilitiesMixin
-    def get_capabilities(self) -> dict[str, bool]:
-        """Get capabilities - provided by CapabilitiesMixin."""
-        ...
-
-    # =========================================================================
-    # COMPACT STATE GENERATION
-    # =========================================================================
-
-    def generate_compact_state(self) -> str:
-        """Generate SBAR-format compact state from current session.
-
-        Creates a human-readable summary of the current session state,
-        suitable for Claude Code's .claude/compact-state.md file.
-
-        Returns:
-            Markdown-formatted compact state string
-        """
-        lines = [
-            "# Compact State - Session Handoff",
-            "",
-            f"**Generated:** {datetime.now().strftime('%Y-%m-%d %H:%M')}",
-        ]
-
-        # Add session info
-        if self._file_session:
-            session = self._file_session._state
-            lines.extend(
-                [
-                    f"**Session ID:** {session.session_id}",
-                    f"**User ID:** {session.user_id}",
-                    "",
-                ]
-            )
-
-        lines.extend(
-            [
-                "## SBAR Handoff",
-                "",
-                "### Situation",
-            ]
-        )
-
-        # Get context from file session
-        context = {}
-        if self._file_session:
-            context = self._file_session.get_all_context()
-
-        situation = context.get("situation", "Session in progress.")
-        background = context.get("background", "No background information recorded.")
-        assessment = context.get("assessment", "No assessment recorded.")
-        recommendation = context.get("recommendation", "Continue with current task.")
-
-        lines.extend(
-            [
-                situation,
-                "",
-                "### Background",
-                background,
-                "",
-                "### Assessment",
-                assessment,
-                "",
-                "### Recommendation",
-                recommendation,
-                "",
-            ]
-        )
-
-        # Add working memory summary
-        if self._file_session:
-            working_keys = list(self._file_session._state.working_memory.keys())
-            if working_keys:
-                lines.extend(
-                    [
-                        "## Working Memory",
-                        "",
-                        f"**Active keys:** {len(working_keys)}",
-                        "",
-                    ]
-                )
-                for key in working_keys[:10]:  # Show max 10
-                    lines.append(f"- `{key}`")
-                if len(working_keys) > 10:
-                    lines.append(f"- ... and {len(working_keys) - 10} more")
-                lines.append("")
-
-        # Add staged patterns summary
-        if self._file_session:
-            staged = list(self._file_session._state.staged_patterns.values())
-            if staged:
-                lines.extend(
-                    [
-                        "## Staged Patterns",
-                        "",
-                        f"**Pending validation:** {len(staged)}",
-                        "",
-                    ]
-                )
-                for pattern in staged[:5]:  # Show max 5
-                    lines.append(
-                        f"- {pattern.name} ({pattern.pattern_type}, conf: {pattern.confidence:.2f})"
-                    )
-                if len(staged) > 5:
-                    lines.append(f"- ... and {len(staged) - 5} more")
-                lines.append("")
-
-        # Add capabilities
-        caps = self.get_capabilities()
-        lines.extend(
-            [
-                "## Capabilities",
-                "",
-                f"- File session: {'Yes' if caps['file_session'] else 'No'}",
-                f"- Redis: {'Yes' if caps['redis'] else 'No'}",
-                f"- Long-term memory: {'Yes' if caps['long_term'] else 'No'}",
-                f"- Real-time sync: {'Yes' if caps['realtime'] else 'No'}",
-                "",
-            ]
-        )
-
-        return "\n".join(lines)
-
-    def export_to_claude_md(self, path: str | None = None) -> Path:
-        """Export current session state to Claude Code's compact-state.md.
-
-        Args:
-            path: Path to write to (defaults to config.compact_state_path)
-
-        Returns:
-            Path where state was written
-        """
-        from empathy_os.config import _validate_file_path
-
-        path = path or self.config.compact_state_path
-        validated_path = _validate_file_path(path)
-
-        # Ensure parent directory exists
-        validated_path.parent.mkdir(parents=True, exist_ok=True)
-
-        # Generate and write compact state
-        content = self.generate_compact_state()
-        validated_path.write_text(content, encoding="utf-8")
-
-        logger.info("compact_state_exported", path=str(validated_path))
-        return validated_path
-
-    def set_handoff(
-        self,
-        situation: str,
-        background: str,
-        assessment: str,
-        recommendation: str,
-        **extra_context,
-    ) -> None:
-        """Set SBAR handoff context for session continuity.
-
-        This data is used by generate_compact_state() and export_to_claude_md().
-
-        Args:
-            situation: Current situation summary
-            background: Relevant background information
-            assessment: Assessment of progress/state
-            recommendation: Recommended next steps
-            **extra_context: Additional context key-value pairs
-        """
-        if not self._file_session:
-            logger.warning("file_session_not_available")
-            return
-
-        self._file_session.set_context("situation", situation)
-        self._file_session.set_context("background", background)
-        self._file_session.set_context("assessment", assessment)
-        self._file_session.set_context("recommendation", recommendation)
-
-        for key, value in extra_context.items():
-            self._file_session.set_context(key, value)
-
-        # Auto-export if configured
-        if self.config.auto_generate_compact_state:
-            self.export_to_claude_md()

empathy_os/memory/mixins/lifecycle_mixin.py

@@ -1,49 +0,0 @@
-"""Lifecycle management mixin for UnifiedMemory.
-
-Provides resource cleanup and context manager protocol.
-
-Copyright 2025 Smart AI Memory, LLC
-Licensed under Fair Source 0.9
-"""
-
-from typing import TYPE_CHECKING
-
-import structlog
-
-if TYPE_CHECKING:
-    from ..file_session import FileSessionMemory
-    from ..short_term import RedisShortTermMemory
-
-logger = structlog.get_logger(__name__)
-
-
-class LifecycleMixin:
-    """Mixin providing lifecycle management for UnifiedMemory."""
-
-    # Type hints for attributes that will be provided by UnifiedMemory
-    _file_session: "FileSessionMemory | None"
-    _short_term: "RedisShortTermMemory | None"
-
-    def save(self) -> None:
-        """Explicitly save all memory state."""
-        if self._file_session:
-            self._file_session.save()
-        logger.debug("memory_saved")
-
-    def close(self) -> None:
-        """Close all memory backends and save state."""
-        if self._file_session:
-            self._file_session.close()
-
-        if self._short_term and hasattr(self._short_term, "close"):
-            self._short_term.close()
-
-        logger.info("unified_memory_closed")
-
-    def __enter__(self):
-        """Context manager entry."""
-        return self
-
-    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
-        """Context manager exit - close all backends."""
-        self.close()

empathy_os/memory/mixins/long_term_mixin.py

@@ -1,352 +0,0 @@
-"""Long-term memory operations mixin for UnifiedMemory.
-
-Provides pattern persistence, retrieval, search, and caching.
-
-Copyright 2025 Smart AI Memory, LLC
-Licensed under Fair Source 0.9
-"""
-
-import heapq
-import json
-from collections.abc import Iterator
-from pathlib import Path
-from typing import TYPE_CHECKING, Any
-
-import structlog
-
-if TYPE_CHECKING:
-    from ..long_term import Classification
-
-logger = structlog.get_logger(__name__)
-
-
-class LongTermOperationsMixin:
-    """Mixin providing long-term memory operations for UnifiedMemory."""
-
-    # Type hints for attributes that will be provided by UnifiedMemory
-    user_id: str
-    _long_term: Any  # SecureMemDocsIntegration | None
-    _pattern_cache: dict[str, dict[str, Any]]
-    _pattern_cache_max_size: int
-
-    # =========================================================================
-    # LONG-TERM MEMORY OPERATIONS
-    # =========================================================================
-
-    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:
-        """Store a pattern in long-term memory with security controls.
-
-        Args:
-            content: Pattern content
-            pattern_type: Type of pattern (algorithm, protocol, etc.)
-            classification: Security classification (PUBLIC/INTERNAL/SENSITIVE)
-            auto_classify: Auto-detect classification from content
-            metadata: Additional metadata to store
-
-        Returns:
-            Storage result with pattern_id and classification, or None if failed
-
-        """
-        from ..long_term import Classification
-
-        if not self._long_term:
-            logger.error("long_term_memory_unavailable")
-            return None
-
-        try:
-            # Convert string classification to enum if needed
-            explicit_class = None
-            if classification is not None:
-                if isinstance(classification, str):
-                    explicit_class = Classification[classification.upper()]
-                else:
-                    explicit_class = classification
-
-            result = self._long_term.store_pattern(
-                content=content,
-                pattern_type=pattern_type,
-                user_id=self.user_id,
-                explicit_classification=explicit_class,
-                auto_classify=auto_classify,
-                custom_metadata=metadata,
-            )
-            logger.info(
-                "pattern_persisted",
-                pattern_id=result.get("pattern_id"),
-                classification=result.get("classification"),
-            )
-            return result
-        except Exception as e:
-            logger.error("persist_pattern_failed", error=str(e))
-            return None
-
-    def _cache_pattern(self, pattern_id: str, pattern: dict[str, Any]) -> None:
-        """Add pattern to LRU cache, evicting oldest if at capacity."""
-        # Simple LRU: remove oldest entry if at max size
-        if len(self._pattern_cache) >= self._pattern_cache_max_size:
-            # Remove first (oldest) item
-            oldest_key = next(iter(self._pattern_cache))
-            del self._pattern_cache[oldest_key]
-
-        self._pattern_cache[pattern_id] = pattern
-
-    def recall_pattern(
-        self,
-        pattern_id: str,
-        check_permissions: bool = True,
-        use_cache: bool = True,
-    ) -> dict[str, Any] | None:
-        """Retrieve a pattern from long-term memory.
-
-        Uses LRU cache for frequently accessed patterns to reduce I/O.
-
-        Args:
-            pattern_id: ID of pattern to retrieve
-            check_permissions: Verify user has access to pattern
-            use_cache: Whether to use/update the pattern cache (default: True)
-
-        Returns:
-            Pattern data with content and metadata, or None if not found
-
-        """
-        if not self._long_term:
-            logger.error("long_term_memory_unavailable")
-            return None
-
-        # Check cache first (if enabled)
-        if use_cache and pattern_id in self._pattern_cache:
-            logger.debug("pattern_cache_hit", pattern_id=pattern_id)
-            return self._pattern_cache[pattern_id]
-
-        try:
-            pattern = self._long_term.retrieve_pattern(
-                pattern_id=pattern_id,
-                user_id=self.user_id,
-                check_permissions=check_permissions,
-            )
-
-            # Cache the result (if enabled and pattern found)
-            if use_cache and pattern:
-                self._cache_pattern(pattern_id, pattern)
-
-            return pattern
-        except Exception as e:
-            logger.error("recall_pattern_failed", pattern_id=pattern_id, error=str(e))
-            return None
-
-    def clear_pattern_cache(self) -> int:
-        """Clear the pattern lookup cache.
-
-        Returns:
-            Number of entries cleared
-        """
-        count = len(self._pattern_cache)
-        self._pattern_cache.clear()
-        logger.debug("pattern_cache_cleared", entries=count)
-        return count
-
-    # =========================================================================
-    # PATTERN SEARCH
-    # =========================================================================
-
-    def _score_pattern(
-        self,
-        pattern: dict[str, Any],
-        query_lower: str,
-        query_words: list[str],
-    ) -> float:
-        """Calculate relevance score for a pattern.
-
-        Args:
-            pattern: Pattern data dictionary
-            query_lower: Lowercase query string
-            query_words: Pre-split query words (length >= 3)
-
-        Returns:
-            Relevance score (0.0 if no match)
-        """
-        if not query_lower:
-            return 1.0  # No query - all patterns have equal score
-
-        content = str(pattern.get("content", "")).lower()
-        metadata_str = str(pattern.get("metadata", {})).lower()
-
-        score = 0.0
-
-        # Exact phrase match in content (highest score)
-        if query_lower in content:
-            score += 10.0
-
-        # Keyword matching (medium score)
-        for word in query_words:
-            if word in content:
-                score += 2.0
-            if word in metadata_str:
-                score += 1.0
-
-        return score
-
-    def _filter_and_score_patterns(
-        self,
-        query: str | None,
-        pattern_type: str | None,
-        classification: "Classification | None",
-    ) -> Iterator[tuple[float, dict[str, Any]]]:
-        """Generator that filters and scores patterns.
-
-        Memory-efficient: yields (score, pattern) tuples one at a time.
-        Use with heapq.nlargest() for efficient top-N selection.
-
-        Args:
-            query: Search query (case-insensitive)
-            pattern_type: Filter by pattern type
-            classification: Filter by classification level
-
-        Yields:
-            Tuples of (score, pattern) for matching patterns
-        """
-        from ..long_term import Classification
-
-        query_lower = query.lower() if query else ""
-        query_words = [w for w in query_lower.split() if len(w) >= 3] if query else []
-
-        for pattern in self._iter_all_patterns():
-            # Apply filters
-            if pattern_type and pattern.get("pattern_type") != pattern_type:
-                continue
-
-            if classification:
-                pattern_class = pattern.get("classification")
-                if isinstance(classification, Classification):
-                    if pattern_class != classification.value:
-                        continue
-                elif pattern_class != classification:
-                    continue
-
-            # Calculate relevance score
-            score = self._score_pattern(pattern, query_lower, query_words)
-
-            # Skip if no matches found (when query is provided)
-            if query and score == 0.0:
-                continue
-
-            yield (score, pattern)
-
-    def search_patterns(
-        self,
-        query: str | None = None,
-        pattern_type: str | None = None,
-        classification: "Classification | None" = None,
-        limit: int = 10,
-    ) -> list[dict[str, Any]]:
-        """Search patterns in long-term memory with keyword matching and relevance scoring.
-
-        Implements keyword-based search with:
-        1. Full-text search in pattern content and metadata
-        2. Filter by pattern_type and classification
-        3. Relevance scoring (exact matches rank higher)
-        4. Results sorted by relevance
-
-        Memory-efficient: Uses generators and heapq.nlargest() to avoid
-        loading all patterns into memory. Only keeps top N results.
-
-        Args:
-            query: Text to search for in pattern content (case-insensitive)
-            pattern_type: Filter by pattern type (e.g., "meta_workflow_execution")
-            classification: Filter by classification level
-            limit: Maximum results to return
-
-        Returns:
-            List of matching patterns with metadata, sorted by relevance
-
-        Example:
-            >>> patterns = memory.search_patterns(
-            ...     query="successful workflows",
-            ...     pattern_type="meta_workflow_execution",
-            ...     limit=5
-            ... )
-        """
-        if not self._long_term:
-            logger.debug("long_term_memory_unavailable")
-            return []
-
-        try:
-            # Use heapq.nlargest for memory-efficient top-N selection
-            # This avoids loading all patterns into memory at once
-            scored_patterns = heapq.nlargest(
-                limit,
-                self._filter_and_score_patterns(query, pattern_type, classification),
-                key=lambda x: x[0],
-            )
-
-            # Return patterns without scores
-            return [pattern for _, pattern in scored_patterns]
-
-        except Exception as e:
-            logger.error("pattern_search_failed", error=str(e))
-            return []
-
-    # =========================================================================
-    # PATTERN ITERATION (Internal Helpers)
-    # =========================================================================
-
-    def _get_storage_dir(self) -> Path | None:
-        """Get the storage directory from long-term memory backend.
-
-        Returns:
-            Path to storage directory, or None if unavailable.
-        """
-        if not self._long_term:
-            return None
-
-        # Try different ways to access storage directory
-        if hasattr(self._long_term, "storage_dir"):
-            return Path(self._long_term.storage_dir)
-        elif hasattr(self._long_term, "storage"):
-            if hasattr(self._long_term.storage, "storage_dir"):
-                return Path(self._long_term.storage.storage_dir)
-        elif hasattr(self._long_term, "_storage"):
-            if hasattr(self._long_term._storage, "storage_dir"):
-                return Path(self._long_term._storage.storage_dir)
-
-        return None
-
-    def _iter_all_patterns(self) -> Iterator[dict[str, Any]]:
-        """Iterate over all patterns from long-term memory storage.
-
-        Memory-efficient generator that yields patterns one at a time,
-        avoiding loading all patterns into memory simultaneously.
-
-        Yields:
-            Pattern data dictionaries
-
-        Note:
-            This is O(1) memory vs O(n) for _get_all_patterns().
-            Use this for large datasets or when streaming is acceptable.
-        """
-        storage_dir = self._get_storage_dir()
-        if not storage_dir:
-            logger.warning("cannot_access_storage_directory")
-            return
-
-        if not storage_dir.exists():
-            return
-
-        # Yield patterns one at a time (memory-efficient)
-        for pattern_file in storage_dir.rglob("*.json"):
-            try:
-                with pattern_file.open("r", encoding="utf-8") as f:
-                    yield json.load(f)
-            except json.JSONDecodeError as e:
-                logger.debug("pattern_json_decode_failed", file=str(pattern_file), error=str(e))
-                continue
-            except Exception as e:
-                logger.debug("pattern_load_failed", file=str(pattern_file), error=str(e))
-                continue