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

alma/consolidation/prompts.py

@@ -0,0 +1,84 @@
+"""
+ALMA Consolidation Prompts.
+
+LLM prompts for intelligently merging similar memories.
+"""
+
+# Prompt for merging multiple similar heuristics into one
+MERGE_HEURISTICS_PROMPT = """You are a memory consolidation agent. Given these similar heuristics that have been identified as near-duplicates based on semantic similarity, create a single consolidated heuristic that captures the essence of all.
+
+Similar Heuristics:
+{heuristics}
+
+Create a consolidated heuristic that:
+1. Generalizes the condition to cover all cases
+2. Combines the strategies into a comprehensive approach
+3. Preserves any unique insights from individual heuristics
+
+Output a JSON object with exactly these fields:
+{{
+    "condition": "The generalized condition that triggers this heuristic",
+    "strategy": "The merged strategy combining all approaches",
+    "confidence": <average confidence as a float between 0 and 1>
+}}
+
+Only output the JSON object, no other text."""
+
+# Prompt for merging similar domain knowledge
+MERGE_DOMAIN_KNOWLEDGE_PROMPT = """You are a memory consolidation agent. Given these similar domain knowledge facts that have been identified as near-duplicates, create a single consolidated fact that captures all the information.
+
+Similar Domain Knowledge:
+{knowledge_items}
+
+Create a consolidated fact that:
+1. Combines all unique information
+2. Removes redundancy
+3. Maintains accuracy
+
+Output a JSON object with exactly these fields:
+{{
+    "fact": "The consolidated fact combining all information",
+    "confidence": <average confidence as a float between 0 and 1>
+}}
+
+Only output the JSON object, no other text."""
+
+# Prompt for merging anti-patterns
+MERGE_ANTI_PATTERNS_PROMPT = """You are a memory consolidation agent. Given these similar anti-patterns that have been identified as near-duplicates, create a single consolidated anti-pattern.
+
+Similar Anti-Patterns:
+{anti_patterns}
+
+Create a consolidated anti-pattern that:
+1. Generalizes the pattern description
+2. Combines all reasons why it's bad
+3. Provides a comprehensive alternative
+
+Output a JSON object with exactly these fields:
+{{
+    "pattern": "The generalized pattern to avoid",
+    "why_bad": "Combined explanation of why this pattern is problematic",
+    "better_alternative": "The recommended alternative approach"
+}}
+
+Only output the JSON object, no other text."""
+
+# Prompt for merging outcomes (typically used for summarization rather than true merge)
+MERGE_OUTCOMES_PROMPT = """You are a memory consolidation agent. Given these similar task outcomes, create a summary that captures the key learnings.
+
+Similar Outcomes:
+{outcomes}
+
+Create a summary that:
+1. Identifies the common task type
+2. Notes the overall success/failure pattern
+3. Highlights effective strategies
+
+Output a JSON object with exactly these fields:
+{{
+    "task_type": "The common task type",
+    "summary": "Summary of the outcomes and learnings",
+    "recommended_strategy": "The most effective strategy based on the outcomes"
+}}
+
+Only output the JSON object, no other text."""

alma/core.py

