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

claude_mpm/core/framework/processors/memory_processor.py

@@ -0,0 +1,230 @@
+"""Memory content processor for framework memory management."""
+
+from pathlib import Path
+from typing import Any, Dict, Set
+
+from claude_mpm.core.logging_utils import get_logger
+
+
+class MemoryProcessor:
+    """Processes and manages memory content for agents."""
+
+    def __init__(self):
+        """Initialize the memory processor."""
+        self.logger = get_logger("memory_processor")
+
+    def load_pm_memories(self) -> Dict[str, str]:
+        """Load PM memories from various locations.
+
+        Returns:
+            Dictionary with actual_memories content
+        """
+        memories = {}
+
+        # Check for project-specific PM memories (highest priority)
+        project_memory_file = Path.cwd() / ".claude-mpm" / "memories" / "PM_memories.md"
+        if project_memory_file.exists():
+            try:
+                content = project_memory_file.read_text()
+                memories["actual_memories"] = content
+                memories["memory_source"] = "project"
+                self.logger.info(
+                    f"Loaded PM memories from project: {project_memory_file}"
+                )
+                return memories
+            except Exception as e:
+                self.logger.error(f"Failed to load project PM memories: {e}")
+
+        # Check for user-specific PM memories (fallback)
+        user_memory_file = Path.home() / ".claude-mpm" / "memories" / "PM_memories.md"
+        if user_memory_file.exists():
+            try:
+                content = user_memory_file.read_text()
+                memories["actual_memories"] = content
+                memories["memory_source"] = "user"
+                self.logger.info(f"Loaded PM memories from user: {user_memory_file}")
+                return memories
+            except Exception as e:
+                self.logger.error(f"Failed to load user PM memories: {e}")
+
+        return memories
+
+    def load_agent_memories(self, deployed_agents: Set[str]) -> Dict[str, str]:
+        """Load memories for deployed agents.
+
+        Args:
+            deployed_agents: Set of deployed agent names
+
+        Returns:
+            Dictionary mapping agent names to their memory content
+        """
+        agent_memories = {}
+
+        # Define memory file search locations
+        memory_locations = [
+            Path.cwd() / ".claude-mpm" / "memories",  # Project memories
+            Path.home() / ".claude-mpm" / "memories",  # User memories
+        ]
+
+        for agent_name in deployed_agents:
+            memory_filename = f"{agent_name}_memories.md"
+
+            # Search for memory file in each location (project takes precedence)
+            for memory_dir in memory_locations:
+                memory_file = memory_dir / memory_filename
+                if memory_file.exists():
+                    try:
+                        content = memory_file.read_text()
+                        agent_memories[agent_name] = content
+                        self.logger.debug(
+                            f"Loaded memories for {agent_name} from {memory_file}"
+                        )
+                        break  # Use first found (project > user)
+                    except Exception as e:
+                        self.logger.error(
+                            f"Failed to load memories for {agent_name}: {e}"
+                        )
+
+        return agent_memories
+
+    def aggregate_memories(
+        self,
+        pm_memories: Dict[str, str],
+        agent_memories: Dict[str, str],
+    ) -> Dict[str, Any]:
+        """Aggregate all memories into a single structure.
+
+        Args:
+            pm_memories: PM memory content
+            agent_memories: Agent-specific memories
+
+        Returns:
+            Aggregated memory structure
+        """
+        result = {}
+
+        # Add PM memories
+        if pm_memories.get("actual_memories"):
+            result["actual_memories"] = pm_memories["actual_memories"]
+            result["memory_source"] = pm_memories.get("memory_source", "unknown")
+
+        # Add agent memories
+        if agent_memories:
+            result["agent_memories"] = agent_memories
+
+        return result
+
+    def format_memory_section(self, memories: Dict[str, Any]) -> str:
+        """Format memories into a section for instructions.
+
+        Args:
+            memories: Memory content dictionary
+
+        Returns:
+            Formatted memory section
+        """
+        sections = []
+
+        # Format PM memories
+        if memories.get("actual_memories"):
+            sections.append("\n\n## Current PM Memories\n\n")
+            sections.append(
+                "**The following are your accumulated memories and knowledge from this project:**\n\n"
+            )
+            sections.append(memories["actual_memories"])
+            sections.append("\n")
+
+        # Format agent memories
+        if memories.get("agent_memories"):
+            agent_memories = memories["agent_memories"]
+            if agent_memories:
+                sections.append("\n\n## Agent Memories\n\n")
+                sections.append(
+                    "**The following are accumulated memories from specialized agents:**\n\n"
+                )
+
+                for agent_name in sorted(agent_memories.keys()):
+                    memory_content = agent_memories[agent_name]
+                    if memory_content:
+                        formatted_name = agent_name.replace("_", " ").title()
+                        sections.append(f"### {formatted_name} Agent Memory\n\n")
+                        sections.append(memory_content)
+                        sections.append("\n\n")
+
+        return "".join(sections)
+
+    def deduplicate_memories(self, memories: Dict[str, str]) -> Dict[str, str]:
+        """Remove duplicate entries from memories.
+
+        Args:
+            memories: Raw memory content
+
+        Returns:
+            Deduplicated memories
+        """
+        deduplicated = {}
+
+        for key, content in memories.items():
+            if not content:
+                continue
+
+            # Split into lines and remove duplicates while preserving order
+            lines = content.split("\n")
+            seen = set()
+            unique_lines = []
+
+            for line in lines:
+                # Skip empty lines in deduplication
+                if not line.strip():
+                    unique_lines.append(line)
+                    continue
+
+                # Add non-duplicate lines
+                if line not in seen:
+                    seen.add(line)
+                    unique_lines.append(line)
+
+            deduplicated[key] = "\n".join(unique_lines)
+
+        return deduplicated
+
+    def migrate_legacy_memories(self) -> bool:
+        """Migrate memories from old .claude/ locations to new .claude-mpm/ locations.
+
+        Returns:
+            True if any migrations were performed
+        """
+        migrated = False
+
+        # Define migration paths
+        migrations = [
+            # Project memories
+            (
+                Path.cwd() / ".claude" / "memories" / "PM_memories.md",
+                Path.cwd() / ".claude-mpm" / "memories" / "PM_memories.md",
+            ),
+            # User memories
+            (
+                Path.home() / ".claude" / "memories" / "PM_memories.md",
+                Path.home() / ".claude-mpm" / "memories" / "PM_memories.md",
+            ),
+        ]
+
+        for old_path, new_path in migrations:
+            if old_path.exists() and not new_path.exists():
+                try:
+                    # Create new directory if needed
+                    new_path.parent.mkdir(parents=True, exist_ok=True)
+
+                    # Copy content
+                    content = old_path.read_text()
+                    new_path.write_text(content)
+
+                    self.logger.info(f"Migrated memories from {old_path} to {new_path}")
+                    migrated = True
+                except Exception as e:
+                    self.logger.error(
+                        f"Failed to migrate memories from {old_path}: {e}"
+                    )
+
+        return migrated

