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

gllm_core/utils/main_method_resolver.py

@@ -0,0 +1,185 @@
+"""Main method resolver for Component classes.
+
+This module provides the MainMethodResolver class which encapsulates the logic
+for resolving the main entrypoint method for Component subclasses.
+
+Authors:
+    Dimitrij Ray (dimitrij.ray@gdplabs.id)
+
+References:
+    NONE
+"""
+
+from abc import ABC
+from typing import Callable
+
+from gllm_core.utils.logger_manager import LoggerManager
+
+
+class MainMethodResolver:
+    """Resolves the main entrypoint method for Component classes.
+
+    This resolver implements the precedence rules for determining which method
+    should be used as the main entrypoint:
+    1. Method decorated with @main in the most derived class.
+    2. Method named by __main_method__ property.
+    3. _run method (with deprecation warning).
+
+    Attributes:
+        cls (type): The Component class to resolve the main method for.
+    """
+
+    def __init__(self, component_class: type):
+        """Initialize the resolver with a Component class.
+
+        Args:
+            component_class (type): The Component class to resolve the main method for.
+        """
+        self.cls = component_class
+        self._logger = LoggerManager().get_logger(f"MainMethodResolver.{component_class.__name__}")
+
+    @staticmethod
+    def validate_class(component_class: type) -> None:
+        """Validate main method configuration at class definition time.
+
+        This performs early validation that can be done when a Component subclass
+        is defined, before any instances are created or methods are called.
+
+        Validations performed:
+        1. Check that __main_method__ property points to an existing method
+        2. Check that only one @main decorator is used within the same class
+
+        Note: Multiple inheritance conflicts are intentionally NOT checked here,
+        as they are deferred to runtime (get_main()) to allow class definition
+        to succeed.
+
+        Args:
+            component_class (type): The Component class to validate.
+
+        Raises:
+            AttributeError: If __main_method__ refers to a non-existent method.
+            TypeError: If multiple methods are decorated with @main in the same class.
+        """
+        if (method_name := getattr(component_class, "__main_method__", None)) is not None:
+            if not hasattr(component_class, method_name):
+                raise AttributeError(
+                    f"Method {method_name!r} specified in __main_method__ does not exist in {component_class.__name__}"
+                )
+
+        main_methods = []
+        for name, method in component_class.__dict__.items():
+            if callable(method) and hasattr(method, "__is_main__"):
+                main_methods.append(name)
+
+        if len(main_methods) > 1:
+            raise TypeError(f"Multiple main methods defined in {component_class.__name__}: {', '.join(main_methods)}")
+
+    def resolve(self) -> Callable | None:
+        """Resolve the main method following precedence rules.
+
+        Returns:
+            Callable | None: The resolved main method, or None if not found.
+
+        Raises:
+            TypeError: If conflicting main methods are inherited from multiple ancestors.
+        """
+        if decorated := self._resolve_decorated():
+            self._warn_if_redundant_property()
+            return decorated
+
+        if property_method := self._resolve_property():
+            return property_method
+
+        return self._resolve_legacy()
+
+    def _resolve_decorated(self) -> Callable | None:
+        """Find the most-derived @main decorated method in the MRO (method resolution order).
+
+        Returns:
+            Callable | None: The decorated main method, or None if not found.
+
+        Raises:
+            TypeError: If conflicting main methods are inherited from multiple ancestors.
+        """
+        classes_with_main = []
+        for base in self.cls.__mro__:
+            if base.__name__ == "Component" or base is ABC:
+                continue
+
+            main_method_name = next(
+                (name for name, method in base.__dict__.items() if callable(method) and hasattr(method, "__is_main__")),
+                None,
+            )
+
+            if main_method_name:
+                classes_with_main.append((base, main_method_name))
+
+        if not classes_with_main:
+            return None
+
+        most_derived_class, method_name = classes_with_main[0]
+        actual_method = getattr(self.cls, method_name)
+
+        self._validate_no_decorator_conflicts(classes_with_main, most_derived_class, actual_method)
+
+        return actual_method
+
+    def _validate_no_decorator_conflicts(
+        self, classes_with_main: list[tuple[type, str]], most_derived_class: type, actual_method: Callable
+    ) -> None:
+        """Validate that there are no conflicting @main decorators in multiple inheritance.
+
+        This method checks for conflicts only when multiple classes in the inheritance hierarchy have @main decorated
+        methods. It allows intentional overrides (when the most derived class defines its own @main method) but prevents
+        conflicts from multiple inheritance where different ancestors define different @main methods.
+
+        Args:
+            classes_with_main (list[tuple[type, str]]): List of (class, method_name) tuples for classes with @main.
+            most_derived_class (type): The most derived class in the hierarchy with @main.
+            actual_method (Callable): The resolved method from the most derived class.
+
+        Raises:
+            TypeError: If conflicting main methods are inherited from multiple ancestors and the most derived class
+                is not the current class (indicating a true conflict rather than an intentional override).
+        """
+        if len(classes_with_main) > 1 and most_derived_class is not self.cls:
+            for _, name in classes_with_main[1:]:
+                other_method = getattr(self.cls, name)
+                if other_method is not actual_method:
+                    raise TypeError(
+                        f"Conflicting main methods inherited from multiple ancestors in {self.cls.__name__}. "
+                        "Please explicitly override with @main decorator."
+                    )
+
+    def _resolve_property(self) -> Callable | None:
+        """Find method via __main_method__ property.
+
+        Returns:
+            Callable | None: The method named by __main_method__, or None if not found.
+        """
+        if hasattr(self.cls, "__main_method__") and self.cls.__main_method__ is not None:
+            method_name = self.cls.__main_method__
+            return getattr(self.cls, method_name, None)
+
+    def _resolve_legacy(self) -> Callable | None:
+        """Fall back to _run method with deprecation warning.
+
+        Returns:
+            Callable | None: The _run method, or None if not found.
+        """
+        if hasattr(self.cls, "_run"):
+            self._logger.warning(
+                f"Using legacy _run method for {self.cls.__name__}. "
+                f"Consider using @main decorator to explicitly declare the main entrypoint.",
+                stacklevel=4,
+            )
+            return self.cls._run
+
+    def _warn_if_redundant_property(self) -> None:
+        """Emit warning if both @main decorator and __main_method__ are defined."""
+        if self.cls.__dict__.get("__main_method__") is not None:
+            self._logger.warning(
+                f"Both @main decorator and __main_method__ property are defined in {self.cls.__name__}. "
+                "The @main decorator takes precedence. This redundant configuration should be resolved.",
+                stacklevel=4,
+            )

