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

gllm_core/event/handler/stream_event_handler.pyi

@@ -0,0 +1,62 @@
+import asyncio
+from _typeshed import Incomplete
+from gllm_core.event.handler.event_handler import BaseEventHandler as BaseEventHandler
+from gllm_core.schema import Event as Event
+from typing import AsyncGenerator
+
+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.
+    """
+    queue: asyncio.Queue
+    stream_delay: Incomplete
+    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.
+        """
+    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
+        """
+    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.
+        """
+    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
+        """

gllm_core/event/hook/__init__.py

@@ -0,0 +1,5 @@
+"""Defines the event hooks module used throughout the Gen AI applications."""
+
+from gllm_core.event.hook.json_stringify_event_hook import JSONStringifyEventHook
+
+__all__ = ["JSONStringifyEventHook"]

gllm_core/event/hook/__init__.pyi

@@ -0,0 +1,3 @@
+from gllm_core.event.hook.json_stringify_event_hook import JSONStringifyEventHook as JSONStringifyEventHook
+
+__all__ = ['JSONStringifyEventHook']

gllm_core/event/hook/event_hook.py

@@ -0,0 +1,30 @@
+"""Defines an interface for event hooks.
+
+Authors:
+    Henry Wicaksono (henry.wicaksono@gdplabs.id)
+
+References:
+    NONE
+"""
+
+from abc import ABC, abstractmethod
+
+from gllm_core.schema import Event
+
+
+class BaseEventHook(ABC):
+    """An abstract base class for all event hooks."""
+
+    @abstractmethod
+    async def __call__(self, event: Event) -> Event:
+        """Applies the hook to the event.
+
+        This abstract method must be implemented by subclasses to define how the hook is applied to the event.
+
+        Args:
+            event (Event): The event to apply the hook to.
+
+        Returns:
+            Event: The event after the hook is applied.
+        """
+        raise NotImplementedError

gllm_core/event/hook/event_hook.pyi

@@ -0,0 +1,18 @@
+import abc
+from abc import ABC, abstractmethod
+from gllm_core.schema import Event as Event
+
+class BaseEventHook(ABC, metaclass=abc.ABCMeta):
+    """An abstract base class for all event hooks."""
+    @abstractmethod
+    async def __call__(self, event: Event) -> Event:
+        """Applies the hook to the event.
+
+        This abstract method must be implemented by subclasses to define how the hook is applied to the event.
+
+        Args:
+            event (Event): The event to apply the hook to.
+
+        Returns:
+            Event: The event after the hook is applied.
+        """

gllm_core/event/hook/json_stringify_event_hook.py

@@ -0,0 +1,32 @@
+"""Defines an event hook to JSON stringify the event value.
+
+Authors:
+    Henry Wicaksono (henry.wicaksono@gdplabs.id)
+
+References:
+    NONE
+"""
+
+import json
+
+from gllm_core.event.hook.event_hook import BaseEventHook
+from gllm_core.schema import Event
+
+
+class JSONStringifyEventHook(BaseEventHook):
+    """An event hook to JSON stringify the event value."""
+
+    async def __call__(self, event: Event) -> Event:
+        """Applies the hook to the event.
+
+        This method will convert the event value to a JSON string if it is a dictionary.
+
+        Args:
+            event (Event): The event to apply the hook to.
+
+        Returns:
+            Event: The event after the hook is applied.
+        """
+        if isinstance(event.value, dict):
+            event.value = json.dumps(event.value)
+        return event

gllm_core/event/hook/json_stringify_event_hook.pyi

@@ -0,0 +1,16 @@
+from gllm_core.event.hook.event_hook import BaseEventHook as BaseEventHook
+from gllm_core.schema import Event as Event
+
+class JSONStringifyEventHook(BaseEventHook):
+    """An event hook to JSON stringify the event value."""
+    async def __call__(self, event: Event) -> Event:
+        """Applies the hook to the event.
+
+        This method will convert the event value to a JSON string if it is a dictionary.
+
+        Args:
+            event (Event): The event to apply the hook to.
+
+        Returns:
+            Event: The event after the hook is applied.
+        """

gllm_core/event/messenger.py

@@ -0,0 +1,133 @@
+"""Defines a component used for custom event messaging in Gen AI applications pipelines.
+
+Authors:
+    Henry Wicaksono (henry.wicaksono@gdplabs.id)
+
+References:
+    NONE
+"""
+
+from typing import Any
+
+from gllm_core.event import EventEmitter
+from gllm_core.schema import Component
+from gllm_core.utils import get_placeholder_keys
+
+
+class Messenger(Component):
+    """Emits a custom event message with possible access to the state variables.
+
+    This component acts as an intermediary step, designed to be placed between other pipeline steps.
+    It allows for event messaging operations to be performed outside individual components but still within
+    the context of the pipeline execution.
+
+    Attributes:
+        message (str): The message to be sent, may contain placeholders enclosed in curly braces `{}`.
+        is_template (bool): Whether the message is a template that can be injected with state variables.
+            Defaults to True.
+        variable_keys (list[str]): The keys of the message that can be injected with state variables.
+            Only used if `is_template` is set to True.
+
+    Plain string message example:
+    ```python
+    event_emitter = EventEmitter(handlers=[ConsoleEventHandler()])
+    kwargs = {"event_emitter": event_emitter}
+
+    messenger = Messenger("Executing component.", is_template=False)
+    await messenger.run(**kwargs)
+    ```
+
+    Template message example:
+    ```python
+    event_emitter = EventEmitter(handlers=[ConsoleEventHandler()])
+    state_variables = {"query": "Hi!", "top_k": 10}
+    kwargs = {"event_emitter": event_emitter, "state_variables": state_variables}
+
+    messenger = Messenger("Executing component for query {query} and top k {top_k}.")
+    await messenger.run(**kwargs)
+    ```
+    """
+
+    def __init__(self, message: str, is_template: bool = True):
+        """Initializes a new instance of the Messenger class.
+
+        Args:
+            message (str): The message to be sent, may contain placeholders enclosed in curly braces `{}`.
+            is_template (bool, optional): Whether the message is a template that can be injected with state variables.
+                Defaults to True.
+
+        Raises:
+            ValueError: If the keys of the message does not match the provided keys.
+        """
+        self.message = message
+        self.is_template = is_template
+        self.variable_keys = get_placeholder_keys(message) if is_template else []
+
+    async def _run(self, **kwargs: Any) -> None:
+        """Executes the messaging operation.
+
+        This method validates the provided kwargs to make sure it contains the necessary keys and values, then
+        calls the `send_message` method to emit the message.
+
+        Args:
+            **kwargs (Any): A dictionary of arguments for the event process, must include `event_emitter` and may
+                optionally include `state_variables`, and `emit_kwargs`.
+
+        Raises:
+            KeyError: If the kwargs is missing the `event_emitter` key.
+        """
+        if "event_emitter" not in kwargs or not isinstance(kwargs["event_emitter"], EventEmitter):
+            raise KeyError("The input kwargs must include an `event_emitter` key with an EventEmitter instance.")
+
+        return await self.send_message(
+            kwargs["event_emitter"],
+            state_variables=kwargs.get("state_variables"),
+            emit_kwargs=kwargs.get("emit_kwargs"),
+        )
+
+    async def send_message(
+        self,
+        event_emitter: EventEmitter,
+        state_variables: dict[str, Any] | None = None,
+        emit_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        """Emits the message to the event emitter.
+
+        This method validates the variables, formats the message if required, and then emits the message using the
+        event emitter.
+
+        Args:
+            event_emitter (EventEmitter): The event emitter instance to emit the message.
+            state_variables (dict[str, Any] | None, optional): The state variables to be injected into the message
+                placeholders. Can only be provided if `is_template` is set to True. Defaults to None.
+            emit_kwargs (dict[str, Any] | None, optional): The keyword arguments to be passed to the event emitter's
+                emit method. Defaults to None.
+        """
+        state_variables = state_variables or {}
+        emit_kwargs = emit_kwargs or {}
+        formatted_message = self.message
+
+        if self.is_template:
+            self._validate_variables(state_variables)
+            message_kwargs = {key: state_variables[key] for key in self.variable_keys}
+            formatted_message = formatted_message.format(**message_kwargs)
+        elif state_variables:
+            raise ValueError("State variables can only be provided if `is_template` is set to True.")
+
+        await event_emitter.emit(formatted_message, **emit_kwargs)
+
+    def _validate_variables(self, variables: dict[str, Any]) -> None:
+        """Validates the variables to ensure there are no missing keys.
+
+        This method checks if the provided variables are missing any of the expected keys. If so, it raises a
+        `ValueError`.
+
+        Args:
+            variables (dict[str, Any]): The variables to be validated.
+
+        Raises:
+            ValueError: If the variables are missing the expected keys.
+        """
+        missing_keys = set(self.variable_keys) - set(variables.keys())
+        if missing_keys:
+            raise ValueError(f"The following keys are missing in the variables: {missing_keys}")

gllm_core/event/messenger.pyi

@@ -0,0 +1,66 @@
+from _typeshed import Incomplete
+from gllm_core.event import EventEmitter as EventEmitter
+from gllm_core.schema import Component as Component
+from gllm_core.utils import get_placeholder_keys as get_placeholder_keys
+from typing import Any
+
+class Messenger(Component):
+    '''Emits a custom event message with possible access to the state variables.
+
+    This component acts as an intermediary step, designed to be placed between other pipeline steps.
+    It allows for event messaging operations to be performed outside individual components but still within
+    the context of the pipeline execution.
+
+    Attributes:
+        message (str): The message to be sent, may contain placeholders enclosed in curly braces `{}`.
+        is_template (bool): Whether the message is a template that can be injected with state variables.
+            Defaults to True.
+        variable_keys (list[str]): The keys of the message that can be injected with state variables.
+            Only used if `is_template` is set to True.
+
+    Plain string message example:
+    ```python
+    event_emitter = EventEmitter(handlers=[ConsoleEventHandler()])
+    kwargs = {"event_emitter": event_emitter}
+
+    messenger = Messenger("Executing component.", is_template=False)
+    await messenger.run(**kwargs)
+    ```
+
+    Template message example:
+    ```python
+    event_emitter = EventEmitter(handlers=[ConsoleEventHandler()])
+    state_variables = {"query": "Hi!", "top_k": 10}
+    kwargs = {"event_emitter": event_emitter, "state_variables": state_variables}
+
+    messenger = Messenger("Executing component for query {query} and top k {top_k}.")
+    await messenger.run(**kwargs)
+    ```
+    '''
+    message: Incomplete
+    is_template: Incomplete
+    variable_keys: Incomplete
+    def __init__(self, message: str, is_template: bool = True) -> None:
+        """Initializes a new instance of the Messenger class.
+
+        Args:
+            message (str): The message to be sent, may contain placeholders enclosed in curly braces `{}`.
+            is_template (bool, optional): Whether the message is a template that can be injected with state variables.
+                Defaults to True.
+
+        Raises:
+            ValueError: If the keys of the message does not match the provided keys.
+        """
+    async def send_message(self, event_emitter: EventEmitter, state_variables: dict[str, Any] | None = None, emit_kwargs: dict[str, Any] | None = None) -> None:
+        """Emits the message to the event emitter.
+
+        This method validates the variables, formats the message if required, and then emits the message using the
+        event emitter.
+
+        Args:
+            event_emitter (EventEmitter): The event emitter instance to emit the message.
+            state_variables (dict[str, Any] | None, optional): The state variables to be injected into the message
+                placeholders. Can only be provided if `is_template` is set to True. Defaults to None.
+            emit_kwargs (dict[str, Any] | None, optional): The keyword arguments to be passed to the event emitter's
+                emit method. Defaults to None.
+        """

gllm_core/schema/__init__.py

@@ -0,0 +1,8 @@
+"""Modules concerning the schemas used throughout the Gen AI applications."""
+
+from gllm_core.schema.chunk import Chunk
+from gllm_core.schema.component import Component, main
+from gllm_core.schema.event import Event
+from gllm_core.schema.tool import Tool, tool
+
+__all__ = ["Chunk", "Component", "Event", "Tool", "main", "tool"]

gllm_core/schema/__init__.pyi

@@ -0,0 +1,6 @@
+from gllm_core.schema.chunk import Chunk as Chunk
+from gllm_core.schema.component import Component as Component, main as main
+from gllm_core.schema.event import Event as Event
+from gllm_core.schema.tool import Tool as Tool, tool as tool
+
+__all__ = ['Chunk', 'Component', 'Event', 'Tool', 'main', 'tool']

gllm_core/schema/chunk.py

@@ -0,0 +1,148 @@
+"""Defines the Chunk schema, which represents a chunk of content retrieved from a vector store.
+
+Authors:
+    Dimitrij Ray (dimitrij.ray@gdplabs.id)
+
+References:
+    NONE
+"""
+
+from typing import Any, Generic, Iterable, TypeVar
+from uuid import uuid4
+
+from pydantic import BaseModel, Field, field_validator
+
+MAX_PREVIEW_LENGTH = 50
+MAX_ITEMS_PREVIEW = 3
+
+T = TypeVar("T")
+
+
+class _TruncatedIterable(Generic[T]):
+    """Represents a truncated iterable with first and last elements visible.
+
+    Attributes:
+        items (Iterable[T]): The iterable to be truncated.
+        max_items_preview (int): Maximum number of items to show before truncation.
+    """
+
+    def __init__(self, items: Iterable[T], max_items_preview: int = MAX_ITEMS_PREVIEW) -> None:
+        """Initialize a TruncatedIterable.
+
+        Args:
+            items (Iterable[T]): The iterable to be truncated.
+            max_items_preview (int, optional): Maximum number of items to show before truncation.
+                Defaults to MAX_ITEMS_PREVIEW.
+        """
+        self.items = list(items)
+        self.max_items_preview = max_items_preview
+
+    def __repr__(self) -> str:
+        """Return a string representation of the truncated iterable.
+
+        Returns:
+            str: The string representation in the format [first, ..., last] if truncated,
+                 or [item1, item2, ...] if not truncated.
+        """
+        if len(self.items) <= self.max_items_preview:
+            return str(self.items)
+
+        def format_element(elem: Any) -> str:
+            return f"{elem!r}"
+
+        first_item = format_element(self.items[0])
+        last_item = format_element(self.items[-1])
+        return f"[{first_item}, ..., {last_item}]"
+
+
+class Chunk(BaseModel, arbitrary_types_allowed=True):
+    """Represents a chunk of content retrieved from a vector store.
+
+    Attributes:
+        id (str): A unique identifier for the chunk. Defaults to a random UUID.
+        content (str | bytes): The content of the chunk, either text or binary.
+        metadata (dict[str, Any]): Additional metadata associated with the chunk. Defaults to an empty dictionary.
+        score (float | None): Similarity score of the chunk (if available). Defaults to None.
+    """
+
+    id: str = Field(default_factory=lambda: str(uuid4()))
+    content: str | bytes
+    metadata: dict[str, Any] = Field(default_factory=dict)
+    score: float | None = None
+
+    @field_validator("content")
+    @classmethod
+    def validate_content(cls, value: str | bytes) -> str | bytes:
+        """Validate the content of the Chunk.
+
+        This is a class method required by Pydantic validators. As such, it follows its signature and conventions.
+
+        Args:
+            value (str | bytes): The content to validate.
+
+        Returns:
+            str | bytes: The validated content.
+
+        Raises:
+            ValueError: If the content is empty or not a string or bytes.
+        """
+        if not value:
+            raise ValueError("Content must not be empty")
+        if not isinstance(value, (str, bytes)):
+            raise ValueError("Content must be either str or bytes")
+        return value
+
+    def is_text(self) -> bool:
+        """Check if the content is text.
+
+        Returns:
+            bool: True if the content is text, False otherwise.
+        """
+        return isinstance(self.content, str)
+
+    def is_binary(self) -> bool:
+        """Check if the content is binary.
+
+        Returns:
+            bool: True if the content is binary, False otherwise.
+        """
+        return isinstance(self.content, bytes)
+
+    def _format_value(self, value: Any) -> Any:
+        """Format a value for string representation.
+
+        Args:
+            value (Any): The value to format.
+
+        Returns:
+            Any: The formatted value.
+        """
+        if isinstance(value, str):
+            return f"{value[:MAX_PREVIEW_LENGTH]}{'...' if len(value) > MAX_PREVIEW_LENGTH else ''}"
+
+        if isinstance(value, bytes):
+            return "(Binary content)"
+
+        if isinstance(value, (list, tuple)):
+            return _TruncatedIterable(value)
+
+        if isinstance(value, dict):
+            return {k: self._format_value(v) for k, v in value.items()}
+
+        return value
+
+    def __repr__(self) -> str:
+        """Return a string representation of the Chunk.
+
+        Returns:
+            str: The string representation of the Chunk.
+        """
+        content_preview = self._format_value(self.content)
+        formatted_metadata = self._format_value(self.metadata)
+
+        return (
+            f"Chunk(id={self.id}, "
+            f"content={content_preview}, "
+            f"metadata={formatted_metadata}, "
+            f"score={self.score})"
+        )

gllm_core/schema/chunk.pyi

@@ -0,0 +1,66 @@
+from _typeshed import Incomplete
+from pydantic import BaseModel
+from typing import Any, Generic, Iterable, TypeVar
+
+MAX_PREVIEW_LENGTH: int
+MAX_ITEMS_PREVIEW: int
+T = TypeVar('T')
+
+class _TruncatedIterable(Generic[T]):
+    """Represents a truncated iterable with first and last elements visible.
+
+    Attributes:
+        items (Iterable[T]): The iterable to be truncated.
+        max_items_preview (int): Maximum number of items to show before truncation.
+    """
+    items: Incomplete
+    max_items_preview: Incomplete
+    def __init__(self, items: Iterable[T], max_items_preview: int = ...) -> None:
+        """Initialize a TruncatedIterable.
+
+        Args:
+            items (Iterable[T]): The iterable to be truncated.
+            max_items_preview (int, optional): Maximum number of items to show before truncation.
+                Defaults to MAX_ITEMS_PREVIEW.
+        """
+
+class Chunk(BaseModel, arbitrary_types_allowed=True):
+    """Represents a chunk of content retrieved from a vector store.
+
+    Attributes:
+        id (str): A unique identifier for the chunk. Defaults to a random UUID.
+        content (str | bytes): The content of the chunk, either text or binary.
+        metadata (dict[str, Any]): Additional metadata associated with the chunk. Defaults to an empty dictionary.
+        score (float | None): Similarity score of the chunk (if available). Defaults to None.
+    """
+    id: str
+    content: str | bytes
+    metadata: dict[str, Any]
+    score: float | None
+    @classmethod
+    def validate_content(cls, value: str | bytes) -> str | bytes:
+        """Validate the content of the Chunk.
+
+        This is a class method required by Pydantic validators. As such, it follows its signature and conventions.
+
+        Args:
+            value (str | bytes): The content to validate.
+
+        Returns:
+            str | bytes: The validated content.
+
+        Raises:
+            ValueError: If the content is empty or not a string or bytes.
+        """
+    def is_text(self) -> bool:
+        """Check if the content is text.
+
+        Returns:
+            bool: True if the content is text, False otherwise.
+        """
+    def is_binary(self) -> bool:
+        """Check if the content is binary.
+
+        Returns:
+            bool: True if the content is binary, False otherwise.
+        """