gllm-core-binary 0.4.4__py3-none-macosx_13_0_arm64.whl

gllm_core/event/event_emitter.pyi

@@ -0,0 +1,155 @@
+from _typeshed import Incomplete
+from gllm_core.constants import EventLevel as EventLevel
+from gllm_core.event.handler import ConsoleEventHandler as ConsoleEventHandler, PrintEventHandler as PrintEventHandler, StreamEventHandler as StreamEventHandler
+from gllm_core.event.handler.event_handler import BaseEventHandler as BaseEventHandler
+from gllm_core.event.hook.event_hook import BaseEventHook as BaseEventHook
+from gllm_core.schema import Event as Event
+from gllm_core.utils import validate_string_enum as validate_string_enum
+from typing import AsyncGenerator
+
+class EventEmitter:
+    '''Handles events emitting using event handlers with various levels and types.
+
+    The `EventEmitter` class is responsible for handling and emitting events using a list of event handlers.
+    Events are processed based on their severity level and type, with the option to disable specific handlers.
+
+    Attributes:
+        handlers (list[BaseEventHandler]): A list of event handlers to process emitted events.
+        severity (int): The minimum severity level of events to be processed.
+
+    Examples:
+        Basic usage:
+        ```python
+        event_emitter = EventEmitter(handlers=[ConsoleEventHandler()])
+        await event_emitter.emit("Hello, world!")
+        ```
+
+        Emitting an event object:
+        ```python
+        event_emitter = EventEmitter(handlers=[ConsoleEventHandler()])
+        event = Event(id="123", value="Hello, world!", level=EventLevel.INFO, type="object", metadata={})
+        await event_emitter.emit(event)
+        ```
+
+        Using with hooks:
+        ```python
+        event_emitter = EventEmitter(handlers=[ConsoleEventHandler()], hooks=[JSONStringifyEventHook()])
+        await event_emitter.emit("Hello, world!")
+        ```
+
+        Using with customized event level:
+        ```python
+        event_emitter = EventEmitter(handlers=[ConsoleEventHandler()], event_level=EventLevel.DEBUG)
+        await event_emitter.emit("Hello, world!")
+        ```
+
+        Using with console handler:
+        ```python
+        event_emitter = EventEmitter.with_console_handler()
+        await event_emitter.emit("Hello, world!")
+        ```
+
+        Using with print handler:
+        ```python
+        event_emitter = EventEmitter.with_print_handler()
+        await event_emitter.emit("Hello, world!")
+        ```
+
+        Using with stream handler:
+        ```python
+        async def function(event_emitter: EventEmitter):
+            await event_emitter.emit("Hello, world!")
+
+        event_emitter = EventEmitter.with_stream_handler()
+        asyncio.create_task(function(event_emitter))
+        async for event in event_emitter.stream():
+            print(event)
+        ```
+    '''
+    handlers: Incomplete
+    severity: Incomplete
+    hooks: Incomplete
+    def __init__(self, handlers: list[BaseEventHandler], event_level: EventLevel = ..., hooks: list[BaseEventHook] | None = None) -> None:
+        """Initializes a new instance of the EventEmitter class.
+
+        Args:
+            handlers (list[BaseEventHandler]): A list of event handlers to process emitted events.
+            event_level (EventLevel, optional): The minimum severity level of events to be processed.
+                Defaults to EventLevel.INFO.
+            hooks (list[BaseEventHook] | None, optional): A list of event hooks to be applied to the emitted events.
+                Defaults to None, in which case the event emitter will not apply any hooks.
+
+        Raises:
+            ValueError:
+                1. If the event handlers list is empty.
+                2. If an invalid event level is provided.
+        """
+    @classmethod
+    def with_console_handler(cls, event_level: EventLevel = ..., hooks: list[BaseEventHook] | None = None) -> EventEmitter:
+        """Creates a new instance of the EventEmitter class with a single ConsoleEventHandler.
+
+        Args:
+            event_level (EventLevel, optional): The minimum severity level of events to be processed.
+                Defaults to EventLevel.INFO.
+            hooks (list[BaseEventHook] | None, optional): A list of event hooks to be applied to the emitted events.
+                Defaults to None, in which case the event emitter will not apply any hooks.
+
+        Returns:
+            EventEmitter: A new instance of the EventEmitter class with a single ConsoleEventHandler.
+        """
+    @classmethod
+    def with_print_handler(cls, event_level: EventLevel = ..., hooks: list[BaseEventHook] | None = None) -> EventEmitter:
+        """Creates a new instance of the EventEmitter class with a single PrintEventHandler.
+
+        Args:
+            event_level (EventLevel, optional): The minimum severity level of events to be processed.
+                Defaults to EventLevel.INFO.
+            hooks (list[BaseEventHook] | None, optional): A list of event hooks to be applied to the emitted events.
+                Defaults to None, in which case the event emitter will not apply any hooks.
+
+        Returns:
+            EventEmitter: A new instance of the EventEmitter class with a single PrintEventHandler.
+        """
+    @classmethod
+    def with_stream_handler(cls, event_level: EventLevel = ..., hooks: list[BaseEventHook] | None = None) -> EventEmitter:
+        """Creates a new instance of the EventEmitter class with a single StreamEventHandler.
+
+        Args:
+            event_level (EventLevel, optional): The minimum severity level of events to be processed.
+                Defaults to EventLevel.INFO.
+            hooks (list[BaseEventHook] | None, optional): A list of event hooks to be applied to the emitted events.
+                Defaults to None, in which case the event emitter will not apply any hooks.
+
+        Returns:
+            EventEmitter: A new instance of the EventEmitter class with a single StreamEventHandler.
+        """
+    async def emit(self, event: Event, disabled_handlers: list[str] | None = None) -> None:
+        """Emits an event using the configured event handlers.
+
+        Events are emitted by passing them to all handlers except those listed in disabled_handlers.
+        Events are only processed if their severity level meets or exceeds the EventEmitter's configured level.
+
+        Args:
+            event (Event): The event to emit.
+            disabled_handlers (list[str] | None, optional): Names of handlers to skip for this event. Defaults to None.
+
+        Raises:
+            ValueError: If the provided event_level is not a valid EventLevel.
+        """
+    async def close(self) -> None:
+        """Closes all handlers in the handler list.
+
+        This method iterates through the list of handlers and calls the `close` method on each handler.
+
+        Returns:
+            None
+        """
+    def stream(self) -> AsyncGenerator:
+        """Streams events from the StreamEventHandler.
+
+        This method is a convenience method that calls the `stream` method on the StreamEventHandler.
+        To use this method, the event emitter must have exactly one StreamEventHandler.
+
+        Returns:
+            AsyncGenerator: An asynchronous generator yielding events from the StreamEventHandler.
+        """