gllm_core/utils/main_method_resolver.pyi

@@ -0,0 +1,54 @@
+from _typeshed import Incomplete
+from gllm_core.utils.logger_manager import LoggerManager as LoggerManager
+from typing import Callable
+
+class MainMethodResolver:
+    """Resolves the main entrypoint method for Component classes.
+
+    This resolver implements the precedence rules for determining which method
+    should be used as the main entrypoint:
+    1. Method decorated with @main in the most derived class.
+    2. Method named by __main_method__ property.
+    3. _run method (with deprecation warning).
+
+    Attributes:
+        cls (type): The Component class to resolve the main method for.
+    """
+    cls: Incomplete
+    def __init__(self, component_class: type) -> None:
+        """Initialize the resolver with a Component class.
+
+        Args:
+            component_class (type): The Component class to resolve the main method for.
+        """
+    @staticmethod
+    def validate_class(component_class: type) -> None:
+        """Validate main method configuration at class definition time.
+
+        This performs early validation that can be done when a Component subclass
+        is defined, before any instances are created or methods are called.
+
+        Validations performed:
+        1. Check that __main_method__ property points to an existing method
+        2. Check that only one @main decorator is used within the same class
+
+        Note: Multiple inheritance conflicts are intentionally NOT checked here,
+        as they are deferred to runtime (get_main()) to allow class definition
+        to succeed.
+
+        Args:
+            component_class (type): The Component class to validate.
+
+        Raises:
+            AttributeError: If __main_method__ refers to a non-existent method.
+            TypeError: If multiple methods are decorated with @main in the same class.
+        """
+    def resolve(self) -> Callable | None:
+        """Resolve the main method following precedence rules.
+
+        Returns:
+            Callable | None: The resolved main method, or None if not found.
+
+        Raises:
+            TypeError: If conflicting main methods are inherited from multiple ancestors.
+        """

gllm_core/utils/merger_method.py

