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

alma/retrieval/cache.py

@@ -5,16 +5,15 @@ Multi-backend caching layer for retrieval results with TTL-based expiration.
 Supports in-memory and Redis backends with performance monitoring.
 """
 
-import time
-import json
 import hashlib
-import threading
+import json
 import logging
+import threading
+import time
 from abc import ABC, abstractmethod
-from typing import Optional, Dict, Any, List, Callable, Tuple
-from dataclasses import dataclass, field, asdict
+from dataclasses import dataclass, field
 from datetime import datetime, timezone
-from contextlib import contextmanager
+from typing import Any, Callable, Dict, List, Optional
 
 from alma.types import MemorySlice
 
@@ -27,6 +26,7 @@ logger = logging.getLogger(__name__)
 @dataclass
 class CacheEntry:
     """A cached retrieval result with metadata."""
+
     result: MemorySlice
     created_at: float  # time.time() timestamp
     expires_at: float
@@ -41,6 +41,7 @@ class CacheEntry:
 @dataclass
 class CacheStats:
     """Statistics about cache performance."""
+
     hits: int = 0
     misses: int = 0
     evictions: int = 0
@@ -81,6 +82,7 @@ class CacheStats:
 @dataclass
 class PerformanceMetrics:
     """Tracks timing metrics for performance analysis."""
+
     get_times: List[float] = field(default_factory=list)
     set_times: List[float] = field(default_factory=list)
     max_samples: int = 1000
@@ -89,13 +91,13 @@ class PerformanceMetrics:
         """Record a get operation time."""
         self.get_times.append(duration_ms)
         if len(self.get_times) > self.max_samples:
-            self.get_times = self.get_times[-self.max_samples:]
+            self.get_times = self.get_times[-self.max_samples :]
 
     def record_set(self, duration_ms: float):
         """Record a set operation time."""
         self.set_times.append(duration_ms)
         if len(self.set_times) > self.max_samples:
-            self.set_times = self.set_times[-self.max_samples:]
+            self.set_times = self.set_times[-self.max_samples :]
 
     def get_percentile(self, times: List[float], percentile: float) -> float:
         """Calculate percentile from timing data."""
@@ -430,9 +432,7 @@ class RetrievalCache(CacheBackend):
         """Remove all expired entries."""
         now = time.time()
         expired = [
-            (key, entry)
-            for key, entry in self._cache.items()
-            if now > entry.expires_at
+            (key, entry) for key, entry in self._cache.items() if now > entry.expires_at
         ]
 
         for key, entry in expired:
@@ -587,13 +587,12 @@ class RedisCache(CacheBackend):
             # Test connection
             self._redis.ping()
             logger.info(f"Connected to Redis at {host}:{port}")
-        except ImportError:
+        except ImportError as err:
             raise ImportError(
-                "redis package required for RedisCache. "
-                "Install with: pip install redis"
-            )
+                "redis package required for RedisCache. Install with: pip install redis"
+            ) from err
         except Exception as e:
-            raise ConnectionError(f"Failed to connect to Redis: {e}")
+            raise ConnectionError(f"Failed to connect to Redis: {e}") from e
 
     def set_hooks(
         self,
@@ -641,9 +640,9 @@ class RedisCache(CacheBackend):
                     "confidence": h.confidence,
                     "occurrence_count": h.occurrence_count,
                     "success_count": h.success_count,
-                    "last_validated": h.last_validated.isoformat()
-                    if h.last_validated
-                    else None,
+                    "last_validated": (
+                        h.last_validated.isoformat() if h.last_validated else None
+                    ),
                     "created_at": h.created_at.isoformat() if h.created_at else None,
                 }
                 for h in result.heuristics
@@ -703,11 +702,11 @@ class RedisCache(CacheBackend):
     def _deserialize_result(self, data: bytes) -> MemorySlice:
         """Deserialize bytes to MemorySlice."""
         from alma.types import (
+            AntiPattern,
+            DomainKnowledge,
             Heuristic,
             Outcome,
             UserPreference,
-            DomainKnowledge,
-            AntiPattern,
         )
 
         obj = json.loads(data.decode("utf-8"))

alma/retrieval/embeddings.py

@@ -59,11 +59,11 @@ class LocalEmbedder(EmbeddingProvider):
                 self._model = SentenceTransformer(self.model_name)
                 self._dimension = self._model.get_sentence_embedding_dimension()
                 logger.info(f"Model loaded, dimension: {self._dimension}")
-            except ImportError:
+            except ImportError as err:
                 raise ImportError(
                     "sentence-transformers is required for local embeddings. "
                     "Install with: pip install sentence-transformers"
-                )
+                ) from err
 
     def encode(self, text: str) -> List[float]:
         """Generate embedding for text."""
@@ -134,11 +134,11 @@ class AzureEmbedder(EmbeddingProvider):
                     api_key=self.api_key,
                     api_version=self.api_version,
                 )
-            except ImportError:
+            except ImportError as err:
                 raise ImportError(
                     "openai is required for Azure embeddings. "
                     "Install with: pip install openai"
-                )
+                ) from err
         return self._client
 
     def encode(self, text: str) -> List[float]:

alma/retrieval/engine.py

@@ -4,16 +4,21 @@ ALMA Retrieval Engine.
 Handles semantic search and memory retrieval with scoring and caching.
 """
 