gllm_core/event/handler/__init__.py

@@ -0,0 +1,7 @@
+"""Modules concerning the event handler modules used throughout the Gen AI applications."""
+
+from gllm_core.event.handler.console_event_handler import ConsoleEventHandler
+from gllm_core.event.handler.print_event_handler import PrintEventHandler
+from gllm_core.event.handler.stream_event_handler import StreamEventHandler
+
+__all__ = ["ConsoleEventHandler", "PrintEventHandler", "StreamEventHandler"]

gllm_core/event/handler/__init__.pyi

@@ -0,0 +1,5 @@
+from gllm_core.event.handler.console_event_handler import ConsoleEventHandler as ConsoleEventHandler
+from gllm_core.event.handler.print_event_handler import PrintEventHandler as PrintEventHandler
+from gllm_core.event.handler.stream_event_handler import StreamEventHandler as StreamEventHandler
+
+__all__ = ['ConsoleEventHandler', 'PrintEventHandler', 'StreamEventHandler']

gllm_core/event/handler/console_event_handler.py

@@ -0,0 +1,48 @@
+"""Defines an event handler class to print events to console.
+
+Authors:
+    Henry Wicaksono (henry.wicaksono@gdplabs.id)
+
+References:
+    NONE
+"""
+
+from rich.console import Console
+
+from gllm_core.event.handler.event_handler import BaseEventHandler
+from gllm_core.schema import Event
+
+
+class ConsoleEventHandler(BaseEventHandler):
+    """Defines an event handler class that prints events to the console.
+
+    Attributes:
+        name (str): The name assigned to the event handler.
+        color_map (dict[str, str]): The dictionary that maps certain event types to their
+            corresponding colors in Rich format.
+        console (Console): The Rich Console object to use for printing.
+    """
+
+    def __init__(self, name: str | None = None, color_map: dict[str, str] | None = None) -> None:
+        """Initializes a new instance of the ConsoleEventHandler class.
+
+        Args:
+            name (str | None, optional): The name assigned to the event handler. Defaults to None,
+                in which case the class name will be used.
+            color_map (dict[str, str], optional): The dictionary that maps certain event types to their corresponding
+                colors in Rich format. Defaults to None, in which case the default color map will be used.
+        """
+        super().__init__(name, color_map)
+        self.console = Console(highlight=False)
+
+    async def emit(self, event: Event) -> None:
+        """Emits the given event by printing it to the console as a JSON string.
+
+        Args:
+            event (Event): The event to be emitted.
+
+        Raises:
+            ValueError: If the event type is invalid.
+        """
+        color = self._get_rich_color(event.type)
+        self.console.print(f"[{color}]{event.model_dump_json()}[/]")

