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

claude_mpm/core/__init__.py

@@ -1,20 +1,56 @@
-"""Core components for Claude MPM."""
-
-from .claude_runner import ClaudeRunner
-from .config import Config
-
-# Import DI components
-from .container import DIContainer, ServiceLifetime, get_container
-from .factories import (
-    AgentServiceFactory,
-    ConfigurationFactory,
-    ServiceFactory,
-    SessionManagerFactory,
-    get_factory_registry,
-)
-from .injectable_service import InjectableService
-from .mixins import LoggerMixin
-from .service_registry import ServiceRegistry, get_service_registry, initialize_services
+"""Core components for Claude MPM.
+
+Lazy imports for all components to avoid loading heavy dependencies
+when only importing lightweight utilities (constants, logging_utils, etc).
+"""
+
+
+# Lazy imports via __getattr__ to prevent loading heavy dependencies
+# when hooks only need lightweight utilities
+def __getattr__(name):
+    """Lazy load core components only when accessed using dictionary-based mapping."""
+    from importlib import import_module
+
+    # Dictionary mapping: name -> (module_path, attribute_name)
+    _LAZY_IMPORTS = {
+        # Core components
+        "ClaudeRunner": ("claude_mpm.core.claude_runner", "ClaudeRunner"),
+        "Config": ("claude_mpm.core.config", "Config"),
+        # Dependency injection
+        "DIContainer": ("claude_mpm.core.container", "DIContainer"),
+        "ServiceLifetime": ("claude_mpm.core.container", "ServiceLifetime"),
+        "get_container": ("claude_mpm.core.container", "get_container"),
+        # Factories
+        "AgentServiceFactory": ("claude_mpm.core.factories", "AgentServiceFactory"),
+        "ConfigurationFactory": ("claude_mpm.core.factories", "ConfigurationFactory"),
+        "ServiceFactory": ("claude_mpm.core.factories", "ServiceFactory"),
+        "SessionManagerFactory": ("claude_mpm.core.factories", "SessionManagerFactory"),
+        "get_factory_registry": ("claude_mpm.core.factories", "get_factory_registry"),
+        # Services and utilities
+        "InjectableService": (
+            "claude_mpm.core.injectable_service",
+            "InjectableService",
+        ),
+        "LoggerMixin": ("claude_mpm.core.mixins", "LoggerMixin"),
+        # Service registry
+        "ServiceRegistry": ("claude_mpm.core.service_registry", "ServiceRegistry"),
+        "get_service_registry": (
+            "claude_mpm.core.service_registry",
+            "get_service_registry",
+        ),
+        "initialize_services": (
+            "claude_mpm.core.service_registry",
+            "initialize_services",
+        ),
+    }
+
+    if name in _LAZY_IMPORTS:
+        module_path, attr_name = _LAZY_IMPORTS[name]
+        module = import_module(module_path)
+        return getattr(module, attr_name)
+
+    raise AttributeError(f"module '{__name__}' has no attribute '{name}'")
+
 
 __all__ = [
     "AgentServiceFactory",

claude_mpm/core/agent_name_normalizer.py

@@ -1,9 +1,10 @@
 """Agent name normalization utilities for consistent naming across the system."""
 
-import logging
 from typing import Optional
 
-logger = logging.getLogger(__name__)
+from claude_mpm.core.logging_utils import get_logger
+
+logger = get_logger(__name__)
 
 
 class AgentNameNormalizer:

claude_mpm/core/agent_registry.py

@@ -14,7 +14,7 @@ This module provides:
 import contextlib
 import warnings
 from dataclasses import dataclass
-from datetime import datetime
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Set
 
@@ -379,7 +379,7 @@ class AgentRegistryAdapter:
         }
 
         nickname = nicknames.get(agent_name, agent_name.title())
