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

gllm_core/utils/concurrency.py

@@ -0,0 +1,184 @@
+"""Concurrency utilities for bridging sync and async code.
+
+This module provides two primary helpers:
+
+1. asyncify: Wrap a synchronous function so it can be awaited in async code
+   by offloading it to a worker thread using AnyIO.
+2. syncify: Wrap an asynchronous function so it can be called from synchronous
+   code. By default, this uses a shared AnyIO BlockingPortal running in a
+   background thread.
+
+Usage:
+    ```python
+    from gllm_core.utils.concurrency import asyncify, syncify
+
+    # Asyncify a sync function
+    async_op = asyncify(blocking_fn)
+    result = await async_op(arg1, arg2)
+
+    # Syncify an async function
+    sync_op = syncify(async_fn)
+    result = sync_op(arg1, arg2)
+    ```
+
+Notes:
+1. For asyncify: Cancelling an await of an asyncified sync function cancels the awaiter, but
+   the underlying thread cannot be forcibly interrupted. The function continues to run until it returns.
+2. For syncify: A shared default BlockingPortal is lazily created on first use and shut down
+   at process exit.
+
+Authors:
+    Dimitrij Ray (dimitrij.ray@gdplabs.id)
+
+References:
+    NONE
+"""
+
+from __future__ import annotations
+
+import atexit
+import threading
+from typing import Awaitable, Callable, ContextManager, ParamSpec, TypeVar
+
+import anyio
+from anyio.abc import BlockingPortal
+from anyio.from_thread import start_blocking_portal
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+class _DefaultPortalManager:
+    """Lazily manages a process-wide AnyIO BlockingPortal.
+
+    The portal runs an event loop in a background thread started via
+    anyio.from_thread.start_blocking_portal(). It is created on first access and stopped
+    automatically at interpreter shutdown.
+    """
+
+    _lock: threading.Lock
+    _portal: BlockingPortal | None
+    _cm: ContextManager[BlockingPortal] | None
+
+    def __init__(self) -> None:
+        """Initialize the default portal manager."""
+        self._lock = threading.Lock()
+        self._portal = None
+        self._cm = None
+
+    def get(self) -> BlockingPortal:
+        """Return the shared BlockingPortal, creating it if necessary.
+
+        This method is thread-safe: concurrent callers will see the same portal.
+
+        Returns:
+            BlockingPortal: The shared default portal.
+        """
+        with self._lock:
+            portal = self._portal
+            if portal is None:
+                cm = start_blocking_portal()
+                portal = cm.__enter__()
+
+                atexit.register(cm.__exit__, None, None, None)
+
+                self._cm = cm
+                self._portal = portal
+
+            return portal
+
+
+_default_portal_mgr = _DefaultPortalManager()
+
+
+def get_default_portal() -> BlockingPortal:
+    """Return the shared default BlockingPortal.
+
+    Returns:
+        BlockingPortal: A process-wide portal running on a background thread.
+    """
+    return _default_portal_mgr.get()
+
+
+def asyncify(
+    func: Callable[P, R], *, cancellable: bool = False, limiter: anyio.CapacityLimiter | None = None
+) -> Callable[P, Awaitable[R]]:
+    """Wrap a sync function into an awaitable callable using a worker thread.
+
+    Args:
+        func (Callable[P, R]): Synchronous function to wrap.
+        cancellable (bool, optional): If True, allow cancellation of the awaiter while running in a
+            worker thread. Defaults to False.
+        limiter (anyio.CapacityLimiter | None, optional): Capacity limiter to throttle concurrent
+            thread usage. Defaults to None.
+
+    Returns:
+        Callable[P, Awaitable[R]]: An async function that when awaited will execute `func` in a
+        worker thread and return its result.
+
+    Usage:
+        ```python
+        async def handler() -> int:
+            wrapped = asyncify(blocking_func)
+            return await wrapped(1, 2)
+        ```
+    """
+
+    async def _wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        return await anyio.to_thread.run_sync(lambda: func(*args, **kwargs), abandon_on_cancel=cancellable, limiter=limiter)
+
+    return _wrapper
+
+
+def syncify(
+    async_func: Callable[P, Awaitable[R]],
+    *,
+    portal: BlockingPortal | None = None,
+) -> Callable[P, R]:
+    """Wrap an async function to be callable from synchronous code.
+
+    Lifecycle and portals:
+    1. This helper uses an already running AnyIO `BlockingPortal` to execute the coroutine.
+    2. If `portal` is not provided, a process-wide shared portal is used. Its lifecycle is
+      managed internally: it is created lazily on first use and shut down automatically at process exit.
+    3. If you provide a `portal`, you are expected to manage its lifecycle, typically with a
+      context manager. This is recommended when making many calls in a bounded scope since it
+      avoids per-call startup costs while allowing deterministic teardown.
+
+    Args:
+        async_func (Callable[P, Awaitable[R]]): Asynchronous function to wrap.
+        portal (BlockingPortal | None, optional): Portal to use for calling the async function
+            from sync code. Defaults to None, in which case a shared default portal is used.
+
+    Returns:
+        Callable[P, R]: A synchronous function that runs the coroutine and returns its result.
+
+    Usage:
+        ```python
+        # Use the default shared portal (most convenient)
+        def do_work(x: int) -> int:
+            sync_call = syncify(async_func)
+            return sync_call(x)
+        ```
+
+        ```python
+        # Reuse a scoped portal for multiple calls (deterministic lifecycle)
+        from anyio.from_thread import start_blocking_portal
+
+        with start_blocking_portal() as portal:
+            sync_call = syncify(async_func, portal=portal)
+            a = sync_call(1)
+            b = sync_call(2)
+        ```
+
+    Notes:
+        Creating a brand-new portal per call is discouraged due to the overhead of spinning up
+        and tearing down a background event loop/thread. Prefer the shared portal or a scoped
+        portal reused for a batch of calls.
+    """
+
+    def _wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        p: BlockingPortal = portal if portal is not None else get_default_portal()
+        return p.call(lambda: async_func(*args, **kwargs))
+
+    return _wrapper

