claude-mpm 3.4.10__py3-none-any.whl → 5.4.55__py3-none-any.whl

claude_mpm/core/framework/formatters/context_generator.py

@@ -0,0 +1,185 @@
+"""Temporal and user context generator for framework instructions."""
+
+import getpass
+import locale
+import os
+import platform
+import time as time_module
+from datetime import datetime, timezone
+from pathlib import Path
+
+from claude_mpm.core.logging_utils import get_logger
+
+
+class ContextGenerator:
+    """Generates temporal and user context for better PM awareness."""
+
+    def __init__(self):
+        """Initialize the context generator."""
+        self.logger = get_logger("context_generator")
+
+    def generate_temporal_user_context(self) -> str:
+        """Generate enhanced temporal and user context for better PM awareness.
+
+        Returns:
+            Formatted context string with datetime, user, and system information
+        """
+        context_lines = ["\n\n## Temporal & User Context\n"]
+
+        try:
+            # Get current datetime with timezone awareness
+            now = datetime.now(timezone.utc)
+
+            # Try to get timezone info - fallback to UTC offset if timezone name not available
+            try:
+                if hasattr(time_module, "tzname"):
+                    tz_name = time_module.tzname[time_module.daylight]
+                    tz_offset = time_module.strftime("%z")
+                    if tz_offset:
+                        # Format UTC offset properly (e.g., -0800 to -08:00)
+                        tz_offset = (
+                            f"{tz_offset[:3]}:{tz_offset[3:]}"
+                            if len(tz_offset) >= 4
+                            else tz_offset
+                        )
+                        tz_info = f"{tz_name} (UTC{tz_offset})"
+                    else:
+                        tz_info = tz_name
+                else:
+                    tz_info = "Local Time"
+            except Exception:
+                tz_info = "Local Time"
+
+            # Format datetime components
+            date_str = now.strftime("%Y-%m-%d")
+            time_str = now.strftime("%H:%M:%S")
+            day_name = now.strftime("%A")
+
+            context_lines.append(
+                f"**Current DateTime**: {date_str} {time_str} {tz_info}\n"
+            )
+            context_lines.append(f"**Day**: {day_name}\n")
+
+        except Exception as e:
+            # Fallback to basic date if enhanced datetime fails
+            self.logger.debug(f"Error generating enhanced datetime context: {e}")
+            context_lines.append(
+                f"**Today's Date**: {datetime.now(timezone.utc).strftime('%Y-%m-%d')}\n"
+            )
+
+        # Get user information
+        self._add_user_context(context_lines)
+
+        # Get system information
+        self._add_system_context(context_lines)
+
+        # Get environment information
+        self._add_environment_context(context_lines)
+
+        # Add instruction for applying context
+        context_lines.append(
+            "\nApply temporal and user awareness to all tasks, "
+            "decisions, and interactions.\n"
+        )
+        context_lines.append(
+            "Use this context for personalized responses and "
+            "time-sensitive operations.\n"
+        )
+
+        return "".join(context_lines)
+
+    def _add_user_context(self, context_lines: list) -> None:
+        """Add user information to context.
+
+        Args:
+            context_lines: List to append context lines to
+        """
+        try:
+            # Get user information with safe fallbacks
+            username = None
+
+            # Try multiple methods to get username
+            methods = [
+                lambda: os.environ.get("USER"),
+                lambda: os.environ.get("USERNAME"),  # Windows fallback
+                lambda: getpass.getuser(),
+            ]
+
+            for method in methods:
+                try:
+                    username = method()
+                    if username:
+                        break
+                except Exception:
+                    continue
+
+            if username:
+                context_lines.append(f"**User**: {username}\n")
+
+                # Add home directory if available
+                try:
+                    home_dir = Path("~").expanduser()
+                    if home_dir and home_dir != "~":
+                        context_lines.append(f"**Home Directory**: {home_dir}\n")
+                except Exception:
+                    pass
+
+        except Exception as e:
+            # User detection is optional, don't fail
+            self.logger.debug(f"Could not detect user information: {e}")
+
+    def _add_system_context(self, context_lines: list) -> None:
+        """Add system information to context.
+
+        Args:
+            context_lines: List to append context lines to
+        """
+        try:
+            # Get system information
+            system_info = platform.system()
+            if system_info:
+                # Enhance system name for common platforms
+                system_names = {
+                    "Darwin": "Darwin (macOS)",
+                    "Linux": "Linux",
+                    "Windows": "Windows",
+                }
+                system_display = system_names.get(system_info, system_info)
+                context_lines.append(f"**System**: {system_display}\n")
+
+                # Add platform version if available
+                try:
+                    platform_version = platform.release()
+                    if platform_version:
+                        context_lines.append(
+                            f"**System Version**: {platform_version}\n"
+                        )
+                except Exception:
+                    pass
+
+        except Exception as e:
+            # System info is optional
+            self.logger.debug(f"Could not detect system information: {e}")
+
+    def _add_environment_context(self, context_lines: list) -> None:
+        """Add environment information to context.
+
+        Args:
+            context_lines: List to append context lines to
+        """
+        try:
+            # Add current working directory
+            cwd = Path.cwd()
+            if cwd:
+                context_lines.append(f"**Working Directory**: {cwd}\n")
+        except Exception:
+            pass
+
+        try:
+            # Add locale information if available
+            current_locale = locale.getlocale()
+            if current_locale and current_locale[0]:
+                context_lines.append(f"**Locale**: {current_locale[0]}\n")
+        except Exception:
+            # Locale is optional
+            pass

