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

claude_mpm/agents/async_agent_loader.py

@@ -1,3 +1,5 @@
+from pathlib import Path
+
 """Async Agent Loader for high-performance parallel agent discovery and loading.
 
 This module provides async versions of agent loading operations to significantly
@@ -26,18 +28,18 @@ import asyncio
 import json
 import logging
 import time
-from pathlib import Path
-from typing import Dict, Any, List, Optional, Tuple
-from enum import Enum
 from concurrent.futures import ThreadPoolExecutor
+from enum import Enum
+from typing import Any, Dict, List, Optional, Tuple
 
 import aiofiles
 
 from claude_mpm.services.memory.cache.shared_prompt_cache import SharedPromptCache
-from .base_agent_loader import prepend_base_instructions
-from ..validation.agent_validator import AgentValidator, ValidationResult
+
 from ..core.agent_name_normalizer import AgentNameNormalizer
-from ..core.config_paths import ConfigPaths
+from ..core.unified_paths import get_path_manager
+from ..validation.agent_validator import AgentValidator, ValidationResult
+from .base_agent_loader import prepend_base_instructions
 from .frontmatter_validator import FrontmatterValidator
 
 # Module-level logger
@@ -46,6 +48,7 @@ logger = logging.getLogger(__name__)
 
 class AgentTier(Enum):
     """Agent precedence tiers."""
+
     PROJECT = "project"
     USER = "user"
     SYSTEM = "system"
@@ -53,19 +56,19 @@ class AgentTier(Enum):
 
 class AsyncAgentLoader:
     """Async agent loader for high-performance parallel operations.
-    
+
     WHY: This async loader provides:
     - 60-80% faster agent discovery through parallel tier scanning
     - Non-blocking file I/O for all agent files
     - Concurrent validation and parsing
     - Seamless integration with existing code
-    
+
     PERFORMANCE METRICS (typical):
     - Sync loading: 300-500ms for 10 agents across 3 tiers
     - Async loading: 80-150ms for same (70-80% reduction)
     - Scales better with more agents (near-constant time)
     """
-    
+
     def __init__(self):
         """Initialize async agent loader."""
         self.validator = AgentValidator()
@@ -73,50 +76,60 @@ class AsyncAgentLoader:
         self._agent_registry: Dict[str, Dict[str, Any]] = {}
         self._agent_tiers: Dict[str, AgentTier] = {}
         self.frontmatter_validator = FrontmatterValidator()
-        
+
         # Thread pool for CPU-bound operations
         self.executor = ThreadPoolExecutor(max_workers=4)
-        
+
         # Performance metrics
         self._metrics = {
-            'agents_loaded': 0,
-            'async_operations': 0,
-            'parallel_tiers_scanned': 0,
-            'time_saved_ms': 0.0,
-            'cache_hits': 0,
-            'cache_misses': 0
+            "agents_loaded": 0,
+            "async_operations": 0,
+            "parallel_tiers_scanned": 0,
+            "time_saved_ms": 0.0,
+            "cache_hits": 0,
+            "cache_misses": 0,
         }
-    
+
     async def discover_agent_dirs_async(self) -> Dict[AgentTier, Optional[Path]]:
         """Discover agent directories across all tiers in parallel.
-        
+
         WHY: Checking directory existence across PROJECT/USER/SYSTEM tiers
         sequentially adds unnecessary latency. Parallel checking reduces
         this to the time of the slowest check.
