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

claude_mpm/services/memory_hook_service.py

@@ -11,6 +11,7 @@ Extracted from ClaudeRunner to follow Single Responsibility Principle.
 from typing import Any, Dict
 
 from claude_mpm.core.base_service import BaseService
+from claude_mpm.core.enums import ServiceState
 from claude_mpm.services.core.interfaces import MemoryHookInterface
 
 
@@ -41,8 +42,8 @@ class MemoryHookService(BaseService, MemoryHookInterface):
         These hooks ensure memory is properly managed and persisted.
 
         DESIGN DECISION: We register hooks for key lifecycle events:
-        - Before Claude interaction: Load relevant memories
-        - After Claude interaction: Save new memories
+        - Before Claude interaction: Load relevant memories (kuzu-memory + legacy)
+        - After Claude interaction: Save new memories (kuzu-memory + legacy)
         - On error: Ensure memory state is preserved
         """
         if not self.hook_service:
@@ -90,11 +91,169 @@ class MemoryHookService(BaseService, MemoryHookInterface):
             if success2:
                 self.registered_hooks.append("memory_save")
 
-            self.logger.debug("Memory hooks registered successfully")
+            self.logger.debug("Legacy memory hooks registered successfully")
+
+            # Register kuzu-memory hooks if available
+            self._register_kuzu_memory_hooks()
+
+            # Register failure-learning hooks
+            self._register_failure_learning_hooks()
 
         except Exception as e:
             self.logger.warning(f"Failed to register memory hooks: {e}")
 
+    def _register_kuzu_memory_hooks(self):
+        """Register kuzu-memory bidirectional enrichment hooks.
+
+        WHY: Kuzu-memory provides persistent knowledge graph storage that works
+        across conversations. This enables:
+        1. Delegation context enrichment with relevant memories (READ)
+        2. Automatic learning extraction from responses (WRITE)
+
+        DESIGN DECISION: These hooks are separate from legacy memory hooks to
+        allow independent evolution and configuration. Both systems can coexist.
+        """
+        try:
+            # Check if kuzu-memory is enabled in config
+            from claude_mpm.core.config import Config
+
+            config = Config()
+            kuzu_config = config.get("memory.kuzu", {})
+            if isinstance(kuzu_config, dict):
+                kuzu_enabled = kuzu_config.get("enabled", True)
+                enrichment_enabled = kuzu_config.get("enrichment", True)
+                learning_enabled = kuzu_config.get("learning", True)
+            else:
+                # Default to enabled if config section doesn't exist
+                kuzu_enabled = True
+                enrichment_enabled = True
+                learning_enabled = True
+
+            if not kuzu_enabled:
+                self.logger.debug("Kuzu-memory disabled in configuration")
+                return
+
+            from claude_mpm.hooks import (
+                get_kuzu_enrichment_hook,
+                get_kuzu_response_hook,
+            )
+
+            # Get kuzu-memory hooks
+            enrichment_hook = get_kuzu_enrichment_hook()
+            learning_hook = get_kuzu_response_hook()
+
+            # Register enrichment hook (PreDelegationHook) if enabled
+            if enrichment_hook.enabled and enrichment_enabled:
+                success = self.hook_service.register_hook(enrichment_hook)
+                if success:
+                    self.registered_hooks.append("kuzu_memory_enrichment")
+                    self.logger.info(
+                        "✅ Kuzu-memory enrichment enabled (prompts → memories)"
+                    )
+                else:
+                    self.logger.warning(
+                        "Failed to register kuzu-memory enrichment hook"
+                    )
+            elif not enrichment_enabled:
+                self.logger.debug("Kuzu-memory enrichment disabled in configuration")
+
+            # Register learning hook (PostDelegationHook) if enabled
+            if learning_hook.enabled and learning_enabled:
+                success = self.hook_service.register_hook(learning_hook)
+                if success:
+                    self.registered_hooks.append("kuzu_response_learner")
+                    self.logger.info(
+                        "✅ Kuzu-memory learning enabled (responses → memories)"
+                    )
+                else:
+                    self.logger.warning("Failed to register kuzu-memory learning hook")
+            elif not learning_enabled:
+                self.logger.debug("Kuzu-memory learning disabled in configuration")
+
+            # If neither hook is enabled, kuzu-memory is not available
+            if not enrichment_hook.enabled and not learning_hook.enabled:
+                self.logger.debug(
+                    "Kuzu-memory not available. Install with: pipx install kuzu-memory"
+                )
+
+        except ImportError as e:
+            self.logger.debug(f"Kuzu-memory hooks not available: {e}")
+        except Exception as e:
+            self.logger.warning(f"Failed to register kuzu-memory hooks: {e}")
+
+    def _register_failure_learning_hooks(self):
+        """Register failure-learning hooks for automatic learning extraction.
+
+        WHY: When tasks fail and agents fix them, we want to automatically capture
+        this as a learning. The failure-learning system provides:
+        1. Failure detection from tool outputs (errors, exceptions, test failures)
+        2. Fix detection when same task type succeeds after failure
+        3. Learning extraction and persistence to agent memory files
+
+        DESIGN DECISION: These hooks work as a chain with specific priorities:
+        - FailureDetectionHook (priority=85): Detects failures after tool execution
+        - FixDetectionHook (priority=87): Matches fixes with failures
+        - LearningExtractionHook (priority=89): Extracts and persists learnings
+
+        The system is enabled by default but can be disabled via configuration.
+        """
+        try:
+            # Check if failure-learning is enabled in config
+            from claude_mpm.core.config import Config
+
+            config = Config()
+            failure_learning_config = config.get("memory.failure_learning", {})
+
+            if isinstance(failure_learning_config, dict):
+                enabled = failure_learning_config.get("enabled", True)
+            else:
+                # Default to enabled if config section doesn't exist
+                enabled = True
+
+            if not enabled:
+                self.logger.debug("Failure-learning disabled in configuration")
+                return
+
+            # Import failure-learning hooks
+            from claude_mpm.hooks.failure_learning import (
+                get_failure_detection_hook,
+                get_fix_detection_hook,
+                get_learning_extraction_hook,
+            )
+
+            # Get hook instances
+            failure_hook = get_failure_detection_hook()
+            fix_hook = get_fix_detection_hook()
+            learning_hook = get_learning_extraction_hook()
+
+            # Register hooks in priority order
+            success1 = self.hook_service.register_hook(failure_hook)
+            success2 = self.hook_service.register_hook(fix_hook)
+            success3 = self.hook_service.register_hook(learning_hook)
+
+            if success1:
+                self.registered_hooks.append("failure_detection")
+                self.logger.debug("✅ Failure detection enabled")
+
+            if success2:
+                self.registered_hooks.append("fix_detection")
+                self.logger.debug("✅ Fix detection enabled")
+
+            if success3:
+                self.registered_hooks.append("learning_extraction")
+                self.logger.debug("✅ Learning extraction enabled")
+
+            if success1 and success2 and success3:
+                self.logger.info(
+                    "✅ Failure-learning system enabled "
+                    "(failures → fixes → learnings → memory)"
+                )
+
+        except ImportError as e:
+            self.logger.debug(f"Failure-learning hooks not available: {e}")
+        except Exception as e:
+            self.logger.warning(f"Failed to register failure-learning hooks: {e}")
+
     def _load_relevant_memories_hook(self, context):
         """Hook function to load relevant memories before Claude interaction.
 
