alma-memory 0.2.0__py3-none-any.whl

alma/learning/validation.py

@@ -0,0 +1,341 @@
+"""
+ALMA Learning Validation.
+
+Enforces scope constraints and validates learning requests.
+"""
+
+import logging
+from typing import Optional, List, Dict, Any, Set
+from dataclasses import dataclass, field
+from enum import Enum
+
+from alma.types import MemoryScope
+
+logger = logging.getLogger(__name__)
+
+
+class ValidationResult(Enum):
+    """Result of a validation check."""
+    ALLOWED = "allowed"
+    DENIED_OUT_OF_SCOPE = "denied_out_of_scope"
+    DENIED_FORBIDDEN = "denied_forbidden"
+    DENIED_UNKNOWN_AGENT = "denied_unknown_agent"
+    WARNING_NO_SCOPE = "warning_no_scope"
+
+
+@dataclass
+class ValidationReport:
+    """Detailed report of a validation check."""
+    result: ValidationResult
+    agent: str
+    domain: str
+    reason: str
+    allowed_domains: List[str] = field(default_factory=list)
+    forbidden_domains: List[str] = field(default_factory=list)
+
+    @property
+    def is_allowed(self) -> bool:
+        """Check if the validation passed."""
+        return self.result in (ValidationResult.ALLOWED, ValidationResult.WARNING_NO_SCOPE)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {
+            "result": self.result.value,
+            "agent": self.agent,
+            "domain": self.domain,
+            "reason": self.reason,
+            "is_allowed": self.is_allowed,
+            "allowed_domains": self.allowed_domains,
+            "forbidden_domains": self.forbidden_domains,
+        }
+
+
+class ScopeValidator:
+    """
+    Validates that learning requests are within agent scope.
+
+    Provides strict enforcement with detailed reporting.
+    """
+
+    def __init__(
+        self,
+        scopes: Dict[str, MemoryScope],
+        strict_mode: bool = True,
+        allow_unknown_agents: bool = False,
+    ):
+        """
+        Initialize validator.
+
+        Args:
+            scopes: Dict of agent_name -> MemoryScope
+            strict_mode: If True, deny requests for unknown domains
+            allow_unknown_agents: If True, allow learning for agents without scopes
+        """
+        self.scopes = scopes
+        self.strict_mode = strict_mode
+        self.allow_unknown_agents = allow_unknown_agents
+
+        # Track validation statistics
+        self._stats = {
+            "total_validations": 0,
+            "allowed": 0,
+            "denied": 0,
+            "warnings": 0,
+        }
+
+    def validate(
+        self,
+        agent: str,
+        domain: str,
+        task_type: Optional[str] = None,
+    ) -> ValidationReport:
+        """
+        Validate a learning request.
+
+        Args:
+            agent: Agent attempting to learn
+            domain: Knowledge domain to learn in
+            task_type: Optional task type for context
+
+        Returns:
+            ValidationReport with detailed results
+        """
+        self._stats["total_validations"] += 1
+
+        # Check if agent has a scope
+        scope = self.scopes.get(agent)
+
+        if scope is None:
+            if self.allow_unknown_agents:
+                self._stats["warnings"] += 1
+                logger.warning(f"Agent '{agent}' has no defined scope, allowing anyway")
+                return ValidationReport(
+                    result=ValidationResult.WARNING_NO_SCOPE,
+                    agent=agent,
+                    domain=domain,
+                    reason=f"Agent '{agent}' has no defined scope",
+                )
+            else:
+                self._stats["denied"] += 1
+                logger.warning(f"Agent '{agent}' denied: no scope defined")
+                return ValidationReport(
+                    result=ValidationResult.DENIED_UNKNOWN_AGENT,
+                    agent=agent,
+                    domain=domain,
+                    reason=f"Agent '{agent}' has no defined scope and unknown agents are not allowed",
+                )
+
+        # Check if domain is explicitly forbidden
+        if domain in scope.cannot_learn:
+            self._stats["denied"] += 1
+            logger.warning(
+                f"Agent '{agent}' denied learning in '{domain}': explicitly forbidden"
+            )
+            return ValidationReport(
+                result=ValidationResult.DENIED_FORBIDDEN,
+                agent=agent,
+                domain=domain,
+                reason=f"Domain '{domain}' is explicitly forbidden for agent '{agent}'",
+                allowed_domains=scope.can_learn,
+                forbidden_domains=scope.cannot_learn,
+            )
+
+        # Check if domain is in allowed list
+        if scope.can_learn:  # If list is not empty, it's an allowlist
+            if domain not in scope.can_learn:
+                # Check for partial matches (e.g., "form_testing" contains "testing")
+                partial_match = any(
+                    allowed in domain or domain in allowed
+                    for allowed in scope.can_learn
+                )
+
+                if not partial_match and self.strict_mode:
+                    self._stats["denied"] += 1
+                    logger.warning(
+                        f"Agent '{agent}' denied learning in '{domain}': not in allowed list"
+                    )
+                    return ValidationReport(
+                        result=ValidationResult.DENIED_OUT_OF_SCOPE,
+                        agent=agent,
+                        domain=domain,
+                        reason=f"Domain '{domain}' is not in agent '{agent}'s allowed domains",
+                        allowed_domains=scope.can_learn,
+                        forbidden_domains=scope.cannot_learn,
+                    )
+
+        # Allowed
+        self._stats["allowed"] += 1
+        return ValidationReport(
+            result=ValidationResult.ALLOWED,
+            agent=agent,
+            domain=domain,
+            reason="Learning allowed",
+            allowed_domains=scope.can_learn,
+            forbidden_domains=scope.cannot_learn,
+        )
+
+    def validate_batch(
+        self,
+        agent: str,
+        domains: List[str],
+    ) -> Dict[str, ValidationReport]:
+        """
+        Validate multiple domains at once.
+
+        Args:
+            agent: Agent attempting to learn
+            domains: List of domains to validate
+
+        Returns:
+            Dict of domain -> ValidationReport
+        """
+        return {domain: self.validate(agent, domain) for domain in domains}
+
+    def get_allowed_domains(self, agent: str) -> Set[str]:
+        """Get all allowed domains for an agent."""
+        scope = self.scopes.get(agent)
+        if scope is None:
+            return set()
+        return set(scope.can_learn)
+
+    def get_forbidden_domains(self, agent: str) -> Set[str]:
+        """Get all forbidden domains for an agent."""
+        scope = self.scopes.get(agent)
+        if scope is None:
+            return set()
+        return set(scope.cannot_learn)
+
+    def is_allowed(self, agent: str, domain: str) -> bool:
+        """Quick check if learning is allowed (no detailed report)."""
+        return self.validate(agent, domain).is_allowed
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get validation statistics."""
+        total = self._stats["total_validations"]
+        return {
+            **self._stats,
+            "allow_rate": self._stats["allowed"] / total if total > 0 else 0,
+            "deny_rate": self._stats["denied"] / total if total > 0 else 0,
+        }
+
+    def reset_stats(self):
+        """Reset validation statistics."""
+        self._stats = {
+            "total_validations": 0,
+            "allowed": 0,
+            "denied": 0,
+            "warnings": 0,
+        }
+
+
+class TaskTypeValidator:
+    """
+    Validates and normalizes task types.
+
+    Ensures consistent categorization across learning events.
+    """
+
+    # Standard task type categories
+    STANDARD_TYPES = {
+        "testing": ["test", "validate", "verify", "check", "qa"],
+        "form_testing": ["form", "input", "field", "validation"],
+        "api_testing": ["api", "endpoint", "rest", "graphql", "request"],
+        "database_validation": ["database", "query", "sql", "schema"],
+        "ui_testing": ["ui", "component", "button", "click", "element"],
+        "performance_testing": ["performance", "load", "stress", "speed"],
+        "security_testing": ["security", "auth", "permission", "xss", "injection"],
+        "accessibility_testing": ["accessibility", "a11y", "aria", "screen reader"],
+    }
+
+    def __init__(self, custom_types: Optional[Dict[str, List[str]]] = None):
+        """
+        Initialize validator.
+
+        Args:
+            custom_types: Additional custom type mappings
+        """
+        self.type_mappings = {**self.STANDARD_TYPES}
+        if custom_types:
+            self.type_mappings.update(custom_types)
+
+        # Build reverse lookup
+        self._keyword_to_type: Dict[str, str] = {}
+        for task_type, keywords in self.type_mappings.items():
+            for keyword in keywords:
+                self._keyword_to_type[keyword.lower()] = task_type
+
+    def infer_type(self, task_description: str) -> str:
+        """
+        Infer task type from description.
+
+        Args:
+            task_description: Description of the task
+
+        Returns:
+            Inferred task type or "general"
+        """
+        task_lower = task_description.lower()
+
+        # Check for keyword matches
+        scores: Dict[str, int] = {}
+        for task_type, keywords in self.type_mappings.items():
+            score = sum(1 for kw in keywords if kw in task_lower)
+            if score > 0:
+                scores[task_type] = score
+
+        if scores:
+            # Return the type with highest score
+            return max(scores.keys(), key=lambda k: scores[k])
+
+        return "general"
+
+    def normalize_type(self, task_type: str) -> str:
+        """
+        Normalize a task type to standard category.
+
+        Args:
+            task_type: Raw task type
+
+        Returns:
+            Normalized task type
+        """
+        type_lower = task_type.lower().replace("_", " ").replace("-", " ")
+
+        # Check direct match
+        if type_lower in self.type_mappings:
+            return type_lower
+
+        # Check keyword lookup
+        for word in type_lower.split():
+            if word in self._keyword_to_type:
+                return self._keyword_to_type[word]
+
+        return task_type  # Return original if no match
+
+    def validate_type(self, task_type: str) -> bool:
+        """Check if task type is recognized."""
+        normalized = self.normalize_type(task_type)
+        return normalized in self.type_mappings or task_type == "general"
+
+
+def validate_learning_request(
+    agent: str,
+    domain: str,
+    scopes: Dict[str, MemoryScope],
+    strict: bool = True,
+) -> ValidationReport:
+    """
+    Convenience function for one-off validation.
+
+    Args:
+        agent: Agent attempting to learn
+        domain: Knowledge domain
+        scopes: Dict of agent scopes
+        strict: Use strict mode
+
+    Returns:
+        ValidationReport
+    """
+    validator = ScopeValidator(scopes, strict_mode=strict)
+    return validator.validate(agent, domain)

alma/mcp/__init__.py

@@ -0,0 +1,45 @@
+"""
+ALMA MCP Server Module.
+
+Exposes ALMA functionality to any Claude Code instance via the
+Model Context Protocol (MCP).
+
+Usage:
+    # stdio mode (for Claude Code integration)
+    python -m alma.mcp --config .alma/config.yaml
+
+    # HTTP mode (for remote access)
+    python -m alma.mcp --http --port 8765
+
+Integration with Claude Code (.mcp.json):
+    {
+        "mcpServers": {
+            "alma-memory": {
+                "command": "python",
+                "args": ["-m", "alma.mcp", "--config", ".alma/config.yaml"]
+            }
+        }
+    }
+"""
+
+from alma.mcp.server import ALMAMCPServer
+from alma.mcp.tools import (
+    alma_retrieve,
+    alma_learn,
+    alma_add_preference,
+    alma_add_knowledge,
+    alma_forget,
+    alma_stats,
+    alma_health,
+)
+
+__all__ = [
+    "ALMAMCPServer",
+    "alma_retrieve",
+    "alma_learn",
+    "alma_add_preference",
+    "alma_add_knowledge",
+    "alma_forget",
+    "alma_stats",
+    "alma_health",
+]

alma/mcp/__main__.py

@@ -0,0 +1,155 @@
+"""
+ALMA MCP Server CLI Entry Point.
+
+Usage:
+    # stdio mode (for Claude Code)
+    python -m alma.mcp --config .alma/config.yaml
+
+    # HTTP mode (for remote access)
+    python -m alma.mcp --http --port 8765
+
+    # With verbose logging
+    python -m alma.mcp --config .alma/config.yaml --verbose
+"""
+
+import argparse
+import asyncio
+import logging
+import sys
+from pathlib import Path
+
+from alma import ALMA
+from alma.mcp.server import ALMAMCPServer
+
+
+def setup_logging(verbose: bool = False):
+    """Configure logging."""
+    level = logging.DEBUG if verbose else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        stream=sys.stderr,  # Log to stderr to avoid interfering with stdio
+    )
+
+
+def main():
+    """Main entry point."""
+    parser = argparse.ArgumentParser(
+        description="ALMA MCP Server - Memory for AI Agents",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+    # Start in stdio mode for Claude Code
+    python -m alma.mcp --config .alma/config.yaml
+
+    # Start in HTTP mode on port 8765
+    python -m alma.mcp --http --port 8765
+
+    # Use with verbose logging
+    python -m alma.mcp --config .alma/config.yaml --verbose
+        """,
+    )
+
+    parser.add_argument(
+        "--config",
+        type=str,
+        default=".alma/config.yaml",
+        help="Path to ALMA config file (default: .alma/config.yaml)",
+    )
+
+    parser.add_argument(
+        "--http",
+        action="store_true",
+        help="Run in HTTP mode instead of stdio",
+    )
+
+    parser.add_argument(
+        "--host",
+        type=str,
+        default="0.0.0.0",
+        help="HTTP server host (default: 0.0.0.0)",
+    )
+
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=8765,
+        help="HTTP server port (default: 8765)",
+    )
+
+    parser.add_argument(
+        "--verbose", "-v",
+        action="store_true",
+        help="Enable verbose logging",
+    )
+
+    args = parser.parse_args()
+
+    # Setup logging
+    setup_logging(args.verbose)
+    logger = logging.getLogger(__name__)
+
+    # Load ALMA from config
+    config_path = Path(args.config)
+    if not config_path.exists():
+        logger.error(f"Config file not found: {config_path}")
+        logger.info("Creating default config...")
+
+        # Create minimal default config
+        config_path.parent.mkdir(parents=True, exist_ok=True)
+        with open(config_path, "w") as f:
+            f.write("""# ALMA Configuration
+alma:
+  project_id: "default"
+  storage: "file"
+  storage_dir: ".alma"
+  embedding_provider: "local"
+
+  agents:
+    helena:
+      can_learn:
+        - testing_strategies
+        - selector_patterns
+        - form_testing
+        - accessibility_testing
+      cannot_learn:
+        - backend_logic
+        - database_queries
+      min_occurrences_for_heuristic: 3
+
+    victor:
+      can_learn:
+        - api_design_patterns
+        - authentication_patterns
+        - error_handling
+        - database_query_patterns
+      cannot_learn:
+        - frontend_styling
+        - ui_testing
+      min_occurrences_for_heuristic: 3
+""")
+        logger.info(f"Created default config at {config_path}")
+
+    try:
+        alma = ALMA.from_config(str(config_path))
+        logger.info(f"Loaded ALMA from {config_path}")
+        logger.info(f"Project: {alma.project_id}")
+        logger.info(f"Agents: {list(alma.scopes.keys())}")
+
+    except Exception as e:
+        logger.exception(f"Failed to load ALMA: {e}")
+        sys.exit(1)
+
+    # Create and run server
+    server = ALMAMCPServer(alma=alma)
+
+    if args.http:
+        logger.info(f"Starting HTTP server on {args.host}:{args.port}")
+        asyncio.run(server.run_http(host=args.host, port=args.port))
+    else:
+        logger.info("Starting stdio server for Claude Code integration")
+        asyncio.run(server.run_stdio())
+
+
+if __name__ == "__main__":
+    main()