@@ -0,0 +1,130 @@
+"""Defines a collection of merger methods.
+
+Authors:
+    Henry Wicaksono (henry.wicaksono@gdplabs.id)
+
+References:
+    NONE
+"""
+
+import os
+from typing import Any, Callable
+
+
+class MergerMethod:
+    """A collection of merger methods."""
+
+    @staticmethod
+    def concatenate(delimiter: str = "-") -> Callable[[list[Any]], str]:
+        """Creates a function that concatenates a list of values with a delimiter.
+
+        Args:
+            delimiter (str, optional): The delimiter to use when concatenating the values. Defaults to "-".
+
+        Returns:
+            Callable[[list[Any]], str]: A function that concatenates a list of values with the delimiter.
+        """
+
+        def _concat_with_delimiter(values: list[Any]) -> str:
+            return delimiter.join([str(value) for value in values])
+
+        return _concat_with_delimiter
+
+    @staticmethod
+    def pick_first(values: list[Any]) -> Any:
+        """Picks the first value from a list of values.
+
+        Args:
+            values (list[Any]): The values to pick from.
+
+        Returns:
+            Any: The first value from the list.
+        """
+        return values[0] if values else None
+
+    @staticmethod
+    def pick_last(values: list[Any]) -> Any:
+        """Picks the last value from a list of values.
+
+        Args:
+            values (list[Any]): The values to pick from.
+
+        Returns:
+            Any: The last value from the list.
+        """
+        return values[-1] if values else None
+
+    @staticmethod
+    def merge_overlapping_strings(delimiter: str = "\n") -> Callable[[list[str]], str]:
+        r"""Creates a function that merges a list of strings, handling common prefixes and overlaps.
+
+        The created function will:
+        - Identify and remove any common prefix shared by the strings.
+        - Process each pair of adjacent strings to remove overlapping strings.
+        - Join the cleaned strings together, including the common prefix at the beginning.
+
+        Args:
+            delimiter (str, optional): The delimiter to use when merging the values. Defaults to "\n".
+
+        Returns:
+            Callable[[list[str]], str]: A function that merges a list of strings, handling common prefixes and overlaps.
+        """
+
+        def _merge_overlapping_strings(values: list[str]) -> str:
+            values = [str(value) for value in values]
+            common_prefix = MergerMethod._get_common_prefix(values)
+            values = [string[len(common_prefix) :] for string in values]
+
+            for idx in range(len(values) - 1):
+                overlap = MergerMethod._find_overlap(values[idx], values[idx + 1])
+                values[idx] = values[idx].replace(overlap, "")
+
+            values.insert(0, common_prefix)
+
+            return delimiter.join([string.strip() for string in values if string.strip()])
+
+        return _merge_overlapping_strings
+
+    @staticmethod
+    def _get_common_prefix(strings: list[str]) -> str:
+        """Identifies the common prefix shared by a list of strings.
+
+        This method uses `os.path.commonprefix` to find the common prefix shared by all strings in the provided
+        `strings`. If the common prefix does not end with a newline, the method removes the last partial line to
+        ensure the prefix ends at a full line break.
+
+        Args:
+            strings (list[str]): A list of strings to find the common prefix.
+
+        Returns:
+            str: The common prefix shared by all strings, ending at the last full line.
+        """
+        common_prefix = os.path.commonprefix(strings)
+        last_newline_index = common_prefix.rfind("\n")
+
+        if last_newline_index != -1:
+            return common_prefix[:last_newline_index]
+
+        return ""
+
+    @staticmethod
+    def _find_overlap(first_string: str, second_string: str) -> str:
+        """Finds the overlapping portion between two strings.
+
+        This method compares the end of the `first_string` with the beginning of the `second_string` to find the
+        longest overlapping substring. It returns the overlap if found, otherwise returns an empty string.
+
+        Args:
+            first_string (str): The first string to compare.
+            second_string (str): The second string to compare.
+
+        Returns:
+            str: The overlapping substring between the two strings, or an empty string if no overlap is found.
+        """
+        max_overlap_len = min(len(first_string), len(second_string))
+
+        for i in range(max_overlap_len, 0, -1):
+            if first_string[-i:] == second_string[:i]:
+                return first_string[-i:]
+
+        return ""

gllm_core/utils/merger_method.pyi

@@ -0,0 +1,49 @@
+from typing import Any, Callable
+
+class MergerMethod:
+    """A collection of merger methods."""
+    @staticmethod
+    def concatenate(delimiter: str = '-') -> Callable[[list[Any]], str]:
+        '''Creates a function that concatenates a list of values with a delimiter.
+
+        Args:
+            delimiter (str, optional): The delimiter to use when concatenating the values. Defaults to "-".
+
+        Returns:
+            Callable[[list[Any]], str]: A function that concatenates a list of values with the delimiter.
+        '''
+    @staticmethod
+    def pick_first(values: list[Any]) -> Any:
+        """Picks the first value from a list of values.
+
+        Args:
+            values (list[Any]): The values to pick from.
+
+        Returns:
+            Any: The first value from the list.
+        """
+    @staticmethod
+    def pick_last(values: list[Any]) -> Any:
+        """Picks the last value from a list of values.
+
+        Args:
+            values (list[Any]): The values to pick from.
+
+        Returns:
+            Any: The last value from the list.
+        """
+    @staticmethod
+    def merge_overlapping_strings(delimiter: str = '\n') -> Callable[[list[str]], str]:
+        '''Creates a function that merges a list of strings, handling common prefixes and overlaps.
+
+        The created function will:
+        - Identify and remove any common prefix shared by the strings.
+        - Process each pair of adjacent strings to remove overlapping strings.
+        - Join the cleaned strings together, including the common prefix at the beginning.
+
+        Args:
+            delimiter (str, optional): The delimiter to use when merging the values. Defaults to "\\n".
+
+        Returns:
+            Callable[[list[str]], str]: A function that merges a list of strings, handling common prefixes and overlaps.
+        '''

