claude-mpm 4.24.0__py3-none-any.whl → 5.4.41__py3-none-any.whl

claude_mpm/services/agents/agent_preset_service.py

@@ -0,0 +1,238 @@
+"""Service for managing agent preset configurations.
+
+This service resolves preset names to concrete agent lists, validates preset
+availability against configured sources, and provides metadata for CLI display.
+
+Design Decision: Separate service layer for presets
+Rationale: Keeps CLI commands thin, enables easy testing, allows preset logic
+to be reused across multiple command interfaces.
+
+Trade-offs:
+- Abstraction: Added layer vs. direct preset access in CLI
+- Testability: Easy to mock service in CLI tests
+- Reusability: Preset logic available to web UI, API, etc.
+"""
+
+from typing import Any, Dict, List
+
+from ...config.agent_presets import (
+    PRESETS,
+    get_preset_agents,
+    get_preset_info,
+    get_preset_names,
+)
+from ...core.logging_config import get_logger
+from .git_source_manager import GitSourceManager
+
+logger = get_logger(__name__)
+
+
+class AgentPresetService:
+    """Service for resolving and validating agent presets.
+
+    This service bridges preset definitions and git source management,
+    providing a unified interface for preset-based agent deployment.
+
+    Attributes:
+        source_manager: GitSourceManager for agent resolution
+    """
+
+    def __init__(self, source_manager: GitSourceManager):
+        """Initialize with GitSourceManager for agent resolution.
+
+        Args:
+            source_manager: GitSourceManager instance for accessing agent sources
+        """
+        self.source_manager = source_manager
+
+    def list_presets(self) -> List[Dict[str, Any]]:
+        """List all available presets with metadata.
+
+        Returns:
+            List of preset info dicts with keys:
+            - name: Preset name (str)
+            - description: Human-readable description (str)
+            - agent_count: Number of agents in preset (int)
+            - use_cases: List of use case strings (List[str])
+
+        Example:
+            >>> service = AgentPresetService(source_manager)
+            >>> presets = service.list_presets()
+            >>> len(presets) >= 10
+            True
+            >>> all('name' in p for p in presets)
+            True
+        """
+        return [get_preset_info(name) for name in get_preset_names()]
+
+    def validate_preset(self, preset_name: str) -> bool:
+        """Check if preset name is valid.
+
+        Args:
+            preset_name: Name of preset to validate
+
+        Returns:
+            True if preset exists, False otherwise
+
+        Example:
+            >>> service.validate_preset('minimal')
+            True
+            >>> service.validate_preset('invalid-preset')
+            False
+        """
+        return preset_name in PRESETS
+
+    def get_preset_agents(self, preset_name: str) -> List[str]:
+        """Get agent list for preset.
+
+        Args:
+            preset_name: Name of preset
+
+        Returns:
+            List of agent IDs (e.g., ["universal/memory-manager", ...])
+
+        Raises:
+            ValueError: If preset name invalid
+
+        Example:
+            >>> agents = service.get_preset_agents('minimal')
+            >>> len(agents)
+            6
+        """
+        return get_preset_agents(preset_name)
+
+    def resolve_agents(
+        self, preset_name: str, validate_availability: bool = True
+    ) -> Dict[str, Any]:
+        """Resolve preset to actual agent definitions from configured sources.
+
+        This method cross-references preset agent IDs with available agents
+        from configured git sources, detecting missing agents and conflicts.
+
+        Args:
+            preset_name: Name of preset
+            validate_availability: Check if agents exist in sources
+
+        Returns:
+            Dict with keys:
+            - preset_info: Preset metadata (dict)
+            - agents: List of agent dicts with source attribution (List[dict])
+            - missing_agents: List of agent IDs not found (List[str])
+            - conflicts: List of agents found in multiple sources (List[dict])
+
+        Raises:
+            ValueError: If preset name invalid
+
+        Example:
+            >>> result = service.resolve_agents('minimal', validate_availability=True)
+            >>> 'preset_info' in result
+            True
+            >>> 'agents' in result
+            True
+            >>> 'missing_agents' in result
+            True
+
+        Design Decision: Graceful degradation for missing agents
+        Rationale: Allow deployment to proceed with warnings rather than
+        failing completely. Users may have subset of sources configured.
+        """
+        logger.debug(f"[DEBUG] resolve_agents START: preset_name={preset_name}")
+
+        if not self.validate_preset(preset_name):
+            raise ValueError(f"Unknown preset: {preset_name}")
+
+        logger.debug("[DEBUG] Validation passed")
+        preset_info = get_preset_info(preset_name)
+        logger.debug(f"[DEBUG] Got preset info: {preset_info.get('name')}")
+
+        agent_ids = self.get_preset_agents(preset_name)
+        logger.debug(f"[DEBUG] Got agent IDs: {len(agent_ids)} agents")
+
+        result = {
+            "preset_info": preset_info,
+            "agents": [],
+            "missing_agents": [],
+            "conflicts": [],
+        }
+
+        if not validate_availability:
+            # Return agent IDs without validation
+            logger.debug("[DEBUG] Skipping validation, returning agent IDs only")
+            result["agents"] = [{"agent_id": aid} for aid in agent_ids]
+            return result
+
+        # Get all cached agents from sources
+        logger.debug("[DEBUG] Calling source_manager.list_cached_agents()")
+        all_agents = self.source_manager.list_cached_agents()
+        logger.debug(f"[DEBUG] Got {len(all_agents)} agents from source manager")
+
+        # Build lookup: agent_id -> list of sources
+        # Each entry is (source_identifier, agent_data)
+        logger.debug("[DEBUG] Building agent_sources lookup table")
+        agent_sources: Dict[str, List[tuple]] = {}
+        for idx, agent in enumerate(all_agents):
+            if idx % 10 == 0:
+                logger.debug(f"[DEBUG] Processing agent {idx}/{len(all_agents)}")
+            # Handle both 'agent_id' and 'id' keys for compatibility
+            agent_id = agent.get("agent_id") or agent.get("id")
+            if not agent_id:
+                logger.warning(f"Agent missing agent_id field: {agent.keys()}")
+                continue
+
+            # Bug #5 fix: Handle both string and dict formats for 'source' field
+            # GitSourceManager sets source as string (repo_identifier)
+            # Some agents may have source as dict with 'identifier' key
+            source_value = agent.get("source", "unknown")
+            if isinstance(source_value, dict):
+                source = source_value.get("identifier", "unknown")
+            else:
+                source = source_value  # Already a string
+
+            if agent_id not in agent_sources:
+                agent_sources[agent_id] = []
+            agent_sources[agent_id].append((source, agent))
+
+        logger.debug(
+            f"[DEBUG] Built lookup table with {len(agent_sources)} unique agents"
+        )
+
+        # Resolve each agent in preset
+        logger.debug(f"[DEBUG] Resolving {len(agent_ids)} preset agents")
+        for idx, agent_id in enumerate(agent_ids):
+            logger.debug(
+                f"[DEBUG] Resolving agent {idx + 1}/{len(agent_ids)}: {agent_id}"
+            )
+            if agent_id not in agent_sources:
+                logger.debug(f"[DEBUG] Agent {agent_id} not found in sources (missing)")
+                result["missing_agents"].append(agent_id)
+                continue
+
+            sources = agent_sources[agent_id]
+            logger.debug(f"[DEBUG] Agent {agent_id} found in {len(sources)} source(s)")
+
+            # Conflict if agent found in multiple sources
+            if len(sources) > 1:
+                logger.debug(
+                    f"[DEBUG] Agent {agent_id} has conflict (multiple sources)"
+                )
+                result["conflicts"].append(
+                    {
+                        "agent_id": agent_id,
+                        "sources": [s[0] for s in sources],
+                    }
+                )
+
+            # Use first source (highest priority)
+            source_name, agent_data = sources[0]
+            result["agents"].append(
+                {
+                    "agent_id": agent_id,
+                    "source": source_name,
+                    "metadata": agent_data,
+                }
+            )
+
+        logger.debug(
+            f"[DEBUG] resolve_agents COMPLETE: {len(result['agents'])} resolved"
+        )
+        return result