gllm_core/event/handler/console_event_handler.pyi

@@ -0,0 +1,32 @@
+from _typeshed import Incomplete
+from gllm_core.event.handler.event_handler import BaseEventHandler as BaseEventHandler
+from gllm_core.schema import Event as Event
+
+class ConsoleEventHandler(BaseEventHandler):
+    """Defines an event handler class that prints events to the console.
+
+    Attributes:
+        name (str): The name assigned to the event handler.
+        color_map (dict[str, str]): The dictionary that maps certain event types to their
+            corresponding colors in Rich format.
+        console (Console): The Rich Console object to use for printing.
+    """
+    console: Incomplete
+    def __init__(self, name: str | None = None, color_map: dict[str, str] | None = None) -> None:
+        """Initializes a new instance of the ConsoleEventHandler class.
+
+        Args:
+            name (str | None, optional): The name assigned to the event handler. Defaults to None,
+                in which case the class name will be used.
+            color_map (dict[str, str], optional): The dictionary that maps certain event types to their corresponding
+                colors in Rich format. Defaults to None, in which case the default color map will be used.
+        """
+    async def emit(self, event: Event) -> None:
+        """Emits the given event by printing it to the console as a JSON string.
+
+        Args:
+            event (Event): The event to be emitted.
+
+        Raises:
+            ValueError: If the event type is invalid.
+        """

gllm_core/event/handler/event_handler.py

