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

claude_mpm/services/core/models/__init__.py

@@ -0,0 +1,70 @@
+"""
+Core Models Package for Claude MPM Framework
+============================================
+
+WHY: This package contains data models used across the service layer.
+Models are organized by domain to maintain clear boundaries and enable
+independent evolution of different model types.
+
+DESIGN DECISION: Models are grouped by domain (toolchain, agent_config)
+to create logical cohesion and make it easier to understand dependencies
+between different parts of the system.
+
+Part of TSK-0054: Auto-Configuration Feature - Phase 1
+"""
+
+from .agent_config import (
+    AgentCapabilities,
+    AgentRecommendation,
+    ConfigurationPreview,
+    ConfigurationResult,
+    ValidationResult,
+)
+from .process import (
+    PROTECTED_PORT_RANGES,
+    DeploymentState,
+    ProcessInfo,
+    StartConfig,
+    is_port_protected,
+)
+from .restart import CircuitBreakerState, RestartAttempt, RestartConfig, RestartHistory
+from .stability import LogPatternMatch, MemoryTrend, ResourceUsage
+from .toolchain import (
+    ConfidenceLevel,
+    DeploymentTarget,
+    Framework,
+    LanguageDetection,
+    ToolchainAnalysis,
+    ToolchainComponent,
+)
+
+__all__ = [  # noqa: RUF022 - Grouped by category with comments for clarity
+    # Toolchain models
+    "ConfidenceLevel",
+    "ToolchainComponent",
+    "LanguageDetection",
+    "Framework",
+    "DeploymentTarget",
+    "ToolchainAnalysis",
+    # Agent configuration models
+    "AgentCapabilities",
+    "AgentRecommendation",
+    "ConfigurationResult",
+    "ValidationResult",
+    "ConfigurationPreview",
+    # Process management models
+    "DeploymentState",
+    "ProcessInfo",
+    "StartConfig",
+    "PROTECTED_PORT_RANGES",
+    "is_port_protected",
+    # Restart management models
+    "CircuitBreakerState",
+    "RestartAttempt",
+    "RestartHistory",
+    "RestartConfig",
+    # Stability monitoring models
+    "MemoryTrend",
+    "LogPatternMatch",
+    "ResourceUsage",
+]

claude_mpm/services/core/models/agent_config.py