-        
+
         Returns:
             Dictionary mapping tiers to their directories
         """
-        async def check_tier_dir(tier: AgentTier, path: Path) -> Tuple[AgentTier, Optional[Path]]:
+
+        async def check_tier_dir(
+            tier: AgentTier, path: Path
+        ) -> Tuple[AgentTier, Optional[Path]]:
             """Check if a tier directory exists."""
             if path.exists():
                 logger.debug(f"Found {tier.value.upper()} agents at: {path}")
                 return tier, path
             return tier, None
-        
+
         # Define tier paths
         tier_paths = [
-            (AgentTier.PROJECT, Path.cwd() / ConfigPaths.CONFIG_DIR / "agents"),
-            (AgentTier.USER, ConfigPaths.get_user_config_dir() / "agents" if ConfigPaths.get_user_config_dir() else None),
-            (AgentTier.SYSTEM, Path(__file__).parent / "templates")
+            (AgentTier.PROJECT, Path.cwd() / get_path_manager().CONFIG_DIR / "agents"),
+            (
+                AgentTier.USER,
+                (
+                    get_path_manager().get_user_config_dir() / "agents"
+                    if get_path_manager().get_user_config_dir()
+                    else None
+                ),
+            ),
+            (AgentTier.SYSTEM, Path(__file__).parent / "templates"),
         ]
-        
+
         # Check all tiers in parallel
         results = await asyncio.gather(
             *[check_tier_dir(tier, path) for tier, path in tier_paths if path],
-            return_exceptions=True
+            return_exceptions=True,
         )
-        
+
         dirs = {}
         for result in results:
             if isinstance(result, Exception):
@@ -125,257 +138,258 @@ class AsyncAgentLoader:
             tier, path = result
             if path:
                 dirs[tier] = path
-                
-        self._metrics['parallel_tiers_scanned'] = len(dirs)
+
+        self._metrics["parallel_tiers_scanned"] = len(dirs)
         return dirs
-    
-    async def load_agents_from_dir_async(self, directory: Path, tier: AgentTier) -> List[Dict[str, Any]]:
+
+    async def load_agents_from_dir_async(
+        self, directory: Path, tier: AgentTier
+    ) -> List[Dict[str, Any]]:
         """Load all agents from a directory asynchronously.
-        
+
         WHY: Loading multiple agent files sequentially is slow.
         This method discovers and loads all files in parallel,
         dramatically reducing I/O wait time.
-        
+
         Args:
             directory: Directory containing agent files
             tier: The tier this directory belongs to
-            
+
         Returns:
             List of loaded agent configurations
         """
         if not directory.exists():
             return []
-        
+
         start_time = time.time()
-        
+
         # Discover agent files (both .json and .md)
         loop = asyncio.get_event_loop()
         json_files = await loop.run_in_executor(
-            self.executor,
-            lambda: list(directory.glob("*.json"))
+            self.executor, lambda: list(directory.glob("*.json"))
         )
         md_files = await loop.run_in_executor(
-            self.executor,
-            lambda: list(directory.glob("*.md"))
+            self.executor, lambda: list(directory.glob("*.md"))
         )
-        
+
         all_files = json_files + md_files
         logger.debug(f"Found {len(all_files)} agent files in {directory}")
-        
+
         if not all_files:
             return []
-        
+
         # Load all files in parallel
         async def load_file(file_path: Path) -> Optional[Dict[str, Any]]:
             """Load a single agent file."""
             try:
-                if file_path.suffix == '.json':
+                if file_path.suffix == ".json":
                     return await self.load_json_agent_async(file_path)
-                elif file_path.suffix == '.md':
+                elif file_path.suffix == ".md":
                     return await self.load_md_agent_async(file_path)
                 else:
                     return None
             except Exception as e:
                 logger.error(f"Failed to load {file_path}: {e}")
                 return None
-        
+
         agents = await asyncio.gather(
-            *[load_file(f) for f in all_files],
-            return_exceptions=False
+            *[load_file(f) for f in all_files], return_exceptions=False
         )
-        
+
         # Filter out None values and add tier information
         valid_agents = []
         for agent in agents:
             if agent:
-                agent['_tier'] = tier.value
-                agent_id = agent.get('agent_id') or agent.get('_agent_name')
+                agent["_tier"] = tier.value
+                agent_id = agent.get("agent_id") or agent.get("_agent_name")
                 if agent_id:
                     self._agent_tiers[agent_id] = tier
                 valid_agents.append(agent)
-        
+
         elapsed = (time.time() - start_time) * 1000
-        logger.info(f"Loaded {len(valid_agents)} agents from {tier.value} tier in {elapsed:.1f}ms")
-        self._metrics['agents_loaded'] += len(valid_agents)
-        
+        logger.info(
+            f"Loaded {len(valid_agents)} agents from {tier.value} tier in {elapsed:.1f}ms"
+        )
+        self._metrics["agents_loaded"] += len(valid_agents)
+
         return valid_agents
-    
+
     async def load_json_agent_async(self, file_path: Path) -> Optional[Dict[str, Any]]:
         """Load a JSON agent file asynchronously.
-        
+
         WHY: JSON files require file I/O (async) and parsing (CPU-bound).
         We use aiofiles for non-blocking reads and thread pool for parsing.
