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

claude_mpm/services/agents/deployment/interface_adapter.py

@@ -0,0 +1,227 @@
+"""Interface adapter for AgentDeploymentService compliance."""
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from claude_mpm.core.interfaces import AgentDeploymentInterface
+from claude_mpm.core.logger import get_logger
+
+
+class AgentDeploymentInterfaceAdapter(AgentDeploymentInterface):
+    """Adapter to make AgentDeploymentService compliant with AgentDeploymentInterface.
+
+    This adapter bridges the gap between the current implementation's method
+    signatures and the required interface signatures, providing a clean
+    interface compliance layer.
+    """
+
+    def __init__(self, deployment_service):
+        """Initialize the interface adapter.
+
+        Args:
+            deployment_service: The actual deployment service implementation
+        """
+        self.deployment_service = deployment_service
+        self.logger = get_logger(__name__)
+
+    def deploy_agents(
+        self, force: bool = False, include_all: bool = False
+    ) -> Dict[str, Any]:
+        """Deploy agents to target environment.
+
+        This method adapts the interface signature to the actual implementation.
+
+        Args:
+            force: Force deployment even if agents already exist
+            include_all: Include all agents, ignoring exclusion lists
+
+        Returns:
+            Dictionary with deployment results and status
+        """
+        try:
+            # Map interface parameters to implementation parameters
+            force_rebuild = force
+
+            # Determine deployment mode based on include_all
+            deployment_mode = "project" if include_all else "update"
+
+            # Call the actual implementation
+            results = self.deployment_service.deploy_agents(
+                target_dir=None,  # Use default target directory
+                force_rebuild=force_rebuild,
+                deployment_mode=deployment_mode,
+                config=None,  # Use default configuration
+                use_async=False,  # Default to sync for interface compliance
+            )
+
+            # Ensure the result has the expected structure
+            if not isinstance(results, dict):
+                return {
+                    "success": False,
+                    "error": "Invalid result format from deployment service",
+                    "deployed": [],
+                    "updated": [],
+                    "migrated": [],
+                    "skipped": [],
+                    "errors": ["Invalid result format"],
+                }
+
+            # Add interface compliance metadata
+            results["interface_version"] = "1.0.0"
+            results["adapter_used"] = True
+
+            return results
+
+        except Exception as e:
+            self.logger.error(
+                f"Interface adapter deployment failed: {e}", exc_info=True
+            )
+            return {
+                "success": False,
+                "error": str(e),
+                "deployed": [],
+                "updated": [],
+                "migrated": [],
+                "skipped": [],
+                "errors": [str(e)],
+                "interface_version": "1.0.0",
+                "adapter_used": True,
+            }
+
+    def validate_agent(self, agent_path: Path) -> Tuple[bool, List[str]]:
+        """Validate agent configuration and structure.
+
+        Args:
+            agent_path: Path to agent configuration file
+
+        Returns:
+            Tuple of (is_valid, list_of_errors)
+        """
+        try:
+            # Delegate to the actual implementation
+            return self.deployment_service.validate_agent(agent_path)
+        except Exception as e:
+            self.logger.error(f"Agent validation failed: {e}", exc_info=True)
+            return False, [f"Validation error: {str(e)}"]
+
+    def clean_deployment(self, preserve_user_agents: bool = True) -> bool:
+        """Clean up deployed agents.
+
+        Args:
+            preserve_user_agents: Whether to keep user-created agents
+
+        Returns:
+            True if cleanup successful
+        """
+        try:
+            # Check if the deployment service has a clean_deployment method
+            if hasattr(self.deployment_service, "clean_deployment"):
+                # Call the existing method (it has a different signature)
+                result = self.deployment_service.clean_deployment()
+
+                # The existing method returns a dict, we need to return a bool
+                if isinstance(result, dict):
+                    return result.get("success", False)
+                else:
+                    return bool(result)
+            else:
+                # Implement basic cleanup logic if method doesn't exist
+                return self._basic_cleanup(preserve_user_agents)
+
+        except Exception as e:
+            self.logger.error(f"Deployment cleanup failed: {e}", exc_info=True)
+            return False
+
+    def _basic_cleanup(self, preserve_user_agents: bool) -> bool:
+        """Basic cleanup implementation.
+
+        Args:
+            preserve_user_agents: Whether to keep user-created agents
+
+        Returns:
+            True if cleanup successful
+        """
+        try:
+            # Get the working directory from the deployment service
+            working_dir = getattr(
+                self.deployment_service, "working_directory", Path.cwd()
+            )
+            agents_dir = working_dir / ".claude" / "agents"
+
+            if not agents_dir.exists():
+                self.logger.info("No agents directory to clean")
+                return True
+
+            cleaned_count = 0
+
+            # Clean up agent files
+            for agent_file in agents_dir.glob("*.md"):
+                try:
+                    if preserve_user_agents:
+                        # Check if this is a system agent (authored by claude-mpm)
+                        content = agent_file.read_text(encoding="utf-8")
+                        if (
+                            "author: claude-mpm" not in content
+                            and "author: 'claude-mpm'" not in content
+                        ):
+                            self.logger.debug(
+                                f"Preserving user agent: {agent_file.name}"
+                            )
+                            continue
+
+                    # Remove the agent file
+                    agent_file.unlink()
+                    cleaned_count += 1
+                    self.logger.debug(f"Cleaned agent: {agent_file.name}")
+
+                except Exception as e:
+                    self.logger.warning(f"Failed to clean agent {agent_file.name}: {e}")
+
+            self.logger.info(f"Cleaned {cleaned_count} agent files")
+            return True
+
+        except Exception as e:
+            self.logger.error(f"Basic cleanup failed: {e}", exc_info=True)
+            return False
+
+    def get_deployment_status(self) -> Dict[str, Any]:
+        """Get current deployment status and metrics.
+
+        Returns:
+            Dictionary with deployment status information
+        """
+        try:
+            # Delegate to the actual implementation
+            status = self.deployment_service.get_deployment_status()
+
+            # Ensure the result is a dictionary
+            if not isinstance(status, dict):
+                return {
+                    "status": "unknown",
+                    "error": "Invalid status format from deployment service",
+                    "interface_version": "1.0.0",
+                    "adapter_used": True,
+                }
+
+            # Add interface compliance metadata
+            status["interface_version"] = "1.0.0"
+            status["adapter_used"] = True
+
+            return status
+
+        except Exception as e:
+            self.logger.error(f"Failed to get deployment status: {e}", exc_info=True)
+            return {
+                "status": "error",
+                "error": str(e),
+                "interface_version": "1.0.0",
+                "adapter_used": True,
+            }
+
+    def get_wrapped_service(self):
+        """Get the wrapped deployment service.
+
+        Returns:
+            The actual deployment service implementation
+        """
+        return self.deployment_service