@@ -0,0 +1,384 @@
+"""
+Agent Configuration Data Models for Claude MPM Framework
+========================================================
+
+WHY: These models represent agent capabilities, recommendations, and
+configuration results. They provide a standardized way to communicate
+agent suitability, deployment plans, and validation outcomes.
+
+DESIGN DECISION: Uses dataclasses with validation to ensure data consistency.
+Includes confidence scores and reasoning to enable transparent decision-making.
+Supports both successful and error states for robust error handling.
+
+Part of TSK-0054: Auto-Configuration Feature - Phase 1
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+from ....core.enums import OperationResult, ValidationSeverity
+
+# Backward compatibility alias (consolidated in Phase 3A Batch 25)
+ConfigurationStatus = OperationResult
+
+
+class AgentSpecialization(str, Enum):
+    """Agent specialization categories.
+
+    WHY: Agents have different areas of expertise. This enum provides
+    a standardized taxonomy for categorizing agent capabilities.
+    """
+
+    GENERAL = "general"
+    LANGUAGE_SPECIFIC = "language_specific"
+    FRAMEWORK_SPECIFIC = "framework_specific"
+    DEVOPS = "devops"
+    SECURITY = "security"
+    TESTING = "testing"
+    DOCUMENTATION = "documentation"
+    PERFORMANCE = "performance"
+
+
+@dataclass(frozen=True)
+class AgentCapabilities:
+    """Represents the capabilities of an agent.
+
+    WHY: Understanding what an agent can do is essential for matching
+    agents to projects. This model captures all relevant capability
+    information in a structured format.
+
+    DESIGN DECISION: Frozen to prevent modification of capability definitions.
+    Includes both broad categories (specializations) and specific skills
+    (languages, frameworks) to enable fine-grained matching.
+    """
+
+    agent_id: str
+    agent_name: str
+    specializations: List[AgentSpecialization] = field(default_factory=list)
+    supported_languages: List[str] = field(default_factory=list)
+    supported_frameworks: List[str] = field(default_factory=list)
+    required_tools: List[str] = field(default_factory=list)
+    optional_tools: List[str] = field(default_factory=list)
+    deployment_targets: List[str] = field(default_factory=list)
+    description: str = ""
+    strengths: List[str] = field(default_factory=list)
+    limitations: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Validate agent capabilities."""
+        if not self.agent_id or not self.agent_id.strip():
+            raise ValueError("Agent ID cannot be empty")
+        if not self.agent_name or not self.agent_name.strip():
+            raise ValueError("Agent name cannot be empty")
+
+    def supports_language(self, language: str) -> bool:
+        """Check if agent supports a specific language (case-insensitive)."""
+        return any(
+            lang.lower() == language.lower() for lang in self.supported_languages
+        )
+
+    def supports_framework(self, framework: str) -> bool:
+        """Check if agent supports a specific framework (case-insensitive)."""
+        return any(fw.lower() == framework.lower() for fw in self.supported_frameworks)
+
+    def has_specialization(self, specialization: AgentSpecialization) -> bool:
+        """Check if agent has a specific specialization."""
+        return specialization in self.specializations
+
+
+@dataclass
+class AgentRecommendation:
+    """Represents a recommended agent with reasoning.
+
+    WHY: Users need to understand why agents are recommended. This model
+    captures the recommendation along with confidence score, match reasoning,
+    and any warnings or considerations.
+
+    DESIGN DECISION: Includes detailed reasoning to support transparency
+    and enable users to make informed decisions. Confidence score enables
+    filtering and ranking of recommendations.
+    """
+
+    agent_id: str
+    agent_name: str
+    confidence_score: float  # 0.0-1.0
+    match_reasons: List[str] = field(default_factory=list)
+    concerns: List[str] = field(default_factory=list)
+    capabilities: Optional[AgentCapabilities] = None
+    deployment_priority: int = 1  # Lower = higher priority
+    configuration_hints: Dict[str, Any] = field(default_factory=dict)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Validate agent recommendation."""
+        if not self.agent_id or not self.agent_id.strip():
+            raise ValueError("Agent ID cannot be empty")
+        if not self.agent_name or not self.agent_name.strip():
+            raise ValueError("Agent name cannot be empty")
+        if not (0.0 <= self.confidence_score <= 1.0):
+            raise ValueError(
+                f"Confidence score must be 0.0-1.0, got {self.confidence_score}"
+            )
+        if self.deployment_priority < 1:
+            raise ValueError(
+                f"Deployment priority must be >= 1, got {self.deployment_priority}"
+            )
+
+    @property
+    def is_high_confidence(self) -> bool:
+        """Check if recommendation has high confidence (>= 0.8)."""
+        return self.confidence_score >= 0.8
+
+    @property
+    def is_medium_confidence(self) -> bool:
+        """Check if recommendation has medium confidence (0.5-0.8)."""
+        return 0.5 <= self.confidence_score < 0.8
+
+    @property
+    def is_low_confidence(self) -> bool:
+        """Check if recommendation has low confidence (< 0.5)."""
+        return self.confidence_score < 0.5
+
+    @property
+    def has_concerns(self) -> bool:
+        """Check if recommendation has any concerns."""
+        return len(self.concerns) > 0
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert recommendation to dictionary."""
+        return {
+            "agent_id": self.agent_id,
+            "agent_name": self.agent_name,
+            "confidence_score": self.confidence_score,
+            "match_reasons": self.match_reasons,
+            "concerns": self.concerns,
+            "deployment_priority": self.deployment_priority,
+            "configuration_hints": self.configuration_hints,
+        }
+
+
+@dataclass
+class ConfigurationResult:
+    """Result of automated configuration operation.
+
+    WHY: Configuration operations need to return comprehensive results
+    including what was deployed, what failed, and any warnings. This model
+    provides a complete picture of the configuration outcome.
+
+    DESIGN DECISION: Separates successful and failed deployments to enable
+    proper error handling. Includes validation results and user-facing
+    messages for transparency.
+
+    NOTE: Uses core OperationResult enum (consolidated from ConfigurationStatus
+    in Phase 3A Batch 25). Mappings:
+    - SUCCESS → OperationResult.SUCCESS
+    - PARTIAL_SUCCESS → OperationResult.WARNING (partial success with issues)
+    - FAILURE → OperationResult.FAILED
+    - VALIDATION_ERROR → OperationResult.ERROR
+    - USER_CANCELLED → OperationResult.CANCELLED
+    """
+
+    status: OperationResult
+    deployed_agents: List[str] = field(default_factory=list)
+    failed_agents: List[str] = field(default_factory=list)
+    validation_warnings: List[str] = field(default_factory=list)
+    validation_errors: List[str] = field(default_factory=list)
+    recommendations: List[AgentRecommendation] = field(default_factory=list)
+    message: str = ""
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def is_successful(self) -> bool:
+        """Check if configuration was completely successful."""
+        return self.status == OperationResult.SUCCESS
+
+    @property
+    def has_failures(self) -> bool:
+        """Check if any agents failed to deploy."""
+        return len(self.failed_agents) > 0
+
+    @property
+    def has_warnings(self) -> bool:
+        """Check if there are any warnings."""
+        return len(self.validation_warnings) > 0
+
+    @property
+    def deployment_count(self) -> int:
+        """Get number of successfully deployed agents."""
+        return len(self.deployed_agents)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert result to dictionary."""
+        return {
+            "status": self.status.value,
+            "deployed_agents": self.deployed_agents,
+            "failed_agents": self.failed_agents,
+            "validation_warnings": self.validation_warnings,
+            "validation_errors": self.validation_errors,
+            "message": self.message,
+            "deployment_count": self.deployment_count,
+        }
+
+
+@dataclass
+class ValidationIssue:
+    """Represents a validation issue.
+
+    WHY: Validation can identify multiple types of issues. This model
+    provides structured representation of issues with context and
+    suggested resolutions.
+    """
+
+    severity: ValidationSeverity
+    message: str
+    agent_id: Optional[str] = None
+    field: Optional[str] = None
+    suggested_fix: Optional[str] = None
+
+    def __post_init__(self):
+        """Validate issue data."""
+        if not self.message or not self.message.strip():
+            raise ValueError("Validation issue message cannot be empty")
+
+
+@dataclass
+class ValidationResult:
+    """Result of configuration validation.
+
+    WHY: Validation produces multiple types of findings (errors, warnings, info).
+    This model aggregates all validation results and provides summary properties.
+
+    DESIGN DECISION: Separates issues by severity to enable appropriate handling.
+    Provides convenience properties for common checks (is_valid, has_errors).
+    """
+
+    is_valid: bool
+    issues: List[ValidationIssue] = field(default_factory=list)
+    validated_agents: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def errors(self) -> List[ValidationIssue]:
+        """Get all error-level issues."""
+        return [
+            issue for issue in self.issues if issue.severity == ValidationSeverity.ERROR
+        ]
+
+    @property
+    def warnings(self) -> List[ValidationIssue]:
+        """Get all warning-level issues."""
+        return [
+            issue
+            for issue in self.issues
+            if issue.severity == ValidationSeverity.WARNING
+        ]
+
+    @property
+    def infos(self) -> List[ValidationIssue]:
+        """Get all info-level issues."""
+        return [
+            issue for issue in self.issues if issue.severity == ValidationSeverity.INFO
+        ]
+
+    @property
+    def has_errors(self) -> bool:
+        """Check if validation has any errors."""
+        return len(self.errors) > 0
+
+    @property
+    def has_warnings(self) -> bool:
+        """Check if validation has any warnings."""
+        return len(self.warnings) > 0
+
+    @property
+    def error_count(self) -> int:
+        """Get number of errors."""
+        return len(self.errors)
+
+    @property
+    def warning_count(self) -> int:
+        """Get number of warnings."""
+        return len(self.warnings)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert validation result to dictionary."""
+        return {
+            "is_valid": self.is_valid,
+            "error_count": self.error_count,
+            "warning_count": self.warning_count,
+            "validated_agents": self.validated_agents,
+            "errors": [
+                {
+                    "severity": issue.severity.value,
+                    "message": issue.message,
+                    "agent_id": issue.agent_id,
+                }
+                for issue in self.errors
+            ],
+            "warnings": [
+                {
+                    "severity": issue.severity.value,
+                    "message": issue.message,
+                    "agent_id": issue.agent_id,
+                }
+                for issue in self.warnings
+            ],
+        }
+
+
+@dataclass
+class ConfigurationPreview:
+    """Preview of what would be configured.
+
+    WHY: Users need to see what would change before committing. This model
+    provides a complete preview including recommendations, validation results,
+    and estimated impact.
+
+    DESIGN DECISION: Includes validation results to show potential issues
+    before deployment. Provides summary statistics for quick assessment.
+    """
+
+    recommendations: List[AgentRecommendation] = field(default_factory=list)
+    validation_result: Optional[ValidationResult] = None
+    estimated_deployment_time: float = 0.0  # seconds
+    would_deploy: List[str] = field(default_factory=list)
+    would_skip: List[str] = field(default_factory=list)
+    requires_confirmation: bool = True
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def deployment_count(self) -> int:
+        """Get number of agents that would be deployed."""
+        return len(self.would_deploy)
+
+    @property
+    def skip_count(self) -> int:
+        """Get number of agents that would be skipped."""
+        return len(self.would_skip)
+
+    @property
+    def is_valid(self) -> bool:
+        """Check if preview represents a valid configuration."""
+        if self.validation_result is None:
+            return True
+        return self.validation_result.is_valid
+
+    @property
+    def high_confidence_count(self) -> int:
+        """Get number of high-confidence recommendations."""
+        return sum(1 for rec in self.recommendations if rec.is_high_confidence)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert preview to dictionary."""
+        return {
+            "deployment_count": self.deployment_count,
+            "skip_count": self.skip_count,
+            "high_confidence_count": self.high_confidence_count,
+            "estimated_deployment_time": self.estimated_deployment_time,
+            "is_valid": self.is_valid,
+            "would_deploy": self.would_deploy,
+            "would_skip": self.would_skip,
+            "recommendations": [rec.to_dict() for rec in self.recommendations],
+        }

claude_mpm/services/core/models/health.py

@@ -0,0 +1,162 @@
+"""
+Health Monitoring Data Models for Claude MPM Framework
+=======================================================
+
+WHY: This module defines data structures for health monitoring operations,
+including health status, check results, and deployment health aggregations.
+
+DESIGN DECISION: Uses dataclasses for immutability and type safety. Provides
+clear health status enum and structured check results.
+
+ARCHITECTURE:
+- HealthStatus: Enum of health states (HEALTHY, DEGRADED, UNHEALTHY, UNKNOWN)
+- HealthCheckResult: Result of a single health check
+- DeploymentHealth: Aggregated health status for a deployment
+"""
+
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from typing import Any, Dict, List
+
+from ....core.enums import HealthStatus
+
+
+@dataclass
+class HealthCheckResult:
+    """
+    Result of a single health check.
+
+    WHY: Contains all information about a specific health check execution,
+    enabling detailed analysis and debugging of health issues.
+
+    Attributes:
+        status: HealthStatus of the check
+        check_type: Type of health check (http, process, resource)
+        message: Human-readable description of the result
+        details: Additional check-specific data
+        checked_at: Timestamp when check was performed
+    """
+
+    status: HealthStatus
+    check_type: str
+    message: str
+    details: Dict[str, Any] = field(default_factory=dict)
+    checked_at: datetime = field(default_factory=datetime.now)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary for JSON serialization.
+
+        Returns:
+            Dictionary representation with datetime converted to ISO format
+        """
+        data = asdict(self)
+        data["status"] = self.status.value
+        data["checked_at"] = self.checked_at.isoformat()
+        return data
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "HealthCheckResult":
+        """
+        Create HealthCheckResult from dictionary.
+
+        Args:
+            data: Dictionary from JSON deserialization
+
+        Returns:
+            HealthCheckResult instance
+        """
+        # Convert ISO string to datetime
+        if isinstance(data.get("checked_at"), str):
+            data["checked_at"] = datetime.fromisoformat(data["checked_at"])
+
+        # Convert status string to enum
+        if isinstance(data.get("status"), str):
+            data["status"] = HealthStatus(data["status"])
+
+        return cls(**data)
+
+
+@dataclass
+class DeploymentHealth:
+    """
+    Aggregated health status for a deployment.
+
+    WHY: Combines results from multiple health checks to provide a
+    comprehensive health assessment of a deployment.
+
+    Attributes:
+        deployment_id: Unique deployment identifier
+        overall_status: Aggregated health status
+        checks: List of individual health check results
+        last_check: Timestamp of the most recent health check
+    """
+
+    deployment_id: str
+    overall_status: HealthStatus
+    checks: List[HealthCheckResult] = field(default_factory=list)
+    last_check: datetime = field(default_factory=datetime.now)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """
+        Convert to dictionary for JSON serialization.
+
+        Returns:
+            Dictionary representation
+        """
+        return {
+            "deployment_id": self.deployment_id,
+            "overall_status": self.overall_status.value,
+            "checks": [check.to_dict() for check in self.checks],
+            "last_check": self.last_check.isoformat(),
+        }
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "DeploymentHealth":
+        """
+        Create DeploymentHealth from dictionary.
+
+        Args:
+            data: Dictionary from JSON deserialization
+
+        Returns:
+            DeploymentHealth instance
+        """
+        # Convert ISO string to datetime
+        if isinstance(data.get("last_check"), str):
+            data["last_check"] = datetime.fromisoformat(data["last_check"])
+
+        # Convert status string to enum
+        if isinstance(data.get("overall_status"), str):
+            data["overall_status"] = HealthStatus(data["overall_status"])
+
+        # Convert check dicts to HealthCheckResult objects
+        if isinstance(data.get("checks"), list):
+            data["checks"] = [
+                HealthCheckResult.from_dict(check) if isinstance(check, dict) else check
+                for check in data["checks"]
+            ]
+
+        return cls(**data)
+
+    def get_check_by_type(self, check_type: str) -> HealthCheckResult | None:
+        """
+        Get the result of a specific check type.
+
+        Args:
+            check_type: Type of health check to retrieve
+
+        Returns:
+            HealthCheckResult if found, None otherwise
+        """
+        for check in self.checks:
+            if check.check_type == check_type:
+                return check
+        return None
+
+
+__all__ = [
+    "DeploymentHealth",
+    "HealthCheckResult",
+    "HealthStatus",
+]