claude_mpm/services/agents/agent_recommendation_service.py

@@ -0,0 +1,278 @@
+"""Agent Recommendation Service
+
+WHY: Provides intelligent agent recommendations based on toolchain detection
+and always-recommended core agents. Helps users discover and install the
+most relevant agents for their project without manual selection.
+
+DESIGN DECISION: Uses toolchain analysis to map detected languages/frameworks
+to specific engineer agents, plus always includes core agents.
+
+Architecture:
+- Toolchain-based recommendations: Python → python-engineer, etc.
+- Core agents (always recommended): engineer, qa-agent, memory-manager-agent, local-ops-agent,
+  research-agent, documentation-agent, security-agent
+- Confidence-based filtering: Only recommend high-confidence detections
+"""
+
+from pathlib import Path
+from typing import Dict, List, Optional, Set
+
+from ...services.project.toolchain_analyzer import ToolchainAnalyzerService
+
+
+class AgentRecommendationService:
+    """Service for recommending agents based on project toolchain.
+
+    WHY: Users shouldn't have to manually figure out which agents to install.
+    This service provides intelligent recommendations based on detected stack.
+
+    DESIGN DECISION: Separated from configure.py for reusability and testability.
+    Can be used by CLI, API, or future auto-configuration features.
+    """
+
+    # Core agents always included - matches ToolchainDetector.CORE_AGENTS
+    # Uses exact agent IDs from repository for consistency
+    CORE_AGENTS = {
+        "engineer",
+        "qa-agent",
+        "memory-manager-agent",
+        "local-ops-agent",
+        "research-agent",
+        "documentation-agent",
+        "security-agent",
+    }
+
+    # Map detected languages to recommended engineer agents
+    LANGUAGE_TO_AGENTS: Dict[str, List[str]] = {
+        "python": [
+            "engineer/backend/python-engineer",
+            "qa/api-qa",
+        ],
+        "javascript": [
+            "engineer/backend/javascript-engineer",
+            "engineer/data/typescript-engineer",
+        ],
+        "typescript": [
+            "engineer/data/typescript-engineer",
+            "engineer/backend/javascript-engineer",
+        ],
+        "rust": [
+            "engineer/backend/rust-engineer",
+        ],
+        "go": [
+            "engineer/backend/golang-engineer",
+        ],
+        "java": [
+            "engineer/backend/java-engineer",
+        ],
+        "dart": [
+            "engineer/mobile/dart-engineer",
+        ],
+        "php": [
+            "engineer/backend/php-engineer",
+        ],
+        "ruby": [
+            "engineer/backend/ruby-engineer",
+        ],
+        "swift": [
+            "engineer/mobile/swift-engineer",
+        ],
+        "kotlin": [
+            "engineer/mobile/kotlin-engineer",
+        ],
+    }
+
+    # Map detected frameworks to recommended agents
+    FRAMEWORK_TO_AGENTS: Dict[str, List[str]] = {
+        # Frontend frameworks
+        "react": [
+            "engineer/frontend/react-engineer",
+            "qa/web-qa",
+        ],
+        "nextjs": [
+            "engineer/frontend/nextjs-engineer",
+            "engineer/frontend/react-engineer",
+            "ops/platform/vercel-ops",
+        ],
+        "vue": [
+            "engineer/frontend/vue-engineer",
+        ],
+        "angular": [
+            "engineer/frontend/angular-engineer",
+        ],
+        # Backend frameworks
+        "fastapi": [
+            "engineer/backend/python-engineer",
+            "qa/api-qa",
+        ],
+        "django": [
+            "engineer/backend/python-engineer",
+            "qa/api-qa",
+        ],
+        "flask": [
+            "engineer/backend/python-engineer",
+            "qa/api-qa",
+        ],
+        "express": [
+            "engineer/backend/javascript-engineer",
+            "qa/api-qa",
+        ],
+        "nest": [
+            "engineer/backend/javascript-engineer",
+            "qa/api-qa",
+        ],
+        # Mobile frameworks
+        "flutter": [
+            "engineer/mobile/dart-engineer",
+        ],
+        "react-native": [
+            "engineer/frontend/react-engineer",
+            "engineer/mobile/react-native-engineer",
+        ],
+        # Desktop frameworks
+        "tauri": [
+            "engineer/mobile/tauri-engineer",
+            "engineer/backend/rust-engineer",
+        ],
+        "electron": [
+            "engineer/backend/javascript-engineer",
+        ],
+    }
+
+    def __init__(self, toolchain_analyzer: Optional[ToolchainAnalyzerService] = None):
+        """Initialize agent recommendation service.
+
+        Args:
+            toolchain_analyzer: Optional pre-initialized toolchain analyzer.
+                               If None, creates a new instance.
+        """
+        self.toolchain_analyzer = toolchain_analyzer or ToolchainAnalyzerService()
+
+    def get_recommended_agents(
+        self,
+        project_path: Optional[str] = None,
+        confidence_threshold: float = 0.5,
+    ) -> Set[str]:
+        """Get recommended agents for a project.
+
+        Args:
+            project_path: Path to project directory. Defaults to cwd.
+            confidence_threshold: Minimum confidence for recommendations (0.0-1.0).
+                                 Only include detected components above this threshold.
+
+        Returns:
+            Set of recommended agent IDs (e.g., {"qa-agent", "research-agent", ...})
+
+        Example:
+            >>> service = AgentRecommendationService()
+            >>> recommended = service.get_recommended_agents()
+            >>> "qa-agent" in recommended
+            True
+            >>> # For Python project:
+            >>> "engineer/backend/python-engineer" in recommended
+            True
+        """
+        # Start with core agents (always recommended)
+        recommended = self.CORE_AGENTS.copy()
+
+        # Analyze project toolchain
+        if project_path is None:
+            project_path = str(Path.cwd())
+
+        try:
+            # ToolchainAnalyzerService.analyze_toolchain takes Path, not str
+            analysis = self.toolchain_analyzer.analyze_toolchain(Path(project_path))
+        except Exception as e:
+            # If analysis fails, just return core agents
+            print(f"Warning: Toolchain analysis failed: {e}")
+            return recommended
+
+        # Add language-specific agents
+        # ToolchainAnalysis has a single LanguageDetection object, not a list
+        if analysis.language_detection:
+            # Check primary language
+            primary_lang = analysis.language_detection.primary_language.lower()
+            if primary_lang in self.LANGUAGE_TO_AGENTS:
+                recommended.update(self.LANGUAGE_TO_AGENTS[primary_lang])
+
+            # Check secondary languages
+            for lang_component in analysis.language_detection.secondary_languages:
+                lang = lang_component.name.lower()
+                if lang in self.LANGUAGE_TO_AGENTS:
+                    recommended.update(self.LANGUAGE_TO_AGENTS[lang])
+
+        # Add framework-specific agents
+        for framework in analysis.frameworks:
+            fw_name = framework.name.lower()
+            if fw_name in self.FRAMEWORK_TO_AGENTS:
+                recommended.update(self.FRAMEWORK_TO_AGENTS[fw_name])
+
+        return recommended
+
+    def get_detection_summary(self, project_path: Optional[str] = None) -> Dict:
+        """Get human-readable summary of detected toolchain.
+
+        Args:
+            project_path: Path to project directory. Defaults to cwd.
+
+        Returns:
+            Dict with keys:
+            - detected_languages: List of detected language names
+            - detected_frameworks: List of detected framework names
+            - recommended_count: Number of recommended agents
+            - detection_quality: "high", "medium", "low", or "none"
+
+        Example:
+            >>> summary = service.get_detection_summary()
+            >>> summary['detected_languages']
+            ['Python', 'JavaScript']
+            >>> summary['recommended_count']
+            15
+        """
+        if project_path is None:
+            project_path = str(Path.cwd())
+
+        try:
+            analysis = self.toolchain_analyzer.analyze_toolchain(Path(project_path))
+
+            # Extract languages from LanguageDetection object
+            languages = []
+            if analysis.language_detection:
+                languages.append(analysis.language_detection.primary_language)
+                languages.extend(
+                    comp.name
+                    for comp in analysis.language_detection.secondary_languages
+                )
+
+            # Extract frameworks
+            frameworks = [fw.name for fw in analysis.frameworks]
+
+            # Get recommended agents
+            recommended = self.get_recommended_agents(project_path)
+
+            # Determine detection quality from overall_confidence
+            confidence_map = {
+                "high": "high",
+                "medium": "medium",
+                "low": "low",
+                "very_low": "low",
+            }
+            quality = confidence_map.get(
+                str(analysis.overall_confidence).lower(), "unknown"
+            )
+
+            return {
+                "detected_languages": languages,
+                "detected_frameworks": frameworks,
+                "recommended_count": len(recommended),
+                "detection_quality": quality,
+            }
+        except Exception as e:
+            # Log the error for debugging
+            print(f"Warning: Toolchain analysis failed: {e}")
+            return {
+                "detected_languages": [],
+                "detected_frameworks": [],
+                "recommended_count": len(self.CORE_AGENTS),
+                "detection_quality": "none",
+            }