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

alma/__init__.py

@@ -12,84 +12,135 @@ The Harness Pattern:
 
 This makes any tool-using agent appear to "learn" by injecting relevant
 memory slices before each run and updating memory after.
+
+Testing Support:
+    For testing ALMA integrations, use the `alma.testing` module:
+
+        from alma.testing import MockStorage, create_test_heuristic
+
+        def test_my_integration():
+            storage = MockStorage()
+            heuristic = create_test_heuristic(agent="test-agent")
+            storage.save_heuristic(heuristic)
+
+    Available utilities:
+    - MockStorage: In-memory storage backend
+    - MockEmbedder: Deterministic fake embeddings
+    - create_test_heuristic(), create_test_outcome(), etc.
 """
 
-__version__ = "0.4.0"
+__version__ = "0.5.1"
 
 # Core
+# Confidence Engine (Phase 12)
+from alma.confidence import (
+    ConfidenceEngine,
+    ConfidenceSignal,
+    OpportunitySignal,
+    RiskSignal,
+)
+
+# Consolidation Engine (Phase 13)
+from alma.consolidation import (
+    ConsolidationEngine,
+    ConsolidationResult,
+)
 from alma.core import ALMA
-from alma.types import (
-    Heuristic,
-    Outcome,
-    UserPreference,
-    DomainKnowledge,
-    AntiPattern,
-    MemorySlice,
-    MemoryScope,
+
+# Domain Memory Factory (Phase 10)
+from alma.domains import (
+    DomainMemoryFactory,
+    DomainSchema,
+    EntityType,
+    RelationshipType,
+    get_coding_schema,
+    get_general_schema,
+    get_research_schema,
+    get_sales_schema,
+)
+
+# Event System (Phase 19)
+from alma.events import (
+    EventEmitter,
+    MemoryEvent,
+    MemoryEventType,
+    WebhookConfig,
+    WebhookManager,
+    get_emitter,
+)
+
+# Exceptions
+from alma.exceptions import (
+    ALMAError,
+    ConfigurationError,
+    EmbeddingError,
+    ExtractionError,
+    RetrievalError,
+    ScopeViolationError,
+    StorageError,
 )
 
 # Harness Pattern
 from alma.harness.base import (
-    Setting,
-    Context,
     Agent,
-    MemorySchema,
+    Context,
     Harness,
+    MemorySchema,
+    RunResult,
+    Setting,
     Tool,
     ToolType,
-    RunResult,
 )
 from alma.harness.domains import (
     CodingDomain,
-    ResearchDomain,
     ContentDomain,
     OperationsDomain,
+    ResearchDomain,
     create_harness,
 )
 
+# Session Initializer (Phase 11)
+from alma.initializer import (
+    CodebaseOrientation,
+    InitializationResult,
+    RulesOfEngagement,
+    SessionInitializer,
+)
+
+# Observability (Phase 20)
+from alma.observability import (
+    ALMAMetrics,
+    configure_observability,
+    get_logger,
+    get_metrics,
+    get_tracer,
+    trace_method,
+)
+
 # Progress Tracking (Phase 10)
 from alma.progress import (
-    WorkItem,
-    WorkItemStatus,
     ProgressLog,
     ProgressSummary,
     ProgressTracker,
+    WorkItem,
+    WorkItemStatus,
 )
 
 # Session Management (Phase 10)
 from alma.session import (
-    SessionHandoff,
     SessionContext,
-    SessionOutcome,
+    SessionHandoff,
     SessionManager,
+    SessionOutcome,
 )
-
-# Domain Memory Factory (Phase 10)
-from alma.domains import (
-    DomainSchema,
-    EntityType,
-    RelationshipType,
-    DomainMemoryFactory,
-    get_coding_schema,
-    get_research_schema,
-    get_sales_schema,
-    get_general_schema,
-)
-
-# Session Initializer (Phase 11)
-from alma.initializer import (
-    CodebaseOrientation,
-    InitializationResult,
-    RulesOfEngagement,
-    SessionInitializer,
-)
-
-# Confidence Engine (Phase 12)
-from alma.confidence import (
-    ConfidenceEngine,
-    ConfidenceSignal,
-    OpportunitySignal,
-    RiskSignal,
+from alma.types import (
+    AntiPattern,
+    DomainKnowledge,
+    Heuristic,
+    MemoryScope,
+    MemorySlice,
+    Outcome,
+    UserPreference,
 )
 
 __all__ = [
@@ -147,4 +198,29 @@ __all__ = [
     "ConfidenceSignal",
     "OpportunitySignal",
     "RiskSignal",
+    # Consolidation Engine
+    "ConsolidationEngine",
+    "ConsolidationResult",
+    # Event System
+    "MemoryEvent",
+    "MemoryEventType",
+    "EventEmitter",
+    "get_emitter",
+    "WebhookConfig",
+    "WebhookManager",
+    # Exceptions
+    "ALMAError",
+    "ConfigurationError",
+    "ScopeViolationError",
+    "StorageError",
+    "EmbeddingError",
+    "RetrievalError",
+    "ExtractionError",
+    # Observability
+    "configure_observability",
+    "get_tracer",
+    "get_logger",
+    "get_metrics",
+    "ALMAMetrics",
+    "trace_method",
 ]

alma/confidence/__init__.py

@@ -30,13 +30,13 @@ Usage:
     )
 """
 
