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

claude_mpm/commands/mpm.md

@@ -0,0 +1,21 @@
+# Claude MPM - Multi-Agent Project Manager
+
+Access Claude MPM functionality and manage your multi-agent orchestration.
+
+Available MPM commands:
+- /mpm-agents - Show available agents and versions
+- /mpm-doctor - Run diagnostic checks
+- /mpm-help - Show command help
+- /mpm-status - Show MPM status
+- /mpm-config - Manage configuration
+- /mpm-resume - Create session resume files
+- /mpm-version - Display version information for project, agents, and skills
+
+Claude MPM extends Claude Code with:
+- Multi-agent orchestration
+- Project-specific PM instructions
+- Agent memory management
+- WebSocket monitoring
+- Hook system for automation
+
+For more information, use /mpm-help [command]

claude_mpm/config/agent_config.py

@@ -14,17 +14,17 @@ This module handles:
 UPDATED: Migrated to use shared ConfigLoader pattern (TSK-0141)
 """
 
-import logging
 import os
 from dataclasses import dataclass, field
 from enum import Enum
 from pathlib import Path
 from typing import Any, Dict, List, Optional
 
+from claude_mpm.core.logging_utils import get_logger
 from claude_mpm.core.shared.config_loader import ConfigLoader, ConfigPattern
 from claude_mpm.core.unified_paths import get_path_manager
 
-logger = logging.getLogger(__name__)
+logger = get_logger(__name__)
 
 
 class AgentPrecedenceMode(Enum):
@@ -242,7 +242,7 @@ class AgentConfig:
                 Path.cwd() / get_path_manager().CONFIG_DIR / "agent_config.yaml"
             )
             if project_config.exists():
-                logger.info(f"Loading project agent config from {project_config}")
+                logger.debug(f"Loading project agent config from {project_config}")
                 file_config = cls.from_file(project_config)
                 # Merge with environment config (env takes precedence)
                 config = cls._merge_configs(config, file_config)
@@ -252,7 +252,7 @@ class AgentConfig:
             if user_config_dir:
                 user_config = user_config_dir / "agent_config.yaml"
                 if user_config.exists():
-                    logger.info(f"Loading user agent config from {user_config}")
+                    logger.debug(f"Loading user agent config from {user_config}")
                     file_config = cls.from_file(user_config)
                     config = cls._merge_configs(config, file_config)
 

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

@@ -10,6 +10,8 @@ WHY configuration management:
 - Supports multiple deployment scenarios (local, PyPI, Docker, etc.)
 - Provides environment-specific defaults
 - Allows runtime configuration overrides
+
+CRITICAL: Ping/pong settings MUST match between client and server to prevent disconnections!
 """
 
 import os
@@ -19,6 +21,30 @@ from typing import Any, Dict, List, Optional
 # Import constants for default values
 from claude_mpm.core.constants import NetworkConfig, RetryConfig, SystemLimits
 
+# Connection stability settings - MUST be consistent between client and server
+CONNECTION_CONFIG = {
+    # Ping/pong intervals (milliseconds for client, seconds for server)
+    "ping_interval_ms": 25000,  # 25 seconds (for client JavaScript)
+    "ping_interval": 25,  # 25 seconds (for server Python) - reduced for stability
+    "ping_timeout_ms": 20000,  # 20 seconds (for client JavaScript)
+    "ping_timeout": 20,  # 20 seconds (for server Python)
+    # Connection management
+    "stale_timeout": 90,  # 90 seconds before considering connection stale (was 180)
+    "health_check_interval": 30,  # Health check every 30 seconds
+    "event_ttl": 300,  # Keep events for 5 minutes for replay
+    "connection_timeout": 10,  # 10 seconds for initial connection timeout
+    # Client reconnection settings
+    "reconnection_attempts": 5,  # Number of reconnection attempts
+    "reconnection_delay": 1000,  # Initial delay in ms
+    "reconnection_delay_max": 5000,  # Maximum delay in ms
+    # Feature flags
+    "enable_extra_heartbeat": False,  # Disable redundant heartbeats
+    "enable_health_monitoring": True,  # Enable connection health monitoring
+    # Buffer settings
+    "max_events_buffer": 1000,  # Maximum events to buffer per client
+    "max_http_buffer_size": 1e8,  # 100MB max buffer for large payloads
+}
+
 
 @dataclass
 class SocketIOConfig:
@@ -29,11 +55,14 @@ class SocketIOConfig:
     port: int = NetworkConfig.DEFAULT_DASHBOARD_PORT
     server_id: Optional[str] = None
 
-    # Connection settings
+    # Connection settings - Use centralized config for consistency
     cors_allowed_origins: str = "*"  # Configure properly for production
-    ping_timeout: int = NetworkConfig.PING_TIMEOUT_STANDARD
-    ping_interval: int = NetworkConfig.PING_INTERVAL_STANDARD
-    max_http_buffer_size: int = 1000000
+    ping_timeout: int = CONNECTION_CONFIG["ping_timeout"]  # 20 seconds
+    ping_interval: int = CONNECTION_CONFIG["ping_interval"]  # 25 seconds (was 45)
+    max_http_buffer_size: int = int(CONNECTION_CONFIG["max_http_buffer_size"])
+    connection_timeout: int = CONNECTION_CONFIG.get(
+        "connection_timeout", 10
+    )  # 10 seconds
 
     # Compatibility settings
     min_client_version: str = "0.7.0"
@@ -157,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
@@ -220,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}")
@@ -238,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: