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

claude_mpm/services/agents/deployment/results/deployment_metrics.py

@@ -0,0 +1,200 @@
+"""Deployment metrics data class."""
+
+import time
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class DeploymentMetrics:
+    """Metrics collected during agent deployment.
+
+    This class encapsulates all metrics and timing information
+    collected during the deployment process.
+    """
+
+    # Timing metrics
+    start_time: float = field(default_factory=time.time)
+    end_time: Optional[float] = None
+    total_duration: Optional[float] = None
+
+    # Step timing metrics
+    step_timings: Dict[str, float] = field(default_factory=dict)
+
+    # Agent metrics
+    total_agents: int = 0
+    deployed_agents: int = 0
+    updated_agents: int = 0
+    migrated_agents: int = 0
+    skipped_agents: int = 0
+    repaired_agents: int = 0
+    failed_agents: int = 0
+
+    # Agent lists for detailed tracking
+    deployed_agent_names: List[str] = field(default_factory=list)
+    updated_agent_names: List[str] = field(default_factory=list)
+    migrated_agent_names: List[str] = field(default_factory=list)
+    skipped_agent_names: List[str] = field(default_factory=list)
+    repaired_agent_names: List[str] = field(default_factory=list)
+    failed_agent_names: List[str] = field(default_factory=list)
+
+    # Error and warning tracking
+    errors: List[str] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+
+    # Performance metrics
+    average_agent_deployment_time: Optional[float] = None
+    fastest_agent_deployment: Optional[float] = None
+    slowest_agent_deployment: Optional[float] = None
+
+    # Strategy and configuration info
+    strategy_used: Optional[str] = None
+    deployment_mode: Optional[str] = None
+    target_directory: Optional[str] = None
+
+    # Additional metadata
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def finalize(self, end_time: Optional[float] = None) -> None:
+        """Finalize metrics calculation.
+
+        Args:
+            end_time: Optional end time, defaults to current time
+        """
+        if end_time is None:
+            end_time = time.time()
+
+        self.end_time = end_time
+        self.total_duration = end_time - self.start_time
+
+        # Calculate performance metrics
+        if self.step_timings:
+            agent_times = [
+                t for name, t in self.step_timings.items() if "agent" in name.lower()
+            ]
+            if agent_times:
+                self.average_agent_deployment_time = sum(agent_times) / len(agent_times)
+                self.fastest_agent_deployment = min(agent_times)
+                self.slowest_agent_deployment = max(agent_times)
+
+    def add_deployed_agent(
+        self, agent_name: str, deployment_time: Optional[float] = None
+    ) -> None:
+        """Add a deployed agent to metrics.
+
+        Args:
+            agent_name: Name of the deployed agent
+            deployment_time: Time taken to deploy the agent
+        """
+        self.deployed_agents += 1
+        self.deployed_agent_names.append(agent_name)
+
+        if deployment_time is not None:
+            self.step_timings[f"agent_{agent_name}"] = deployment_time
+
+    def add_updated_agent(
+        self, agent_name: str, deployment_time: Optional[float] = None
+    ) -> None:
+        """Add an updated agent to metrics.
+
+        Args:
+            agent_name: Name of the updated agent
+            deployment_time: Time taken to update the agent
+        """
+        self.updated_agents += 1
+        self.updated_agent_names.append(agent_name)
+
+        if deployment_time is not None:
+            self.step_timings[f"agent_{agent_name}"] = deployment_time
+
+    def add_migrated_agent(self, agent_name: str) -> None:
+        """Add a migrated agent to metrics.
+
+        Args:
+            agent_name: Name of the migrated agent
+        """
+        self.migrated_agents += 1
+        self.migrated_agent_names.append(agent_name)
+
+    def add_skipped_agent(self, agent_name: str, reason: Optional[str] = None) -> None:
+        """Add a skipped agent to metrics.
+
+        Args:
+            agent_name: Name of the skipped agent
+            reason: Optional reason for skipping
+        """
+        self.skipped_agents += 1
+        self.skipped_agent_names.append(agent_name)
+
+        if reason:
+            self.metadata[f"skip_reason_{agent_name}"] = reason
+
+    def add_repaired_agent(self, agent_name: str) -> None:
+        """Add a repaired agent to metrics.
+
+        Args:
+            agent_name: Name of the repaired agent
+        """
+        self.repaired_agents += 1
+        self.repaired_agent_names.append(agent_name)
+
+    def add_failed_agent(self, agent_name: str, error: str) -> None:
+        """Add a failed agent to metrics.
+
+        Args:
+            agent_name: Name of the failed agent
+            error: Error message
+        """
+        self.failed_agents += 1
+        self.failed_agent_names.append(agent_name)
+        self.errors.append(f"Agent {agent_name}: {error}")
+
+    def add_error(self, error: str) -> None:
+        """Add a general error to metrics.
+
+        Args:
+            error: Error message
+        """
+        self.errors.append(error)
+
+    def add_warning(self, warning: str) -> None:
+        """Add a warning to metrics.
+
+        Args:
+            warning: Warning message
+        """
+        self.warnings.append(warning)
+
+    def get_success_rate(self) -> float:
+        """Calculate deployment success rate.
+
+        Returns:
+            Success rate as a percentage (0-100)
+        """
+        if self.total_agents == 0:
+            return 100.0
+
+        successful = self.deployed_agents + self.updated_agents + self.skipped_agents
+        return (successful / self.total_agents) * 100.0
+
+    def get_summary(self) -> Dict[str, Any]:
+        """Get a summary of deployment metrics.
+
+        Returns:
+            Dictionary with metric summary
+        """
+        return {
+            "total_duration": self.total_duration,
+            "total_agents": self.total_agents,
+            "deployed": self.deployed_agents,
+            "updated": self.updated_agents,
+            "migrated": self.migrated_agents,
+            "skipped": self.skipped_agents,
+            "repaired": self.repaired_agents,
+            "failed": self.failed_agents,
+            "success_rate": self.get_success_rate(),
+            "error_count": len(self.errors),
+            "warning_count": len(self.warnings),
+            "strategy_used": self.strategy_used,
+            "deployment_mode": self.deployment_mode,
+        }