@@ -0,0 +1,89 @@
+"""Defines an abstract base class for all event handlers used throughout the Gen AI applications.
+
+Authors:
+    Henry Wicaksono (henry.wicaksono@gdplabs.id)
+
+References:
+    NONE
+"""
+
+from abc import ABC, abstractmethod
+
+from gllm_core.constants import EventType, EventTypeSuffix
+from gllm_core.schema import Event
+from gllm_core.utils import LoggerManager
+
+DEFAULT_COLOR_MAP = {
+    EventType.ACTIVITY: "bright_blue",
+    EventType.CODE: "bright_red",
+    EventType.THINKING: "bright_yellow",
+    EventType.REFERENCE: "bright_green",
+    EventType.STATUS: "bright_black",
+}
+DEFAULT_COLOR = "white"
+
+
+class BaseEventHandler(ABC):
+    """An abstract base class for all event handlers used throughout the Gen AI applications.
+
+    Attributes:
+        name (str): The name assigned to the event handler.
+        color_map (dict[str, str]): The dictionary that maps certain event types to their
+            corresponding colors in Rich format.
+    """
+
+    def __init__(
+        self,
+        name: str | None = None,
+        color_map: dict[str, str] | None = None,
+    ):
+        """Initializes a new instance of the BaseEventHandler class.
+
+        Args:
+            name (str | None, optional): The name assigned to the event handler. Defaults to None,
+                in which case the class name will be used.
+            color_map (dict[str, str], optional): The dictionary that maps certain event types to their corresponding
+                colors in Rich format. Defaults to None, in which case the default color map will be used.
+        """
+        self.name = name or self.__class__.__name__
+        self.color_map = color_map or DEFAULT_COLOR_MAP
+        self._logger = LoggerManager().get_logger(self.name)
+
+    @abstractmethod
+    async def emit(self, event: Event) -> None:
+        """Emits the given event.
+
+        This abstract method must be implemented by subclasses to define how an event is emitted.
+
+        Args:
+            event (Event): The event to be emitted.
+
+        Raises:
+            NotImplementedError: If the method is not implemented in a subclass.
+        """
+        raise NotImplementedError
+
+    async def close(self) -> None:  # noqa: B027
+        """Closes the event handler.
+
+        By default, this method does nothing. Subclasses can override this method to perform cleanup tasks
+        (e.g., closing connections or releasing resources) when needed. Event handlers that do not require
+        cleanup can inherit this default behavior without any changes.
+
+        Returns:
+            None
+        """
+
+    def _get_rich_color(self, value: str) -> str:
+        """Gets the assigned Rich color for the given value.
+
+        Args:
+            value (str): The value to get the Rich color for.
+
+        Returns:
+            str: The Rich color for the given value.
+        """
+        for suffix in EventTypeSuffix:
+            value = value.removesuffix(suffix)
+
+        return self.color_map.get(value, DEFAULT_COLOR)

gllm_core/event/handler/event_handler.pyi

@@ -0,0 +1,51 @@
+import abc
+from _typeshed import Incomplete
+from abc import ABC, abstractmethod
+from gllm_core.constants import EventType as EventType, EventTypeSuffix as EventTypeSuffix
+from gllm_core.schema import Event as Event
+from gllm_core.utils import LoggerManager as LoggerManager
+
+DEFAULT_COLOR_MAP: Incomplete
+DEFAULT_COLOR: str
+
+class BaseEventHandler(ABC, metaclass=abc.ABCMeta):
+    """An abstract base class for all event handlers used throughout the Gen AI applications.
+
+    Attributes:
+        name (str): The name assigned to the event handler.
+        color_map (dict[str, str]): The dictionary that maps certain event types to their
+            corresponding colors in Rich format.
+    """
+    name: Incomplete
+    color_map: Incomplete
+    def __init__(self, name: str | None = None, color_map: dict[str, str] | None = None) -> None:
+        """Initializes a new instance of the BaseEventHandler class.
+
+        Args:
+            name (str | None, optional): The name assigned to the event handler. Defaults to None,
+                in which case the class name will be used.
+            color_map (dict[str, str], optional): The dictionary that maps certain event types to their corresponding
+                colors in Rich format. Defaults to None, in which case the default color map will be used.
+        """
+    @abstractmethod
+    async def emit(self, event: Event) -> None:
+        """Emits the given event.
+
+        This abstract method must be implemented by subclasses to define how an event is emitted.
+
+        Args:
+            event (Event): The event to be emitted.
+
+        Raises:
+            NotImplementedError: If the method is not implemented in a subclass.
+        """
+    async def close(self) -> None:
+        """Closes the event handler.
+
+        By default, this method does nothing. Subclasses can override this method to perform cleanup tasks
+        (e.g., closing connections or releasing resources) when needed. Event handlers that do not require
+        cleanup can inherit this default behavior without any changes.
+
+        Returns:
+            None
+        """

gllm_core/event/handler/print_event_handler.py

