claude-mpm 3.4.10__py3-none-any.whl → 5.4.85__py3-none-any.whl

claude_mpm/services/agents/deployment/deployment_results_manager.py

@@ -0,0 +1,185 @@
+"""Deployment results manager for tracking deployment outcomes."""
+
+import logging
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+class DeploymentResultsManager:
+    """Service for managing deployment results and metrics.
+
+    This service handles initialization and updates of deployment
+    results dictionaries, ensuring consistent structure across
+    all deployment operations.
+    """
+
+    def __init__(self, logger: Optional[logging.Logger] = None):
+        """Initialize the deployment results manager.
+
+        Args:
+            logger: Optional logger instance
+        """
+        self.logger = logger or logging.getLogger(__name__)
+
+        # Initialize deployment metrics tracking
+        self._deployment_metrics = {
+            "total_deployments": 0,
+            "successful_deployments": 0,
+            "failed_deployments": 0,
+            "migrations_performed": 0,
+            "version_migration_count": 0,
+            "agent_type_counts": {},
+            "deployment_errors": {},
+        }
+
+    def initialize_deployment_results(
+        self, agents_dir: Path, deployment_start_time: float
+    ) -> Dict[str, Any]:
+        """Initialize the deployment results dictionary.
+
+        WHY: Consistent result structure ensures all deployment
+        operations return the same format for easier processing.
+
+        Args:
+            agents_dir: Target agents directory
+            deployment_start_time: Start time for metrics
+
+        Returns:
+            Initialized results dictionary
+        """
+        return {
+            "target_dir": str(agents_dir),
+            "deployed": [],
+            "errors": [],
+            "skipped": [],
+            "updated": [],
+            "migrated": [],  # Track agents migrated from old format
+            "converted": [],  # Track YAML to MD conversions
+            "repaired": [],  # Track agents with repaired frontmatter
+            "total": 0,
+            # METRICS: Add detailed timing and performance data to results
+            "metrics": {
+                "start_time": deployment_start_time,
+                "end_time": None,
+                "duration_ms": None,
+                "agent_timings": {},  # Track individual agent deployment times
+                "validation_times": {},  # Track template validation times
+                "resource_usage": {},  # Could track memory/CPU if needed
+            },
+        }
+
+    def record_agent_deployment(
+        self,
+        agent_name: str,
+        template_file: Path,
+        target_file: Path,
+        is_update: bool,
+        is_migration: bool,
+        reason: str,
+        agent_start_time: float,
+        results: Dict[str, Any],
+        logger: Optional[logging.Logger] = None,
+    ) -> None:
+        """Record deployment metrics and update results.
+
+        WHY: Centralized metrics recording ensures consistent tracking
+        of deployment performance and statistics.
+
+        Args:
+            agent_name: Name of the agent
+            template_file: Template file
+            target_file: Target file
+            is_update: Whether this is an update
+            is_migration: Whether this is a migration
+            reason: Update/migration reason
+            agent_start_time: Start time for this agent
+            results: Results dictionary to update
+            logger: Optional logger for output
+        """
+        logger = logger or self.logger
+
+        # METRICS: Record deployment time for this agent
+        agent_deployment_time = (time.time() - agent_start_time) * 1000  # Convert to ms
+        results["metrics"]["agent_timings"][agent_name] = agent_deployment_time
+
+        # METRICS: Update agent type deployment counts
+        self._deployment_metrics["agent_type_counts"][agent_name] = (
+            self._deployment_metrics["agent_type_counts"].get(agent_name, 0) + 1
+        )
+
+        deployment_info = {
+            "name": agent_name,
+            "template": str(template_file),
+            "target": str(target_file),
+            "deployment_time_ms": agent_deployment_time,
+        }
+
+        if is_migration:
+            deployment_info["reason"] = reason
+            results["migrated"].append(deployment_info)
+            logger.info(
+                f"Successfully migrated agent: {agent_name} to semantic versioning"
+            )
+
+            # METRICS: Track migration statistics
+            self._deployment_metrics["migrations_performed"] += 1
+            self._deployment_metrics["version_migration_count"] += 1
+
+        elif is_update:
+            results["updated"].append(deployment_info)
+            logger.debug(f"Updated agent: {agent_name}")
+        else:
+            results["deployed"].append(deployment_info)
+            logger.debug(f"Built and deployed agent: {agent_name}")
+
+    def finalize_results(
+        self, results: Dict[str, Any], deployment_start_time: float
+    ) -> None:
+        """Finalize deployment results with end metrics.
+
+        Args:
+            results: Results dictionary to finalize
+            deployment_start_time: Original start time
+        """
+        deployment_end_time = time.time()
+        deployment_duration = (deployment_end_time - deployment_start_time) * 1000  # ms
+
+        results["metrics"]["end_time"] = deployment_end_time
+        results["metrics"]["duration_ms"] = deployment_duration
+
+    def update_deployment_metrics(
+        self, success: bool, error_type: Optional[str] = None
+    ) -> None:
+        """Update internal deployment metrics.
+
+        Args:
+            success: Whether deployment succeeded
+            error_type: Type of error if failed
+        """
+        self._deployment_metrics["total_deployments"] += 1
+
+        if success:
+            self._deployment_metrics["successful_deployments"] += 1
+        else:
+            self._deployment_metrics["failed_deployments"] += 1
+            if error_type:
+                self._deployment_metrics["deployment_errors"][error_type] = (
+                    self._deployment_metrics["deployment_errors"].get(error_type, 0) + 1
+                )
+
+    def get_deployment_metrics(self) -> Dict[str, Any]:
+        """Get current deployment metrics."""
+        return self._deployment_metrics.copy()
+
+    def reset_metrics(self) -> None:
+        """Reset deployment metrics."""
+        self._deployment_metrics = {
+            "total_deployments": 0,
+            "successful_deployments": 0,
+            "failed_deployments": 0,
+            "migrations_performed": 0,
+            "version_migration_count": 0,
+            "agent_type_counts": {},
+            "deployment_errors": {},
+        }

