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

lionagi/libs/func/lcall.py

@@ -0,0 +1,57 @@
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from ..parse import to_list
+
+T = TypeVar("T")
+
+
+def lcall(
+    input_: list[Any],
+    func: Callable[..., T],
+    /,
+    *,
+    flatten: bool = False,
+    dropna: bool = False,
+    unique: bool = False,
+    **kwargs,
+) -> list[Any]:
+    """Apply a function to each element of a list synchronously.
+
+    Args:
+        input_: List of inputs to be processed.
+        func: Function to apply to each input element.
+        flatten: If True, flatten the resulting list.
+        dropna: If True, remove None values from the result.
+        unique: If True, return only unique values (requires flatten=True).
+        **kwargs: Additional keyword arguments passed to func.
+
+    Returns:
+        list[Any]: List of results after applying func to each input element.
+
+    Raises:
+        ValueError: If more than one function is provided.
+
+    Examples:
+        >>> lcall([1, 2, 3], lambda x: x * 2)
+        [2, 4, 6]
+        >>> lcall([[1, 2], [3, 4]], sum, flatten=True)
+        [3, 7]
+        >>> lcall([1, 2, 2, 3], lambda x: x, unique=True, flatten=True)
+        [1, 2, 3]
+
+    Note:
+        The function uses to_list internally, which allows for flexible input
+        types beyond just lists.
+    """
+    lst = to_list(input_)
+    if len(to_list(func, flatten=True, dropna=True)) != 1:
+        raise ValueError(
+            "There must be one and only one function for list calling."
+        )
+    return to_list(
+        [func(i, **kwargs) for i in lst],
+        flatten=flatten,
+        dropna=dropna,
+        unique=unique,
+    )

lionagi/libs/func/params.py

@@ -0,0 +1,64 @@
+"""Parameter models for function execution configurations.
+
+This module defines Pydantic models that specify parameters for various function
+execution patterns including timed calls and retry logic.
+"""
+
+from collections.abc import Callable
+
+from pydantic import BaseModel, Field
+
+from lionagi.libs.constants import UNDEFINED, UndefinedType
+
+
+class TimedCallParams(BaseModel):
+
+    initial_delay: int = Field(
+        default=0,
+        ge=0,
+        description="Delay in seconds before function execution",
+    )
+    retry_default: str | UndefinedType = Field(
+        default=UNDEFINED,
+        description="Value to return if an error occurs and suppress_err is True",
+    )
+    retry_timeout: int | None = Field(
+        default=None,
+        ge=0,
+        description="Timeout in seconds for function execution. None means no timeout",
+    )
+    retry_timing: bool = Field(
+        default=False,
+        description="If True, return execution duration along with result",
+    )
+    error_msg: str | None = Field(
+        default=None, description="Custom error message prefix for exceptions"
+    )
+    error_map: dict[type[Exception], Callable[[Exception], None]] | None = (
+        Field(
+            default=None,
+            description="Dictionary mapping exception types to error handler functions",
+        )
+    )
+
+
+class RetryCallParams(TimedCallParams):
+
+    num_retries: int = Field(
+        default=0,
+        ge=0,
+        description="Number of retry attempts after initial failure",
+    )
+    retry_delay: int = Field(
+        default=0,
+        ge=0,
+        description="Base delay in seconds between retry attempts",
+    )
+    backoff_factor: int = Field(
+        default=1,
+        ge=1,
+        description="Factor to multiply retry_delay by after each attempt",
+    )
+    verbose_retry: bool = Field(
+        default=False, description="If True, print retry attempt messages"
+    )

lionagi/libs/func/throttle.py

