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

alma/events/emitter.py

@@ -0,0 +1,284 @@
+"""
+ALMA Event Emitter.
+
+Provides a pub/sub mechanism for memory events, allowing components
+and external systems to subscribe to and receive notifications about
+memory changes.
+"""
+
+import asyncio
+import logging
+from concurrent.futures import ThreadPoolExecutor
+from typing import Awaitable, Callable, Dict, List, Optional, Union
+
+from alma.events.types import MemoryEvent, MemoryEventType
+
+logger = logging.getLogger(__name__)
+
+# Type aliases for callbacks
+SyncCallback = Callable[[MemoryEvent], None]
+AsyncCallback = Callable[[MemoryEvent], Awaitable[None]]
+EventCallback = Union[SyncCallback, AsyncCallback]
+
+
+class EventEmitter:
+    """
+    Event emitter for memory system events.
+
+    Supports both synchronous and asynchronous callbacks, with options
+    to subscribe to specific event types or all events.
+
+    The emitter is designed to be non-blocking - callbacks are executed
+    in a way that doesn't slow down the main storage operations.
+
+    Example:
+        ```python
+        emitter = EventEmitter()
+
+        def on_created(event: MemoryEvent):
+            print(f"Memory created: {event.memory_id}")
+
+        emitter.subscribe(MemoryEventType.CREATED, on_created)
+        emitter.emit(event)
+        ```
+    """
+
+    def __init__(self, max_workers: int = 4):
+        """
+        Initialize the event emitter.
+
+        Args:
+            max_workers: Maximum number of worker threads for async callback execution
+        """
+        self._subscribers: Dict[MemoryEventType, List[EventCallback]] = {}
+        self._global_subscribers: List[EventCallback] = []
+        self._executor = ThreadPoolExecutor(max_workers=max_workers)
+        self._enabled = True
+
+    def subscribe(
+        self,
+        event_type: MemoryEventType,
+        callback: EventCallback,
+    ) -> None:
+        """
+        Subscribe to a specific event type.
+
+        Args:
+            event_type: The type of event to subscribe to
+            callback: Function to call when event occurs (sync or async)
+        """
+        if event_type not in self._subscribers:
+            self._subscribers[event_type] = []
+
+        if callback not in self._subscribers[event_type]:
+            self._subscribers[event_type].append(callback)
+            callback_name = getattr(callback, "__name__", repr(callback))
+            logger.debug(f"Subscribed to {event_type.value}: {callback_name}")
+
+    def subscribe_all(self, callback: EventCallback) -> None:
+        """
+        Subscribe to all events.
+
+        Args:
+            callback: Function to call for any event
+        """
+        if callback not in self._global_subscribers:
+            self._global_subscribers.append(callback)
+            callback_name = getattr(callback, "__name__", repr(callback))
+            logger.debug(f"Subscribed to all events: {callback_name}")
+
+    def unsubscribe(
+        self,
+        event_type: MemoryEventType,
+        callback: EventCallback,
+    ) -> bool:
+        """
+        Unsubscribe from a specific event type.
+
+        Args:
+            event_type: The event type to unsubscribe from
+            callback: The callback to remove
+
+        Returns:
+            True if callback was removed, False if not found
+        """
+        if event_type in self._subscribers:
+            try:
+                self._subscribers[event_type].remove(callback)
+                callback_name = getattr(callback, "__name__", repr(callback))
+                logger.debug(f"Unsubscribed from {event_type.value}: {callback_name}")
+                return True
+            except ValueError:
+                pass
+        return False
+
+    def unsubscribe_all(self, callback: EventCallback) -> bool:
+        """
+        Unsubscribe a callback from all events.
+
+        Args:
+            callback: The callback to remove
+
+        Returns:
+            True if callback was removed, False if not found
+        """
+        try:
+            self._global_subscribers.remove(callback)
+            callback_name = getattr(callback, "__name__", repr(callback))
+            logger.debug(f"Unsubscribed from all events: {callback_name}")
+            return True
+        except ValueError:
+            return False
+
+    def has_subscribers(self, event_type: Optional[MemoryEventType] = None) -> bool:
+        """
+        Check if there are any subscribers.
+
+        Args:
+            event_type: Optional specific event type to check
+
+        Returns:
+            True if there are subscribers
+        """
+        if event_type is None:
+            return bool(self._global_subscribers) or any(
+                bool(subs) for subs in self._subscribers.values()
+            )
+        return bool(self._subscribers.get(event_type)) or bool(self._global_subscribers)
+
+    def emit(self, event: MemoryEvent) -> None:
+        """
+        Emit an event to all matching subscribers (non-blocking).
+
+        Callbacks are executed in a thread pool to avoid blocking
+        the main thread. Any exceptions in callbacks are logged
+        but do not propagate.
+
+        Args:
+            event: The event to emit
+        """
+        if not self._enabled:
+            return
+
+        callbacks = self._get_callbacks(event.event_type)
+        if not callbacks:
+            return
+
+        # Execute callbacks in thread pool (non-blocking)
+        for callback in callbacks:
+            self._executor.submit(self._safe_call, callback, event)
+
+    async def emit_async(self, event: MemoryEvent) -> None:
+        """
+        Emit an event to all matching subscribers asynchronously.
+
+        For async callbacks, awaits them directly. For sync callbacks,
+        runs them in the executor.
+
+        Args:
+            event: The event to emit
+        """
+        if not self._enabled:
+            return
+
+        callbacks = self._get_callbacks(event.event_type)
+        if not callbacks:
+            return
+
+        tasks = []
+        for callback in callbacks:
+            if asyncio.iscoroutinefunction(callback):
+                tasks.append(self._safe_call_async(callback, event))
+            else:
+                # Run sync callbacks in executor
+                loop = asyncio.get_event_loop()
+                tasks.append(
+                    loop.run_in_executor(
+                        self._executor,
+                        self._safe_call,
+                        callback,
+                        event,
+                    )
+                )
+
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+
+    def _get_callbacks(self, event_type: MemoryEventType) -> List[EventCallback]:
+        """Get all callbacks for an event type."""
+        callbacks = list(self._global_subscribers)
+        callbacks.extend(self._subscribers.get(event_type, []))
+        return callbacks
+
+    def _safe_call(self, callback: SyncCallback, event: MemoryEvent) -> None:
+        """Safely call a sync callback, catching exceptions."""
+        try:
+            callback(event)
+        except Exception as e:
+            callback_name = getattr(callback, "__name__", repr(callback))
+            logger.error(
+                f"Error in event callback {callback_name}: {e}",
+                exc_info=True,
+            )
+
+    async def _safe_call_async(
+        self,
+        callback: AsyncCallback,
+        event: MemoryEvent,
+    ) -> None:
+        """Safely call an async callback, catching exceptions."""
+        try:
+            await callback(event)
+        except Exception as e:
+            callback_name = getattr(callback, "__name__", repr(callback))
+            logger.error(
+                f"Error in async event callback {callback_name}: {e}",
+                exc_info=True,
+            )
+
+    def enable(self) -> None:
+        """Enable event emission."""
+        self._enabled = True
+
+    def disable(self) -> None:
+        """Disable event emission (events will be silently dropped)."""
+        self._enabled = False
+
+    def clear(self) -> None:
+        """Remove all subscribers."""
+        self._subscribers.clear()
+        self._global_subscribers.clear()
+
+    def shutdown(self) -> None:
+        """Shutdown the executor and clear subscribers."""
+        self.clear()
+        self._executor.shutdown(wait=False)
+
+
+# Global emitter instance (singleton pattern)
+_emitter: Optional[EventEmitter] = None
+
+
+def get_emitter() -> EventEmitter:
+    """
+    Get the global event emitter instance.
+
+    Returns:
+        The singleton EventEmitter instance
+    """
+    global _emitter
+    if _emitter is None:
+        _emitter = EventEmitter()
+    return _emitter
+
+
+def reset_emitter() -> None:
+    """
+    Reset the global emitter (mainly for testing).
+
+    Creates a fresh emitter instance, clearing all subscriptions.
+    """
+    global _emitter
+    if _emitter is not None:
+        _emitter.shutdown()
+    _emitter = EventEmitter()

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 {},
+    )