-import time
 import logging
-from typing import Optional, List, Dict, Any
+import time
+from typing import Any, Dict, List, Optional
 
-from alma.types import MemorySlice, MemoryScope
+from alma.observability.logging import get_logger
+from alma.observability.metrics import get_metrics
+from alma.observability.tracing import get_tracer
+from alma.retrieval.cache import NullCache, RetrievalCache
+from alma.retrieval.scoring import MemoryScorer, ScoredItem, ScoringWeights
 from alma.storage.base import StorageBackend
-from alma.retrieval.scoring import MemoryScorer, ScoringWeights, ScoredItem
-from alma.retrieval.cache import RetrievalCache, NullCache
+from alma.types import MemoryScope, MemorySlice
 
 logger = logging.getLogger(__name__)
+structured_logger = get_logger(__name__)
+tracer = get_tracer(__name__)
 
 
 class RetrievalEngine:
@@ -81,18 +86,24 @@ class RetrievalEngine:
         top_k: int = 5,
         scope: Optional[MemoryScope] = None,
         bypass_cache: bool = False,
+        include_shared: bool = True,
     ) -> MemorySlice:
         """
         Retrieve relevant memories for a task.
 
+        Supports multi-agent memory sharing: if a scope is provided with
+        inherit_from agents, memories from those agents will also be included.
+        Shared memories have their origin tracked in the metadata['shared_from'] field.
+
         Args:
             query: Task description to find relevant memories for
             agent: Agent requesting memories
             project_id: Project context
             user_id: Optional user for preference retrieval
             top_k: Max items per memory type
-            scope: Agent's learning scope for filtering
+            scope: Agent's learning scope for filtering (enables multi-agent sharing)
             bypass_cache: Skip cache lookup/storage
+            include_shared: If True and scope has inherit_from, include shared memories
 
         Returns:
             MemorySlice with relevant memories, scored and ranked
@@ -110,36 +121,79 @@ class RetrievalEngine:
         # Generate embedding for query
         query_embedding = self._get_embedding(query)
 
-        # Retrieve raw items from storage (with vector search)
-        raw_heuristics = self.storage.get_heuristics(
-            project_id=project_id,
-            agent=agent,
-            embedding=query_embedding,
-            top_k=top_k * 2,  # Get extra for scoring/filtering
-            min_confidence=0.0,  # Let scorer handle filtering
-        )
-
-        raw_outcomes = self.storage.get_outcomes(
-            project_id=project_id,
-            agent=agent,
-            embedding=query_embedding,
-            top_k=top_k * 2,
-            success_only=False,
-        )
+        # Determine which agents to query based on scope
+        agents_to_query = [agent]
+        if include_shared and scope and scope.inherit_from:
+            agents_to_query = scope.get_readable_agents()
+            logger.debug(
+                f"Multi-agent retrieval for {agent}: querying {agents_to_query}"
+            )
 
-        raw_domain_knowledge = self.storage.get_domain_knowledge(
-            project_id=project_id,
-            agent=agent,
-            embedding=query_embedding,
-            top_k=top_k * 2,
-        )
+        # Retrieve raw items from storage (with vector search)
+        if len(agents_to_query) > 1:
+            # Use multi-agent query methods
+            raw_heuristics = self.storage.get_heuristics_for_agents(
+                project_id=project_id,
+                agents=agents_to_query,
+                embedding=query_embedding,
+                top_k=top_k * 2,
+                min_confidence=0.0,
+            )
+            raw_outcomes = self.storage.get_outcomes_for_agents(
+                project_id=project_id,
+                agents=agents_to_query,
+                embedding=query_embedding,
+                top_k=top_k * 2,
+                success_only=False,
+            )
+            raw_domain_knowledge = self.storage.get_domain_knowledge_for_agents(
+                project_id=project_id,
+                agents=agents_to_query,
+                embedding=query_embedding,
+                top_k=top_k * 2,
+            )
+            raw_anti_patterns = self.storage.get_anti_patterns_for_agents(
+                project_id=project_id,
+                agents=agents_to_query,
+                embedding=query_embedding,
+                top_k=top_k * 2,
+            )
 
-        raw_anti_patterns = self.storage.get_anti_patterns(
-            project_id=project_id,
-            agent=agent,
-            embedding=query_embedding,
-            top_k=top_k * 2,
-        )
+            # Mark shared memories with origin tracking
+            raw_heuristics = self._mark_shared_memories(raw_heuristics, agent)
+            raw_outcomes = self._mark_shared_memories(raw_outcomes, agent)
+            raw_domain_knowledge = self._mark_shared_memories(
+                raw_domain_knowledge, agent
+            )
+            raw_anti_patterns = self._mark_shared_memories(raw_anti_patterns, agent)
+        else:
+            # Single agent query (original behavior)
+            raw_heuristics = self.storage.get_heuristics(
+                project_id=project_id,
+                agent=agent,
+                embedding=query_embedding,
+                top_k=top_k * 2,
+                min_confidence=0.0,
+            )
+            raw_outcomes = self.storage.get_outcomes(
+                project_id=project_id,
+                agent=agent,
+                embedding=query_embedding,
+                top_k=top_k * 2,
+                success_only=False,
+            )
+            raw_domain_knowledge = self.storage.get_domain_knowledge(
+                project_id=project_id,
+                agent=agent,
+                embedding=query_embedding,
+                top_k=top_k * 2,
+            )
+            raw_anti_patterns = self.storage.get_anti_patterns(
+                project_id=project_id,
+                agent=agent,
+                embedding=query_embedding,
+                top_k=top_k * 2,
+            )
 
         # Score and rank each type
         scored_heuristics = self.scorer.score_heuristics(raw_heuristics)
@@ -182,6 +236,31 @@ class RetrievalEngine:
 
         return result
 
+    def _mark_shared_memories(
+        self,
+        memories: List[Any],
+        requesting_agent: str,
+    ) -> List[Any]:
+        """
+        Mark memories that came from other agents with their origin.
+
+        Adds 'shared_from' to metadata for memories not owned by requesting_agent.
+        This maintains write isolation - only the owning agent can modify their memories.
+
+        Args:
+            memories: List of memory objects (Heuristic, Outcome, etc.)
+            requesting_agent: The agent that requested the memories
+
+        Returns:
+            Same memories with shared_from metadata added where applicable
+        """
+        for memory in memories:
+            if hasattr(memory, "agent") and memory.agent != requesting_agent:
+                if not hasattr(memory, "metadata") or memory.metadata is None:
+                    memory.metadata = {}
+                memory.metadata["shared_from"] = memory.agent
+        return memories
+
     def _extract_top_k(
         self,
         scored_items: List[ScoredItem],
@@ -211,19 +290,78 @@ class RetrievalEngine:
         if self._embedder is None:
             self._embedder = self._init_embedder()
 
-        return self._embedder.encode(text)
+        start_time = time.time()
+        embedding = self._embedder.encode(text)
+        duration_ms = (time.time() - start_time) * 1000
+
+        # Record embedding generation metrics
+        metrics = get_metrics()
+        metrics.record_embedding_latency(
+            duration_ms=duration_ms,
+            provider=self.embedding_provider,
+            batch_size=1,
+        )
+
+        return embedding
 
     def _init_embedder(self):
         """Initialize the embedding model based on provider config."""
         if self.embedding_provider == "azure":
             from alma.retrieval.embeddings import AzureEmbedder
-            return AzureEmbedder()
+
+            embedder = AzureEmbedder()
         elif self.embedding_provider == "mock":
             from alma.retrieval.embeddings import MockEmbedder
-            return MockEmbedder()
+
+            embedder = MockEmbedder()
         else:
             from alma.retrieval.embeddings import LocalEmbedder
-            return LocalEmbedder()
+
+            embedder = LocalEmbedder()
+
+        # Validate embedding dimension matches storage configuration
+        self._validate_embedding_dimension(embedder)
+        return embedder
+
+    def _validate_embedding_dimension(self, embedder) -> None:
+        """
+        Validate that embedding provider dimension matches storage configuration.
+
+        Raises:
+            ValueError: If dimensions don't match
+        """
+        provider_dim = embedder.dimension
+
+        # Check if storage has embedding_dim attribute
+        storage_dim = getattr(self.storage, "embedding_dim", None)
+        if storage_dim is None:
+            logger.debug(
+                "Storage backend doesn't specify embedding_dim, skipping validation"
+            )
+            return
+
+        # Skip validation if storage_dim is not an integer (e.g., mock objects)
+        if not isinstance(storage_dim, int):
+            logger.debug(
+                f"Storage embedding_dim is not an integer ({type(storage_dim)}), "
+                "skipping validation"
+            )
+            return
+
+        if provider_dim != storage_dim:
+            raise ValueError(
+                f"Embedding dimension mismatch: provider '{self.embedding_provider}' "
+                f"outputs {provider_dim} dimensions, but storage is configured for "
+                f"{storage_dim} dimensions. Update your config's embedding_dim to "
+                f"match the provider, or use a different embedding provider.\n"
+                f"  - local (all-MiniLM-L6-v2): 384 dimensions\n"
+                f"  - azure (text-embedding-3-small): 1536 dimensions"
+            )
+
+        logger.info(
+            f"Embedding dimension validated: {provider_dim} "
+            f"(provider: {self.embedding_provider})"
+        )
 
     def invalidate_cache(
         self,
@@ -280,7 +418,9 @@ class RetrievalEngine:
         self.scorer.weights = ScoringWeights(
             similarity=similarity if similarity is not None else current.similarity,
             recency=recency if recency is not None else current.recency,
-            success_rate=success_rate if success_rate is not None else current.success_rate,
+            success_rate=(
+                success_rate if success_rate is not None else current.success_rate
+            ),
             confidence=confidence if confidence is not None else current.confidence,
         )
         # Clear cache since scoring changed

alma/retrieval/scoring.py

@@ -5,11 +5,11 @@ Combines semantic similarity, recency, and success rate for optimal retrieval.
 """
 
 import math