claude_mpm/services/agents/deployment/deployment_type_detector.py

@@ -0,0 +1,120 @@
+"""Deployment type detection for agent deployment service.
+
+This module provides utilities to detect the type of agent deployment
+(system, project-specific, or user custom) based on template directory paths.
+Extracted from AgentDeploymentService to reduce complexity.
+"""
+
+from pathlib import Path
+from typing import Optional
+
+from claude_mpm.config.paths import paths
+
+
+class DeploymentTypeDetector:
+    """Detects the type of agent deployment based on template directory."""
+
+    @staticmethod
+    def is_system_agent_deployment(templates_dir: Optional[Path]) -> bool:
+        """
+        Check if this is a deployment of system agents.
+
+        System agents are those provided by the claude-mpm package itself,
+        located in the package's agents/templates directory.
+
+        Args:
+            templates_dir: Directory containing agent templates
+
+        Returns:
+            True if deploying system agents, False otherwise
+        """
+        # Check if templates_dir points to the system templates
+        if templates_dir and templates_dir.exists():
+            # System agents are in the package's agents/templates directory
+            try:
+                # Check if templates_dir is within the claude_mpm package structure
+                templates_str = str(templates_dir.resolve())
+                return (
+                    "site-packages/claude_mpm" in templates_str
+                    or "src/claude_mpm/agents/templates" in templates_str
+                    or (paths.agents_dir / "templates").resolve()
+                    == templates_dir.resolve()
+                )
+            except Exception:
+                pass
+        return False
+
+    @staticmethod
+    def is_project_specific_deployment(
+        templates_dir: Optional[Path], working_directory: Path
+    ) -> bool:
+        """
+        Check if deploying project-specific agents.
+
+        Project-specific agents are those found in the project's
+        .claude-mpm/agents/ directory.
+
+        Args:
+            templates_dir: Directory containing agent templates
+            working_directory: Current working directory
+
+        Returns:
+            True if deploying project-specific agents, False otherwise
+        """
+        # Check if we're in a project directory with .claude-mpm/agents
+        project_agents_dir = working_directory / ".claude-mpm" / "agents"
+        if project_agents_dir.exists() and templates_dir and templates_dir.exists():
+            try:
+                return project_agents_dir.resolve() == templates_dir.resolve()
+            except Exception:
+                pass
+        return False
+
+    @staticmethod
+    def is_user_custom_deployment(templates_dir: Optional[Path]) -> bool:
+        """
+        Check if deploying user custom agents.
+
+        User custom agents are those in ~/.claude-mpm/agents/
+
+        Args:
+            templates_dir: Directory containing agent templates
+
+        Returns:
+            True if deploying user custom agents, False otherwise
+        """
+        user_agents_dir = Path.home() / ".claude-mpm" / "agents"
+        if user_agents_dir.exists() and templates_dir and templates_dir.exists():
+            try:
+                return user_agents_dir.resolve() == templates_dir.resolve()
+            except Exception:
+                pass
+        return False
+
+    @staticmethod
+    def determine_source_tier(templates_dir: Optional[Path]) -> str:
+        """
+        Determine the source tier for logging.
+
+        Understanding which tier (SYSTEM/USER/PROJECT) agents
+        are being deployed from helps with debugging and auditing.
+
+        Args:
+            templates_dir: Directory containing agent templates
+
+        Returns:
+            Source tier string: "SYSTEM", "USER", or "PROJECT"
+        """
+        if templates_dir:
+            templates_str = str(templates_dir)
+            if (
+                ".claude-mpm/agents" in templates_str
+                and "/templates" not in templates_str
+            ):
+                return "PROJECT"
+            if (
+                "/.claude-mpm/agents" in templates_str
+                and "/templates" not in templates_str
+            ):
+                return "USER"
+        return "SYSTEM"