claude_mpm/services/agents/deployment/results/deployment_result_builder.py

@@ -0,0 +1,249 @@
+"""Deployment result builder for creating structured deployment results."""
+
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from claude_mpm.core.logger import get_logger
+
+from .deployment_metrics import DeploymentMetrics
+
+
+class DeploymentResultBuilder:
+    """Builder for creating structured deployment results.
+
+    This class provides a clean interface for building deployment
+    results with proper structure and metrics collection.
+    """
+
+    def __init__(self):
+        """Initialize the deployment result builder."""
+        self.logger = get_logger(__name__)
+        self.metrics = DeploymentMetrics()
+        self._results: Dict[str, Any] = {}
+        self._initialized = False
+
+    def initialize(
+        self,
+        target_dir: Optional[Path] = None,
+        strategy_name: Optional[str] = None,
+        deployment_mode: Optional[str] = None,
+    ) -> "DeploymentResultBuilder":
+        """Initialize the result builder with basic information.
+
+        Args:
+            target_dir: Target directory for deployment
+            strategy_name: Name of deployment strategy used
+            deployment_mode: Deployment mode used
+
+        Returns:
+            Self for method chaining
+        """
+        self._results = {
+            "target_dir": str(target_dir) if target_dir else "",
+            "deployed": [],
+            "updated": [],
+            "migrated": [],
+            "skipped": [],
+            "errors": [],
+            "warnings": [],
+            "repaired": [],
+            "total": 0,
+            "deployment_time": 0.0,
+            "strategy_used": strategy_name or "Unknown",
+            "deployment_mode": deployment_mode or "update",
+        }
+
+        # Update metrics
+        self.metrics.strategy_used = strategy_name
+        self.metrics.deployment_mode = deployment_mode
+        self.metrics.target_directory = str(target_dir) if target_dir else None
+
+        self._initialized = True
+        self.logger.debug("Result builder initialized")
+        return self
+
+    def set_total_agents(self, total: int) -> "DeploymentResultBuilder":
+        """Set the total number of agents being processed.
+
+        Args:
+            total: Total number of agents
+
+        Returns:
+            Self for method chaining
+        """
+        self._results["total"] = total
+        self.metrics.total_agents = total
+        return self
+
+    def add_deployed_agent(
+        self, agent_name: str, deployment_time: Optional[float] = None
+    ) -> "DeploymentResultBuilder":
+        """Add a deployed agent to results.
+
+        Args:
+            agent_name: Name of the deployed agent
+            deployment_time: Time taken to deploy the agent
+
+        Returns:
+            Self for method chaining
+        """
+        self._results["deployed"].append(agent_name)
+        self.metrics.add_deployed_agent(agent_name, deployment_time)
+        return self
+
+    def add_updated_agent(
+        self, agent_name: str, deployment_time: Optional[float] = None
+    ) -> "DeploymentResultBuilder":
+        """Add an updated agent to results.
+
+        Args:
+            agent_name: Name of the updated agent
+            deployment_time: Time taken to update the agent
+
+        Returns:
+            Self for method chaining
+        """
+        self._results["updated"].append(agent_name)
+        self.metrics.add_updated_agent(agent_name, deployment_time)
+        return self
+
+    def add_migrated_agent(self, agent_name: str) -> "DeploymentResultBuilder":
+        """Add a migrated agent to results.
+
+        Args:
+            agent_name: Name of the migrated agent
+
+        Returns:
+            Self for method chaining
+        """
+        self._results["migrated"].append(agent_name)
+        self.metrics.add_migrated_agent(agent_name)
+        return self
+
+    def add_skipped_agent(
+        self, agent_name: str, reason: Optional[str] = None
+    ) -> "DeploymentResultBuilder":
+        """Add a skipped agent to results.
+
+        Args:
+            agent_name: Name of the skipped agent
+            reason: Optional reason for skipping
+
+        Returns:
+            Self for method chaining
+        """
+        self._results["skipped"].append(agent_name)
+        self.metrics.add_skipped_agent(agent_name, reason)
+        return self
+
+    def add_repaired_agent(self, agent_name: str) -> "DeploymentResultBuilder":
+        """Add a repaired agent to results.
+
+        Args:
+            agent_name: Name of the repaired agent
+
+        Returns:
+            Self for method chaining
+        """
+        self._results["repaired"].append(agent_name)
+        self.metrics.add_repaired_agent(agent_name)
+        return self
+
+    def add_error(self, error: str) -> "DeploymentResultBuilder":
+        """Add an error to results.
+
+        Args:
+            error: Error message
+
+        Returns:
+            Self for method chaining
+        """
+        self._results["errors"].append(error)
+        self.metrics.add_error(error)
+        return self
+
+    def add_warning(self, warning: str) -> "DeploymentResultBuilder":
+        """Add a warning to results.
+
+        Args:
+            warning: Warning message
+
+        Returns:
+            Self for method chaining
+        """
+        self._results["warnings"].append(warning)
+        self.metrics.add_warning(warning)
+        return self
+
+    def add_step_timing(
+        self, step_name: str, duration: float
+    ) -> "DeploymentResultBuilder":
+        """Add timing information for a step.
+
+        Args:
+            step_name: Name of the step
+            duration: Duration in seconds
+
+        Returns:
+            Self for method chaining
+        """
+        self.metrics.step_timings[step_name] = duration
+        return self
+
+    def add_metadata(self, key: str, value: Any) -> "DeploymentResultBuilder":
+        """Add metadata to results.
+
+        Args:
+            key: Metadata key
+            value: Metadata value
+
+        Returns:
+            Self for method chaining
+        """
+        self.metrics.metadata[key] = value
+        return self
+
+    def build(self) -> Dict[str, Any]:
+        """Build the final results dictionary.
+
+        Returns:
+            Complete deployment results dictionary
+        """
+        if not self._initialized:
+            self.logger.warning("Result builder not initialized, using defaults")
+            self.initialize()
+
+        # Finalize metrics
+        self.metrics.finalize()
+
+        # Update results with final timing
+        self._results["deployment_time"] = self.metrics.total_duration or 0.0
+
+        # Add step timings if available
+        if self.metrics.step_timings:
+            self._results["step_timings"] = self.metrics.step_timings.copy()
+
+        # Add metrics summary
+        self._results["metrics"] = self.metrics.get_summary()
+
+        # Add detailed metrics if requested
+        self._results["detailed_metrics"] = {
+            "deployed_agents": self.metrics.deployed_agent_names,
+            "updated_agents": self.metrics.updated_agent_names,
+            "migrated_agents": self.metrics.migrated_agent_names,
+            "skipped_agents": self.metrics.skipped_agent_names,
+            "repaired_agents": self.metrics.repaired_agent_names,
+            "failed_agents": self.metrics.failed_agent_names,
+            "success_rate": self.metrics.get_success_rate(),
+        }
+
+        self.logger.debug(f"Built deployment results with {len(self._results)} fields")
+        return self._results.copy()
+
+    def get_metrics(self) -> DeploymentMetrics:
+        """Get the metrics object.
+
+        Returns:
+            DeploymentMetrics object
+        """
+        return self.metrics

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