-        today = datetime.now().strftime("%Y-%m-%d")
+        today = datetime.now(timezone.utc).strftime("%Y-%m-%d")
 
         return f"""**{nickname}**: {task}
 

claude_mpm/core/agent_session_manager.py

@@ -3,7 +3,7 @@
 import json
 import uuid
 from collections import defaultdict
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Dict, Optional
 
@@ -53,10 +53,10 @@ class AgentSessionManager:
             if not self.session_locks.get(session_id, False):
                 # Check if session is still fresh (not too old)
                 created = datetime.fromisoformat(session_data["created_at"])
-                if datetime.now() - created < timedelta(hours=1):
+                if datetime.now(timezone.utc) - created < timedelta(hours=1):
                     # Use this session
                     self.session_locks[session_id] = True
-                    session_data["last_used"] = datetime.now().isoformat()
+                    session_data["last_used"] = datetime.now(timezone.utc).isoformat()
                     session_data["use_count"] += 1
                     logger.info(f"Reusing session {session_id} for {agent_type} agent")
                     return session_id
@@ -85,8 +85,8 @@ class AgentSessionManager:
         session_data = {
             "id": session_id,
             "agent_type": agent_type,
-            "created_at": datetime.now().isoformat(),
-            "last_used": datetime.now().isoformat(),
+            "created_at": datetime.now(timezone.utc).isoformat(),
+            "last_used": datetime.now(timezone.utc).isoformat(),
             "use_count": 0,
             "tasks_completed": [],
         }
@@ -122,7 +122,7 @@ class AgentSessionManager:
                 sessions[session_id]["tasks_completed"].append(
                     {
                         "task": task[:100],  # Truncate long tasks
-                        "timestamp": datetime.now().isoformat(),
+                        "timestamp": datetime.now(timezone.utc).isoformat(),
                         "success": success,
                     }
                 )
@@ -135,7 +135,7 @@ class AgentSessionManager:
         Args:
             max_age_hours: Maximum age in hours
         """
-        now = datetime.now()
+        now = datetime.now(timezone.utc)
         max_age = timedelta(hours=max_age_hours)
 
         for agent_type in list(self.agent_sessions.keys()):
@@ -207,9 +207,9 @@ class AgentSessionManager:
         try:
             data = {
                 "agent_sessions": dict(self.agent_sessions),
-                "updated_at": datetime.now().isoformat(),
+                "updated_at": datetime.now(timezone.utc).isoformat(),
             }
-            with open(session_file, "w") as f:
+            with session_file.open("w") as f:
                 json.dump(data, f, indent=2)
         except Exception as e:
             logger.error(f"Failed to save agent sessions: {e}")
@@ -219,7 +219,7 @@ class AgentSessionManager:
         session_file = self.session_dir / "agent_sessions.json"
         if session_file.exists():
             try:
-                with open(session_file) as f:
+                with session_file.open() as f:
                     data = json.load(f)
                     self.agent_sessions = defaultdict(
                         dict, data.get("agent_sessions", {})

claude_mpm/core/api_validator.py

@@ -0,0 +1,330 @@
+"""API Key Validation Module for Claude MPM.
+
+This module validates API keys for various services on startup to ensure
+proper configuration and prevent runtime failures. It follows the principle
+of failing fast with clear error messages rather than degrading gracefully.
+"""
+
+import os
+from typing import Dict, List, Optional, Tuple
+
+import requests
+
+from claude_mpm.core.logger import get_logger
+
+
+class APIKeyValidator:
+    """Validates API keys for various services on framework startup."""
+
+    def __init__(self, config: Optional[Dict] = None):
+        """Initialize the API validator.
+
+        Args:
+            config: Optional configuration dictionary
+        """
+        self.logger = get_logger("api_validator")
+        self.config = config or {}
+        self.errors: List[str] = []
+        self.warnings: List[str] = []
+
+    def validate_all_keys(
+        self, strict: bool = True
+    ) -> Tuple[bool, List[str], List[str]]:
+        """Validate all configured API keys.
+
+        Args:
+            strict: If True, validation failures raise exceptions.
+                   If False, failures are logged as warnings.
+
+        Returns:
+            Tuple of (success, errors, warnings)
+        """
+        self.errors = []
+        self.warnings = []
+
+        # Check if validation is enabled
+        if not self.config.get("validate_api_keys", True):
+            self.logger.info("API key validation disabled in config")
+            return True, [], []
+
+        # Validate OpenAI key if configured
+        openai_key = os.getenv("OPENAI_API_KEY")
+        if openai_key:
+            self._validate_openai_key(openai_key)
+
+        # Validate Anthropic key if configured
+        anthropic_key = os.getenv("ANTHROPIC_API_KEY")
+        if anthropic_key:
+            self._validate_anthropic_key(anthropic_key)
+
+        # Validate GitHub token if configured
+        github_token = os.getenv("GITHUB_TOKEN")
+        if github_token:
+            self._validate_github_token(github_token)
+
+        # Validate custom API keys from config
+        custom_apis = self.config.get("custom_api_validations", {})
+        for api_name, validation_config in custom_apis.items():
+            self._validate_custom_api(api_name, validation_config)
+
+        # Report results
+        if self.errors:
+            error_msg = "API Key Validation Failed:\n" + "\n".join(self.errors)
+            if strict:
+                self.logger.error(error_msg)
+                raise ValueError(error_msg)
+            self.logger.warning(error_msg)
+
+        if self.warnings:
+            for warning in self.warnings:
+                self.logger.warning(warning)
+
+        if not self.errors:
+            self.logger.info("✅ All configured API keys validated successfully")
+
+        return not bool(self.errors), self.errors, self.warnings
+
+    def _validate_openai_key(self, api_key: str) -> bool:
+        """Validate OpenAI API key.
+
+        Args:
+            api_key: The OpenAI API key to validate
+
+        Returns:
+            True if valid, False otherwise
+        """
+        try:
+            # Make a lightweight request to validate the key
+            response = requests.get(
+                "https://api.openai.com/v1/models",
+                headers={"Authorization": f"Bearer {api_key}"},
+                timeout=10,
+            )
+
+            if response.status_code == 401:
+                self.errors.append("❌ OpenAI API key is invalid (401 Unauthorized)")
+                return False
+            if response.status_code == 403:
+                self.errors.append(
+                    "❌ OpenAI API key lacks required permissions (403 Forbidden)"
+                )
+                return False
+            if response.status_code == 429:
+                # Rate limited but key is valid
+                self.warnings.append("⚠️ OpenAI API key is valid but rate limited")
+                return True
+            if response.status_code == 200:
+                self.logger.debug("✅ OpenAI API key validated successfully")
+                return True
+            self.warnings.append(
+                f"⚠️ OpenAI API returned unexpected status: {response.status_code}"
+            )
+            return True  # Assume valid for unexpected status codes
+
+        except requests.exceptions.Timeout:
+            self.warnings.append(
+                "⚠️ OpenAI API validation timed out - assuming key is valid"
+            )
+            return True
+        except requests.exceptions.ConnectionError as e:
+            self.warnings.append(f"⚠️ Could not connect to OpenAI API: {e}")
+            return True
+        except Exception as e:
+            self.errors.append(f"❌ OpenAI API validation failed with error: {e}")
+            return False
+
+    def _validate_anthropic_key(self, api_key: str) -> bool:
+        """Validate Anthropic API key.
+
+        Args:
+            api_key: The Anthropic API key to validate
+
+        Returns:
+            True if valid, False otherwise
+        """
+        try:
+            # Make a minimal request to validate the key
+            # Using a very small max_tokens to minimize cost
+            response = requests.post(
+                "https://api.anthropic.com/v1/messages",
+                headers={
+                    "x-api-key": api_key,
+                    "anthropic-version": "2023-06-01",
+                    "content-type": "application/json",
+                },
+                json={
+                    "model": "claude-3-haiku-20240307",  # Use cheapest model
+                    "messages": [{"role": "user", "content": "test"}],
+                    "max_tokens": 1,
+                },
+                timeout=10,
+            )
+
+            if response.status_code == 401:
+                self.errors.append("❌ Anthropic API key is invalid (401 Unauthorized)")
+                return False
+            if response.status_code == 403:
+                self.errors.append(
+                    "❌ Anthropic API key lacks required permissions (403 Forbidden)"
+                )
+                return False
+            if response.status_code == 400:
+                # Bad request but key is valid (we sent minimal request on purpose)
+                self.logger.debug("✅ Anthropic API key validated successfully")
+                return True
+            if response.status_code == 429:
+                # Rate limited but key is valid
+                self.warnings.append("⚠️ Anthropic API key is valid but rate limited")
+                return True
+            if response.status_code == 200:
+                self.logger.debug("✅ Anthropic API key validated successfully")
+                return True
+            self.warnings.append(
+                f"⚠️ Anthropic API returned unexpected status: {response.status_code}"
+            )
+            return True
+
+        except requests.exceptions.Timeout:
+            self.warnings.append(
+                "⚠️ Anthropic API validation timed out - assuming key is valid"
+            )
+            return True
+        except requests.exceptions.ConnectionError as e:
+            self.warnings.append(f"⚠️ Could not connect to Anthropic API: {e}")
+            return True
+        except Exception as e:
+            self.errors.append(f"❌ Anthropic API validation failed with error: {e}")
+            return False
+
+    def _validate_github_token(self, token: str) -> bool:
+        """Validate GitHub personal access token.
+
+        Args:
+            token: The GitHub token to validate
+
+        Returns:
+            True if valid, False otherwise
+        """
+        try:
+            # Check token validity with minimal request
+            response = requests.get(
+                "https://api.github.com/user",
+                headers={
+                    "Authorization": f"token {token}",
+                    "Accept": "application/vnd.github.v3+json",
+                },
+                timeout=10,
+            )
+
+            if response.status_code == 401:
+                self.errors.append("❌ GitHub token is invalid (401 Unauthorized)")
+                return False
+            if response.status_code == 403:
+                self.errors.append(
+                    "❌ GitHub token lacks required permissions (403 Forbidden)"
+                )
+                return False
+            if response.status_code == 200:
+                self.logger.debug("✅ GitHub token validated successfully")
+                return True
+            self.warnings.append(
+                f"⚠️ GitHub API returned unexpected status: {response.status_code}"
+            )
+            return True
+
+        except requests.exceptions.Timeout:
+            self.warnings.append(
+                "⚠️ GitHub API validation timed out - assuming token is valid"
+            )
+            return True
+        except requests.exceptions.ConnectionError as e:
+            self.warnings.append(f"⚠️ Could not connect to GitHub API: {e}")
+            return True
+        except Exception as e:
+            self.errors.append(f"❌ GitHub token validation failed with error: {e}")
+            return False
+
+    def _validate_custom_api(self, api_name: str, validation_config: Dict) -> bool:
+        """Validate a custom API key based on configuration.
+
+        Args:
+            api_name: Name of the API
+            validation_config: Configuration for validating this API
+
+        Returns:
+            True if valid, False otherwise
+        """
+        try:
+            env_var = validation_config.get("env_var")
+            if not env_var:
+                return True
+
+            api_key = os.getenv(env_var)
+            if not api_key:
+                return True  # Not configured, skip validation
+
+            # Get validation endpoint and method
+            endpoint = validation_config.get("endpoint")
+            method = validation_config.get("method", "GET").upper()
+            headers = validation_config.get("headers", {})
+
+            # Replace {API_KEY} placeholder in headers
+            for key, value in headers.items():
+                if isinstance(value, str):
+                    headers[key] = value.replace("{API_KEY}", api_key)
+
+            # Make validation request
+            if method == "GET":
+                response = requests.get(endpoint, headers=headers, timeout=10)
+            elif method == "POST":
+                body = validation_config.get("body", {})
+                response = requests.post(
+                    endpoint, headers=headers, json=body, timeout=10
+                )
+            else:
+                self.warnings.append(
+                    f"⚠️ Unsupported validation method for {api_name}: {method}"
+                )
+                return True
+
+            # Check expected status codes
+            valid_status_codes = validation_config.get("valid_status_codes", [200])
+            if response.status_code in valid_status_codes:
+                self.logger.debug(f"✅ {api_name} API key validated successfully")
+                return True
+            if response.status_code == 401:
+                self.errors.append(
+                    f"❌ {api_name} API key is invalid (401 Unauthorized)"
+                )
+                return False
+            if response.status_code == 403:
+                self.errors.append(
+                    f"❌ {api_name} API key lacks permissions (403 Forbidden)"
+                )
+                return False
+            self.warnings.append(
+                f"⚠️ {api_name} API returned status: {response.status_code}"
+            )
+            return True
+
+        except Exception as e:
+            self.warnings.append(f"⚠️ {api_name} API validation failed: {e}")
+            return True
+
+
+def validate_api_keys(config: Optional[Dict] = None, strict: bool = True) -> bool:
+    """Convenience function to validate all API keys.
+
+    Args:
+        config: Optional configuration dictionary
+        strict: If True, raise exception on validation failure
+
+    Returns:
+        True if all validations passed, False otherwise
+
+    Raises:
+        ValueError: If strict=True and any validation fails
+    """
+    validator = APIKeyValidator(config)
+    success, _errors, _warnings = validator.validate_all_keys(strict=strict)
+    return success

claude_mpm/core/base_service.py

@@ -26,11 +26,12 @@ import traceback
 from abc import ABC, abstractmethod
 from contextlib import asynccontextmanager
 from dataclasses import dataclass, field
-from datetime import datetime, timedelta
+from datetime import datetime, timedelta, timezone
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
 from .config import Config
+from .enums import HealthStatus
 from .mixins import LoggerMixin
 
 
@@ -38,7 +39,7 @@ from .mixins import LoggerMixin
 class ServiceHealth:
     """Service health status information."""
 
-    status: str  # healthy, degraded, unhealthy, unknown
+    status: HealthStatus  # Type-safe health status using enum
     message: str
     timestamp: str
     metrics: Dict[str, Any] = field(default_factory=dict)
@@ -142,9 +143,9 @@ class BaseService(LoggerMixin, ABC):
 
         # Health and metrics
         self._health = ServiceHealth(
-            status="unknown",
+            status=HealthStatus.UNKNOWN,
             message="Service not started",
-            timestamp=datetime.now().isoformat(),
+            timestamp=datetime.now(timezone.utc).isoformat(),
         )
         self._metrics = ServiceMetrics()
         self._last_health_check: Optional[float] = None
@@ -199,7 +200,7 @@ class BaseService(LoggerMixin, ABC):
     def uptime(self) -> Optional[float]:
         """Get service uptime in seconds."""
         if self._start_time and self._running:
-            return (datetime.now() - self._start_time).total_seconds()
+            return (datetime.now(timezone.utc) - self._start_time).total_seconds()
         return None
 
     @property
@@ -235,9 +236,9 @@ class BaseService(LoggerMixin, ABC):
         except Exception as e:
             self.logger.error(f"Failed to start service {self.name}: {e}")
             self._health = ServiceHealth(
-                status="unhealthy",
+                status=HealthStatus.UNHEALTHY,
                 message=f"Startup failed: {e!s}",
-                timestamp=datetime.now().isoformat(),
+                timestamp=datetime.now(timezone.utc).isoformat(),
                 checks={"startup": False},
             )
 
@@ -268,13 +269,13 @@ class BaseService(LoggerMixin, ABC):
 
         # Mark as running
         self._running = True
-        self._start_time = datetime.now()
+        self._start_time = datetime.now(timezone.utc)
 
         # Update health status
         self._health = ServiceHealth(
-            status="healthy",
+            status=HealthStatus.HEALTHY,
             message="Service started successfully",
-            timestamp=datetime.now().isoformat(),
+            timestamp=datetime.now(timezone.utc).isoformat(),
             checks={"startup": True},
             metrics=self._get_health_metrics() if self._enable_enhanced else {},
         )
@@ -336,9 +337,9 @@ class BaseService(LoggerMixin, ABC):
 
         # Update health status
         self._health = ServiceHealth(
-            status="unknown",
+            status=HealthStatus.UNKNOWN,
             message="Service stopped",
-            timestamp=datetime.now().isoformat(),
+            timestamp=datetime.now(timezone.utc).isoformat(),
             checks={"running": False},
         )
 
@@ -372,23 +373,23 @@ class BaseService(LoggerMixin, ABC):
 
             # Determine overall status
             if not checks["running"]:
-                status = "unhealthy"
+                status = HealthStatus.UNHEALTHY
                 message = "Service is not running"
             elif all(checks.values()):
-                status = "healthy"
+                status = HealthStatus.HEALTHY
                 message = "All health checks passed"
             elif any(checks.values()):
-                status = "degraded"
+                status = HealthStatus.DEGRADED
                 message = "Some health checks failed"
             else:
-                status = "unhealthy"
+                status = HealthStatus.UNHEALTHY
                 message = "Multiple health checks failed"
 
             # Update health status
             self._health = ServiceHealth(
                 status=status,
                 message=message,
-                timestamp=datetime.now().isoformat(),
+                timestamp=datetime.now(timezone.utc).isoformat(),
                 checks=checks,
                 metrics={
                     "uptime": self.uptime,
@@ -402,9 +403,9 @@ class BaseService(LoggerMixin, ABC):
         except Exception as e:
             self.logger.error(f"Health check failed for {self.name}: {e}")
             self._health = ServiceHealth(
-                status="unhealthy",
+                status=HealthStatus.UNHEALTHY,
                 message=f"Health check error: {e!s}",
-                timestamp=datetime.now().isoformat(),
+                timestamp=datetime.now(timezone.utc).isoformat(),
                 checks={"health_check_error": True},
             )
             return self._health
@@ -428,7 +429,16 @@ class BaseService(LoggerMixin, ABC):
             self.logger.info(
                 f"Received signal {signum}, initiating graceful shutdown..."
             )
-            asyncio.create_task(self.stop())
+            # Get the event loop and create a tracked shutdown task
+            try:
+                loop = asyncio.get_event_loop()
+                task = loop.create_task(self.stop())
+                # Store reference to prevent GC during shutdown
+                if not hasattr(self, "_shutdown_task"):
+                    self._shutdown_task = task
+            except RuntimeError:
+                # No event loop, call stop synchronously
+                self.logger.warning("No event loop available for graceful shutdown")
 
         signal.signal(signal.SIGINT, signal_handler)
         signal.signal(signal.SIGTERM, signal_handler)
@@ -584,9 +594,9 @@ class BaseService(LoggerMixin, ABC):
                     )
                 else:
                     return ServiceHealth(
-                        status="degraded",
+                        status=HealthStatus.DEGRADED,
                         message="Service circuit breaker is open",
-                        timestamp=datetime.now().isoformat(),
+                        timestamp=datetime.now(timezone.utc).isoformat(),
                         checks={"circuit_breaker": False},
                         metrics=self._get_health_metrics(),
                     )
@@ -595,7 +605,7 @@ class BaseService(LoggerMixin, ABC):
             health = await self.health_check()
 
             # Update circuit breaker
-            if health.status in ["healthy", "degraded"]:
+            if health.status in (HealthStatus.HEALTHY, HealthStatus.DEGRADED):
                 self._record_circuit_success()
             else:
                 self._record_circuit_failure()