+from alma.confidence.engine import ConfidenceEngine
 from alma.confidence.types import (
     ConfidenceSignal,
     OpportunitySignal,
     Recommendation,
     RiskSignal,
 )
-from alma.confidence.engine import ConfidenceEngine
 
 __all__ = [
     "ConfidenceSignal",

alma/confidence/engine.py

@@ -95,11 +95,13 @@ class ConfidenceEngine:
 
         # 1. Load historical data from heuristic
         if heuristic:
-            signal.occurrence_count = getattr(heuristic, 'occurrence_count', 0)
-            success_count = getattr(heuristic, 'success_count', 0)
+            signal.occurrence_count = getattr(heuristic, "occurrence_count", 0)
+            success_count = getattr(heuristic, "success_count", 0)
             if signal.occurrence_count > 0:
                 signal.historical_success_rate = success_count / signal.occurrence_count
-            signal.metadata["heuristic_confidence"] = getattr(heuristic, 'confidence', 0.5)
+            signal.metadata["heuristic_confidence"] = getattr(
+                heuristic, "confidence", 0.5
+            )
 
         # 2. Analyze context similarity
         signal.context_similarity = self._compute_context_similarity(
@@ -214,30 +216,43 @@ class ConfidenceEngine:
                     top_k=10,
                 )
 
-                if memories and hasattr(memories, 'anti_patterns'):
+                if memories and hasattr(memories, "anti_patterns"):
                     for ap in memories.anti_patterns[:3]:
                         # Check if this anti-pattern relates to our strategy
                         if self._is_similar(strategy, ap.strategy):
-                            risks.append(RiskSignal(
-                                signal_type="similar_to_failure",
-                                description=f"Similar to known anti-pattern: {ap.reason[:100]}",
-                                severity=0.7,
-                                source=f"anti_pattern:{ap.id}",
-                                related_memories=[ap.id],
-                            ))
+                            risks.append(
+                                RiskSignal(
+                                    signal_type="similar_to_failure",
+                                    description=f"Similar to known anti-pattern: {ap.reason[:100]}",
+                                    severity=0.7,
+                                    source=f"anti_pattern:{ap.id}",
+                                    related_memories=[ap.id],
+                                )
+                            )
             except Exception as e:
                 logger.warning(f"Failed to check anti-patterns: {e}")
 
         # Check for complexity indicators
-        complexity_keywords = ["complex", "multiple", "all", "every", "entire", "complete"]
-        complexity_score = sum(1 for kw in complexity_keywords if kw in strategy.lower())
+        complexity_keywords = [
+            "complex",
+            "multiple",
+            "all",
+            "every",
+            "entire",
+            "complete",
+        ]
+        complexity_score = sum(
+            1 for kw in complexity_keywords if kw in strategy.lower()
+        )
         if complexity_score >= 2:
-            risks.append(RiskSignal(
-                signal_type="high_complexity",
-                description="Strategy appears complex - consider breaking into smaller steps",
-                severity=0.4,
-                source="context_analysis",
-            ))
+            risks.append(
+                RiskSignal(
+                    signal_type="high_complexity",
+                    description="Strategy appears complex - consider breaking into smaller steps",
+                    severity=0.4,
+                    source="context_analysis",
+                )
+            )
 
         # Check for risky patterns
         risky_patterns = [
@@ -248,12 +263,14 @@ class ConfidenceEngine:
         ]
         for pattern, description, severity in risky_patterns:
             if pattern in strategy.lower():
-                risks.append(RiskSignal(
-                    signal_type="risky_pattern",
-                    description=description,
-                    severity=severity,
-                    source="pattern_match",
-                ))
+                risks.append(
+                    RiskSignal(
+                        signal_type="risky_pattern",
+                        description=description,
+                        severity=severity,
+                        source="pattern_match",
+                    )
+                )
 
         return risks
 
@@ -291,34 +308,43 @@ class ConfidenceEngine:
                     top_k=10,
                 )
 