gllm_core/utils/concurrency.pyi

@@ -0,0 +1,94 @@
+import anyio
+from anyio.abc import BlockingPortal as BlockingPortal
+from typing import Awaitable, Callable, ParamSpec, TypeVar
+
+P = ParamSpec('P')
+R = TypeVar('R')
+
+class _DefaultPortalManager:
+    """Lazily manages a process-wide AnyIO BlockingPortal.
+
+    The portal runs an event loop in a background thread started via
+    anyio.from_thread.start_blocking_portal(). It is created on first access and stopped
+    automatically at interpreter shutdown.
+    """
+    def __init__(self) -> None:
+        """Initialize the default portal manager."""
+    def get(self) -> BlockingPortal:
+        """Return the shared BlockingPortal, creating it if necessary.
+
+        This method is thread-safe: concurrent callers will see the same portal.
+
+        Returns:
+            BlockingPortal: The shared default portal.
+        """
+
+def get_default_portal() -> BlockingPortal:
+    """Return the shared default BlockingPortal.
+
+    Returns:
+        BlockingPortal: A process-wide portal running on a background thread.
+    """
+def asyncify(func: Callable[P, R], *, cancellable: bool = False, limiter: anyio.CapacityLimiter | None = None) -> Callable[P, Awaitable[R]]:
+    """Wrap a sync function into an awaitable callable using a worker thread.
+
+    Args:
+        func (Callable[P, R]): Synchronous function to wrap.
+        cancellable (bool, optional): If True, allow cancellation of the awaiter while running in a
+            worker thread. Defaults to False.
+        limiter (anyio.CapacityLimiter | None, optional): Capacity limiter to throttle concurrent
+            thread usage. Defaults to None.
+
+    Returns:
+        Callable[P, Awaitable[R]]: An async function that when awaited will execute `func` in a
+        worker thread and return its result.
+
+    Usage:
+        ```python
+        async def handler() -> int:
+            wrapped = asyncify(blocking_func)
+            return await wrapped(1, 2)
+        ```
+    """
+def syncify(async_func: Callable[P, Awaitable[R]], *, portal: BlockingPortal | None = None) -> Callable[P, R]:
+    """Wrap an async function to be callable from synchronous code.
+
+    Lifecycle and portals:
+    1. This helper uses an already running AnyIO `BlockingPortal` to execute the coroutine.
+    2. If `portal` is not provided, a process-wide shared portal is used. Its lifecycle is
+      managed internally: it is created lazily on first use and shut down automatically at process exit.
+    3. If you provide a `portal`, you are expected to manage its lifecycle, typically with a
+      context manager. This is recommended when making many calls in a bounded scope since it
+      avoids per-call startup costs while allowing deterministic teardown.
+
+    Args:
+        async_func (Callable[P, Awaitable[R]]): Asynchronous function to wrap.
+        portal (BlockingPortal | None, optional): Portal to use for calling the async function
+            from sync code. Defaults to None, in which case a shared default portal is used.
+
+    Returns:
+        Callable[P, R]: A synchronous function that runs the coroutine and returns its result.
+
+    Usage:
+        ```python
+        # Use the default shared portal (most convenient)
+        def do_work(x: int) -> int:
+            sync_call = syncify(async_func)
+            return sync_call(x)
+        ```
+
+        ```python
+        # Reuse a scoped portal for multiple calls (deterministic lifecycle)
+        from anyio.from_thread import start_blocking_portal
+
+        with start_blocking_portal() as portal:
+            sync_call = syncify(async_func, portal=portal)
+            a = sync_call(1)
+            b = sync_call(2)
+        ```
+
+    Notes:
+        Creating a brand-new portal per call is discouraged due to the overhead of spinning up
+        and tearing down a background event loop/thread. Prefer the shared portal or a scoped
+        portal reused for a batch of calls.
+    """

