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

claude_mpm/services/core/interfaces/agent.py

@@ -21,6 +21,15 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Tuple
 
+from ..models.agent_config import (
+    AgentCapabilities,
+    AgentRecommendation,
+    ConfigurationPreview,
+    ConfigurationResult,
+    ValidationResult,
+)
+from ..models.toolchain import ToolchainAnalysis
+
 
 # Agent registry interface
 @dataclass
@@ -328,3 +337,178 @@ class RunnerConfigurationInterface(ABC):
         Args:
             config: Logging configuration
         """
+
+
+# Agent recommender interface
+class IAgentRecommender(ABC):
+    """Interface for agent recommendation operations.
+
+    WHY: Automated agent recommendation is critical for the auto-configuration
+    feature. This interface abstracts the recommendation logic to enable different
+    scoring algorithms, rule-based systems, and ML-based approaches.
+
+    DESIGN DECISION: Separates recommendation from configuration to enable
+    independent testing and different recommendation strategies (rule-based,
+    ML-based, hybrid). Returns structured recommendations with confidence scores.
+    """
+
+    @abstractmethod
+    def recommend_agents(
+        self,
+        toolchain: ToolchainAnalysis,
+        constraints: Optional[Dict[str, Any]] = None,
+    ) -> List[AgentRecommendation]:
+        """Recommend agents based on toolchain analysis.
+
+        Analyzes the toolchain and recommends agents that best match the
+        project's technical requirements. Considers:
+        - Language compatibility
+        - Framework expertise
+        - Deployment environment requirements
+        - Optional user-defined constraints (max agents, required capabilities)
+
+        Args:
+            toolchain: Complete toolchain analysis results
+            constraints: Optional constraints for recommendations:
+                - max_agents: Maximum number of agents to recommend
+                - required_capabilities: List of required agent capabilities
+                - excluded_agents: List of agent IDs to exclude
+                - min_confidence: Minimum confidence score threshold
+
+        Returns:
+            List[AgentRecommendation]: Ordered list of recommended agents
+                with confidence scores and reasoning
+
+        Raises:
+            ValueError: If constraints are invalid or contradictory
+        """
+
+    @abstractmethod
+    def get_agent_capabilities(self, agent_id: str) -> AgentCapabilities:
+        """Get detailed capabilities for an agent.
+
+        Retrieves comprehensive capability information for a specific agent:
+        - Supported languages and frameworks
+        - Specialization areas
+        - Required toolchain components
+        - Performance characteristics
+
+        Args:
+            agent_id: Unique identifier of the agent
+
+        Returns:
+            AgentCapabilities: Complete capability information
+
+        Raises:
+            KeyError: If agent_id does not exist
+        """
+
+    @abstractmethod
+    def match_score(self, agent_id: str, toolchain: ToolchainAnalysis) -> float:
+        """Calculate match score between agent and toolchain.
+
+        Computes a numerical score (0.0 to 1.0) indicating how well an agent
+        matches the project's toolchain. Higher scores indicate better matches.
+        Considers:
+        - Language compatibility
+        - Framework experience
+        - Deployment target alignment
+        - Toolchain component coverage
+
+        Args:
+            agent_id: Unique identifier of the agent
+            toolchain: Complete toolchain analysis
+
+        Returns:
+            float: Match score between 0.0 (no match) and 1.0 (perfect match)
+
+        Raises:
+            KeyError: If agent_id does not exist
+        """
+
+
+# Auto-configuration manager interface
+class IAutoConfigManager(ABC):
+    """Interface for automated configuration management.
+
+    WHY: Auto-configuration orchestrates the entire process of analyzing,
+    recommending, validating, and deploying agents. This interface abstracts
+    the orchestration logic to enable different workflows and approval processes.
+
+    DESIGN DECISION: Provides both preview and apply modes to enable user review
+    before deployment. Includes validation to catch configuration issues early.
+    Supports both interactive (confirmation required) and automated modes.
+    """
+
+    @abstractmethod
+    async def auto_configure(
+        self, project_path: Path, confirmation_required: bool = True
+    ) -> ConfigurationResult:
+        """Perform automated agent configuration.
+
+        Complete end-to-end configuration workflow:
+        1. Analyze project toolchain
+        2. Generate agent recommendations
+        3. Validate proposed configuration
+        4. Request user confirmation (if required)
+        5. Deploy approved agents
+        6. Verify deployment success
+
+        Args:
+            project_path: Path to the project root directory
+            confirmation_required: Whether to require user approval before deployment
+
+        Returns:
+            ConfigurationResult: Complete configuration results including
+                deployed agents, validation results, and any errors
+
+        Raises:
+            FileNotFoundError: If project_path does not exist
+            PermissionError: If unable to write to project directory
+            ValidationError: If configuration validation fails critically
+        """
+
+    @abstractmethod
+    def validate_configuration(
+        self, recommendations: List[AgentRecommendation]
+    ) -> ValidationResult:
+        """Validate proposed configuration before deployment.
+
+        Performs comprehensive validation of recommended agents:
+        - Checks for conflicting agent capabilities
+        - Verifies resource requirements are met
+        - Validates agent compatibility with project
+        - Identifies potential configuration issues
+
+        Args:
+            recommendations: List of agent recommendations to validate
+
+        Returns:
+            ValidationResult: Validation result with any warnings or errors
+
+        Raises:
+            ValueError: If recommendations list is empty or invalid
+        """
+
+    @abstractmethod
+    def preview_configuration(self, project_path: Path) -> ConfigurationPreview:
+        """Preview what would be configured without applying changes.
+
+        Performs analysis and recommendation without making any changes:
+        - Analyzes project toolchain
+        - Generates recommendations
+        - Validates configuration
+        - Returns preview of what would be deployed
+
+        Useful for testing and showing users what would happen before
+        committing to changes.
+
+        Args:
+            project_path: Path to the project root directory
+
+        Returns:
+            ConfigurationPreview: Preview of configuration that would be applied
+
+        Raises:
+            FileNotFoundError: If project_path does not exist
+        """

claude_mpm/services/core/interfaces/project.py

@@ -0,0 +1,121 @@
+"""
+Project Analysis Interfaces for Claude MPM Framework
+====================================================
+
+WHY: This module contains interfaces for project analysis, toolchain detection,
+and technology stack identification. These interfaces enable the auto-configuration
+system to intelligently recommend agents based on detected project characteristics.
+
+DESIGN DECISION: Project analysis interfaces are separated because they deal
+with understanding the codebase structure, dependencies, and toolchain setup,
+which requires different patterns than other service types.
+
+Part of TSK-0054: Auto-Configuration Feature - Phase 1
+"""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import List, Optional
+
+from ..models.toolchain import (
+    DeploymentTarget,
+    Framework,
+    LanguageDetection,
+    ToolchainAnalysis,
+)
+
+
+class IToolchainAnalyzer(ABC):
+    """Interface for toolchain analysis operations.
+
+    WHY: Understanding project toolchain is essential for recommending appropriate
+    agents. This interface abstracts toolchain analysis to support different
+    project types, languages, and frameworks.
+
+    DESIGN DECISION: Separates language, framework, and deployment detection
+    into distinct methods to enable granular analysis and caching of results.
+    Each analysis type can be run independently based on needs.
+    """
+
+    @abstractmethod
+    def analyze_toolchain(self, project_path: Path) -> ToolchainAnalysis:
+        """Analyze project toolchain and dependencies.
+
+        Performs comprehensive analysis of the project's technical stack including:
+        - Primary and secondary programming languages
+        - Framework and library dependencies
+        - Build and deployment configuration
+        - Development environment requirements
+
+        Args:
+            project_path: Path to the project root directory
+
+        Returns:
+            ToolchainAnalysis: Complete analysis result with confidence scores
+
+        Raises:
+            FileNotFoundError: If project_path does not exist
+            PermissionError: If project_path is not readable
+        """
+
+    @abstractmethod
+    def detect_language(self, project_path: Path) -> LanguageDetection:
+        """Detect primary and secondary languages used in the project.
+
+        Analyzes source files to determine:
+        - Primary programming language (highest code volume)
+        - Secondary languages (supporting code, scripts)
+        - Language versions if detectable
+        - Confidence level for each detection
+
+        Args:
+            project_path: Path to the project root directory
+
+        Returns:
+            LanguageDetection: Detected languages with confidence scores
+
+        Raises:
+            FileNotFoundError: If project_path does not exist
+        """
+
+    @abstractmethod
+    def detect_frameworks(self, project_path: Path) -> List[Framework]:
+        """Detect frameworks and their versions.
+
+        Identifies frameworks by analyzing:
+        - Dependency files (package.json, requirements.txt, etc.)
+        - Import statements in source code
+        - Configuration files specific to frameworks
+        - Project structure patterns
+
+        Args:
+            project_path: Path to the project root directory
+
+        Returns:
+            List[Framework]: List of detected frameworks with versions and types
+
+        Raises:
+            FileNotFoundError: If project_path does not exist
+        """
+
+    @abstractmethod
+    def detect_deployment_target(
+        self, project_path: Path
+    ) -> Optional[DeploymentTarget]:
+        """Detect intended deployment environment.
+
+        Analyzes configuration to identify deployment targets:
+        - Cloud platforms (AWS, GCP, Azure)
+        - Container orchestration (Kubernetes, Docker)
+        - Serverless platforms (Lambda, Cloud Functions)
+        - Traditional hosting (VPS, dedicated servers)
+
+        Args:
+            project_path: Path to the project root directory
+
+        Returns:
+            Optional[DeploymentTarget]: Detected deployment target or None if unclear
+
+        Raises:
+            FileNotFoundError: If project_path does not exist
+        """

claude_mpm/services/core/models/__init__.py

@@ -0,0 +1,46 @@
+"""
+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 .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",
+]