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

claude_mpm/config/experimental_features.py

@@ -12,7 +12,7 @@ gradual rollout of experimental features while maintaining stability in producti
 
 import json
 import os
-from typing import Dict, Optional
+from typing import ClassVar, Dict, Optional
 
 
 class ExperimentalFeatures:
@@ -26,7 +26,7 @@ class ExperimentalFeatures:
     """
 
     # Default feature flags
-    DEFAULTS = {
+    DEFAULTS: ClassVar[Dict[str, bool]] = {
         "enable_mcp_gateway": False,  # MCP Gateway is experimental
         "enable_advanced_aggregation": False,  # Advanced aggregation features
         "show_experimental_warnings": True,  # Show warnings for experimental features
@@ -34,7 +34,7 @@ class ExperimentalFeatures:
     }
 
     # Warning messages for experimental features
-    WARNINGS = {
+    WARNINGS: ClassVar[Dict[str, str]] = {
         "mcp_gateway": (
             "⚠️  EXPERIMENTAL FEATURE: MCP Gateway is in early access.\n"
             "   Tool integration may be unstable. Not recommended for production use."
@@ -64,7 +64,7 @@ class ExperimentalFeatures:
         """
         if self._config_file and self._config_file.exists():
             try:
-                with open(self._config_file) as f:
+                with self._config_file.open() as f:
                     config = json.load(f)
                     experimental = config.get("experimental_features", {})
                     self._features.update(experimental)
@@ -125,7 +125,7 @@ class ExperimentalFeatures:
         accepted_file = Path.home() / ".claude-mpm" / ".experimental_accepted"
         if accepted_file.exists():
             try:
-                with open(accepted_file) as f:
+                with accepted_file.open() as f:
                     accepted = json.load(f)
                     if feature in accepted.get("features", []):
                         return False
@@ -148,7 +148,7 @@ class ExperimentalFeatures:
 
         try:
             if accepted_file.exists():
-                with open(accepted_file) as f:
+                with accepted_file.open() as f:
                     data = json.load(f)
             else:
                 data = {"features": [], "timestamp": {}}
@@ -159,7 +159,7 @@ class ExperimentalFeatures:
                     "CLAUDE_MPM_TIMESTAMP", str(Path.cwd())
                 )
 
-            with open(accepted_file, "w") as f:
+            with accepted_file.open("w") as f:
                 json.dump(data, f, indent=2)
         except Exception:
             # Silently ignore errors in acceptance tracking

claude_mpm/config/model_config.py