@@ -0,0 +1,130 @@
+"""Defines an event handler class to print events with human readable format.
+
+Authors:
+    Henry Wicaksono (henry.wicaksono@gdplabs.id)
+
+References:
+    NONE
+"""
+
+from typing import Any
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.style import Style
+
+from gllm_core.constants import EventType, EventTypeSuffix
+from gllm_core.event.handler.event_handler import BaseEventHandler
+from gllm_core.schema import Event
+
+
+class PrintEventHandler(BaseEventHandler):
+    """An event handler that prints the event with human readable format.
+
+    Attributes:
+        name (str): The name assigned to the event handler.
+        padding_char (str): The character to use for padding.
+        color_map (dict[str, str]): The dictionary that maps certain event types to their
+            corresponding colors in Rich format.
+        console (Console): The Rich Console object to use for printing.
+    """
+
+    def __init__(
+        self,
+        name: str | None = None,
+        color_map: dict[str, str] | None = None,
+        padding_char: str = "=",
+    ):
+        """Initializes a new instance of the PrintEventHandler class.
+
+        Args:
+            name (str | None, optional): The name assigned to the event handler. Defaults to None,
+                in which case the class name will be used.
+            color_map (dict[str, str], optional): The dictionary that maps certain event types to their corresponding
+                colors in Rich format. Defaults to None, in which case the default color map will be used.
+            padding_char (str, optional): The character to use for padding. Defaults to "=".
+        """
+        super().__init__(name, color_map)
+        self.padding_char = padding_char
+        self.console = Console(highlight=False)
+
+    async def emit(self, event: Event) -> None:
+        """Emits the given event.
+
+        Args:
+            event (Event): The event to be emitted.
+        """
+        if event.type == EventType.STATUS:
+            self.console.print(f"[{event.level.name}][{event.timestamp}] {event.value}")
+            return
+
+        if event.type == EventType.ACTIVITY:
+            self._print_activity(event.value)
+        elif event.type.endswith(EventTypeSuffix.START) or event.type.endswith(EventTypeSuffix.END):
+            self._print_start_end(event.type)
+        else:
+            style = Style(color=self._get_rich_color(event.type))
+            self.console.print(event.value, end="", style=style)
+
+    def _print_activity(self, activity: dict[str, Any]) -> None:
+        """Prints the activity.
+
+        This method prints the activity with the following format:
+
+        ╭──────────────────╮
+        │     ACTIVITY     │
+        ╰──────────────────╯
+        >>> key1: value1
+        >>> key2: value2
+
+        Args:
+            activity (dict[str, Any]): The activity to print.
+        """
+        color = self._get_rich_color(EventType.ACTIVITY)
+        panel = self._create_separator_panel(EventType.ACTIVITY, color)
+        self.console.print()
+        self.console.print(panel)
+
+        for key, value in activity.items():
+            self.console.print(f">>> {key}: {value}", style=Style(color=color))
+
+    def _print_start_end(self, event_type: str) -> None:
+        """Prints the start or end of block based events.
+
+        This method prints the start or end of block based events with the following format:
+
+        ╭─────────────────────╮
+        │     EVENT START     │
+        ╰─────────────────────╯
+        Event content...
+        ╭───────────────────╮
+        │     EVENT END     │
+        ╰───────────────────╯
+
+        Args:
+            event_type (str): The type of the event.
+        """
+        color = self._get_rich_color(event_type)
+        panel = self._create_separator_panel(event_type, color)
+        self.console.print()
+        self.console.print(panel)
+
+    def _create_separator_panel(self, value: str, color: str) -> Panel:
+        """Creates a separator panel.
+
+        This method creates a separator Rich Panel with the following format:
+
+        ╭───────────────╮
+        │     VALUE     │
+        ╰───────────────╯
+
+        Args:
+            value (str): The value to format.
+            color (str): The color of the separator.
+
+        Returns:
+            Panel: The separator panel.
+        """
+        value = value.replace("_", " ").upper().strip()
+        style = Style(color=color, bold=True)
+        return Panel.fit(value, style=style, border_style=style, padding=(0, 5))

gllm_core/event/handler/print_event_handler.pyi

