alma-memory 0.4.0__py3-none-any.whl → 0.5.0__py3-none-any.whl

alma/events/storage_mixin.py

@@ -0,0 +1,246 @@
+"""
+ALMA Event-Aware Storage Mixin.
+
+Provides event emission capabilities for storage backends.
+This is a mixin class that can be used by any storage implementation
+to emit events when memory operations occur.
+"""
+
+import logging
+from dataclasses import asdict
+from typing import Any, Dict, Optional
+
+from alma.events.emitter import EventEmitter, get_emitter
+from alma.events.types import MemoryEventType, create_memory_event
+
+logger = logging.getLogger(__name__)
+
+
+class EventAwareStorageMixin:
+    """
+    Mixin that adds event emission to storage backends.
+
+    This mixin provides helper methods to emit events for various
+    storage operations. Events are only emitted if there are subscribers,
+    making the overhead negligible when events are not used.
+
+    Usage:
+        class MyStorage(StorageBackend, EventAwareStorageMixin):
+            def save_heuristic(self, heuristic):
+                result_id = super().save_heuristic(heuristic)
+                self._emit_memory_event(
+                    event_type=MemoryEventType.CREATED,
+                    agent=heuristic.agent,
+                    project_id=heuristic.project_id,
+                    memory_type="heuristics",
+                    memory_id=result_id,
+                    payload=self._heuristic_to_dict(heuristic),
+                )
+                return result_id
+    """
+
+    _events_enabled: bool = True
+    _custom_emitter: Optional[EventEmitter] = None
+
+    def enable_events(self) -> None:
+        """Enable event emission for this storage instance."""
+        self._events_enabled = True
+
+    def disable_events(self) -> None:
+        """Disable event emission for this storage instance."""
+        self._events_enabled = False
+
+    def set_emitter(self, emitter: EventEmitter) -> None:
+        """
+        Set a custom event emitter for this storage instance.
+
+        Args:
+            emitter: The event emitter to use
+        """
+        self._custom_emitter = emitter
+
+    def _get_emitter(self) -> EventEmitter:
+        """Get the event emitter to use."""
+        if self._custom_emitter is not None:
+            return self._custom_emitter
+        return get_emitter()
+
+    def _should_emit(self, event_type: MemoryEventType) -> bool:
+        """
+        Check if events should be emitted.
+
+        Returns False if:
+        - Events are disabled for this storage instance
+        - There are no subscribers for this event type
+
+        This optimization ensures event creation overhead is avoided
+        when no one is listening.
+
+        Args:
+            event_type: The type of event being considered
+
+        Returns:
+            True if an event should be emitted
+        """
+        if not self._events_enabled:
+            return False
+
+        emitter = self._get_emitter()
+        return emitter.has_subscribers(event_type)
+
+    def _emit_memory_event(
+        self,
+        event_type: MemoryEventType,
+        agent: str,
+        project_id: str,
+        memory_type: str,
+        memory_id: str,
+        payload: Dict[str, Any],
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """
+        Emit a memory event if there are subscribers.
+
+        This is a convenience method that checks for subscribers before
+        creating and emitting the event.
+
+        Args:
+            event_type: Type of event
+            agent: Agent name
+            project_id: Project identifier
+            memory_type: Type of memory
+            memory_id: Memory identifier
+            payload: Event-specific data
+            metadata: Optional additional context
+        """
+        if not self._should_emit(event_type):
+            return
+
+        event = create_memory_event(
+            event_type=event_type,
+            agent=agent,
+            project_id=project_id,
+            memory_type=memory_type,
+            memory_id=memory_id,
+            payload=payload,
+            metadata=metadata,
+        )
+
+        emitter = self._get_emitter()
+        emitter.emit(event)
+
+        logger.debug(f"Emitted {event_type.value} for {memory_type}/{memory_id}")
+
+    def _emit_created_event(
+        self,
+        agent: str,
+        project_id: str,
+        memory_type: str,
+        memory_id: str,
+        payload: Dict[str, Any],
+    ) -> None:
+        """Emit a CREATED event."""
+        self._emit_memory_event(
+            event_type=MemoryEventType.CREATED,
+            agent=agent,
+            project_id=project_id,
+            memory_type=memory_type,
+            memory_id=memory_id,
+            payload=payload,
+        )
+
+    def _emit_updated_event(
+        self,
+        agent: str,
+        project_id: str,
+        memory_type: str,
+        memory_id: str,
+        payload: Dict[str, Any],
+    ) -> None:
+        """Emit an UPDATED event."""
+        self._emit_memory_event(
+            event_type=MemoryEventType.UPDATED,
+            agent=agent,
+            project_id=project_id,
+            memory_type=memory_type,
+            memory_id=memory_id,
+            payload=payload,
+        )
+
+    def _emit_deleted_event(
+        self,
+        agent: str,
+        project_id: str,
+        memory_type: str,
+        memory_id: str,
+    ) -> None:
+        """Emit a DELETED event."""
+        self._emit_memory_event(
+            event_type=MemoryEventType.DELETED,
+            agent=agent,
+            project_id=project_id,
+            memory_type=memory_type,
+            memory_id=memory_id,
+            payload={"deleted_id": memory_id},
+        )
+
+
+def emit_on_save(
+    memory_type: str, event_type: MemoryEventType = MemoryEventType.CREATED
+):
+    """
+    Decorator to emit events when save methods are called.
+
+    This decorator can be used on storage methods that save memories.
+    It will emit an event after the save completes successfully.
+
+    Args:
+        memory_type: The type of memory being saved (e.g., "heuristics")
+        event_type: The event type to emit (default: CREATED)
+
+    Example:
+        @emit_on_save("heuristics")
+        def save_heuristic(self, heuristic: Heuristic) -> str:
+            # Original implementation
+            ...
+    """
+
+    def decorator(func):
+        def wrapper(self, memory_item):
+            # Call the original method
+            result_id = func(self, memory_item)
+
+            # Emit event if storage supports events
+            if hasattr(self, "_emit_memory_event") and hasattr(self, "_should_emit"):
+                if self._should_emit(event_type):
+                    # Extract common fields
+                    agent = getattr(memory_item, "agent", "unknown")
+                    project_id = getattr(memory_item, "project_id", "unknown")
+
+                    # Convert to dict, handling dataclasses
+                    try:
+                        if hasattr(memory_item, "__dataclass_fields__"):
+                            payload = {
+                                k: v
+                                for k, v in asdict(memory_item).items()
+                                if k != "embedding"  # Exclude large embedding vectors
+                            }
+                        else:
+                            payload = {"id": result_id}
+                    except Exception:
+                        payload = {"id": result_id}
+
+                    self._emit_memory_event(
+                        event_type=event_type,
+                        agent=agent,
+                        project_id=project_id,
+                        memory_type=memory_type,
+                        memory_id=result_id,
+                        payload=payload,
+                    )
+
+            return result_id
+
+        return wrapper
+
+    return decorator

alma/events/types.py

@@ -0,0 +1,126 @@
+"""
+ALMA Event Types.
+
+Defines event types and the MemoryEvent dataclass for the event system.
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, Optional
+
+
+class MemoryEventType(Enum):
+    """Types of events that can be emitted by the memory system."""
+
+    # Core memory operations
+    CREATED = "memory.created"
+    UPDATED = "memory.updated"
+    DELETED = "memory.deleted"
+    CONSOLIDATED = "memory.consolidated"
+
+    # Learning-specific events
+    HEURISTIC_FORMED = "heuristic.formed"
+    ANTIPATTERN_DETECTED = "antipattern.detected"
+    PREFERENCE_ADDED = "preference.added"
+    KNOWLEDGE_ADDED = "knowledge.added"
+
+    # Confidence events
+    CONFIDENCE_UPDATED = "confidence.updated"
+    CONFIDENCE_DECAYED = "confidence.decayed"
+
+
+@dataclass
+class MemoryEvent:
+    """
+    Represents an event in the memory system.
+
+    Events are emitted when memory operations occur, allowing external
+    systems to react to changes through callbacks or webhooks.
+
+    Attributes:
+        event_type: The type of event that occurred
+        agent: Name of the agent associated with the event
+        project_id: Project identifier
+        memory_type: Type of memory (heuristics, outcomes, etc.)
+        memory_id: Unique identifier of the affected memory
+        timestamp: When the event occurred
+        payload: Event-specific data (e.g., the created memory)
+        metadata: Optional additional context
+    """
+
+    event_type: MemoryEventType
+    agent: str
+    project_id: str
+    memory_type: (
+        str  # heuristics, outcomes, preferences, domain_knowledge, anti_patterns
+    )
+    memory_id: str
+    timestamp: datetime
+    payload: Dict[str, Any]
+    metadata: Optional[Dict[str, Any]] = field(default_factory=dict)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert event to dictionary for serialization."""
+        return {
+            "event_type": self.event_type.value,
+            "agent": self.agent,
+            "project_id": self.project_id,
+            "memory_type": self.memory_type,
+            "memory_id": self.memory_id,
+            "timestamp": self.timestamp.isoformat(),
+            "payload": self.payload,
+            "metadata": self.metadata or {},
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "MemoryEvent":
+        """Create event from dictionary."""
+        return cls(
+            event_type=MemoryEventType(data["event_type"]),
+            agent=data["agent"],
+            project_id=data["project_id"],
+            memory_type=data["memory_type"],
+            memory_id=data["memory_id"],
+            timestamp=datetime.fromisoformat(data["timestamp"]),
+            payload=data["payload"],
+            metadata=data.get("metadata"),
+        )
+
+
+def create_memory_event(
+    event_type: MemoryEventType,
+    agent: str,
+    project_id: str,
+    memory_type: str,
+    memory_id: str,
+    payload: Dict[str, Any],
+    metadata: Optional[Dict[str, Any]] = None,
+    *,
+    default_metadata: bool = True,
+) -> MemoryEvent:
+    """
+    Factory function to create a MemoryEvent with current timestamp.
+
+    Args:
+        event_type: Type of event
+        agent: Agent name
+        project_id: Project identifier
+        memory_type: Type of memory
+        memory_id: Memory identifier
+        payload: Event-specific data
+        metadata: Optional additional context
+
+    Returns:
+        A new MemoryEvent instance
+    """
+    return MemoryEvent(
+        event_type=event_type,
+        agent=agent,
+        project_id=project_id,
+        memory_type=memory_type,
+        memory_id=memory_id,
+        timestamp=datetime.now(timezone.utc),
+        payload=payload,
+        metadata=metadata if metadata is not None else {},
+    )