@@ -0,0 +1,119 @@
+"""
+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
+import functools
+import time
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from ..utils import time as _t
+from .utils import force_async, is_coroutine_func
+
+T = TypeVar("T")
+
+
+class Throttle:
+    """
+    Provide a throttling mechanism for function calls.
+
+    When used as a decorator, it ensures that the decorated function can only
+    be called once per specified period. Subsequent calls within this period
+    are delayed to enforce this constraint.
+
+    Attributes:
+        period: The minimum time period (in seconds) between successive calls.
+    """
+
+    def __init__(self, period: float) -> None:
+        """
+        Initialize a new instance of Throttle.
+
+        Args:
+            period: The minimum time period (in seconds) between
+                successive calls.
+        """
+        self.period = period
+        self.last_called = 0
+
+    def __call__(self, func: Callable[..., T]) -> Callable[..., T]:
+        """
+        Decorate a synchronous function with the throttling mechanism.
+
+        Args:
+            func: The synchronous function to be throttled.
+
+        Returns:
+            The throttled synchronous function.
+        """
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs) -> Any:
+            elapsed = _t() - self.last_called
+            if elapsed < self.period:
+                time.sleep(self.period - elapsed)
+            self.last_called = _t()
+            return func(*args, **kwargs)
+
+        return wrapper
+
+    def __call_async__(
+        self, func: Callable[..., Callable[..., T]]
+    ) -> Callable[..., Callable[..., T]]:
+        """
+        Decorate an asynchronous function with the throttling mechanism.
+
+        Args:
+            func: The asynchronous function to be throttled.
+
+        Returns:
+            The throttled asynchronous function.
+        """
+
+        @functools.wraps(func)
+        async def wrapper(*args, **kwargs) -> Any:
+            elapsed = _t() - self.last_called
+            if elapsed < self.period:
+                await asyncio.sleep(self.period - elapsed)
+            self.last_called = _t()
+            return await func(*args, **kwargs)
+
+        return wrapper
+
+
+def throttle(
+    func: Callable[..., T], period: float
+) -> Callable[..., Callable[..., T]]:
+    """
+    Throttle function execution to limit the rate of calls.
+
+    Args:
+        func: The function to throttle.
+        period: The minimum time interval between consecutive calls.
+
+    Returns:
+        The throttled function.
+    """
+    if not is_coroutine_func(func):
+        func = force_async(func)
+    throttle_instance = Throttle(period)
+
+    @functools.wraps(func)
+    async def wrapper(*args, **kwargs):
+        await throttle_instance(func)(*args, **kwargs)
+        return await func(*args, **kwargs)
+
+    return wrapper

lionagi/libs/func/types.py

@@ -0,0 +1,39 @@
+from .async_calls.alcall import alcall
+from .async_calls.bcall import bcall
+from .async_calls.mcall import mcall
+from .async_calls.pcall import pcall
+from .async_calls.rcall import rcall
+from .async_calls.tcall import tcall
+from .async_calls.ucall import ucall
+from .decorators import CallDecorator
+from .lcall import lcall
+from .throttle import Throttle, throttle
+from .utils import (
+    custom_error_handler,
+    force_async,
+    is_coroutine_func,
+    max_concurrent,
+)
+
+__all__ = [
+    # Async calls
+    "bcall",
+    "alcall",
+    "mcall",
+    "pcall",
+    "rcall",
+    "tcall",
+    "ucall",
+    # List operations
+    "lcall",
+    # Decorators
+    "CallDecorator",
+    # Throttling
+    "Throttle",
+    "throttle",
+    # Utilities
+    "force_async",
+    "is_coroutine_func",
+    "custom_error_handler",
+    "max_concurrent",
+]

lionagi/libs/func/utils.py

@@ -0,0 +1,96 @@
+"""
+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
+import functools
+import logging
+from collections.abc import Callable
+from concurrent.futures import ThreadPoolExecutor
+from functools import lru_cache, wraps
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+def force_async(fn: Callable[..., T]) -> Callable[..., Callable[..., T]]:
+    """
+    Convert a synchronous function to an asynchronous function
+    using a thread pool.
+
+    Args:
+        fn: The synchronous function to convert.
+
+    Returns:
+        The asynchronous version of the function.
+    """
+    pool = ThreadPoolExecutor()
+
+    @wraps(fn)
+    def wrapper(*args, **kwargs):
+        future = pool.submit(fn, *args, **kwargs)
+        return asyncio.wrap_future(future)  # Make it awaitable
+
+    return wrapper
+
+
+@lru_cache(maxsize=None)
+def is_coroutine_func(func: Callable[..., Any]) -> bool:
+    """
+    Check if a function is a coroutine function.
+
+    Args:
+        func: The function to check.
+
+    Returns:
+        True if the function is a coroutine function, False otherwise.
+    """
+    return asyncio.iscoroutinefunction(func)
+
+
+async def custom_error_handler(
+    error: Exception, error_map: dict[type, Callable[[Exception], None]]
+) -> None:
+    for error_type, handler in error_map.items():
+        if isinstance(error, error_type):
+            if is_coroutine_func(handler):
+                return await handler(error)
+            return handler(error)
+    logging.error(f"Unhandled error: {error}")
+
+
+def max_concurrent(
+    func: Callable[..., T], limit: int
+) -> Callable[..., Callable[..., T]]:
+    """
+    Limit the concurrency of function execution using a semaphore.
+
+    Args:
+        func: The function to limit concurrency for.
+        limit: The maximum number of concurrent executions.
+
+    Returns:
+        The function wrapped with concurrency control.
+    """
+    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