@@ -0,0 +1,33 @@
+from _typeshed import Incomplete
+from gllm_core.constants import EventType as EventType, EventTypeSuffix as EventTypeSuffix
+from gllm_core.event.handler.event_handler import BaseEventHandler as BaseEventHandler
+from gllm_core.schema import Event as Event
+
+class PrintEventHandler(BaseEventHandler):
+    """An event handler that prints the event with human readable format.
+
+    Attributes:
+        name (str): The name assigned to the event handler.
+        padding_char (str): The character to use for padding.
+        color_map (dict[str, str]): The dictionary that maps certain event types to their
+            corresponding colors in Rich format.
+        console (Console): The Rich Console object to use for printing.
+    """
+    padding_char: Incomplete
+    console: Incomplete
+    def __init__(self, name: str | None = None, color_map: dict[str, str] | None = None, padding_char: str = '=') -> None:
+        '''Initializes a new instance of the PrintEventHandler class.
+
+        Args:
+            name (str | None, optional): The name assigned to the event handler. Defaults to None,
+                in which case the class name will be used.
+            color_map (dict[str, str], optional): The dictionary that maps certain event types to their corresponding
+                colors in Rich format. Defaults to None, in which case the default color map will be used.
+            padding_char (str, optional): The character to use for padding. Defaults to "=".
+        '''
+    async def emit(self, event: Event) -> None:
+        """Emits the given event.
+
+        Args:
+            event (Event): The event to be emitted.
+        """

gllm_core/event/handler/stream_event_handler.py

@@ -0,0 +1,85 @@
+"""Defines an event handler class to stream events to clients using asynchronous queue.
+
+Authors:
+    Henry Wicaksono (henry.wicaksono@gdplabs.id)
+
+References:
+    NONE
+"""
+
+import asyncio
+from typing import AsyncGenerator
+
+from gllm_core.event.handler.event_handler import BaseEventHandler
+from gllm_core.schema import Event
+
+
+class StreamEventHandler(BaseEventHandler):
+    """A class that manages an asynchronous stream of data using a queue.
+
+    The StreamEventHandler class provides methods to manage an asynchronous stream, allowing data to be sent and
+    retrieved in a non-blocking manner. The stream method yields items from the queue, and the emit method adds
+    items to the queue. The stream can be closed by calling the close method, which ensures no further items
+    are processed.
+
+    Attributes:
+        name (str): The name assigned to the event handler.
+        color_map (dict[str, str]): The dictionary that maps certain event types to their
+            corresponding colors in Rich format.
+        queue (asyncio.Queue): The queue used to manage an asynchronous stream.
+    """
+
+    def __init__(self, name: str | None = None, stream_delay: float = 0.001) -> None:
+        """Initializes a new instance of the StreamEventHandler class.
+
+        Args:
+            name (str | None, optional): The name assigned to the event handler. Defaults to None,
+                in which case the class name will be used.
+            stream_delay (float, optional): The delay duration after each data stream. Needed in order for the stream
+                manager to process the data stream properly. Defaults to 0.001.
+        """
+        self.queue: asyncio.Queue = asyncio.Queue()
+        self.stream_delay = stream_delay
+        super().__init__(name)
+
+    async def emit(self, event: Event) -> None:
+        """Emits the given event by sending it to the client via an asynchronous queue.
+
+        This method serializes the event to a JSON and sends it to the client by adding it to an asynchronous
+        queue. It also introduces a delay specified by `stream_delay` to make sure that the stream data can
+        be processed properly.
+
+        Args:
+            event (Event): The event to be emitted.
+
+        Returns:
+            None
+        """
+        await self.queue.put(event.model_dump_json())
+        await asyncio.sleep(self.stream_delay)
+
+    async def stream(self) -> AsyncGenerator:
+        """Asynchronously yields items from the queue until a StopIteration item is encountered.
+
+        This method continuously retrieves items from the queue and yields them. The iteration stops when a
+        StopIteration item is encountered, at which point the method returns.
+
+        Returns:
+            AsyncGenerator: An asynchronous generator yielding items from the queue.
+        """
+        while True:
+            item = await self.queue.get()
+            if item is StopIteration:
+                return
+            yield item
+
+    async def close(self) -> None:
+        """Immediately stops the stream by placing a StopIteration item in the queue.
+
+        This method inserts a StopIteration item into the queue without waiting, which signals the stream to stop
+        processing further items.
+
+        Returns:
+            None
+        """
+        self.queue.put_nowait(StopIteration)