@@ -0,0 +1,428 @@
+"""
+Model Configuration Management for Claude MPM Framework
+=======================================================
+
+WHY: Centralizes configuration for model providers, routing strategy, and
+model selection. Supports configuration files, environment variables, and
+programmatic configuration.
+
+DESIGN DECISION: Uses Pydantic for configuration validation and type safety.
+Supports loading from YAML files and environment variables with sensible defaults.
+
+CONFIGURATION STRUCTURE:
+```yaml
+content_agent:
+  model_provider: auto  # auto|ollama|claude|privacy
+
+  ollama:
+    enabled: true
+    host: http://localhost:11434
+    fallback_to_cloud: true
+    timeout: 30
+    models:
+      seo_analysis: llama3.3:70b
+      readability: gemma2:9b
+      grammar: qwen3:14b
+      summarization: mistral:7b
+      keyword_extraction: seoassistant
+
+  claude:
+    enabled: true
+    model: claude-3-5-sonnet-20241022
+    max_tokens: 4096
+    temperature: 0.7
+```
+
+ENVIRONMENT VARIABLES:
+- MODEL_PROVIDER: Override provider strategy
+- OLLAMA_HOST: Override Ollama endpoint
+- OLLAMA_ENABLED: Enable/disable Ollama
+- CLAUDE_ENABLED: Enable/disable Claude
+- ANTHROPIC_API_KEY: Claude API key
+"""
+
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+from pydantic import BaseModel, Field
+
+try:
+    import yaml
+except ImportError:
+    yaml = None  # type: ignore
+
+
+class OllamaConfig(BaseModel):
+    """
+    Configuration for Ollama provider.
+
+    WHY: Separates Ollama-specific settings for better organization
+    and validation.
+    """
+
+    enabled: bool = Field(default=True, description="Enable Ollama provider")
+    host: str = Field(
+        default="http://localhost:11434",
+        description="Ollama API endpoint",
+    )
+    fallback_to_cloud: bool = Field(
+        default=True,
+        description="Allow fallback to cloud on Ollama failure",
+    )
+    timeout: int = Field(default=30, description="Request timeout in seconds")
+    models: Dict[str, str] = Field(
+        default_factory=dict,
+        description="Task-specific model mappings",
+    )
+
+    class Config:
+        """Pydantic config."""
+
+        extra = "allow"
+
+
+class ClaudeConfig(BaseModel):
+    """
+    Configuration for Claude provider.
+
+    WHY: Separates Claude-specific settings for better organization
+    and validation.
+    """
+
+    enabled: bool = Field(default=True, description="Enable Claude provider")
+    model: str = Field(
+        default="claude-3-5-sonnet-20241022",
+        description="Default Claude model",
+    )
+    max_tokens: int = Field(
+        default=4096,
+        description="Maximum response tokens",
+    )
+    temperature: float = Field(
+        default=0.7,
+        description="Sampling temperature (0.0-1.0)",
+    )
+    api_key: Optional[str] = Field(
+        default=None,
+        description="Anthropic API key (can use env var)",
+    )
+
+    class Config:
+        """Pydantic config."""
+
+        extra = "allow"
+
+
+class ModelProviderConfig(BaseModel):
+    """
+    Main model provider configuration.
+
+    WHY: Top-level configuration containing all model-related settings.
+    Validates configuration at load time to catch errors early.
+    """
+
+    provider: str = Field(
+        default="auto",
+        description="Provider strategy: auto|ollama|claude|privacy",
+    )
+    ollama: OllamaConfig = Field(
+        default_factory=OllamaConfig,
+        description="Ollama provider configuration",
+    )
+    claude: ClaudeConfig = Field(
+        default_factory=ClaudeConfig,
+        description="Claude provider configuration",
+    )
+
+    class Config:
+        """Pydantic config."""
+
+        extra = "allow"
+
+
+class ModelConfigManager:
+    """
+    Manager for model configuration.
+
+    WHY: Provides centralized configuration loading with support for
+    multiple sources (files, env vars, defaults) and validation.
+
+    Usage:
+        manager = ModelConfigManager()
+        config = manager.load_config()
+
+        # Get router config
+        router_config = manager.get_router_config(config)
+
+        # Get provider configs
+        ollama_config = manager.get_ollama_config(config)
+        claude_config = manager.get_claude_config(config)
+    """
+
+    DEFAULT_CONFIG_PATHS = [
+        ".claude/configuration.yaml",
+        "configuration.yaml",
+        ".claude-mpm/configuration.yaml",
+        str(Path("~/.claude-mpm/configuration.yaml").expanduser()),
+    ]
+
+    @staticmethod
+    def load_config(
+        config_path: Optional[str] = None,
+    ) -> ModelProviderConfig:
+        """
+        Load model configuration from file and environment.
+
+        WHY: Supports multiple configuration sources with priority:
+        1. Explicit config_path parameter
+        2. Environment variables
+        3. Configuration file
+        4. Default values
+
+        Args:
+            config_path: Optional path to configuration file
+
+        Returns:
+            ModelProviderConfig with merged settings
+        """
+        config_data: Dict[str, Any] = {}
+
+        # Try to load from file
+        if config_path and Path(config_path).exists():
+            config_data = ModelConfigManager._load_yaml_file(config_path)
+        else:
+            # Try default paths
+            for default_path in ModelConfigManager.DEFAULT_CONFIG_PATHS:
+                if Path(default_path).exists():
+                    config_data = ModelConfigManager._load_yaml_file(default_path)
+                    break
+
+        # Extract content_agent section if present
+        if "content_agent" in config_data:
+            config_data = config_data["content_agent"]
+
+        # Override with environment variables
+        config_data = ModelConfigManager._apply_env_overrides(config_data)
+
+        # Create and validate config
+        try:
+            return ModelProviderConfig(**config_data)
+        except Exception as e:
+            # If validation fails, return default config
+            print(f"Warning: Failed to load config: {e}. Using defaults.")
+            return ModelProviderConfig()
+
+    @staticmethod
+    def _load_yaml_file(path: str) -> Dict[str, Any]:
+        """
+        Load YAML configuration file.
+
+        Args:
+            path: Path to YAML file
+
+        Returns:
+            Dictionary of configuration
+        """
+        if yaml is None:
+            return {}
+
+        try:
+            path_obj = Path(path)
+            with path_obj.open() as f:
+                data = yaml.safe_load(f)
+                return data or {}
+        except Exception as e:
+            print(f"Warning: Failed to load {path}: {e}")
+            return {}
+
+    @staticmethod
+    def _apply_env_overrides(config: Dict[str, Any]) -> Dict[str, Any]:
+        """
+        Apply environment variable overrides.
+
+        WHY: Allows runtime configuration without modifying files.
+        Useful for containerized deployments and CI/CD.
+
+        Args:
+            config: Base configuration
+
+        Returns:
+            Configuration with env overrides applied
+        """
+        # Provider strategy
+        if "MODEL_PROVIDER" in os.environ:
+            config["provider"] = os.environ["MODEL_PROVIDER"]
+
+        # Ollama settings
+        if "ollama" not in config:
+            config["ollama"] = {}
+
+        if "OLLAMA_ENABLED" in os.environ:
+            config["ollama"]["enabled"] = os.environ["OLLAMA_ENABLED"].lower() == "true"
+
+        if "OLLAMA_HOST" in os.environ:
+            config["ollama"]["host"] = os.environ["OLLAMA_HOST"]
+
+        if "OLLAMA_TIMEOUT" in os.environ:
+            try:
+                config["ollama"]["timeout"] = int(os.environ["OLLAMA_TIMEOUT"])
+            except ValueError:
+                pass
+
+        if "OLLAMA_FALLBACK_TO_CLOUD" in os.environ:
+            config["ollama"]["fallback_to_cloud"] = (
+                os.environ["OLLAMA_FALLBACK_TO_CLOUD"].lower() == "true"
+            )
+
+        # Claude settings
+        if "claude" not in config:
+            config["claude"] = {}
+
+        if "CLAUDE_ENABLED" in os.environ:
+            config["claude"]["enabled"] = os.environ["CLAUDE_ENABLED"].lower() == "true"
+
+        if "ANTHROPIC_API_KEY" in os.environ:
+            config["claude"]["api_key"] = os.environ["ANTHROPIC_API_KEY"]
+
+        if "CLAUDE_MODEL" in os.environ:
+            config["claude"]["model"] = os.environ["CLAUDE_MODEL"]
+
+        if "CLAUDE_MAX_TOKENS" in os.environ:
+            try:
+                config["claude"]["max_tokens"] = int(os.environ["CLAUDE_MAX_TOKENS"])
+            except ValueError:
+                pass
+
+        if "CLAUDE_TEMPERATURE" in os.environ:
+            try:
+                config["claude"]["temperature"] = float(
+                    os.environ["CLAUDE_TEMPERATURE"]
+                )
+            except ValueError:
+                pass
+
+        return config
+
+    @staticmethod
+    def get_router_config(config: ModelProviderConfig) -> Dict[str, Any]:
+        """
+        Get router configuration from model config.
+
+        Args:
+            config: Model provider configuration
+
+        Returns:
+            Dictionary suitable for ModelRouter initialization
+        """
+        return {
+            "strategy": config.provider,
+            "fallback_enabled": config.ollama.fallback_to_cloud,
+            "ollama_config": ModelConfigManager.get_ollama_config(config),
+            "claude_config": ModelConfigManager.get_claude_config(config),
+        }
+
+    @staticmethod
+    def get_ollama_config(config: ModelProviderConfig) -> Dict[str, Any]:
+        """
+        Get Ollama provider configuration.
+
+        Args:
+            config: Model provider configuration
+
+        Returns:
+            Dictionary suitable for OllamaProvider initialization
+        """
+        return {
+            "host": config.ollama.host,
+            "timeout": config.ollama.timeout,
+            "models": config.ollama.models,
+        }
+
+    @staticmethod
+    def get_claude_config(config: ModelProviderConfig) -> Dict[str, Any]:
+        """
+        Get Claude provider configuration.
+
+        Args:
+            config: Model provider configuration
+
+        Returns:
+            Dictionary suitable for ClaudeProvider initialization
+        """
+        return {
+            "api_key": config.claude.api_key,
+            "model": config.claude.model,
+            "max_tokens": config.claude.max_tokens,
+            "temperature": config.claude.temperature,
+        }
+
+    @staticmethod
+    def create_sample_config(output_path: str) -> None:
+        """
+        Create sample configuration file.
+
+        WHY: Helps users get started with proper configuration.
+
+        Args:
+            output_path: Path where to write sample config
+        """
+        sample_config = """# Claude MPM Model Provider Configuration
+# ==========================================
+
+content_agent:
+  # Provider strategy: auto|ollama|claude|privacy
+  # - auto: Try Ollama first, fallback to Claude
+  # - ollama: Local-only, fail if unavailable
+  # - claude: Cloud-only, always use Claude
+  # - privacy: Like ollama but with privacy-focused error messages
+  model_provider: auto
+
+  # Ollama Configuration (local models)
+  ollama:
+    enabled: true
+    host: http://localhost:11434
+    fallback_to_cloud: true  # Allow fallback to Claude on error
+    timeout: 30  # Request timeout in seconds
+
+    # Task-specific model mappings (optional)
+    # Defaults are provided if not specified
+    models:
+      seo_analysis: llama3.3:70b
+      readability: gemma2:9b
+      grammar: qwen3:14b
+      summarization: mistral:7b
+      keyword_extraction: seoassistant
+      accessibility: gemma2:9b
+      sentiment: gemma2:9b
+      general: gemma2:9b
+
+  # Claude Configuration (cloud models)
+  claude:
+    enabled: true
+    model: claude-3-5-sonnet-20241022
+    max_tokens: 4096
+    temperature: 0.7
+    # api_key: sk-ant-...  # Or use ANTHROPIC_API_KEY env var
+
+# Environment Variable Overrides:
+# - MODEL_PROVIDER: Override provider strategy
+# - OLLAMA_HOST: Override Ollama endpoint
+# - OLLAMA_ENABLED: Enable/disable Ollama (true/false)
+# - CLAUDE_ENABLED: Enable/disable Claude (true/false)
+# - ANTHROPIC_API_KEY: Claude API key
+# - CLAUDE_MODEL: Override Claude model
+"""
+
+        output_path_obj = Path(output_path)
+        output_path_obj.parent.mkdir(parents=True, exist_ok=True)
+        with output_path_obj.open("w") as f:
+            f.write(sample_config)
+
+
+__all__ = [
+    "ClaudeConfig",
+    "ModelConfigManager",
+    "ModelProviderConfig",
+    "OllamaConfig",
+]

