claude-mpm 4.7.4__py3-none-any.whl → 4.18.2__py3-none-any.whl

claude_mpm/services/core/__init__.py

@@ -16,7 +16,9 @@ from .interfaces import (  # Core dependency injection; Configuration management
     CacheEntry,
     HealthStatus,
     HookServiceInterface,
+    IAgentRecommender,
     IAgentRegistry,
+    IAutoConfigManager,
     ICacheService,
     IConfigurationManager,
     IConfigurationService,
@@ -31,6 +33,7 @@ from .interfaces import (  # Core dependency injection; Configuration management
     IServiceLifecycle,
     IStructuredLogger,
     ITemplateManager,
+    IToolchainAnalyzer,
     MemoryServiceInterface,
     ProjectAnalyzerInterface,
     ServiceType,
@@ -38,8 +41,21 @@ from .interfaces import (  # Core dependency injection; Configuration management
     TemplateRenderContext,
     TicketManagerInterface,
 )
+from .models import (  # Data models for services
+    AgentCapabilities,
+    AgentRecommendation,
+    ConfidenceLevel,
+    ConfigurationPreview,
+    ConfigurationResult,
+    DeploymentTarget,
+    Framework,
+    LanguageDetection,
+    ToolchainAnalysis,
+    ToolchainComponent,
+    ValidationResult,
+)
 
-__all__ = [
+__all__ = [  # noqa: RUF022 - Grouped by category with comments for clarity
     # Service interfaces
     "AgentDeploymentInterface",
     "AgentMetadata",
@@ -48,7 +64,9 @@ __all__ = [
     "CacheEntry",
     "HealthStatus",
     "HookServiceInterface",
+    "IAgentRecommender",
     "IAgentRegistry",
+    "IAutoConfigManager",
     "ICacheService",
     "IConfigurationManager",
     "IConfigurationService",
@@ -63,6 +81,7 @@ __all__ = [
     "IServiceLifecycle",
     "IStructuredLogger",
     "ITemplateManager",
+    "IToolchainAnalyzer",
     # Registry
     "InterfaceRegistry",
     "MemoryServiceInterface",
@@ -73,4 +92,17 @@ __all__ = [
     "SyncBaseService",
     "TemplateRenderContext",
     "TicketManagerInterface",
+    # Data models - Toolchain
+    "ConfidenceLevel",
+    "ToolchainComponent",
+    "LanguageDetection",
+    "Framework",
+    "DeploymentTarget",
+    "ToolchainAnalysis",
+    # Data models - Agent Configuration
+    "AgentCapabilities",
+    "AgentRecommendation",
+    "ConfigurationResult",
+    "ValidationResult",
+    "ConfigurationPreview",
 ]

claude_mpm/services/core/interfaces/__init__.py

@@ -24,11 +24,13 @@ MODULES:
 """
 
 # Agent interfaces (agent management and operations)
-from .agent import (  # Agent registry; Agent deployment; Agent capabilities; System instructions; Subprocess management; Runner configuration
+from .agent import (  # Agent registry; Agent deployment; Agent capabilities; System instructions; Subprocess management; Runner configuration; Agent recommendation; Auto-configuration
     AgentCapabilitiesInterface,
     AgentDeploymentInterface,
     AgentMetadata,
+    IAgentRecommender,
     IAgentRegistry,
+    IAutoConfigManager,
     RunnerConfigurationInterface,
     SubprocessLauncherInterface,
     SystemInstructionsInterface,
@@ -41,6 +43,12 @@ from .communication import (  # WebSocket/SocketIO; Project analysis; Ticket man
     TicketManagerInterface,
 )
 
+# Health interfaces (health monitoring)
+from .health import (  # Health checks; Health monitoring
+    IHealthCheck,
+    IHealthCheckManager,
+)
+
 # Infrastructure interfaces (core framework services)
 from .infrastructure import (  # Type variables; Core dependency injection; Configuration management; Caching; Health monitoring; Template management; Service factory; Logging; Service lifecycle; Error handling; Performance monitoring; Event system
     CacheEntry,
@@ -63,6 +71,33 @@ from .infrastructure import (  # Type variables; Core dependency injection; Conf
     TemplateRenderContext,
 )
 
+# Model interfaces (content processing and model providers)
+from .model import (  # Model providers; Routing
+    IModelProvider,
+    IModelRouter,
+    ModelCapability,
+    ModelProvider,
+    ModelResponse,
+)
+
+# Process interfaces (local process management)
+from .process import (  # Process lifecycle; State persistence
+    IDeploymentStateManager,
+    ILocalProcessManager,
+)
+
+# Project interfaces (project analysis and toolchain detection)
+from .project import (  # Toolchain analysis
+    IToolchainAnalyzer,
+)
+
+# Restart interfaces (auto-restart management)
+from .restart import (  # Crash detection; Restart policy; Restart orchestration
+    ICrashDetector,
+    IRestartManager,
+    IRestartPolicy,
+)
+
 # Service interfaces (business services)
 from .service import (  # Version service; Command handling; Memory management; Session management; Utilities; Hook service
     CommandHandlerInterface,
@@ -74,6 +109,13 @@ from .service import (  # Version service; Command handling; Memory management;
     VersionServiceInterface,
 )
 
+# Stability interfaces (proactive monitoring and crash prevention)
+from .stability import (  # Memory leak detection; Log monitoring; Resource monitoring
+    ILogMonitor,
+    IMemoryLeakDetector,
+    IResourceMonitor,
+)
+
 
 # Interface registry for dependency injection discovery
 class InterfaceRegistry:
@@ -118,6 +160,27 @@ class InterfaceRegistry:
         "socketio_service": SocketIOServiceInterface,
         "project_analyzer": ProjectAnalyzerInterface,
         "ticket_manager": TicketManagerInterface,
+        # Project interfaces
+        "toolchain_analyzer": IToolchainAnalyzer,
+        "agent_recommender": IAgentRecommender,
+        "auto_config_manager": IAutoConfigManager,
+        # Model interfaces
+        "model_provider": IModelProvider,
+        "model_router": IModelRouter,
+        # Process interfaces
+        "deployment_state_manager": IDeploymentStateManager,
+        "local_process_manager": ILocalProcessManager,
+        # Health interfaces
+        "health_check": IHealthCheck,
+        "health_check_manager": IHealthCheckManager,
+        # Restart interfaces
+        "crash_detector": ICrashDetector,
+        "restart_policy": IRestartPolicy,
+        "restart_manager": IRestartManager,
+        # Stability interfaces
+        "memory_leak_detector": IMemoryLeakDetector,
+        "log_monitor": ILogMonitor,
+        "resource_monitor": IResourceMonitor,
     }
 
     @classmethod
@@ -142,7 +205,7 @@ class InterfaceRegistry:
 
 
 # Re-export everything for backward compatibility
-__all__ = [
+__all__ = [  # noqa: RUF022 - Semantic grouping by domain preferred over alphabetical
     "AgentCapabilitiesInterface",
     "AgentDeploymentInterface",
     "AgentMetadata",
@@ -151,23 +214,47 @@ __all__ = [
     "HealthStatus",
     "HookServiceInterface",
     # Agent interfaces
+    "IAgentRecommender",
     "IAgentRegistry",
+    "IAutoConfigManager",
     "ICacheService",
     "IConfigurationManager",
     "IConfigurationService",
+    # Process interfaces
+    "IDeploymentStateManager",
     "IErrorHandler",
     "IEventBus",
+    # Health interfaces
+    "IHealthCheck",
+    "IHealthCheckManager",
     "IHealthMonitor",
+    # Infrastructure interfaces
+    "ILocalProcessManager",
+    # Restart interfaces
+    "ICrashDetector",
+    "IRestartManager",
+    "IRestartPolicy",
+    # Stability interfaces
+    "IMemoryLeakDetector",
+    "ILogMonitor",
+    "IResourceMonitor",
+    # Model interfaces
+    "IModelProvider",
+    "IModelRouter",
     "IPerformanceMonitor",
     "IPromptCache",
-    # Infrastructure interfaces
     "IServiceContainer",
     "IServiceFactory",
     "IServiceLifecycle",
     "IStructuredLogger",
     "ITemplateManager",
+    # Project interfaces
+    "IToolchainAnalyzer",
     # Registry
     "InterfaceRegistry",
+    "ModelCapability",
+    "ModelProvider",
+    "ModelResponse",
     "MemoryHookInterface",
     "MemoryServiceInterface",
     "ProjectAnalyzerInterface",

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/health.py

@@ -0,0 +1,172 @@
+"""
+Health Check Interfaces for Claude MPM Framework
+=================================================
+
+WHY: This module defines interfaces for health monitoring operations,
+enabling the local-ops-agent to perform comprehensive health checks on
+deployed processes including HTTP endpoints, process status, and resource usage.
+
+DESIGN DECISION: Health check interfaces are separated to enable modular
+health monitoring with different check types (HTTP, process, resource).
+
+ARCHITECTURE:
+- IHealthCheck: Interface for individual health check implementations
+- IHealthCheckManager: Interface for orchestrating multiple health checks
+- Health data models defined in models/health.py
+
+USAGE:
+    http_check = HttpHealthCheck(endpoint="http://localhost:3000/health")
+    process_check = ProcessHealthCheck(process_manager)
+    resource_check = ResourceHealthCheck(process_manager)
+
+    health_manager = HealthCheckManager(
+        process_manager=process_manager,
+        check_interval=30
+    )
+    health_manager.start_monitoring()
+"""
+
+from abc import ABC, abstractmethod
+from typing import List
+
+from claude_mpm.services.core.models.health import (
+    DeploymentHealth,
+    HealthCheckResult,
+)
+
+
+class IHealthCheck(ABC):
+    """
+    Interface for individual health check implementations.
+
+    WHY: Abstracts different types of health checks (HTTP, process, resource)
+    to enable flexible health monitoring strategies.
+
+    DESIGN DECISION: Each check type implements this interface to provide
+    a consistent API for executing checks and interpreting results.
+
+    Thread Safety: Implementations must be thread-safe for concurrent execution.
+    """
+
+    @abstractmethod
+    def check(self, deployment_id: str, **kwargs) -> HealthCheckResult:
+        """
+        Execute the health check for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+            **kwargs: Check-specific parameters (e.g., endpoint URL, thresholds)
+
+        Returns:
+            HealthCheckResult with check status and details
+
+        Raises:
+            ValueError: If deployment_id not found
+        """
+
+    @abstractmethod
+    def get_check_type(self) -> str:
+        """
+        Get the type identifier for this health check.
+
+        Returns:
+            Check type string (e.g., "http", "process", "resource")
+        """
+
+
+class IHealthCheckManager(ABC):
+    """
+    Interface for coordinating health checks across deployments.
+
+    WHY: Health monitoring requires orchestrating multiple check types,
+    aggregating results, and maintaining historical data. This interface
+    provides a high-level API for comprehensive health monitoring.
+
+    DESIGN DECISION: Provides both synchronous (check_health) and asynchronous
+    (background monitoring) operations to support different use cases.
+
+    Background Monitoring:
+    - Runs health checks at regular intervals
+    - Maintains historical health data
+    - Triggers callbacks on status changes
+    - Thread-safe with proper locking
+    """
+
+    @abstractmethod
+    def check_health(self, deployment_id: str) -> DeploymentHealth:
+        """
+        Execute all health checks for a deployment.
+
+        WHY: Provides a comprehensive health snapshot by running all
+        registered health checks and aggregating results.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            DeploymentHealth with aggregated status and check results
+
+        Raises:
+            ValueError: If deployment_id not found
+        """
+
+    @abstractmethod
+    def start_monitoring(self) -> None:
+        """
+        Start background health monitoring.
+
+        WHY: Enables continuous health tracking without manual polling.
+        Monitoring runs in a separate daemon thread.
+
+        Thread Safety: Creates a daemon thread that performs periodic checks.
+        """
+
+    @abstractmethod
+    def stop_monitoring(self) -> None:
+        """
+        Stop background health monitoring.
+
+        WHY: Gracefully stops the monitoring thread and releases resources.
+        """
+
+    @abstractmethod
+    def is_monitoring(self) -> bool:
+        """
+        Check if background monitoring is active.
+
+        Returns:
+            True if monitoring thread is running
+        """
+
+    @abstractmethod
+    def get_health_history(
+        self, deployment_id: str, limit: int = 10
+    ) -> List[DeploymentHealth]:
+        """
+        Get historical health check results for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+            limit: Maximum number of historical entries to return
+
+        Returns:
+            List of DeploymentHealth objects, newest first
+        """
+
+    @abstractmethod
+    def register_status_callback(self, callback) -> None:
+        """
+        Register a callback for health status changes.
+
+        WHY: Enables reactive behavior based on health status changes
+        (e.g., alerts, auto-recovery, logging).
+
+        Args:
+            callback: Function called with (deployment_id, old_status, new_status)
+        """
+
+
+__all__ = [
+    "IHealthCheck",
+    "IHealthCheckManager",
+]