alma-memory 0.2.0__py3-none-any.whl

alma/__init__.py

@@ -0,0 +1,75 @@
+"""
+ALMA - Agent Learning Memory Architecture
+
+Persistent memory system for AI agents that learn and improve over time
+through structured memory layers - without model weight updates.
+
+The Harness Pattern:
+    1. Setting - Fixed environment (tools, constraints)
+    2. Context - Ephemeral per-run inputs
+    3. Agent - The executor with scoped intelligence
+    4. Memory Schema - Domain-specific learning structure
+
+This makes any tool-using agent appear to "learn" by injecting relevant
+memory slices before each run and updating memory after.
+"""
+
+__version__ = "0.2.0"
+
+# Core
+from alma.core import ALMA
+from alma.types import (
+    Heuristic,
+    Outcome,
+    UserPreference,
+    DomainKnowledge,
+    AntiPattern,
+    MemorySlice,
+    MemoryScope,
+)
+
+# Harness Pattern
+from alma.harness.base import (
+    Setting,
+    Context,
+    Agent,
+    MemorySchema,
+    Harness,
+    Tool,
+    ToolType,
+    RunResult,
+)
+from alma.harness.domains import (
+    CodingDomain,
+    ResearchDomain,
+    ContentDomain,
+    OperationsDomain,
+    create_harness,
+)
+
+__all__ = [
+    # Core
+    "ALMA",
+    "Heuristic",
+    "Outcome",
+    "UserPreference",
+    "DomainKnowledge",
+    "AntiPattern",
+    "MemorySlice",
+    "MemoryScope",
+    # Harness Pattern
+    "Setting",
+    "Context",
+    "Agent",
+    "MemorySchema",
+    "Harness",
+    "Tool",
+    "ToolType",
+    "RunResult",
+    # Domain Configurations
+    "CodingDomain",
+    "ResearchDomain",
+    "ContentDomain",
+    "OperationsDomain",
+    "create_harness",
+]

alma/config/__init__.py

@@ -0,0 +1,5 @@
+"""ALMA Configuration."""
+
+from alma.config.loader import ConfigLoader
+
+__all__ = ["ConfigLoader"]

alma/config/loader.py