claude_mpm/core/framework/processors/metadata_processor.py

@@ -0,0 +1,146 @@
+"""Metadata extraction and processing for framework files."""
+
+import re
+import time
+from pathlib import Path
+from typing import Any, Dict, Optional, Tuple
+
+import yaml
+
+from claude_mpm.core.logging_utils import get_logger
+
+
+class MetadataProcessor:
+    """Processes and extracts metadata from framework files and agents."""
+
+    def __init__(self):
+        """Initialize the metadata processor."""
+        self.logger = get_logger("metadata_processor")
+
+    def extract_metadata_from_content(self, content: str) -> Dict[str, Optional[str]]:
+        """Extract metadata from content string.
+
+        Args:
+            content: Content to extract metadata from
+
+        Returns:
+            Dictionary with extracted metadata
+        """
+        metadata = {
+            "version": None,
+            "last_modified": None,
+        }
+
+        # Extract version
+        version_match = re.search(r"<!-- FRAMEWORK_VERSION: (\d+) -->", content)
+        if version_match:
+            metadata["version"] = version_match.group(1)
+            self.logger.debug(f"Extracted version: {metadata['version']}")
+
+        # Extract timestamp
+        timestamp_match = re.search(r"<!-- LAST_MODIFIED: ([^>]+) -->", content)
+        if timestamp_match:
+            metadata["last_modified"] = timestamp_match.group(1).strip()
+            self.logger.debug(f"Extracted last_modified: {metadata['last_modified']}")
+
+        return metadata
+
+    def parse_agent_metadata(self, agent_file: Path) -> Optional[Dict[str, Any]]:
+        """Parse agent metadata from deployed agent file.
+
+        Args:
+            agent_file: Path to deployed agent file
+
+        Returns:
+            Dictionary with agent metadata or None
+        """
+        try:
+            with agent_file.open() as f:
+                content = f.read()
+
+            # Default values
+            agent_data = {
+                "id": agent_file.stem,
+                "display_name": agent_file.stem.replace("_", " ")
+                .replace("-", " ")
+                .title(),
+                "description": "Specialized agent",
+                "file_path": str(agent_file),
+                "file_mtime": agent_file.stat().st_mtime,
+            }
+
+            # Extract YAML frontmatter if present
+            if content.startswith("---"):
+                end_marker = content.find("---", 3)
+                if end_marker > 0:
+                    frontmatter = content[3:end_marker]
+                    metadata = yaml.safe_load(frontmatter)
+                    if metadata:
+                        # Use name as ID for Task tool
+                        agent_data["id"] = metadata.get("name", agent_data["id"])
+                        agent_data["display_name"] = (
+                            metadata.get("name", agent_data["display_name"])
+                            .replace("-", " ")
+                            .title()
+                        )
+
+                        # Copy all metadata fields directly
+                        for key, value in metadata.items():
+                            if key not in ["name"]:  # Skip already processed fields
+                                agent_data[key] = value
+
+                        # IMPORTANT: Do NOT add spaces to tools field - it breaks deployment!
+                        # Tools must remain as comma-separated without spaces: "Read,Write,Edit"
+
+            return agent_data
+
+        except Exception as e:
+            self.logger.debug(f"Could not parse metadata from {agent_file}: {e}")
+            return None
+
+    def extract_cache_metadata(self, data: Any, cache_key: str) -> Tuple[Any, float]:
+        """Extract cache metadata for storage.
+
+        Args:
+            data: Data to cache
+            cache_key: Cache key for identification
+
+        Returns:
+            Tuple of (data, timestamp) for cache storage
+        """
+        return data, time.time()
+
+    def validate_cache_metadata(
+        self,
+        cached_data: Tuple[Any, float],
+        file_path: Optional[Path] = None,
+        ttl: float = 60.0,
+    ) -> bool:
+        """Validate cache metadata for freshness.
+
+        Args:
+            cached_data: Tuple of (data, timestamp) from cache
+            file_path: Optional file path to check modification time
+            ttl: Time-to-live in seconds
+
+        Returns:
+            True if cache is valid, False otherwise
+        """
+        try:
+            _data, cache_time = cached_data
+            current_time = time.time()
+
+            # Check TTL
+            if current_time - cache_time > ttl:
+                return False
+
+            # Check file modification time if provided
+            if file_path and file_path.exists():
+                file_mtime = file_path.stat().st_mtime
+                if file_mtime > cache_time:
+                    return False
+
+            return True
+        except Exception as e:
+            self.logger.debug(f"Cache validation failed: {e}")
+            return False