alma/mcp/resources.py

@@ -0,0 +1,121 @@
+"""
+ALMA MCP Resource Definitions.
+
+Provides read-only resources that can be accessed via MCP protocol.
+Resources represent configuration and metadata about the ALMA instance.
+"""
+
+import logging
+from typing import Dict, Any, List
+
+from alma import ALMA
+from alma.types import MemoryScope
+
+logger = logging.getLogger(__name__)
+
+
+def get_config_resource(alma: ALMA) -> Dict[str, Any]:
+    """
+    Get current ALMA configuration as a resource.
+
+    This exposes non-sensitive configuration information about
+    the ALMA instance.
+
+    Args:
+        alma: ALMA instance
+
+    Returns:
+        Dict with configuration details
+    """
+    return {
+        "uri": "alma://config",
+        "name": "ALMA Configuration",
+        "description": "Current configuration of the ALMA memory system",
+        "mimeType": "application/json",
+        "content": {
+            "project_id": alma.project_id,
+            "storage_type": type(alma.storage).__name__,
+            "registered_agents": list(alma.scopes.keys()),
+            "scopes": {
+                name: {
+                    "can_learn": scope.can_learn,
+                    "cannot_learn": scope.cannot_learn,
+                    "min_occurrences_for_heuristic": scope.min_occurrences_for_heuristic,
+                }
+                for name, scope in alma.scopes.items()
+            },
+        },
+    }
+
+
+def get_agents_resource(alma: ALMA) -> Dict[str, Any]:
+    """
+    Get registered agents and their scopes as a resource.
+
+    This provides detailed information about each registered agent
+    and their learning permissions.
+
+    Args:
+        alma: ALMA instance
+
+    Returns:
+        Dict with agent details
+    """
+    agents = []
+
+    for name, scope in alma.scopes.items():
+        # Get stats for this agent
+        try:
+            stats = alma.get_stats(agent=name)
+        except Exception:
+            stats = {}
+
+        agents.append({
+            "name": name,
+            "scope": {
+                "can_learn": scope.can_learn,
+                "cannot_learn": scope.cannot_learn,
+                "min_occurrences_for_heuristic": scope.min_occurrences_for_heuristic,
+            },
+            "stats": {
+                "heuristics_count": stats.get("heuristics_count", 0),
+                "outcomes_count": stats.get("outcomes_count", 0),
+                "domain_knowledge_count": stats.get("domain_knowledge_count", 0),
+                "anti_patterns_count": stats.get("anti_patterns_count", 0),
+            },
+        })
+
+    return {
+        "uri": "alma://agents",
+        "name": "ALMA Registered Agents",
+        "description": "All registered agents and their memory scopes",
+        "mimeType": "application/json",
+        "content": {
+            "project_id": alma.project_id,
+            "agent_count": len(agents),
+            "agents": agents,
+        },
+    }
+
+
+def list_resources() -> List[Dict[str, Any]]:
+    """
+    List all available resources.
+
+    Returns:
+        List of resource descriptors
+    """
+    return [
+        {
+            "uri": "alma://config",
+            "name": "ALMA Configuration",
+            "description": "Current configuration of the ALMA memory system",
+            "mimeType": "application/json",
+        },
+        {
+            "uri": "alma://agents",
+            "name": "ALMA Registered Agents",
+            "description": "All registered agents and their memory scopes",
+            "mimeType": "application/json",
+        },
+    ]