-        
+
         Args:
             file_path: Path to JSON agent file
-            
+
         Returns:
             Parsed agent configuration or None if failed
         """
         try:
             # Non-blocking file read
-            async with aiofiles.open(file_path, 'r') as f:
+            async with aiofiles.open(file_path, "r") as f:
                 content = await f.read()
-            
+
             # Parse JSON in thread pool (CPU-bound)
             loop = asyncio.get_event_loop()
-            data = await loop.run_in_executor(
-                self.executor,
-                json.loads,
-                content
-            )
-            
+            data = await loop.run_in_executor(self.executor, json.loads, content)
+
             # Add metadata
-            data['_source_file'] = str(file_path)
-            data['_agent_name'] = file_path.stem
-            data['_format'] = 'json'
-            
-            self._metrics['async_operations'] += 1
+            data["_source_file"] = str(file_path)
+            data["_agent_name"] = file_path.stem
+            data["_format"] = "json"
+
+            self._metrics["async_operations"] += 1
             return data
-            
+
         except Exception as e:
             logger.error(f"Failed to load JSON agent {file_path}: {e}")
             return None
-    
+
     async def load_md_agent_async(self, file_path: Path) -> Optional[Dict[str, Any]]:
         """Load a Markdown agent file with YAML frontmatter asynchronously.
-        
+
         WHY: MD files with frontmatter require parsing both YAML and markdown.
         Async loading prevents blocking on file I/O.
-        
+
         Args:
             file_path: Path to MD agent file
-            
+
         Returns:
             Parsed agent configuration or None if failed
         """
         try:
             # Non-blocking file read
-            async with aiofiles.open(file_path, 'r') as f:
+            async with aiofiles.open(file_path, "r") as f:
                 content = await f.read()
-            
+
             # Parse frontmatter in thread pool
             loop = asyncio.get_event_loop()
             data = await loop.run_in_executor(
-                self.executor,
-                self._parse_frontmatter,
-                content
+                self.executor, self._parse_frontmatter, content
             )
-            
+
             if data:
                 # Add metadata
-                data['_source_file'] = str(file_path)
-                data['_agent_name'] = file_path.stem
-                data['_format'] = 'markdown'
-                
-                self._metrics['async_operations'] += 1
-            
+                data["_source_file"] = str(file_path)
+                data["_agent_name"] = file_path.stem
+                data["_format"] = "markdown"
+
+                self._metrics["async_operations"] += 1
+
             return data
-            
+
         except Exception as e:
             logger.error(f"Failed to load MD agent {file_path}: {e}")
             return None
-    
+
     def _parse_frontmatter(self, content: str) -> Optional[Dict[str, Any]]:
         """Parse YAML frontmatter from markdown content.
-        
+
         This is a CPU-bound operation run in the thread pool.
-        
+
         Args:
             content: Markdown file content
-            
+
         Returns:
             Parsed agent data or None if invalid
         """
         try:
             import yaml
-            
+
             # Extract frontmatter
-            if not content.startswith('---'):
+            if not content.startswith("---"):
                 return None
-                
-            end_marker = content.find('\n---\n', 4)
+
+            end_marker = content.find("\n---\n", 4)
             if end_marker == -1:
                 return None
-                
+
             frontmatter = content[4:end_marker]
-            instructions = content[end_marker + 5:].strip()
-            
+            instructions = content[end_marker + 5 :].strip()
+
             # Parse YAML
             data = yaml.safe_load(frontmatter)
             if not isinstance(data, dict):
                 return None
-                
+
             # Add instructions
-            data['instructions'] = instructions
-            
+            data["instructions"] = instructions
+
             # Map fields for compatibility
-            if 'name' in data:
-                data['agent_id'] = data['name']
-                
+            if "name" in data:
+                data["agent_id"] = data["name"]
+
             return data
-            
+
         except Exception as e:
             logger.error(f"Failed to parse frontmatter: {e}")
             return None
-    
+
     async def load_all_agents_async(self) -> Dict[str, Dict[str, Any]]:
         """Load all agents from all tiers in parallel.
-        
+
         WHY: This is the main performance optimization - loading agents
         from PROJECT, USER, and SYSTEM tiers simultaneously reduces
         total load time to that of the slowest tier.
