alma-memory 0.4.0__py3-none-any.whl → 0.5.1__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

@@ -1,27 +1,38 @@
 """
 ALMA Core - Main interface for the Agent Learning Memory Architecture.
+
+API Return Type Conventions:
+- Create operations: Return created object or raise exception
+- Update operations: Return updated object or raise exception
+- Delete operations: Return bool (success) or int (count), raise on failure
+- Query operations: Return list (empty if none) or object
+
+All scope violations raise ScopeViolationError for consistent error handling.
 """
 
-from typing import Optional, Dict, Any, List
-from pathlib import Path
-import yaml
 import logging
+import time
+from typing import Any, Dict, Optional
 
+from alma.config.loader import ConfigLoader
+from alma.exceptions import ScopeViolationError
+from alma.learning.protocols import LearningProtocol
+from alma.observability.logging import get_logger
+from alma.observability.metrics import get_metrics
+from alma.observability.tracing import SpanKind, get_tracer, trace_method
+from alma.retrieval.engine import RetrievalEngine
+from alma.storage.base import StorageBackend
 from alma.types import (
-    MemorySlice,
+    DomainKnowledge,
     MemoryScope,
-    Heuristic,
+    MemorySlice,
     Outcome,
     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__)
+structured_logger = get_logger(__name__)
+tracer = get_tracer(__name__)
 
 
 class ALMA:
@@ -114,14 +125,22 @@ 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)
 