@@ -305,5 +464,7 @@ class MemoryHookService(BaseService, MemoryHookInterface):
             "hook_service_available": self.hook_service is not None,
             "memory_enabled": self.is_memory_enabled(),
             "total_hooks": len(self.registered_hooks),
-            "status": "active" if self.registered_hooks else "inactive",
+            "status": (
+                ServiceState.RUNNING if self.registered_hooks else ServiceState.IDLE
+            ),
         }

claude_mpm/services/model/__init__.py

@@ -0,0 +1,147 @@
+"""
+Model Services Package for Claude MPM Framework
+================================================
+
+WHY: Provides hybrid local/cloud content processing with intelligent routing
+and automatic fallback. Enables privacy-preserving local model execution via
+Ollama with cloud fallback to Claude for reliability.
+
+ARCHITECTURE:
+- Interfaces: Core contracts for model providers and routing (IModelProvider, IModelRouter)
+- Base Provider: Common functionality for all providers (BaseModelProvider)
+- Providers: Ollama (local) and Claude (cloud) implementations
+- Router: Intelligent routing with fallback logic (ModelRouter)
+- Configuration: Centralized config management (model_config.py)
+
+USAGE:
+
+    Basic Usage with Auto-Routing:
+    ```python
+    from claude_mpm.services.model import ModelRouter
+    from claude_mpm.services.core.interfaces.model import ModelCapability
+
+    # Create router with default config (auto mode)
+    router = ModelRouter()
+    await router.initialize()
+
+    # Analyze content (tries Ollama first, falls back to Claude)
+    response = await router.analyze_content(
+        content="Your article text here...",
+        task=ModelCapability.SEO_ANALYSIS
+    )
+
+    if response.success:
+        print(f"Analysis by {response.provider}:")
+        print(response.result)
+    ```
+
+    Direct Provider Usage:
+    ```python
+    from claude_mpm.services.model import OllamaProvider
+
+    # Use Ollama directly
+    provider = OllamaProvider(config={
+        "host": "http://localhost:11434"
+    })
+
+    if await provider.is_available():
+        response = await provider.analyze_content(
+            content="Text to analyze",
+            task=ModelCapability.READABILITY
+        )
+    ```
+
+    Configuration-Based Setup:
+    ```python
+    from claude_mpm.config.model_config import ModelConfigManager
+    from claude_mpm.services.model import ModelRouter
+
+    # Load config from file
+    config = ModelConfigManager.load_config(".claude/configuration.yaml")
+    router_config = ModelConfigManager.get_router_config(config)
+
+    # Create router with loaded config
+    router = ModelRouter(config=router_config)
+    await router.initialize()
+    ```
+
+PROVIDER STRATEGIES:
+- AUTO: Try Ollama first, fallback to Claude (default)
+- OLLAMA: Local-only, fail if unavailable (privacy mode)
+- CLAUDE: Cloud-only, always use Claude
+- PRIVACY: Like OLLAMA with privacy-focused messages
+
+RECOMMENDED MODELS (Ollama):
+- SEO Analysis: llama3.3:70b - Comprehensive SEO insights
+- Readability: gemma2:9b - Fast, accurate readability scoring
+- Grammar: qwen3:14b - Specialized grammar checking
+- Summarization: mistral:7b - Concise, effective summaries
+- Keyword Extraction: seoassistant - SEO-specialized model
+
+CONFIGURATION:
+See claude_mpm.config.model_config for detailed configuration options.
+
+Example configuration.yaml:
+```yaml
+content_agent:
+  model_provider: auto
+
+  ollama:
+    enabled: true
+    host: http://localhost:11434
+    fallback_to_cloud: true
+    models:
+      seo_analysis: llama3.3:70b
+      readability: gemma2:9b
+
+  claude:
+    enabled: true
+    model: claude-3-5-sonnet-20241022
+```
+
+PHASE 1 STATUS (Current):
+✅ Core interfaces and contracts defined
+✅ Base provider with common functionality
+✅ Ollama provider with direct API integration
+✅ Claude provider (Phase 1: mock responses)
+✅ Router with intelligent fallback logic
+✅ Configuration management with validation
+⏳ Claude API integration (Phase 2)
+⏳ Content agent integration (Phase 2)
+"""
+
+# Re-export interfaces for convenience
+from claude_mpm.services.core.interfaces.model import (
+    IModelProvider,
+    IModelRouter,
+    ModelCapability,
+    ModelProvider,
+    ModelResponse,
+)
+from claude_mpm.services.model.base_provider import BaseModelProvider
+from claude_mpm.services.model.claude_provider import ClaudeProvider
+from claude_mpm.services.model.model_router import ModelRouter, RoutingStrategy
+from claude_mpm.services.model.ollama_provider import OllamaProvider
+
+__all__ = [  # noqa: RUF022 - Semantic grouping preferred over alphabetical
+    # Base classes
+    "BaseModelProvider",
+    # Providers
+    "ClaudeProvider",
+    "OllamaProvider",
+    # Router
+    "ModelRouter",
+    "RoutingStrategy",
+    # Interfaces
+    "IModelProvider",
+    "IModelRouter",
+    # Data types
+    "ModelCapability",
+    "ModelProvider",
+    "ModelResponse",
+]
+
+# Version and metadata
+__version__ = "1.0.0"
+__phase__ = "1"
+__status__ = "Core Infrastructure Complete"