claude_mpm/core/framework/loaders/__init__.py

@@ -0,0 +1,13 @@
+"""Framework loaders for handling various types of file and content loading."""
+
+from .agent_loader import AgentLoader
+from .file_loader import FileLoader
+from .instruction_loader import InstructionLoader
+from .packaged_loader import PackagedLoader
+
+__all__ = [
+    "AgentLoader",
+    "FileLoader",
+    "InstructionLoader",
+    "PackagedLoader",
+]

claude_mpm/core/framework/loaders/agent_loader.py

@@ -0,0 +1,213 @@
+"""Loader for agent discovery and management."""
+
+from pathlib import Path
+from typing import Any, Dict, Optional, Set, Tuple
+
+from claude_mpm.core.logging_utils import get_logger
+
+
+class AgentLoader:
+    """Handles agent discovery and loading from various sources."""
+
+    def __init__(self, framework_path: Optional[Path] = None):
+        """Initialize the agent loader.
+
+        Args:
+            framework_path: Path to framework installation
+        """
+        self.logger = get_logger("agent_loader")
+        self.framework_path = framework_path
+
+    def get_deployed_agents(self) -> Set[str]:
+        """
+        Get a set of deployed agent names from .claude/agents/ directories.
+
+        Returns:
+            Set of agent names (file stems) that are deployed
+        """
+        self.logger.debug("Scanning for deployed agents")
+        deployed = set()
+
+        # Check multiple locations for deployed agents
+        agents_dirs = [
+            Path.cwd() / ".claude" / "agents",  # Project-specific agents
+            Path.home() / ".claude" / "agents",  # User's system agents
+        ]
+
+        for agents_dir in agents_dirs:
+            if agents_dir.exists():
+                for agent_file in agents_dir.glob("*.md"):
+                    if not agent_file.name.startswith("."):
+                        # Use stem to get agent name without extension
+                        deployed.add(agent_file.stem)
+                        self.logger.debug(
+                            f"Found deployed agent: {agent_file.stem} in {agents_dir}"
+                        )
+
+        self.logger.debug(f"Total deployed agents found: {len(deployed)}")
+        return deployed
+
+    def load_single_agent(
+        self, agent_file: Path
+    ) -> Tuple[Optional[str], Optional[str]]:
+        """
+        Load a single agent file.
+
+        Args:
+            agent_file: Path to the agent file
+
+        Returns:
+            Tuple of (agent_name, agent_content) or (None, None) on failure
+        """
+        try:
+            agent_name = agent_file.stem
+            # Skip README files
+            if agent_name.upper() == "README":
+                return None, None
+            content = agent_file.read_text()
+            self.logger.debug(f"Loaded agent: {agent_name}")
+            return agent_name, content
+        except Exception as e:
+            self.logger.error(f"Failed to load agent {agent_file}: {e}")
+            return None, None
+
+    def load_agents_directory(
+        self,
+        agents_dir: Optional[Path],
+        templates_dir: Optional[Path] = None,
+        main_dir: Optional[Path] = None,
+    ) -> Dict[str, str]:
+        """
+        Load agent definitions from the appropriate directory.
+
+        Args:
+            agents_dir: Primary agents directory to load from
+            templates_dir: Templates directory path
+            main_dir: Main agents directory path
+
+        Returns:
+            Dictionary mapping agent names to their content
+        """
+        agents = {}
+
+        if not agents_dir or not agents_dir.exists():
+            return agents
+
+        # Load all agent files
+        for agent_file in agents_dir.glob("*.md"):
+            agent_name, agent_content = self.load_single_agent(agent_file)
+            if agent_name and agent_content:
+                agents[agent_name] = agent_content
+
+        # If we used templates dir, also check main dir for base_agent.md
+        if (
+            agents_dir == templates_dir
+            and main_dir
+            and main_dir.exists()
+            and "base_agent" not in agents
+        ):
+            base_agent_file = main_dir / "base_agent.md"
+            if base_agent_file.exists():
+                agent_name, agent_content = self.load_single_agent(base_agent_file)
+                if agent_name and agent_content:
+                    agents[agent_name] = agent_content
+
+        return agents
+
+    def discover_local_json_templates(self) -> Dict[str, Dict[str, Any]]:
+        """Discover local JSON agent templates.
+
+        NOTE: This method is kept for backward compatibility but is deprecated.
+        The new architecture uses SOURCE (~/.claude-mpm/cache/agents/)
+        and DEPLOYMENT (.claude/agents/) locations only.
+
+        Returns:
+            Dictionary mapping agent IDs to agent metadata
+        """
+        import json
+
+        local_agents = {}
+
+        # Check for local JSON templates in priority order
+        # NOTE: These directories are deprecated in the simplified architecture
+        template_dirs = [
+            Path.cwd() / ".claude-mpm" / "agents",  # Deprecated: Project local agents
+            Path.home() / ".claude-mpm" / "agents",  # Deprecated: 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)
+
+                    # Extract agent metadata
+                    agent_id = template_data.get("agent_id", json_file.stem)
+
+                    # Skip if already found at higher priority
+                    if agent_id in local_agents:
+                        continue
+
+                    # Extract metadata
+                    metadata = template_data.get("metadata", {})
+
+                    # Build agent data in expected format
+                    agent_data = {
+                        "id": agent_id,
+                        "display_name": metadata.get(
+                            "name", agent_id.replace("_", " ").title()
+                        ),
+                        "description": metadata.get(
+                            "description", f"Local {agent_id} agent"
+                        ),
+                        "tools": self._extract_tools_from_template(template_data),
+                        "is_local": True,
+                        "tier": "project" if priority == 0 else "user",
+                        "author": template_data.get("author", "local"),
+                        "version": template_data.get("agent_version", "1.0.0"),
+                    }
+
+                    # Add routing data if present
+                    if "routing" in template_data:
+                        agent_data["routing"] = template_data["routing"]
+
+                    # Add memory routing if present
+                    if "memory_routing" in template_data:
+                        agent_data["memory_routing"] = template_data["memory_routing"]
+
+                    local_agents[agent_id] = agent_data
+                    self.logger.debug(
+                        f"Discovered local JSON agent: {agent_id} from {template_dir}"
+                    )
+
+                except Exception as e:
+                    self.logger.warning(
+                        f"Failed to parse local JSON template {json_file}: {e}"
+                    )
+
+        return local_agents
+
+    def _extract_tools_from_template(self, template_data: Dict[str, Any]) -> str:
+        """Extract tools string from template data.
+
+        Args:
+            template_data: JSON 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):
+            if "," in tools:
+                return tools
+            return tools
+        return "Standard Tools"

claude_mpm/core/framework/loaders/file_loader.py

@@ -0,0 +1,176 @@
+"""File loading utilities for the framework."""
+
+import logging
+import re
+from pathlib import Path
+from typing import Optional
+
+from claude_mpm.core.logging_utils import get_logger
+
+
+class FileLoader:
+    """Handles file I/O operations for the framework."""
+
+    def __init__(self):
+        """Initialize the file loader."""
+        self.logger = get_logger("file_loader")
+        self.framework_version: Optional[str] = None
+        self.framework_last_modified: Optional[str] = None
+
+    def try_load_file(self, file_path: Path, file_type: str) -> Optional[str]:
+        """
+        Try to load a file with error handling.
+
+        Args:
+            file_path: Path to the file to load
+            file_type: Description of file type for logging
+
+        Returns:
+            File content if successful, None otherwise
+        """
+        try:
+            content = file_path.read_text()
+            if self.logger.isEnabledFor(logging.INFO):
+                self.logger.info(f"Loaded {file_type} from: {file_path}")
+
+            # Extract metadata if present
+            self._extract_metadata(content, file_path)
+            return content
+        except Exception as e:
+            if self.logger.isEnabledFor(logging.ERROR):
+                self.logger.error(f"Failed to load {file_type}: {e}")
+            return None
+
+    def _extract_metadata(self, content: str, file_path: Path) -> None:
+        """Extract metadata from file content.
+
+        Args:
+            content: File content to extract metadata from
+            file_path: Path to the file (for context)
+        """
+        # Extract version
+        version_match = re.search(r"<!-- FRAMEWORK_VERSION: (\d+) -->", content)
+        if version_match:
+            version = version_match.group(1)  # Keep as string to preserve leading zeros
+            self.logger.info(f"Framework version: {version}")
+            # Store framework version if this is the main INSTRUCTIONS.md
+            if "INSTRUCTIONS.md" in str(file_path):
+                self.framework_version = version
+
+        # Extract modification timestamp
+        timestamp_match = re.search(r"<!-- LAST_MODIFIED: ([^>]+) -->", content)
+        if timestamp_match:
+            timestamp = timestamp_match.group(1).strip()
+            self.logger.info(f"Last modified: {timestamp}")
+            # Store timestamp if this is the main INSTRUCTIONS.md
+            if "INSTRUCTIONS.md" in str(file_path):
+                self.framework_last_modified = timestamp
+
+    def _load_tier_file(
+        self,
+        filename: str,
+        current_dir: Path,
+        framework_path: Optional[Path] = None,
+        include_system: bool = False,
+    ) -> tuple[Optional[str], Optional[str]]:
+        """Load file with tier precedence: project → user → system.
+
+        Args:
+            filename: Name of file to load (e.g., "INSTRUCTIONS.md")
+            current_dir: Current working directory for project-level
+            framework_path: Path to framework installation for system-level
+            include_system: Whether to check system-level path
+
+        Returns:
+            Tuple of (content, level) where level is 'project', 'user', 'system', or None
+        """
+        # Check project-level (highest priority)
+        project_path = current_dir / ".claude-mpm" / filename
+        if project_path.exists():
+            loaded_content = self.try_load_file(
+                project_path, f"project-specific {filename}"
+            )
+            if loaded_content:
+                self.logger.info(f"Using project-specific {filename} from .claude-mpm/")
+                return loaded_content, "project"
+
+        # Check user-level (medium priority)
+        user_path = Path.home() / ".claude-mpm" / filename
+        if user_path.exists():
+            loaded_content = self.try_load_file(user_path, f"user-specific {filename}")
+            if loaded_content:
+                self.logger.info(f"Using user-specific {filename} from ~/.claude-mpm/")
+                return loaded_content, "user"
+
+        # Check system-level (lowest priority)
+        if include_system and framework_path and framework_path != Path("__PACKAGED__"):
+            system_path = framework_path / "src" / "claude_mpm" / "agents" / filename
+            if system_path.exists():
+                loaded_content = self.try_load_file(system_path, f"system {filename}")
+                if loaded_content:
+                    self.logger.info(f"Using system {filename}")
+                    return loaded_content, "system"
+
+        return None, None
+
+    def load_instructions_file(
+        self, current_dir: Path
+    ) -> tuple[Optional[str], Optional[str]]:
+        """
+        Load custom INSTRUCTIONS.md from .claude-mpm directories.
+
+        Precedence (highest to lowest):
+        1. Project-specific: ./.claude-mpm/INSTRUCTIONS.md
+        2. User-specific: ~/.claude-mpm/INSTRUCTIONS.md
+
+        Args:
+            current_dir: Current working directory
+
+        Returns:
+            Tuple of (content, level) where level is 'project', 'user', or None
+        """
+        return self._load_tier_file("INSTRUCTIONS.md", current_dir)
+
+    def load_workflow_file(
+        self, current_dir: Path, framework_path: Path
+    ) -> tuple[Optional[str], Optional[str]]:
+        """
+        Load WORKFLOW.md from various locations.
+
+        Precedence (highest to lowest):
+        1. Project-specific: ./.claude-mpm/WORKFLOW.md
+        2. User-specific: ~/.claude-mpm/WORKFLOW.md
+        3. System default: framework/agents/WORKFLOW.md
+
+        Args:
+            current_dir: Current working directory
+            framework_path: Path to framework installation
+
+        Returns:
+            Tuple of (content, level) where level is 'project', 'user', 'system', or None
+        """
+        return self._load_tier_file(
+            "WORKFLOW.md", current_dir, framework_path, include_system=True
+        )
+
+    def load_memory_file(
+        self, current_dir: Path, framework_path: Path
+    ) -> tuple[Optional[str], Optional[str]]:
+        """
+        Load MEMORY.md from various locations.
+
+        Precedence (highest to lowest):
+        1. Project-specific: ./.claude-mpm/MEMORY.md
+        2. User-specific: ~/.claude-mpm/MEMORY.md
+        3. System default: framework/agents/MEMORY.md
+
+        Args:
+            current_dir: Current working directory
+            framework_path: Path to framework installation
+
+        Returns:
+            Tuple of (content, level) where level is 'project', 'user', 'system', or None
+        """
+        return self._load_tier_file(
+            "MEMORY.md", current_dir, framework_path, include_system=True
+        )