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

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,73 @@
+"""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
+        """
+        pass
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Check if this executor is available.
+
+        Returns:
+            True if executor can be used
+        """
+        pass
+
+    @abstractmethod
+    def get_executor_name(self) -> str:
+        """Get the name of this executor.
+
+        Returns:
+            Executor name for logging/metrics
+        """
+        pass
+
+    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
+        }

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

@@ -0,0 +1,270 @@
+"""Deployment facade for handling async/sync deployment modes."""
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from claude_mpm.core.config import Config
+from claude_mpm.core.logger import get_logger
+
+from .async_deployment_executor import AsyncDeploymentExecutor
+from .deployment_executor import DeploymentExecutor
+from .sync_deployment_executor import SyncDeploymentExecutor
+
+
+class DeploymentFacade:
+    """Facade for handling different deployment execution modes.
+
+    This facade provides a clean interface for choosing between
+    async and sync deployment execution without cluttering the
+    main deployment logic with conditional complexity.
+    """
+
+    def __init__(self, pipeline_builder, pipeline_executor):
+        """Initialize deployment facade.
+
+        Args:
+            pipeline_builder: Pipeline builder for sync deployment
+            pipeline_executor: Pipeline executor for sync deployment
+        """
+        self.logger = get_logger(__name__)
+
+        # Initialize executors
+        self.sync_executor = SyncDeploymentExecutor(pipeline_builder, pipeline_executor)
+        self.async_executor = AsyncDeploymentExecutor()
+
+        # Executor registry
+        self.executors = {
+            "sync": self.sync_executor,
+            "async": self.async_executor,
+        }
+
+    def deploy_agents(
+        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,
+        use_async: bool = False,
+        preferred_executor: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Deploy agents using the appropriate executor.
+
+        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
+            use_async: Whether to prefer async execution
+            preferred_executor: Specific executor to use ('sync' or 'async')
+
+        Returns:
+            Deployment results dictionary
+        """
+        # Select executor
+        executor = self._select_executor(use_async, preferred_executor)
+
+        self.logger.info(f"Using {executor.get_executor_name()} deployment executor")
+
+        # Execute deployment
+        try:
+            results = executor.execute_deployment(
+                templates_dir=templates_dir,
+                base_agent_path=base_agent_path,
+                working_directory=working_directory,
+                target_dir=target_dir,
+                force_rebuild=force_rebuild,
+                deployment_mode=deployment_mode,
+                config=config,
+            )
+
+            # Add facade metadata
+            if "metadata" not in results:
+                results["metadata"] = {}
+
+            results["metadata"]["facade_version"] = "1.0.0"
+            results["metadata"]["selected_executor"] = executor.get_executor_name()
+            results["metadata"][
+                "executor_characteristics"
+            ] = executor.get_performance_characteristics()
+
+            return results
+
+        except Exception as e:
+            self.logger.error(
+                f"Deployment failed with {executor.get_executor_name()} executor: {e}"
+            )
+
+            # If async failed and we have a fallback option, try sync
+            if (
+                executor.get_executor_name() == "async"
+                and self.sync_executor.is_available()
+            ):
+                self.logger.info("Falling back to synchronous deployment")
+                return self._fallback_to_sync(
+                    templates_dir,
+                    base_agent_path,
+                    working_directory,
+                    target_dir,
+                    force_rebuild,
+                    deployment_mode,
+                    config,
+                    e,
+                )
+
+            # No fallback available, return error result
+            return {
+                "success": False,
+                "error": str(e),
+                "deployed": [],
+                "updated": [],
+                "migrated": [],
+                "skipped": [],
+                "errors": [str(e)],
+                "metadata": {
+                    "facade_version": "1.0.0",
+                    "selected_executor": executor.get_executor_name(),
+                    "error_type": type(e).__name__,
+                    "fallback_attempted": False,
+                },
+            }
+
+    def _select_executor(
+        self, use_async: bool, preferred_executor: Optional[str]
+    ) -> DeploymentExecutor:
+        """Select the appropriate deployment executor.
+
+        Args:
+            use_async: Whether to prefer async execution
+            preferred_executor: Specific executor preference
+
+        Returns:
+            Selected deployment executor
+        """
+        # If specific executor is requested, try to use it
+        if preferred_executor:
+            if preferred_executor in self.executors:
+                executor = self.executors[preferred_executor]
+                if executor.is_available():
+                    return executor
+                else:
+                    self.logger.warning(
+                        f"Preferred executor '{preferred_executor}' is not available"
+                    )
+            else:
+                self.logger.warning(f"Unknown executor '{preferred_executor}'")
+
+        # If async is preferred and available, use it
+        if use_async and self.async_executor.is_available():
+            return self.async_executor
+
+        # Fall back to sync executor
+        if self.sync_executor.is_available():
+            return self.sync_executor
+
+        # This should never happen, but just in case
+        raise RuntimeError("No deployment executors are available")
+
+    def get_available_executors(self) -> List[Dict[str, Any]]:
+        """Get information about available executors.
+
+        Returns:
+            List of executor information dictionaries
+        """
+        return [
+            executor.get_performance_characteristics()
+            for executor in self.executors.values()
+            if executor.is_available()
+        ]
+
+    def get_recommended_executor(self, agent_count: int = 1) -> str:
+        """Get recommended executor based on deployment characteristics.
+
+        Args:
+            agent_count: Number of agents to deploy
+
+        Returns:
+            Recommended executor name
+        """
+        # For small deployments, sync is fine
+        if agent_count <= 3:
+            return "sync"
+
+        # For larger deployments, prefer async if available
+        if self.async_executor.is_available():
+            return "async"
+
+        # Fallback to sync
+        return "sync"
+
+    def _fallback_to_sync(
+        self,
+        templates_dir: Path,
+        base_agent_path: Path,
+        working_directory: Path,
+        target_dir: Optional[Path],
+        force_rebuild: bool,
+        deployment_mode: str,
+        config: Optional[Config],
+        original_error: Exception,
+    ) -> Dict[str, Any]:
+        """Fallback to sync deployment when async fails.
+
+        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
+            config: Optional configuration
+            original_error: The original error that caused fallback
+
+        Returns:
+            Deployment results from sync executor
+        """
+        try:
+            results = self.sync_executor.execute_deployment(
+                templates_dir=templates_dir,
+                base_agent_path=base_agent_path,
+                working_directory=working_directory,
+                target_dir=target_dir,
+                force_rebuild=force_rebuild,
+                deployment_mode=deployment_mode,
+                config=config,
+            )
+
+            # Add fallback metadata
+            if "metadata" not in results:
+                results["metadata"] = {}
+
+            results["metadata"]["fallback_from"] = "async"
+            results["metadata"]["original_error"] = str(original_error)
+            results["metadata"]["fallback_successful"] = results.get("success", False)
+
+            return results
+
+        except Exception as fallback_error:
+            self.logger.error(f"Fallback to sync also failed: {fallback_error}")
+            return {
+                "success": False,
+                "error": f"Both async and sync deployment failed. Async: {original_error}, Sync: {fallback_error}",
+                "deployed": [],
+                "updated": [],
+                "migrated": [],
+                "skipped": [],
+                "errors": [str(original_error), str(fallback_error)],
+                "metadata": {
+                    "facade_version": "1.0.0",
+                    "selected_executor": "async",
+                    "fallback_attempted": True,
+                    "fallback_successful": False,
+                    "original_error": str(original_error),
+                    "fallback_error": str(fallback_error),
+                },
+            }

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