claude_mpm/services/agents/deployment/deployment_wrapper.py

@@ -0,0 +1,129 @@
+"""Temporary wrapper to provide backward compatibility for CLI commands."""
+
+import contextlib
+from pathlib import Path
+from typing import Any, Dict
+
+from claude_mpm.services.agents.deployment import AgentDeploymentService
+
+
+class DeploymentServiceWrapper:
+    """Wrapper to provide backward-compatible methods for the CLI."""
+
+    def __init__(self, deployment_service: AgentDeploymentService):
+        """Initialize wrapper with actual deployment service."""
+        self.service = deployment_service
+        # Pass through all attributes
+        for attr in dir(deployment_service):
+            if not attr.startswith("_") and not hasattr(self, attr):
+                setattr(self, attr, getattr(deployment_service, attr))
+
+    def deploy_system_agents(self, force: bool = False) -> Dict[str, Any]:
+        """Deploy system agents only.
+
+        Args:
+            force: Force rebuild even if agents are up to date
+
+        Returns:
+            Deployment results
+        """
+        # Deploy agents with default target (system agents location)
+        result = self.service.deploy_agents(
+            force_rebuild=force, deployment_mode="update"
+        )
+
+        # Transform result to expected format
+        return {
+            "deployed_count": len(result.get("deployed", []))
+            + len(result.get("updated", [])),
+            "deployed": result.get("deployed", []),
+            "updated": result.get("updated", []),
+            "errors": result.get("errors", []),
+            "target_dir": result.get("target_dir", ""),
+        }
+
+    def deploy_project_agents(self, force: bool = False) -> Dict[str, Any]:
+        """Deploy project agents only.
+
+        Args:
+            force: Force rebuild even if agents are up to date
+
+        Returns:
+            Deployment results
+        """
+        # Check if project agents directory exists
+        project_dir = Path.cwd() / ".claude-mpm" / "agents"
+        if not project_dir.exists():
+            return {
+                "deployed_count": 0,
+                "deployed": [],
+                "updated": [],
+                "errors": [],
+                "target_dir": "",
+            }
+
+        # For now, return empty result as project agents are handled differently
+        return {
+            "deployed_count": 0,
+            "deployed": [],
+            "updated": [],
+            "errors": [],
+            "target_dir": str(project_dir),
+        }
+
+    def get_agent_details(self, agent_name: str) -> Dict[str, Any]:
+        """Get detailed information for a specific agent.
+
+        Args:
+            agent_name: Name of the agent
+
+        Returns:
+            Agent details dictionary or empty dict if not found
+        """
+        try:
+            # Try to get from list of available agents
+            available_agents = self.service.list_available_agents()
+            for agent in available_agents:
+                if agent.get("name") == agent_name:
+                    # Get template path for the agent
+                    templates_dir = self.service.templates_dir
+                    agent_path = templates_dir / f"{agent_name}.md"
+
+                    # Read agent content if file exists
+                    if agent_path.exists():
+                        with agent_path.open() as f:
+                            content = f.read()
+
+                        # Parse metadata from content
+                        import yaml
+
+                        metadata = {}
+                        if content.startswith("---"):
+                            # Extract frontmatter
+                            parts = content.split("---", 2)
+                            if len(parts) >= 2:
+                                with contextlib.suppress(yaml.YAMLError):
+                                    metadata = yaml.safe_load(parts[1])
+
+                        return {
+                            "name": agent_name,
+                            "path": str(agent_path),
+                            "type": agent.get("type", "agent"),
+                            "version": metadata.get("version", "1.0.0"),
+                            "description": metadata.get("description", ""),
+                            "specializations": metadata.get("specializations", []),
+                            "metadata": metadata,
+                            "content": content,
+                            "exists": True,
+                        }
+
+            # Agent not found in available agents
+            return {
+                "name": agent_name,
+                "exists": False,
+                "error": f"Agent '{agent_name}' not found",
+            }
+
+        except Exception as e:
+            # Return error information
+            return {"name": agent_name, "exists": False, "error": str(e)}