lionagi/libs/package/imports.py

@@ -0,0 +1,162 @@
+import importlib.metadata
+import importlib.util
+import logging
+import subprocess
+from typing import Any
+
+from ..utils import run_pip_command
+
+
+def check_import(
+    package_name: str,
+    module_name: str | None = None,
+    import_name: str | None = None,
+    pip_name: str | None = None,
+    attempt_install: bool = True,
+    error_message: str = "",
+):
+    """
+    Check if a package is installed, attempt to install if not.
+
+    Args:
+        package_name: The name of the package to check.
+        module_name: The specific module to import (if any).
+        import_name: The specific name to import from the module (if any).
+        pip_name: The name to use for pip installation (if different).
+        attempt_install: Whether to attempt installation if not found.
+        error_message: Custom error message to use if package not found.
+
+    Raises:
+        ImportError: If the package is not found and not installed.
+        ValueError: If the import fails after installation attempt.
+    """
+    if not is_import_installed(package_name):
+        if attempt_install:
+            logging.info(
+                f"Package {package_name} not found. Attempting " "to install.",
+            )
+            try:
+                return install_import(
+                    package_name=package_name,
+                    module_name=module_name,
+                    import_name=import_name,
+                    pip_name=pip_name,
+                )
+            except ImportError as e:
+                raise ValueError(
+                    f"Failed to install {package_name}: {e}"
+                ) from e
+        else:
+            logging.info(
+                f"Package {package_name} not found. {error_message}",
+            )
+            raise ImportError(
+                f"Package {package_name} not found. {error_message}",
+            )
+
+    return import_module(
+        package_name=package_name,
+        module_name=module_name,
+        import_name=import_name,
+    )
+
+
+def import_module(
+    package_name: str,
+    module_name: str = None,
+    import_name: str | list = None,
+) -> Any:
+    """
+    Import a module by its path.
+
+    Args:
+        module_path: The path of the module to import.
+
+    Returns:
+        The imported module.
+
+    Raises:
+        ImportError: If the module cannot be imported.
+    """
+    try:
+        full_import_path = (
+            f"{package_name}.{module_name}" if module_name else package_name
+        )
+
+        if import_name:
+            import_name = (
+                [import_name]
+                if not isinstance(import_name, list)
+                else import_name
+            )
+            a = __import__(
+                full_import_path,
+                fromlist=import_name,
+            )
+            if len(import_name) == 1:
+                return getattr(a, import_name[0])
+            return [getattr(a, name) for name in import_name]
+        else:
+            return __import__(full_import_path)
+
+    except ImportError as e:
+        raise ImportError(
+            f"Failed to import module {full_import_path}: {e}"
+        ) from e
+
+
+def install_import(
+    package_name: str,
+    module_name: str | None = None,
+    import_name: str | None = None,
+    pip_name: str | None = None,
+):
+    """
+    Attempt to import a package, installing it if not found.
+
+    Args:
+        package_name: The name of the package to import.
+        module_name: The specific module to import (if any).
+        import_name: The specific name to import from the module (if any).
+        pip_name: The name to use for pip installation (if different).
+
+    Raises:
+        ImportError: If the package cannot be imported or installed.
+        subprocess.CalledProcessError: If pip installation fails.
+    """
+    pip_name = pip_name or package_name
+
+    try:
+        return import_module(
+            package_name=package_name,
+            module_name=module_name,
+            import_name=import_name,
+        )
+    except ImportError:
+        logging.info(f"Installing {pip_name}...")
+        try:
+            run_pip_command(["install", pip_name])
+            return import_module(
+                package_name=package_name,
+                module_name=module_name,
+                import_name=import_name,
+            )
+        except subprocess.CalledProcessError as e:
+            raise ImportError(f"Failed to install {pip_name}: {e}") from e
+        except ImportError as e:
+            raise ImportError(
+                f"Failed to import {pip_name} after installation: {e}"
+            ) from e
+
+
+def is_import_installed(package_name: str) -> bool:
+    """
+    Check if a package is installed.
+
+    Args:
+        package_name: The name of the package to check.
+
+    Returns:
+        bool: True if the package is installed, False otherwise.
+    """
+    return importlib.util.find_spec(package_name) is not None