@@ -2,24 +2,19 @@
 ALMA Core - Main interface for the Agent Learning Memory Architecture.
 """
 
-from typing import Optional, Dict, Any, List
-from pathlib import Path
-import yaml
 import logging
+from typing import Any, Dict, Optional
 
+from alma.config.loader import ConfigLoader
+from alma.learning.protocols import LearningProtocol
+from alma.retrieval.engine import RetrievalEngine
+from alma.storage.base import StorageBackend
 from alma.types import (
-    MemorySlice,
+    DomainKnowledge,
     MemoryScope,
-    Heuristic,
-    Outcome,
+    MemorySlice,
     UserPreference,
-    DomainKnowledge,
-    AntiPattern,
 )
-from alma.storage.base import StorageBackend
-from alma.retrieval.engine import RetrievalEngine
-from alma.learning.protocols import LearningProtocol
-from alma.config.loader import ConfigLoader
 
 logger = logging.getLogger(__name__)
 
@@ -114,12 +109,19 @@ class ALMA:
 
         if storage_type == "azure":
             from alma.storage.azure_cosmos import AzureCosmosStorage
+
             return AzureCosmosStorage.from_config(config)
+        elif storage_type == "postgres":
+            from alma.storage.postgresql import PostgreSQLStorage
+
+            return PostgreSQLStorage.from_config(config)
         elif storage_type == "sqlite":
             from alma.storage.sqlite_local import SQLiteStorage
+
             return SQLiteStorage.from_config(config)
         else:
             from alma.storage.file_based import FileBasedStorage
+
             return FileBasedStorage.from_config(config)
 
     def retrieve(
@@ -255,9 +257,7 @@ class ALMA:
         # Check scope
         scope = self.scopes.get(agent)
         if scope and not scope.is_allowed(domain):
-            logger.warning(
-                f"Agent '{agent}' not allowed to learn in domain '{domain}'"
-            )
+            logger.warning(f"Agent '{agent}' not allowed to learn in domain '{domain}'")
             return None
 
         result = self.learning.add_domain_knowledge(

alma/domains/__init__.py

@@ -5,17 +5,17 @@ Provides domain-agnostic memory schemas and factory pattern
 for creating domain-specific ALMA instances.
 """
 
