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

empathy_llm_toolkit/hooks/registry.py

@@ -0,0 +1,302 @@
+"""Hook Registry
+
+Central registry for managing and dispatching hooks by event type.
+
+Copyright 2025 Smart-AI-Memory
+Licensed under Fair Source License 0.9
+"""
+
+import logging
+from collections.abc import Callable
+from typing import Any
+
+from empathy_llm_toolkit.hooks.config import (
+    HookConfig,
+    HookDefinition,
+    HookEvent,
+    HookMatcher,
+    HookRule,
+    HookType,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class HookRegistry:
+    """Central registry for hook management and dispatch.
+
+    The registry handles:
+    - Loading hook configuration
+    - Matching events to hooks
+    - Dispatching hooks to the executor
+    - Tracking hook execution results
+
+    Example:
+        registry = HookRegistry()
+        registry.load_config(config)
+
+        # Register a Python function hook
+        registry.register(
+            event=HookEvent.SESSION_START,
+            handler=my_session_start_handler,
+            description="Initialize session state"
+        )
+
+        # Fire hooks for an event
+        results = await registry.fire(
+            HookEvent.SESSION_START,
+            context={"session_id": "abc123"}
+        )
+    """
+
+    def __init__(self, config: HookConfig | None = None):
+        """Initialize the hook registry.
+
+        Args:
+            config: Optional hook configuration to load
+
+        """
+        self.config = config or HookConfig()
+        self._python_handlers: dict[str, Callable] = {}
+        self._execution_log: list[dict[str, Any]] = []
+
+    def load_config(self, config: HookConfig) -> None:
+        """Load or replace hook configuration.
+
+        Args:
+            config: New hook configuration
+
+        """
+        self.config = config
+        logger.info("Loaded hook configuration with %d event types", len(config.hooks))
+
+    def register(
+        self,
+        event: HookEvent,
+        handler: Callable[..., Any],
+        description: str = "",
+        matcher: HookMatcher | None = None,
+        priority: int = 0,
+    ) -> str:
+        """Register a Python function as a hook handler.
+
+        Args:
+            event: Event type to hook
+            handler: Python callable to execute
+            description: Human-readable description
+            matcher: Optional matcher for conditional execution
+            priority: Execution priority (higher = earlier)
+
+        Returns:
+            Handler ID for later reference
+
+        """
+        # Generate unique handler ID
+        handler_id = f"{event.value}_{handler.__name__}_{id(handler)}"
+        self._python_handlers[handler_id] = handler
+
+        # Create hook definition pointing to the handler
+        hook_def = HookDefinition(
+            type=HookType.PYTHON,
+            command=handler_id,
+            description=description,
+        )
+
+        self.config.add_hook(
+            event=event,
+            hook=hook_def,
+            matcher=matcher,
+            priority=priority,
+        )
+
+        logger.debug("Registered hook '%s' for event %s", handler_id, event.value)
+        return handler_id
+
+    def unregister(self, handler_id: str) -> bool:
+        """Unregister a hook handler by ID.
+
+        Args:
+            handler_id: Handler ID returned from register()
+
+        Returns:
+            True if handler was found and removed
+
+        """
+        if handler_id in self._python_handlers:
+            del self._python_handlers[handler_id]
+            # Remove from config rules
+            for event_rules in self.config.hooks.values():
+                for rule in event_rules:
+                    rule.hooks = [h for h in rule.hooks if h.command != handler_id]
+            logger.debug("Unregistered hook '%s'", handler_id)
+            return True
+        return False
+
+    def get_matching_hooks(
+        self,
+        event: HookEvent,
+        context: dict[str, Any],
+    ) -> list[tuple[HookRule, HookDefinition]]:
+        """Get all hooks that match the given event and context.
+
+        Args:
+            event: Event type
+            context: Event context for matching
+
+        Returns:
+            List of (rule, hook) tuples that match
+
+        """
+        if not self.config.enabled:
+            return []
+
+        matching = []
+        for rule in self.config.get_hooks_for_event(event):
+            if rule.matcher.matches(context):
+                for hook in rule.hooks:
+                    matching.append((rule, hook))
+
+        return matching
+
+    async def fire(
+        self,
+        event: HookEvent,
+        context: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Fire all matching hooks for an event.
+
+        Args:
+            event: Event type to fire
+            context: Event context for matching and execution
+
+        Returns:
+            List of execution results
+
+        """
+        from empathy_llm_toolkit.hooks.executor import HookExecutor
+
+        context = context or {}
+        matching_hooks = self.get_matching_hooks(event, context)
+
+        if not matching_hooks:
+            logger.debug("No hooks matched for event %s", event.value)
+            return []
+
+        logger.info(
+            "Firing %d hook(s) for event %s",
+            len(matching_hooks),
+            event.value,
+        )
+
+        executor = HookExecutor(python_handlers=self._python_handlers)
+        results = []
+
+        for _rule, hook in matching_hooks:
+            try:
+                result = await executor.execute(hook, context)
+                execution_record = {
+                    "event": event.value,
+                    "hook": hook.command,
+                    "description": hook.description,
+                    "success": result.get("success", False),
+                    "output": result.get("output"),
+                    "error": result.get("error"),
+                    "duration_ms": result.get("duration_ms"),
+                }
+                results.append(execution_record)
+
+                if self.config.log_executions:
+                    self._execution_log.append(execution_record)
+
+            except Exception as e:
+                error_record = {
+                    "event": event.value,
+                    "hook": hook.command,
+                    "success": False,
+                    "error": str(e),
+                }
+                results.append(error_record)
+                logger.error("Hook execution failed: %s - %s", hook.command, e)
+
+                if hook.on_error == "raise":
+                    raise
+
+        return results
+
+    def fire_sync(
+        self,
+        event: HookEvent,
+        context: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        """Synchronous version of fire().
+
+        Args:
+            event: Event type to fire
+            context: Event context
+
+        Returns:
+            List of execution results
+
+        """
+        import asyncio
+
+        try:
+            loop = asyncio.get_running_loop()
+            # If we're in an async context, use run_coroutine_threadsafe
+
+            future = asyncio.run_coroutine_threadsafe(
+                self.fire(event, context),
+                loop,
+            )
+            return future.result(timeout=self.config.default_timeout)
+        except RuntimeError:
+            # No running loop, create one
+            return asyncio.run(self.fire(event, context))
+
+    def get_execution_log(
+        self,
+        limit: int = 100,
+        event_filter: HookEvent | None = None,
+    ) -> list[dict[str, Any]]:
+        """Get recent hook execution log entries.
+
+        Args:
+            limit: Maximum entries to return
+            event_filter: Optional event type filter
+
+        Returns:
+            List of execution records
+
+        """
+        log = self._execution_log
+        if event_filter:
+            log = [e for e in log if e.get("event") == event_filter.value]
+        return log[-limit:]
+
+    def clear_execution_log(self) -> None:
+        """Clear the execution log."""
+        self._execution_log.clear()
+
+    def get_stats(self) -> dict[str, Any]:
+        """Get hook registry statistics.
+
+        Returns:
+            Dictionary with stats
+
+        """
+        total_hooks = sum(
+            sum(len(rule.hooks) for rule in rules) for rules in self.config.hooks.values()
+        )
+
+        executions = len(self._execution_log)
+        successes = sum(1 for e in self._execution_log if e.get("success"))
+
+        return {
+            "enabled": self.config.enabled,
+            "total_hooks": total_hooks,
+            "event_types": len([v for v in self.config.hooks.values() if v]),
+            "python_handlers": len(self._python_handlers),
+            "total_executions": executions,
+            "successful_executions": successes,
+            "success_rate": (successes / executions * 100) if executions else 0,
+        }

empathy_llm_toolkit/hooks/scripts/__init__.py

@@ -0,0 +1,39 @@
+"""Hook Scripts
+
+Pre-built hook scripts for common Empathy Framework events.
+
+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
+Licensed under Fair Source License 0.9
+"""
+
+from empathy_llm_toolkit.hooks.scripts.evaluate_session import (
+    apply_learned_patterns,
+    get_learning_summary,
+    run_evaluate_session,
+)
+from empathy_llm_toolkit.hooks.scripts.first_time_init import (
+    check_init,
+    handle_init_response,
+    initialize_project,
+)
+from empathy_llm_toolkit.hooks.scripts.pre_compact import run_pre_compact
+from empathy_llm_toolkit.hooks.scripts.session_end import main as session_end
+from empathy_llm_toolkit.hooks.scripts.session_start import main as session_start
+from empathy_llm_toolkit.hooks.scripts.suggest_compact import main as suggest_compact
+
+__all__ = [
+    "session_start",
+    "session_end",
+    "suggest_compact",
+    "run_pre_compact",
+    "run_evaluate_session",
+    "get_learning_summary",
+    "apply_learned_patterns",
+    "check_init",
+    "handle_init_response",
+    "initialize_project",
+]

empathy_llm_toolkit/hooks/scripts/evaluate_session.py

@@ -0,0 +1,201 @@
+"""Evaluate Session Hook Script
+
+Evaluates sessions at end for learning potential and extracts patterns.
+Called during SessionEnd hook to enable continuous learning.
+
+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 typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def run_evaluate_session(context: dict[str, Any]) -> dict[str, Any]:
+    """Evaluate a session for learning potential.
+
+    This hook is called at session end to:
+    1. Evaluate if the session has learning value
+    2. Extract patterns if valuable
+    3. Store patterns for future use
+
+    Args:
+        context: Hook context containing:
+            - collaboration_state: CollaborationState
+            - user_id: User identifier
+            - session_id: Session identifier
+            - storage_dir: Optional storage directory
+            - min_score: Optional minimum score for extraction
+
+    Returns:
+        Dict with:
+            - evaluated: Whether evaluation completed
+            - quality: Session quality rating
+            - score: Numeric score (0.0-1.0)
+            - patterns_extracted: Number of patterns extracted
+            - patterns_stored: Number of patterns stored
+            - learnable_topics: List of identified topics
+            - reasoning: Human-readable evaluation reasoning
+            - error: Error message if failed
+    """
+    try:
+        collaboration_state = context.get("collaboration_state")
+        user_id = context.get("user_id")
+        session_id = context.get("session_id", "")
+        storage_dir = context.get("storage_dir", ".empathy/learned_skills")
+        min_score = context.get("min_score", 0.4)
+
+        if not collaboration_state:
+            return {
+                "evaluated": False,
+                "error": "No collaboration state provided",
+            }
+
+        if not user_id:
+            user_id = collaboration_state.user_id
+
+        # Import learning components
+        from empathy_llm_toolkit.learning import (
+            LearnedSkillsStorage,
+            PatternExtractor,
+            SessionEvaluator,
+        )
+
+        # Evaluate the session
+        evaluator = SessionEvaluator(min_score_for_extraction=min_score)
+        evaluation = evaluator.evaluate(collaboration_state)
+
+        result = {
+            "evaluated": True,
+            "quality": evaluation.quality.value,
+            "score": evaluation.score,
+            "learnable_topics": evaluation.learnable_topics,
+            "reasoning": evaluation.reasoning,
+            "patterns_extracted": 0,
+            "patterns_stored": 0,
+        }
+
+        # Extract patterns if recommended
+        if evaluation.recommended_extraction:
+            extractor = PatternExtractor()
+            patterns = extractor.extract_patterns(collaboration_state, session_id)
+
+            result["patterns_extracted"] = len(patterns)
+
+            if patterns:
+                # Store patterns
+                storage = LearnedSkillsStorage(storage_dir=storage_dir)
+                stored_ids = storage.save_patterns(user_id, patterns)
+                result["patterns_stored"] = len(stored_ids)
+
+                # Include pattern summaries
+                result["pattern_summaries"] = [
+                    {
+                        "id": p.pattern_id,
+                        "category": p.category.value,
+                        "trigger": p.trigger[:50],
+                        "confidence": p.confidence,
+                    }
+                    for p in patterns[:5]  # Top 5
+                ]
+
+                logger.info(
+                    f"Extracted {len(patterns)} patterns, stored {len(stored_ids)} "
+                    f"for user {user_id}"
+                )
+        else:
+            logger.debug(f"Session not recommended for extraction (score: {evaluation.score:.2f})")
+
+        return result
+
+    except Exception as e:
+        logger.exception(f"Session evaluation failed: {e}")
+        return {
+            "evaluated": False,
+            "error": str(e),
+        }
+
+
+def get_learning_summary(context: dict[str, Any]) -> dict[str, Any]:
+    """Get learning summary for a user.
+
+    Args:
+        context: Context with user_id and optional storage_dir
+
+    Returns:
+        Learning summary dictionary
+    """
+    try:
+        user_id = context.get("user_id")
+        storage_dir = context.get("storage_dir", ".empathy/learned_skills")
+
+        if not user_id:
+            return {"error": "No user_id provided"}
+
+        from empathy_llm_toolkit.learning import LearnedSkillsStorage
+
+        storage = LearnedSkillsStorage(storage_dir=storage_dir)
+        return storage.get_summary(user_id)
+
+    except Exception as e:
+        logger.exception(f"Failed to get learning summary: {e}")
+        return {"error": str(e)}
+
+
+def apply_learned_patterns(context: dict[str, Any]) -> str:
+    """Generate context injection from learned patterns.
+
+    Args:
+        context: Context with user_id, max_patterns, and optional filters
+
+    Returns:
+        Formatted markdown for context injection
+    """
+    try:
+        user_id = context.get("user_id")
+        max_patterns = context.get("max_patterns", 5)
+        storage_dir = context.get("storage_dir", ".empathy/learned_skills")
+
+        if not user_id:
+            return ""
+
+        from empathy_llm_toolkit.learning import LearnedSkillsStorage, PatternCategory
+
+        # Parse category filter if provided
+        categories = None
+        if cat_filter := context.get("categories"):
+            categories = [PatternCategory(c) for c in cat_filter]
+
+        storage = LearnedSkillsStorage(storage_dir=storage_dir)
+        return storage.format_patterns_for_context(
+            user_id,
+            max_patterns=max_patterns,
+            categories=categories,
+        )
+
+    except Exception as e:
+        logger.exception(f"Failed to apply learned patterns: {e}")
+        return ""
+
+
+# Entry point for hook execution
+if __name__ == "__main__":
+    print("Evaluate Session Hook Script")
+    print("This script is called at session end to evaluate learning potential")
+    print()
+    print("Required context keys:")
+    print("  - collaboration_state: CollaborationState object")
+    print("  - user_id: User identifier (optional, uses state.user_id)")
+    print()
+    print("Optional context keys:")
+    print("  - session_id: Session identifier")
+    print("  - storage_dir: Storage directory path")
+    print("  - min_score: Minimum score for extraction (default: 0.4)")