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

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,169 @@
+"""
+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",
+]

claude_mpm/services/core/interfaces/model.py

@@ -0,0 +1,281 @@
+"""
+Model Provider Interfaces for Claude MPM Framework
+==================================================
+
+WHY: This module defines the interfaces for content processing model providers,
+enabling support for both local (Ollama) and cloud (Claude) models with
+intelligent routing and auto-fallback capabilities.
+
+DESIGN DECISION: Model providers implement a common interface (IModelProvider)
+to enable polymorphic use and easy switching between providers. The abstraction
+allows for provider-specific optimizations while maintaining a consistent API.
+
+ARCHITECTURE:
+- IModelProvider: Core provider interface for content analysis
+- ModelCapability: Enum of supported content processing tasks
+- ModelProvider: Enum of available provider types
+- ModelResponse: Standardized response format across providers
+
+USAGE:
+    provider = OllamaProvider()
+    if await provider.is_available():
+        response = await provider.analyze_content(
+            content="Your text here",
+            task=ModelCapability.SEO_ANALYSIS
+        )
+        if response.success:
+            print(f"Analysis from {response.model}: {response.result}")
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class ModelCapability(Enum):
+    """
+    Content processing capabilities supported by model providers.
+
+    WHY: Defines task-specific analysis types for content processing.
+    Each capability may route to different models optimized for that task.
+    """
+
+    SEO_ANALYSIS = "seo_analysis"
+    READABILITY = "readability"
+    GRAMMAR = "grammar"
+    SUMMARIZATION = "summarization"
+    KEYWORD_EXTRACTION = "keyword_extraction"
+    ACCESSIBILITY = "accessibility"
+    SENTIMENT = "sentiment"
+    GENERAL = "general"
+
+
+class ModelProvider(Enum):
+    """
+    Available model provider backends.
+
+    WHY: Enables configuration-based routing between providers.
+
+    Values:
+        CLAUDE: Cloud-based Claude API (always available)
+        OLLAMA: Local Ollama installation (requires local setup)
+        AUTO: Intelligent routing with Ollama-first, Claude fallback
+    """
+
+    CLAUDE = "claude"
+    OLLAMA = "ollama"
+    AUTO = "auto"
+
+
+@dataclass
+class ModelResponse:
+    """
+    Standardized response from model providers.
+
+    WHY: Provides consistent response format across all providers,
+    enabling transparent provider switching and unified error handling.
+
+    Attributes:
+        success: Whether the operation succeeded
+        provider: Name of provider that handled request (e.g., "ollama", "claude")
+        model: Specific model used (e.g., "llama3.3:70b", "claude-3-5-sonnet")
+        task: Task that was performed
+        result: Analysis result text
+        metadata: Provider-specific metadata (tokens, timing, etc.)
+        error: Error message if success=False
+    """
+
+    success: bool
+    provider: str
+    model: str
+    task: str
+    result: str
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    error: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert response to dictionary for serialization."""
+        return {
+            "success": self.success,
+            "provider": self.provider,
+            "model": self.model,
+            "task": self.task,
+            "result": self.result,
+            "metadata": self.metadata,
+            "error": self.error,
+        }
+
+
+class IModelProvider(ABC):
+    """
+    Interface for content processing model providers.
+
+    WHY: Defines contract for all model providers (Claude, Ollama, future providers).
+    Enables polymorphic use and easy provider switching without changing client code.
+
+    DESIGN PATTERN: Strategy pattern - allows runtime selection of model provider
+    based on availability, configuration, and task requirements.
+
+    Implementations should:
+    - Handle provider-specific connection management
+    - Map capabilities to optimal models
+    - Provide robust error handling
+    - Return standardized ModelResponse objects
+    """
+
+    @abstractmethod
+    async def is_available(self) -> bool:
+        """
+        Check if provider is available and functional.
+
+        WHY: Enables auto-fallback routing. Local providers may not always be
+        available (Ollama not running), while cloud providers need API keys.
+
+        Returns:
+            True if provider is ready to handle requests
+        """
+
+    @abstractmethod
+    async def analyze_content(
+        self,
+        content: str,
+        task: ModelCapability,
+        model: Optional[str] = None,
+        **kwargs,
+    ) -> ModelResponse:
+        """
+        Analyze content with specified task.
+
+        WHY: Core content processing method. Handles all analysis types
+        with task-specific prompting and model selection.
+
+        Args:
+            content: Text content to analyze
+            task: Type of analysis to perform
+            model: Optional specific model to use (overrides default)
+            **kwargs: Provider-specific options (temperature, max_tokens, etc.)
+
+        Returns:
+            ModelResponse with analysis results or error
+
+        Example:
+            response = await provider.analyze_content(
+                content="Your article text",
+                task=ModelCapability.SEO_ANALYSIS,
+                temperature=0.7
+            )
+        """
+
+    @abstractmethod
+    def get_supported_capabilities(self) -> List[ModelCapability]:
+        """
+        Return list of capabilities this provider supports.
+
+        WHY: Enables capability-based routing. Some providers may not
+        support all task types.
+
+        Returns:
+            List of supported ModelCapability values
+        """
+
+    @abstractmethod
+    async def get_available_models(self) -> List[str]:
+        """
+        List models available from this provider.
+
+        WHY: Enables model validation and user selection. Local providers
+        may have different models installed than expected.
+
+        Returns:
+            List of model names/identifiers
+
+        Example:
+            models = await provider.get_available_models()
+            # ["llama3.3:70b", "gemma2:9b", "mistral:7b"]
+        """
+
+    @abstractmethod
+    async def get_model_info(self, model: str) -> Dict[str, Any]:
+        """
+        Get detailed information about a specific model.
+
+        WHY: Provides model metadata for UI display and capability checking.
+
+        Args:
+            model: Model name/identifier
+
+        Returns:
+            Dictionary with model details (size, parameters, capabilities, etc.)
+        """
+
+    @abstractmethod
+    async def shutdown(self) -> None:
+        """
+        Shutdown provider and cleanup resources.
+
+        WHY: Proper resource cleanup for connection pools, HTTP sessions, etc.
+        """
+
+
+class IModelRouter(ABC):
+    """
+    Interface for intelligent model routing with fallback.
+
+    WHY: Manages provider selection and fallback logic. Routes requests
+    to optimal provider based on availability and configuration.
+
+    DESIGN PATTERN: Chain of Responsibility - tries providers in order
+    until one succeeds or all fail.
+    """
+
+    @abstractmethod
+    async def analyze_content(
+        self,
+        content: str,
+        task: ModelCapability,
+        model: Optional[str] = None,
+        **kwargs,
+    ) -> ModelResponse:
+        """
+        Route content analysis to optimal provider.
+
+        WHY: Single entry point for all content analysis. Handles provider
+        selection, fallback, and error recovery transparently.
+
+        Args:
+            content: Text content to analyze
+            task: Type of analysis to perform
+            model: Optional specific model to use
+            **kwargs: Provider-specific options
+
+        Returns:
+            ModelResponse from successful provider
+        """
+
+    @abstractmethod
+    def get_active_provider(self) -> Optional[str]:
+        """
+        Get name of currently active provider.
+
+        Returns:
+            Provider name or None if no provider active
+        """
+
+    @abstractmethod
+    async def get_provider_status(self) -> Dict[str, Dict[str, Any]]:
+        """
+        Get status of all configured providers.
+
+        Returns:
+            Dictionary mapping provider names to status info
+        """
+
+
+__all__ = [
+    "IModelProvider",
+    "IModelRouter",
+    "ModelCapability",
+    "ModelProvider",
+    "ModelResponse",
+]