-from alma.domains.types import (
-    DomainSchema,
-    EntityType,
-    RelationshipType,
-)
 from alma.domains.factory import DomainMemoryFactory
 from alma.domains.schemas import (
     get_coding_schema,
+    get_general_schema,
     get_research_schema,
     get_sales_schema,
-    get_general_schema,
+)
+from alma.domains.types import (
+    DomainSchema,
+    EntityType,
+    RelationshipType,
 )
 
 __all__ = [

alma/domains/factory.py

@@ -4,18 +4,18 @@ Domain Memory Factory.
 Factory pattern for creating domain-specific ALMA instances.
 """
 
-from typing import Dict, Any, Optional, List, Type
 import logging
+from typing import Any, Dict, List, Optional
 
-from alma.domains.types import DomainSchema, EntityType, RelationshipType
 from alma.domains.schemas import (
     get_coding_schema,
+    get_content_creation_schema,
+    get_customer_support_schema,
+    get_general_schema,
     get_research_schema,
     get_sales_schema,
-    get_general_schema,
-    get_customer_support_schema,
-    get_content_creation_schema,
 )
+from alma.domains.types import DomainSchema
 
 logger = logging.getLogger(__name__)
 
@@ -124,7 +124,9 @@ class DomainMemoryFactory:
             description=config.get("description", f"Custom schema: {name}"),
             learning_categories=config.get("learning_categories", []),
             excluded_categories=config.get("excluded_categories", []),
-            min_occurrences_for_heuristic=config.get("min_occurrences_for_heuristic", 3),
+            min_occurrences_for_heuristic=config.get(
+                "min_occurrences_for_heuristic", 3
+            ),
             confidence_decay_days=config.get("confidence_decay_days", 30.0),
         )
 
@@ -200,16 +202,17 @@ class DomainMemoryFactory:
             - Initialize domain-specific entity tracking
         """
         # Import here to avoid circular dependency
-        from alma.storage.file_based import FileBasedStorage
-        from alma.retrieval import RetrievalEngine
+        from alma import ALMA
         from alma.learning import LearningProtocol
+        from alma.retrieval import RetrievalEngine
+        from alma.storage.file_based import FileBasedStorage
         from alma.types import MemoryScope
-        from alma import ALMA
 
         # Create storage if not provided
         if storage is None:
             import tempfile
             from pathlib import Path
+
             storage_dir = Path(tempfile.mkdtemp()) / ".alma" / project_id
             storage = FileBasedStorage(storage_dir)
 

alma/domains/schemas.py

@@ -4,7 +4,7 @@ Pre-built Domain Schemas.
 Standard domain schemas for common use cases.
 """
 
-from alma.domains.types import DomainSchema, EntityType, RelationshipType
+from alma.domains.types import DomainSchema
 
 
 def get_coding_schema() -> DomainSchema:
@@ -110,12 +110,26 @@ def get_research_schema() -> DomainSchema:
     schema.add_entity_type(
         name="paper",
         description="An academic paper or article",
-        attributes=["title", "authors", "year", "citations", "abstract", "venue", "doi"],
+        attributes=[
+            "title",
+            "authors",
+            "year",
+            "citations",
+            "abstract",
+            "venue",
+            "doi",
+        ],
     )
     schema.add_entity_type(
         name="hypothesis",
         description="A research hypothesis",
-        attributes=["statement", "confidence", "evidence_for", "evidence_against", "status"],
+        attributes=[
+            "statement",
+            "confidence",
+            "evidence_for",
+            "evidence_against",
+            "status",
+        ],
     )
     schema.add_entity_type(
         name="experiment",

alma/domains/types.py

@@ -4,10 +4,10 @@ Domain Memory Types.
 Data models for domain-specific memory schemas.
 """
 
+import uuid
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
-from typing import List, Dict, Any, Optional
-import uuid
+from typing import Any, Dict, List, Optional
 
 
 @dataclass
@@ -21,11 +21,15 @@ class EntityType:
 
     name: str  # "feature", "test", "paper", "lead"
     description: str
-    attributes: List[str] = field(default_factory=list)  # ["status", "priority", "owner"]
+    attributes: List[str] = field(
+        default_factory=list
+    )  # ["status", "priority", "owner"]
 
     # Optional schema validation
     required_attributes: List[str] = field(default_factory=list)
-    attribute_types: Dict[str, str] = field(default_factory=dict)  # attr -> "str", "int", "bool"
+    attribute_types: Dict[str, str] = field(
+        default_factory=dict
+    )  # attr -> "str", "int", "bool"
 
     def validate_entity(self, entity: Dict[str, Any]) -> List[str]:
         """Validate an entity instance against this type."""

alma/events/__init__.py

@@ -0,0 +1,75 @@
+"""
+ALMA Event System.
+
+Provides event emission and webhook delivery for memory operations.
+
+The event system allows external systems to react to memory changes through:
+1. In-process callbacks (subscribe to event types)
+2. Webhooks (HTTP delivery with signatures)
+
+Example - In-process subscription:
+    ```python
+    from alma.events import get_emitter, MemoryEventType
+
+    def on_memory_created(event):
+        print(f"Memory created: {event.memory_id}")
+
+    emitter = get_emitter()
+    emitter.subscribe(MemoryEventType.CREATED, on_memory_created)
+    ```
+
+Example - Webhook delivery:
+    ```python
+    from alma.events import WebhookConfig, WebhookManager, get_emitter
+
+    manager = WebhookManager()
+    manager.add_webhook(WebhookConfig(
+        url="https://example.com/webhook",
+        events=[MemoryEventType.CREATED, MemoryEventType.UPDATED],
+        secret="my-webhook-secret"
+    ))
+    manager.start(get_emitter())
+    ```
+"""
+
+from alma.events.emitter import (
+    EventEmitter,
+    get_emitter,
+    reset_emitter,
+)
+from alma.events.storage_mixin import (
+    EventAwareStorageMixin,
+    emit_on_save,
+)
+from alma.events.types import (
+    MemoryEvent,
+    MemoryEventType,
+    create_memory_event,
+)
+from alma.events.webhook import (
+    WebhookConfig,
+    WebhookDelivery,
+    WebhookDeliveryResult,
+    WebhookDeliveryStatus,
+    WebhookManager,
+)
+
+__all__ = [
+    # Types
+    "MemoryEvent",
+    "MemoryEventType",
+    "create_memory_event",
+    # Emitter
+    "EventEmitter",
+    "get_emitter",
+    "reset_emitter",
+    # Webhook
+    "WebhookConfig",
+    "WebhookDelivery",
+    "WebhookDeliveryResult",
+    "WebhookDeliveryStatus",
+    "WebhookManager",
+    # Storage Mixin
+    "EventAwareStorageMixin",
+    "emit_on_save",
+]

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()