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

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

claude_mpm/services/core/interfaces/process.py

@@ -0,0 +1,372 @@
+"""
+Process Management Interfaces for Claude MPM Framework
+=======================================================
+
+WHY: This module defines interfaces for local process management operations,
+enabling the local-ops-agent to spawn, track, and manage background processes
+with proper isolation, state persistence, and port conflict prevention.
+
+DESIGN DECISION: Process management interfaces are separated from other service
+interfaces to maintain clear boundaries between deployment operations and other
+system services.
+
+ARCHITECTURE:
+- ILocalProcessManager: Core interface for process lifecycle management
+- IDeploymentStateManager: Interface for persistent state tracking
+- Process data models defined in models/process.py
+
+USAGE:
+    state_manager = DeploymentStateManager(state_file_path)
+    process_manager = LocalProcessManager(state_manager)
+
+    config = StartConfig(
+        command=["npm", "run", "dev"],
+        working_directory="/path/to/project",
+        port=3000
+    )
+
+    deployment = await process_manager.start(config)
+    print(f"Started process {deployment.process_id} on port {deployment.port}")
+"""
+
+from abc import ABC, abstractmethod
+from typing import Dict, List, Optional
+
+from claude_mpm.core.enums import ServiceState
+from claude_mpm.services.core.models.process import (
+    DeploymentState,
+    ProcessInfo,
+    StartConfig,
+)
+
+
+class IDeploymentStateManager(ABC):
+    """
+    Interface for deployment state persistence and management.
+
+    WHY: State persistence is critical for tracking processes across restarts
+    and preventing orphaned processes. This interface abstracts the storage
+    mechanism to enable different backends (JSON file, database, etc.).
+
+    DESIGN DECISION: Provides both low-level (save/load) and high-level (query)
+    operations to support different use cases. Uses file locking to prevent
+    corruption from concurrent access.
+
+    Thread Safety: All operations must be thread-safe with proper locking.
+    """
+
+    @abstractmethod
+    def load_state(self) -> Dict[str, DeploymentState]:
+        """
+        Load all deployment states from persistent storage.
+
+        Returns:
+            Dictionary mapping deployment_id to DeploymentState
+
+        Raises:
+            StateCorruptionError: If state file is corrupted
+            IOError: If state file cannot be read
+        """
+
+    @abstractmethod
+    def save_state(self, states: Dict[str, DeploymentState]) -> None:
+        """
+        Save all deployment states to persistent storage.
+
+        Args:
+            states: Dictionary mapping deployment_id to DeploymentState
+
+        Raises:
+            IOError: If state file cannot be written
+        """
+
+    @abstractmethod
+    def get_deployment(self, deployment_id: str) -> Optional[DeploymentState]:
+        """
+        Get a specific deployment by ID.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            DeploymentState if found, None otherwise
+        """
+
+    @abstractmethod
+    def get_all_deployments(self) -> List[DeploymentState]:
+        """
+        Get all tracked deployments.
+
+        Returns:
+            List of all DeploymentState objects
+        """
+
+    @abstractmethod
+    def get_deployments_by_status(self, status: ServiceState) -> List[DeploymentState]:
+        """
+        Get all deployments with a specific status.
+
+        Args:
+            status: ServiceState to filter by
+
+        Returns:
+            List of matching DeploymentState objects
+        """
+
+    @abstractmethod
+    def get_deployment_by_port(self, port: int) -> Optional[DeploymentState]:
+        """
+        Get deployment using a specific port.
+
+        Args:
+            port: Port number to search for
+
+        Returns:
+            DeploymentState if found, None otherwise
+        """
+
+    @abstractmethod
+    def get_deployments_by_project(
+        self, working_directory: str
+    ) -> List[DeploymentState]:
+        """
+        Get all deployments for a specific project directory.
+
+        Args:
+            working_directory: Project directory path
+
+        Returns:
+            List of matching DeploymentState objects
+        """
+
+    @abstractmethod
+    def add_deployment(self, deployment: DeploymentState) -> None:
+        """
+        Add or update a deployment in state.
+
+        Args:
+            deployment: DeploymentState to add/update
+
+        Raises:
+            IOError: If state cannot be persisted
+        """
+
+    @abstractmethod
+    def remove_deployment(self, deployment_id: str) -> bool:
+        """
+        Remove a deployment from state.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            True if deployment was removed, False if not found
+
+        Raises:
+            IOError: If state cannot be persisted
+        """
+
+    @abstractmethod
+    def update_deployment_status(
+        self, deployment_id: str, status: ServiceState
+    ) -> bool:
+        """
+        Update the status of a deployment.
+
+        Args:
+            deployment_id: Unique deployment identifier
+            status: New ServiceState
+
+        Returns:
+            True if updated, False if deployment not found
+
+        Raises:
+            IOError: If state cannot be persisted
+        """
+
+    @abstractmethod
+    def cleanup_dead_pids(self) -> int:
+        """
+        Remove deployments with dead process IDs.
+
+        WHY: Processes may crash or be killed externally. This method cleans
+        up stale state entries for processes that no longer exist.
+
+        Returns:
+            Number of dead PIDs cleaned up
+
+        Raises:
+            IOError: If state cannot be persisted
+        """
+
+
+class ILocalProcessManager(ABC):
+    """
+    Interface for local process lifecycle management.
+
+    WHY: Process management involves complex operations like spawning, tracking,
+    and terminating background processes. This interface abstracts these operations
+    to enable different implementations and improve testability.
+
+    DESIGN DECISION: Provides high-level operations (start, stop, restart) that
+    handle all the complexity internally including port checking, process group
+    isolation, and state tracking.
+
+    Process Lifecycle:
+    1. Start: Spawn process with isolation and port checking
+    2. Monitor: Track status and update state
+    3. Stop: Graceful shutdown with fallback to force kill
+    4. Cleanup: Remove state and release resources
+    """
+
+    @abstractmethod
+    def start(self, config: StartConfig) -> DeploymentState:
+        """
+        Start a new background process.
+
+        WHY: Combines process spawning, port allocation, and state tracking in
+        a single operation to ensure consistency.
+
+        Args:
+            config: Configuration for the process to start
+
+        Returns:
+            DeploymentState with process information
+
+        Raises:
+            ProcessSpawnError: If process cannot be spawned
+            PortConflictError: If requested port is unavailable and no alternative found
+            ValueError: If configuration is invalid
+        """
+
+    @abstractmethod
+    def stop(self, deployment_id: str, timeout: int = 10, force: bool = False) -> bool:
+        """
+        Stop a running process.
+
+        WHY: Provides graceful shutdown with configurable timeout and force
+        option for stuck processes.
+
+        Args:
+            deployment_id: Unique deployment identifier
+            timeout: Seconds to wait for graceful shutdown
+            force: If True, kill immediately without waiting
+
+        Returns:
+            True if process stopped successfully
+
+        Raises:
+            ValueError: If deployment_id not found
+        """
+
+    @abstractmethod
+    def restart(self, deployment_id: str, timeout: int = 10) -> DeploymentState:
+        """
+        Restart a process (stop then start with same config).
+
+        Args:
+            deployment_id: Unique deployment identifier
+            timeout: Seconds to wait for graceful shutdown
+
+        Returns:
+            New DeploymentState after restart
+
+        Raises:
+            ValueError: If deployment_id not found
+            ProcessSpawnError: If restart fails
+        """
+
+    @abstractmethod
+    def get_status(self, deployment_id: str) -> Optional[ProcessInfo]:
+        """
+        Get current status and runtime information for a process.
+
+        Args:
+            deployment_id: Unique deployment identifier
+
+        Returns:
+            ProcessInfo with current status, or None if not found
+        """
+
+    @abstractmethod
+    def list_processes(
+        self, status_filter: Optional[ServiceState] = None
+    ) -> List[ProcessInfo]:
+        """
+        List all managed processes.
+
+        Args:
+            status_filter: Optional status to filter by
+
+        Returns:
+            List of ProcessInfo for all matching processes
+        """
+
+    @abstractmethod
+    def is_port_available(self, port: int) -> bool:
+        """
+        Check if a port is available for use.
+
+        WHY: Port conflict prevention is critical for reliable deployments.
+        This check happens before process spawn.
+
+        Args:
+            port: Port number to check
+
+        Returns:
+            True if port is available
+        """
+
+    @abstractmethod
+    def find_available_port(
+        self, preferred_port: int, max_attempts: int = 10
+    ) -> Optional[int]:
+        """
+        Find an available port starting from preferred_port.
+
+        WHY: Uses linear probing to find alternative ports when the preferred
+        port is unavailable. Respects protected port ranges.
+
+        Args:
+            preferred_port: Starting port number
+            max_attempts: Maximum number of ports to try
+
+        Returns:
+            Available port number, or None if none found
+        """
+
+    @abstractmethod
+    def cleanup_orphans(self) -> int:
+        """
+        Clean up orphaned process state entries.
+
+        WHY: Processes may crash or be killed externally, leaving stale state.
+        This method identifies and cleans up these orphans.
+
+        Returns:
+            Number of orphaned entries cleaned up
+        """
+
+    @abstractmethod
+    def generate_deployment_id(
+        self, project_name: str, port: Optional[int] = None
+    ) -> str:
+        """
+        Generate a unique deployment ID.
+
+        WHY: Provides consistent ID generation with optional port suffix for
+        projects with multiple deployments.
+
+        Args:
+            project_name: Name of the project
+            port: Optional port number to include in ID
+
+        Returns:
+            Unique deployment identifier
+        """
+
+
+__all__ = [
+    "IDeploymentStateManager",
+    "ILocalProcessManager",
+]