attune-ai 2.1.5__py3-none-any.whl → 2.2.0__py3-none-any.whl

attune/memory/short_term/caching.py

@@ -0,0 +1,227 @@
+"""Local LRU cache layer for Redis operations.
+
+This module provides a two-tier caching strategy:
+1. Local in-memory LRU cache (fast, limited size)
+2. Redis (persistent, shared across processes)
+
+The local cache reduces Redis round-trips for frequently accessed data.
+Benchmark: reduces latency from 37ms (Redis) to <0.001ms (local cache).
+
+Classes:
+    CacheManager: LRU cache with TTL support
+
+Example:
+    >>> from attune.memory.short_term.caching import CacheManager
+    >>> cache = CacheManager(enabled=True, max_size=1000)
+    >>> cache.add("key", "value")
+    >>> cache.get("key")
+    'value'
+    >>> cache.get_stats()
+    {'enabled': True, 'size': 1, 'max_size': 1000, 'hits': 1, ...}
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING
+
+import structlog
+
+if TYPE_CHECKING:
+    pass
+
+logger = structlog.get_logger(__name__)
+
+
+class CacheManager:
+    """Local LRU cache manager for two-tier caching.
+
+    Provides fast local caching with LRU eviction to reduce
+    Redis/mock storage round-trips for frequently accessed keys.
+
+    The cache stores tuples of (value, timestamp, last_access) for
+    each key, enabling both TTL expiration and LRU eviction.
+
+    Attributes:
+        enabled: Whether caching is active
+        max_size: Maximum number of entries to cache
+        hits: Total cache hits
+        misses: Total cache misses
+
+    Example:
+        >>> cache = CacheManager(enabled=True, max_size=100)
+        >>> cache.add("user:123", '{"name": "Alice"}')
+        >>> value = cache.get("user:123")
+        >>> stats = cache.get_stats()
+        >>> print(f"Hit rate: {stats['hit_rate']:.1f}%")
+    """
+
+    def __init__(
+        self,
+        enabled: bool = True,
+        max_size: int = 1000,
+    ) -> None:
+        """Initialize cache manager.
+
+        Args:
+            enabled: Whether local caching is enabled
+            max_size: Maximum number of entries to cache (LRU eviction)
+        """
+        self.enabled = enabled
+        self.max_size = max_size
+
+        # Cache storage: key -> (value, timestamp, last_access)
+        self._cache: dict[str, tuple[str, float, float]] = {}
+        self._hits = 0
+        self._misses = 0
+
+    @property
+    def hits(self) -> int:
+        """Total cache hits."""
+        return self._hits
+
+    @property
+    def misses(self) -> int:
+        """Total cache misses."""
+        return self._misses
+
+    def get(self, key: str) -> str | None:
+        """Get value from local cache.
+
+        Updates last_access time for LRU tracking on hit.
+        Increments hit/miss counters for statistics.
+
+        Args:
+            key: Cache key to retrieve
+
+        Returns:
+            Cached value or None if not found or disabled
+        """
+        if not self.enabled:
+            self._misses += 1
+            return None
+
+        if key in self._cache:
+            value, timestamp, _last_access = self._cache[key]
+            now = time.time()
+            # Update last access time for LRU
+            self._cache[key] = (value, timestamp, now)
+            self._hits += 1
+            return value
+
+        self._misses += 1
+        return None
+
+    def add(self, key: str, value: str) -> None:
+        """Add entry to local cache with LRU eviction.
+
+        If cache is at max capacity, evicts the least recently
+        accessed entry before adding the new one.
+
+        Args:
+            key: Cache key
+            value: Value to cache
+        """
+        if not self.enabled:
+            return
+
+        now = time.time()
+
+        # Evict oldest entry if cache is full
+        if len(self._cache) >= self.max_size:
+            # Find key with oldest last_access time (LRU)
+            oldest_key = min(self._cache, key=lambda k: self._cache[k][2])
+            del self._cache[oldest_key]
+
+        # Add new entry: (value, timestamp, last_access)
+        self._cache[key] = (value, now, now)
+
+    def remove(self, key: str) -> bool:
+        """Remove entry from cache.
+
+        Args:
+            key: Cache key to remove
+
+        Returns:
+            True if key was present and removed
+        """
+        if key in self._cache:
+            del self._cache[key]
+            return True
+        return False
+
+    def invalidate(self, key: str) -> bool:
+        """Invalidate (remove) entry from cache.
+
+        Alias for remove() to match common cache API terminology.
+
+        Args:
+            key: Cache key to invalidate
+
+        Returns:
+            True if key was present and invalidated
+        """
+        return self.remove(key)
+
+    def contains(self, key: str) -> bool:
+        """Check if key exists in cache (without updating access time).
+
+        Args:
+            key: Cache key to check
+
+        Returns:
+            True if key exists in cache
+        """
+        return self.enabled and key in self._cache
+
+    def clear(self) -> int:
+        """Clear all entries from local cache.
+
+        Resets hit/miss counters to zero.
+
+        Returns:
+            Number of entries cleared
+        """
+        count = len(self._cache)
+        self._cache.clear()
+        self._hits = 0
+        self._misses = 0
+        logger.info("local_cache_cleared", entries_cleared=count)
+        return count
+
+    def get_stats(self) -> dict:
+        """Get local cache performance statistics.
+
+        Returns:
+            Dict with cache stats including:
+            - enabled: Whether caching is active
+            - size: Current number of cached entries
+            - max_size: Maximum cache capacity
+            - hits: Total cache hits
+            - misses: Total cache misses
+            - hit_rate: Percentage of requests served from cache
+            - total_requests: Total get requests
+        """
+        total = self._hits + self._misses
+        hit_rate = (self._hits / total * 100) if total > 0 else 0.0
+
+        return {
+            "enabled": self.enabled,
+            "size": len(self._cache),
+            "max_size": self.max_size,
+            "hits": self._hits,
+            "misses": self._misses,
+            "hit_rate": hit_rate,
+            "total_requests": total,
+        }
+
+    def __len__(self) -> int:
+        """Return number of cached entries."""
+        return len(self._cache)
+
+    def __contains__(self, key: str) -> bool:
+        """Support 'in' operator."""
+        return self.contains(key)

attune/memory/short_term/conflicts.py

@@ -0,0 +1,265 @@
+"""Conflict negotiation for multi-agent collaboration.
+
+This module provides principled negotiation support per "Getting to Yes":
+- Separate positions from interests
+- Define BATNA before negotiating
+- Track resolution outcomes
+
+Key Prefix: PREFIX_CONFLICT = "empathy:conflict:"
+
+Classes:
+    ConflictNegotiation: Conflict context and resolution operations
+
+Example:
+    >>> from attune.memory.short_term.conflicts import ConflictNegotiation
+    >>> from attune.memory.types import AgentCredentials, AccessTier
+    >>> negotiation = ConflictNegotiation(base_ops)
+    >>> creds = AgentCredentials("agent_1", AccessTier.CONTRIBUTOR)
+    >>> context = negotiation.create_conflict_context(
+    ...     "conflict_1",
+    ...     positions={"agent_1": "Use Redis", "agent_2": "Use SQLite"},
+    ...     interests={"agent_1": ["speed", "scale"], "agent_2": ["simplicity"]},
+    ...     credentials=creds,
+    ... )
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+import structlog
+
+from attune.memory.types import (
+    AgentCredentials,
+    ConflictContext,
+    TTLStrategy,
+)
+
+if TYPE_CHECKING:
+    from attune.memory.short_term.base import BaseOperations
+
+logger = structlog.get_logger(__name__)
+
+
+class ConflictNegotiation:
+    """Conflict context and resolution operations.
+
+    Implements principled negotiation per "Getting to Yes" framework:
+    - Separate positions from interests
+    - Define BATNA (Best Alternative to Negotiated Agreement)
+    - Track resolution outcomes for learning
+
+    The class is designed to be composed with BaseOperations
+    for dependency injection.
+
+    Attributes:
+        PREFIX_CONFLICT: Key prefix for conflict context namespace
+
+    Example:
+        >>> negotiation = ConflictNegotiation(base_ops)
+        >>> creds = AgentCredentials("agent_1", AccessTier.CONTRIBUTOR)
+        >>> context = negotiation.create_conflict_context(...)
+        >>> negotiation.resolve_conflict("conflict_1", "Chose Redis", validator_creds)
+    """
+
+    PREFIX_CONFLICT = "empathy:conflict:"
+
+    def __init__(self, base: BaseOperations) -> None:
+        """Initialize conflict negotiation operations.
+
+        Args:
+            base: BaseOperations instance for storage access
+        """
+        self._base = base
+
+    def create_conflict_context(
+        self,
+        conflict_id: str,
+        positions: dict[str, Any],
+        interests: dict[str, list[str]],
+        credentials: AgentCredentials,
+        batna: str | None = None,
+    ) -> ConflictContext:
+        """Create context for principled negotiation.
+
+        Per Getting to Yes framework:
+        - Separate positions from interests
+        - Define BATNA before negotiating
+
+        Args:
+            conflict_id: Unique conflict identifier
+            positions: agent_id -> their stated position
+            interests: agent_id -> underlying interests
+            credentials: Must be CONTRIBUTOR or higher
+            batna: Best Alternative to Negotiated Agreement
+
+        Returns:
+            ConflictContext for resolution
+
+        Raises:
+            ValueError: If conflict_id is empty
+            TypeError: If positions or interests are not dicts
+            PermissionError: If credentials lack permission
+
+        Example:
+            >>> context = negotiation.create_conflict_context(
+            ...     "conflict_1",
+            ...     positions={"a1": "Redis", "a2": "SQLite"},
+            ...     interests={"a1": ["speed"], "a2": ["simplicity"]},
+            ...     credentials=creds,
+            ...     batna="Use file-based storage",
+            ... )
+        """
+        # Pattern 1: String ID validation
+        if not conflict_id or not conflict_id.strip():
+            raise ValueError(f"conflict_id cannot be empty. Got: {conflict_id!r}")
+
+        # Pattern 5: Type validation
+        if not isinstance(positions, dict):
+            raise TypeError(f"positions must be dict, got {type(positions).__name__}")
+        if not isinstance(interests, dict):
+            raise TypeError(f"interests must be dict, got {type(interests).__name__}")
+
+        if not credentials.can_stage():
+            raise PermissionError(
+                f"Agent {credentials.agent_id} cannot create conflict context. "
+                "Requires CONTRIBUTOR tier or higher.",
+            )
+
+        context = ConflictContext(
+            conflict_id=conflict_id,
+            positions=positions,
+            interests=interests,
+            batna=batna,
+        )
+
+        key = f"{self.PREFIX_CONFLICT}{conflict_id}"
+        self._base._set(
+            key,
+            json.dumps(context.to_dict()),
+            TTLStrategy.CONFLICT_CONTEXT.value,
+        )
+
+        logger.info(
+            "conflict_context_created",
+            conflict_id=conflict_id,
+            agent_count=len(positions),
+            has_batna=batna is not None,
+        )
+
+        return context
+
+    def get_conflict_context(
+        self,
+        conflict_id: str,
+        credentials: AgentCredentials,
+    ) -> ConflictContext | None:
+        """Retrieve conflict context.
+
+        Args:
+            conflict_id: Conflict identifier
+            credentials: Any tier can read
+
+        Returns:
+            ConflictContext or None if not found
+
+        Raises:
+            ValueError: If conflict_id is empty
+
+        Example:
+            >>> context = negotiation.get_conflict_context("conflict_1", creds)
+            >>> if context:
+            ...     print(f"BATNA: {context.batna}")
+        """
+        # Pattern 1: String ID validation
+        if not conflict_id or not conflict_id.strip():
+            raise ValueError(f"conflict_id cannot be empty. Got: {conflict_id!r}")
+
+        key = f"{self.PREFIX_CONFLICT}{conflict_id}"
+        raw = self._base._get(key)
+
+        if raw is None:
+            return None
+
+        return ConflictContext.from_dict(json.loads(raw))
+
+    def resolve_conflict(
+        self,
+        conflict_id: str,
+        resolution: str,
+        credentials: AgentCredentials,
+    ) -> bool:
+        """Mark conflict as resolved.
+
+        Args:
+            conflict_id: Conflict to resolve
+            resolution: How it was resolved
+            credentials: Must be VALIDATOR or higher
+
+        Returns:
+            True if resolved
+
+        Raises:
+            PermissionError: If credentials lack validation access
+
+        Example:
+            >>> negotiation.resolve_conflict(
+            ...     "conflict_1",
+            ...     "Chose Redis for better scaling",
+            ...     validator_creds,
+            ... )
+            True
+        """
+        if not credentials.can_validate():
+            raise PermissionError(
+                f"Agent {credentials.agent_id} cannot resolve conflicts. "
+                "Requires VALIDATOR tier or higher.",
+            )
+
+        context = self.get_conflict_context(conflict_id, credentials)
+        if context is None:
+            return False
+
+        context.resolved = True
+        context.resolution = resolution
+
+        key = f"{self.PREFIX_CONFLICT}{conflict_id}"
+        # Keep resolved conflicts longer for audit
+        self._base._set(key, json.dumps(context.to_dict()), TTLStrategy.CONFLICT_CONTEXT.value)
+
+        logger.info(
+            "conflict_resolved",
+            conflict_id=conflict_id,
+            agent_id=credentials.agent_id,
+        )
+
+        return True
+
+    def list_active_conflicts(
+        self,
+        credentials: AgentCredentials,
+    ) -> list[ConflictContext]:
+        """List all active (unresolved) conflicts.
+
+        Args:
+            credentials: Any tier can read
+
+        Returns:
+            List of unresolved conflict contexts
+        """
+        pattern = f"{self.PREFIX_CONFLICT}*"
+        keys = self._base._keys(pattern)
+        conflicts = []
+
+        for key in keys:
+            raw = self._base._get(key)
+            if raw:
+                context = ConflictContext.from_dict(json.loads(raw))
+                if not context.resolved:
+                    conflicts.append(context)
+
+        return conflicts