-        
+
         Returns:
             Dictionary of all loaded agents by ID
         """
         start_time = time.time()
-        
+
         # Discover directories in parallel
         tier_dirs = await self.discover_agent_dirs_async()
-        
+
         if not tier_dirs:
             logger.warning("No agent directories found")
             return {}
-        
+
         # Load agents from all tiers in parallel
         tier_agents = await asyncio.gather(
-            *[self.load_agents_from_dir_async(directory, tier) 
-              for tier, directory in tier_dirs.items()],
-            return_exceptions=False
+            *[
+                self.load_agents_from_dir_async(directory, tier)
+                for tier, directory in tier_dirs.items()
+            ],
+            return_exceptions=False,
         )
-        
+
         # Merge agents with tier precedence (PROJECT > USER > SYSTEM)
         merged_agents = {}
-        
+
         # Process in reverse precedence order
         for agents in reversed(tier_agents):
             for agent in agents:
-                agent_id = agent.get('agent_id') or agent.get('_agent_name')
+                agent_id = agent.get("agent_id") or agent.get("_agent_name")
                 if agent_id:
                     # Check if already loaded from higher precedence tier
                     if agent_id in merged_agents:
-                        existing_tier = merged_agents[agent_id].get('_tier', 'unknown')
-                        new_tier = agent.get('_tier', 'unknown')
-                        logger.debug(f"Agent {agent_id}: keeping {existing_tier} version, skipping {new_tier}")
+                        existing_tier = merged_agents[agent_id].get("_tier", "unknown")
+                        new_tier = agent.get("_tier", "unknown")
+                        logger.debug(
+                            f"Agent {agent_id}: keeping {existing_tier} version, skipping {new_tier}"
+                        )
                     else:
                         merged_agents[agent_id] = agent
-        
+
         elapsed = (time.time() - start_time) * 1000
-        self._metrics['time_saved_ms'] = max(0, (500 - elapsed))  # Assume 500ms for sync
-        
+        self._metrics["time_saved_ms"] = max(
+            0, (500 - elapsed)
+        )  # Assume 500ms for sync
+
         logger.info(
             f"Async loaded {len(merged_agents)} agents in {elapsed:.1f}ms "
             f"(~{self._metrics['time_saved_ms']:.0f}ms saved)"
         )
-        
+
         self._agent_registry = merged_agents
         return merged_agents
-    
+
     async def cleanup(self):
         """Clean up resources."""
         self.executor.shutdown(wait=False)
-    
+
     def get_metrics(self) -> Dict[str, Any]:
         """Get performance metrics."""
         return self._metrics.copy()
@@ -384,33 +398,37 @@ class AsyncAgentLoader:
 # Convenience function to load agents asynchronously from sync code
 def load_agents_async() -> Dict[str, Dict[str, Any]]:
     """Load all agents using async operations.
-    
+
     WHY: This wrapper allows async agent loading from synchronous code,
     providing significant performance improvements without requiring
     a full async refactor of the codebase.
-    
+
     Returns:
         Dictionary of loaded agents by ID
     """
+
     async def run_loading():
         loader = AsyncAgentLoader()
         try:
             agents = await loader.load_all_agents_async()
             metrics = loader.get_metrics()
-            
-            if metrics.get('time_saved_ms', 0) > 0:
-                logger.info(f"Async loading saved approximately {metrics['time_saved_ms']:.0f}ms")
-                
+
+            if metrics.get("time_saved_ms", 0) > 0:
+                logger.info(
+                    f"Async loading saved approximately {metrics['time_saved_ms']:.0f}ms"
+                )
+
             return agents
         finally:
             await loader.cleanup()
-    
+
     # Run in event loop
     try:
         loop = asyncio.get_event_loop()
         if loop.is_running():
             # If loop is already running, use thread pool
             import concurrent.futures
+
             with concurrent.futures.ThreadPoolExecutor() as executor:
                 future = executor.submit(asyncio.run, run_loading())
                 return future.result()
@@ -418,4 +436,4 @@ def load_agents_async() -> Dict[str, Dict[str, Any]]:
             return loop.run_until_complete(run_loading())
     except RuntimeError:
         # No event loop, create new one
-        return asyncio.run(run_loading())
+        return asyncio.run(run_loading())

claude_mpm/agents/base_agent.json

@@ -25,4 +25,4 @@
     "token_efficiency": "optimized",
     "compatibility": ["claude-4-sonnet", "claude-4-opus"]
   }
-}
+}