-                if memories and hasattr(memories, 'heuristics'):
+                if memories and hasattr(memories, "heuristics"):
                     for h in memories.heuristics[:3]:
                         # Check success rate
                         if h.occurrence_count >= self.min_occurrences_for_confidence:
-                            success_rate = h.success_count / h.occurrence_count if h.occurrence_count > 0 else 0
+                            success_rate = (
+                                h.success_count / h.occurrence_count
+                                if h.occurrence_count > 0
+                                else 0
+                            )
                             if success_rate >= 0.8:
-                                opportunities.append(OpportunitySignal(
-                                    signal_type="proven_pattern",
-                                    description=f"Proven strategy with {success_rate:.0%} success rate over {h.occurrence_count} uses",
-                                    strength=min(0.9, success_rate),
-                                    source=f"heuristic:{h.id}",
-                                    related_memories=[h.id],
-                                ))
+                                opportunities.append(
+                                    OpportunitySignal(
+                                        signal_type="proven_pattern",
+                                        description=f"Proven strategy with {success_rate:.0%} success rate over {h.occurrence_count} uses",
+                                        strength=min(0.9, success_rate),
+                                        source=f"heuristic:{h.id}",
+                                        related_memories=[h.id],
+                                    )
+                                )
 
                 # Check for recent successes in outcomes
-                if hasattr(memories, 'outcomes'):
+                if hasattr(memories, "outcomes"):
                     recent_successes = [
-                        o for o in memories.outcomes
-                        if getattr(o, 'outcome', '') == 'success'
+                        o
+                        for o in memories.outcomes
+                        if getattr(o, "outcome", "") == "success"
                     ][:3]
                     if recent_successes:
-                        opportunities.append(OpportunitySignal(
-                            signal_type="recent_success",
-                            description=f"Similar approach succeeded recently ({len(recent_successes)} recent successes)",
-                            strength=0.6,
-                            source="outcome_analysis",
-                            related_memories=[o.id for o in recent_successes],
-                        ))
+                        opportunities.append(
+                            OpportunitySignal(
+                                signal_type="recent_success",
+                                description=f"Similar approach succeeded recently ({len(recent_successes)} recent successes)",
+                                strength=0.6,
+                                source="outcome_analysis",
+                                related_memories=[o.id for o in recent_successes],
+                            )
+                        )
 
             except Exception as e:
                 logger.warning(f"Failed to check opportunities: {e}")
@@ -332,12 +358,14 @@ class ConfidenceEngine:
         ]
         for pattern, description, strength in best_practices:
             if pattern in strategy.lower():
-                opportunities.append(OpportunitySignal(
-                    signal_type="best_practice",
-                    description=description,
-                    strength=strength,
-                    source="pattern_match",
-                ))
+                opportunities.append(
+                    OpportunitySignal(
+                        signal_type="best_practice",
+                        description=description,
+                        strength=strength,
+                        source="pattern_match",
+                    )
+                )
 
         return opportunities
 
