empathy-framework 4.6.6__py3-none-any.whl → 4.7.0__py3-none-any.whl

empathy_llm_toolkit/commands/context.py

@@ -0,0 +1,375 @@
+"""Command Context
+
+Provides execution context for commands with access to hooks, context management,
+and learning modules.
+
+Architectural patterns inspired by everything-claude-code by Affaan Mustafa.
+See: https://github.com/affaan-m/everything-claude-code (MIT License)
+See: ACKNOWLEDGMENTS.md for full attribution.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from empathy_llm_toolkit.commands.models import CommandConfig, CommandResult
+
+if TYPE_CHECKING:
+    from empathy_llm_toolkit.context.manager import ContextManager
+    from empathy_llm_toolkit.hooks.config import HookEvent
+    from empathy_llm_toolkit.hooks.registry import HookRegistry
+    from empathy_llm_toolkit.learning.storage import LearnedSkillsStorage
+    from empathy_llm_toolkit.state import CollaborationState
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class CommandContext:
+    """Execution context for commands.
+
+    Provides access to framework components that commands may need:
+    - Hook registry for firing events
+    - Context manager for state preservation
+    - Learning storage for pattern access
+    - Collaboration state for user context
+
+    Example:
+        # Create context with all components
+        ctx = CommandContext(
+            user_id="user123",
+            hook_registry=hooks,
+            context_manager=context_mgr,
+            learning_storage=storage,
+            collaboration_state=state,
+        )
+
+        # Commands can access components
+        patterns = ctx.get_patterns_for_context()
+        ctx.fire_hook("PreCommand", {"command": "compact"})
+    """
+
+    user_id: str
+    hook_registry: HookRegistry | None = None
+    context_manager: ContextManager | None = None
+    learning_storage: LearnedSkillsStorage | None = None
+    collaboration_state: CollaborationState | None = None
+    project_root: Path | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def fire_hook(
+        self,
+        event: str | HookEvent,
+        context: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Fire a hook event.
+
+        Args:
+            event: Event type (string or HookEvent enum)
+            context: Additional context for the hook
+
+        Returns:
+            List of hook execution results
+
+        """
+        if self.hook_registry is None:
+            logger.debug("No hook registry available, skipping hook")
+            return []
+
+        from empathy_llm_toolkit.hooks.config import HookEvent
+
+        # Convert string to enum if needed
+        if isinstance(event, str):
+            try:
+                event = HookEvent(event)
+            except ValueError:
+                logger.warning("Unknown hook event: %s", event)
+                return []
+
+        hook_context = context or {}
+        hook_context["user_id"] = self.user_id
+
+        return self.hook_registry.fire_sync(event, hook_context)
+
+    def save_context_state(self) -> Path | None:
+        """Save current collaboration state for compaction.
+
+        Returns:
+            Path to saved state file or None
+
+        """
+        if self.context_manager is None:
+            logger.debug("No context manager available")
+            return None
+
+        if self.collaboration_state is None:
+            logger.debug("No collaboration state available")
+            return None
+
+        return self.context_manager.save_for_compaction(self.collaboration_state)
+
+    def restore_context_state(self) -> bool:
+        """Restore context state for user.
+
+        Returns:
+            True if state was restored
+
+        """
+        if self.context_manager is None:
+            logger.debug("No context manager available")
+            return False
+
+        state = self.context_manager.restore_state(self.user_id)
+        return state is not None
+
+    def get_patterns_for_context(
+        self,
+        max_patterns: int = 5,
+    ) -> str:
+        """Get learned patterns formatted for context injection.
+
+        Args:
+            max_patterns: Maximum patterns to include
+
+        Returns:
+            Formatted markdown string
+
+        """
+        if self.learning_storage is None:
+            return ""
+
+        return self.learning_storage.format_patterns_for_context(
+            self.user_id,
+            max_patterns=max_patterns,
+        )
+
+    def search_patterns(self, query: str) -> list[Any]:
+        """Search learned patterns.
+
+        Args:
+            query: Search query
+
+        Returns:
+            List of matching patterns
+
+        """
+        if self.learning_storage is None:
+            return []
+
+        return self.learning_storage.search_patterns(self.user_id, query)
+
+    def get_learning_summary(self) -> dict[str, Any]:
+        """Get learning summary for user.
+
+        Returns:
+            Summary dictionary
+
+        """
+        if self.learning_storage is None:
+            return {}
+
+        return self.learning_storage.get_summary(self.user_id)
+
+
+class CommandExecutor:
+    """Executes commands with proper hook integration.
+
+    Handles the lifecycle of command execution:
+    1. Fire PreCommand hook
+    2. Execute command logic
+    3. Fire PostCommand hook
+    4. Return result
+
+    Example:
+        executor = CommandExecutor(context)
+
+        # Execute a command
+        result = await executor.execute(compact_command)
+
+        # Check result
+        if result.success:
+            print(f"Output: {result.output}")
+    """
+
+    def __init__(self, context: CommandContext):
+        """Initialize the executor.
+
+        Args:
+            context: Command execution context
+
+        """
+        self.context = context
+
+    def execute(
+        self,
+        command: CommandConfig,
+        args: dict[str, Any] | None = None,
+    ) -> CommandResult:
+        """Execute a command.
+
+        Args:
+            command: Command configuration to execute
+            args: Additional arguments
+
+        Returns:
+            CommandResult with execution details
+
+        """
+        args = args or {}
+        start_time = time.time()
+        hooks_fired: list[str] = []
+        patterns_applied: list[str] = []
+
+        # Fire pre-command hook if configured
+        pre_hook = command.hooks.get("pre")
+        if pre_hook:
+            try:
+                self.context.fire_hook(
+                    pre_hook,
+                    {
+                        "command": command.name,
+                        "args": args,
+                    },
+                )
+                hooks_fired.append(f"pre:{pre_hook}")
+                logger.debug("Pre-command hook fired: %s", pre_hook)
+            except Exception as e:
+                logger.error("Pre-command hook failed: %s", e)
+
+        # Get relevant patterns
+        if self.context.learning_storage:
+            patterns = self.context.search_patterns(command.name)
+            patterns_applied = [p.pattern_id for p in patterns[:3]]
+
+        # The actual command execution happens in Claude
+        # This executor prepares the context and returns the command body
+        output = command.body
+
+        # Fire post-command hook if configured
+        post_hook = command.hooks.get("post")
+        if post_hook:
+            try:
+                self.context.fire_hook(
+                    post_hook,
+                    {
+                        "command": command.name,
+                        "args": args,
+                        "success": True,
+                    },
+                )
+                hooks_fired.append(f"post:{post_hook}")
+                logger.debug("Post-command hook fired: %s", post_hook)
+            except Exception as e:
+                logger.error("Post-command hook failed: %s", e)
+
+        duration_ms = (time.time() - start_time) * 1000
+
+        return CommandResult(
+            command_name=command.name,
+            success=True,
+            output=output,
+            duration_ms=duration_ms,
+            hooks_fired=hooks_fired,
+            patterns_applied=patterns_applied,
+        )
+
+    def prepare_command(
+        self,
+        command: CommandConfig,
+        args: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Prepare command for execution without running hooks.
+
+        Useful for getting command context before actual execution.
+
+        Args:
+            command: Command configuration
+            args: Additional arguments
+
+        Returns:
+            Dictionary with prepared command context
+
+        """
+        args = args or {}
+
+        # Get relevant patterns
+        patterns_context = ""
+        if self.context.learning_storage:
+            patterns_context = self.context.get_patterns_for_context(max_patterns=3)
+
+        return {
+            "command": command.name,
+            "description": command.description,
+            "body": command.body,
+            "args": args,
+            "patterns_context": patterns_context,
+            "user_id": self.context.user_id,
+            "has_hooks": bool(command.hooks),
+        }
+
+
+def create_command_context(
+    user_id: str,
+    project_root: str | Path | None = None,
+    enable_hooks: bool = True,
+    enable_learning: bool = True,
+    enable_context: bool = True,
+) -> CommandContext:
+    """Create a CommandContext with available components.
+
+    Factory function that creates a context with the requested
+    components, handling import errors gracefully.
+
+    Args:
+        user_id: User identifier
+        project_root: Project root directory
+        enable_hooks: Enable hook integration
+        enable_learning: Enable learning integration
+        enable_context: Enable context management
+
+    Returns:
+        Configured CommandContext
+
+    """
+    hook_registry = None
+    context_manager = None
+    learning_storage = None
+
+    if enable_hooks:
+        try:
+            from empathy_llm_toolkit.hooks.registry import HookRegistry
+
+            hook_registry = HookRegistry()
+        except ImportError:
+            logger.debug("Hooks module not available")
+
+    if enable_context:
+        try:
+            from empathy_llm_toolkit.context.manager import ContextManager
+
+            context_manager = ContextManager()
+        except ImportError:
+            logger.debug("Context module not available")
+
+    if enable_learning:
+        try:
+            from empathy_llm_toolkit.learning.storage import LearnedSkillsStorage
+
+            learning_storage = LearnedSkillsStorage()
+        except ImportError:
+            logger.debug("Learning module not available")
+
+    return CommandContext(
+        user_id=user_id,
+        hook_registry=hook_registry,
+        context_manager=context_manager,
+        learning_storage=learning_storage,
+        project_root=Path(project_root) if project_root else None,
+    )

empathy_llm_toolkit/commands/loader.py

@@ -0,0 +1,301 @@
+"""Command Loader
+
+Loads commands from directory structures.
+
+Architectural patterns inspired by everything-claude-code by Affaan Mustafa.
+See: https://github.com/affaan-m/everything-claude-code (MIT License)
+See: ACKNOWLEDGMENTS.md for full attribution.
+
+Copyright 2025 Smart AI Memory, LLC
+Licensed under Fair Source 0.9
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Iterator
+from pathlib import Path
+
+from empathy_llm_toolkit.commands.models import CommandConfig
+from empathy_llm_toolkit.commands.parser import CommandParser
+
+logger = logging.getLogger(__name__)
+
+# Default commands directory relative to project root
+DEFAULT_COMMANDS_DIR = ".claude/commands"
+
+# Files to skip when scanning
+SKIP_FILES = frozenset(
+    {
+        "README.md",
+        "readme.md",
+        "CHANGELOG.md",
+        "changelog.md",
+        "INDEX.md",
+        "index.md",
+    }
+)
+
+
+class CommandLoader:
+    """Loader for discovering and loading command markdown files.
+
+    Scans directories for .md files with command definitions and loads
+    them into CommandConfig instances.
+
+    Example:
+        loader = CommandLoader()
+
+        # Load a single command
+        config = loader.load(".claude/commands/commit.md")
+
+        # Load all commands from a directory
+        commands = loader.load_directory(".claude/commands/")
+
+        # Discover and iterate commands lazily
+        for config in loader.discover(".claude/commands/"):
+            print(config.name)
+    """
+
+    def __init__(self, parser: CommandParser | None = None):
+        """Initialize the loader.
+
+        Args:
+            parser: Optional custom parser instance
+
+        """
+        self.parser = parser or CommandParser()
+
+    def load(self, file_path: str | Path) -> CommandConfig:
+        """Load a single command file.
+
+        Args:
+            file_path: Path to the command markdown file
+
+        Returns:
+            CommandConfig instance
+
+        """
+        return self.parser.parse_file(file_path)
+
+    def load_directory(
+        self,
+        directory: str | Path,
+        recursive: bool = False,
+    ) -> dict[str, CommandConfig]:
+        """Load all commands from a directory.
+
+        Args:
+            directory: Directory to scan for .md files
+            recursive: If True, scan subdirectories
+
+        Returns:
+            Dictionary mapping command names to configs
+
+        """
+        commands: dict[str, CommandConfig] = {}
+
+        for config in self.discover(directory, recursive=recursive):
+            if config.name in commands:
+                logger.warning(
+                    "Duplicate command name '%s' - keeping first occurrence",
+                    config.name,
+                )
+                continue
+            commands[config.name] = config
+
+        logger.info("Loaded %d command(s) from %s", len(commands), directory)
+        return commands
+
+    def discover(
+        self,
+        directory: str | Path,
+        recursive: bool = False,
+    ) -> Iterator[CommandConfig]:
+        """Discover and yield commands from a directory.
+
+        Args:
+            directory: Directory to scan
+            recursive: If True, scan subdirectories
+
+        Yields:
+            CommandConfig instances
+
+        """
+        directory = Path(directory)
+
+        if not directory.exists():
+            logger.warning("Commands directory not found: %s", directory)
+            return
+
+        if not directory.is_dir():
+            raise ValueError(f"Not a directory: {directory}")
+
+        # Get pattern for globbing
+        pattern = "**/*.md" if recursive else "*.md"
+
+        for file_path in sorted(directory.glob(pattern)):
+            if not file_path.is_file():
+                continue
+
+            # Skip non-command files
+            if file_path.name in SKIP_FILES:
+                continue
+            if file_path.name.startswith("_"):
+                continue
+            if file_path.name.startswith("."):
+                continue
+
+            try:
+                config = self.parser.parse_file(file_path)
+                yield config
+            except ValueError as e:
+                logger.warning("Skipping invalid command file %s: %s", file_path, e)
+            except FileNotFoundError as e:
+                logger.warning("Command file not found %s: %s", file_path, e)
+            except OSError as e:
+                logger.error("Error loading command file %s: %s", file_path, e)
+
+    def validate_directory(
+        self,
+        directory: str | Path,
+        recursive: bool = False,
+    ) -> dict[str, list[str]]:
+        """Validate all command files in a directory.
+
+        Args:
+            directory: Directory to validate
+            recursive: If True, scan subdirectories
+
+        Returns:
+            Dictionary mapping file paths to lists of errors
+
+        """
+        directory = Path(directory)
+        results: dict[str, list[str]] = {}
+
+        if not directory.exists():
+            return {str(directory): ["Directory not found"]}
+
+        pattern = "**/*.md" if recursive else "*.md"
+
+        for file_path in sorted(directory.glob(pattern)):
+            if not file_path.is_file():
+                continue
+            if file_path.name in SKIP_FILES:
+                continue
+            if file_path.name.startswith("_"):
+                continue
+
+            errors = self.parser.validate_file(file_path)
+            if errors:
+                results[str(file_path)] = errors
+
+        return results
+
+    def get_command_names(
+        self,
+        directory: str | Path,
+        recursive: bool = False,
+    ) -> list[str]:
+        """Get list of command names in a directory without fully loading.
+
+        Args:
+            directory: Directory to scan
+            recursive: If True, scan subdirectories
+
+        Returns:
+            List of command names
+
+        """
+        names: list[str] = []
+        for config in self.discover(directory, recursive=recursive):
+            names.append(config.name)
+        return names
+
+    def find_command_file(
+        self,
+        name: str,
+        directory: str | Path,
+    ) -> Path | None:
+        """Find a command file by name.
+
+        Args:
+            name: Command name to find
+            directory: Directory to search
+
+        Returns:
+            Path to command file or None
+
+        """
+        directory = Path(directory)
+
+        # Try exact match first
+        exact_path = directory / f"{name}.md"
+        if exact_path.exists():
+            return exact_path
+
+        # Search through files
+        for file_path in directory.glob("*.md"):
+            if file_path.stem == name:
+                return file_path
+
+        return None
+
+
+def load_commands_from_paths(
+    paths: list[str | Path],
+    parser: CommandParser | None = None,
+) -> dict[str, CommandConfig]:
+    """Load commands from multiple paths (files or directories).
+
+    Args:
+        paths: List of file or directory paths
+        parser: Optional custom parser
+
+    Returns:
+        Dictionary mapping command names to configs
+
+    """
+    loader = CommandLoader(parser=parser)
+    commands: dict[str, CommandConfig] = {}
+
+    for path in paths:
+        path = Path(path)
+
+        if path.is_file():
+            config = loader.load(path)
+            commands[config.name] = config
+        elif path.is_dir():
+            dir_commands = loader.load_directory(path)
+            commands.update(dir_commands)
+        else:
+            logger.warning("Path not found: %s", path)
+
+    return commands
+
+
+def get_default_commands_directory() -> Path:
+    """Get the default commands directory.
+
+    Searches for .claude/commands/ starting from current directory
+    and walking up to find project root.
+
+    Returns:
+        Path to commands directory
+
+    """
+    current = Path.cwd()
+
+    # Walk up looking for .claude/commands/
+    for parent in [current, *current.parents]:
+        commands_dir = parent / DEFAULT_COMMANDS_DIR
+        if commands_dir.exists():
+            return commands_dir
+
+        # Also check for .claude directory as project root indicator
+        if (parent / ".claude").exists():
+            return commands_dir
+
+    # Fall back to current directory
+    return current / DEFAULT_COMMANDS_DIR