claude_mpm/services/agents/deployment/lifecycle_health_checker.py

@@ -0,0 +1,85 @@
+"""Health checker for agent lifecycle manager.
+
+This module provides health checking functionality for the AgentLifecycleManager.
+Extracted to reduce complexity and improve maintainability.
+"""
+
+from typing import TYPE_CHECKING, Dict
+
+if TYPE_CHECKING:
+    from .agent_lifecycle_manager import AgentLifecycleManager
+
+
+class LifecycleHealthChecker:
+    """Handles health checking for the lifecycle manager."""
+
+    def __init__(self, lifecycle_manager: "AgentLifecycleManager"):
+        """Initialize the health checker."""
+        self.lifecycle_manager = lifecycle_manager
+        self.logger = lifecycle_manager.logger
+
+    async def perform_health_check(self) -> Dict[str, bool]:
+        """Perform comprehensive health checks."""
+        checks = {}
+
+        try:
+            # Check core service availability
+            checks["cache_service"] = self.lifecycle_manager.shared_cache is not None
+            checks["registry_service"] = (
+                self.lifecycle_manager.agent_registry is not None
+            )
+            checks["tracker_service"] = (
+                self.lifecycle_manager.modification_tracker is not None
+            )
+            checks["persistence_service"] = (
+                self.lifecycle_manager.persistence_service is not None
+            )
+
+            # Check operation capabilities
+            checks["can_create_agents"] = await self._test_create_capability()
+            checks["can_modify_agents"] = await self._test_modify_capability()
+            checks["can_delete_agents"] = await self._test_delete_capability()
+
+            # Check data integrity
+            checks["agent_records_valid"] = (
+                len(self.lifecycle_manager.agent_records) >= 0
+            )
+            checks["operation_history_valid"] = (
+                len(self.lifecycle_manager.operation_history) >= 0
+            )
+
+        except Exception as e:
+            self.logger.error(f"Lifecycle manager health check failed: {e}")
+            checks["health_check_error"] = False
+
+        return checks
+
+    async def _test_create_capability(self) -> bool:
+        """Test agent creation capability."""
+        try:
+            # This would test if we can create agents in the configured tiers
+            return (
+                self.lifecycle_manager.modification_tracker is not None
+                and self.lifecycle_manager.persistence_service is not None
+            )
+        except Exception:
+            return False
+
+    async def _test_modify_capability(self) -> bool:
+        """Test agent modification capability."""
+        try:
+            # This would test if we can modify existing agents
+            return (
+                self.lifecycle_manager.modification_tracker is not None
+                and self.lifecycle_manager.persistence_service is not None
+            )
+        except Exception:
+            return False
+
+    async def _test_delete_capability(self) -> bool:
+        """Test agent deletion capability."""
+        try:
+            # This would test if we can delete agents
+            return self.lifecycle_manager.modification_tracker is not None
+        except Exception:
+            return False