-from datetime import datetime, timezone
-from typing import List, Dict, Any, Optional, TypeVar, Callable
 from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, List, Optional
 
-from alma.types import Heuristic, Outcome, DomainKnowledge, AntiPattern
+from alma.types import AntiPattern, DomainKnowledge, Heuristic, Outcome
 
 
 @dataclass
@@ -19,10 +19,11 @@ class ScoringWeights:
 
     All weights should sum to 1.0 for normalized scores.
     """
-    similarity: float = 0.4      # Semantic relevance to query
-    recency: float = 0.3         # How recently the memory was validated/used
-    success_rate: float = 0.2    # Historical success rate
-    confidence: float = 0.1      # Stored confidence score
+
+    similarity: float = 0.4  # Semantic relevance to query
+    recency: float = 0.3  # How recently the memory was validated/used
+    success_rate: float = 0.2  # Historical success rate
+    confidence: float = 0.1  # Stored confidence score
 
     def __post_init__(self):
         """Validate weights sum to approximately 1.0."""
@@ -38,6 +39,7 @@ class ScoringWeights:
 @dataclass
 class ScoredItem:
     """A memory item with its computed score."""
+
     item: Any
     score: float
     similarity_score: float
@@ -93,26 +95,28 @@ class MemoryScorer:
         similarities = similarities or [1.0] * len(heuristics)
         scored = []
 
-        for h, sim in zip(heuristics, similarities):
+        for h, sim in zip(heuristics, similarities, strict=False):
             recency = self._compute_recency_score(h.last_validated)
             success = h.success_rate
             confidence = h.confidence
 
             total = (
-                self.weights.similarity * sim +
-                self.weights.recency * recency +
-                self.weights.success_rate * success +
-                self.weights.confidence * confidence
+                self.weights.similarity * sim
+                + self.weights.recency * recency
+                + self.weights.success_rate * success
+                + self.weights.confidence * confidence
             )
 
-            scored.append(ScoredItem(
-                item=h,
-                score=total,
-                similarity_score=sim,
-                recency_score=recency,
-                success_score=success,
-                confidence_score=confidence,
-            ))
+            scored.append(
+                ScoredItem(
+                    item=h,
+                    score=total,
+                    similarity_score=sim,
+                    recency_score=recency,
+                    success_score=success,
+                    confidence_score=confidence,
+                )
+            )
 
         return sorted(scored, key=lambda x: -x.score)
 
@@ -140,7 +144,7 @@ class MemoryScorer:
         similarities = similarities or [1.0] * len(outcomes)
         scored = []
 
-        for o, sim in zip(outcomes, similarities):
+        for o, sim in zip(outcomes, similarities, strict=False):
             recency = self._compute_recency_score(o.timestamp)
             # Success gets full score, failure gets partial (still useful to learn from)
             success = 1.0 if o.success else 0.3
@@ -148,20 +152,22 @@ class MemoryScorer:
             confidence = 1.0
 
             total = (
-                self.weights.similarity * sim +
-                self.weights.recency * recency +
-                self.weights.success_rate * success +
-                self.weights.confidence * confidence
+                self.weights.similarity * sim
+                + self.weights.recency * recency
+                + self.weights.success_rate * success
+                + self.weights.confidence * confidence
             )
 
-            scored.append(ScoredItem(
-                item=o,
-                score=total,
-                similarity_score=sim,
-                recency_score=recency,
-                success_score=success,
-                confidence_score=confidence,
-            ))
+            scored.append(
+                ScoredItem(
+                    item=o,
+                    score=total,
+                    similarity_score=sim,
+                    recency_score=recency,
+                    success_score=success,
+                    confidence_score=confidence,
+                )
+            )
 
         return sorted(scored, key=lambda x: -x.score)
 
@@ -186,27 +192,29 @@ class MemoryScorer:
         similarities = similarities or [1.0] * len(knowledge)
         scored = []
 
-        for dk, sim in zip(knowledge, similarities):
+        for dk, sim in zip(knowledge, similarities, strict=False):
             recency = self._compute_recency_score(dk.last_verified)
             # Knowledge doesn't have success rate, use 1.0
             success = 1.0
             confidence = dk.confidence
 
             total = (
-                self.weights.similarity * sim +
-                self.weights.recency * recency +
-                self.weights.success_rate * success +
-                self.weights.confidence * confidence
+                self.weights.similarity * sim
+                + self.weights.recency * recency
+                + self.weights.success_rate * success
+                + self.weights.confidence * confidence
             )
 
-            scored.append(ScoredItem(
-                item=dk,
-                score=total,
-                similarity_score=sim,
-                recency_score=recency,
-                success_score=success,
-                confidence_score=confidence,
-            ))
+            scored.append(
+                ScoredItem(
+                    item=dk,
+                    score=total,
+                    similarity_score=sim,
+                    recency_score=recency,
+                    success_score=success,
+                    confidence_score=confidence,
+                )
+            )
 
         return sorted(scored, key=lambda x: -x.score)
 
@@ -233,7 +241,7 @@ class MemoryScorer:
         similarities = similarities or [1.0] * len(anti_patterns)
         scored = []
 
-        for ap, sim in zip(anti_patterns, similarities):
+        for ap, sim in zip(anti_patterns, similarities, strict=False):
             recency = self._compute_recency_score(ap.last_seen)
             # More occurrences = more important to avoid
             # Normalize occurrence count (cap at 10 for scoring)
@@ -241,20 +249,22 @@ class MemoryScorer:
             confidence = 1.0
 
             total = (
-                self.weights.similarity * sim +
-                self.weights.recency * recency +
-                self.weights.success_rate * success +
-                self.weights.confidence * confidence
+                self.weights.similarity * sim
+                + self.weights.recency * recency
+                + self.weights.success_rate * success
+                + self.weights.confidence * confidence
             )
 
-            scored.append(ScoredItem(
-                item=ap,
-                score=total,
-                similarity_score=sim,
-                recency_score=recency,
-                success_score=success,
-                confidence_score=confidence,
-            ))
+            scored.append(
+                ScoredItem(
+                    item=ap,
+                    score=total,
+                    similarity_score=sim,
+                    recency_score=recency,
+                    success_score=success,
+                    confidence_score=confidence,
+                )
+            )
 
         return sorted(scored, key=lambda x: -x.score)
 
@@ -327,8 +337,8 @@ def compute_composite_score(
     recency_score = math.pow(0.5, recency_days / recency_half_life)
 
     return (
-        weights.similarity * similarity +
-        weights.recency * recency_score +
-        weights.success_rate * success_rate +
-        weights.confidence * confidence
+        weights.similarity * similarity
+        + weights.recency * recency_score
+        + weights.success_rate * success_rate
+        + weights.confidence * confidence
     )

alma/session/__init__.py

@@ -4,12 +4,12 @@ ALMA Session Management Module.
 Handles session continuity, handoffs, and quick context reload.
 """
 
+from alma.session.manager import SessionManager
 from alma.session.types import (
-    SessionHandoff,
     SessionContext,
+    SessionHandoff,
     SessionOutcome,
 )
-from alma.session.manager import SessionManager
 
 __all__ = [
     "SessionHandoff",