@@ -363,19 +391,21 @@ class ConfidenceEngine:
                 return 0.3  # Low similarity for novel contexts
 
             # Check if any outcomes match our strategy
-            if hasattr(memories, 'outcomes'):
+            if hasattr(memories, "outcomes"):
                 matching_outcomes = [
-                    o for o in memories.outcomes
-                    if self._is_similar(strategy, getattr(o, 'strategy_used', ''))
+                    o
+                    for o in memories.outcomes
+                    if self._is_similar(strategy, getattr(o, "strategy_used", ""))
                 ]
                 if matching_outcomes:
                     return 0.8  # High similarity
 
             # Check heuristics
-            if hasattr(memories, 'heuristics'):
+            if hasattr(memories, "heuristics"):
                 matching_heuristics = [
-                    h for h in memories.heuristics
-                    if self._is_similar(strategy, getattr(h, 'strategy', ''))
+                    h
+                    for h in memories.heuristics
+                    if self._is_similar(strategy, getattr(h, "strategy", ""))
                 ]
                 if matching_heuristics:
                     return 0.7
@@ -489,7 +519,9 @@ class ConfidenceEngine:
 
         # Context similarity
         if signal.context_similarity >= 0.7:
-            parts.append("Current context is highly similar to past successful applications.")
+            parts.append(
+                "Current context is highly similar to past successful applications."
+            )
         elif signal.context_similarity <= 0.3:
             parts.append("Current context is quite different from past applications.")
 
@@ -501,6 +533,8 @@ class ConfidenceEngine:
         # Key opportunities
         strong_opps = [o for o in signal.opportunity_signals if o.strength >= 0.6]
         if strong_opps:
-            parts.append(f"POSITIVE: {len(strong_opps)} strong opportunity signal(s) detected.")
+            parts.append(
+                f"POSITIVE: {len(strong_opps)} strong opportunity signal(s) detected."
+            )
 
         return " ".join(parts)

alma/confidence/types.py

@@ -5,10 +5,10 @@ Forward-looking confidence signals for strategies.
 Inspired by Ilya Sutskever's insight: emotions are forward-looking value functions.
 """
 
+import uuid
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from typing import Any, Dict, List, Literal, Optional
-import uuid
 
 
 @dataclass
@@ -27,7 +27,9 @@ class RiskSignal:
     id: str = field(default_factory=lambda: str(uuid.uuid4()))
 
     # Type of risk
-    signal_type: str = ""  # "similar_to_failure", "untested_context", "high_complexity", etc.
+    signal_type: str = (
+        ""  # "similar_to_failure", "untested_context", "high_complexity", etc.
+    )
 
     # Human-readable description
     description: str = ""
@@ -139,7 +141,9 @@ class ConfidenceSignal:
 
     # Forward-looking predictions (computed for current context)
     predicted_success: float = 0.5  # Expected success in THIS context
-    uncertainty: float = 0.5  # How uncertain is the prediction (0=certain, 1=very uncertain)
+    uncertainty: float = (
+        0.5  # How uncertain is the prediction (0=certain, 1=very uncertain)
+    )
     context_similarity: float = 0.0  # How similar is current context to past successes
 
     # Risk signals
@@ -225,26 +229,28 @@ class ConfidenceSignal:
         # Aggregate opportunity
         if self.opportunity_signals:
             # Use max opportunity as the dominant signal
-            self.total_opportunity_score = max(o.strength for o in self.opportunity_signals)
+            self.total_opportunity_score = max(
+                o.strength for o in self.opportunity_signals
+            )
         else:
             self.total_opportunity_score = 0.0
 
         # Combined confidence score
         # Weighs historical success, predicted success, and risk/opportunity balance
         base_confidence = (
-            0.3 * self.historical_success_rate +
-            0.4 * self.predicted_success +
-            0.15 * self.context_similarity +
-            0.15 * (1.0 - self.uncertainty)
+            0.3 * self.historical_success_rate
+            + 0.4 * self.predicted_success
+            + 0.15 * self.context_similarity
+            + 0.15 * (1.0 - self.uncertainty)
         )
 
         # Adjust for risk/opportunity
         risk_adjustment = -0.2 * self.total_risk_score
         opportunity_adjustment = 0.2 * self.total_opportunity_score
 
-        self.confidence_score = max(0.0, min(1.0,
-            base_confidence + risk_adjustment + opportunity_adjustment
-        ))
+        self.confidence_score = max(
+            0.0, min(1.0, base_confidence + risk_adjustment + opportunity_adjustment)
+        )
 
         # Determine recommendation
         self._update_recommendation()
@@ -277,7 +283,9 @@ class ConfidenceSignal:
 
         # Metrics
         lines.append("### Metrics")
-        lines.append(f"- Historical success: {self.historical_success_rate:.0%} ({self.occurrence_count} uses)")
+        lines.append(
+            f"- Historical success: {self.historical_success_rate:.0%} ({self.occurrence_count} uses)"
+        )
         lines.append(f"- Predicted success: {self.predicted_success:.0%}")
         lines.append(f"- Context similarity: {self.context_similarity:.0%}")
         lines.append(f"- Uncertainty: {self.uncertainty:.0%}")
@@ -287,7 +295,13 @@ class ConfidenceSignal:
         if self.risk_signals:
             lines.append("### Risks")
             for risk in self.risk_signals:
-                severity_label = "HIGH" if risk.severity >= 0.7 else "MEDIUM" if risk.severity >= 0.4 else "LOW"
+                severity_label = (
+                    "HIGH"
+                    if risk.severity >= 0.7
+                    else "MEDIUM"
+                    if risk.severity >= 0.4
+                    else "LOW"
+                )
                 lines.append(f"- [{severity_label}] {risk.description}")
             lines.append("")
 
@@ -295,7 +309,13 @@ class ConfidenceSignal:
         if self.opportunity_signals:
             lines.append("### Opportunities")
             for opp in self.opportunity_signals:
-                strength_label = "STRONG" if opp.strength >= 0.7 else "MODERATE" if opp.strength >= 0.4 else "WEAK"
+                strength_label = (
+                    "STRONG"
+                    if opp.strength >= 0.7
+                    else "MODERATE"
+                    if opp.strength >= 0.4
+                    else "WEAK"
+                )
                 lines.append(f"- [{strength_label}] {opp.description}")
             lines.append("")
 

alma/config/loader.py

@@ -5,10 +5,10 @@ Handles loading configuration from files and environment variables,
 with support for Azure Key Vault secret resolution.
 """
 
-import os
 import logging
+import os
 from pathlib import Path
-from typing import Dict, Any, Optional
+from typing import Any, Dict
 
 import yaml
 
@@ -78,6 +78,7 @@ class ConfigLoader:
 
         # Handle ${VAR} patterns
         import re
+
         pattern = r"\$\{([^}]+)\}"
 
         def replace(match):

alma/consolidation/__init__.py

@@ -0,0 +1,23 @@
+"""
+ALMA Consolidation Module.
+
+Provides memory consolidation capabilities for deduplicating and merging
+similar memories, inspired by Mem0's core innovation.
+"""
+
+from alma.consolidation.engine import ConsolidationEngine, ConsolidationResult
+from alma.consolidation.prompts import (
+    MERGE_ANTI_PATTERNS_PROMPT,
+    MERGE_DOMAIN_KNOWLEDGE_PROMPT,
+    MERGE_HEURISTICS_PROMPT,
+    MERGE_OUTCOMES_PROMPT,
+)
+
+__all__ = [
+    "ConsolidationEngine",
+    "ConsolidationResult",
+    "MERGE_HEURISTICS_PROMPT",
+    "MERGE_DOMAIN_KNOWLEDGE_PROMPT",
+    "MERGE_ANTI_PATTERNS_PROMPT",
+    "MERGE_OUTCOMES_PROMPT",
+]