@@ -0,0 +1,178 @@
+"""Synchronous 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 SyncDeploymentExecutor(DeploymentExecutor):
+    """Synchronous deployment executor.
+
+    This executor uses the standard synchronous deployment pipeline
+    for reliable, sequential processing of agents.
+    """
+
+    def __init__(self, pipeline_builder, pipeline_executor):
+        """Initialize sync deployment executor.
+
+        Args:
+            pipeline_builder: Pipeline builder for creating deployment pipelines
+            pipeline_executor: Pipeline executor for running pipelines
+        """
+        self.pipeline_builder = pipeline_builder
+        self.pipeline_executor = pipeline_executor
+        self.logger = get_logger(__name__)
+
+    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 synchronous 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
+        """
+        self.logger.info("Executing synchronous deployment")
+
+        try:
+            # Build deployment pipeline
+            pipeline = self.pipeline_builder.create_standard_pipeline()
+
+            # Create pipeline context
+            from claude_mpm.services.agents.deployment.pipeline import PipelineContext
+
+            context = PipelineContext(
+                templates_dir=templates_dir,
+                base_agent_path=base_agent_path,
+                working_directory=working_directory,
+                target_dir=target_dir,
+                force_rebuild=force_rebuild,
+                deployment_mode=deployment_mode,
+                config=config,
+            )
+
+            # Execute pipeline
+            pipeline_result = self.pipeline_executor.execute(pipeline, context)
+
+            # Convert pipeline result to deployment result format
+            deployment_result = self._convert_pipeline_result(pipeline_result, context)
+
+            # Add executor metadata
+            deployment_result["metadata"]["executor"] = self.get_executor_name()
+            deployment_result["metadata"]["execution_mode"] = "synchronous"
+
+            return deployment_result
+
+        except Exception as e:
+            self.logger.error(f"Synchronous 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": "synchronous",
+                    "error_type": type(e).__name__,
+                },
+            }
+
+    def _convert_pipeline_result(self, pipeline_result, context) -> Dict[str, Any]:
+        """Convert pipeline result to deployment result format.
+
+        Args:
+            pipeline_result: Result from pipeline execution (dict)
+            context: Pipeline context with results
+
+        Returns:
+            Deployment result dictionary
+        """
+        # Extract pipeline execution info
+        pipeline_exec = pipeline_result.get("pipeline_execution", {})
+
+        # Extract results from pipeline result
+        deployed = pipeline_result.get("deployed", [])
+        updated = pipeline_result.get("updated", [])
+        migrated = pipeline_result.get("migrated", [])
+        skipped = pipeline_result.get("skipped", [])
+        errors = pipeline_result.get("errors", [])
+
+        return {
+            "success": pipeline_exec.get("success", False),
+            "target_dir": (
+                str(context.actual_target_dir)
+                if hasattr(context, "actual_target_dir")
+                else None
+            ),
+            "deployed": deployed,
+            "updated": updated,
+            "migrated": migrated,
+            "skipped": skipped,
+            "errors": errors,
+            "warnings": getattr(context, "warnings", []),
+            "metrics": {
+                "total_steps": pipeline_exec.get("total_steps", 0),
+                "executed_steps": pipeline_exec.get("executed_steps", []),
+                "failed_steps": pipeline_exec.get("failed_steps", []),
+                "total_execution_time": pipeline_exec.get("total_execution_time", 0),
+                "step_timings": getattr(context, "step_timings", {}),
+                "deployment_time": pipeline_result.get("deployment_time", 0),
+            },
+            "metadata": {
+                "pipeline_execution": pipeline_exec,
+                "step_timings": getattr(context, "step_timings", {}),
+            },
+        }
+
+    def is_available(self) -> bool:
+        """Sync executor is always available.
+
+        Returns:
+            True - sync execution is always available
+        """
+        return True
+
+    def get_executor_name(self) -> str:
+        """Get executor name.
+
+        Returns:
+            Executor name
+        """
+        return "sync"
+
+    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.0,  # Baseline
+            "memory_usage": "normal",
+            "reliability": "high",
+            "description": "Sequential processing with high reliability",
+        }