claude_mpm/services/model/base_provider.py

@@ -0,0 +1,365 @@
+"""
+Base Model Provider Implementation for Claude MPM Framework
+===========================================================
+
+WHY: Provides common functionality for all model providers, reducing
+duplication and ensuring consistent behavior across implementations.
+
+DESIGN DECISION: Abstract base class extends both BaseService and IModelProvider,
+providing service lifecycle management plus model-specific utilities.
+
+RESPONSIBILITIES:
+- Common error handling and logging
+- Task-specific prompt generation
+- Response formatting and validation
+- Performance metrics tracking
+- Retry logic for transient failures
+"""
+
+import asyncio
+import time
+from abc import abstractmethod
+from typing import Any, Dict, Optional
+
+from claude_mpm.core.logger import get_logger
+from claude_mpm.services.core.base import BaseService
+from claude_mpm.services.core.interfaces.model import (
+    IModelProvider,
+    ModelCapability,
+    ModelResponse,
+)
+
+
+class BaseModelProvider(BaseService, IModelProvider):
+    """
+    Abstract base class for model providers.
+
+    WHY: Centralizes common provider functionality like prompt generation,
+    error handling, and response formatting.
+
+    Usage:
+        class MyProvider(BaseModelProvider):
+            async def analyze_content(self, content, task, model=None, **kwargs):
+                prompt = self.get_task_prompt(task, content)
+                # Call provider API
+                return self.create_response(...)
+    """
+
+    # Task-specific prompt templates
+    TASK_PROMPTS: Dict[ModelCapability, str] = {
+        ModelCapability.SEO_ANALYSIS: """Analyze the following content for SEO effectiveness. Provide:
+1. Primary and secondary keywords identified
+2. Keyword density analysis
+3. Meta description recommendation
+4. Title tag optimization suggestions
+5. Content structure analysis (H1, H2, etc.)
+6. SEO score (0-100) with justification
+
+Content to analyze:
+{content}
+
+Provide your analysis in a structured format.""",
+        ModelCapability.READABILITY: """Analyze the readability of the following content. Provide:
+1. Readability score (Flesch-Kincaid or similar)
+2. Average sentence length
+3. Complex word count
+4. Grade level assessment
+5. Suggestions for improvement
+6. Overall readability rating (Easy/Medium/Hard)
+
+Content to analyze:
+{content}
+
+Provide your analysis in a structured format.""",
+        ModelCapability.GRAMMAR: """Perform a grammar and style check on the following content. Identify:
+1. Grammatical errors with corrections
+2. Spelling mistakes
+3. Punctuation issues
+4. Style inconsistencies
+5. Clarity improvements
+6. Overall quality score (0-100)
+
+Content to analyze:
+{content}
+
+Provide your analysis in a structured format.""",
+        ModelCapability.SUMMARIZATION: """Provide a comprehensive summary of the following content:
+1. Main topic and key points (3-5 bullet points)
+2. Supporting details
+3. Conclusions or recommendations
+4. One-sentence TL;DR
+
+Content to summarize:
+{content}
+
+Provide your summary in a structured format.""",
+        ModelCapability.KEYWORD_EXTRACTION: """Extract and analyze keywords from the following content:
+1. Primary keywords (top 5-10)
+2. Long-tail keyword phrases
+3. Semantic relationships between keywords
+4. Keyword relevance scores
+5. Suggested additional keywords
+
+Content to analyze:
+{content}
+
+Provide your keyword analysis in a structured format.""",
+        ModelCapability.ACCESSIBILITY: """Analyze the accessibility of the following content:
+1. Language complexity level
+2. Inclusivity assessment
+3. Plain language recommendations
+4. Potential barriers for readers with disabilities
+5. WCAG compliance suggestions
+6. Accessibility score (0-100)
+
+Content to analyze:
+{content}
+
+Provide your analysis in a structured format.""",
+        ModelCapability.SENTIMENT: """Analyze the sentiment and tone of the following content:
+1. Overall sentiment (Positive/Negative/Neutral)
+2. Sentiment score (-1 to +1)
+3. Emotional tone detected
+4. Audience perception analysis
+5. Tone consistency evaluation
+
+Content to analyze:
+{content}
+
+Provide your analysis in a structured format.""",
+        ModelCapability.GENERAL: """Analyze the following content and provide:
+1. Overview and main themes
+2. Quality assessment
+3. Structural analysis
+4. Improvement suggestions
+5. Overall effectiveness rating
+
+Content to analyze:
+{content}
+
+Provide your analysis in a structured format.""",
+    }
+
+    def __init__(
+        self,
+        provider_name: str,
+        config: Optional[Dict[str, Any]] = None,
+    ):
+        """
+        Initialize base model provider.
+
+        Args:
+            provider_name: Name of the provider (e.g., "ollama", "claude")
+            config: Provider-specific configuration
+        """
+        super().__init__(service_name=f"{provider_name}_provider", config=config)
+        self.provider_name = provider_name
+        self.logger = get_logger(f"model.{provider_name}")
+        self._request_count = 0
+        self._error_count = 0
+        self._total_latency = 0.0
+
+    def get_task_prompt(self, task: ModelCapability, content: str) -> str:
+        """
+        Generate task-specific prompt.
+
+        WHY: Centralizes prompt engineering. Tasks require different analysis
+        approaches and output formats.
+
+        Args:
+            task: Type of analysis to perform
+            content: Content to analyze
+
+        Returns:
+            Formatted prompt string
+        """
+        template = self.TASK_PROMPTS.get(
+            task, self.TASK_PROMPTS[ModelCapability.GENERAL]
+        )
+        return template.format(content=content)
+
+    def create_response(
+        self,
+        success: bool,
+        model: str,
+        task: ModelCapability,
+        result: str = "",
+        metadata: Optional[Dict[str, Any]] = None,
+        error: Optional[str] = None,
+    ) -> ModelResponse:
+        """
+        Create standardized model response.
+
+        WHY: Ensures consistent response format across all providers.
+
+        Args:
+            success: Whether operation succeeded
+            model: Model used
+            task: Task performed
+            result: Analysis result
+            metadata: Additional metadata
+            error: Error message if failed
+
+        Returns:
+            ModelResponse object
+        """
+        return ModelResponse(
+            success=success,
+            provider=self.provider_name,
+            model=model,
+            task=task.value,
+            result=result,
+            metadata=metadata or {},
+            error=error,
+        )
+
+    async def analyze_with_retry(
+        self,
+        analyze_func,
+        content: str,
+        task: ModelCapability,
+        model: Optional[str] = None,
+        max_retries: int = 3,
+        **kwargs,
+    ) -> ModelResponse:
+        """
+        Execute analysis with retry logic.
+
+        WHY: Handles transient failures (network issues, rate limits, etc.)
+        without requiring retry logic in each provider implementation.
+
+        Args:
+            analyze_func: Async function to call for analysis
+            content: Content to analyze
+            task: Task to perform
+            model: Optional model to use
+            max_retries: Maximum retry attempts
+            **kwargs: Additional arguments for analyze_func
+
+        Returns:
+            ModelResponse from successful attempt or final error
+        """
+        last_error = None
+
+        for attempt in range(max_retries):
+            try:
+                start_time = time.time()
+                response = await analyze_func(content, task, model, **kwargs)
+                latency = time.time() - start_time
+
+                # Track metrics
+                self._request_count += 1
+                self._total_latency += latency
+
+                if response.success:
+                    response.metadata["latency_seconds"] = latency
+                    response.metadata["attempt"] = attempt + 1
+                    self.log_debug(
+                        f"Analysis completed in {latency:.2f}s (attempt {attempt + 1})"
+                    )
+                    return response
+                last_error = response.error
+                self._error_count += 1
+
+            except Exception as e:
+                last_error = str(e)
+                self._error_count += 1
+                self.log_warning(
+                    f"Analysis attempt {attempt + 1} failed: {e}",
+                    exc_info=True,
+                )
+
+            # Wait before retry (exponential backoff)
+            if attempt < max_retries - 1:
+                wait_time = 2**attempt  # 1s, 2s, 4s
+                self.log_info(f"Retrying in {wait_time}s...")
+                await asyncio.sleep(wait_time)
+
+        # All retries failed
+        self.log_error(f"All {max_retries} attempts failed. Last error: {last_error}")
+        return self.create_response(
+            success=False,
+            model=model or "unknown",
+            task=task,
+            error=f"Failed after {max_retries} attempts: {last_error}",
+        )
+
+    def validate_content(self, content: str, max_length: Optional[int] = None) -> bool:
+        """
+        Validate content before analysis.
+
+        WHY: Prevents invalid requests and provides early error detection.
+
+        Args:
+            content: Content to validate
+            max_length: Optional maximum length in characters
+
+        Returns:
+            True if valid, False otherwise
+        """
+        if not content or not content.strip():
+            self.log_warning("Empty content provided for analysis")
+            return False
+
+        if max_length and len(content) > max_length:
+            self.log_warning(
+                f"Content length {len(content)} exceeds maximum {max_length}"
+            )
+            return False
+
+        return True
+
+    def get_metrics(self) -> Dict[str, Any]:
+        """
+        Get provider performance metrics.
+
+        Returns:
+            Dictionary of metrics (request count, error rate, avg latency)
+        """
+        avg_latency = (
+            self._total_latency / self._request_count if self._request_count > 0 else 0
+        )
+        error_rate = (
+            self._error_count / self._request_count if self._request_count > 0 else 0
+        )
+
+        return {
+            "provider": self.provider_name,
+            "request_count": self._request_count,
+            "error_count": self._error_count,
+            "error_rate": error_rate,
+            "avg_latency_seconds": avg_latency,
+        }
+
+    async def initialize(self) -> bool:
+        """
+        Initialize provider.
+
+        Subclasses should override to perform provider-specific setup.
+
+        Returns:
+            True if initialization successful
+        """
+        self.log_info(f"Initializing {self.provider_name} provider")
+        self._initialized = True
+        return True
+
+    async def shutdown(self) -> None:
+        """
+        Shutdown provider and cleanup resources.
+
+        Subclasses should override to perform provider-specific cleanup.
+        """
+        self.log_info(f"Shutting down {self.provider_name} provider")
+        self._shutdown = True
+
+    @abstractmethod
+    async def get_model_info(self, model: str) -> Dict[str, Any]:
+        """
+        Get model information.
+
+        Must be implemented by subclasses.
+        """
+
+
+__all__ = ["BaseModelProvider"]