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

gllm_core/__init__.py

@@ -0,0 +1 @@
+"""Provides fundamental components and utilities."""

gllm_core/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Adapters for external formats."""
+
+from gllm_core.adapters.tool import from_google_function, from_langchain_tool
+
+__all__ = ["from_google_function", "from_langchain_tool"]

gllm_core/adapters/__init__.pyi

@@ -0,0 +1,3 @@
+from gllm_core.adapters.tool import from_google_function as from_google_function, from_langchain_tool as from_langchain_tool
+
+__all__ = ['from_google_function', 'from_langchain_tool']

gllm_core/adapters/tool/__init__.py

@@ -0,0 +1,6 @@
+"""Tool adapters for external formats."""
+
+from gllm_core.adapters.tool.google_adk import from_google_function
+from gllm_core.adapters.tool.langchain import from_langchain_tool
+
+__all__ = ["from_langchain_tool", "from_google_function"]

gllm_core/adapters/tool/__init__.pyi

@@ -0,0 +1,4 @@
+from gllm_core.adapters.tool.google_adk import from_google_function as from_google_function
+from gllm_core.adapters.tool.langchain import from_langchain_tool as from_langchain_tool
+
+__all__ = ['from_langchain_tool', 'from_google_function']

gllm_core/adapters/tool/google_adk.py

@@ -0,0 +1,91 @@
+"""Google ADK tool adapter conversions.
+
+Authors:
+    Dimitrij Ray (dimitrij.ray@gdplabs.id)
+
+References:
+    NONE
+"""
+
+import asyncio
+from typing import Any, Callable
+
+from gllm_core.schema.tool import Tool
+
+_DEFAULT_SCHEMA: dict[str, Any] = {"type": "object", "properties": {}}
+
+
+def _validate_and_extract_schema(parameters: Any) -> dict[str, Any]:
+    """Validate and extract the input schema from Google ADK parameters.
+
+    Args:
+        parameters (Any): The parameters from the Google ADK function declaration.
+
+    Returns:
+        dict[str, Any]: The validated input schema.
+
+    Raises:
+        TypeError: If the schema has invalid structure.
+    """
+    if parameters is None:
+        return _DEFAULT_SCHEMA.copy()
+
+    if isinstance(parameters, dict):
+        if "properties" in parameters and not isinstance(parameters.get("properties"), dict):
+            raise TypeError("Google ADK function schema 'properties' must be a dictionary.")
+        return parameters
+
+    return dict(parameters) if hasattr(parameters, "__iter__") else _DEFAULT_SCHEMA.copy()
+
+
+def from_google_function(function_declaration: Any, func: Callable | None = None) -> Tool:
+    """Convert a Google ADK function declaration into the SDK Tool representation.
+
+    The Google ADK `FunctionDeclaration` provides access to:
+    1. `name`: The function name
+    2. `description`: The function description
+    3. `parameters`: A dict in JSON Schema format (OpenAPI 3.0 compatible)
+
+    Args:
+        function_declaration (Any): The Google ADK function declaration to convert.
+        func (Callable | None, optional): The implementation function for the tool. Defaults to None.
+
+    Returns:
+        Tool: The converted SDK tool.
+
+    Raises:
+        ValueError: If the function declaration is None or has invalid fields.
+        AttributeError: If required attributes are missing.
+        TypeError: If field types are incorrect.
+    """
+    if function_declaration is None:
+        raise ValueError("Google ADK function declaration cannot be None.")
+
+    for attr in ("name", "description"):
+        if not hasattr(function_declaration, attr):
+            raise AttributeError(f"Google ADK function declaration must have a {attr!r} attribute.")
+
+    name = function_declaration.name
+    description = function_declaration.description
+
+    if not isinstance(name, str) or not name:
+        raise ValueError("Google ADK function 'name' must be a non-empty string.")
+
+    if description is not None and not isinstance(description, str):
+        raise TypeError("Google ADK function 'description' must be a string when provided.")
+
+    if func is not None and not callable(func):
+        raise TypeError("Google ADK tool implementation must be callable when provided.")
+
+    parameters = getattr(function_declaration, "parameters", None)
+    input_schema = _validate_and_extract_schema(parameters)
+
+    is_async = asyncio.iscoroutinefunction(func) if func else False
+
+    return Tool(
+        name=name,
+        description=description,
+        input_schema=input_schema,
+        func=func,
+        is_async=is_async,
+    )

gllm_core/adapters/tool/google_adk.pyi

@@ -0,0 +1,23 @@
+from gllm_core.schema.tool import Tool as Tool
+from typing import Any, Callable
+
+def from_google_function(function_declaration: Any, func: Callable | None = None) -> Tool:
+    """Convert a Google ADK function declaration into the SDK Tool representation.
+
+    The Google ADK `FunctionDeclaration` provides access to:
+    1. `name`: The function name
+    2. `description`: The function description
+    3. `parameters`: A dict in JSON Schema format (OpenAPI 3.0 compatible)
+
+    Args:
+        function_declaration (Any): The Google ADK function declaration to convert.
+        func (Callable | None, optional): The implementation function for the tool. Defaults to None.
+
+    Returns:
+        Tool: The converted SDK tool.
+
+    Raises:
+        ValueError: If the function declaration is None or has invalid fields.
+        AttributeError: If required attributes are missing.
+        TypeError: If field types are incorrect.
+    """

gllm_core/adapters/tool/langchain.py

@@ -0,0 +1,130 @@
+"""LangChain tool adapter conversions.
+
+Authors:
+    Dimitrij Ray (dimitrij.ray@gdplabs.id)
+
+References:
+    NONE
+"""
+
+import asyncio
+from typing import Any, Callable
+
+from gllm_core.schema.tool import Tool
+
+
+class LangChainToolKeys:
+    """Constants for LangChain tool attribute keys."""
+
+    FUNC = "func"
+    COROUTINE = "coroutine"
+    RUN = "_run"
+    ARUN = "_arun"
+    NAME = "name"
+    DESCRIPTION = "description"
+    ARGS_SCHEMA = "args_schema"
+
+
+LANGCHAIN_FUNCTION_ATTRS = (
+    LangChainToolKeys.FUNC,
+    LangChainToolKeys.COROUTINE,
+    LangChainToolKeys.RUN,
+    LangChainToolKeys.ARUN,
+)
+
+
+def _extract_attribute(tool: Any, attr_name: str) -> Any:
+    """Extract an attribute from a LangChain tool.
+
+    A LangChain tool can be either a dictionary-like object or an object with attributes.
+    This function handles both cases:
+        1. If the tool has the attribute as an attribute, it returns the attribute value.
+        2. If the tool has the attribute as a key (is a dictionary-like object), it returns the key value.
+        3. Otherwise, it returns None.
+
+    Args:
+        tool (Any): The LangChain tool to extract the attribute from.
+        attr_name (str): The attribute name to extract.
+
+    Returns:
+        Any: The attribute value, or None if not found.
+    """
+    if hasattr(tool, attr_name):
+        return getattr(tool, attr_name)
+
+    if hasattr(tool, "get"):
+        return tool.get(attr_name)
+
+    return None
+
+
+def _get_langchain_tool_func(tool: Any) -> Callable | None:
+    """Gets the function from a LangChain tool.
+
+    This function extracts the appropriate callable from a LangChain tool, with the following priority:
+        1. func
+        2. coroutine
+        3. _run
+        4. _arun
+
+    Args:
+        tool (Any): The LangChain tool to extract the function from.
+
+    Returns:
+        Callable | None: The extracted function, or None if no function is found.
+    """
+    for func_key in LANGCHAIN_FUNCTION_ATTRS:
+        func = _extract_attribute(tool, func_key)
+        if callable(func):
+            return func
+
+    return None
+
+
+def _get_input_schema(tool: Any) -> dict[str, Any]:
+    """Get input schema from a LangChain tool.
+
+    Args:
+        tool (Any): The LangChain tool to get schema from.
+
+    Returns:
+        dict[str, Any]: The input schema, or default empty schema if none found.
+    """
+    input_schema = _extract_attribute(tool, LangChainToolKeys.ARGS_SCHEMA)
+
+    return input_schema if input_schema is not None else {"type": "object", "properties": {}}
+
+
+def from_langchain_tool(langchain_tool: Any) -> Tool:
+    """Convert a LangChain tool into the SDK Tool representation.
+
+    This function handles both traditional LangChain tools created with the @tool decorator
+    and tools created by subclassing the LangChain Tool class.
+
+    Args:
+        langchain_tool (Any): The LangChain tool to convert.
+
+    Returns:
+        Tool: The converted SDK tool.
+
+    Raises:
+        ValueError: If the input is not a valid LangChain tool.
+    """
+    name = _extract_attribute(langchain_tool, LangChainToolKeys.NAME)
+    if not name:
+        raise ValueError("LangChain tool must have a 'name' attribute or key.")
+
+    description = _extract_attribute(langchain_tool, LangChainToolKeys.DESCRIPTION)
+    if not description:
+        raise ValueError("LangChain tool must have a 'description' attribute or key.")
+
+    func = _get_langchain_tool_func(langchain_tool)
+    input_schema = _get_input_schema(langchain_tool)
+
+    return Tool(
+        name=name,
+        description=description,
+        input_schema=input_schema,
+        func=func,
+        is_async=asyncio.iscoroutinefunction(func) if func is not None else False,
+    )

gllm_core/adapters/tool/langchain.pyi

@@ -0,0 +1,31 @@
+from _typeshed import Incomplete
+from gllm_core.schema.tool import Tool as Tool
+from typing import Any
+
+class LangChainToolKeys:
+    """Constants for LangChain tool attribute keys."""
+    FUNC: str
+    COROUTINE: str
+    RUN: str
+    ARUN: str
+    NAME: str
+    DESCRIPTION: str
+    ARGS_SCHEMA: str
+
+LANGCHAIN_FUNCTION_ATTRS: Incomplete
+
+def from_langchain_tool(langchain_tool: Any) -> Tool:
+    """Convert a LangChain tool into the SDK Tool representation.
+
+    This function handles both traditional LangChain tools created with the @tool decorator
+    and tools created by subclassing the LangChain Tool class.
+
+    Args:
+        langchain_tool (Any): The LangChain tool to convert.
+
+    Returns:
+        Tool: The converted SDK tool.
+
+    Raises:
+        ValueError: If the input is not a valid LangChain tool.
+    """

gllm_core/constants.py

@@ -0,0 +1,55 @@
+"""Contains constants used throughout the gllm_core package.
+
+Authors:
+    Henry Wicaksono (henry.wicaksono@gdplabs.id)
+
+References:
+    NONE
+"""
+
+from enum import IntEnum, StrEnum
+
+
+class EventLevel(IntEnum):
+    """Defines event levels for the event emitter module."""
+
+    TRACE = 0
+    DEBUG = 1
+    INFO = 2
+    WARN = 3
+    ERROR = 4
+    FATAL = 5
+
+
+class EventType(StrEnum):
+    """Defines event types for the event emitter module."""
+
+    ACTIVITY = "activity"
+    CODE = "code"
+    REFERENCE = "reference"
+    RESPONSE = "response"
+    STATUS = "status"
+    THINKING = "thinking"
+
+
+class EventTypeSuffix(StrEnum):
+    """Defines suffixes for block based event types."""
+
+    START = "_start"
+    END = "_end"
+
+
+class DefaultChunkMetadata:
+    """Defines constants for default chunk metadata keys."""
+
+    CHUNK_ID = "chunk_id"
+    PREV_CHUNK_ID = "previous_chunk"
+    NEXT_CHUNK_ID = "next_chunk"
+
+
+class LogMode(StrEnum):
+    """Defines supported log modes for the SDK logging system."""
+
+    TEXT = "text"
+    SIMPLE = "simple"
+    JSON = "json"

gllm_core/constants.pyi

@@ -0,0 +1,36 @@
+from enum import IntEnum, StrEnum
+
+class EventLevel(IntEnum):
+    """Defines event levels for the event emitter module."""
+    TRACE = 0
+    DEBUG = 1
+    INFO = 2
+    WARN = 3
+    ERROR = 4
+    FATAL = 5
+
+class EventType(StrEnum):
+    """Defines event types for the event emitter module."""
+    ACTIVITY = 'activity'
+    CODE = 'code'
+    REFERENCE = 'reference'
+    RESPONSE = 'response'
+    STATUS = 'status'
+    THINKING = 'thinking'
+
+class EventTypeSuffix(StrEnum):
+    """Defines suffixes for block based event types."""
+    START = '_start'
+    END = '_end'
+
+class DefaultChunkMetadata:
+    """Defines constants for default chunk metadata keys."""
+    CHUNK_ID: str
+    PREV_CHUNK_ID: str
+    NEXT_CHUNK_ID: str
+
+class LogMode(StrEnum):
+    """Defines supported log modes for the SDK logging system."""
+    TEXT = 'text'
+    SIMPLE = 'simple'
+    JSON = 'json'

gllm_core/event/__init__.py

@@ -0,0 +1,6 @@
+"""Modules concerning the event handling system used throughout the Gen AI applications."""
+
+from gllm_core.event.event_emitter import EventEmitter
+from gllm_core.event.messenger import Messenger
+
+__all__ = ["EventEmitter", "Messenger"]

gllm_core/event/__init__.pyi

@@ -0,0 +1,4 @@
+from gllm_core.event.event_emitter import EventEmitter as EventEmitter
+from gllm_core.event.messenger import Messenger as Messenger
+
+__all__ = ['EventEmitter', 'Messenger']

gllm_core/event/event_emitter.py

@@ -0,0 +1,211 @@
+"""Defines the event emitter module used throughout the Gen AI applications.
+
+Authors:
+    Henry Wicaksono (henry.wicaksono@gdplabs.id)
+
+References:
+    NONE
+"""
+
+from typing import AsyncGenerator
+
+from gllm_core.constants import EventLevel
+from gllm_core.event.handler import ConsoleEventHandler, PrintEventHandler, StreamEventHandler
+from gllm_core.event.handler.event_handler import BaseEventHandler
+from gllm_core.event.hook.event_hook import BaseEventHook
+from gllm_core.schema import Event
+from gllm_core.utils import validate_string_enum
+
+
+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)
+        ```
+    """
+
+    def __init__(
+        self,
+        handlers: list[BaseEventHandler],
+        event_level: EventLevel = EventLevel.INFO,
+        hooks: list[BaseEventHook] | 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.
+        """
+        if not handlers:
+            raise ValueError("The event handlers can not be empty.")
+
+        validate_string_enum(EventLevel, event_level)
+
+        self.handlers = handlers
+        self.severity = event_level
+        self.hooks = hooks or []
+
+    @classmethod
+    def with_console_handler(
+        cls, event_level: EventLevel = EventLevel.INFO, 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.
+        """
+        return cls(handlers=[ConsoleEventHandler()], event_level=event_level, hooks=hooks)
+
+    @classmethod
+    def with_print_handler(
+        cls, event_level: EventLevel = EventLevel.INFO, 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.
+        """
+        return cls(handlers=[PrintEventHandler()], event_level=event_level, hooks=hooks)
+
+    @classmethod
+    def with_stream_handler(
+        cls, event_level: EventLevel = EventLevel.INFO, 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.
+        """
+        return cls(handlers=[StreamEventHandler()], event_level=event_level, hooks=hooks)
+
+    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.
+        """
+        if event.level < self.severity:
+            return
+
+        for hook in self.hooks:
+            event = await hook(event)
+
+        disabled_handlers = disabled_handlers or []
+        for handler in self.handlers:
+            if handler.name not in disabled_handlers:
+                await handler.emit(event)
+
+    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
+        """
+        for handler in self.handlers:
+            await handler.close()
+
+    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.
+        """
+        stream_handlers = [handler for handler in self.handlers if isinstance(handler, StreamEventHandler)]
+
+        if len(stream_handlers) != 1:
+            raise ValueError(
+                f"The event emitter must have exactly one stream handler. Found {len(stream_handlers)} instances."
+            )
+
+        return stream_handlers[0].stream()