lionagi 0.3.8__py3-none-any.whl → 0.5.0__py3-none-any.whl

lionagi/libs/func/async_calls/rcall.py

@@ -0,0 +1,185 @@
+import asyncio
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from ...constants import UNDEFINED
+from ...utils import time as _t
+from .ucall import ucall
+
+T = TypeVar("T")
+
+
+async def rcall(
+    func: Callable[..., T],
+    /,
+    *args: Any,
+    num_retries: int = 0,
+    initial_delay: float = 0,
+    retry_delay: float = 0,
+    backoff_factor: float = 1,
+    retry_default: Any = UNDEFINED,
+    retry_timeout: float | None = None,
+    retry_timing: bool = False,
+    verbose_retry: bool = True,
+    error_msg: str | None = None,
+    error_map: dict[type, Callable[[Exception], None]] | None = None,
+    **kwargs: Any,
+) -> T | tuple[T, float]:
+    """Retry a function asynchronously with customizable options.
+
+    Executes a function with specified retry logic, timing, and error handling.
+
+    Args:
+        func: The function to execute (coroutine or regular).
+        *args: Positional arguments for the function.
+        num_retries: Number of retry attempts (default: 0).
+        initial_delay: Delay before first attempt (seconds).
+        retry_delay: Delay between retry attempts (seconds).
+        backoff_factor: Factor to increase delay after each retry.
+        retry_default: Value to return if all attempts fail.
+        retry_timeout: Timeout for each function execution (seconds).
+        retry_timing: If True, return execution duration.
+        verbose_retry: If True, print retry messages.
+        error_msg: Custom error message prefix.
+        error_map: Dict mapping exception types to error handlers.
+        **kwargs: Additional keyword arguments for the function.
+
+    Returns:
+        T | tuple[T, float]: Function result, optionally with duration.
+
+    Raises:
+        RuntimeError: If function fails after all retries.
+        asyncio.TimeoutError: If execution exceeds retry_timeout.
+
+    Examples:
+        >>> async def flaky_func(x):
+        ...     if random.random() < 0.5:
+        ...         raise ValueError("Random failure")
+        ...     return x * 2
+        >>> result = await rcall(flaky_func, 5, num_retries=3)
+        >>> print(result)
+        10
+
+    Note:
+        - Supports both coroutine and regular functions.
+        - Implements exponential backoff for retries.
+        - Can return execution timing for performance analysis.
+    """
+    last_exception = None
+    result = None
+
+    await asyncio.sleep(initial_delay)
+    for attempt in range(num_retries + 1):
+        try:
+            if num_retries == 0:
+                if retry_timing:
+                    result, duration = await _rcall(
+                        func,
+                        *args,
+                        retry_timeout=retry_timeout,
+                        retry_timing=True,
+                        **kwargs,
+                    )
+                    return result, duration
+                result = await _rcall(
+                    func,
+                    *args,
+                    retry_timeout=retry_timeout,
+                    **kwargs,
+                )
+                return result
+            err_msg = (
+                f"Attempt {attempt + 1}/{num_retries + 1}: {error_msg or ''}"
+            )
+            if retry_timing:
+                result, duration = await _rcall(
+                    func,
+                    *args,
+                    error_msg=err_msg,
+                    retry_timeout=retry_timeout,
+                    retry_timing=True,
+                    **kwargs,
+                )
+                return result, duration
+
+            result = await _rcall(
+                func,
+                *args,
+                error_msg=err_msg,
+                retry_timeout=retry_timeout,
+                **kwargs,
+            )
+            return result
+        except Exception as e:
+            last_exception = e
+            if error_map and type(e) in error_map:
+                error_map[type(e)](e)
+            if attempt < num_retries:
+                if verbose_retry:
+                    print(
+                        f"Attempt {attempt + 1}/{num_retries + 1} failed: {e},"
+                        " retrying..."
+                    )
+                await asyncio.sleep(retry_delay)
+                retry_delay *= backoff_factor
+            else:
+                break
+
+    if retry_default is not UNDEFINED:
+        return retry_default
+
+    if last_exception is not None:
+        if error_map and type(last_exception) in error_map:
+            handler = error_map[type(last_exception)]
+            if asyncio.iscoroutinefunction(handler):
+                return await handler(last_exception)
+            else:
+                return handler(last_exception)
+        raise RuntimeError(
+            f"{error_msg or ''} Operation failed after {num_retries + 1} "
+            f"attempts: {last_exception}"
+        ) from last_exception
+
+    raise RuntimeError(
+        f"{error_msg or ''} Operation failed after {num_retries + 1} attempts"
+    )
+
+
+async def _rcall(
+    func: Callable[..., T],
+    *args: Any,
+    retry_delay: float = 0,
+    error_msg: str | None = None,
+    ignore_err: bool = False,
+    retry_timing: bool = False,
+    retry_default: Any = None,
+    retry_timeout: float | None = None,
+    **kwargs: Any,
+) -> T | tuple[T, float]:
+    start_time = _t()
+
+    try:
+        await asyncio.sleep(retry_delay)
+        if retry_timeout is not None:
+            result = await asyncio.wait_for(
+                ucall(func, *args, **kwargs), timeout=retry_timeout
+            )
+        else:
+            result = await ucall(func, *args, **kwargs)
+        duration = _t() - start_time
+        return (result, duration) if retry_timing else result
+    except TimeoutError as e:
+        error_msg = (
+            f"{error_msg or ''} Timeout {retry_timeout} seconds exceeded"
+        )
+        if ignore_err:
+            duration = _t() - start_time
+            return (retry_default, duration) if retry_timing else retry_default
+        else:
+            raise TimeoutError(error_msg) from e
+    except Exception:
+        if ignore_err:
+            duration = _t() - start_time
+            return (retry_default, duration) if retry_timing else retry_default
+        else:
+            raise

