gnosisllm-knowledge 0.2.0__py3-none-any.whl

gnosisllm_knowledge/core/events/emitter.py

@@ -0,0 +1,216 @@
+"""Event emitter for knowledge module (Observer pattern)."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import logging
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, TypeVar
+
+if TYPE_CHECKING:
+    from gnosisllm_knowledge.core.events.types import Event, EventType
+
+T = TypeVar("T")
+
+# Event handler types
+SyncEventHandler = Callable[["Event"], None]
+AsyncEventHandler = Callable[["Event"], Awaitable[None]]
+EventHandler = SyncEventHandler | AsyncEventHandler
+
+
+class EventEmitter:
+    """Event emitter for decoupled communication (Observer pattern).
+
+    Supports both synchronous and asynchronous event handlers.
+    Handlers can be registered for specific event types or for all events.
+
+    Example:
+        ```python
+        emitter = EventEmitter()
+
+        @emitter.on(EventType.DOCUMENT_LOADED)
+        def on_loaded(event: Event) -> None:
+            print(f"Loaded: {event.data['url']}")
+
+        @emitter.on(EventType.DOCUMENT_INDEXED)
+        async def on_indexed(event: Event) -> None:
+            await log_to_service(event)
+
+        # Emit events
+        emitter.emit(DocumentLoadedEvent(url="https://example.com"))
+        await emitter.emit_async(DocumentIndexedEvent(doc_id="123"))
+        ```
+    """
+
+    def __init__(self) -> None:
+        """Initialize the event emitter."""
+        self._handlers: dict[EventType, list[EventHandler]] = {}
+        self._global_handlers: list[EventHandler] = []
+        self._logger = logging.getLogger(__name__)
+
+    def on(
+        self,
+        *event_types: EventType,
+    ) -> Callable[[EventHandler], EventHandler]:
+        """Decorator to register an event handler.
+
+        Can be used with one or more event types.
+
+        Args:
+            *event_types: Event types to listen for.
+                If empty, handler is called for all events.
+
+        Returns:
+            Decorator function that registers the handler.
+
+        Example:
+            ```python
+            @emitter.on(EventType.DOCUMENT_LOADED)
+            def handler(event): ...
+
+            @emitter.on(EventType.LOAD_STARTED, EventType.LOAD_COMPLETED)
+            def multi_handler(event): ...
+
+            @emitter.on()  # All events
+            def global_handler(event): ...
+            ```
+        """
+
+        def decorator(handler: EventHandler) -> EventHandler:
+            if event_types:
+                for event_type in event_types:
+                    self.add_handler(event_type, handler)
+            else:
+                self._global_handlers.append(handler)
+            return handler
+
+        return decorator
+
+    def add_handler(self, event_type: EventType, handler: EventHandler) -> None:
+        """Register an event handler for a specific event type.
+
+        Args:
+            event_type: Event type to listen for.
+            handler: Handler function to call.
+        """
+        if event_type not in self._handlers:
+            self._handlers[event_type] = []
+        self._handlers[event_type].append(handler)
+
+    def remove_handler(self, event_type: EventType, handler: EventHandler) -> None:
+        """Remove an event handler.
+
+        Args:
+            event_type: Event type the handler was registered for.
+            handler: Handler to remove.
+        """
+        if event_type in self._handlers:
+            with contextlib.suppress(ValueError):
+                self._handlers[event_type].remove(handler)
+
+    def off(self, event_type: EventType, handler: EventHandler) -> None:
+        """Alias for remove_handler."""
+        self.remove_handler(event_type, handler)
+
+    def emit(self, event: Event) -> None:
+        """Emit an event synchronously.
+
+        Calls all registered handlers for the event type.
+        Async handlers are scheduled but not awaited.
+
+        Args:
+            event: The event to emit.
+        """
+        handlers = self._get_handlers(event.event_type)
+        for handler in handlers:
+            try:
+                result = handler(event)
+                # Schedule async handlers
+                if asyncio.iscoroutine(result):
+                    asyncio.create_task(result)
+            except Exception as e:
+                self._logger.error(f"Event handler error: {e}")
+
+    async def emit_async(self, event: Event) -> None:
+        """Emit an event asynchronously.
+
+        Awaits all handlers, including async ones.
+
+        Args:
+            event: The event to emit.
+        """
+        handlers = self._get_handlers(event.event_type)
+        for handler in handlers:
+            try:
+                result = handler(event)
+                if asyncio.iscoroutine(result):
+                    await result
+            except Exception as e:
+                self._logger.error(f"Event handler error: {e}")
+
+    async def emit_parallel(self, event: Event) -> None:
+        """Emit an event and run handlers in parallel.
+
+        All handlers are executed concurrently.
+
+        Args:
+            event: The event to emit.
+        """
+        handlers = self._get_handlers(event.event_type)
+        tasks: list[Awaitable[None]] = []
+
+        for handler in handlers:
+            try:
+                result = handler(event)
+                if asyncio.iscoroutine(result):
+                    tasks.append(result)
+            except Exception as e:
+                self._logger.error(f"Event handler error: {e}")
+
+        if tasks:
+            results = await asyncio.gather(*tasks, return_exceptions=True)
+            for result in results:
+                if isinstance(result, Exception):
+                    self._logger.error(f"Async handler error: {result}")
+
+    def _get_handlers(self, event_type: EventType) -> list[EventHandler]:
+        """Get all handlers for an event type.
+
+        Args:
+            event_type: Event type to get handlers for.
+
+        Returns:
+            List of handlers (specific + global).
+        """
+        specific = self._handlers.get(event_type, [])
+        return specific + self._global_handlers
+
+    def clear(self) -> None:
+        """Clear all event handlers."""
+        self._handlers.clear()
+        self._global_handlers.clear()
+
+    def clear_type(self, event_type: EventType) -> None:
+        """Clear handlers for a specific event type.
+
+        Args:
+            event_type: Event type to clear handlers for.
+        """
+        if event_type in self._handlers:
+            self._handlers[event_type].clear()
+
+    def handler_count(self, event_type: EventType | None = None) -> int:
+        """Get the number of registered handlers.
+
+        Args:
+            event_type: Specific event type, or None for total.
+
+        Returns:
+            Number of handlers.
+        """
+        if event_type is None:
+            return sum(len(h) for h in self._handlers.values()) + len(
+                self._global_handlers
+            )
+        return len(self._handlers.get(event_type, [])) + len(self._global_handlers)

gnosisllm_knowledge/core/events/types.py

@@ -0,0 +1,226 @@
+"""Event type definitions for the knowledge module."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+
+
+class EventType(str, Enum):
+    """Types of events in the knowledge system.
+
+    Events are organized by category:
+    - Loading events: Document and content loading
+    - Indexing events: Document indexing operations
+    - Search events: Search and retrieval operations
+    - Agentic events: AI-powered operations
+    - Setup events: Backend setup operations
+    - Resilience events: Fault tolerance events
+    - Health events: Health check events
+    """
+
+    # Loading events
+    LOAD_STARTED = "load_started"
+    LOAD_PROGRESS = "load_progress"
+    DOCUMENT_FETCHED = "document_fetched"
+    DOCUMENT_CHUNKED = "document_chunked"
+    DOCUMENT_LOADED = "document_loaded"
+    DOCUMENT_VALIDATED = "document_validated"
+    DOCUMENT_REJECTED = "document_rejected"
+    LOAD_COMPLETED = "load_completed"
+    LOAD_FAILED = "load_failed"
+    SITEMAP_DISCOVERED = "sitemap_discovered"
+
+    # Indexing events
+    INDEX_STARTED = "index_started"
+    DOCUMENT_INDEXED = "document_indexed"
+    DOCUMENT_INDEX_FAILED = "document_index_failed"
+    BATCH_STARTED = "batch_started"
+    BATCH_COMPLETED = "batch_completed"
+    INDEX_COMPLETED = "index_completed"
+    INDEX_FAILED = "index_failed"
+
+    # Search events
+    SEARCH_STARTED = "search_started"
+    SEARCH_CACHE_HIT = "search_cache_hit"
+    SEARCH_CACHE_MISS = "search_cache_miss"
+    EMBEDDING_GENERATED = "embedding_generated"
+    EMBEDDING_CACHE_HIT = "embedding_cache_hit"
+    SEARCH_COMPLETED = "search_completed"
+    SEARCH_FAILED = "search_failed"
+
+    # Agentic events
+    AGENT_STARTED = "agent_started"
+    AGENT_STEP = "agent_step"
+    AGENT_COMPLETED = "agent_completed"
+    AGENT_FAILED = "agent_failed"
+
+    # Setup events
+    SETUP_STARTED = "setup_started"
+    SETUP_STEP_STARTED = "setup_step_started"
+    SETUP_STEP_COMPLETED = "setup_step_completed"
+    SETUP_STEP_FAILED = "setup_step_failed"
+    SETUP_COMPLETED = "setup_completed"
+
+    # Resilience events
+    RETRY_ATTEMPT = "retry_attempt"
+    CIRCUIT_BREAKER_OPENED = "circuit_breaker_opened"
+    CIRCUIT_BREAKER_CLOSED = "circuit_breaker_closed"
+    CIRCUIT_BREAKER_HALF_OPEN = "circuit_breaker_half_open"
+    FALLBACK_TRIGGERED = "fallback_triggered"
+
+    # Health events
+    HEALTH_CHECK_STARTED = "health_check_started"
+    HEALTH_CHECK_COMPLETED = "health_check_completed"
+    HEALTH_DEGRADED = "health_degraded"
+    HEALTH_RECOVERED = "health_recovered"
+
+    # Error events
+    ERROR = "error"
+
+
+@dataclass
+class Event:
+    """Base event class.
+
+    Attributes:
+        event_type: The type of event.
+        timestamp: When the event occurred.
+        data: Additional event data.
+        account_id: Account ID for multi-tenant context.
+        user_id: User ID if applicable.
+        request_id: Request ID for tracing.
+        trace_id: Distributed trace ID.
+        span_id: Distributed trace span ID.
+    """
+
+    event_type: EventType = EventType.ERROR  # Default, usually overridden
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+    data: dict[str, Any] = field(default_factory=dict)
+
+    # Context
+    account_id: str | None = None
+    user_id: str | None = None
+    request_id: str | None = None
+
+    # Tracing
+    trace_id: str | None = None
+    span_id: str | None = None
+
+    def with_context(
+        self,
+        account_id: str | None = None,
+        user_id: str | None = None,
+        request_id: str | None = None,
+    ) -> Event:
+        """Create a copy with context information."""
+        return Event(
+            event_type=self.event_type,
+            timestamp=self.timestamp,
+            data=self.data.copy(),
+            account_id=account_id or self.account_id,
+            user_id=user_id or self.user_id,
+            request_id=request_id or self.request_id,
+            trace_id=self.trace_id,
+            span_id=self.span_id,
+        )
+
+
+@dataclass
+class DocumentLoadedEvent(Event):
+    """Event emitted when a document is loaded."""
+
+    url: str = ""
+    source: str = ""
+    chunks_count: int = 0
+    content_length: int = 0
+
+    def __post_init__(self) -> None:
+        """Set event type."""
+        self.event_type = EventType.DOCUMENT_LOADED
+        self.data = {
+            "url": self.url,
+            "source": self.source,
+            "chunks_count": self.chunks_count,
+            "content_length": self.content_length,
+        }
+
+
+@dataclass
+class DocumentIndexedEvent(Event):
+    """Event emitted when a document is indexed."""
+
+    doc_id: str = ""
+    index_name: str = ""
+    success: bool = True
+    error_message: str | None = None
+
+    def __post_init__(self) -> None:
+        """Set event type."""
+        self.event_type = EventType.DOCUMENT_INDEXED
+        self.data = {
+            "doc_id": self.doc_id,
+            "index_name": self.index_name,
+            "success": self.success,
+            "error_message": self.error_message,
+        }
+
+
+@dataclass
+class SitemapDiscoveryEvent(Event):
+    """Event emitted when URLs are discovered from a sitemap."""
+
+    sitemap_url: str = ""
+    urls_discovered: int = 0
+    depth: int = 0
+    total_urls: int = 0
+
+    def __post_init__(self) -> None:
+        """Set event type."""
+        self.event_type = EventType.SITEMAP_DISCOVERED
+        self.data = {
+            "sitemap_url": self.sitemap_url,
+            "urls_discovered": self.urls_discovered,
+            "depth": self.depth,
+            "total_urls": self.total_urls,
+        }
+
+
+@dataclass
+class BatchStartedEvent(Event):
+    """Event emitted when a batch operation starts."""
+
+    batch_index: int = 0
+    batch_size: int = 0
+    total_batches: int = 0
+
+    def __post_init__(self) -> None:
+        """Set event type."""
+        self.event_type = EventType.BATCH_STARTED
+        self.data = {
+            "batch_index": self.batch_index,
+            "batch_size": self.batch_size,
+            "total_batches": self.total_batches,
+        }
+
+
+@dataclass
+class BatchCompletedEvent(Event):
+    """Event emitted when a batch operation completes."""
+
+    batch_index: int = 0
+    success_count: int = 0
+    failure_count: int = 0
+    duration_ms: float = 0.0
+
+    def __post_init__(self) -> None:
+        """Set event type."""
+        self.event_type = EventType.BATCH_COMPLETED
+        self.data = {
+            "batch_index": self.batch_index,
+            "success_count": self.success_count,
+            "failure_count": self.failure_count,
+            "duration_ms": self.duration_ms,
+        }