gllm_core/utils/event_formatter.py

@@ -0,0 +1,69 @@
+"""Defines helper functions to format logged events.
+
+Authors:
+    Henry Wicaksono (henry.wicaksono@gdplabs.id)
+
+References:
+    NONE
+"""
+
+import re
+
+from gllm_core.schema import Chunk
+from gllm_core.schema.chunk import MAX_PREVIEW_LENGTH
+
+TEMPLATE_VALIDATOR_REGEX = re.compile(r"(?<!\{)\{(?!\{)(.*?)(?<!\})\}(?!\})")
+
+
+def format_chunk_message(
+    chunk: Chunk,
+    rank: int = None,
+    include_score: bool = True,
+    include_metadata: bool = True,
+) -> str:
+    """Formats a log to display a single chunk.
+
+    Args:
+        chunk (Chunk): The chunk to be formatted.
+        rank (int, optional): The optional rank of the formatted chunk. Defaults to None.
+        include_score (bool, optional): Whether to include the score in the formatted message. Defaults to True.
+        include_metadata (bool, optional): Whether to include the metadata in the formatted message. Defaults to True.
+
+    Returns:
+        str: A formatted log message that displays information about the logged chunk.
+    """
+    content_preview = chunk.content[:MAX_PREVIEW_LENGTH]
+    if len(chunk.content) > MAX_PREVIEW_LENGTH:
+        content_preview = f"{content_preview}..."
+
+    message = f"ID: {chunk.id}\n    Content: {content_preview}"
+
+    if chunk.score is not None and include_score:
+        message += f"\n    Score: {chunk.score}"
+
+    if chunk.metadata and include_metadata:
+        message += "\n    Metadata:"
+        for key, value in chunk.metadata.items():
+            message += f"\n      - {key}: {value}"
+
+    if rank:
+        message = f"Rank: {rank}\n    {message}"
+
+    message = f"\n  - {message}"
+
+    return message
+
+
+def get_placeholder_keys(template: str) -> list[str]:
+    """Extracts keys from a template string based on a regex pattern.
+
+    This function searches the template for placeholders enclosed in single curly braces `{}` and ignores
+    any placeholders within double curly braces `{{}}`. It returns a list of the keys found.
+
+    Args:
+        template (str): The template string containing placeholders.
+
+    Returns:
+        list[str]: A list of keys extracted from the template.
+    """
+    return TEMPLATE_VALIDATOR_REGEX.findall(template)