lionagi/libs/func/async_calls/tcall.py

@@ -0,0 +1,114 @@
+import asyncio
+import logging
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from ...constants import UNDEFINED
+from .ucall import ucall
+
+T = TypeVar("T")
+
+
+async def tcall(
+    func: Callable[..., T],
+    /,
+    *args: Any,
+    initial_delay: float = 0,
+    error_msg: str | None = None,
+    suppress_err: bool = False,
+    retry_timing: bool = False,
+    retry_timeout: float | None = None,
+    retry_default: Any = None,
+    error_map: dict[type, Callable[[Exception], None]] | None = None,
+    **kwargs: Any,
+) -> T | tuple[T, float]:
+    """Execute a function asynchronously with timing and error handling.
+
+    Handles both coroutine and regular functions, supporting timing,
+    timeout, and custom error handling.
+
+    Args:
+        func: The function to execute (coroutine or regular).
+        *args: Positional arguments for the function.
+        initial_delay: Delay before execution (seconds).
+        error_msg: Custom error message prefix.
+        suppress_err: If True, return default on error instead of raising.
+        retry_timing: If True, return execution duration.
+        retry_timeout: Timeout for function execution (seconds).
+        retry_default: Value to return if an error occurs and suppress_err
+        is True.
+        error_map: Dict mapping exception types to error handlers.
+        **kwargs: Additional keyword arguments for the function.
+
+    Returns:
+        T | tuple[T, float]: Function result, optionally with duration.
+
+    Raises:
+        asyncio.TimeoutError: If execution exceeds the timeout.
+        RuntimeError: If an error occurs and suppress_err is False.
+
+    Examples:
+        >>> async def slow_func(x):
+        ...     await asyncio.sleep(1)
+        ...     return x * 2
+        >>> result, duration = await tcall(slow_func, 5, retry_timing=True)
+        >>> print(f"Result: {result}, Duration: {duration:.2f}s")
+        Result: 10, Duration: 1.00s
+
+    Note:
+        - Automatically handles both coroutine and regular functions.
+        - Provides timing information for performance analysis.
+        - Supports custom error handling and suppression.
+    """
+    start = asyncio.get_event_loop().time()
+
+    try:
+        await asyncio.sleep(initial_delay)
+        result = None
+
+        if asyncio.iscoroutinefunction(func):
+            # Asynchronous function
+            if retry_timeout is None:
+                result = await func(*args, **kwargs)
+            else:
+                result = await asyncio.wait_for(
+                    func(*args, **kwargs), timeout=retry_timeout
+                )
+        else:
+            # Synchronous function
+            if retry_timeout is None:
+                result = func(*args, **kwargs)
+            else:
+                result = await asyncio.wait_for(
+                    asyncio.shield(asyncio.to_thread(func, *args, **kwargs)),
+                    timeout=retry_timeout,
+                )
+
+        duration = asyncio.get_event_loop().time() - start
+        return (result, duration) if retry_timing else result
+
+    except TimeoutError as e:
+        error_msg = (
+            f"{error_msg or ''} Timeout {retry_timeout} seconds exceeded"
+        )
+        if suppress_err:
+            duration = asyncio.get_event_loop().time() - start
+            return (retry_default, duration) if retry_timing else retry_default
+        else:
+            raise TimeoutError(error_msg) from e
+
+    except Exception as e:
+        if error_map and type(e) in error_map:
+            error_map[type(e)](e)
+            duration = asyncio.get_event_loop().time() - start
+            return (None, duration) if retry_timing else None
+        error_msg = (
+            f"{error_msg} Error: {e}"
+            if error_msg
+            else f"An error occurred in async execution: {e}"
+        )
+        if suppress_err:
+            duration = asyncio.get_event_loop().time() - start
+            return (retry_default, duration) if retry_timing else retry_default
+        else:
+            raise RuntimeError(error_msg) from e

