claude-mpm 4.1.26__py3-none-any.whl → 5.0.9__py3-none-any.whl

claude_mpm/cli/commands/agents_discover.py

@@ -0,0 +1,338 @@
+"""Agent discovery command for browsing available agents from configured sources.
+
+WHY: This module implements the 'agents discover' command, allowing users to
+browse and filter agents from configured Git sources. Provides rich filtering
+by category, language, framework, platform, and specialization.
+
+DESIGN DECISION: Rich console output using rich library
+
+Rationale: Users need beautiful, informative output when discovering agents.
+The rich library (already a dependency) provides excellent table formatting,
+color support, and tree views.
+
+Trade-offs:
+- User Experience: Beautiful output improves discoverability
+- Complexity: Rich table formatting adds some code overhead
+- Performance: Rendering is fast enough for CLI use (<50ms)
+
+Example Usage:
+    >>> claude-mpm agents discover --category engineer/backend
+    >>> claude-mpm agents discover --language python --verbose
+    >>> claude-mpm agents discover --framework react --format json
+"""
+
+import json
+import logging
+from typing import Any, Dict, List
+
+from rich.console import Console
+
+from ...config.agent_sources import AgentSourceConfiguration
+from ...services.agents.git_source_manager import GitSourceManager
+
+logger = logging.getLogger(__name__)
+console = Console()
+
+
+def _group_agents_by_category(
+    agents: List[Dict[str, Any]],
+) -> Dict[str, List[Dict[str, Any]]]:
+    """Group agents by their category for organized display.
+
+    Args:
+        agents: List of agent dictionaries
+
+    Returns:
+        Dictionary mapping category names to lists of agents
+
+    Example:
+        >>> agents = [
+        ...     {"agent_id": "engineer/backend/python-engineer", "category": "engineer/backend"},
+        ...     {"agent_id": "qa/qa", "category": "qa"}
+        ... ]
+        >>> grouped = _group_agents_by_category(agents)
+        >>> grouped.keys()
+        dict_keys(['engineer/backend', 'qa'])
+    """
+    grouped: Dict[str, List[Dict[str, Any]]] = {}
+
+    for agent in agents:
+        # Extract category from agent_id if not present
+        category = agent.get("category", "unknown")
+
+        if category == "unknown" and "agent_id" in agent:
+            agent_id = agent["agent_id"]
+            if "/" in agent_id:
+                category = agent_id.rsplit("/", 1)[0]
+
+        if category not in grouped:
+            grouped[category] = []
+
+        grouped[category].append(agent)
+
+    return grouped
+
+
+def _format_category_name(category: str) -> str:
+    """Format category name for display.
+
+    Args:
+        category: Raw category string (e.g., "engineer/backend")
+
+    Returns:
+        Formatted category name (e.g., "Engineering/Backend")
+
+    Example:
+        >>> _format_category_name("engineer/backend")
+        'Engineering/Backend'
+        >>> _format_category_name("qa")
+        'QA'
+    """
+    # Special cases
+    if category == "qa":
+        return "QA"
+    if category == "ops":
+        return "Ops"
+
+    # Capitalize each part
+    parts = category.split("/")
+    formatted_parts = []
+
+    for part in parts:
+        if part == "qa":
+            formatted_parts.append("QA")
+        elif part == "ops":
+            formatted_parts.append("Ops")
+        else:
+            formatted_parts.append(part.capitalize())
+
+    return "/".join(formatted_parts)
+
+
+def _output_table_format(agents: List[Dict[str, Any]], verbose: bool = False) -> None:
+    """Output agents in rich table format (default).
+
+    Design Decision: Group by category for better organization
+
+    Rationale: Agents grouped by category (engineer/backend, qa, ops) are
+    easier to scan than a flat list. Categories provide context about
+    agent purpose.
+
+    Args:
+        agents: List of agent dictionaries
+        verbose: Show descriptions and metadata
+    """
+    if not agents:
+        console.print("[yellow]No agents found matching filters.[/yellow]")
+        return
+
+    console.print(
+        f"\n[bold]📚 Agents from configured sources ({len(agents)} matching filters):[/bold]\n"
+    )
+
+    # Group by category
+    grouped = _group_agents_by_category(agents)
+
+    # Sort categories for consistent display
+    sorted_categories = sorted(grouped.keys())
+
+    for category in sorted_categories:
+        category_agents = grouped[category]
+
+        # Print category header
+        formatted_category = _format_category_name(category)
+        console.print(f"[bold cyan]{formatted_category}[/bold cyan]")
+
+        # Print agents in this category
+        for agent in sorted(category_agents, key=lambda a: a.get("agent_id", "")):
+            agent_id = agent.get("agent_id", "unknown")
+            source = agent.get("source", agent.get("repository", "unknown"))
+            priority = agent.get("priority", "unknown")
+
+            # Agent ID line
+            console.print(f"  • [bold]{agent_id}[/bold]")
+
+            if verbose:
+                # Description
+                description = agent.get("metadata", {}).get("description", "")
+                if not description:
+                    description = agent.get("description", "No description available")
+
+                console.print(f"    {description}")
+
+                # Version
+                version = agent.get(
+                    "version", agent.get("metadata", {}).get("version", "unknown")
+                )
+                console.print(f"    Version: {version}")
+
+            # Source attribution
+            console.print(f"    Source: [dim]{source}[/dim] (priority: {priority})")
+
+            console.print()  # Blank line between agents
+
+        console.print()  # Blank line between categories
+
+
+def _output_json_format(
+    agents: List[Dict[str, Any]], filters_applied: Dict[str, str]
+) -> None:
+    """Output agents in JSON format for scripting.
+
+    Args:
+        agents: List of agent dictionaries
+        filters_applied: Dictionary of filters that were applied
+    """
+    output = {
+        "total": len(agents),
+        "filters_applied": filters_applied,
+        "agents": [
+            {
+                "agent_id": agent.get("agent_id", "unknown"),
+                "source": agent.get("source", agent.get("repository", "unknown")),
+                "priority": agent.get("priority", "unknown"),
+                "category": agent.get("category", "unknown"),
+                "version": agent.get(
+                    "version", agent.get("metadata", {}).get("version", "unknown")
+                ),
+                "description": agent.get("metadata", {}).get(
+                    "description", agent.get("description", "")
+                ),
+            }
+            for agent in agents
+        ],
+    }
+
+    console.print(json.dumps(output, indent=2))
+
+
+def _output_simple_format(agents: List[Dict[str, Any]]) -> None:
+    """Output agents in simple format (agent IDs only).
+
+    Args:
+        agents: List of agent dictionaries
+    """
+    for agent in sorted(agents, key=lambda a: a.get("agent_id", "")):
+        agent_id = agent.get("agent_id", "unknown")
+        console.print(agent_id)
+
+
+def discover_command(args) -> int:
+    """Execute the 'agents discover' command.
+
+    This command discovers and lists available agents from all configured
+    Git sources, with optional filtering by category, language, framework,
+    platform, and source.
+
+    Design Decision: Load sources from configuration
+
+    Rationale: Use AgentSourceConfiguration to load all configured sources,
+    respecting enabled/disabled state and priority. This ensures consistent
+    behavior with other agent commands.
+
+    Error Handling:
+    - Graceful degradation if no sources configured
+    - Warning if cache not populated (suggest agent-source update)
+    - Empty result sets clearly communicated
+
+    Args:
+        args: Parsed command arguments with attributes:
+            - source: Optional source ID filter
+            - category: Optional category filter
+            - language: Optional language filter
+            - framework: Optional framework filter
+            - platform: Optional platform filter
+            - specialization: Optional specialization filter
+            - format: Output format (table, json, simple)
+            - verbose: Show descriptions and metadata
+
+    Returns:
+        Exit code (0 for success, 1 for error)
+
+    Example:
+        >>> args = argparse.Namespace(
+        ...     source=None,
+        ...     category="engineer/backend",
+        ...     language=None,
+        ...     framework=None,
+        ...     platform=None,
+        ...     specialization=None,
+        ...     format="table",
+        ...     verbose=False
+        ... )
+        >>> discover_command(args)
+        0
+    """
+    try:
+        # Load agent sources configuration
+        sources_config = AgentSourceConfiguration()
+
+        # Initialize Git source manager
+        manager = GitSourceManager()
+
+        # Build filters dictionary
+        filters = {}
+
+        if args.category:
+            filters["category"] = args.category
+
+        if args.language:
+            filters["language"] = args.language
+
+        if args.framework:
+            filters["framework"] = args.framework
+
+        if args.platform:
+            filters["platform"] = args.platform
+
+        if args.specialization:
+            filters["specialization"] = args.specialization
+
+        # Get agents with filters
+        agents = manager.list_cached_agents_with_filters(
+            repo_identifier=args.source, filters=filters if filters else None
+        )
+
+        # Check if any sources are configured
+        if not agents and not sources_config.list_sources():
+            console.print("[yellow]⚠️  No agent sources configured.[/yellow]")
+            console.print("\nAdd a source with:")
+            console.print("  claude-mpm agent-source add <git-url>")
+            return 1
+
+        # Check if cache might be empty
+        if not agents and not filters:
+            console.print("[yellow]⚠️  No agents found in cache.[/yellow]")
+            console.print("\nTry syncing sources first:")
+            console.print("  claude-mpm agent-source update")
+            return 1
+
+        # Output based on format
+        if args.format == "json":
+            filters_applied = {
+                k: v
+                for k, v in [
+                    ("source", args.source),
+                    ("category", args.category),
+                    ("language", args.language),
+                    ("framework", args.framework),
+                    ("platform", args.platform),
+                    ("specialization", args.specialization),
+                ]
+                if v is not None
+            }
+
+            _output_json_format(agents, filters_applied)
+
+        elif args.format == "simple":
+            _output_simple_format(agents)
+
+        else:  # table (default)
+            _output_table_format(agents, verbose=args.verbose)
+
+        return 0
+
+    except Exception as e:
+        logger.error(f"Error discovering agents: {e}", exc_info=True)
+        console.print(f"[bold red]Error:[/bold red] {e}")
+        return 1

