claude-mpm 3.9.11__py3-none-any.whl → 4.0.3__py3-none-any.whl

claude_mpm/core/unified_agent_registry.py

@@ -0,0 +1,721 @@
+#!/usr/bin/env python3
+"""
+Unified Agent Registry System for Claude MPM
+============================================
+
+This module consolidates all agent registry functionality from the duplicate modules:
+- core/agent_registry.py (AgentRegistryAdapter and legacy functions)
+- services/agents/registry/agent_registry.py (Full-featured AgentRegistry)
+- agents/core/agent_registry.py (Core AgentRegistry with memory integration)
+
+Design Principles:
+- Single source of truth for agent discovery and management
+- Consistent API across all agent operations
+- Hierarchical tier system (PROJECT > USER > SYSTEM)
+- Memory-aware agent creation
+- Efficient caching with smart invalidation
+- Comprehensive metadata management
+- Backward compatibility during migration
+
+Architecture:
+- UnifiedAgentRegistry: Main registry class
+- AgentMetadata: Standardized agent metadata model
+- AgentTier: Hierarchical precedence system
+- AgentType: Agent classification system
+- Discovery engine with tier-based precedence
+"""
+
+import json
+import logging
+import time
+from dataclasses import asdict, dataclass
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Set, Union
+
+from .unified_paths import get_path_manager
+
+logger = logging.getLogger(__name__)
+
+
+class AgentTier(Enum):
+    """Agent tier hierarchy for precedence resolution."""
+
+    PROJECT = "project"  # Highest precedence
+    USER = "user"  # Medium precedence
+    SYSTEM = "system"  # Lowest precedence
+
+
+class AgentType(Enum):
+    """Agent type classification."""
+
+    CORE = "core"  # Core framework agents
+    SPECIALIZED = "specialized"  # Specialized domain agents
+    USER_DEFINED = "user_defined"  # User-created agents
+    PROJECT = "project"  # Project-specific agents
+    MEMORY_AWARE = "memory_aware"  # Memory-enhanced agents
+
+
+class AgentFormat(Enum):
+    """Supported agent file formats."""
+
+    MARKDOWN = "markdown"
+    JSON = "json"
+    YAML = "yaml"
+
+
+@dataclass
+class AgentMetadata:
+    """Standardized agent metadata model."""
+
+    name: str
+    agent_type: AgentType
+    tier: AgentTier
+    path: str
+    format: AgentFormat
+    last_modified: float
+    description: str = ""
+    specializations: List[str] = None
+    memory_files: List[str] = None
+    dependencies: List[str] = None
+    version: str = "1.0.0"
+    author: str = ""
+    tags: List[str] = None
+
+    def __post_init__(self):
+        """Initialize default values for mutable fields."""
+        if self.specializations is None:
+            self.specializations = []
+        if self.memory_files is None:
+            self.memory_files = []
+        if self.dependencies is None:
+            self.dependencies = []
+        if self.tags is None:
+            self.tags = []
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary representation."""
+        data = asdict(self)
+        data["agent_type"] = self.agent_type.value
+        data["tier"] = self.tier.value
+        data["format"] = self.format.value
+        return data
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "AgentMetadata":
+        """Create from dictionary representation."""
+        data["agent_type"] = AgentType(data["agent_type"])
+        data["tier"] = AgentTier(data["tier"])
+        data["format"] = AgentFormat(data["format"])
+        return cls(**data)
+
+
+class UnifiedAgentRegistry:
+    """
+    Unified agent registry system that consolidates all agent-related functionality.
+
+    This class provides a single, authoritative interface for all agent operations
+    in Claude MPM, replacing the multiple duplicate agent registry modules.
+    """
+
+    def __init__(self, cache_enabled: bool = True, cache_ttl: int = 3600):
+        """Initialize the unified agent registry."""
+        self.path_manager = get_path_manager()
+
+        # Registry storage
+        self.registry: Dict[str, AgentMetadata] = {}
+        self.discovery_paths: List[Path] = []
+        self.discovered_files: Set[Path] = set()
+
+        # Cache configuration
+        self.cache_enabled = cache_enabled
+        self.cache_ttl = cache_ttl
+        self.cache_prefix = "unified_agent_registry"
+
+        # Discovery configuration
+        self.file_extensions = {".md", ".json", ".yaml", ".yml"}
+        self.ignore_patterns = {"__pycache__", ".git", "node_modules", ".pytest_cache"}
+
+        # Statistics
+        self.discovery_stats = {
+            "last_discovery": None,
+            "total_discovered": 0,
+            "cache_hits": 0,
+            "cache_misses": 0,
+            "discovery_duration": 0.0,
+        }
+
+        # Setup discovery paths
+        self._setup_discovery_paths()
+
+        logger.info(
+            f"UnifiedAgentRegistry initialized with cache={'enabled' if cache_enabled else 'disabled'}"
+        )
+
+    def _setup_discovery_paths(self) -> None:
+        """Setup standard discovery paths for agent files."""
+        # Project-level agents (highest priority)
+        project_path = self.path_manager.get_project_agents_dir()
+        if project_path.exists():
+            self.discovery_paths.append(project_path)
+
+        # User-level agents
+        user_path = self.path_manager.get_user_agents_dir()
+        if user_path.exists():
+            self.discovery_paths.append(user_path)
+
+        # System-level agents
+        system_path = self.path_manager.get_system_agents_dir()
+        if system_path.exists():
+            self.discovery_paths.append(system_path)
+
+        # Templates directory
+        templates_path = self.path_manager.get_templates_dir()
+        if templates_path.exists():
+            self.discovery_paths.append(templates_path)
+
+        logger.debug(
+            f"Discovery paths configured: {[str(p) for p in self.discovery_paths]}"
+        )
+
+    def discover_agents(self, force_refresh: bool = False) -> Dict[str, AgentMetadata]:
+        """
+        Discover all agents from configured paths with tier precedence.
+
+        Args:
+            force_refresh: Force re-discovery even if cache is valid
+
+        Returns:
+            Dictionary mapping agent names to their metadata
+        """
+        start_time = time.time()
+
+        # Check cache first (if enabled and not forcing refresh)
+        if self.cache_enabled and not force_refresh and self._is_cache_valid():
+            self.discovery_stats["cache_hits"] += 1
+            logger.debug("Using cached agent registry")
+            return self.registry
+
+        self.discovery_stats["cache_misses"] += 1
+
+        # Clear existing registry and discovered files
+        self.registry.clear()
+        self.discovered_files.clear()
+
+        # Discover agents from all paths
+        for discovery_path in self.discovery_paths:
+            tier = self._determine_tier(discovery_path)
+            self._discover_path(discovery_path, tier)
+
+        # Handle tier precedence
+        self._apply_tier_precedence()
+
+        # Discover and integrate memory files
+        self._discover_memory_integration()
+
+        # Cache the results
+        if self.cache_enabled:
+            self._cache_registry()
+
+        # Update statistics
+        self.discovery_stats["last_discovery"] = time.time()
+        self.discovery_stats["total_discovered"] = len(self.registry)
+        self.discovery_stats["discovery_duration"] = time.time() - start_time
+
+        logger.info(
+            f"Discovered {len(self.registry)} agents in {self.discovery_stats['discovery_duration']:.2f}s"
+        )
+
+        return self.registry
+
+    def _discover_path(self, path: Path, tier: AgentTier) -> None:
+        """Discover agents in a specific path."""
+        if not path.exists():
+            return
+
+        for file_path in path.rglob("*"):
+            # Skip directories and ignored patterns
+            if file_path.is_dir():
+                continue
+
+            if any(pattern in str(file_path) for pattern in self.ignore_patterns):
+                continue
+
+            # Check file extension
+            if file_path.suffix not in self.file_extensions:
+                continue
+
+            # Extract agent name
+            agent_name = self._extract_agent_name(file_path)
+            if not agent_name:
+                continue
+
+            # Create agent metadata
+            try:
+                metadata = self._create_agent_metadata(file_path, agent_name, tier)
+                if metadata:
+                    self.registry[agent_name] = metadata
+                    self.discovered_files.add(file_path)
+                    logger.debug(
+                        f"Discovered agent: {agent_name} ({tier.value}) at {file_path}"
+                    )
+            except Exception as e:
+                logger.warning(f"Failed to process agent file {file_path}: {e}")
+
+    def _extract_agent_name(self, file_path: Path) -> Optional[str]:
+        """Extract agent name from file path."""
+        # Remove extension and use filename as agent name
+        name = file_path.stem
+
+        # Skip certain files
+        skip_files = {"README", "INSTRUCTIONS", "template", "example"}
+        if name.upper() in skip_files:
+            return None
+
+        # Normalize name
+        return name.lower().replace("-", "_").replace(" ", "_")
+
+    def _create_agent_metadata(
+        self, file_path: Path, agent_name: str, tier: AgentTier
+    ) -> Optional[AgentMetadata]:
+        """Create agent metadata from file."""
+        try:
+            # Determine format
+            format_map = {
+                ".md": AgentFormat.MARKDOWN,
+                ".json": AgentFormat.JSON,
+                ".yaml": AgentFormat.YAML,
+                ".yml": AgentFormat.YAML,
+            }
+            agent_format = format_map.get(file_path.suffix, AgentFormat.MARKDOWN)
+
+            # Determine agent type
+            agent_type = self._determine_agent_type(file_path, tier)
+
+            # Extract metadata from file content
+            description, specializations = self._extract_file_metadata(
+                file_path, agent_format
+            )
+
+            return AgentMetadata(
+                name=agent_name,
+                agent_type=agent_type,
+                tier=tier,
+                path=str(file_path),
+                format=agent_format,
+                last_modified=file_path.stat().st_mtime,
+                description=description,
+                specializations=specializations,
+            )
+
+        except Exception as e:
+            logger.error(f"Failed to create metadata for {file_path}: {e}")
+            return None
+
+    def _determine_tier(self, path: Path) -> AgentTier:
+        """Determine agent tier based on path."""
+        path_str = str(path)
+
+        if (
+            "project" in path_str
+            or str(self.path_manager.get_project_agents_dir()) in path_str
+        ):
+            return AgentTier.PROJECT
+        elif (
+            "user" in path_str
+            or str(self.path_manager.get_user_agents_dir()) in path_str
+        ):
+            return AgentTier.USER
+        else:
+            return AgentTier.SYSTEM
+
+    def _determine_agent_type(self, file_path: Path, tier: AgentTier) -> AgentType:
+        """Determine agent type based on file path and tier."""
+        path_str = str(file_path).lower()
+
+        # Project-specific agents
+        if tier == AgentTier.PROJECT:
+            return AgentType.PROJECT
+
+        # User-defined agents
+        if tier == AgentTier.USER:
+            return AgentType.USER_DEFINED
+
+        # Core framework agents
+        if "templates" in path_str or "core" in path_str:
+            return AgentType.CORE
+
+        # Specialized agents
+        return AgentType.SPECIALIZED
+
+    def _extract_file_metadata(
+        self, file_path: Path, agent_format: AgentFormat
+    ) -> tuple[str, List[str]]:
+        """Extract description and specializations from agent file."""
+        try:
+            content = file_path.read_text(encoding="utf-8")
+
+            if agent_format == AgentFormat.JSON:
+                data = json.loads(content)
+                description = data.get("description", "")
+                specializations = data.get("specializations", [])
+            elif agent_format in [AgentFormat.YAML, AgentFormat.YAML]:
+                try:
+                    import yaml
+
+                    data = yaml.safe_load(content)
+                    description = data.get("description", "")
+                    specializations = data.get("specializations", [])
+                except ImportError:
+                    # Fallback if yaml not available
+                    description = ""
+                    specializations = []
+            else:  # Markdown
+                # Extract from frontmatter or content
+                description = self._extract_markdown_description(content)
+                specializations = self._extract_markdown_specializations(content)
+
+            return description, specializations
+
+        except Exception as e:
+            logger.warning(f"Failed to extract metadata from {file_path}: {e}")
+            return "", []
+
+    def _extract_markdown_description(self, content: str) -> str:
+        """Extract description from markdown content."""
+        lines = content.split("\n")
+
+        # Look for frontmatter
+        if lines and lines[0].strip() == "---":
+            in_frontmatter = True
+            for i, line in enumerate(lines[1:], 1):
+                if line.strip() == "---":
+                    break
+                if line.startswith("description:"):
+                    return line.split(":", 1)[1].strip().strip("\"'")
+
+        # Look for first paragraph
+        for line in lines:
+            line = line.strip()
+            if line and not line.startswith("#") and not line.startswith("---"):
+                return line
+
+        return ""
+
+    def _extract_markdown_specializations(self, content: str) -> List[str]:
+        """Extract specializations from markdown content."""
+        specializations = []
+
+        # Look for frontmatter
+        lines = content.split("\n")
+        if lines and lines[0].strip() == "---":
+            in_frontmatter = True
+            for i, line in enumerate(lines[1:], 1):
+                if line.strip() == "---":
+                    break
+                if line.startswith("specializations:"):
+                    # Parse YAML list
+                    spec_content = line.split(":", 1)[1].strip()
+                    if spec_content.startswith("[") and spec_content.endswith("]"):
+                        # JSON-style list
+                        try:
+                            specializations = json.loads(spec_content)
+                        except:
+                            pass
+
+        return specializations
+
+    def _apply_tier_precedence(self) -> None:
+        """Apply tier precedence rules to resolve conflicts."""
+        # Group agents by name
+        agent_groups = {}
+        for name, metadata in self.registry.items():
+            if name not in agent_groups:
+                agent_groups[name] = []
+            agent_groups[name].append(metadata)
+
+        # Resolve conflicts using tier precedence
+        resolved_registry = {}
+        tier_order = [AgentTier.PROJECT, AgentTier.USER, AgentTier.SYSTEM]
+
+        for name, agents in agent_groups.items():
+            if len(agents) == 1:
+                resolved_registry[name] = agents[0]
+            else:
+                # Find highest precedence agent
+                for tier in tier_order:
+                    for agent in agents:
+                        if agent.tier == tier:
+                            resolved_registry[name] = agent
+                            logger.debug(
+                                f"Resolved conflict for {name}: using {tier.value} tier"
+                            )
+                            break
+                    if name in resolved_registry:
+                        break
+
+        self.registry = resolved_registry
+
+    def _discover_memory_integration(self) -> None:
+        """Discover and integrate memory files with agents."""
+        memories_dir = self.path_manager.get_memories_dir("project")
+        if not memories_dir.exists():
+            return
+
+        for memory_file in memories_dir.glob("*.md"):
+            memory_name = memory_file.stem
+
+            # Find matching agent
+            for agent_name, metadata in self.registry.items():
+                if agent_name == memory_name or memory_name in agent_name:
+                    metadata.memory_files.append(str(memory_file))
+                    metadata.agent_type = AgentType.MEMORY_AWARE
+                    logger.debug(
+                        f"Integrated memory file {memory_file} with agent {agent_name}"
+                    )
+
+    def _is_cache_valid(self) -> bool:
+        """Check if the current cache is still valid."""
+        if not self.discovery_stats["last_discovery"]:
+            return False
+
+        # Check if cache has expired
+        cache_age = time.time() - self.discovery_stats["last_discovery"]
+        if cache_age > self.cache_ttl:
+            return False
+
+        # Check if any discovered files have been modified
+        for file_path in self.discovered_files:
+            if file_path.exists():
+                if file_path.stat().st_mtime > self.discovery_stats["last_discovery"]:
+                    return False
+            else:
+                # File was deleted
+                return False
+
+        return True
+
+    def _cache_registry(self) -> None:
+        """Cache the current registry state."""
+        # For now, we just store in memory
+        # In a full implementation, this could write to disk
+        pass
+
+    # ========================================================================
+    # Public API Methods
+    # ========================================================================
+
+    def get_agent(self, name: str) -> Optional[AgentMetadata]:
+        """Get agent metadata by name."""
+        if not self.registry:
+            self.discover_agents()
+
+        return self.registry.get(name)
+
+    def list_agents(
+        self,
+        tier: Optional[AgentTier] = None,
+        agent_type: Optional[AgentType] = None,
+        tags: Optional[List[str]] = None,
+    ) -> List[AgentMetadata]:
+        """List agents with optional filtering."""
+        if not self.registry:
+            self.discover_agents()
+
+        agents = list(self.registry.values())
+
+        # Apply filters
+        if tier:
+            agents = [a for a in agents if a.tier == tier]
+
+        if agent_type:
+            agents = [a for a in agents if a.agent_type == agent_type]
+
+        if tags:
+            agents = [a for a in agents if any(tag in a.tags for tag in tags)]
+
+        return sorted(agents, key=lambda a: (a.tier.value, a.name))
+
+    def get_agent_names(self) -> List[str]:
+        """Get list of all agent names."""
+        if not self.registry:
+            self.discover_agents()
+
+        return sorted(self.registry.keys())
+
+    def get_core_agents(self) -> List[AgentMetadata]:
+        """Get all core framework agents."""
+        return self.list_agents(agent_type=AgentType.CORE)
+
+    def get_specialized_agents(self) -> List[AgentMetadata]:
+        """Get all specialized agents."""
+        return self.list_agents(agent_type=AgentType.SPECIALIZED)
+
+    def get_project_agents(self) -> List[AgentMetadata]:
+        """Get all project-specific agents."""
+        return self.list_agents(tier=AgentTier.PROJECT)
+
+    def get_memory_aware_agents(self) -> List[AgentMetadata]:
+        """Get all memory-aware agents."""
+        return self.list_agents(agent_type=AgentType.MEMORY_AWARE)
+
+    def add_discovery_path(self, path: Union[str, Path]) -> None:
+        """Add a new path for agent discovery."""
+        path = Path(path)
+        if path.exists() and path not in self.discovery_paths:
+            self.discovery_paths.append(path)
+            logger.info(f"Added discovery path: {path}")
+            # Force re-discovery with new path
+            self.discover_agents(force_refresh=True)
+
+    def invalidate_cache(self) -> None:
+        """Invalidate the current cache."""
+        self.discovery_stats["last_discovery"] = None
+        logger.debug("Agent registry cache invalidated")
+
+    def get_registry_stats(self) -> Dict[str, Any]:
+        """Get registry statistics."""
+        return {
+            **self.discovery_stats,
+            "total_agents": len(self.registry),
+            "discovery_paths": [str(p) for p in self.discovery_paths],
+            "cache_enabled": self.cache_enabled,
+        }
+
+    def export_registry(self, output_path: Union[str, Path]) -> None:
+        """Export registry to JSON file."""
+        output_path = Path(output_path)
+
+        export_data = {
+            "metadata": {
+                "export_time": datetime.now().isoformat(),
+                "total_agents": len(self.registry),
+                "discovery_paths": [str(p) for p in self.discovery_paths],
+            },
+            "agents": {
+                name: metadata.to_dict() for name, metadata in self.registry.items()
+            },
+        }
+
+        with open(output_path, "w") as f:
+            json.dump(export_data, f, indent=2)
+
+        logger.info(f"Exported {len(self.registry)} agents to {output_path}")
+
+    def import_registry(self, input_path: Union[str, Path]) -> None:
+        """Import registry from JSON file."""
+        input_path = Path(input_path)
+
+        with open(input_path, "r") as f:
+            data = json.load(f)
+
+        # Clear current registry
+        self.registry.clear()
+
+        # Import agents
+        for name, agent_data in data.get("agents", {}).items():
+            self.registry[name] = AgentMetadata.from_dict(agent_data)
+
+        logger.info(f"Imported {len(self.registry)} agents from {input_path}")
+
+
+# ============================================================================
+# Singleton Instance and Convenience Functions
+# ============================================================================
+
+# Global singleton instance
+_agent_registry: Optional[UnifiedAgentRegistry] = None
+
+
+def get_agent_registry() -> UnifiedAgentRegistry:
+    """Get the global UnifiedAgentRegistry instance."""
+    global _agent_registry
+    if _agent_registry is None:
+        _agent_registry = UnifiedAgentRegistry()
+    return _agent_registry
+
+
+# Convenience functions for backward compatibility
+def discover_agents() -> Dict[str, AgentMetadata]:
+    """Discover all agents."""
+    return get_agent_registry().discover_agents()
+
+
+def list_agents(
+    tier: Optional[AgentTier] = None, agent_type: Optional[AgentType] = None
+) -> List[AgentMetadata]:
+    """List agents with optional filtering."""
+    return get_agent_registry().list_agents(tier=tier, agent_type=agent_type)
+
+
+def get_agent(name: str) -> Optional[AgentMetadata]:
+    """Get agent metadata by name."""
+    return get_agent_registry().get_agent(name)
+
+
+def get_core_agents() -> List[AgentMetadata]:
+    """Get all core framework agents."""
+    return get_agent_registry().get_core_agents()
+
+
+def get_specialized_agents() -> List[AgentMetadata]:
+    """Get all specialized agents."""
+    return get_agent_registry().get_specialized_agents()
+
+
+def get_project_agents() -> List[AgentMetadata]:
+    """Get all project-specific agents."""
+    return get_agent_registry().get_project_agents()
+
+
+def get_agent_names() -> List[str]:
+    """Get list of all agent names."""
+    return get_agent_registry().get_agent_names()
+
+
+def get_registry_stats() -> Dict[str, Any]:
+    """Get registry statistics."""
+    return get_agent_registry().get_registry_stats()
+
+
+# Legacy function names for backward compatibility
+def listAgents() -> List[str]:
+    """Legacy function: Get list of agent names."""
+    return get_agent_names()
+
+
+def discover_agents_sync() -> Dict[str, AgentMetadata]:
+    """Legacy function: Synchronous agent discovery."""
+    return discover_agents()
+
+
+def list_agents_all() -> List[AgentMetadata]:
+    """Legacy function: List all agents."""
+    return list_agents()
+
+
+# ============================================================================
+# Export All Public Symbols
+# ============================================================================
+
+__all__ = [
+    "UnifiedAgentRegistry",
+    "AgentMetadata",
+    "AgentTier",
+    "AgentType",
+    "AgentFormat",
+    "get_agent_registry",
+    "discover_agents",
+    "list_agents",
+    "get_agent",
+    "get_core_agents",
+    "get_specialized_agents",
+    "get_project_agents",
+    "get_agent_names",
+    "get_registry_stats",
+    # Legacy compatibility
+    "listAgents",
+    "discover_agents_sync",
+    "list_agents_all",
+]