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

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/interfaces/restart.py

@@ -0,0 +1,307 @@
+"""
+Restart Management Interfaces for Claude MPM Framework
+========================================================
+
+WHY: This module defines interfaces for auto-restart functionality with crash
+detection, intelligent restart policies, and circuit breaker patterns.
+
+DESIGN DECISION: Restart interfaces are separated to enable modular restart
+management with different crash detection strategies and restart policies.
+
+ARCHITECTURE:
+- ICrashDetector: Interface for detecting process crashes and failures
+- IRestartPolicy: Interface for restart decision logic with backoff
+- IRestartManager: Interface for orchestrating the full restart workflow
+
+USAGE:
+    crash_detector = CrashDetector(health_manager)
+    restart_policy = RestartPolicy(config)
+    restart_manager = RestartManager(
+        process_manager=process_manager,
+        health_manager=health_manager,
+        config=config
+    )
+    restart_manager.enable_auto_restart(deployment_id)
+"""
+
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Callable, Optional
+
+if TYPE_CHECKING:
+    from claude_mpm.services.core.models.restart import RestartHistory
+
+
+class ICrashDetector(ABC):
+    """
+    Interface for detecting process crashes and failures.
+
+    WHY: Crash detection requires monitoring health status changes, process
+    exits, and zombie states. This interface abstracts different detection
+    strategies to enable flexible crash monitoring.
+
+    DESIGN DECISION: Integrates with IHealthCheckManager via callbacks to
+    receive real-time status updates. Tracks crash history per deployment
+    to enable pattern detection.
+
+    Thread Safety: Implementations must be thread-safe for concurrent monitoring.
+    """
+
+    @abstractmethod
+    def register_crash_callback(self, callback: Callable[[str, str], None]) -> None:
+        """
+        Register a callback to be invoked when a crash is detected.
+
+        Args:
+            callback: Function called with (deployment_id, reason)
+        """
+
+    @abstractmethod
+    def start_monitoring(self, deployment_id: str) -> None:
+        """
+        Start monitoring a deployment for crashes.
+
+        WHY: Enables targeted monitoring for specific deployments.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Raises:
+            ValueError: If deployment_id not found
+        """
+
+    @abstractmethod
+    def stop_monitoring(self, deployment_id: str) -> None:
+        """
+        Stop monitoring a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+        """
+
+    @abstractmethod
+    def is_monitoring(self, deployment_id: str) -> bool:
+        """
+        Check if a deployment is being monitored.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            True if deployment is being monitored
+        """
+
+    @abstractmethod
+    def get_crash_count(self, deployment_id: str) -> int:
+        """
+        Get the number of crashes detected for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            Number of crashes detected
+        """
+
+
+class IRestartPolicy(ABC):
+    """
+    Interface for restart decision logic with exponential backoff.
+
+    WHY: Restart policies prevent restart loops through exponential backoff,
+    max attempts, and circuit breaker patterns. This interface abstracts
+    the decision-making logic to enable different strategies.
+
+    DESIGN DECISION: Implements exponential backoff with configurable
+    parameters and circuit breaker state transitions (CLOSED → OPEN → HALF_OPEN).
+
+    Circuit Breaker States:
+    - CLOSED: Normal operation, restarts allowed
+    - OPEN: Circuit breaker tripped, restarts blocked
+    - HALF_OPEN: Testing if service recovered
+    """
+
+    @abstractmethod
+    def should_restart(self, deployment_id: str) -> bool:
+        """
+        Determine if a deployment should be restarted.
+
+        WHY: Central decision point that considers attempt count, circuit
+        breaker state, and backoff timing.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            True if restart should proceed
+        """
+
+    @abstractmethod
+    def calculate_backoff(self, deployment_id: str) -> float:
+        """
+        Calculate backoff time in seconds for next restart.
+
+        WHY: Implements exponential backoff to prevent restart storms.
+        Formula: min(initial * (multiplier ** (attempt - 1)), max_backoff)
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            Backoff time in seconds (0 if first attempt)
+        """
+
+    @abstractmethod
+    def record_restart_attempt(
+        self, deployment_id: str, success: bool, failure_reason: Optional[str] = None
+    ) -> None:
+        """
+        Record a restart attempt and update circuit breaker state.
+
+        Args:
+            deployment_id: Unique deployment identifier
+            success: Whether restart succeeded
+            failure_reason: Optional reason for failure
+        """
+
+    @abstractmethod
+    def reset_restart_history(self, deployment_id: str) -> None:
+        """
+        Reset restart history for a deployment.
+
+        WHY: Clears restart attempts after successful recovery or manual
+        intervention.
+
+        Args:
+            deployment_id: Unique deployment identifier
+        """
+
+    @abstractmethod
+    def get_circuit_breaker_state(self, deployment_id: str) -> str:
+        """
+        Get current circuit breaker state.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            Circuit breaker state (CLOSED, OPEN, HALF_OPEN)
+        """
+
+    @abstractmethod
+    def get_restart_attempt_count(self, deployment_id: str) -> int:
+        """
+        Get number of restart attempts for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            Number of restart attempts
+        """
+
+
+class IRestartManager(ABC):
+    """
+    Interface for orchestrating the complete restart workflow.
+
+    WHY: Restart management requires coordinating crash detection, policy
+    evaluation, process restart, and health verification. This interface
+    provides a high-level API for automatic and manual restarts.
+
+    DESIGN DECISION: Provides both automatic (background) and manual
+    (on-demand) restart operations. Integrates with all components:
+    CrashDetector, RestartPolicy, ProcessManager, and HealthCheckManager.
+
+    Restart Workflow:
+    1. Detect crash (via CrashDetector callback)
+    2. Check restart policy (max attempts, circuit breaker)
+    3. Wait for backoff period
+    4. Execute restart (preserve original StartConfig)
+    5. Verify health after restart
+    6. Record attempt and update circuit breaker
+    """
+
+    @abstractmethod
+    def enable_auto_restart(self, deployment_id: str) -> None:
+        """
+        Enable automatic restarts for a deployment.
+
+        WHY: Enables hands-free recovery from crashes. Starts monitoring
+        via CrashDetector and registers restart callbacks.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Raises:
+            ValueError: If deployment_id not found
+        """
+
+    @abstractmethod
+    def disable_auto_restart(self, deployment_id: str) -> None:
+        """
+        Disable automatic restarts for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+        """
+
+    @abstractmethod
+    def is_auto_restart_enabled(self, deployment_id: str) -> bool:
+        """
+        Check if auto-restart is enabled for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            True if auto-restart is enabled
+        """
+
+    @abstractmethod
+    def restart_deployment(self, deployment_id: str, manual: bool = False) -> bool:
+        """
+        Restart a deployment (manual or automatic trigger).
+
+        WHY: Provides unified restart operation that respects policy
+        constraints and performs health verification.
+
+        Args:
+            deployment_id: Unique deployment identifier
+            manual: If True, bypass some policy checks (e.g., circuit breaker)
+
+        Returns:
+            True if restart succeeded
+
+        Raises:
+            ValueError: If deployment_id not found
+        """
+
+    @abstractmethod
+    def get_restart_history(self, deployment_id: str) -> Optional["RestartHistory"]:
+        """
+        Get restart history for a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            RestartHistory if found, None otherwise
+        """
+
+    @abstractmethod
+    def clear_restart_history(self, deployment_id: str) -> None:
+        """
+        Clear restart history and reset circuit breaker.
+
+        WHY: Allows manual intervention to clear failed restart state.
+
+        Args:
+            deployment_id: Unique deployment identifier
+        """
+
+
+__all__ = [
+    "ICrashDetector",
+    "IRestartManager",
+    "IRestartPolicy",
+]

