claude-mpm 3.4.10__py3-none-any.whl → 5.4.55__py3-none-any.whl

claude_mpm/services/core/__init__.py

@@ -0,0 +1,108 @@
+"""
+Core Service Interfaces and Base Classes
+========================================
+
+This module provides the core service interfaces and base classes for the
+Claude MPM framework. All services should inherit from these base classes
+and implement the appropriate interfaces.
+
+Part of TSK-0046: Service Layer Architecture Reorganization
+"""
+
+from .base import BaseService, SingletonService, SyncBaseService
+from .interfaces import (  # Core dependency injection; Configuration management; Agent management; Health monitoring; Caching; Template management; Factory patterns; Event system; Logging; Service lifecycle; Error handling; Performance monitoring; Cache service; Agent deployment; Memory service; Hook service; SocketIO service; Project analyzer; Ticket manager; Interface registry
+    AgentDeploymentInterface,
+    AgentMetadata,
+    CacheEntry,
+    HealthStatus,
+    HookServiceInterface,
+    IAgentRecommender,
+    IAgentRegistry,
+    IAutoConfigManager,
+    ICacheService,
+    IConfigurationManager,
+    IConfigurationService,
+    IErrorHandler,
+    IEventBus,
+    IHealthMonitor,
+    InterfaceRegistry,
+    IPerformanceMonitor,
+    IPromptCache,
+    IServiceContainer,
+    IServiceFactory,
+    IServiceLifecycle,
+    IStructuredLogger,
+    ITemplateManager,
+    IToolchainAnalyzer,
+    MemoryServiceInterface,
+    ProjectAnalyzerInterface,
+    ServiceType,
+    SocketIOServiceInterface,
+    TemplateRenderContext,
+    TicketManagerInterface,
+)
+from .models import (  # Data models for services
+    AgentCapabilities,
+    AgentRecommendation,
+    ConfidenceLevel,
+    ConfigurationPreview,
+    ConfigurationResult,
+    DeploymentTarget,
+    Framework,
+    LanguageDetection,
+    ToolchainAnalysis,
+    ToolchainComponent,
+    ValidationResult,
+)
+
+__all__ = [  # noqa: RUF022 - Grouped by category with comments for clarity
+    # Service interfaces
+    "AgentDeploymentInterface",
+    "AgentMetadata",
+    # Base classes
+    "BaseService",
+    "CacheEntry",
+    "HealthStatus",
+    "HookServiceInterface",
+    "IAgentRecommender",
+    "IAgentRegistry",
+    "IAutoConfigManager",
+    "ICacheService",
+    "IConfigurationManager",
+    "IConfigurationService",
+    "IErrorHandler",
+    "IEventBus",
+    "IHealthMonitor",
+    "IPerformanceMonitor",
+    "IPromptCache",
+    # Core interfaces
+    "IServiceContainer",
+    "IServiceFactory",
+    "IServiceLifecycle",
+    "IStructuredLogger",
+    "ITemplateManager",
+    "IToolchainAnalyzer",
+    # Registry
+    "InterfaceRegistry",
+    "MemoryServiceInterface",
+    "ProjectAnalyzerInterface",
+    "ServiceType",
+    "SingletonService",
+    "SocketIOServiceInterface",
+    "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/base.py

@@ -0,0 +1,269 @@
+"""
+Base Service Classes for Claude MPM Framework
+============================================
+
+This module provides the base service classes that all services should inherit from.
+These base classes provide common functionality like logging, configuration access,
+and lifecycle management.
+
+Part of TSK-0046: Service Layer Architecture Reorganization
+"""
+
+import threading
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional
+
+from claude_mpm.core.logger import get_logger
+
+
+class BaseService(ABC):
+    """
+    Base class for all services in the Claude MPM framework.
+
+    Provides:
+    - Logging setup
+    - Configuration access
+    - Lifecycle management
+    - Common error handling patterns
+    """
+
+    def __init__(
+        self,
+        service_name: Optional[str] = None,
+        config: Optional[Dict[str, Any]] = None,
+    ):
+        """
+        Initialize base service.
+
+        Args:
+            service_name: Name of the service for logging
+            config: Service-specific configuration
+        """
+        self.service_name = service_name or self.__class__.__name__
+        self.logger = get_logger(self.service_name)
+        self._config = config or {}
+        self._initialized = False
+        self._shutdown = False
+
+    @abstractmethod
+    async def initialize(self) -> bool:
+        """
+        Initialize the service.
+
+        This method should be called before the service is used.
+        Implementations should set up any required resources.
+
+        Returns:
+            True if initialization successful, False otherwise
+        """
+
+    @abstractmethod
+    async def shutdown(self) -> None:
+        """
+        Shutdown the service gracefully.
+
+        This method should clean up any resources held by the service.
+        """
+
+    def get_config(self, key: str, default: Any = None) -> Any:
+        """
+        Get configuration value.
+
+        Args:
+            key: Configuration key
+            default: Default value if key not found
+
+        Returns:
+            Configuration value or default
+        """
+        return self._config.get(key, default)
+
+    def set_config(self, key: str, value: Any) -> None:
+        """
+        Set configuration value.
+
+        Args:
+            key: Configuration key
+            value: Configuration value
+        """
+        self._config[key] = value
+
+    @property
+    def is_initialized(self) -> bool:
+        """Check if service is initialized."""
+        return self._initialized
+
+    @property
+    def is_shutdown(self) -> bool:
+        """Check if service is shutdown."""
+        return self._shutdown
+
+    def log_debug(self, message: str, **kwargs) -> None:
+        """Log debug message."""
+        self.logger.debug(f"[{self.service_name}] {message}", **kwargs)
+
+    def log_info(self, message: str, **kwargs) -> None:
+        """Log info message."""
+        self.logger.info(f"[{self.service_name}] {message}", **kwargs)
+
+    def log_warning(self, message: str, **kwargs) -> None:
+        """Log warning message."""
+        self.logger.warning(f"[{self.service_name}] {message}", **kwargs)
+
+    def log_error(self, message: str, **kwargs) -> None:
+        """Log error message."""
+        self.logger.error(f"[{self.service_name}] {message}", **kwargs)
+
+    def log_critical(self, message: str, **kwargs) -> None:
+        """Log critical message."""
+        self.logger.critical(f"[{self.service_name}] {message}", **kwargs)
+
+
+class SyncBaseService(ABC):
+    """
+    Base class for synchronous services in the Claude MPM framework.
+
+    Similar to BaseService but for services that don't require async operations.
+    """
+
+    def __init__(
+        self,
+        service_name: Optional[str] = None,
+        config: Optional[Dict[str, Any]] = None,
+    ):
+        """
+        Initialize base service.
+
+        Args:
+            service_name: Name of the service for logging
+            config: Service-specific configuration
+        """
+        self.service_name = service_name or self.__class__.__name__
+        self.logger = get_logger(self.service_name)
+        self._config = config or {}
+        self._initialized = False
+        self._shutdown = False
+
+    @abstractmethod
+    def initialize(self) -> bool:
+        """
+        Initialize the service.
+
+        This method should be called before the service is used.
+        Implementations should set up any required resources.
+
+        Returns:
+            True if initialization successful, False otherwise
+        """
+
+    @abstractmethod
+    def shutdown(self) -> None:
+        """
+        Shutdown the service gracefully.
+
+        This method should clean up any resources held by the service.
+        """
+
+    def get_config(self, key: str, default: Any = None) -> Any:
+        """
+        Get configuration value.
+
+        Args:
+            key: Configuration key
+            default: Default value if key not found
+
+        Returns:
+            Configuration value or default
+        """
+        return self._config.get(key, default)
+
+    def set_config(self, key: str, value: Any) -> None:
+        """
+        Set configuration value.
+
+        Args:
+            key: Configuration key
+            value: Configuration value
+        """
+        self._config[key] = value
+
+    @property
+    def is_initialized(self) -> bool:
+        """Check if service is initialized."""
+        return self._initialized
+
+    @property
+    def is_shutdown(self) -> bool:
+        """Check if service is shutdown."""
+        return self._shutdown
+
+    def log_debug(self, message: str, **kwargs) -> None:
+        """Log debug message."""
+        self.logger.debug(f"[{self.service_name}] {message}", **kwargs)
+
+    def log_info(self, message: str, **kwargs) -> None:
+        """Log info message."""
+        self.logger.info(f"[{self.service_name}] {message}", **kwargs)
+
+    def log_warning(self, message: str, **kwargs) -> None:
+        """Log warning message."""
+        self.logger.warning(f"[{self.service_name}] {message}", **kwargs)
+
+    def log_error(self, message: str, **kwargs) -> None:
+        """Log error message."""
+        self.logger.error(f"[{self.service_name}] {message}", **kwargs)
+
+    def log_critical(self, message: str, **kwargs) -> None:
+        """Log critical message."""
+        self.logger.critical(f"[{self.service_name}] {message}", **kwargs)
+
+
+class SingletonService(SyncBaseService):
+    """
+    Base class for singleton services.
+
+    Ensures only one instance of the service exists with thread-safe initialization.
+    Uses double-checked locking pattern to prevent race conditions.
+    Uses RLock (reentrant lock) to support recursive instantiation patterns.
+    """
+
+    _instances: Dict[type, "SingletonService"] = {}
+    _lock = threading.RLock()
+
+    def __new__(cls, *args, **kwargs):
+        """Ensure only one instance exists with thread-safe initialization."""
+        # Fast path - check without lock
+        if cls not in cls._instances:
+            # Slow path - acquire lock and double-check
+            with cls._lock:
+                if cls not in cls._instances:
+                    cls._instances[cls] = super().__new__(cls)
+        return cls._instances[cls]
+
+    @classmethod
+    def get_instance(cls) -> "SingletonService":
+        """Get the singleton instance with thread-safe initialization."""
+        # Fast path - check without lock
+        if cls not in cls._instances:
+            # Slow path - acquire lock and double-check
+            with cls._lock:
+                if cls not in cls._instances:
+                    # Use object.__new__ to bypass __new__ recursion
+                    instance = object.__new__(cls)
+                    cls._instances[cls] = instance
+                    # Call __init__ explicitly after storing instance
+                    instance.__init__()
+        return cls._instances[cls]
+
+    @classmethod
+    def clear_instance(cls) -> None:
+        """Clear the singleton instance (useful for testing).
+
+        Thread-safe implementation ensures proper cleanup.
+        """
+        with cls._lock:
+            if cls in cls._instances:
+                instance = cls._instances[cls]
+                if hasattr(instance, "shutdown") and not instance.is_shutdown:
+                    instance.shutdown()
+                del cls._instances[cls]

claude_mpm/services/core/cache_manager.py

@@ -0,0 +1,309 @@
+"""
+Cache Manager Service for Framework Loader
+==========================================
+
+WHY: This service extracts and centralizes cache management logic from the FrameworkLoader,
+providing a clean interface for managing multiple cache types with different TTLs.
+
+DESIGN DECISION: Built on top of the existing FileSystemCache infrastructure while
+providing a specialized interface for framework-specific caching needs.
+
+EXTRACTED FROM: core/framework_loader.py (lines 89-140)
+- Reduces FrameworkLoader complexity by ~50 lines
+- Provides thread-safe, type-specific cache management
+
+NOTE: The ICacheManager interface has been moved to service_interfaces.py for
+better organization and to support dependency injection.
+"""
+
+import threading
+import time
+from typing import Any, Dict, Optional, Set, Tuple
+
+from claude_mpm.core.cache import FileSystemCache
+from claude_mpm.core.logger import get_logger
+
+# Import interface from consolidated location
+from .service_interfaces import ICacheManager
+
+
+class CacheManager(ICacheManager):
+    """
+    Centralized cache management service for framework loader.
+
+    This service manages multiple cache types with different TTLs:
+    - Agent capabilities (60s TTL)
+    - Deployed agents (30s TTL)
+    - Agent metadata (60s TTL)
+    - Memories (60s TTL)
+
+    Thread-safe implementation using locks for concurrent access.
+    """
+
+    # Default TTL values (in seconds)
+    DEFAULT_CAPABILITIES_TTL = 60
+    DEFAULT_DEPLOYED_AGENTS_TTL = 30
+    DEFAULT_METADATA_TTL = 60
+    DEFAULT_MEMORIES_TTL = 60
+
+    def __init__(
+        self,
+        capabilities_ttl: float = DEFAULT_CAPABILITIES_TTL,
+        deployed_agents_ttl: float = DEFAULT_DEPLOYED_AGENTS_TTL,
+        metadata_ttl: float = DEFAULT_METADATA_TTL,
+        memories_ttl: float = DEFAULT_MEMORIES_TTL,
+    ):
+        """
+        Initialize cache manager with configurable TTLs.
+
+        Args:
+            capabilities_ttl: TTL for agent capabilities cache
+            deployed_agents_ttl: TTL for deployed agents cache
+            metadata_ttl: TTL for agent metadata cache
+            memories_ttl: TTL for memories cache
+        """
+        self.logger = get_logger("cache_manager")
+
+        # TTL configuration
+        self.capabilities_ttl = capabilities_ttl
+        self.deployed_agents_ttl = deployed_agents_ttl
+        self.metadata_ttl = metadata_ttl
+        self.memories_ttl = memories_ttl
+
+        # Cache storage with timestamps
+        self._capabilities_cache: Optional[str] = None
+        self._capabilities_cache_time: float = 0
+
+        self._deployed_agents_cache: Optional[Set[str]] = None
+        self._deployed_agents_cache_time: float = 0
+
+        self._agent_metadata_cache: Dict[
+            str, Tuple[Optional[Dict[str, Any]], float]
+        ] = {}
+
+        self._memories_cache: Optional[Dict[str, Any]] = None
+        self._memories_cache_time: float = 0
+
+        # Thread safety
+        self._lock = threading.RLock()
+
+        # Underlying file system cache (optional, for persistence)
+        self._fs_cache = FileSystemCache(
+            max_size_mb=50,  # 50MB for framework caches
+            default_ttl=max(
+                capabilities_ttl, deployed_agents_ttl, metadata_ttl, memories_ttl
+            ),
+        )
+
+        self.logger.debug(
+            f"Cache manager initialized with TTLs: "
+            f"capabilities={capabilities_ttl}s, "
+            f"deployed_agents={deployed_agents_ttl}s, "
+            f"metadata={metadata_ttl}s, "
+            f"memories={memories_ttl}s"
+        )
+
+    def is_cache_valid(self, cache_time: float, ttl: float) -> bool:
+        """Check if a cache entry is still valid based on its timestamp and TTL."""
+        current_time = time.time()
+        age = current_time - cache_time
+        return age < ttl
+
+    # Agent capabilities cache
+    def get_capabilities(self) -> Optional[str]:
+        """Get cached agent capabilities."""
+        with self._lock:
+            if self._capabilities_cache is not None and self.is_cache_valid(
+                self._capabilities_cache_time, self.capabilities_ttl
+            ):
+                age = time.time() - self._capabilities_cache_time
+                self.logger.debug(f"Cache hit: agent capabilities (age: {age:.1f}s)")
+                return self._capabilities_cache
+
+            self.logger.debug("Cache miss: agent capabilities")
+            return None
+
+    def set_capabilities(self, value: str) -> None:
+        """Set agent capabilities cache."""
+        with self._lock:
+            self._capabilities_cache = value
+            self._capabilities_cache_time = time.time()
+            self.logger.debug("Updated agent capabilities cache")
+
+    # Deployed agents cache
+    def get_deployed_agents(self) -> Optional[Set[str]]:
+        """Get cached deployed agents set."""
+        with self._lock:
+            if self._deployed_agents_cache is not None and self.is_cache_valid(
+                self._deployed_agents_cache_time, self.deployed_agents_ttl
+            ):
+                age = time.time() - self._deployed_agents_cache_time
+                self.logger.debug(f"Cache hit: deployed agents (age: {age:.1f}s)")
+                return (
+                    self._deployed_agents_cache.copy()
+                )  # Return a copy to prevent external modification
+
+            self.logger.debug("Cache miss: deployed agents")
+            return None
+
+    def set_deployed_agents(self, agents: Set[str]) -> None:
+        """Set deployed agents cache."""
+        with self._lock:
+            self._deployed_agents_cache = agents.copy()  # Store a copy
+            self._deployed_agents_cache_time = time.time()
+            self.logger.debug(
+                f"Updated deployed agents cache with {len(agents)} agents"
+            )
+
+    # Agent metadata cache
+    def get_agent_metadata(
+        self, agent_file: str
+    ) -> Optional[Tuple[Optional[Dict[str, Any]], float]]:
+        """Get cached agent metadata for a specific file."""
+        with self._lock:
+            if agent_file in self._agent_metadata_cache:
+                cached_data, cached_mtime = self._agent_metadata_cache[agent_file]
+                # Check if cache is still valid
+                if self.is_cache_valid(cached_mtime, self.metadata_ttl):
+                    self.logger.debug(f"Cache hit: metadata for {agent_file}")
+                    return cached_data, cached_mtime
+
+            self.logger.debug(f"Cache miss: metadata for {agent_file}")
+            return None
+
+    def set_agent_metadata(
+        self, agent_file: str, metadata: Optional[Dict[str, Any]], mtime: float
+    ) -> None:
+        """Set agent metadata cache for a specific file."""
+        with self._lock:
+            self._agent_metadata_cache[agent_file] = (metadata, mtime)
+            self.logger.debug(f"Updated metadata cache for {agent_file}")
+
+    # Memories cache
+    def get_memories(self) -> Optional[Dict[str, Any]]:
+        """Get cached memories."""
+        with self._lock:
+            if self._memories_cache is not None and self.is_cache_valid(
+                self._memories_cache_time, self.memories_ttl
+            ):
+                age = time.time() - self._memories_cache_time
+                self.logger.debug(f"Cache hit: memories (age: {age:.1f}s)")
+                return self._memories_cache.copy()  # Return a copy
+
+            self.logger.debug("Cache miss: memories")
+            return None
+
+    def set_memories(self, memories: Dict[str, Any]) -> None:
+        """Set memories cache."""
+        with self._lock:
+            self._memories_cache = memories.copy()  # Store a copy
+            self._memories_cache_time = time.time()
+            self.logger.debug("Updated memories cache")
+
+    # Cache clearing methods
+    def clear_all(self) -> None:
+        """Clear all caches."""
+        with self._lock:
+            self.logger.info("Clearing all caches")
+
+            # Clear capabilities
+            self._capabilities_cache = None
+            self._capabilities_cache_time = 0
+
+            # Clear deployed agents
+            self._deployed_agents_cache = None
+            self._deployed_agents_cache_time = 0
+
+            # Clear metadata
+            self._agent_metadata_cache.clear()
+
+            # Clear memories
+            self._memories_cache = None
+            self._memories_cache_time = 0
+
+            # Clear underlying file system cache
+            self._fs_cache.clear()
+
+    def clear_agent_caches(self) -> None:
+        """Clear agent-related caches only."""
+        with self._lock:
+            self.logger.info("Clearing agent-related caches")
+
+            # Clear capabilities
+            self._capabilities_cache = None
+            self._capabilities_cache_time = 0
+
+            # Clear deployed agents
+            self._deployed_agents_cache = None
+            self._deployed_agents_cache_time = 0
+
+            # Clear metadata
+            self._agent_metadata_cache.clear()
+
+    def clear_memory_caches(self) -> None:
+        """Clear memory-related caches only."""
+        with self._lock:
+            self.logger.info("Clearing memory caches")
+
+            self._memories_cache = None
+            self._memories_cache_time = 0
+
+    def get_stats(self) -> Dict[str, Any]:
+        """Get cache statistics."""
+        with self._lock:
+            current_time = time.time()
+
+            return {
+                "capabilities": {
+                    "cached": self._capabilities_cache is not None,
+                    "age": (
+                        current_time - self._capabilities_cache_time
+                        if self._capabilities_cache
+                        else None
+                    ),
+                    "valid": (
+                        self.is_cache_valid(
+                            self._capabilities_cache_time, self.capabilities_ttl
+                        )
+                        if self._capabilities_cache
+                        else False
+                    ),
+                },
+                "deployed_agents": {
+                    "cached": self._deployed_agents_cache is not None,
+                    "count": (
+                        len(self._deployed_agents_cache)
+                        if self._deployed_agents_cache
+                        else 0
+                    ),
+                    "age": (
+                        current_time - self._deployed_agents_cache_time
+                        if self._deployed_agents_cache
+                        else None
+                    ),
+                    "valid": (
+                        self.is_cache_valid(
+                            self._deployed_agents_cache_time, self.deployed_agents_ttl
+                        )
+                        if self._deployed_agents_cache
+                        else False
+                    ),
+                },
+                "metadata": {"entries": len(self._agent_metadata_cache)},
+                "memories": {
+                    "cached": self._memories_cache is not None,
+                    "age": (
+                        current_time - self._memories_cache_time
+                        if self._memories_cache
+                        else None
+                    ),
+                    "valid": (
+                        self.is_cache_valid(
+                            self._memories_cache_time, self.memories_ttl
+                        )
+                        if self._memories_cache
+                        else False
+                    ),
+                },
+                "fs_cache": self._fs_cache.get_stats() if self._fs_cache else {},
+            }