claude_mpm/services/agents/deployment/lifecycle_performance_tracker.py

@@ -0,0 +1,100 @@
+"""Performance tracking for agent lifecycle manager.
+
+This module provides performance metrics tracking functionality for the AgentLifecycleManager.
+Extracted to reduce complexity and improve maintainability.
+"""
+
+from typing import TYPE_CHECKING, Any, Dict
+
+if TYPE_CHECKING:
+    from .agent_lifecycle_manager import LifecycleOperationResult
+
+
+class LifecyclePerformanceTracker:
+    """Handles performance metrics tracking for the lifecycle manager."""
+
+    def __init__(self, performance_metrics: Dict[str, Any]):
+        """Initialize the performance tracker."""
+        self.performance_metrics = performance_metrics
+
+    def update_metrics(self, result: "LifecycleOperationResult") -> None:
+        """Update performance metrics with operation result.
+
+        METRICS COLLECTION:
+        This method demonstrates a simple ETL pipeline for operational metrics:
+
+        1. EXTRACT: Pull raw data from operation results
+           - Success/failure status
+           - Operation duration
+           - Cache invalidation events
+           - Operation type and agent tier
+
+        2. TRANSFORM: Calculate derived metrics
+           - Success rates and failure percentages
+           - Rolling averages for performance
+           - Operation distribution by type
+           - Performance by agent tier
+
+        3. LOAD: Store in metrics structure
+           - In-memory storage for real-time access
+           - Could be extended to push to:
+             * Time-series databases (Prometheus, InfluxDB)
+             * AI observability platforms (Datadog, New Relic)
+             * Custom analytics pipelines
+
+        OPTIMIZATION OPPORTUNITIES:
+        - Add percentile calculations (p50, p95, p99)
+        - Track operation queuing times
+        - Monitor resource usage per operation
+        - Implement sliding window metrics
+        """
+        self.performance_metrics["total_operations"] += 1
+
+        if result.success:
+            self.performance_metrics["successful_operations"] += 1
+        else:
+            self.performance_metrics["failed_operations"] += 1
+
+        # Update average duration using incremental calculation
+        # This avoids storing all durations in memory
+        total_ops = self.performance_metrics["total_operations"]
+        current_avg = self.performance_metrics["average_duration_ms"]
+        new_avg = ((current_avg * (total_ops - 1)) + result.duration_ms) / total_ops
+        self.performance_metrics["average_duration_ms"] = new_avg
+
+        # METRICS: Track operation type distribution
+        # This helps identify which operations are most common
+        op_type = result.operation.value
+        if "operation_distribution" not in self.performance_metrics:
+            self.performance_metrics["operation_distribution"] = {}
+        self.performance_metrics["operation_distribution"][op_type] = (
+            self.performance_metrics["operation_distribution"].get(op_type, 0) + 1
+        )
+
+        # METRICS: Track performance by agent tier
+        # Useful for identifying tier-specific performance issues
+        if hasattr(result, "tier") and result.tier:
+            if "tier_performance" not in self.performance_metrics:
+                self.performance_metrics["tier_performance"] = {}
+            tier_name = (
+                result.tier.value if hasattr(result.tier, "value") else str(result.tier)
+            )
+            if tier_name not in self.performance_metrics["tier_performance"]:
+                self.performance_metrics["tier_performance"][tier_name] = {
+                    "count": 0,
+                    "total_duration_ms": 0,
+                    "average_duration_ms": 0,
+                }
+            tier_metrics = self.performance_metrics["tier_performance"][tier_name]
+            tier_metrics["count"] += 1
+            tier_metrics["total_duration_ms"] += result.duration_ms
+            tier_metrics["average_duration_ms"] = (
+                tier_metrics["total_duration_ms"] / tier_metrics["count"]
+            )
+
+        # Update cache hit rate if cache was involved
+        if result.cache_invalidated:
+            # Track cache invalidation frequency
+            if "cache_invalidations" not in self.performance_metrics:
+                self.performance_metrics["cache_invalidations"] = 0
+            self.performance_metrics["cache_invalidations"] += 1

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

