claude-mpm 4.12.1__py3-none-any.whl → 4.13.0__py3-none-any.whl

claude_mpm/services/core/models/agent_config.py

@@ -0,0 +1,397 @@
+"""
+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
+
+
+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,
+        }
+
+
+class ConfigurationStatus(str, Enum):
+    """Status of configuration operation.
+
+    WHY: Configuration can succeed, fail, or partially succeed. This enum
+    provides a standardized way to communicate operation outcomes.
+    """
+
+    SUCCESS = "success"
+    PARTIAL_SUCCESS = "partial_success"
+    FAILURE = "failure"
+    VALIDATION_ERROR = "validation_error"
+    USER_CANCELLED = "user_cancelled"
+
+
+@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.
+    """
+
+    status: ConfigurationStatus
+    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 == ConfigurationStatus.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,
+        }
+
+
+class ValidationSeverity(str, Enum):
+    """Severity level for validation issues.
+
+    WHY: Not all validation issues are equally critical. This enum enables
+    categorization of issues by severity to support appropriate handling.
+    """
+
+    ERROR = "error"  # Blocks deployment
+    WARNING = "warning"  # Should be reviewed but doesn't block
+    INFO = "info"  # Informational only
+
+
+@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/toolchain.py

@@ -0,0 +1,306 @@
+"""
+Toolchain Data Models for Claude MPM Framework
+==============================================
+
+WHY: These models represent the structure of project toolchain analysis results.
+They provide a standardized way to represent detected languages, frameworks,
+deployment targets, and overall toolchain characteristics.
+
+DESIGN DECISION: Uses dataclasses with field validation and default values
+to ensure data consistency. Confidence levels are included to represent
+uncertainty in detection. Immutable where possible to prevent accidental
+modification of analysis results.
+
+Part of TSK-0054: Auto-Configuration Feature - Phase 1
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+class ConfidenceLevel(str, Enum):
+    """Confidence level for detection results.
+
+    WHY: Not all detections are equally certain. This enum provides a
+    standardized way to communicate confidence levels to users and
+    enable threshold-based decision making.
+    """
+
+    HIGH = "high"  # >80% confidence, very strong indicators
+    MEDIUM = "medium"  # 50-80% confidence, good indicators
+    LOW = "low"  # 20-50% confidence, weak indicators
+    VERY_LOW = "very_low"  # <20% confidence, speculative
+
+
+@dataclass(frozen=True)
+class ToolchainComponent:
+    """Represents a component in the project's toolchain.
+
+    WHY: Toolchain components (languages, frameworks, tools) share common
+    attributes like name, version, and confidence. This base model enables
+    consistent representation across different component types.
+
+    DESIGN DECISION: Frozen dataclass to prevent modification after creation,
+    ensuring analysis results remain consistent. Version is optional as not
+    all components have detectable versions.
+    """
+
+    name: str
+    version: Optional[str] = None
+    confidence: ConfidenceLevel = ConfidenceLevel.MEDIUM
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Validate component data after initialization."""
+        if not self.name or not self.name.strip():
+            raise ValueError("Component name cannot be empty")
+        if self.version is not None and not self.version.strip():
+            raise ValueError("Component version cannot be empty string")
+
+
+@dataclass(frozen=True)
+class LanguageDetection:
+    """Result of language detection analysis.
+
+    WHY: Projects often use multiple languages. This model captures both
+    primary (main codebase) and secondary (scripts, config) languages
+    with their relative proportions and confidence levels.
+
+    DESIGN DECISION: Includes percentage breakdown to help understand
+    language distribution. Confidence per language enables threshold-based
+    filtering of uncertain detections.
+    """
+
+    primary_language: str
+    primary_version: Optional[str] = None
+    primary_confidence: ConfidenceLevel = ConfidenceLevel.MEDIUM
+    secondary_languages: List[ToolchainComponent] = field(default_factory=list)
+    language_percentages: Dict[str, float] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Validate language detection data."""
+        if not self.primary_language or not self.primary_language.strip():
+            raise ValueError("Primary language cannot be empty")
+
+        # Validate language percentages sum to ~100% (allow small floating point error)
+        if self.language_percentages:
+            total = sum(self.language_percentages.values())
+            if not (99.0 <= total <= 101.0):
+                raise ValueError(f"Language percentages must sum to 100%, got {total}%")
+
+    @property
+    def all_languages(self) -> List[str]:
+        """Get list of all detected languages (primary + secondary)."""
+        languages = [self.primary_language]
+        languages.extend(comp.name for comp in self.secondary_languages)
+        return languages
+
+    @property
+    def high_confidence_languages(self) -> List[str]:
+        """Get languages detected with high confidence."""
+        languages = []
+        if self.primary_confidence == ConfidenceLevel.HIGH:
+            languages.append(self.primary_language)
+        languages.extend(
+            comp.name
+            for comp in self.secondary_languages
+            if comp.confidence == ConfidenceLevel.HIGH
+        )
+        return languages
+
+
+@dataclass(frozen=True)
+class Framework:
+    """Represents a detected framework or library.
+
+    WHY: Frameworks are critical for agent recommendation as different agents
+    specialize in different frameworks. This model captures framework identity,
+    version, type, and usage characteristics.
+
+    DESIGN DECISION: Includes framework type (web, testing, ORM, etc.) to
+    enable category-based recommendations. Popularity metric helps prioritize
+    agent recommendations for commonly-used frameworks.
+    """
+
+    name: str
+    version: Optional[str] = None
+    framework_type: Optional[str] = None  # web, testing, orm, cli, etc.
+    confidence: ConfidenceLevel = ConfidenceLevel.MEDIUM
+    is_dev_dependency: bool = False
+    popularity_score: float = 0.0  # 0.0-1.0, higher = more popular/used
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Validate framework data."""
+        if not self.name or not self.name.strip():
+            raise ValueError("Framework name cannot be empty")
+        if not (0.0 <= self.popularity_score <= 1.0):
+            raise ValueError(
+                f"Popularity score must be 0.0-1.0, got {self.popularity_score}"
+            )
+
+    @property
+    def display_name(self) -> str:
+        """Get formatted display name with version."""
+        if self.version:
+            return f"{self.name} {self.version}"
+        return self.name
+
+
+@dataclass(frozen=True)
+class DeploymentTarget:
+    """Represents the detected deployment target environment.
+
+    WHY: Deployment target affects agent recommendations (e.g., DevOps agents
+    for Kubernetes, serverless agents for Lambda). This model captures the
+    deployment platform and configuration details.
+
+    DESIGN DECISION: Includes target type (cloud, container, serverless, etc.)
+    and platform-specific configuration. Confidence level enables fallback
+    to generic recommendations when deployment target is unclear.
+    """
+
+    target_type: str  # cloud, container, serverless, on-premise, edge
+    platform: Optional[str] = None  # aws, gcp, azure, kubernetes, docker, etc.
+    configuration: Dict[str, Any] = field(default_factory=dict)
+    confidence: ConfidenceLevel = ConfidenceLevel.MEDIUM
+    requires_ops_agent: bool = False
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Validate deployment target data."""
+        valid_types = {"cloud", "container", "serverless", "on-premise", "edge"}
+        if self.target_type not in valid_types:
+            raise ValueError(
+                f"Invalid target_type '{self.target_type}'. "
+                f"Must be one of: {valid_types}"
+            )
+
+    @property
+    def display_name(self) -> str:
+        """Get formatted display name."""
+        if self.platform:
+            return f"{self.target_type} ({self.platform})"
+        return self.target_type
+
+
+@dataclass
+class ToolchainAnalysis:
+    """Complete toolchain analysis result.
+
+    WHY: This is the primary output of toolchain analysis, aggregating all
+    detected components into a single structure. It provides a complete
+    picture of the project's technical stack.
+
+    DESIGN DECISION: Not frozen to allow caching and updating of analysis
+    results. Includes project_path for reference and validation. Provides
+    convenience methods for common queries (e.g., has framework, get languages).
+    """
+
+    project_path: Path
+    language_detection: LanguageDetection
+    frameworks: List[Framework] = field(default_factory=list)
+    deployment_target: Optional[DeploymentTarget] = None
+    build_tools: List[ToolchainComponent] = field(default_factory=list)
+    package_managers: List[ToolchainComponent] = field(default_factory=list)
+    development_tools: List[ToolchainComponent] = field(default_factory=list)
+    overall_confidence: ConfidenceLevel = ConfidenceLevel.MEDIUM
+    analysis_timestamp: Optional[float] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Validate toolchain analysis data."""
+        if not self.project_path.exists():
+            raise ValueError(f"Project path does not exist: {self.project_path}")
+        if not self.project_path.is_dir():
+            raise ValueError(f"Project path is not a directory: {self.project_path}")
+
+    def has_framework(self, framework_name: str) -> bool:
+        """Check if a specific framework is detected."""
+        return any(fw.name.lower() == framework_name.lower() for fw in self.frameworks)
+
+    def get_framework(self, framework_name: str) -> Optional[Framework]:
+        """Get framework by name (case-insensitive)."""
+        for fw in self.frameworks:
+            if fw.name.lower() == framework_name.lower():
+                return fw
+        return None
+
+    def get_frameworks_by_type(self, framework_type: str) -> List[Framework]:
+        """Get all frameworks of a specific type."""
+        return [
+            fw
+            for fw in self.frameworks
+            if fw.framework_type and fw.framework_type.lower() == framework_type.lower()
+        ]
+
+    @property
+    def primary_language(self) -> str:
+        """Get the primary language detected."""
+        return self.language_detection.primary_language
+
+    @property
+    def all_languages(self) -> List[str]:
+        """Get all detected languages."""
+        return self.language_detection.all_languages
+
+    @property
+    def web_frameworks(self) -> List[Framework]:
+        """Get all web frameworks."""
+        return self.get_frameworks_by_type("web")
+
+    @property
+    def is_web_project(self) -> bool:
+        """Check if this appears to be a web project."""
+        return len(self.web_frameworks) > 0
+
+    @property
+    def requires_devops_agent(self) -> bool:
+        """Check if project likely needs DevOps agent."""
+        if self.deployment_target and self.deployment_target.requires_ops_agent:
+            return True
+        # Check for containerization
+        return any(
+            tool.name.lower() in {"docker", "kubernetes", "terraform"}
+            for tool in self.development_tools
+        )
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert analysis to dictionary for serialization."""
+        return {
+            "project_path": str(self.project_path),
+            "language_detection": {
+                "primary_language": self.language_detection.primary_language,
+                "primary_version": self.language_detection.primary_version,
+                "primary_confidence": self.language_detection.primary_confidence.value,
+                "secondary_languages": [
+                    {"name": lang.name, "version": lang.version}
+                    for lang in self.language_detection.secondary_languages
+                ],
+                "language_percentages": self.language_detection.language_percentages,
+            },
+            "frameworks": [
+                {
+                    "name": fw.name,
+                    "version": fw.version,
+                    "type": fw.framework_type,
+                    "confidence": fw.confidence.value,
+                }
+                for fw in self.frameworks
+            ],
+            "deployment_target": (
+                {
+                    "type": self.deployment_target.target_type,
+                    "platform": self.deployment_target.platform,
+                    "confidence": self.deployment_target.confidence.value,
+                }
+                if self.deployment_target
+                else None
+            ),
+            "build_tools": [tool.name for tool in self.build_tools],
+            "package_managers": [pm.name for pm in self.package_managers],
+            "overall_confidence": self.overall_confidence.value,
+            "metadata": self.metadata,
+        }