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

attune/memory/short_term/streams.py

@@ -0,0 +1,249 @@
+"""Redis Streams for ordered event logs.
+
+This module provides stream operations for event sourcing:
+- Append: Add events to stream with auto-generated IDs
+- Read: Get events from specific position
+- Read new: Block and wait for new events
+
+Key Prefix: PREFIX_STREAM = "stream:"
+
+Use Cases:
+- Event sourcing
+- Activity logs
+- Message queues with persistence
+
+Classes:
+    StreamManager: Redis Streams operations
+
+Example:
+    >>> from attune.memory.short_term.streams import StreamManager
+    >>> from attune.memory.types import AgentCredentials, AccessTier
+    >>> streams = StreamManager(base_ops)
+    >>> creds = AgentCredentials("agent_1", AccessTier.CONTRIBUTOR)
+    >>> entry_id = streams.append("audit", {"action": "promoted"}, creds)
+    >>> entries = streams.read("audit", creds, count=50)
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+import structlog
+
+from attune.memory.types import (
+    AgentCredentials,
+)
+
+if TYPE_CHECKING:
+    from attune.memory.short_term.base import BaseOperations
+
+logger = structlog.get_logger(__name__)
+
+
+class StreamManager:
+    """Redis Streams operations for audit trails and event logs.
+
+    Provides ordered, persistent event logging using Redis Streams.
+    Features include automatic ID generation, max length trimming,
+    and blocking reads for real-time event processing.
+
+    The class manages its own mock stream storage for testing,
+    composed with BaseOperations for Redis client access.
+
+    Attributes:
+        PREFIX_STREAM: Key prefix for stream names
+
+    Example:
+        >>> streams = StreamManager(base_ops)
+        >>> creds = AgentCredentials("agent_1", AccessTier.CONTRIBUTOR)
+        >>> entry_id = streams.append("audit", {"action": "pattern_promoted"}, creds)
+        >>> entries = streams.read("audit", creds, count=100)
+        >>> for eid, data in entries:
+        ...     print(f"{eid}: {data}")
+    """
+
+    PREFIX_STREAM = "stream:"
+
+    def __init__(self, base: BaseOperations) -> None:
+        """Initialize stream manager.
+
+        Args:
+            base: BaseOperations instance for Redis client access
+        """
+        self._base = base
+        self._mock_streams: dict[str, list[tuple[str, dict]]] = {}
+
+    def append(
+        self,
+        stream_name: str,
+        data: dict,
+        credentials: AgentCredentials,
+        max_len: int = 10000,
+    ) -> str | None:
+        """Append an entry to a Redis Stream for audit trails.
+
+        Streams provide:
+        - Ordered, persistent event log
+        - Consumer groups for distributed processing
+        - Time-based retention
+
+        Args:
+            stream_name: Name of the stream
+            data: Event data to append
+            credentials: Agent credentials (must be CONTRIBUTOR+)
+            max_len: Maximum stream length (older entries trimmed)
+
+        Returns:
+            Entry ID if successful, None otherwise
+
+        Raises:
+            PermissionError: If credentials lack write access
+
+        Example:
+            >>> entry_id = streams.append(
+            ...     "audit",
+            ...     {"action": "pattern_promoted", "pattern_id": "xyz"},
+            ...     creds
+            ... )
+            '1704067200000-0'
+        """
+        if not credentials.can_stage():
+            raise PermissionError(
+                f"Agent {credentials.agent_id} cannot write to stream. "
+                "Requires CONTRIBUTOR tier or higher.",
+            )
+
+        start_time = time.perf_counter()
+        full_stream = f"{self.PREFIX_STREAM}{stream_name}"
+
+        entry = {
+            "agent_id": credentials.agent_id,
+            "timestamp": datetime.now().isoformat(),
+            **{
+                str(k): json.dumps(v) if isinstance(v, dict | list) else str(v)
+                for k, v in data.items()
+            },
+        }
+
+        # Handle mock mode
+        if self._base.use_mock:
+            if full_stream not in self._mock_streams:
+                self._mock_streams[full_stream] = []
+            entry_id = f"{int(datetime.now().timestamp() * 1000)}-0"
+            self._mock_streams[full_stream].append((entry_id, entry))
+            # Trim to max_len
+            if len(self._mock_streams[full_stream]) > max_len:
+                self._mock_streams[full_stream] = self._mock_streams[full_stream][
+                    -max_len:
+                ]
+            latency_ms = (time.perf_counter() - start_time) * 1000
+            self._base._metrics.record_operation("stream_append", latency_ms)
+            return entry_id
+
+        # Handle real Redis client
+        if self._base._client is None:
+            return None
+
+        entry_id = self._base._client.xadd(full_stream, entry, maxlen=max_len)
+        latency_ms = (time.perf_counter() - start_time) * 1000
+        self._base._metrics.record_operation("stream_append", latency_ms)
+
+        return str(entry_id) if entry_id else None
+
+    def read(
+        self,
+        stream_name: str,
+        credentials: AgentCredentials,
+        start_id: str = "0",
+        count: int = 100,
+    ) -> list[tuple[str, dict]]:
+        """Read entries from a Redis Stream.
+
+        Args:
+            stream_name: Name of the stream
+            credentials: Agent credentials
+            start_id: Start reading from this ID ("0" = beginning)
+            count: Maximum entries to read
+
+        Returns:
+            List of (entry_id, data) tuples
+
+        Example:
+            >>> entries = streams.read("audit", creds, count=50)
+            >>> for entry_id, data in entries:
+            ...     print(f"{entry_id}: {data}")
+        """
+        full_stream = f"{self.PREFIX_STREAM}{stream_name}"
+
+        # Handle mock mode
+        if self._base.use_mock:
+            if full_stream not in self._mock_streams:
+                return []
+            entries = self._mock_streams[full_stream]
+            # Filter by start_id (simple comparison)
+            filtered = [(eid, data) for eid, data in entries if eid > start_id]
+            return filtered[:count]
+
+        # Handle real Redis client
+        if self._base._client is None:
+            return []
+
+        result = self._base._client.xrange(full_stream, min=start_id, count=count)
+        return [
+            (str(entry_id), {str(k): v for k, v in data.items()})
+            for entry_id, data in result
+        ]
+
+    def read_new(
+        self,
+        stream_name: str,
+        credentials: AgentCredentials,
+        block_ms: int = 0,
+        count: int = 100,
+    ) -> list[tuple[str, dict]]:
+        """Read only new entries from a stream (blocking read).
+
+        Blocks and waits for new entries to arrive. Useful for
+        real-time event processing.
+
+        Args:
+            stream_name: Name of the stream
+            credentials: Agent credentials
+            block_ms: Milliseconds to block waiting (0 = no block)
+            count: Maximum entries to read
+
+        Returns:
+            List of (entry_id, data) tuples
+
+        Example:
+            >>> # Wait up to 5 seconds for new entries
+            >>> entries = streams.read_new("audit", creds, block_ms=5000)
+        """
+        full_stream = f"{self.PREFIX_STREAM}{stream_name}"
+
+        # Handle mock mode - doesn't support blocking reads
+        if self._base.use_mock:
+            return []
+
+        # Handle real Redis client
+        if self._base._client is None:
+            return []
+
+        result = self._base._client.xread(
+            {full_stream: "$"}, block=block_ms, count=count
+        )
+        if not result:
+            return []
+
+        # Result format: [(stream_name, [(entry_id, data), ...])]
+        entries = []
+        for _stream, stream_entries in result:
+            for entry_id, data in stream_entries:
+                entries.append((str(entry_id), {str(k): v for k, v in data.items()}))
+        return entries

attune/memory/short_term/timelines.py

@@ -0,0 +1,234 @@
+"""Time-window queries using Redis sorted sets.
+
+This module provides timeline operations for time-series data:
+- Add: Insert event with timestamp score
+- Query: Get events in time window
+- Count: Count events in time window
+
+Key Prefix: PREFIX_TIMELINE = "timeline:"
+
+Use Cases:
+- Activity timelines
+- Time-based analytics
+- Rate limiting windows
+
+Classes:
+    TimelineManager: Redis sorted set operations for timelines
+
+Example:
+    >>> from attune.memory.short_term.timelines import TimelineManager
+    >>> from attune.memory.types import AgentCredentials, AccessTier, TimeWindowQuery
+    >>> timelines = TimelineManager(base_ops)
+    >>> creds = AgentCredentials("agent_1", AccessTier.CONTRIBUTOR)
+    >>> timelines.add("events", "evt_1", {"action": "login"}, creds)
+    >>> events = timelines.query("events", creds, TimeWindowQuery(limit=50))
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+import structlog
+
+from attune.memory.types import (
+    AgentCredentials,
+    TimeWindowQuery,
+)
+
+if TYPE_CHECKING:
+    from attune.memory.short_term.base import BaseOperations
+
+logger = structlog.get_logger(__name__)
+
+
+class TimelineManager:
+    """Redis sorted set operations for timeline queries.
+
+    Provides time-series event storage using Redis sorted sets,
+    where events are scored by timestamp for efficient time-window queries.
+
+    The class manages its own mock sorted set storage for testing,
+    composed with BaseOperations for Redis client access.
+
+    Attributes:
+        PREFIX_TIMELINE: Key prefix for timeline names
+
+    Example:
+        >>> timelines = TimelineManager(base_ops)
+        >>> creds = AgentCredentials("agent_1", AccessTier.CONTRIBUTOR)
+        >>> timelines.add("agent_events", "evt_123", {"action": "login"}, creds)
+        >>> query = TimeWindowQuery(limit=100)
+        >>> events = timelines.query("agent_events", creds, query)
+    """
+
+    PREFIX_TIMELINE = "timeline:"
+
+    def __init__(self, base: BaseOperations) -> None:
+        """Initialize timeline manager.
+
+        Args:
+            base: BaseOperations instance for Redis client access
+        """
+        self._base = base
+        self._mock_sorted_sets: dict[str, list[tuple[float, str]]] = {}
+
+    def add(
+        self,
+        timeline_name: str,
+        event_id: str,
+        data: dict,
+        credentials: AgentCredentials,
+        timestamp: datetime | None = None,
+    ) -> bool:
+        """Add an event to a timeline (sorted set by timestamp).
+
+        Args:
+            timeline_name: Name of the timeline
+            event_id: Unique event identifier
+            data: Event data
+            credentials: Agent credentials (must be CONTRIBUTOR+)
+            timestamp: Event timestamp (defaults to now)
+
+        Returns:
+            True if added successfully
+
+        Raises:
+            PermissionError: If credentials lack write access
+
+        Example:
+            >>> timelines.add(
+            ...     "audit_log",
+            ...     "evt_001",
+            ...     {"action": "pattern_promoted"},
+            ...     creds
+            ... )
+            True
+        """
+        if not credentials.can_stage():
+            raise PermissionError(
+                f"Agent {credentials.agent_id} cannot write to timeline. "
+                "Requires CONTRIBUTOR tier or higher.",
+            )
+
+        full_timeline = f"{self.PREFIX_TIMELINE}{timeline_name}"
+        ts = timestamp or datetime.now()
+        score = ts.timestamp()
+
+        payload = json.dumps(
+            {
+                "event_id": event_id,
+                "timestamp": ts.isoformat(),
+                "agent_id": credentials.agent_id,
+                "data": data,
+            },
+        )
+
+        # Handle mock mode
+        if self._base.use_mock:
+            if full_timeline not in self._mock_sorted_sets:
+                self._mock_sorted_sets[full_timeline] = []
+            self._mock_sorted_sets[full_timeline].append((score, payload))
+            self._mock_sorted_sets[full_timeline].sort(key=lambda x: x[0])
+            return True
+
+        # Handle real Redis client
+        if self._base._client is None:
+            return False
+
+        self._base._client.zadd(full_timeline, {payload: score})
+        return True
+
+    def query(
+        self,
+        timeline_name: str,
+        credentials: AgentCredentials,
+        query: TimeWindowQuery | None = None,
+    ) -> list[dict]:
+        """Query events from a timeline within a time window.
+
+        Args:
+            timeline_name: Name of the timeline
+            credentials: Agent credentials
+            query: Time window query parameters
+
+        Returns:
+            List of events in the time window
+
+        Example:
+            >>> from datetime import datetime, timedelta
+            >>> query = TimeWindowQuery(
+            ...     start_time=datetime.now() - timedelta(hours=1),
+            ...     end_time=datetime.now(),
+            ...     limit=50
+            ... )
+            >>> events = timelines.query("agent_events", creds, query)
+        """
+        full_timeline = f"{self.PREFIX_TIMELINE}{timeline_name}"
+        q = query or TimeWindowQuery()
+
+        # Handle mock mode
+        if self._base.use_mock:
+            if full_timeline not in self._mock_sorted_sets:
+                return []
+            entries = self._mock_sorted_sets[full_timeline]
+            filtered = [
+                json.loads(payload)
+                for score, payload in entries
+                if q.start_score <= score <= q.end_score
+            ]
+            return filtered[q.offset : q.offset + q.limit]
+
+        # Handle real Redis client
+        if self._base._client is None:
+            return []
+
+        results = self._base._client.zrangebyscore(
+            full_timeline,
+            min=q.start_score,
+            max=q.end_score,
+            start=q.offset,
+            num=q.limit,
+        )
+
+        return [json.loads(r) for r in results]
+
+    def count(
+        self,
+        timeline_name: str,
+        credentials: AgentCredentials,
+        query: TimeWindowQuery | None = None,
+    ) -> int:
+        """Count events in a timeline within a time window.
+
+        Args:
+            timeline_name: Name of the timeline
+            credentials: Agent credentials
+            query: Time window query parameters
+
+        Returns:
+            Number of events in the time window
+
+        Example:
+            >>> count = timelines.count("agent_events", creds)
+            >>> print(f"Total events: {count}")
+        """
+        full_timeline = f"{self.PREFIX_TIMELINE}{timeline_name}"
+        q = query or TimeWindowQuery()
+
+        # Handle mock mode
+        if self._base.use_mock:
+            if full_timeline not in self._mock_sorted_sets:
+                return 0
+            entries = self._mock_sorted_sets[full_timeline]
+            return len([1 for score, _ in entries if q.start_score <= score <= q.end_score])
+
+        # Handle real Redis client
+        if self._base._client is None:
+            return 0
+
+        return int(self._base._client.zcount(full_timeline, q.start_score, q.end_score))