claude_mpm/core/framework/processors/template_processor.py

@@ -0,0 +1,244 @@
+"""JSON template processor for agent configurations."""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from claude_mpm.core.logging_utils import get_logger
+
+# Import resource handling for packaged installations
+try:
+    from importlib.resources import files
+except ImportError:
+    try:
+        from importlib_resources import files
+    except ImportError:
+        files = None
+
+
+class TemplateProcessor:
+    """Processes JSON template files for agent configurations."""
+
+    def __init__(self, framework_path: Optional[Path] = None):
+        """Initialize the template processor.
+
+        Args:
+            framework_path: Path to framework installation
+        """
+        self.logger = get_logger("template_processor")
+        self.framework_path = framework_path
+
+    def load_template(self, agent_name: str) -> Optional[Dict[str, Any]]:
+        """Load JSON template for an agent.
+
+        Args:
+            agent_name: Name of the agent
+
+        Returns:
+            Template data or None if not found
+        """
+        try:
+            # Check if we have a framework path
+            if not self.framework_path or self.framework_path == Path("__PACKAGED__"):
+                return self._load_packaged_template(agent_name)
+
+            # For development mode, load from filesystem
+            return self._load_filesystem_template(agent_name)
+
+        except Exception as e:
+            self.logger.debug(f"Could not load template for {agent_name}: {e}")
+            return None
+
+    def _load_packaged_template(self, agent_name: str) -> Optional[Dict[str, Any]]:
+        """Load template from packaged installation.
+
+        Args:
+            agent_name: Name of the agent
+
+        Returns:
+            Template data or None if not found
+        """
+        if not files:
+            return None
+
+        try:
+            templates_package = files("claude_mpm.agents.templates")
+            template_file = templates_package / f"{agent_name}.json"
+
+            if template_file.is_file():
+                template_content = template_file.read_text()
+                return json.loads(template_content)
+        except Exception as e:
+            self.logger.debug(f"Could not load packaged template for {agent_name}: {e}")
+
+        return None
+
+    def _load_filesystem_template(self, agent_name: str) -> Optional[Dict[str, Any]]:
+        """Load template from filesystem.
+
+        Args:
+            agent_name: Name of the agent
+
+        Returns:
+            Template data or None if not found
+        """
+        templates_dir = (
+            self.framework_path / "src" / "claude_mpm" / "agents" / "templates"
+        )
+
+        # Try exact match first
+        template_file = templates_dir / f"{agent_name}.json"
+        if template_file.exists():
+            with template_file.open() as f:
+                return json.load(f)
+
+        # Try alternative naming variations
+        alternative_names = self._get_alternative_names(agent_name)
+        for alt_name in alternative_names:
+            alt_file = templates_dir / f"{alt_name}.json"
+            if alt_file.exists():
+                with alt_file.open() as f:
+                    return json.load(f)
+
+        return None
+
+    def _get_alternative_names(self, agent_name: str) -> List[str]:
+        """Get alternative naming variations for an agent.
+
+        Args:
+            agent_name: Original agent name
+
+        Returns:
+            List of alternative names to try
+        """
+        # Remove duplicates by using a set
+        return list(
+            {
+                agent_name.replace("-", "_"),  # api-qa -> api_qa
+                agent_name.replace("_", "-"),  # api_qa -> api-qa
+                agent_name.replace("-", ""),  # api-qa -> apiqa
+                agent_name.replace("_", ""),  # api_qa -> apiqa
+                agent_name.replace("-agent", ""),  # research-agent -> research
+                agent_name.replace("_agent", ""),  # research_agent -> research
+                agent_name + "_agent",  # research -> research_agent
+                agent_name + "-agent",  # research -> research-agent
+            }
+        )
+
+    def extract_routing(
+        self, template_data: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """Extract routing information from template.
+
+        Args:
+            template_data: Template data
+
+        Returns:
+            Routing information or None
+        """
+        return template_data.get("routing")
+
+    def extract_memory_routing(
+        self, template_data: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """Extract memory routing information from template.
+
+        Args:
+            template_data: Template data
+
+        Returns:
+            Memory routing information or None
+        """
+        return template_data.get("memory_routing")
+
+    def extract_tools(self, template_data: Dict[str, Any]) -> str:
+        """Extract tools string from template data.
+
+        Args:
+            template_data: Template data
+
+        Returns:
+            Tools string for display
+        """
+        capabilities = template_data.get("capabilities", {})
+        tools = capabilities.get("tools", "*")
+
+        if tools == "*":
+            return "All Tools"
+        if isinstance(tools, list):
+            return ", ".join(tools) if tools else "Standard Tools"
+        if isinstance(tools, str):
+            return tools
+        return "Standard Tools"
+
+    def extract_metadata(self, template_data: Dict[str, Any]) -> Dict[str, Any]:
+        """Extract agent metadata from template.
+
+        Args:
+            template_data: Template data
+
+        Returns:
+            Dictionary with extracted metadata
+        """
+        metadata = template_data.get("metadata", {})
+        agent_id = template_data.get("agent_id", "unknown")
+
+        return {
+            "id": agent_id,
+            "display_name": metadata.get("name", agent_id.replace("_", " ").title()),
+            "description": metadata.get("description", f"Agent {agent_id}"),
+            "authority": metadata.get("authority"),
+            "primary_function": metadata.get("primary_function"),
+            "handoff_to": metadata.get("handoff_to"),
+            "model": template_data.get("model", {}).get("model"),
+            "tools": self.extract_tools(template_data),
+            "routing": self.extract_routing(template_data),
+            "memory_routing": self.extract_memory_routing(template_data),
+            "author": template_data.get("author", "unknown"),
+            "version": template_data.get("agent_version", "1.0.0"),
+        }
+
+    def process_local_templates(self) -> Dict[str, Dict[str, Any]]:
+        """Process all local JSON templates.
+
+        Returns:
+            Dictionary mapping agent IDs to processed metadata
+        """
+        local_agents = {}
+
+        # Check for local JSON templates in priority order
+        template_dirs = [
+            Path.cwd() / ".claude-mpm" / "agents",  # Project local agents
+            Path.home() / ".claude-mpm" / "agents",  # User local agents
+        ]
+
+        for priority, template_dir in enumerate(template_dirs):
+            if not template_dir.exists():
+                continue
+
+            for json_file in template_dir.glob("*.json"):
+                try:
+                    with json_file.open() as f:
+                        template_data = json.load(f)
+
+                    agent_metadata = self.extract_metadata(template_data)
+                    agent_id = agent_metadata["id"]
+
+                    # Skip if already found at higher priority
+                    if agent_id in local_agents:
+                        continue
+
+                    # Add local-specific fields
+                    agent_metadata["is_local"] = True
+                    agent_metadata["tier"] = "project" if priority == 0 else "user"
+                    agent_metadata["source_file"] = str(json_file)
+
+                    local_agents[agent_id] = agent_metadata
+                    self.logger.debug(
+                        f"Processed local template: {agent_id} from {template_dir}"
+                    )
+
+                except Exception as e:
+                    self.logger.warning(f"Failed to process template {json_file}: {e}")
+
+        return local_agents