@@ -0,0 +1,156 @@
+"""
+ALMA Configuration Loader.
+
+Handles loading configuration from files and environment variables,
+with support for Azure Key Vault secret resolution.
+"""
+
+import os
+import logging
+from pathlib import Path
+from typing import Dict, Any, Optional
+
+import yaml
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigLoader:
+    """
+    Loads ALMA configuration from YAML files with environment variable expansion.
+
+    Supports:
+    - ${ENV_VAR} syntax for environment variables
+    - ${KEYVAULT:secret-name} syntax for Azure Key Vault (when configured)
+    """
+
+    _keyvault_client = None
+
+    @classmethod
+    def load(cls, config_path: str) -> Dict[str, Any]:
+        """
+        Load configuration from YAML file.
+
+        Args:
+            config_path: Path to config.yaml
+
+        Returns:
+            Parsed and expanded configuration dict
+        """
+        path = Path(config_path)
+        if not path.exists():
+            logger.warning(f"Config not found at {config_path}, using defaults")
+            return cls._get_defaults()
+
+        with open(path, "r") as f:
+            raw_config = yaml.safe_load(f)
+
+        # Get the 'alma' section or use whole file
+        config = raw_config.get("alma", raw_config)
+
+        # Expand environment variables and secrets
+        config = cls._expand_config(config)
+
+        return config
+
+    @classmethod
+    def _expand_config(cls, config: Any) -> Any:
+        """Recursively expand environment variables and secrets in config."""
+        if isinstance(config, dict):
+            return {k: cls._expand_config(v) for k, v in config.items()}
+        elif isinstance(config, list):
+            return [cls._expand_config(item) for item in config]
+        elif isinstance(config, str):
+            return cls._expand_value(config)
+        return config
+
+    @classmethod
+    def _expand_value(cls, value: str) -> str:
+        """
+        Expand a single config value.
+
+        Handles:
+        - ${ENV_VAR} -> os.environ["ENV_VAR"]
+        - ${KEYVAULT:secret-name} -> Azure Key Vault lookup
+        """
+        if not isinstance(value, str) or "${" not in value:
+            return value
+
+        # Handle ${VAR} patterns
+        import re
+        pattern = r"\$\{([^}]+)\}"
+
+        def replace(match):
+            ref = match.group(1)
+
+            if ref.startswith("KEYVAULT:"):
+                secret_name = ref[9:]  # Remove "KEYVAULT:" prefix
+                return cls._get_keyvault_secret(secret_name)
+            else:
+                # Environment variable
+                env_value = os.environ.get(ref)
+                if env_value is None:
+                    logger.warning(f"Environment variable {ref} not set")
+                    return match.group(0)  # Keep original if not found
+                return env_value
+
+        return re.sub(pattern, replace, value)
+
+    @classmethod
+    def _get_keyvault_secret(cls, secret_name: str) -> str:
+        """
+        Retrieve secret from Azure Key Vault.
+
+        Requires AZURE_KEYVAULT_URL environment variable.
+        """
+        if cls._keyvault_client is None:
+            vault_url = os.environ.get("AZURE_KEYVAULT_URL")
+            if not vault_url:
+                logger.error("AZURE_KEYVAULT_URL not set, cannot retrieve secrets")
+                return f"${{KEYVAULT:{secret_name}}}"
+
+            try:
+                from azure.identity import DefaultAzureCredential
+                from azure.keyvault.secrets import SecretClient
+
+                credential = DefaultAzureCredential()
+                cls._keyvault_client = SecretClient(
+                    vault_url=vault_url,
+                    credential=credential,
+                )
+            except ImportError:
+                logger.error(
+                    "azure-identity and azure-keyvault-secrets packages required "
+                    "for Key Vault integration"
+                )
+                return f"${{KEYVAULT:{secret_name}}}"
+
+        try:
+            secret = cls._keyvault_client.get_secret(secret_name)
+            return secret.value
+        except Exception as e:
+            logger.error(f"Failed to retrieve secret {secret_name}: {e}")
+            return f"${{KEYVAULT:{secret_name}}}"
+
+    @staticmethod
+    def _get_defaults() -> Dict[str, Any]:
+        """Return default configuration."""
+        return {
+            "project_id": "default",
+            "storage": "file",
+            "embedding_provider": "local",
+            "agents": {},
+        }
+
+    @classmethod
+    def save(cls, config: Dict[str, Any], config_path: str):
+        """
+        Save configuration to YAML file.
+
+        Note: Does NOT save secrets - those should remain as ${} references.
+        """
+        path = Path(config_path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(path, "w") as f:
+            yaml.dump({"alma": config}, f, default_flow_style=False)

alma/core.py

@@ -0,0 +1,322 @@
+"""
+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 alma.types import (
+    MemorySlice,
+    MemoryScope,
+    Heuristic,
+    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__)
+
+
+class ALMA:
+    """
+    Agent Learning Memory Architecture - Main Interface.
+
+    Provides methods for:
+    - Retrieving relevant memories for a task
+    - Learning from task outcomes
+    - Managing agent memory scopes
+    """
+
+    def __init__(
+        self,
+        storage: StorageBackend,
+        retrieval_engine: RetrievalEngine,
+        learning_protocol: LearningProtocol,
+        scopes: Dict[str, MemoryScope],
+        project_id: str,
+    ):
+        self.storage = storage
+        self.retrieval = retrieval_engine
+        self.learning = learning_protocol
+        self.scopes = scopes
+        self.project_id = project_id
+
+    @classmethod
+    def from_config(cls, config_path: str) -> "ALMA":
+        """
+        Initialize ALMA from a configuration file.
+
+        Args:
+            config_path: Path to .alma/config.yaml
+
+        Returns:
+            Configured ALMA instance
+        """
+        config = ConfigLoader.load(config_path)
+
+        # Initialize storage backend based on config
+        storage = cls._create_storage(config)
+
+        # Initialize retrieval engine
+        retrieval = RetrievalEngine(
+            storage=storage,
+            embedding_provider=config.get("embedding_provider", "local"),
+        )
+
+        # Initialize learning protocol
+        learning = LearningProtocol(
+            storage=storage,
+            scopes={
+                name: MemoryScope(
+                    agent_name=name,
+                    can_learn=scope.get("can_learn", []),
+                    cannot_learn=scope.get("cannot_learn", []),
+                    min_occurrences_for_heuristic=scope.get(
+                        "min_occurrences_for_heuristic", 3
+                    ),
+                )
+                for name, scope in config.get("agents", {}).items()
+            },
+        )
+
+        # Build scopes dict
+        scopes = {
+            name: MemoryScope(
+                agent_name=name,
+                can_learn=scope.get("can_learn", []),
+                cannot_learn=scope.get("cannot_learn", []),
+                min_occurrences_for_heuristic=scope.get(
+                    "min_occurrences_for_heuristic", 3
+                ),
+            )
+            for name, scope in config.get("agents", {}).items()
+        }
+
+        return cls(
+            storage=storage,
+            retrieval_engine=retrieval,
+            learning_protocol=learning,
+            scopes=scopes,
+            project_id=config.get("project_id", "default"),
+        )
+
+    @staticmethod
+    def _create_storage(config: Dict[str, Any]) -> StorageBackend:
+        """Create appropriate storage backend based on config."""
+        storage_type = config.get("storage", "file")
+
+        if storage_type == "azure":
+            from alma.storage.azure_cosmos import AzureCosmosStorage
+            return AzureCosmosStorage.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(
+        self,
+        task: str,
+        agent: str,
+        user_id: Optional[str] = None,
+        top_k: int = 5,
+    ) -> MemorySlice:
+        """
+        Retrieve relevant memories for a task.
+
+        Args:
+            task: Description of the task to perform
+            agent: Name of the agent requesting memories
+            user_id: Optional user ID for preference retrieval
+            top_k: Maximum items per memory type
+
+        Returns:
+            MemorySlice with relevant memories for context injection
+        """
+        # Validate agent has a defined scope
+        if agent not in self.scopes:
+            logger.warning(f"Agent '{agent}' has no defined scope, using defaults")
+
+        return self.retrieval.retrieve(
+            query=task,
+            agent=agent,
+            project_id=self.project_id,
+            user_id=user_id,
+            top_k=top_k,
+            scope=self.scopes.get(agent),
+        )
+
+    def learn(
+        self,
+        agent: str,
+        task: str,
+        outcome: str,  # "success" or "failure"
+        strategy_used: str,
+        task_type: Optional[str] = None,
+        duration_ms: Optional[int] = None,
+        error_message: Optional[str] = None,
+        feedback: Optional[str] = None,
+    ) -> bool:
+        """
+        Learn from a task outcome.
+
+        Validates that learning is within agent's scope before committing.
+        Invalidates cache after learning to ensure fresh retrieval results.
+
+        Args:
+            agent: Name of the agent that executed the task
+            task: Description of the task
+            outcome: "success" or "failure"
+            strategy_used: What approach was taken
+            task_type: Category of task (for grouping)
+            duration_ms: How long the task took
+            error_message: Error details if failed
+            feedback: User feedback if provided
+
+        Returns:
+            True if learning was accepted, False if rejected (scope violation)
+        """
+        result = self.learning.learn(
+            agent=agent,
+            project_id=self.project_id,
+            task=task,
+            outcome=outcome == "success",
+            strategy_used=strategy_used,
+            task_type=task_type,
+            duration_ms=duration_ms,
+            error_message=error_message,
+            feedback=feedback,
+        )
+
+        # Invalidate cache for this agent/project after learning
+        if result:
+            self.retrieval.invalidate_cache(agent=agent, project_id=self.project_id)
+
+        return result
+
+    def add_user_preference(
+        self,
+        user_id: str,
+        category: str,
+        preference: str,
+        source: str = "explicit_instruction",
+    ) -> UserPreference:
+        """
+        Add a user preference to memory.
+
+        Args:
+            user_id: User identifier
+            category: Category (communication, code_style, workflow)
+            preference: The preference text
+            source: How this was learned
+
+        Returns:
+            The created UserPreference
+        """
+        result = self.learning.add_preference(
+            user_id=user_id,
+            category=category,
+            preference=preference,
+            source=source,
+        )
+
+        # Invalidate cache for project (user preferences affect all agents)
+        self.retrieval.invalidate_cache(project_id=self.project_id)
+
+        return result
+
+    def add_domain_knowledge(
+        self,
+        agent: str,
+        domain: str,
+        fact: str,
+        source: str = "user_stated",
+    ) -> Optional[DomainKnowledge]:
+        """
+        Add domain knowledge within agent's scope.
+
+        Args:
+            agent: Agent this knowledge belongs to
+            domain: Knowledge domain
+            fact: The fact to remember
+            source: How this was learned
+
+        Returns:
+            The created DomainKnowledge or None if scope violation
+        """
+        # 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}'"
+            )
+            return None
+
+        result = self.learning.add_domain_knowledge(
+            agent=agent,
+            project_id=self.project_id,
+            domain=domain,
+            fact=fact,
+            source=source,
+        )
+
+        # Invalidate cache for this agent/project after adding knowledge
+        if result:
+            self.retrieval.invalidate_cache(agent=agent, project_id=self.project_id)
+
+        return result
+
+    def forget(
+        self,
+        agent: Optional[str] = None,
+        older_than_days: int = 90,
+        below_confidence: float = 0.3,
+    ) -> int:
+        """
+        Prune stale or low-confidence memories.
+
+        Invalidates cache after pruning to ensure fresh retrieval results.
+
+        Args:
+            agent: Specific agent to prune, or None for all
+            older_than_days: Remove outcomes older than this
+            below_confidence: Remove heuristics below this confidence
+
+        Returns:
+            Number of items pruned
+        """
+        count = self.learning.forget(
+            project_id=self.project_id,
+            agent=agent,
+            older_than_days=older_than_days,
+            below_confidence=below_confidence,
+        )
+
+        # Invalidate cache after forgetting (memories were removed)
+        if count > 0:
+            self.retrieval.invalidate_cache(agent=agent, project_id=self.project_id)
+
+        return count
+
+    def get_stats(self, agent: Optional[str] = None) -> Dict[str, Any]:
+        """
+        Get memory statistics.
+
+        Args:
+            agent: Specific agent or None for all
+
+        Returns:
+            Dict with counts and metadata
+        """
+        return self.storage.get_stats(
+            project_id=self.project_id,
+            agent=agent,
+        )

alma/harness/__init__.py

@@ -0,0 +1,35 @@
+"""
+ALMA Harness Pattern.
+
+A structured framework for creating learning agents across any domain:
+- Setting: Environment, tools, constraints
+- Context: Task-specific inputs per run
+- Agent: The executor with scoped intelligence
+- Memory Schema: Domain-specific persistent learning
+"""
+
+from alma.harness.base import (
+    Setting,
+    Context,
+    Agent,
+    MemorySchema,
+    Harness,
+)
+from alma.harness.domains import (
+    CodingDomain,
+    ResearchDomain,
+    ContentDomain,
+    OperationsDomain,
+)
+
+__all__ = [
+    "Setting",
+    "Context",
+    "Agent",
+    "MemorySchema",
+    "Harness",
+    "CodingDomain",
+    "ResearchDomain",
+    "ContentDomain",
+    "OperationsDomain",
+]