+    @trace_method(name="ALMA.retrieve", kind=SpanKind.INTERNAL)
     def retrieve(
         self,
         task: str,
@@ -141,11 +160,19 @@ class ALMA:
         Returns:
             MemorySlice with relevant memories for context injection
         """
+        start_time = time.time()
+        metrics = get_metrics()
+
         # Validate agent has a defined scope
         if agent not in self.scopes:
             logger.warning(f"Agent '{agent}' has no defined scope, using defaults")
+            structured_logger.warning(
+                "Agent has no defined scope, using defaults",
+                agent=agent,
+                project_id=self.project_id,
+            )
 
-        return self.retrieval.retrieve(
+        result = self.retrieval.retrieve(
             query=task,
             agent=agent,
             project_id=self.project_id,
@@ -154,6 +181,30 @@ class ALMA:
             scope=self.scopes.get(agent),
         )
 
+        # Record metrics
+        duration_ms = (time.time() - start_time) * 1000
+        cache_hit = result.retrieval_time_ms < 10  # Approximate cache hit detection
+        metrics.record_retrieve_latency(
+            duration_ms=duration_ms,
+            agent=agent,
+            project_id=self.project_id,
+            cache_hit=cache_hit,
+            items_returned=result.total_items,
+        )
+
+        structured_logger.info(
+            "Memory retrieval completed",
+            agent=agent,
+            project_id=self.project_id,
+            task_preview=task[:50] if task else "",
+            items_returned=result.total_items,
+            duration_ms=duration_ms,
+            cache_hit=cache_hit,
+        )
+
+        return result
+
+    @trace_method(name="ALMA.learn", kind=SpanKind.INTERNAL)
     def learn(
         self,
         agent: str,
@@ -164,7 +215,7 @@ class ALMA:
         duration_ms: Optional[int] = None,
         error_message: Optional[str] = None,
         feedback: Optional[str] = None,
-    ) -> bool:
+    ) -> Outcome:
         """
         Learn from a task outcome.
 
@@ -182,9 +233,15 @@ class ALMA:
             feedback: User feedback if provided
 
         Returns:
-            True if learning was accepted, False if rejected (scope violation)
+            The created Outcome record
+
+        Raises:
+            ScopeViolationError: If learning is outside agent's scope
         """
-        result = self.learning.learn(
+        start_time = time.time()
+        metrics = get_metrics()
+
+        outcome_record = self.learning.learn(
             agent=agent,
             project_id=self.project_id,
             task=task,
@@ -197,10 +254,28 @@ class ALMA:
         )
 
         # Invalidate cache for this agent/project after learning
-        if result:
-            self.retrieval.invalidate_cache(agent=agent, project_id=self.project_id)
+        self.retrieval.invalidate_cache(agent=agent, project_id=self.project_id)
 
-        return result
+        # Record metrics
+        learn_duration_ms = (time.time() - start_time) * 1000
+        metrics.record_learn_operation(
+            duration_ms=learn_duration_ms,
+            agent=agent,
+            project_id=self.project_id,
+            memory_type="outcome",
+            success=True,
+        )
+
+        structured_logger.info(
+            "Learning operation completed",
+            agent=agent,
+            project_id=self.project_id,
+            task_type=task_type,
+            outcome=outcome,
+            duration_ms=learn_duration_ms,
+        )
+
+        return outcome_record
 
     def add_user_preference(
         self,
@@ -239,7 +314,7 @@ class ALMA:
         domain: str,
         fact: str,
         source: str = "user_stated",
-    ) -> Optional[DomainKnowledge]:
+    ) -> DomainKnowledge:
         """
         Add domain knowledge within agent's scope.
 
@@ -250,15 +325,17 @@ class ALMA:
             source: How this was learned
 
         Returns:
-            The created DomainKnowledge or None if scope violation
+            The created DomainKnowledge
+
+        Raises:
+            ScopeViolationError: If agent is not allowed to learn in this domain
         """
         # 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}'"
+            raise ScopeViolationError(
+                f"Agent '{agent}' is not allowed to learn in domain '{domain}'"
             )
-            return None
 
         result = self.learning.add_domain_knowledge(
             agent=agent,
@@ -269,11 +346,11 @@ class ALMA:
         )
 
         # Invalidate cache for this agent/project after adding knowledge
-        if result:
-            self.retrieval.invalidate_cache(agent=agent, project_id=self.project_id)
+        self.retrieval.invalidate_cache(agent=agent, project_id=self.project_id)
 
         return result
 
+    @trace_method(name="ALMA.forget", kind=SpanKind.INTERNAL)
     def forget(
         self,
         agent: Optional[str] = None,
@@ -283,7 +360,8 @@ class ALMA:
         """
         Prune stale or low-confidence memories.
 
-        Invalidates cache after pruning to ensure fresh retrieval results.
+        This is a delete operation that invalidates cache after pruning
+        to ensure fresh retrieval results.
 
         Args:
             agent: Specific agent to prune, or None for all
@@ -291,8 +369,14 @@ class ALMA:
             below_confidence: Remove heuristics below this confidence
 
         Returns:
-            Number of items pruned
+            Number of items pruned (0 if nothing was pruned)
+
+        Raises:
+            StorageError: If the delete operation fails
         """
+        start_time = time.time()
+        metrics = get_metrics()
+
         count = self.learning.forget(
             project_id=self.project_id,
             agent=agent,
@@ -304,17 +388,41 @@ class ALMA:
         if count > 0:
             self.retrieval.invalidate_cache(agent=agent, project_id=self.project_id)
 
+        # Record metrics
+        duration_ms = (time.time() - start_time) * 1000
+        metrics.record_forget_operation(
+            duration_ms=duration_ms,
+            agent=agent,
+            project_id=self.project_id,
+            items_removed=count,
+        )
+
+        structured_logger.info(
+            "Forget operation completed",
+            agent=agent or "all",
+            project_id=self.project_id,
+            items_removed=count,
+            older_than_days=older_than_days,
+            below_confidence=below_confidence,
+            duration_ms=duration_ms,
+        )
+
         return count
 
     def get_stats(self, agent: Optional[str] = None) -> Dict[str, Any]:
         """
         Get memory statistics.
 
+        This is a query operation that returns statistics about stored memories.
+
         Args:
             agent: Specific agent or None for all
 
         Returns:
-            Dict with counts and metadata
+            Dict with counts and metadata (always returns a dict, may be empty)
+
+        Raises:
+            StorageError: If the query operation fails
         """
         return self.storage.get_stats(
             project_id=self.project_id,

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",
+]