claude_mpm/services/core/interfaces/stability.py

@@ -0,0 +1,260 @@
+"""
+Stability Monitoring Interfaces for Claude MPM Framework
+==========================================================
+
+WHY: This module defines interfaces for proactive stability monitoring including
+memory leak detection, log monitoring, and resource exhaustion prevention.
+
+DESIGN DECISION: Separated from health checks to enable preventive monitoring
+that triggers actions BEFORE crashes occur. Provides early warning systems.
+
+ARCHITECTURE:
+- IMemoryLeakDetector: Interface for memory leak detection using trend analysis
+- ILogMonitor: Interface for real-time log file monitoring and pattern matching
+- IResourceMonitor: Interface for comprehensive resource usage tracking
+
+USAGE:
+    memory_detector = MemoryLeakDetector(leak_threshold_mb_per_minute=10.0)
+    log_monitor = LogMonitor(log_file="/var/log/app.log")
+    resource_monitor = ResourceMonitor(fd_threshold_percent=0.8)
+
+    # Integrate with health monitoring
+    health_manager.add_stability_monitors(
+        memory_detector=memory_detector,
+        log_monitor=log_monitor,
+        resource_monitor=resource_monitor,
+    )
+"""
+
+from abc import ABC, abstractmethod
+from typing import Callable, List
+
+from claude_mpm.services.core.models.stability import (
+    LogPatternMatch,
+    MemoryTrend,
+    ResourceUsage,
+)
+
+
+class IMemoryLeakDetector(ABC):
+    """
+    Interface for memory leak detection using trend analysis.
+
+    WHY: Memory leaks are a common cause of process crashes. Early detection
+    enables preemptive restarts BEFORE the OOM killer terminates the process.
+
+    DESIGN DECISION: Uses slope-based trend analysis over a rolling window
+    to detect sustained memory growth patterns, filtering out normal variations.
+
+    Algorithm:
+    1. Maintain rolling window of memory measurements (timestamp, memory_mb)
+    2. Calculate linear regression slope (MB per minute)
+    3. Detect leak if slope exceeds threshold (default: 10 MB/minute)
+    4. Trigger alert when leak detected and memory > 80% limit
+
+    Thread Safety: Implementations must be thread-safe for concurrent access.
+    """
+
+    @abstractmethod
+    def record_memory_usage(self, deployment_id: str, memory_mb: float) -> None:
+        """
+        Record a memory usage measurement.
+
+        WHY: Builds historical data for trend analysis. Should be called
+        periodically (e.g., every 30s) to collect sufficient data points.
+
+        Args:
+            deployment_id: Deployment identifier
+            memory_mb: Current memory usage in megabytes
+        """
+
+    @abstractmethod
+    def analyze_trend(self, deployment_id: str) -> MemoryTrend:
+        """
+        Analyze memory usage trend for leak detection.
+
+        WHY: Computes slope of memory usage over time to detect sustained
+        growth patterns characteristic of memory leaks.
+
+        Args:
+            deployment_id: Deployment identifier
+
+        Returns:
+            MemoryTrend with slope analysis and leak detection result
+
+        Algorithm:
+            slope_mb_per_minute = (recent_memory - old_memory) / time_delta_minutes
+            is_leaking = slope_mb_per_minute > threshold
+        """
+
+    @abstractmethod
+    def is_leaking(self, deployment_id: str) -> bool:
+        """
+        Check if deployment has a detected memory leak.
+
+        Returns:
+            True if leak detected (sustained memory growth)
+        """
+
+    @abstractmethod
+    def register_leak_callback(
+        self, callback: Callable[[str, MemoryTrend], None]
+    ) -> None:
+        """
+        Register callback for leak detection events.
+
+        Args:
+            callback: Function called with (deployment_id, trend) when leak detected
+        """
+
+
+class ILogMonitor(ABC):
+    """
+    Interface for real-time log file monitoring and pattern matching.
+
+    WHY: Application logs contain early warning signals (exceptions, OOM errors,
+    segfaults) that predict imminent crashes. Real-time monitoring enables
+    proactive intervention.
+
+    DESIGN DECISION: Uses watchdog library for efficient file system monitoring.
+    Avoids polling by receiving file modification events from the OS.
+
+    Pattern Matching:
+    - Regex-based patterns for flexibility
+    - Configurable patterns per deployment
+    - Built-in patterns for common errors:
+      * OutOfMemoryError
+      * Segmentation fault
+      * Exception: / Traceback
+      * Database connection errors
+      * Network timeouts
+
+    Thread Safety: Uses watchdog's thread-safe event handling.
+    """
+
+    @abstractmethod
+    def start_monitoring(self, log_file: str, deployment_id: str) -> None:
+        """
+        Start monitoring a log file for error patterns.
+
+        WHY: Begins watching the log file for new entries. Uses OS-level
+        file system events for efficiency.
+
+        Args:
+            log_file: Path to log file to monitor
+            deployment_id: Deployment identifier for callbacks
+        """
+
+    @abstractmethod
+    def stop_monitoring(self, deployment_id: str) -> None:
+        """
+        Stop monitoring a deployment's log file.
+
+        Args:
+            deployment_id: Deployment identifier
+        """
+
+    @abstractmethod
+    def add_pattern(self, pattern: str, severity: str = "ERROR") -> None:
+        """
+        Add an error pattern to monitor.
+
+        Args:
+            pattern: Regex pattern to match
+            severity: Error severity (ERROR, CRITICAL, WARNING)
+        """
+
+    @abstractmethod
+    def get_recent_matches(
+        self, deployment_id: str, limit: int = 10
+    ) -> List[LogPatternMatch]:
+        """
+        Get recent pattern matches for a deployment.
+
+        Args:
+            deployment_id: Deployment identifier
+            limit: Maximum number of matches to return
+
+        Returns:
+            List of LogPatternMatch objects, newest first
+        """
+
+    @abstractmethod
+    def register_match_callback(
+        self, callback: Callable[[str, LogPatternMatch], None]
+    ) -> None:
+        """
+        Register callback for pattern matches.
+
+        Args:
+            callback: Function called with (deployment_id, match) when pattern detected
+        """
+
+
+class IResourceMonitor(ABC):
+    """
+    Interface for comprehensive resource usage monitoring.
+
+    WHY: Resource exhaustion (file descriptors, threads, connections, disk space)
+    causes crashes and degradation. Monitoring enables preemptive action at 80%
+    thresholds before hitting hard limits.
+
+    DESIGN DECISION: Extends basic resource health checks with:
+    - Higher granularity (more frequent checks)
+    - Percentage-based thresholds (80% of ulimit)
+    - Trend analysis for growth rate
+    - Integration with restart manager for preemptive restarts
+
+    Resource Types:
+    1. File Descriptors: Critical for I/O operations (Unix: ulimit -n)
+    2. Threads: Memory and scheduling overhead
+    3. Network Connections: Socket exhaustion
+    4. Disk Space: Working directory availability
+
+    Thread Safety: Implementations must be thread-safe.
+    """
+
+    @abstractmethod
+    def check_resources(self, deployment_id: str) -> ResourceUsage:
+        """
+        Check resource usage for a deployment.
+
+        WHY: Provides comprehensive snapshot of resource consumption across
+        all monitored resource types.
+
+        Args:
+            deployment_id: Deployment identifier
+
+        Returns:
+            ResourceUsage with current metrics and critical status
+
+        Raises:
+            ValueError: If deployment not found
+        """
+
+    @abstractmethod
+    def is_critical(self, deployment_id: str) -> bool:
+        """
+        Check if any resource is at critical threshold (>80%).
+
+        Returns:
+            True if any resource exceeds 80% of limit
+        """
+
+    @abstractmethod
+    def register_critical_callback(
+        self, callback: Callable[[str, ResourceUsage], None]
+    ) -> None:
+        """
+        Register callback for critical resource usage.
+
+        Args:
+            callback: Function called with (deployment_id, usage) when critical
+        """
+
+
+__all__ = [
+    "ILogMonitor",
+    "IMemoryLeakDetector",
+    "IResourceMonitor",
+]