gllm_core/utils/retry.py

@@ -0,0 +1,258 @@
+"""Defines retry and timeout utilities.
+
+Authors:
+    Henry Wicaksono (henry.wicaksono@gdplabs.id)
+
+References:
+    NONE
+"""
+
+import asyncio
+import functools
+import inspect
+import random
+from typing import Any, Callable, TypeVar, overload
+
+from pydantic import BaseModel, Field, model_validator
+
+from gllm_core.utils import LoggerManager
+from gllm_core.utils.concurrency import syncify
+
+logger = LoggerManager().get_logger(__name__)
+
+T = TypeVar("T")
+
+BASE_EXPONENTIAL_BACKOFF = 2.0
+
+
+class RetryConfig(BaseModel):
+    """Configuration for retry behavior.
+
+    Attributes:
+        max_retries (int): Maximum number of retry attempts.
+        base_delay (float): Base delay in seconds between retries.
+        max_delay (float): Maximum delay in seconds between retries.
+        jitter (bool): Whether to add random jitter to delays.
+        timeout (float | None): Overall timeout in seconds for the entire operation. If None, timeout is disabled.
+        retry_on_exceptions (tuple[type[Exception], ...]): Tuple of exception types to retry on.
+    """
+
+    max_retries: int = Field(default=0, ge=0)
+    base_delay: float = Field(default=1.0, gt=0.0)
+    max_delay: float = Field(default=10.0, gt=0.0)
+    jitter: bool = Field(default=True)
+    timeout: float | None = Field(default=None, gt=0.0)
+    retry_on_exceptions: tuple[type[Exception], ...] = Field(default=(Exception,))
+
+    @model_validator(mode="after")
+    def validate_delay_constraints(self) -> "RetryConfig":
+        """Validates that max_delay is greater than or equal to base_delay.
+
+        Returns:
+            RetryConfig: The validated configuration.
+
+        Raises:
+            ValueError: If max_delay is less than base_delay.
+        """
+        if self.timeout == 0:
+            logger.warning(
+                "Setting timeout=0.0 is deprecated and will raise an error in v0.4. "
+                "Please use timeout=None instead to disable timeout."
+            )
+            self.timeout = None
+
+        if self.max_delay < self.base_delay:
+            raise ValueError("The 'max_delay' parameter must be greater than or equal to 'base_delay'.")
+
+        return self
+
+
+def _calculate_delay(attempt: int, config: RetryConfig) -> float:
+    """Calculates the delay for the next retry attempt.
+
+    Args:
+        attempt (int): The current attempt number (0-based).
+        config (RetryConfig): The retry configuration.
+
+    Returns:
+        float: The delay in seconds.
+    """
+    delay = config.base_delay * (BASE_EXPONENTIAL_BACKOFF**attempt)
+
+    if config.jitter:
+        jitter_factor = random.uniform(0, 0.25)
+        delay += delay * jitter_factor
+
+    return min(delay, config.max_delay)
+
+
+async def _retry_async(
+    func: Callable[..., Any],
+    *args: Any,
+    retry_config: RetryConfig | None = None,
+    **kwargs: Any,
+) -> T:
+    """Executes a function with retry logic and exponential backoff.
+
+    This function executes the provided function with retry logic. It will first try to execute the function once.
+    If the function raises an exception that matches the retry_on_exceptions, it will retry up to max_retries times
+    with exponential backoff. Therefore, the max number of attempts is max_retries + 1. If provided, the timeout
+    applies to the entire retry operation, including all attempts and delays.
+
+    Example:
+        If you set timeout=10.0 and max_retries=3, the entire retry operation (including all attempts
+        and delays) will timeout after 10 seconds, not 10 seconds per attempt.
+
+    Args:
+        func (Callable[..., Any]): The function to execute.
+        *args (Any): Positional arguments to pass to the function.
+        retry_config (RetryConfig | None, optional): Retry configuration. If None, uses default config.
+            Defaults to None.
+        **kwargs (Any): Keyword arguments to pass to the function.
+
+    Returns:
+        T: The result of the function execution.
+
+    Raises:
+        Exception: The last exception raised by the function if all retries are exhausted.
+        asyncio.TimeoutError: If the overall timeout is exceeded.
+    """
+    config = retry_config or RetryConfig()
+
+    async def attempt_loop() -> T:
+        max_retries = config.max_retries + 1
+
+        for attempt in range(max_retries):
+            try:
+                result = func(*args, **kwargs)
+                if inspect.isawaitable(result):
+                    return await result
+                return result
+
+            except asyncio.TimeoutError:
+                raise
+
+            except config.retry_on_exceptions as exc:
+                if attempt == config.max_retries:
+                    logger.error(f"Function {func.__name__} failed after {max_retries} attempts. Last error: {exc}")
+                    raise exc from None
+
+                delay = _calculate_delay(attempt, config)
+                logger.warning(
+                    f"Function {func.__name__} failed on attempt {attempt + 1}/{max_retries}. "
+                    f"Retrying in {delay:.2f} seconds. Error: {exc}"
+                )
+                await asyncio.sleep(delay)
+
+    if config.timeout is not None:
+        return await asyncio.wait_for(attempt_loop(), timeout=config.timeout)
+
+    return await attempt_loop()
+
+
+@overload
+async def retry(
+    func: Callable[..., Any],
+    *args: Any,
+    retry_config: RetryConfig | None = None,
+    **kwargs: Any,
+) -> T: ...
+
+
+@overload
+def retry(config: RetryConfig | None = None) -> Callable[[Callable[..., Any]], Callable[..., Any]]: ...
+
+
+def retry(
+    func_or_config: Callable[..., Any] | RetryConfig | None = None,
+    *args: Any,
+    retry_config: RetryConfig | None = None,
+    **kwargs: Any,
+) -> T | Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Executes a function with retry logic or creates a retry decorator.
+
+    This function supports two usage patterns:
+    1. Direct function execution: await retry(func, *args, retry_config=config, **kwargs)
+    2. Decorator factory: @retry() or @retry(config)
+
+    Args:
+        func_or_config (Callable[..., Any] | RetryConfig | None, optional): Either a function to execute or a
+            RetryConfig for decorator usage. Defaults to None.
+        *args (Any): Positional arguments (only used in direct execution mode).
+        retry_config (RetryConfig | None, optional): Retry configuration (only used in direct execution mode).
+            Defaults to None, in which case no retry nor timeout is applied.
+        **kwargs (Any): Keyword arguments (only used in direct execution mode).
+
+    Returns:
+        T | Callable[[Callable[..., Any]], Callable[..., Any]]: Either the result of function execution or
+            a decorator function.
+
+    Raises:
+        Exception: The last exception raised by the function if all retries are exhausted.
+        asyncio.TimeoutError: If the overall timeout is exceeded.
+
+    Examples:
+        # Direct function execution
+        ```python
+        result = await retry(my_function, arg1, arg2, retry_config=config)
+        ```
+
+        # Decorator usage - parameterless
+        ```python
+        @retry()
+        async def my_async_function():
+            # Use default settings, in which case no retry nor timeout is applied.
+            pass
+        ```
+
+        # Decorator usage - with custom configuration
+        ```python
+        @retry(RetryConfig(max_retries=3, timeout=120))
+        async def my_function():
+            # Will retry up to 3 times with 0.5s base delay
+            pass
+        ```
+
+        # Decorator on sync functions
+        ```python
+        @retry()
+        def my_sync_function():
+            # Works with sync functions too
+            return "success"
+        ```
+
+        # Decorator on class methods
+        ```python
+        class MyService:
+            @retry(RetryConfig(max_retries=2))
+            async def get_data(self, id: str):
+                return {"id": id, "data": "value"}
+        ```
+    """
+    if callable(func_or_config) and not isinstance(func_or_config, RetryConfig):
+        func = func_or_config
+
+        async def async_wrapper() -> T:
+            return await _retry_async(func, *args, retry_config=retry_config, **kwargs)
+
+        return async_wrapper()
+
+    config = func_or_config
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        if asyncio.iscoroutinefunction(func):
+
+            @functools.wraps(func)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                return await _retry_async(func, *args, retry_config=config, **kwargs)
+
+            return async_wrapper
+
+        @functools.wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            sync_retry = syncify(lambda: _retry_async(func, *args, retry_config=config, **kwargs))
+            return sync_retry()
+
+        return sync_wrapper
+
+    return decorator