@@ -0,0 +1,25 @@
+"""Deployment strategy pattern for agent deployment.
+
+This module provides different deployment strategies for various scenarios:
+- SystemAgentDeploymentStrategy: For system-wide agent deployment
+- ProjectAgentDeploymentStrategy: For project-specific agent deployment
+- UserAgentDeploymentStrategy: For user-specific agent deployment
+
+The strategy pattern allows for clean separation of deployment logic
+and makes it easy to add new deployment types in the future.
+"""
+
+from .base_strategy import BaseDeploymentStrategy, DeploymentContext
+from .project_strategy import ProjectAgentDeploymentStrategy
+from .strategy_selector import DeploymentStrategySelector
+from .system_strategy import SystemAgentDeploymentStrategy
+from .user_strategy import UserAgentDeploymentStrategy
+
+__all__ = [
+    "BaseDeploymentStrategy",
+    "DeploymentContext",
+    "SystemAgentDeploymentStrategy",
+    "ProjectAgentDeploymentStrategy",
+    "UserAgentDeploymentStrategy",
+    "DeploymentStrategySelector",
+]

claude_mpm/services/agents/deployment/strategies/base_strategy.py

@@ -0,0 +1,119 @@
+"""Base deployment strategy interface and context."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from claude_mpm.core.config import Config
+
+
+@dataclass
+class DeploymentContext:
+    """Context object containing all deployment parameters."""
+
+    target_dir: Optional[Path] = None
+    force_rebuild: bool = False
+    deployment_mode: str = "update"
+    config: Optional[Config] = None
+    use_async: bool = False
+    working_directory: Optional[Path] = None
+    templates_dir: Optional[Path] = None
+    base_agent_path: Optional[Path] = None
+
+
+class BaseDeploymentStrategy(ABC):
+    """Base class for all deployment strategies.
+
+    This abstract base class defines the interface that all deployment
+    strategies must implement. Each strategy handles a specific type
+    of deployment (system, project, user) with its own logic.
+    """
+
+    def __init__(self, name: str):
+        """Initialize the deployment strategy.
+
+        Args:
+            name: Human-readable name for this strategy
+        """
+        self.name = name
+
+    @abstractmethod
+    def can_handle(self, context: DeploymentContext) -> bool:
+        """Check if this strategy can handle the given deployment context.
+
+        Args:
+            context: Deployment context with parameters
+
+        Returns:
+            True if this strategy should handle the deployment
+        """
+        pass
+
+    @abstractmethod
+    def determine_target_directory(self, context: DeploymentContext) -> Path:
+        """Determine the target directory for deployment.
+
+        Args:
+            context: Deployment context with parameters
+
+        Returns:
+            Path where agents should be deployed
+        """
+        pass
+
+    @abstractmethod
+    def get_templates_directory(self, context: DeploymentContext) -> Path:
+        """Get the templates directory for this deployment type.
+
+        Args:
+            context: Deployment context with parameters
+
+        Returns:
+            Path to the templates directory
+        """
+        pass
+
+    @abstractmethod
+    def get_excluded_agents(self, context: DeploymentContext) -> List[str]:
+        """Get list of agents to exclude for this deployment type.
+
+        Args:
+            context: Deployment context with parameters
+
+        Returns:
+            List of agent names to exclude from deployment
+        """
+        pass
+
+    @abstractmethod
+    def should_deploy_system_instructions(self, context: DeploymentContext) -> bool:
+        """Check if system instructions should be deployed.
+
+        Args:
+            context: Deployment context with parameters
+
+        Returns:
+            True if system instructions should be deployed
+        """
+        pass
+
+    @abstractmethod
+    def get_deployment_priority(self) -> int:
+        """Get the priority of this deployment strategy.
+
+        Lower numbers have higher priority. Used when multiple
+        strategies can handle the same context.
+
+        Returns:
+            Priority number (lower = higher priority)
+        """
+        pass
+
+    def __str__(self) -> str:
+        """String representation of the strategy."""
+        return f"{self.__class__.__name__}({self.name})"
+
+    def __repr__(self) -> str:
+        """Detailed string representation of the strategy."""
+        return f"{self.__class__.__name__}(name='{self.name}', priority={self.get_deployment_priority()})"