attune/memory/short_term/cross_session.py

@@ -0,0 +1,122 @@
+"""Cross-session coordination for distributed agents.
+
+This module enables coordination across multiple sessions:
+- Enable cross-session communication
+- Check cross-session availability
+- Coordinate distributed agent activities
+
+Use Cases:
+- Multi-process agent coordination
+- Distributed workflow execution
+- Shared state across sessions
+
+Classes:
+    CrossSessionManager: Cross-session coordination operations
+
+Example:
+    >>> from attune.memory.short_term.cross_session import CrossSessionManager
+    >>> from attune.memory.types import AccessTier
+    >>> cross_session = CrossSessionManager(base_ops)
+    >>> if cross_session.available():
+    ...     coordinator = cross_session.enable(AccessTier.CONTRIBUTOR)
+    ...     print(f"Session ID: {coordinator.agent_id}")
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import structlog
+
+from attune.memory.types import AccessTier
+
+if TYPE_CHECKING:
+    from attune.memory.short_term.base import BaseOperations
+
+logger = structlog.get_logger(__name__)
+
+
+class CrossSessionManager:
+    """Cross-session coordination operations.
+
+    Provides coordination capabilities for agents running in
+    different Claude Code sessions using Redis as the coordination
+    backbone.
+
+    The class is designed to be composed with BaseOperations
+    for dependency injection.
+
+    Example:
+        >>> cross_session = CrossSessionManager(base_ops)
+        >>> if cross_session.available():
+        ...     coordinator = cross_session.enable(AccessTier.CONTRIBUTOR)
+        ...     sessions = coordinator.get_active_sessions()
+    """
+
+    def __init__(self, base: BaseOperations) -> None:
+        """Initialize cross-session manager.
+
+        Args:
+            base: BaseOperations instance for Redis client access
+        """
+        self._base = base
+
+    def enable(
+        self,
+        access_tier: AccessTier = AccessTier.CONTRIBUTOR,
+        auto_announce: bool = True,
+    ) -> Any:
+        """Enable cross-session communication for this memory instance.
+
+        This allows agents in different Claude Code sessions to communicate
+        and coordinate via Redis.
+
+        Args:
+            access_tier: Access tier for this session
+            auto_announce: Whether to announce presence automatically
+
+        Returns:
+            CrossSessionCoordinator instance
+
+        Raises:
+            ValueError: If in mock mode (Redis required for cross-session)
+
+        Example:
+            >>> coordinator = cross_session.enable(AccessTier.CONTRIBUTOR)
+            >>> print(f"Session ID: {coordinator.agent_id}")
+            >>> sessions = coordinator.get_active_sessions()
+        """
+        if self._base.use_mock:
+            raise ValueError(
+                "Cross-session communication requires Redis. "
+                "Set REDIS_HOST/REDIS_PORT or disable mock mode."
+            )
+
+        # Import lazily to avoid circular imports
+        from attune.memory.cross_session import CrossSessionCoordinator, SessionType
+
+        # The coordinator expects a memory instance with full API
+        # For now, pass the base which should be extended by facade
+        coordinator = CrossSessionCoordinator(
+            memory=self._base,  # type: ignore[arg-type]
+            session_type=SessionType.CLAUDE,
+            access_tier=access_tier,
+            auto_announce=auto_announce,
+        )
+
+        return coordinator
+
+    def available(self) -> bool:
+        """Check if cross-session communication is available.
+
+        Returns:
+            True if Redis is connected (not mock mode)
+
+        Example:
+            >>> if cross_session.available():
+            ...     coordinator = cross_session.enable()
+        """
+        return not self._base.use_mock and self._base._client is not None