gllm_core/utils/event_formatter.pyi

@@ -0,0 +1,30 @@
+from _typeshed import Incomplete
+from gllm_core.schema import Chunk as Chunk
+from gllm_core.schema.chunk import MAX_PREVIEW_LENGTH as MAX_PREVIEW_LENGTH
+
+TEMPLATE_VALIDATOR_REGEX: Incomplete
+
+def format_chunk_message(chunk: Chunk, rank: int = None, include_score: bool = True, include_metadata: bool = True) -> str:
+    """Formats a log to display a single chunk.
+
+    Args:
+        chunk (Chunk): The chunk to be formatted.
+        rank (int, optional): The optional rank of the formatted chunk. Defaults to None.
+        include_score (bool, optional): Whether to include the score in the formatted message. Defaults to True.
+        include_metadata (bool, optional): Whether to include the metadata in the formatted message. Defaults to True.
+
+    Returns:
+        str: A formatted log message that displays information about the logged chunk.
+    """
+def get_placeholder_keys(template: str) -> list[str]:
+    """Extracts keys from a template string based on a regex pattern.
+
+    This function searches the template for placeholders enclosed in single curly braces `{}` and ignores
+    any placeholders within double curly braces `{{}}`. It returns a list of the keys found.
+
+    Args:
+        template (str): The template string containing placeholders.
+
+    Returns:
+        list[str]: A list of keys extracted from the template.
+    """

gllm_core/utils/google_sheets.py

@@ -0,0 +1,115 @@
+"""Defines functions to interact with Google Sheets API.
+
+Authors:
+    Henry Wicaksono (henry.wicaksono@gdplabs.id)
+
+References:
+    [1] https://github.com/GDP-ADMIN/gen-ai-veriwise/blob/main/main/backend/module/google_sheets/auth.py
+"""
+
+import gspread
+from google.oauth2 import service_account
+from gspread import Client, Spreadsheet, Worksheet
+
+
+def load_gsheets(
+    client_email: str,
+    private_key: str,
+    sheet_id: str,
+    worksheet_id: str,
+) -> list[dict[str, str]]:
+    """Loads data from a Google Sheets worksheet.
+
+    This function retrieves data from a Google Sheets worksheet using service account credentials.
+    It authorizes the client, selects the specified worksheet, and reads the worksheet data.
+    The first row of the worksheet will be treated as the column names.
+
+    Args:
+        client_email (str): The client email associated with the service account.
+        private_key (str): The private key used for authentication.
+        sheet_id (str): The ID of the Google Sheet.
+        worksheet_id (str): The ID of the worksheet within the Google Sheet.
+
+    Returns:
+        list[dict[str, str]]: A list of dictionaries containing the Google Sheets content.
+    """
+    account_info = _get_account_info(client_email, private_key)
+    client = _get_client(account_info)
+    worksheet = _get_worksheet(client, sheet_id, worksheet_id)
+    return worksheet.get_all_records()
+
+
+def _get_account_info(client_email: str, private_key: str) -> dict[str, str]:
+    """Generates a dictionary with Google Sheets API authentication information.
+
+    This function returns a dictionary containing authentication details required for a Google Sheets API service
+    account.
+
+    Args:
+        client_email (str): The client email associated with the service account.
+        private_key (str): The private key used for authentication.
+
+    Returns:
+        dict[str, str]: A dictionary containing the authentication details for the Google Sheets API.
+    """
+    return {
+        "type": "service_account",
+        "private_key": private_key,
+        "client_email": client_email,
+        "client_id": "https://www.googleapis.com/auth/spreadsheets",
+        "token_uri": "https://oauth2.googleapis.com/token",
+    }
+
+
+def _get_client(info: dict[str, str]) -> Client:
+    """Gets a Google Sheets client with the provided credentials and scopes.
+
+    This function initializes a Google Sheets client using the provided service account credentials
+    (info) and OAuth2 scopes. It authorizes the client and returns it for further use in Google Sheets
+    interactions.
+
+    Args:
+        info (dict[str, str]): Service account information for authentication.
+
+    Returns:
+        Client: An authorized Google Sheets client.
+    """
+    scopes = ["https://www.googleapis.com/auth/spreadsheets"]
+    credentials = service_account.Credentials.from_service_account_info(info=info, scopes=scopes)
+    client = gspread.authorize(credentials)
+    return client
+
+
+def _get_sheet(client: Client, sheet_id: str) -> Spreadsheet:
+    """Gets a Google Sheets spreadsheet by its ID using a Google Sheets client.
+
+    This function opens the spreadsheet using Sheet ID and returns the corresponding Spreadsheet object.
+
+    Args:
+      client (Client): An authorized Google Sheets client.
+      sheet_id (str): The ID of the Google Sheets spreadsheet.
+
+    Returns:
+      Spreadsheet: The Google Sheets spreadsheet as a Spreadsheet object.
+    """
+    sheet = client.open_by_key(sheet_id)
+    return sheet
+
+
+def _get_worksheet(client: Client, sheet_id: str, worksheet_id: str) -> Worksheet:
+    """Gets a specific worksheet from a Google Sheets spreadsheet using a Google Sheets client and worksheet ID.
+
+    This function first retrieves the target Google Sheets spreadsheet using the provided client and sheet ID.
+    Then, it fetches the desired worksheet within the spreadsheet based on the worksheet ID and returns it.
+
+    Args:
+        client (Client): An authorized Google Sheets client.
+        sheet_id (str): The ID of the Google Sheets spreadsheet.
+        worksheet_id (str): The ID of the worksheet to retrieve.
+
+    Returns:
+        Worksheet: The specified worksheet as a Worksheet object.
+    """
+    sheet = _get_sheet(client, sheet_id)
+    worksheet = sheet.get_worksheet_by_id(int(worksheet_id))
+    return worksheet