claude_mpm/services/agents/deployment/facade/__init__.py

@@ -0,0 +1,18 @@
+"""Deployment facade for handling async/sync deployment modes.
+
+This module provides a clean facade pattern for handling different
+deployment execution modes (async vs sync) without cluttering the
+main deployment logic with conditional complexity.
+"""
+
+from .async_deployment_executor import AsyncDeploymentExecutor
+from .deployment_executor import DeploymentExecutor
+from .deployment_facade import DeploymentFacade
+from .sync_deployment_executor import SyncDeploymentExecutor
+
+__all__ = [
+    "AsyncDeploymentExecutor",
+    "DeploymentExecutor",
+    "DeploymentFacade",
+    "SyncDeploymentExecutor",
+]

claude_mpm/services/agents/deployment/facade/async_deployment_executor.py

@@ -0,0 +1,159 @@
+"""Asynchronous deployment executor."""
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from claude_mpm.core.config import Config
+from claude_mpm.core.logger import get_logger
+
+from .deployment_executor import DeploymentExecutor
+
+
+class AsyncDeploymentExecutor(DeploymentExecutor):
+    """Asynchronous deployment executor.
+
+    This executor uses async operations for improved performance
+    when processing multiple agents concurrently.
+    """
+
+    def __init__(self):
+        """Initialize async deployment executor."""
+        self.logger = get_logger(__name__)
+        self._async_module = None
+        self._is_available = None
+
+    def execute_deployment(
+        self,
+        templates_dir: Path,
+        base_agent_path: Path,
+        working_directory: Path,
+        target_dir: Optional[Path] = None,
+        force_rebuild: bool = False,
+        deployment_mode: str = "update",
+        config: Optional[Config] = None,
+    ) -> Dict[str, Any]:
+        """Execute asynchronous deployment.
+
+        Args:
+            templates_dir: Directory containing agent templates
+            base_agent_path: Path to base agent configuration
+            working_directory: Working directory for deployment
+            target_dir: Target directory for deployment
+            force_rebuild: Whether to force rebuild
+            deployment_mode: Deployment mode (update/project)
+            config: Optional configuration
+
+        Returns:
+            Deployment results dictionary
+        """
+        if not self.is_available():
+            raise RuntimeError("Async deployment is not available")
+
+        self.logger.info("Executing asynchronous deployment")
+
+        try:
+            # Import async deployment module
+            async_module = self._get_async_module()
+
+            # Execute async deployment
+            results = async_module.deploy_agents_async_wrapper(
+                templates_dir=templates_dir,
+                base_agent_path=base_agent_path,
+                working_directory=working_directory,
+                target_dir=target_dir,
+                force_rebuild=force_rebuild,
+                config=config,
+            )
+
+            # Add executor metadata
+            if "metadata" not in results:
+                results["metadata"] = {}
+
+            results["metadata"]["executor"] = self.get_executor_name()
+            results["metadata"]["execution_mode"] = "asynchronous"
+
+            # Add performance metrics
+            if "metrics" not in results:
+                results["metrics"] = {}
+
+            results["metrics"]["deployment_method"] = "async"
+
+            return results
+
+        except Exception as e:
+            self.logger.error(f"Asynchronous deployment failed: {e}", exc_info=True)
+            return {
+                "success": False,
+                "error": str(e),
+                "deployed": [],
+                "updated": [],
+                "migrated": [],
+                "skipped": [],
+                "errors": [str(e)],
+                "metadata": {
+                    "executor": self.get_executor_name(),
+                    "execution_mode": "asynchronous",
+                    "error_type": type(e).__name__,
+                },
+            }
+
+    def is_available(self) -> bool:
+        """Check if async deployment is available.
+
+        Returns:
+            True if async deployment module can be imported
+        """
+        if self._is_available is None:
+            try:
+                self._get_async_module()
+                self._is_available = True
+            except ImportError:
+                self._is_available = False
+                self.logger.debug("Async deployment module not available")
+            except Exception as e:
+                self._is_available = False
+                self.logger.debug(f"Async deployment check failed: {e}")
+
+        return self._is_available
+
+    def _get_async_module(self):
+        """Get the async deployment module.
+
+        Returns:
+            Async deployment module
+
+        Raises:
+            ImportError: If async module cannot be imported
+        """
+        if self._async_module is None:
+            try:
+                from claude_mpm.services.agents.deployment import async_agent_deployment
+
+                self._async_module = async_agent_deployment
+            except ImportError as e:
+                raise ImportError("Async deployment module not available") from e
+
+        return self._async_module
+
+    def get_executor_name(self) -> str:
+        """Get executor name.
+
+        Returns:
+            Executor name
+        """
+        return "async"
+
+    def get_performance_characteristics(self) -> Dict[str, Any]:
+        """Get performance characteristics.
+
+        Returns:
+            Performance characteristics dictionary
+        """
+        return {
+            "name": self.get_executor_name(),
+            "available": self.is_available(),
+            "estimated_speedup": 1.6,  # 50-70% faster based on existing comments
+            "memory_usage": "higher",  # Concurrent operations use more memory
+            "reliability": "medium",  # More complex, potential for async issues
+            "description": "Concurrent processing for improved performance",
+        }