attune/memory/short_term/transactions.py

@@ -0,0 +1,186 @@
+"""Atomic operations using Redis transactions.
+
+This module provides atomic multi-step operations using MULTI/EXEC:
+- Pattern promotion with rollback on failure
+- Consistent state updates across multiple keys
+
+Use Cases:
+- Pattern lifecycle (stage -> promote/reject)
+- Session management with consistency guarantees
+- Any multi-key operation requiring atomicity
+
+Classes:
+    TransactionManager: Atomic operations using Redis transactions
+
+Example:
+    >>> from attune.memory.short_term.transactions import TransactionManager
+    >>> from attune.memory.types import AgentCredentials, AccessTier
+    >>> transactions = TransactionManager(base_ops, caching_ops)
+    >>> creds = AgentCredentials("agent_1", AccessTier.VALIDATOR)
+    >>> success, pattern, msg = transactions.atomic_promote_pattern("pat_123", creds)
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+import redis
+import structlog
+
+from attune.memory.types import (
+    AgentCredentials,
+    StagedPattern,
+)
+
+if TYPE_CHECKING:
+    from attune.memory.short_term.base import BaseOperations
+    from attune.memory.short_term.caching import CachingOperations
+
+logger = structlog.get_logger(__name__)
+
+
+class TransactionManager:
+    """Atomic operations using Redis transactions.
+
+    Provides atomic multi-step operations using Redis WATCH/MULTI/EXEC
+    for operations that need consistency guarantees across multiple keys.
+
+    The class requires access to both BaseOperations and CachingOperations
+    to coordinate atomic updates with local cache invalidation.
+
+    Attributes:
+        PREFIX_STAGED: Key prefix for staged patterns namespace
+
+    Example:
+        >>> transactions = TransactionManager(base_ops, caching_ops)
+        >>> creds = AgentCredentials("agent_1", AccessTier.VALIDATOR)
+        >>> success, pattern, msg = transactions.atomic_promote_pattern(
+        ...     "pat_123", creds, min_confidence=0.7
+        ... )
+        >>> if success:
+        ...     library.add(pattern)
+    """
+
+    PREFIX_STAGED = "empathy:staged:"
+
+    def __init__(self, base: BaseOperations, caching: CachingOperations) -> None:
+        """Initialize transaction manager.
+
+        Args:
+            base: BaseOperations instance for Redis client access
+            caching: CachingOperations instance for cache invalidation
+        """
+        self._base = base
+        self._caching = caching
+
+    def atomic_promote_pattern(
+        self,
+        pattern_id: str,
+        credentials: AgentCredentials,
+        min_confidence: float = 0.0,
+    ) -> tuple[bool, StagedPattern | None, str]:
+        """Atomically promote a pattern with validation.
+
+        Uses Redis transaction (WATCH/MULTI/EXEC) to ensure:
+        - Pattern exists and meets confidence threshold
+        - Pattern is removed from staging atomically
+        - No race conditions with concurrent operations
+
+        Args:
+            pattern_id: Pattern to promote
+            credentials: Must be VALIDATOR or higher
+            min_confidence: Minimum confidence threshold
+
+        Returns:
+            Tuple of (success, pattern, message)
+
+        Raises:
+            ValueError: If pattern_id is empty or min_confidence out of range
+
+        Example:
+            >>> success, pattern, msg = transactions.atomic_promote_pattern(
+            ...     "pat_123", creds, min_confidence=0.7
+            ... )
+            >>> if success:
+            ...     library.add(pattern)
+        """
+        # Pattern 1: String ID validation
+        if not pattern_id or not pattern_id.strip():
+            raise ValueError(f"pattern_id cannot be empty. Got: {pattern_id!r}")
+
+        # Pattern 4: Range validation
+        if not 0.0 <= min_confidence <= 1.0:
+            raise ValueError(
+                f"min_confidence must be between 0.0 and 1.0, got {min_confidence}"
+            )
+
+        if not credentials.can_validate():
+            return False, None, "Requires VALIDATOR tier or higher"
+
+        key = f"{self.PREFIX_STAGED}{pattern_id}"
+
+        # Handle mock mode
+        if self._base.use_mock:
+            if key not in self._base._mock_storage:
+                return False, None, "Pattern not found"
+            value, expires = self._base._mock_storage[key]
+            if expires and datetime.now().timestamp() >= expires:
+                return False, None, "Pattern expired"
+            pattern = StagedPattern.from_dict(json.loads(str(value)))
+            if pattern.confidence < min_confidence:
+                return (
+                    False,
+                    None,
+                    f"Confidence {pattern.confidence} below threshold {min_confidence}",
+                )
+            del self._base._mock_storage[key]
+            # Also invalidate local cache
+            self._caching.invalidate(key)
+            return True, pattern, "Pattern promoted successfully"
+
+        # Handle real Redis client
+        if self._base._client is None:
+            return False, None, "Redis not connected"
+
+        # Use WATCH for optimistic locking
+        try:
+            self._base._client.watch(key)
+            raw = self._base._client.get(key)
+
+            if raw is None:
+                self._base._client.unwatch()
+                return False, None, "Pattern not found"
+
+            pattern = StagedPattern.from_dict(json.loads(raw))
+
+            if pattern.confidence < min_confidence:
+                self._base._client.unwatch()
+                return (
+                    False,
+                    None,
+                    f"Confidence {pattern.confidence} below threshold {min_confidence}",
+                )
+
+            # Execute atomic delete
+            pipe = self._base._client.pipeline(True)
+            pipe.delete(key)
+            pipe.execute()
+
+            # Also invalidate local cache
+            self._caching.invalidate(key)
+
+            return True, pattern, "Pattern promoted successfully"
+
+        except redis.WatchError:
+            return False, None, "Pattern was modified by another process"
+        finally:
+            try:
+                self._base._client.unwatch()
+            except Exception:  # noqa: BLE001
+                # INTENTIONAL: Best effort cleanup - don't fail on unwatch errors
+                pass