@@ -0,0 +1,32 @@
+"""Deployment pipeline for agent deployment.
+
+This module provides a pipeline-based approach to agent deployment,
+breaking down the complex deployment process into discrete, testable steps.
+
+The pipeline pattern allows for:
+- Modular deployment steps that can be tested independently
+- Configurable deployment flows for different scenarios
+- Easy addition of new deployment steps
+- Better error handling and recovery
+- Comprehensive logging and metrics collection
+"""
+
+from .pipeline_builder import DeploymentPipelineBuilder
+from .pipeline_context import PipelineContext
+from .pipeline_executor import DeploymentPipelineExecutor
+from .steps import (
+    BaseDeploymentStep,
+    ConfigurationLoadStep,
+    StepResult,
+    TargetDirectorySetupStep,
+)
+
+__all__ = [
+    "DeploymentPipelineBuilder",
+    "DeploymentPipelineExecutor",
+    "PipelineContext",
+    "BaseDeploymentStep",
+    "StepResult",
+    "ConfigurationLoadStep",
+    "TargetDirectorySetupStep",
+]

claude_mpm/services/agents/deployment/pipeline/pipeline_builder.py

@@ -0,0 +1,158 @@
+"""Pipeline builder for creating deployment pipelines."""
+
+from typing import Any, Dict, List, Type
+
+from claude_mpm.core.logger import get_logger
+
+from .steps.base_step import BaseDeploymentStep
+from .steps.configuration_step import ConfigurationLoadStep
+from .steps.target_directory_step import TargetDirectorySetupStep
+
+
+class DeploymentPipelineBuilder:
+    """Builder for creating deployment pipelines.
+
+    This builder allows for flexible construction of deployment pipelines
+    with different steps based on deployment requirements.
+    """
+
+    def __init__(self):
+        """Initialize the pipeline builder."""
+        self.logger = get_logger(__name__)
+        self._steps: List[BaseDeploymentStep] = []
+        self._step_registry: Dict[str, Type[BaseDeploymentStep]] = {}
+
+        # Register default steps
+        self._register_default_steps()
+
+    def _register_default_steps(self) -> None:
+        """Register default deployment steps."""
+        self._step_registry.update(
+            {
+                "configuration": ConfigurationLoadStep,
+                "target_directory": TargetDirectorySetupStep,
+                # Additional steps will be registered as they're created
+            }
+        )
+
+    def add_step(self, step: BaseDeploymentStep) -> "DeploymentPipelineBuilder":
+        """Add a step to the pipeline.
+
+        Args:
+            step: The deployment step to add
+
+        Returns:
+            Self for method chaining
+        """
+        self._steps.append(step)
+        self.logger.debug(f"Added step: {step.name}")
+        return self
+
+    def add_step_by_name(self, step_name: str, **kwargs) -> "DeploymentPipelineBuilder":
+        """Add a step by its registered name.
+
+        Args:
+            step_name: Name of the registered step
+            **kwargs: Arguments to pass to the step constructor
+
+        Returns:
+            Self for method chaining
+
+        Raises:
+            ValueError: If step name is not registered
+        """
+        if step_name not in self._step_registry:
+            raise ValueError(f"Unknown step name: {step_name}")
+
+        step_class = self._step_registry[step_name]
+        step = step_class(**kwargs)
+        return self.add_step(step)
+
+    def create_standard_pipeline(self) -> List[BaseDeploymentStep]:
+        """Create a standard deployment pipeline with all common steps.
+
+        Returns:
+            List of deployment steps in execution order
+        """
+        return [
+            ConfigurationLoadStep(),
+            TargetDirectorySetupStep(),
+            # Additional steps will be added as they're implemented
+        ]
+
+    def create_minimal_pipeline(self) -> List[BaseDeploymentStep]:
+        """Create a minimal deployment pipeline with only essential steps.
+
+        Returns:
+            List of essential deployment steps
+        """
+        return [
+            ConfigurationLoadStep(),
+            TargetDirectorySetupStep(),
+        ]
+
+    def create_custom_pipeline(self, step_names: List[str]) -> List[BaseDeploymentStep]:
+        """Create a custom pipeline from step names.
+
+        Args:
+            step_names: List of step names to include in the pipeline
+
+        Returns:
+            List of deployment steps
+
+        Raises:
+            ValueError: If any step name is not registered
+        """
+        steps = []
+        for step_name in step_names:
+            if step_name not in self._step_registry:
+                raise ValueError(f"Unknown step name: {step_name}")
+
+            step_class = self._step_registry[step_name]
+            steps.append(step_class())
+
+        return steps
+
+    def build(self) -> List[BaseDeploymentStep]:
+        """Build the pipeline from added steps.
+
+        Returns:
+            List of deployment steps in the order they were added
+        """
+        if not self._steps:
+            self.logger.warning(
+                "No steps added to pipeline, creating standard pipeline"
+            )
+            return self.create_standard_pipeline()
+
+        # Sort steps based on dependencies (simplified for now)
+        # In a full implementation, this would do topological sorting
+        return self._steps.copy()
+
+    def register_step(self, name: str, step_class: Type[BaseDeploymentStep]) -> None:
+        """Register a new step type.
+
+        Args:
+            name: Name to register the step under
+            step_class: The step class to register
+        """
+        self._step_registry[name] = step_class
+        self.logger.debug(f"Registered step: {name} -> {step_class.__name__}")
+
+    def get_registered_steps(self) -> Dict[str, Type[BaseDeploymentStep]]:
+        """Get all registered step types.
+
+        Returns:
+            Dictionary of step names to step classes
+        """
+        return self._step_registry.copy()
+
+    def clear(self) -> "DeploymentPipelineBuilder":
+        """Clear all added steps.
+
+        Returns:
+            Self for method chaining
+        """
+        self._steps.clear()
+        self.logger.debug("Cleared all steps from pipeline builder")
+        return self