lionagi/libs/func/async_calls/ucall.py

@@ -0,0 +1,85 @@
+"""
+Copyright 2024 HaiyangLi
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+"""
+
+import asyncio
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from ..utils import custom_error_handler, force_async, is_coroutine_func
+
+T = TypeVar("T")
+
+
+async def ucall(
+    func: Callable[..., T],
+    /,
+    *args: Any,
+    error_map: dict[type, Callable[[Exception], None]] | None = None,
+    **kwargs: Any,
+) -> T:
+    """Execute a function asynchronously with error handling.
+
+    Ensures asynchronous execution of both coroutine and regular functions,
+    managing event loops and applying custom error handling.
+
+    Args:
+        func: The function to be executed (coroutine or regular).
+        *args: Positional arguments for the function.
+        error_map: Dict mapping exception types to error handlers.
+        **kwargs: Keyword arguments for the function.
+
+    Returns:
+        T: The result of the function call.
+
+    Raises:
+        Exception: Any unhandled exception from the function execution.
+
+    Examples:
+        >>> async def example_func(x):
+        ...     return x * 2
+        >>> await ucall(example_func, 5)
+        10
+        >>> await ucall(lambda x: x + 1, 5)  # Non-coroutine function
+        6
+
+    Note:
+        - Automatically wraps non-coroutine functions for async execution.
+        - Manages event loop creation and closure when necessary.
+        - Applies custom error handling based on the provided error_map.
+    """
+    try:
+        if not is_coroutine_func(func):
+            func = force_async(func)
+
+        # Checking for a running event loop
+        try:
+            loop = asyncio.get_running_loop()
+            if loop.is_running():
+                return await func(*args, **kwargs)
+            else:
+                return await asyncio.run(func(*args, **kwargs))
+
+        except RuntimeError:  # No running event loop
+            loop = asyncio.new_event_loop()
+            result = await func(*args, **kwargs)
+            loop.close()
+            return result
+
+    except Exception as e:
+        if error_map:
+
+            return await custom_error_handler(e, error_map)
+        raise e