gllm_core/utils/google_sheets.pyi

@@ -0,0 +1,18 @@
+from gspread import Client as Client, Spreadsheet as Spreadsheet, Worksheet as Worksheet
+
+def load_gsheets(client_email: str, private_key: str, sheet_id: str, worksheet_id: str) -> list[dict[str, str]]:
+    """Loads data from a Google Sheets worksheet.
+
+    This function retrieves data from a Google Sheets worksheet using service account credentials.
+    It authorizes the client, selects the specified worksheet, and reads the worksheet data.
+    The first row of the worksheet will be treated as the column names.
+
+    Args:
+        client_email (str): The client email associated with the service account.
+        private_key (str): The private key used for authentication.
+        sheet_id (str): The ID of the Google Sheet.
+        worksheet_id (str): The ID of the worksheet within the Google Sheet.
+
+    Returns:
+        list[dict[str, str]]: A list of dictionaries containing the Google Sheets content.
+    """

gllm_core/utils/imports.py

@@ -0,0 +1,91 @@
+"""Utilities for handling package imports.
+
+Authors:
+    Dimitrij Ray (dimitrij.ray@gdplabs.id)
+
+References:
+    NONE
+"""
+
+import importlib
+from typing import Callable
+
+from deprecation import deprecated as _deprecated
+
+
+def check_optional_packages(
+    packages: str | list[str],
+    error_message: str | None = None,
+    install_instructions: str | None = None,
+    extras: str | list[str] | None = None,
+) -> None:
+    """Check if optional packages are available and raise ImportError if not.
+
+    Args:
+        packages (str | list[str]): Package name or list of package names to check.
+        error_message (str | None, optional): Custom error message. If None, a default message is used.
+            Defaults to None.
+        install_instructions (str | None, optional): Installation instructions. If None, generates poetry install
+            command. Defaults to None.
+        extras (str | list[str] | None, optional): Poetry extras that contain the required packages. If provided,
+            generates specific installation instructions. If install_instructions is None, it will create
+            default instructions based on the extras. If install_instructions is not None, it will use the
+            provided instructions directly and ignore this argument. Defaults to None.
+
+    Raises:
+        ImportError: If any of the required packages are not installed.
+    """
+    if isinstance(packages, str):
+        packages = [packages]
+
+    missing = [package for package in packages if importlib.util.find_spec(package) is None]
+
+    if missing:
+        packages_str = ", ".join(f"'{pkg}'" for pkg in missing)
+        default_message = f"The following packages are missing: {packages_str}"
+        message = error_message or default_message
+
+        if install_instructions is None:
+            if extras:
+                if isinstance(extras, str):
+                    extras = [extras]
+                extras_str = " ".join(extras)
+                install_instructions = f"Please install the required extras with 'poetry install --extras {extras_str}'"
+            else:
+                install_instructions = (
+                    "Please update your poetry environment with 'poetry install' or "
+                    "install the required extras with 'poetry install --extras <extras>'"
+                )
+
+        raise ImportError(f"{message}.\n{install_instructions}")
+
+
+def deprecated(deprecated_in: str, removed_in: str, current_version: str | None = None, details: str = "") -> Callable:
+    """Decorator to mark functions as deprecated.
+
+    This is currently implemented as a thin wrapper around deprecation.deprecated for consistency, since deprecation
+    may be deprecated when we move into Python 3.13, where @warnings.deprecated will be available.
+
+    Usage example:
+
+    ```python
+    @deprecated(deprecated_in="0.1.0", removed_in="0.2.0", current_version="0.1.1")
+    def old_function():
+        pass
+    ```
+
+    Args:
+        deprecated_in (str): The version when the function was deprecated.
+        removed_in (str): The version when the function will be removed.
+        current_version (str | None, optional): The current version of the package. Defaults to None.
+        details (str, optional): Additional details about the deprecation. Defaults to an empty string.
+
+    Returns:
+        Callable: The decorated function.
+    """
+    return _deprecated(
+        deprecated_in=deprecated_in,
+        removed_in=removed_in,
+        current_version=current_version,
+        details=details,
+    )