claude_mpm/services/agents/deployment/facade/deployment_executor.py

@@ -0,0 +1,70 @@
+"""Base deployment executor interface."""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from claude_mpm.core.config import Config
+
+
+class DeploymentExecutor(ABC):
+    """Abstract base class for deployment executors.
+
+    This interface defines the contract for different deployment
+    execution strategies (async vs sync).
+    """
+
+    @abstractmethod
+    def execute_deployment(
+        self,
+        templates_dir: Path,
+        base_agent_path: Path,
+        working_directory: Path,
+        target_dir: Optional[Path] = None,
+        force_rebuild: bool = False,
+        deployment_mode: str = "update",
+        config: Optional[Config] = None,
+    ) -> Dict[str, Any]:
+        """Execute deployment with the specific strategy.
+
+        Args:
+            templates_dir: Directory containing agent templates
+            base_agent_path: Path to base agent configuration
+            working_directory: Working directory for deployment
+            target_dir: Target directory for deployment
+            force_rebuild: Whether to force rebuild
+            deployment_mode: Deployment mode (update/project)
+            config: Optional configuration
+
+        Returns:
+            Deployment results dictionary
+        """
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Check if this executor is available.
+
+        Returns:
+            True if executor can be used
+        """
+
+    @abstractmethod
+    def get_executor_name(self) -> str:
+        """Get the name of this executor.
+
+        Returns:
+            Executor name for logging/metrics
+        """
+
+    def get_performance_characteristics(self) -> Dict[str, Any]:
+        """Get performance characteristics of this executor.
+
+        Returns:
+            Dictionary with performance info
+        """
+        return {
+            "name": self.get_executor_name(),
+            "available": self.is_available(),
+            "estimated_speedup": 1.0,  # Override in subclasses
+            "memory_usage": "normal",  # Override in subclasses
+        }