claude_mpm/config/paths.py

@@ -8,14 +8,15 @@ This module provides a consistent, reliable way to access project paths
 without fragile parent.parent.parent patterns.
 """
 
-import logging
 from pathlib import Path
 from typing import Optional, Union
 
+from claude_mpm.core.logging_utils import get_logger
+
 # Import from the unified path management system
 from ..core.unified_paths import get_path_manager
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 class ClaudeMPMPaths:

claude_mpm/config/socketio_config.py

@@ -186,7 +186,7 @@ class ConfigManager:
     def detect_environment(self) -> str:
         """Detect the current deployment environment."""
         # Check for Docker
-        if os.path.exists("/.dockerenv") or os.getenv("DOCKER_CONTAINER"):
+        if Path("/.dockerenv").exists() or os.getenv("DOCKER_CONTAINER"):
             return "docker"
 
         # Check for production indicators
@@ -249,7 +249,7 @@ class ConfigManager:
         for config_path in self.config_search_paths:
             if config_path.exists():
                 try:
-                    with open(config_path) as f:
+                    with config_path.open() as f:
                         return json.load(f)
                 except Exception as e:
                     print(f"Warning: Failed to load config from {config_path}: {e}")
@@ -267,7 +267,7 @@ class ConfigManager:
             path = config_dir / self.config_file_name
 
         try:
-            with open(path, "w") as f:
+            with path.open("w") as f:
                 json.dump(config.to_dict(), f, indent=2)
             return True
         except Exception as e:

claude_mpm/constants.py

@@ -44,6 +44,8 @@ class CLICommands(str, Enum):
     MCP = "mcp"
     DOCTOR = "doctor"
     DASHBOARD = "dashboard"
+    UPGRADE = "upgrade"
+    SKILLS = "skills"
 
     def with_prefix(self, prefix: CLIPrefix = CLIPrefix.MPM) -> str:
         """Get command with prefix."""
@@ -140,6 +142,7 @@ class MCPCommands(str, Enum):
     TEST = "test"
     CONFIG = "config"
     SERVER = "server"
+    EXTERNAL = "external"
 
 
 class TicketCommands(str, Enum):
@@ -156,6 +159,17 @@ class TicketCommands(str, Enum):
     WORKFLOW = "workflow"
 
 
+class SkillsCommands(str, Enum):
+    """Skills subcommand constants."""
+
+    LIST = "list"
+    DEPLOY = "deploy"
+    VALIDATE = "validate"
+    UPDATE = "update"
+    INFO = "info"
+    CONFIG = "config"
+
+
 class CLIFlags(str, Enum):
     """CLI flag constants (without prefix)."""
 
@@ -229,7 +243,7 @@ class Paths(str, Enum):
 
     CLAUDE_AGENTS_DIR = ".claude/agents"
     CLAUDE_CONFIG_DIR = ".claude"
-    MPM_LOG_DIR = "logs/mpm"
+    MPM_LOG_DIR = ".claude-mpm/logs/mpm"
     MPM_SESSION_DIR = ".claude-mpm/session"
     MPM_PROMPTS_DIR = ".claude-mpm/prompts"
 

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}