attune-ai 2.0.0__py3-none-any.whl

attune_llm/hooks/config.py

@@ -0,0 +1,306 @@
+"""Hook Configuration Models
+
+Pydantic models for hook system configuration.
+Based on everything-claude-code hooks.json pattern.
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class HookEvent(str, Enum):
+    """Hook event types matching Claude Code lifecycle."""
+
+    PRE_TOOL_USE = "PreToolUse"
+    POST_TOOL_USE = "PostToolUse"
+    SESSION_START = "SessionStart"
+    SESSION_END = "SessionEnd"
+    PRE_COMPACT = "PreCompact"
+    POST_COMPACT = "PostCompact"
+    PRE_COMMAND = "PreCommand"
+    POST_COMMAND = "PostCommand"
+    STOP = "Stop"
+
+
+class HookType(str, Enum):
+    """Type of hook action."""
+
+    COMMAND = "command"  # Run a command/script
+    PYTHON = "python"  # Run a Python function
+    WEBHOOK = "webhook"  # Call a webhook URL
+
+
+class HookDefinition(BaseModel):
+    """Definition of a single hook action.
+
+    Example:
+        hook = HookDefinition(
+            type=HookType.PYTHON,
+            command="attune_llm.hooks.scripts.session_start:main",
+            description="Load previous context on session start"
+        )
+    """
+
+    type: HookType = Field(
+        default=HookType.PYTHON,
+        description="Type of hook action",
+    )
+    command: str = Field(
+        ...,
+        description="Command to run, Python module:function path, or webhook URL",
+    )
+    description: str = Field(
+        default="",
+        description="Human-readable description of what this hook does",
+    )
+    timeout: int = Field(
+        default=30,
+        ge=1,
+        le=300,
+        description="Timeout in seconds for hook execution",
+    )
+    async_execution: bool = Field(
+        default=False,
+        description="Run hook asynchronously (don't wait for completion)",
+    )
+    on_error: str = Field(
+        default="log",
+        description="Error handling: 'log', 'raise', or 'ignore'",
+    )
+
+
+class HookMatcher(BaseModel):
+    """Matcher for determining when a hook should fire.
+
+    Supports tool name matching, file path patterns, and custom conditions.
+
+    Example:
+        matcher = HookMatcher(
+            tool="Edit",
+            file_pattern=r"\\.(ts|tsx|js|jsx)$",
+            description="Match TypeScript/JavaScript file edits"
+        )
+    """
+
+    tool: str | None = Field(
+        default=None,
+        description="Tool name to match (e.g., 'Bash', 'Edit', 'Read')",
+    )
+    file_pattern: str | None = Field(
+        default=None,
+        description="Regex pattern to match file paths",
+    )
+    command_pattern: str | None = Field(
+        default=None,
+        description="Regex pattern to match command strings",
+    )
+    condition: str | None = Field(
+        default=None,
+        description="Custom condition expression",
+    )
+    match_all: bool = Field(
+        default=False,
+        description="If True, matches all events (wildcard)",
+    )
+    description: str = Field(
+        default="",
+        description="Human-readable description of match criteria",
+    )
+
+    def matches(self, context: dict[str, Any]) -> bool:
+        """Check if this matcher matches the given context.
+
+        Args:
+            context: Event context with keys like 'tool', 'file_path', 'command'
+
+        Returns:
+            True if matcher matches the context
+
+        """
+        import re
+
+        # Wildcard matches everything
+        if self.match_all:
+            return True
+
+        # Tool name matching
+        if self.tool and context.get("tool") != self.tool:
+            return False
+
+        # File path pattern matching
+        if self.file_pattern:
+            file_path = context.get("file_path", "")
+            if not re.search(self.file_pattern, file_path):
+                return False
+
+        # Command pattern matching
+        if self.command_pattern:
+            command = context.get("command", "")
+            if not re.search(self.command_pattern, command):
+                return False
+
+        return True
+
+
+class HookRule(BaseModel):
+    """A complete hook rule with matcher and actions.
+
+    Example:
+        rule = HookRule(
+            matcher=HookMatcher(tool="Edit", file_pattern=r"\\.py$"),
+            hooks=[HookDefinition(type=HookType.PYTHON, command="format_python")],
+            description="Auto-format Python files after edits"
+        )
+    """
+
+    matcher: HookMatcher = Field(
+        default_factory=lambda: HookMatcher(match_all=True),
+        description="Conditions for when this rule fires",
+    )
+    hooks: list[HookDefinition] = Field(
+        default_factory=list,
+        description="List of hooks to execute when matched",
+    )
+    enabled: bool = Field(
+        default=True,
+        description="Whether this rule is active",
+    )
+    priority: int = Field(
+        default=0,
+        description="Execution priority (higher = earlier)",
+    )
+    description: str = Field(
+        default="",
+        description="Human-readable description",
+    )
+
+
+class HookConfig(BaseModel):
+    """Complete hook configuration for an Empathy session.
+
+    Example YAML configuration:
+        hooks:
+          SessionStart:
+            - matcher:
+                match_all: true
+              hooks:
+                - type: python
+                  command: attune_llm.hooks.scripts.session_start:main
+                  description: Load previous context
+          PostToolUse:
+            - matcher:
+                tool: Edit
+                file_pattern: "\\.(py)$"
+              hooks:
+                - type: command
+                  command: "ruff format {file_path}"
+                  description: Auto-format Python files
+    """
+
+    hooks: dict[str, list[HookRule]] = Field(
+        default_factory=lambda: {event.value: [] for event in HookEvent},
+        description="Hooks organized by event type",
+    )
+    enabled: bool = Field(
+        default=True,
+        description="Global enable/disable for all hooks",
+    )
+    log_executions: bool = Field(
+        default=True,
+        description="Log hook executions for debugging",
+    )
+    default_timeout: int = Field(
+        default=30,
+        ge=1,
+        le=300,
+        description="Default timeout for hooks without explicit timeout",
+    )
+
+    def get_hooks_for_event(self, event: HookEvent) -> list[HookRule]:
+        """Get all hook rules for a specific event type.
+
+        Args:
+            event: The hook event type
+
+        Returns:
+            List of HookRule objects for this event, sorted by priority
+
+        """
+        rules = self.hooks.get(event.value, [])
+        return sorted(
+            [r for r in rules if r.enabled],
+            key=lambda r: -r.priority,
+        )
+
+    def add_hook(
+        self,
+        event: HookEvent,
+        hook: HookDefinition,
+        matcher: HookMatcher | None = None,
+        priority: int = 0,
+    ) -> None:
+        """Add a hook for an event.
+
+        Args:
+            event: Event type to hook
+            hook: Hook definition to add
+            matcher: Optional matcher (defaults to match_all)
+            priority: Execution priority
+
+        """
+        if event.value not in self.hooks:
+            self.hooks[event.value] = []
+
+        rule = HookRule(
+            matcher=matcher or HookMatcher(match_all=True),
+            hooks=[hook],
+            priority=priority,
+        )
+        self.hooks[event.value].append(rule)
+
+    @classmethod
+    def from_yaml(cls, yaml_path: str) -> "HookConfig":
+        """Load hook configuration from a YAML file.
+
+        Args:
+            yaml_path: Path to YAML configuration file
+
+        Returns:
+            HookConfig instance
+
+        """
+        from pathlib import Path
+
+        import yaml
+
+        config_file = Path(yaml_path)
+        if not config_file.exists():
+            return cls()
+
+        with open(config_file) as f:
+            data = yaml.safe_load(f) or {}
+
+        hooks_data = data.get("hooks", {})
+        return cls.model_validate({"hooks": hooks_data, **data})
+
+    def to_yaml(self, yaml_path: str) -> None:
+        """Save hook configuration to a YAML file.
+
+        Args:
+            yaml_path: Path to write YAML configuration
+
+        """
+        from pathlib import Path
+
+        import yaml
+
+        config_file = Path(yaml_path)
+        config_file.parent.mkdir(parents=True, exist_ok=True)
+
+        with open(config_file, "w") as f:
+            yaml.dump(self.model_dump(), f, default_flow_style=False)

attune_llm/hooks/executor.py

@@ -0,0 +1,289 @@
+"""Hook Executor
+
+Executes hook actions (commands, Python functions, webhooks).
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+import asyncio
+import importlib
+import logging
+import time
+from collections.abc import Callable
+from typing import Any
+
+from attune_llm.hooks.config import HookDefinition, HookType
+
+logger = logging.getLogger(__name__)
+
+
+class HookExecutor:
+    """Executor for running hook actions.
+
+    Supports three hook types:
+    - COMMAND: Run shell commands with variable substitution
+    - PYTHON: Import and call Python functions
+    - WEBHOOK: POST to webhook URLs
+
+    Example:
+        executor = HookExecutor()
+
+        # Execute a command hook
+        result = await executor.execute(
+            HookDefinition(type=HookType.COMMAND, command="echo {file_path}"),
+            context={"file_path": "/path/to/file.py"}
+        )
+    """
+
+    def __init__(self, python_handlers: dict[str, Callable] | None = None):
+        """Initialize the executor.
+
+        Args:
+            python_handlers: Map of handler IDs to Python callables
+
+        """
+        self._python_handlers = python_handlers or {}
+
+    async def execute(
+        self,
+        hook: HookDefinition,
+        context: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Execute a hook action.
+
+        Args:
+            hook: Hook definition to execute
+            context: Execution context with variables
+
+        Returns:
+            Execution result dictionary
+
+        """
+        start_time = time.time()
+
+        try:
+            if hook.async_execution:
+                # Fire and forget
+                asyncio.create_task(self._execute_internal(hook, context))
+                return {
+                    "success": True,
+                    "output": "Hook scheduled for async execution",
+                    "async": True,
+                    "duration_ms": 0,
+                }
+
+            result = await asyncio.wait_for(
+                self._execute_internal(hook, context),
+                timeout=hook.timeout,
+            )
+
+            duration_ms = (time.time() - start_time) * 1000
+            return {
+                "success": True,
+                "output": result,
+                "duration_ms": round(duration_ms, 2),
+            }
+
+        except asyncio.TimeoutError:
+            duration_ms = (time.time() - start_time) * 1000
+            error_msg = f"Hook timed out after {hook.timeout}s"
+            logger.warning("%s: %s", error_msg, hook.command)
+            return {
+                "success": False,
+                "error": error_msg,
+                "duration_ms": round(duration_ms, 2),
+            }
+
+        except Exception as e:
+            duration_ms = (time.time() - start_time) * 1000
+            logger.error("Hook execution failed: %s - %s", hook.command, e)
+            return {
+                "success": False,
+                "error": str(e),
+                "duration_ms": round(duration_ms, 2),
+            }
+
+    async def _execute_internal(
+        self,
+        hook: HookDefinition,
+        context: dict[str, Any],
+    ) -> Any:
+        """Internal execution logic.
+
+        Args:
+            hook: Hook definition
+            context: Execution context
+
+        Returns:
+            Hook output
+
+        """
+        if hook.type == HookType.COMMAND:
+            return await self._execute_command(hook.command, context)
+        elif hook.type == HookType.PYTHON:
+            return await self._execute_python(hook.command, context)
+        elif hook.type == HookType.WEBHOOK:
+            return await self._execute_webhook(hook.command, context)
+        else:
+            raise ValueError(f"Unknown hook type: {hook.type}")
+
+    async def _execute_command(
+        self,
+        command: str,
+        context: dict[str, Any],
+    ) -> str:
+        """Execute a shell command.
+
+        Args:
+            command: Command string with optional {var} placeholders
+            context: Variables for substitution
+
+        Returns:
+            Command output
+
+        """
+        # Substitute context variables
+        try:
+            formatted_command = command.format(**context)
+        except KeyError as e:
+            raise ValueError(f"Missing context variable for command: {e}")
+
+        logger.debug("Executing command: %s", formatted_command)
+
+        # Run command asynchronously
+        process = await asyncio.create_subprocess_shell(
+            formatted_command,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+
+        stdout, stderr = await process.communicate()
+
+        if process.returncode != 0:
+            error_output = stderr.decode().strip() or stdout.decode().strip()
+            raise RuntimeError(
+                f"Command failed with exit code {process.returncode}: {error_output}"
+            )
+
+        return stdout.decode().strip()
+
+    async def _execute_python(
+        self,
+        command: str,
+        context: dict[str, Any],
+    ) -> Any:
+        """Execute a Python function.
+
+        Args:
+            command: Either a handler ID or module.path:function format
+            context: Context passed as kwargs to function
+
+        Returns:
+            Function return value
+
+        """
+        # Check if it's a registered handler ID
+        if command in self._python_handlers:
+            handler = self._python_handlers[command]
+            return await self._call_handler(handler, context)
+
+        # Otherwise, import module:function
+        if ":" not in command:
+            raise ValueError(f"Python hook must be 'module.path:function' format: {command}")
+
+        module_path, func_name = command.rsplit(":", 1)
+
+        try:
+            module = importlib.import_module(module_path)
+            handler = getattr(module, func_name)
+        except (ImportError, AttributeError) as e:
+            raise ValueError(f"Failed to import hook function: {command}") from e
+
+        return await self._call_handler(handler, context)
+
+    async def _call_handler(
+        self,
+        handler: Callable,
+        context: dict[str, Any],
+    ) -> Any:
+        """Call a handler function (sync or async).
+
+        Args:
+            handler: Callable to invoke
+            context: Context passed as kwargs
+
+        Returns:
+            Handler return value
+
+        """
+        if asyncio.iscoroutinefunction(handler):
+            return await handler(**context)
+        else:
+            # Run sync function in thread pool
+            loop = asyncio.get_event_loop()
+            return await loop.run_in_executor(None, lambda: handler(**context))
+
+    async def _execute_webhook(
+        self,
+        url: str,
+        context: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Execute a webhook call.
+
+        Args:
+            url: Webhook URL
+            context: JSON payload to send
+
+        Returns:
+            Response data
+
+        """
+        try:
+            import aiohttp
+        except ImportError:
+            raise ImportError("aiohttp required for webhook hooks: pip install aiohttp")
+
+        logger.debug("Calling webhook: %s", url)
+
+        async with aiohttp.ClientSession() as session:
+            async with session.post(
+                url,
+                json=context,
+                headers={"Content-Type": "application/json"},
+            ) as response:
+                if response.status >= 400:
+                    text = await response.text()
+                    raise RuntimeError(f"Webhook failed with status {response.status}: {text}")
+
+                try:
+                    return await response.json()
+                except Exception:
+                    return {"status": response.status, "text": await response.text()}
+
+
+class HookExecutorSync:
+    """Synchronous wrapper for HookExecutor.
+
+    For use in contexts where async is not available.
+    """
+
+    def __init__(self, python_handlers: dict[str, Callable] | None = None):
+        self._executor = HookExecutor(python_handlers)
+
+    def execute(
+        self,
+        hook: HookDefinition,
+        context: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Execute a hook synchronously.
+
+        Args:
+            hook: Hook definition
+            context: Execution context
+
+        Returns:
+            Execution result
+
+        """
+        return asyncio.run(self._executor.execute(hook, context))