lionagi/libs/package/management.py

@@ -0,0 +1,58 @@
+import importlib.metadata
+import logging
+import subprocess
+
+from ..utils import run_pip_command
+
+
+def list_installed_packages() -> list[str]:
+    """
+    List all installed packages.
+
+    Returns:
+        List[str]: A list of names of installed packages.
+    """
+    try:
+        return [
+            dist.metadata["Name"]
+            for dist in importlib.metadata.distributions()
+        ]
+    except Exception as e:
+        logging.error(f"Failed to list installed packages: {e}")
+        return []
+
+
+def uninstall_package(package_name: str) -> None:
+    """
+    Uninstall a specified package.
+
+    Args:
+        package_name: The name of the package to uninstall.
+
+    Raises:
+        subprocess.CalledProcessError: If the uninstallation fails.
+    """
+    try:
+        run_pip_command(["uninstall", package_name, "-y"])
+        logging.info(f"Successfully uninstalled {package_name}.")
+    except subprocess.CalledProcessError as e:
+        logging.error(f"Failed to uninstall {package_name}. Error: {e}")
+        raise
+
+
+def update_package(package_name: str) -> None:
+    """
+    Update a specified package.
+
+    Args:
+        package_name: The name of the package to update.
+
+    Raises:
+        subprocess.CalledProcessError: If the update fails.
+    """
+    try:
+        run_pip_command(["install", "--upgrade", package_name])
+        logging.info(f"Successfully updated {package_name}.")
+    except subprocess.CalledProcessError as e:
+        logging.error(f"Failed to update {package_name}. Error: {e}")
+        raise

lionagi/libs/package/params.py

@@ -0,0 +1,26 @@
+from pydantic import BaseModel, Field
+
+
+class PackageParams(BaseModel):
+    """Configuration for package import and installation operations.
+
+    This model defines parameters used by package management functions to handle
+    importing and installing Python packages with support for specific module
+    and name imports.
+    """
+
+    package_name: str = Field(
+        description="The name of the package to import or install"
+    )
+    module_name: str | None = Field(
+        default=None,
+        description="The specific module to import from the package (e.g., 'submodule')",
+    )
+    import_name: str | list[str] | None = Field(
+        default=None,
+        description="The specific name(s) to import from the module (e.g., 'ClassName' or ['Class1', 'Class2'])",
+    )
+    pip_name: str | None = Field(
+        default=None,
+        description="The package name to use for pip installation if different from package_name",
+    )

lionagi/libs/package/system.py

@@ -0,0 +1,18 @@
+import platform
+
+
+def get_cpu_architecture() -> str:
+    """
+    Get the CPU architecture.
+
+    Returns:
+        str: 'arm64' if ARM-based, 'x86_64' for Intel/AMD 64-bit, or the
+            actual architecture string for other cases.
+    """
+    arch: str = platform.machine().lower()
+    if "arm" in arch or "aarch64" in arch:
+        return "arm64"
+    elif "x86_64" in arch or "amd64" in arch:
+        return "x86_64"
+    else:
+        return arch

lionagi/libs/package/types.py

@@ -0,0 +1,26 @@
+from .imports import (
+    check_import,
+    import_module,
+    install_import,
+    is_import_installed,
+)
+from .management import (
+    list_installed_packages,
+    uninstall_package,
+    update_package,
+)
+from .system import get_cpu_architecture
+
+__all__ = [
+    # Import handling
+    "check_import",
+    "import_module",
+    "install_import",
+    "is_import_installed",
+    # Package management
+    "list_installed_packages",
+    "uninstall_package",
+    "update_package",
+    # System utilities
+    "get_cpu_architecture",
+]

lionagi/libs/parse/__init__.py

@@ -0,0 +1 @@
+from .types import *

lionagi/libs/parse/flatten/__init__.py

@@ -0,0 +1,9 @@
+"""Utilities for flattening nested data structures."""
+
+from .flatten import flatten
+from .params import FlattenParams
+
+__all__ = [
+    "flatten",
+    "FlattenParams",
+]