lionagi/libs/func/decorators.py

@@ -0,0 +1,277 @@
+"""
+Copyright 2024 HaiyangLi
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+"""
+
+import asyncio
+from collections.abc import Callable, Sequence
+from functools import wraps
+from typing import Any, TypeVar
+
+from ..constants import UNDEFINED
+from .async_calls import rcall, ucall
+from .throttle import Throttle
+from .utils import force_async, is_coroutine_func
+
+T = TypeVar("T")
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+class CallDecorator:
+    """A collection of decorators to enhance function calls."""
+
+    @staticmethod
+    def retry(
+        num_retries: int = 0,
+        initial_delay: float = 0,
+        retry_delay: float = 0,
+        backoff_factor: float = 1,
+        retry_default: Any = UNDEFINED,
+        retry_timeout: float | None = None,
+        retry_timing: bool = False,
+        verbose_retry: bool = True,
+        error_msg: str | None = None,
+        error_map: dict[type, Callable[[Exception], None]] | None = None,
+    ) -> Callable[[F], F]:
+        """Decorator to automatically retry a function call on failure.
+
+        Args:
+            retries: Number of retry attempts.
+            initial_delay: Initial delay before retrying.
+            delay: Delay between retries.
+            backoff_factor: Factor to increase delay after each retry.
+            default: Default value to return on failure.
+            timeout: Timeout for each function call.
+            timing: If True, logs the time taken for each call.
+            verbose: If True, logs the retries.
+            error_msg: Custom error message on failure.
+            error_map: A map of exception types to handler functions.
+
+        Returns:
+            The decorated function.
+        """
+
+        def decorator(func: F) -> F:
+            @wraps(func)
+            async def wrapper(*args, **kwargs) -> Any:
+                return await rcall(
+                    func,
+                    *args,
+                    num_retries=num_retries,
+                    initial_delay=initial_delay,
+                    retry_delay=retry_delay,
+                    backoff_factor=backoff_factor,
+                    retry_default=retry_default,
+                    retry_timeout=retry_timeout,
+                    retry_timing=retry_timing,
+                    verbose_retry=verbose_retry,
+                    error_msg=error_msg,
+                    error_map=error_map,
+                    **kwargs,
+                )
+
+            return wrapper
+
+        return decorator
+
+    @staticmethod
+    def throttle(period: float) -> Callable[[F], F]:
+        """Decorator to limit the execution frequency of a function.
+
+        Args:
+            period: Minimum time in seconds between function calls.
+
+        Returns:
+            The decorated function.
+        """
+
+        def decorator(func: F) -> F:
+            if not is_coroutine_func(func):
+                func = force_async(func)
+            throttle_instance = Throttle(period)
+
+            @wraps(func)
+            async def wrapper(*args, **kwargs):
+                await throttle_instance(func)(*args, **kwargs)
+                return await func(*args, **kwargs)
+
+            return wrapper
+
+        return decorator
+
+    @staticmethod
+    def max_concurrent(limit: int) -> Callable[[F], F]:
+        """Decorator to limit the maximum number of concurrent executions.
+
+        Args:
+            limit: Maximum number of concurrent executions.
+
+        Returns:
+            The decorated function.
+        """
+
+        def decorator(func: F) -> F:
+            if not is_coroutine_func(func):
+                func = force_async(func)
+            semaphore = asyncio.Semaphore(limit)
+
+            @wraps(func)
+            async def wrapper(*args, **kwargs):
+                async with semaphore:
+                    return await func(*args, **kwargs)
+
+            return wrapper
+
+        return decorator
+
+    @staticmethod
+    def compose(*functions: Callable[[T], T]) -> Callable[[F], F]:
+        """Decorator to compose multiple functions, applying in sequence.
+
+        Args:
+            functions: Functions to apply in sequence.
+
+        Returns:
+            The decorated function.
+        """
+
+        def decorator(func: F) -> F:
+            @wraps(func)
+            async def async_wrapper(*args, **kwargs):
+                value = await ucall(func, *args, **kwargs)
+                for function in functions:
+                    try:
+                        value = await ucall(function, value)
+                    except Exception as e:
+                        raise ValueError(
+                            f"Error in function {function.__name__}: {e}"
+                        )
+                return value
+
+            return async_wrapper
+
+        return decorator
+
+    @staticmethod
+    def pre_post_process(
+        preprocess: Callable[..., Any] | None = None,
+        postprocess: Callable[..., Any] | None = None,
+        preprocess_args: Sequence[Any] = (),
+        preprocess_kwargs: dict[str, Any] = {},
+        postprocess_args: Sequence[Any] = (),
+        postprocess_kwargs: dict[str, Any] = {},
+    ) -> Callable[[F], F]:
+        """Decorator to apply pre-processing and post-processing functions.
+
+        Args:
+            preprocess: Function to apply before the main function.
+            postprocess: Function to apply after the main function.
+            preprocess_args: Arguments for the preprocess function.
+            preprocess_kwargs: Keyword arguments for preprocess function.
+            postprocess_args: Arguments for the postprocess function.
+            postprocess_kwargs: Keyword arguments for postprocess function.
+
+        Returns:
+            The decorated function.
+        """
+
+        def decorator(func: F) -> F:
+            @wraps(func)
+            async def async_wrapper(*args, **kwargs) -> Any:
+                preprocessed_args = (
+                    [
+                        await ucall(
+                            preprocess,
+                            arg,
+                            *preprocess_args,
+                            **preprocess_kwargs,
+                        )
+                        for arg in args
+                    ]
+                    if preprocess
+                    else args
+                )
+                preprocessed_kwargs = (
+                    {
+                        k: await ucall(
+                            preprocess,
+                            v,
+                            *preprocess_args,
+                            **preprocess_kwargs,
+                        )
+                        for k, v in kwargs.items()
+                    }
+                    if preprocess
+                    else kwargs
+                )
+                result = await ucall(
+                    func, *preprocessed_args, **preprocessed_kwargs
+                )
+
+                return (
+                    await ucall(
+                        postprocess,
+                        result,
+                        *postprocess_args,
+                        **postprocess_kwargs,
+                    )
+                    if postprocess
+                    else result
+                )
+
+            return async_wrapper
+
+        return decorator
+
+    @staticmethod
+    def map(function: Callable[[Any], Any]) -> Callable:
+        """Decorator to map a function over async function results.
+
+        Applies a mapping function to each element in the list returned
+        by the decorated function. Useful for post-processing results of
+        asynchronous operations, such as transforming data fetched from
+        an API or processing items in a collection concurrently.
+
+        Args:
+            function: Mapping function to apply to each element.
+
+        Returns:
+            Decorated async function with transformed results.
+
+        Examples:
+            >>> @CallDecorator.map(lambda x: x.upper())
+            ... async def get_names():
+            ...     return ["alice", "bob", "charlie"]
+            ... # `get_names` now returns ["ALICE", "BOB", "CHARLIE"]
+        """
+
+        def decorator(func: Callable[..., list[Any]]) -> Callable:
+            if is_coroutine_func(func):
+
+                @wraps(func)
+                async def async_wrapper(*args, **kwargs) -> list[Any]:
+                    values = await func(*args, **kwargs)
+                    return [function(value) for value in values]
+
+                return async_wrapper
+            else:
+
+                @wraps(func)
+                def sync_wrapper(*args, **kwargs) -> list[Any]:
+                    values = func(*args, **kwargs)
+                    return [function(value) for value in values]
+
+                return sync_wrapper
+
+        return decorator