claude_mpm/cli/commands/agents_recommend.py

@@ -0,0 +1,309 @@
+"""
+Agents Recommend CLI Command for Claude MPM Framework
+======================================================
+
+WHY: This module provides a CLI interface for getting agent recommendations
+based on project toolchain without deploying anything. Useful for reviewing
+recommendations before committing to deployment.
+
+DESIGN DECISION: Focused on recommendation display with detailed reasoning,
+showing users why each agent was recommended. Supports JSON output for
+integration with other tools.
+
+Part of TSK-0054: Auto-Configuration Feature - Phase 5
+"""
+
+import json
+from pathlib import Path
+from typing import Optional
+
+try:
+    from rich.console import Console
+    from rich.panel import Panel
+    from rich.table import Table
+
+    RICH_AVAILABLE = True
+except ImportError:
+    RICH_AVAILABLE = False
+
+from ...services.agents.recommender import AgentRecommenderService
+from ...services.agents.registry import AgentRegistry
+from ...services.project.toolchain_analyzer import ToolchainAnalyzerService
+from ..shared import BaseCommand, CommandResult
+
+
+class AgentsRecommendCommand(BaseCommand):
+    """
+    Handle agents recommend CLI command.
+
+    This command analyzes the project toolchain and recommends appropriate
+    agents without deploying them. Shows detailed reasoning for each
+    recommendation.
+    """
+
+    def __init__(self):
+        """Initialize the agents recommend command."""
+        super().__init__("agents-recommend")
+        self.console = Console() if RICH_AVAILABLE else None
+        self._toolchain_analyzer = None
+        self._agent_recommender = None
+
+    @property
+    def toolchain_analyzer(self) -> ToolchainAnalyzerService:
+        """Get toolchain analyzer (lazy loaded)."""
+        if self._toolchain_analyzer is None:
+            self._toolchain_analyzer = ToolchainAnalyzerService()
+        return self._toolchain_analyzer
+
+    @property
+    def agent_recommender(self) -> AgentRecommenderService:
+        """Get agent recommender (lazy loaded)."""
+        if self._agent_recommender is None:
+            agent_registry = AgentRegistry()
+            self._agent_recommender = AgentRecommenderService(
+                agent_registry=agent_registry
+            )
+        return self._agent_recommender
+
+    def validate_args(self, args) -> Optional[str]:
+        """Validate command arguments."""
+        # Validate project path
+        project_path = (
+            Path(args.project_path)
+            if hasattr(args, "project_path") and args.project_path
+            else Path.cwd()
+        )
+        if not project_path.exists():
+            return f"Project path does not exist: {project_path}"
+
+        # Validate min_confidence range
+        if hasattr(args, "min_confidence") and args.min_confidence:
+            if not 0.0 <= args.min_confidence <= 1.0:
+                return "min_confidence must be between 0.0 and 1.0"
+
+        return None
+
+    def run(self, args) -> CommandResult:
+        """
+        Execute agents recommend command.
+
+        Returns:
+            CommandResult with success status and exit code
+        """
+        try:
+            # Setup logging
+            self.setup_logging(args)
+
+            # Validate arguments
+            error = self.validate_args(args)
+            if error:
+                return CommandResult.error_result(error)
+
+            # Get configuration options
+            project_path = (
+                Path(args.project_path)
+                if hasattr(args, "project_path") and args.project_path
+                else Path.cwd()
+            )
+            min_confidence = (
+                args.min_confidence
+                if hasattr(args, "min_confidence") and args.min_confidence
+                else 0.8
+            )
+            json_output = args.json if hasattr(args, "json") and args.json else False
+            show_reasoning = (
+                args.show_reasoning
+                if hasattr(args, "show_reasoning") and args.show_reasoning
+                else True
+            )
+
+            # Analyze toolchain
+            if self.console and not json_output:
+                with self.console.status("[bold green]Analyzing project toolchain..."):
+                    analysis = self.toolchain_analyzer.analyze_project(
+                        str(project_path)
+                    )
+            else:
+                analysis = self.toolchain_analyzer.analyze_project(str(project_path))
+
+            # Get recommendations
+            if self.console and not json_output:
+                with self.console.status(
+                    "[bold green]Generating agent recommendations..."
+                ):
+                    recommendations = self.agent_recommender.recommend_agents(
+                        analysis, min_confidence
+                    )
+            else:
+                recommendations = self.agent_recommender.recommend_agents(
+                    analysis, min_confidence
+                )
+
+            # Output results
+            if json_output:
+                return self._output_json(recommendations, analysis)
+            return self._display_results(recommendations, analysis, show_reasoning)
+
+        except KeyboardInterrupt:
+            if self.console:
+                self.console.print("\n\n❌ Operation cancelled by user")
+            else:
+                print("\n\nOperation cancelled by user")
+            return CommandResult.error_result("Operation cancelled", exit_code=130)
+
+        except Exception as e:
+            self.logger.exception("Agent recommendation failed")
+            error_msg = f"Agent recommendation failed: {e!s}"
+            if self.console:
+                self.console.print(f"\n❌ {error_msg}")
+            else:
+                print(f"\n{error_msg}")
+            return CommandResult.error_result(error_msg)
+
+    def _display_results(
+        self, recommendations, analysis, show_reasoning: bool
+    ) -> CommandResult:
+        """Display agent recommendations with Rich formatting."""
+        if not self.console:
+            return self._display_results_plain(
+                recommendations, analysis, show_reasoning
+            )
+
+        # Display header
+        self.console.print("\n🤖 Agent Recommendations", style="bold blue")
+        self.console.print(f"Project: {analysis.project_path}\n")
+
+        # Display quick summary
+        if recommendations:
+            summary_text = (
+                f"Found {len(recommendations)} recommended agent(s) "
+                f"for your project based on detected toolchain."
+            )
+            panel = Panel(summary_text, border_style="green")
+            self.console.print(panel)
+        else:
+            panel = Panel(
+                "No agents recommended for this project.\n"
+                "Try lowering the confidence threshold with --min-confidence",
+                border_style="yellow",
+            )
+            self.console.print(panel)
+            return CommandResult.success_result()
+
+        # Display recommendations table
+        self.console.print("\n📋 Recommended Agents:", style="bold green")
+        table = Table(show_header=True, header_style="bold")
+        table.add_column("Agent ID", style="cyan")
+        table.add_column("Confidence", style="green")
+        table.add_column("Priority", style="yellow")
+        if show_reasoning:
+            table.add_column("Reasoning", style="dim", no_wrap=False)
+
+        for rec in recommendations:
+            confidence_pct = int(rec.confidence * 100)
+            bar = "█" * (confidence_pct // 10) + "░" * (10 - confidence_pct // 10)
+            confidence_str = f"{bar} {confidence_pct}%"
+
+            if show_reasoning:
+                table.add_row(
+                    rec.agent_id,
+                    confidence_str,
+                    str(rec.priority),
+                    rec.reasoning,
+                )
+            else:
+                table.add_row(rec.agent_id, confidence_str, str(rec.priority))
+
+        self.console.print(table)
+
+        # Display match details if reasoning enabled
+        if show_reasoning:
+            self.console.print("\n🔍 Match Details:", style="bold blue")
+            for rec in recommendations:
+                self.console.print(f"\n[bold cyan]{rec.agent_id}[/bold cyan]")
+                self.console.print(f"  Confidence: {int(rec.confidence * 100)}%")
+                self.console.print(f"  Priority: {rec.priority}")
+                self.console.print(f"  Reasoning: {rec.reasoning}")
+
+                if rec.matched_capabilities:
+                    self.console.print("  Matched capabilities:", style="green")
+                    for cap in rec.matched_capabilities[:5]:
+                        self.console.print(f"    • {cap}", style="dim")
+                    if len(rec.matched_capabilities) > 5:
+                        remaining = len(rec.matched_capabilities) - 5
+                        self.console.print(f"    ... and {remaining} more", style="dim")
+
+        # Display next steps
+        self.console.print("\n💡 Next Steps:", style="bold yellow")
+        self.console.print("  1. Review the recommendations and their reasoning")
+        self.console.print(
+            "  2. Deploy agents with: [bold]claude-mpm auto-configure[/bold]"
+        )
+        self.console.print(
+            "  3. Or preview deployment with: [bold]claude-mpm auto-configure --preview[/bold]"
+        )
+
+        return CommandResult.success_result()
+
+    def _display_results_plain(
+        self, recommendations, analysis, show_reasoning: bool
+    ) -> CommandResult:
+        """Display results in plain text (fallback)."""
+        print("\n🤖 Agent Recommendations")
+        print(f"Project: {analysis.project_path}\n")
+
+        if not recommendations:
+            print("No agents recommended for this project.")
+            print("Try lowering the confidence threshold with --min-confidence")
+            return CommandResult.success_result()
+
+        print(f"Found {len(recommendations)} recommended agent(s) for your project:\n")
+
+        for rec in recommendations:
+            confidence_pct = int(rec.confidence * 100)
+            print(f"• {rec.agent_id} ({confidence_pct}% confidence)")
+
+            if show_reasoning:
+                print(f"  Priority: {rec.priority}")
+                print(f"  Reasoning: {rec.reasoning}")
+
+                if rec.matched_capabilities:
+                    print("  Matched capabilities:")
+                    for cap in rec.matched_capabilities[:5]:
+                        print(f"    - {cap}")
+                    if len(rec.matched_capabilities) > 5:
+                        remaining = len(rec.matched_capabilities) - 5
+                        print(f"    ... and {remaining} more")
+                print()
+
+        print("\nNext Steps:")
+        print("  1. Review the recommendations and their reasoning")
+        print("  2. Deploy agents with: claude-mpm auto-configure")
+        print("  3. Or preview deployment with: claude-mpm auto-configure --preview")
+
+        return CommandResult.success_result()
+
+    def _output_json(self, recommendations, analysis) -> CommandResult:
+        """Output recommendations as JSON."""
+        output = {
+            "project_path": analysis.project_path,
+            "recommendations": [
+                {
+                    "agent_id": rec.agent_id,
+                    "confidence": rec.confidence,
+                    "priority": rec.priority,
+                    "reasoning": rec.reasoning,
+                    "matched_capabilities": rec.matched_capabilities,
+                    "requirements": rec.requirements,
+                }
+                for rec in recommendations
+            ],
+            "toolchain_summary": {
+                "languages": len(analysis.languages),
+                "frameworks": len(analysis.frameworks),
+                "deployment_targets": len(analysis.deployment_targets),
+            },
+        }
+
+        print(json.dumps(output, indent=2))
+        return CommandResult.success_result(data=output)