gllm_core/utils/imports.pyi

@@ -0,0 +1,42 @@
+from typing import Callable
+
+def check_optional_packages(packages: str | list[str], error_message: str | None = None, install_instructions: str | None = None, extras: str | list[str] | None = None) -> None:
+    """Check if optional packages are available and raise ImportError if not.
+
+    Args:
+        packages (str | list[str]): Package name or list of package names to check.
+        error_message (str | None, optional): Custom error message. If None, a default message is used.
+            Defaults to None.
+        install_instructions (str | None, optional): Installation instructions. If None, generates poetry install
+            command. Defaults to None.
+        extras (str | list[str] | None, optional): Poetry extras that contain the required packages. If provided,
+            generates specific installation instructions. If install_instructions is None, it will create
+            default instructions based on the extras. If install_instructions is not None, it will use the
+            provided instructions directly and ignore this argument. Defaults to None.
+
+    Raises:
+        ImportError: If any of the required packages are not installed.
+    """
+def deprecated(deprecated_in: str, removed_in: str, current_version: str | None = None, details: str = '') -> Callable:
+    '''Decorator to mark functions as deprecated.
+
+    This is currently implemented as a thin wrapper around deprecation.deprecated for consistency, since deprecation
+    may be deprecated when we move into Python 3.13, where @warnings.deprecated will be available.
+
+    Usage example:
+
+    ```python
+    @deprecated(deprecated_in="0.1.0", removed_in="0.2.0", current_version="0.1.1")
+    def old_function():
+        pass
+    ```
+
+    Args:
+        deprecated_in (str): The version when the function was deprecated.
+        removed_in (str): The version when the function will be removed.
+        current_version (str | None, optional): The current version of the package. Defaults to None.
+        details (str, optional): Additional details about the deprecation. Defaults to an empty string.
+
+    Returns:
+        Callable: The decorated function.
+    '''