claude-mpm 3.9.11__py3-none-any.whl → 4.0.4__py3-none-any.whl

claude_mpm/services/core/interfaces/agent.py

@@ -0,0 +1,351 @@
+"""
+Agent Management Interfaces for Claude MPM Framework
+===================================================
+
+WHY: This module contains all interfaces related to agent management, deployment,
+capabilities, and discovery. These interfaces are grouped together because they
+all deal with agent lifecycle and operations.
+
+DESIGN DECISION: Agent-related interfaces are separated from infrastructure
+because they represent domain-specific functionality rather than foundational
+framework services.
+
+EXTRACTED FROM: services/core/interfaces.py (lines 198-875)
+- Agent registry and metadata
+- Agent deployment and capabilities
+- Agent system instructions and subprocess management
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+
+# Agent registry interface
+@dataclass
+class AgentMetadata:
+    """Enhanced agent metadata with specialization and model configuration support"""
+
+    name: str
+    type: str
+    path: str
+    tier: str
+    description: Optional[str] = None
+    version: Optional[str] = None
+    capabilities: List[str] = None
+    specializations: List[str] = None
+    frameworks: List[str] = None
+    domains: List[str] = None
+    roles: List[str] = None
+    is_hybrid: bool = False
+    validation_score: float = 0.0
+    last_modified: Optional[float] = None
+    # Model configuration fields
+    preferred_model: Optional[str] = None
+    model_config: Optional[Dict[str, Any]] = None
+
+    def __post_init__(self):
+        if self.capabilities is None:
+            self.capabilities = []
+        if self.specializations is None:
+            self.specializations = []
+        if self.frameworks is None:
+            self.frameworks = []
+        if self.domains is None:
+            self.domains = []
+        if self.roles is None:
+            self.roles = []
+        if self.model_config is None:
+            self.model_config = {}
+
+
+class IAgentRegistry(ABC):
+    """Interface for agent discovery and management"""
+
+    @abstractmethod
+    async def discover_agents(
+        self, force_refresh: bool = False
+    ) -> Dict[str, AgentMetadata]:
+        """Discover all available agents"""
+        pass
+
+    @abstractmethod
+    async def get_agent(self, agent_name: str) -> Optional[AgentMetadata]:
+        """Get specific agent metadata"""
+        pass
+
+    @abstractmethod
+    async def list_agents(
+        self, agent_type: Optional[str] = None, tier: Optional[str] = None
+    ) -> List[AgentMetadata]:
+        """List agents with optional filtering"""
+        pass
+
+    @abstractmethod
+    async def get_specialized_agents(self, agent_type: str) -> List[AgentMetadata]:
+        """Get agents of a specific specialized type"""
+        pass
+
+    @abstractmethod
+    async def refresh_agent_cache(self) -> None:
+        """Refresh the agent metadata cache"""
+        pass
+
+
+# Agent deployment interface
+class AgentDeploymentInterface(ABC):
+    """Interface for agent deployment operations.
+
+    WHY: Agent deployment needs to be decoupled from concrete implementations
+    to enable different deployment strategies (local, remote, containerized).
+    This interface ensures consistency across different deployment backends.
+
+    DESIGN DECISION: Methods return deployment status/results to enable
+    proper error handling and rollback operations when deployments fail.
+    """
+
+    @abstractmethod
+    def deploy_agents(
+        self, force: bool = False, include_all: bool = False
+    ) -> Dict[str, Any]:
+        """Deploy agents to target environment.
+
+        Args:
+            force: Force deployment even if agents already exist
+            include_all: Include all agents, ignoring exclusion lists
+
+        Returns:
+            Dictionary with deployment results and status
+        """
+        pass
+
+    @abstractmethod
+    def validate_agent(self, agent_path: Path) -> Tuple[bool, List[str]]:
+        """Validate agent configuration and structure.
+
+        Args:
+            agent_path: Path to agent configuration file
+
+        Returns:
+            Tuple of (is_valid, list_of_errors)
+        """
+        pass
+
+    @abstractmethod
+    def get_deployment_status(self, agent_name: str) -> Dict[str, Any]:
+        """Get deployment status for a specific agent.
+
+        Args:
+            agent_name: Name of the agent
+
+        Returns:
+            Dictionary with deployment status information
+        """
+        pass
+
+
+# Agent capabilities interface
+class AgentCapabilitiesInterface(ABC):
+    """Interface for agent capabilities discovery and generation.
+
+    WHY: Agent capabilities need to be discovered from multiple sources
+    (system, user, project) and formatted for Claude. This interface
+    abstracts the discovery and formatting logic to enable different
+    agent discovery strategies and capability formats.
+
+    DESIGN DECISION: Returns formatted strings ready for Claude consumption
+    to minimize processing overhead in the main execution path.
+    """
+
+    @abstractmethod
+    def generate_agent_capabilities(self, agent_type: str = "general") -> str:
+        """Generate formatted agent capabilities for Claude.
+
+        Args:
+            agent_type: Type of agent to generate capabilities for
+
+        Returns:
+            Formatted capabilities string for Claude consumption
+        """
+        pass
+
+
+# System instructions interface
+class SystemInstructionsInterface(ABC):
+    """Interface for system instructions loading and processing.
+
+    WHY: System instructions need to be loaded from multiple sources
+    (project, framework) with template processing and metadata stripping.
+    This interface abstracts the loading and processing logic to enable
+    different instruction sources and processing strategies.
+
+    DESIGN DECISION: Provides both raw and processed instruction methods
+    to support different use cases and enable caching of processed results.
+    """
+
+    @abstractmethod
+    def load_system_instructions(self, instruction_type: str = "default") -> str:
+        """Load and process system instructions.
+
+        Args:
+            instruction_type: Type of instructions to load
+
+        Returns:
+            Processed system instructions string
+        """
+        pass
+
+    @abstractmethod
+    def get_available_instruction_types(self) -> List[str]:
+        """Get list of available instruction types.
+
+        Returns:
+            List of available instruction type names
+        """
+        pass
+
+    @abstractmethod
+    def validate_instructions(self, instructions: str) -> Tuple[bool, List[str]]:
+        """Validate system instructions format and content.
+
+        Args:
+            instructions: Instructions content to validate
+
+        Returns:
+            Tuple of (is_valid, list_of_errors)
+        """
+        pass
+
+
+# Subprocess launcher interface
+class SubprocessLauncherInterface(ABC):
+    """Interface for subprocess launching and PTY management.
+
+    WHY: Subprocess launching involves complex PTY management, signal handling,
+    and I/O coordination. This interface abstracts the subprocess launching
+    logic to enable different launching strategies and improve testability.
+
+    DESIGN DECISION: Provides both synchronous and asynchronous launch methods
+    to support different execution contexts and performance requirements.
+    """
+
+    @abstractmethod
+    def launch_subprocess(self, command: List[str], **kwargs) -> Dict[str, Any]:
+        """Launch a subprocess with PTY support.
+
+        Args:
+            command: Command and arguments to execute
+            **kwargs: Additional subprocess options
+
+        Returns:
+            Dictionary with subprocess information and handles
+        """
+        pass
+
+    @abstractmethod
+    async def launch_subprocess_async(
+        self, command: List[str], **kwargs
+    ) -> Dict[str, Any]:
+        """Launch a subprocess asynchronously with PTY support.
+
+        Args:
+            command: Command and arguments to execute
+            **kwargs: Additional subprocess options
+
+        Returns:
+            Dictionary with subprocess information and handles
+        """
+        pass
+
+    @abstractmethod
+    def terminate_subprocess(self, process_id: str) -> bool:
+        """Terminate a running subprocess.
+
+        Args:
+            process_id: ID of the process to terminate
+
+        Returns:
+            True if termination successful
+        """
+        pass
+
+    @abstractmethod
+    def get_subprocess_status(self, process_id: str) -> Dict[str, Any]:
+        """Get status of a running subprocess.
+
+        Args:
+            process_id: ID of the process
+
+        Returns:
+            Dictionary with process status information
+        """
+        pass
+
+
+# Runner configuration interface
+class RunnerConfigurationInterface(ABC):
+    """Interface for runner configuration and initialization.
+
+    WHY: ClaudeRunner initialization involves complex service registration,
+    configuration loading, and logger setup. This interface abstracts the
+    configuration logic to enable different configuration strategies and
+    improve testability.
+
+    DESIGN DECISION: Separates configuration loading from service registration
+    to enable independent testing and different configuration sources.
+    """
+
+    @abstractmethod
+    def initialize_runner(self, config: Dict[str, Any]) -> Dict[str, Any]:
+        """Initialize runner with configuration.
+
+        Args:
+            config: Configuration dictionary
+
+        Returns:
+            Dictionary with initialization results
+        """
+        pass
+
+    @abstractmethod
+    def register_services(self, service_container) -> None:
+        """Register services with the dependency injection container.
+
+        Args:
+            service_container: Service container for registration
+        """
+        pass
+
+    @abstractmethod
+    def load_configuration(self, config_path: Optional[Path] = None) -> Dict[str, Any]:
+        """Load configuration from file or defaults.
+
+        Args:
+            config_path: Optional path to configuration file
+
+        Returns:
+            Loaded configuration dictionary
+        """
+        pass
+
+    @abstractmethod
+    def validate_configuration(self, config: Dict[str, Any]) -> Tuple[bool, List[str]]:
+        """Validate configuration structure and values.
+
+        Args:
+            config: Configuration to validate
+
+        Returns:
+            Tuple of (is_valid, list_of_errors)
+        """
+        pass
+
+    @abstractmethod
+    def setup_logging(self, config: Dict[str, Any]) -> None:
+        """Setup logging configuration.
+
+        Args:
+            config: Logging configuration
+        """
+        pass

claude_mpm/services/core/interfaces/communication.py

@@ -0,0 +1,343 @@
+"""
+Communication and External Service Interfaces for Claude MPM Framework
+======================================================================
+
+WHY: This module contains interfaces for external communication including
+WebSocket/SocketIO services, project analysis, and ticket management.
+These are grouped together because they handle external interactions.
+
+DESIGN DECISION: Communication interfaces are separated because they deal
+with external systems and protocols, requiring different error handling
+and reliability patterns than internal services.
+
+EXTRACTED FROM: services/core/interfaces.py (lines 1195-1397)
+- WebSocket/SocketIO communication
+- Project analysis
+- Ticket management
+"""
+
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+# WebSocket/SocketIO service interface
+class SocketIOServiceInterface(ABC):
+    """Interface for WebSocket communication.
+
+    WHY: Real-time communication is essential for monitoring and interactive
+    features. This interface abstracts WebSocket/SocketIO implementation to
+    enable different transport mechanisms and fallback strategies.
+
+    DESIGN DECISION: Provides both broadcasting and targeted messaging to
+    support different communication patterns and enable efficient updates.
+    """
+
+    @abstractmethod
+    def start_sync(self) -> None:
+        """Start the WebSocket server synchronously."""
+        pass
+
+    @abstractmethod
+    def stop_sync(self) -> None:
+        """Stop the WebSocket server synchronously."""
+        pass
+
+    @abstractmethod
+    def broadcast_event(self, event_type: str, data: Dict[str, Any]) -> None:
+        """Broadcast an event to all connected clients.
+
+        Args:
+            event_type: Type of event to broadcast
+            data: Event data to send
+        """
+        pass
+
+    @abstractmethod
+    def send_to_client(
+        self, client_id: str, event_type: str, data: Dict[str, Any]
+    ) -> bool:
+        """Send an event to a specific client.
+
+        Args:
+            client_id: ID of the target client
+            event_type: Type of event to send
+            data: Event data to send
+
+        Returns:
+            True if message sent successfully
+        """
+        pass
+
+    @abstractmethod
+    def get_connection_count(self) -> int:
+        """Get number of connected clients.
+
+        Returns:
+            Number of connected clients
+        """
+        pass
+
+    @abstractmethod
+    def is_running(self) -> bool:
+        """Check if server is running.
+
+        Returns:
+            True if server is active
+        """
+        pass
+
+    @abstractmethod
+    def session_started(
+        self, session_id: str, launch_method: str, working_dir: str
+    ) -> None:
+        """Notify that a session has started.
+
+        Args:
+            session_id: ID of the started session
+            launch_method: Method used to launch the session
+            working_dir: Working directory of the session
+        """
+        pass
+
+    @abstractmethod
+    def session_ended(self) -> None:
+        """Notify that a session has ended."""
+        pass
+
+    @abstractmethod
+    def claude_status_changed(
+        self, status: str, pid: Optional[int] = None, message: str = ""
+    ) -> None:
+        """Notify Claude status change.
+
+        Args:
+            status: New status of Claude
+            pid: Process ID if applicable
+            message: Optional status message
+        """
+        pass
+
+    @abstractmethod
+    def agent_delegated(self, agent: str, task: str, status: str = "started") -> None:
+        """Notify agent delegation.
+
+        Args:
+            agent: Name of the delegated agent
+            task: Task assigned to the agent
+            status: Status of the delegation
+        """
+        pass
+
+    @abstractmethod
+    def todo_updated(self, todos: List[Dict[str, Any]]) -> None:
+        """Notify todo list update.
+
+        Args:
+            todos: Updated list of todo items
+        """
+        pass
+
+
+# Project analyzer interface
+class ProjectAnalyzerInterface(ABC):
+    """Interface for project analysis operations.
+
+    WHY: Understanding project structure and characteristics is essential for
+    context-aware agent behavior. This interface abstracts project analysis
+    to support different project types and structures.
+
+    DESIGN DECISION: Analysis methods return structured data to enable caching
+    and incremental updates when project structure changes.
+    """
+
+    @abstractmethod
+    def analyze_project(self, project_path: Path) -> Dict[str, Any]:
+        """Analyze project structure and characteristics.
+
+        Args:
+            project_path: Path to the project root
+
+        Returns:
+            Dictionary with project analysis results
+        """
+        pass
+
+    @abstractmethod
+    def detect_technology_stack(self) -> List[str]:
+        """Detect technologies used in the project.
+
+        Returns:
+            List of detected technologies
+        """
+        pass
+
+    @abstractmethod
+    def analyze_code_patterns(self) -> Dict[str, Any]:
+        """Analyze code patterns and conventions.
+
+        Returns:
+            Dictionary of pattern analysis results
+        """
+        pass
+
+    @abstractmethod
+    def get_project_structure(self) -> Dict[str, Any]:
+        """Get project directory structure analysis.
+
+        Returns:
+            Dictionary representing project structure
+        """
+        pass
+
+    @abstractmethod
+    def identify_entry_points(self) -> List[Path]:
+        """Identify project entry points.
+
+        Returns:
+            List of entry point paths
+        """
+        pass
+
+    @abstractmethod
+    def get_dependencies(self) -> Dict[str, List[str]]:
+        """Get project dependencies by type.
+
+        Returns:
+            Dictionary mapping dependency types to lists of dependencies
+        """
+        pass
+
+    @abstractmethod
+    def analyze_test_coverage(self) -> Dict[str, Any]:
+        """Analyze test coverage if available.
+
+        Returns:
+            Dictionary with test coverage information
+        """
+        pass
+
+    @abstractmethod
+    def get_build_configuration(self) -> Dict[str, Any]:
+        """Get build configuration information.
+
+        Returns:
+            Dictionary with build configuration details
+        """
+        pass
+
+
+# Ticket manager interface
+class TicketManagerInterface(ABC):
+    """Interface for ticket management operations.
+
+    WHY: Ticket management provides work tracking and organization. This
+    interface abstracts ticket operations to support different backend
+    systems (file-based, API-based, database).
+
+    DESIGN DECISION: Ticket operations return success/failure status to enable
+    proper error handling and fallback strategies when ticket systems are unavailable.
+    """
+
+    @abstractmethod
+    def create_ticket(
+        self, title: str, description: str, priority: str = "medium"
+    ) -> str:
+        """Create a new ticket.
+
+        Args:
+            title: Ticket title
+            description: Ticket description
+            priority: Ticket priority level
+
+        Returns:
+            Ticket ID
+        """
+        pass
+
+    @abstractmethod
+    def get_ticket(self, ticket_id: str) -> Optional[Dict[str, Any]]:
+        """Get ticket by ID.
+
+        Args:
+            ticket_id: ID of ticket to retrieve
+
+        Returns:
+            Ticket data or None if not found
+        """
+        pass
+
+    @abstractmethod
+    def update_ticket(self, ticket_id: str, updates: Dict[str, Any]) -> bool:
+        """Update ticket information.
+
+        Args:
+            ticket_id: ID of ticket to update
+            updates: Dictionary of fields to update
+
+        Returns:
+            True if update successful
+        """
+        pass
+
+    @abstractmethod
+    def list_tickets(
+        self, status: Optional[str] = None, priority: Optional[str] = None
+    ) -> List[Dict[str, Any]]:
+        """List tickets with optional filtering.
+
+        Args:
+            status: Optional status filter
+            priority: Optional priority filter
+
+        Returns:
+            List of ticket data
+        """
+        pass
+
+    @abstractmethod
+    def assign_ticket(self, ticket_id: str, assignee: str) -> bool:
+        """Assign ticket to a user.
+
+        Args:
+            ticket_id: ID of ticket to assign
+            assignee: User to assign ticket to
+
+        Returns:
+            True if assignment successful
+        """
+        pass
+
+    @abstractmethod
+    def close_ticket(self, ticket_id: str, resolution: Optional[str] = None) -> bool:
+        """Close a ticket.
+
+        Args:
+            ticket_id: ID of ticket to close
+            resolution: Optional resolution description
+
+        Returns:
+            True if close successful
+        """
+        pass
+
+    @abstractmethod
+    def search_tickets(self, query: str) -> List[Dict[str, Any]]:
+        """Search tickets by query.
+
+        Args:
+            query: Search query string
+
+        Returns:
+            List of matching ticket data
+        """
+        pass
+
+    @abstractmethod
+    def get_ticket_statistics(self) -> Dict[str, Any]:
+        """Get ticket statistics.
+
+        Returns:
+            Dictionary with ticket statistics
+        """
+        pass