lionagi 0.14.9__tar.gz → 0.14.11__tar.gz

{lionagi-0.14.9 → lionagi-0.14.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lionagi
-Version: 0.14.9
+Version: 0.14.11
 Summary: An Intelligence Operating System.
 Author-email: HaiyangLi <quantocean.li@gmail.com>, Liangbingyan Luo <llby_luo@outlook.com>
 License:            Apache License
@@ -264,6 +264,10 @@ Provides-Extra: sqlite
 Requires-Dist: aiosqlite>=0.21.0; extra == 'sqlite'
 Provides-Extra: tools
 Requires-Dist: docling>=2.15.0; extra == 'tools'
+Provides-Extra: unstructured
+Requires-Dist: opencv-python>=4.2.0.34; extra == 'unstructured'
+Provides-Extra: xml
+Requires-Dist: xmltodict>=0.12.0; extra == 'xml'
 Description-Content-Type: text/markdown
 
 ![PyPI - Version](https://img.shields.io/pypi/v/lionagi?labelColor=233476aa&color=231fc935)

{lionagi-0.14.9 → lionagi-0.14.11}/lionagi/fields/reason.py

@@ -4,8 +4,8 @@
 
 from pydantic import Field, field_validator
 
+from lionagi.libs.validate.to_num import to_num
 from lionagi.models import FieldModel, HashableModel
-from lionagi.utils import to_num
 
 __all__ = ("Reason",)
 

lionagi-0.14.11/lionagi/libs/concurrency/throttle.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import asyncio
+import functools
+from collections.abc import Callable
+from time import sleep, time
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+__all__ = ("Throttle",)
+
+
+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 = time() - self.last_called
+            if elapsed < self.period:
+                sleep(self.period - elapsed)
+            self.last_called = time()
+            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 = time() - self.last_called
+            if elapsed < self.period:
+                await asyncio.sleep(self.period - elapsed)
+            self.last_called = time()
+            return await func(*args, **kwargs)
+
+        return wrapper

{lionagi-0.14.9 → lionagi-0.14.11}/lionagi/libs/parse.py

@@ -8,7 +8,8 @@ from lionagi.libs.schema.function_to_schema import function_to_schema
 from lionagi.libs.validate.fuzzy_match_keys import fuzzy_match_keys
 from lionagi.libs.validate.fuzzy_validate_mapping import fuzzy_validate_mapping
 from lionagi.libs.validate.string_similarity import string_similarity
-from lionagi.utils import fuzzy_parse_json, to_dict, to_json, to_num
+from lionagi.libs.validate.to_num import to_num
+from lionagi.utils import fuzzy_parse_json, to_dict, to_json
 
 validate_keys = fuzzy_match_keys  # for backward compatibility
 validate_mapping = fuzzy_validate_mapping  # for backward compatibility

lionagi-0.14.11/lionagi/libs/unstructured/pdf_to_image.py

@@ -0,0 +1,45 @@
+from lionagi.utils import check_import, is_import_installed
+
+_HAS_PDF2IMAGE = is_import_installed("pdf2image")
+
+
+def pdf_to_images(
+    pdf_path: str, output_folder: str, dpi: int = 300, fmt: str = "jpeg"
+) -> list:
+    """
+    Convert a PDF file into images, one image per page.
+
+    Args:
+        pdf_path (str): Path to the input PDF file.
+        output_folder (str): Directory to save the output images.
+        dpi (int): Dots per inch (resolution) for conversion (default: 300).
+        fmt (str): Image format (default: 'jpeg'). Use 'png' if preferred.
+
+    Returns:
+        list: A list of file paths for the saved images.
+    """
+    if not _HAS_PDF2IMAGE:
+        raise ModuleNotFoundError(
+            "pdf2image is not installed, please install it with `pip install lionagi[unstructured]`"
+        )
+
+    import os
+
+    convert_from_path = check_import(
+        "pdf2image", import_name="convert_from_path"
+    )
+
+    # Ensure the output folder exists
+    os.makedirs(output_folder, exist_ok=True)
+
+    # Convert PDF to a list of PIL Image objects
+    images = convert_from_path(pdf_path, dpi=dpi)
+
+    saved_paths = []
+    for i, image in enumerate(images):
+        # Construct the output file name
+        image_file = os.path.join(output_folder, f"page_{i + 1}.{fmt}")
+        image.save(image_file, fmt.upper())
+        saved_paths.append(image_file)
+
+    return saved_paths

lionagi-0.14.11/lionagi/libs/unstructured/read_image_to_base64.py

@@ -0,0 +1,33 @@
+from pathlib import Path
+
+from lionagi.utils import is_import_installed
+
+_HAS_OPENCV = is_import_installed("cv2")
+
+
+__all__ = ("read_image_to_base64",)
+
+
+def read_image_to_base64(image_path: str | Path) -> str:
+    if not _HAS_OPENCV:
+        raise ModuleNotFoundError(
+            "OpenCV is not installed, please install it with `pip install lionagi[unstructured]`"
+        )
+
+    import base64
+
+    import cv2
+
+    image_path = str(image_path)
+    image = cv2.imread(image_path, cv2.COLOR_BGR2RGB)
+
+    if image is None:
+        raise ValueError(f"Could not read image from path: {image_path}")
+
+    file_extension = "." + image_path.split(".")[-1]
+
+    success, buffer = cv2.imencode(file_extension, image)
+    if not success:
+        raise ValueError(f"Could not encode image to {file_extension} format.")
+    encoded_image = base64.b64encode(buffer).decode("utf-8")
+    return encoded_image

lionagi-0.14.11/lionagi/libs/validate/to_num.py

@@ -0,0 +1,378 @@
+from __future__ import annotations
+
+import re
+from decimal import Decimal
+from typing import Any, Literal, TypeVar
+
+# Type definitions
+NUM_TYPE_LITERAL = Literal["int", "float", "complex"]
+NUM_TYPES = type[int] | type[float] | type[complex] | NUM_TYPE_LITERAL
+NumericType = TypeVar("NumericType", int, float, complex)
+
+# Type mapping
+TYPE_MAP = {"int": int, "float": float, "complex": complex}
+
+# Regex patterns for different numeric formats
+PATTERNS = {
+    "scientific": r"[-+]?(?:\d*\.)?\d+[eE][-+]?\d+",
+    "complex_sci": r"[-+]?(?:\d*\.)?\d+(?:[eE][-+]?\d+)?[-+](?:\d*\.)?\d+(?:[eE][-+]?\d+)?[jJ]",
+    "complex": r"[-+]?(?:\d*\.)?\d+[-+](?:\d*\.)?\d+[jJ]",
+    "pure_imaginary": r"[-+]?(?:\d*\.)?\d*[jJ]",
+    "percentage": r"[-+]?(?:\d*\.)?\d+%",
+    "fraction": r"[-+]?\d+/\d+",
+    "decimal": r"[-+]?(?:\d*\.)?\d+",
+    "special": r"[-+]?(?:inf|infinity|nan)",
+}
+
+
+def to_num(
+    input_: Any,
+    /,
+    *,
+    upper_bound: int | float | None = None,
+    lower_bound: int | float | None = None,
+    num_type: NUM_TYPES = float,
+    precision: int | None = None,
+    num_count: int = 1,
+) -> int | float | complex | list[int | float | complex]:
+    """Convert input to numeric type(s) with validation and bounds checking.
+
+    Args:
+        input_value: The input to convert to number(s).
+        upper_bound: Maximum allowed value (inclusive).
+        lower_bound: Minimum allowed value (inclusive).
+        num_type: Target numeric type ('int', 'float', 'complex' or type objects).
+        precision: Number of decimal places for rounding (float only).
+        num_count: Number of numeric values to extract.
+
+    Returns:
+        Converted number(s). Single value if num_count=1, else list.
+
+    Raises:
+        ValueError: For invalid input or out of bounds values.
+        TypeError: For invalid input types or invalid type conversions.
+    """
+    # Validate input
+    if isinstance(input_, (list, tuple)):
+        raise TypeError("Input cannot be a sequence")
+
+    # Handle boolean input
+    if isinstance(input_, bool):
+        return validate_num_type(num_type)(input_)
+
+    # Handle direct numeric input
+    if isinstance(input_, (int, float, complex, Decimal)):
+        inferred_type = type(input_)
+        if isinstance(input_, Decimal):
+            inferred_type = float
+        value = float(input_) if not isinstance(input_, complex) else input_
+        value = apply_bounds(value, upper_bound, lower_bound)
+        value = apply_precision(value, precision)
+        return convert_type(value, validate_num_type(num_type), inferred_type)
+
+    # Convert input to string and extract numbers
+    input_str = str(input_)
+    number_matches = extract_numbers(input_str)
+
+    if not number_matches:
+        raise ValueError(f"No valid numbers found in: {input_str}")
+
+    # Process numbers
+    results = []
+    target_type = validate_num_type(num_type)
+
+    number_matches = (
+        number_matches[:num_count]
+        if num_count < len(number_matches)
+        else number_matches
+    )
+
+    for type_and_value in number_matches:
+        try:
+            # Infer appropriate type
+            inferred_type = infer_type(type_and_value)
+
+            # Parse to numeric value
+            value = parse_number(type_and_value)
+
+            # Apply bounds if not complex
+            value = apply_bounds(value, upper_bound, lower_bound)
+
+            # Apply precision
+            value = apply_precision(value, precision)
+
+            # Convert to target type if different from inferred
+            value = convert_type(value, target_type, inferred_type)
+
+            results.append(value)
+
+        except Exception as e:
+            if len(type_and_value) == 2:
+                raise type(e)(
+                    f"Error processing {type_and_value[1]}: {str(e)}"
+                )
+            raise type(e)(f"Error processing {type_and_value}: {str(e)}")
+
+    if results and num_count == 1:
+        return results[0]
+    return results
+
+
+def extract_numbers(text: str) -> list[tuple[str, str]]:
+    """Extract numeric values from text using ordered regex patterns.
+
+    Args:
+        text: The text to extract numbers from.
+
+    Returns:
+        List of tuples containing (pattern_type, matched_value).
+    """
+    combined_pattern = "|".join(PATTERNS.values())
+    matches = re.finditer(combined_pattern, text, re.IGNORECASE)
+    numbers = []
+
+    for match in matches:
+        value = match.group()
+        # Check which pattern matched
+        for pattern_name, pattern in PATTERNS.items():
+            if re.fullmatch(pattern, value, re.IGNORECASE):
+                numbers.append((pattern_name, value))
+                break
+
+    return numbers
+
+
+def validate_num_type(num_type: NUM_TYPES) -> type:
+    """Validate and normalize numeric type specification.
+
+    Args:
+        num_type: The numeric type to validate.
+
+    Returns:
+        The normalized Python type object.
+
+    Raises:
+        ValueError: If the type specification is invalid.
+    """
+    if isinstance(num_type, str):
+        if num_type not in TYPE_MAP:
+            raise ValueError(f"Invalid number type: {num_type}")
+        return TYPE_MAP[num_type]
+
+    if num_type not in (int, float, complex):
+        raise ValueError(f"Invalid number type: {num_type}")
+    return num_type
+
+
+def infer_type(value: tuple[str, str]) -> type:
+    """Infer appropriate numeric type from value.
+
+    Args:
+        value: Tuple of (pattern_type, matched_value).
+
+    Returns:
+        The inferred Python type.
+    """
+    pattern_type, _ = value
+    if pattern_type in ("complex", "complex_sci", "pure_imaginary"):
+        return complex
+    return float
+
+
+def convert_special(value: str) -> float:
+    """Convert special float values (inf, -inf, nan).
+
+    Args:
+        value: The string value to convert.
+
+    Returns:
+        The converted float value.
+    """
+    value = value.lower()
+    if "infinity" in value or "inf" in value:
+        return float("-inf") if value.startswith("-") else float("inf")
+    return float("nan")
+
+
+def convert_percentage(value: str) -> float:
+    """Convert percentage string to float.
+
+    Args:
+        value: The percentage string to convert.
+
+    Returns:
+        The converted float value.
+
+    Raises:
+        ValueError: If the percentage value is invalid.
+    """
+    try:
+        return float(value.rstrip("%")) / 100
+    except ValueError as e:
+        raise ValueError(f"Invalid percentage value: {value}") from e
+
+
+def convert_complex(value: str) -> complex:
+    """Convert complex number string to complex.
+
+    Args:
+        value: The complex number string to convert.
+
+    Returns:
+        The converted complex value.
+
+    Raises:
+        ValueError: If the complex number is invalid.
+    """
+    try:
+        # Handle pure imaginary numbers
+        if value.endswith("j") or value.endswith("J"):
+            if value in ("j", "J"):
+                return complex(0, 1)
+            if value in ("+j", "+J"):
+                return complex(0, 1)
+            if value in ("-j", "-J"):
+                return complex(0, -1)
+            if "+" not in value and "-" not in value[1:]:
+                # Pure imaginary number
+                imag = float(value[:-1] or "1")
+                return complex(0, imag)
+
+        return complex(value.replace(" ", ""))
+    except ValueError as e:
+        raise ValueError(f"Invalid complex number: {value}") from e
+
+
+def convert_type(
+    value: float | complex,
+    target_type: type,
+    inferred_type: type,
+) -> int | float | complex:
+    """Convert value to target type if specified, otherwise use inferred type.
+
+    Args:
+        value: The value to convert.
+        target_type: The requested target type.
+        inferred_type: The inferred type from the value.
+
+    Returns:
+        The converted value.
+
+    Raises:
+        TypeError: If the conversion is not possible.
+    """
+    try:
+        # If no specific type requested, use inferred type
+        if target_type is float and inferred_type is complex:
+            return value
+
+        # Handle explicit type conversions
+        if target_type is int and isinstance(value, complex):
+            raise TypeError("Cannot convert complex number to int")
+        return target_type(value)
+    except (ValueError, TypeError) as e:
+        raise TypeError(
+            f"Cannot convert {value} to {target_type.__name__}"
+        ) from e
+
+
+def apply_bounds(
+    value: float | complex,
+    upper_bound: float | None = None,
+    lower_bound: float | None = None,
+) -> float | complex:
+    """Apply bounds checking to numeric value.
+
+    Args:
+        value: The value to check.
+        upper_bound: Maximum allowed value (inclusive).
+        lower_bound: Minimum allowed value (inclusive).
+
+    Returns:
+        The validated value.
+
+    Raises:
+        ValueError: If the value is outside bounds.
+    """
+    if isinstance(value, complex):
+        return value
+
+    if upper_bound is not None and value > upper_bound:
+        raise ValueError(f"Value {value} exceeds upper bound {upper_bound}")
+    if lower_bound is not None and value < lower_bound:
+        raise ValueError(f"Value {value} below lower bound {lower_bound}")
+    return value
+
+
+def apply_precision(
+    value: float | complex,
+    precision: int | None,
+) -> float | complex:
+    """Apply precision rounding to numeric value.
+
+    Args:
+        value: The value to round.
+        precision: Number of decimal places.
+
+    Returns:
+        The rounded value.
+    """
+    if precision is None or isinstance(value, complex):
+        return value
+    if isinstance(value, float):
+        return round(value, precision)
+    return value
+
+
+def parse_number(type_and_value: tuple[str, str]) -> float | complex:
+    """Parse string to numeric value based on pattern type.
+
+    Args:
+        type_and_value: Tuple of (pattern_type, matched_value).
+
+    Returns:
+        The parsed numeric value.
+
+    Raises:
+        ValueError: If parsing fails.
+    """
+    num_type, value = type_and_value
+    value = value.strip()
+
+    try:
+        if num_type == "special":
+            return convert_special(value)
+
+        if num_type == "percentage":
+            return convert_percentage(value)
+
+        if num_type == "fraction":
+            if "/" not in value:
+                raise ValueError(f"Invalid fraction: {value}")
+            if value.count("/") > 1:
+                raise ValueError(f"Invalid fraction: {value}")
+            num, denom = value.split("/")
+            if not (num.strip("-").isdigit() and denom.isdigit()):
+                raise ValueError(f"Invalid fraction: {value}")
+            denom_val = float(denom)
+            if denom_val == 0:
+                raise ValueError("Division by zero")
+            return float(num) / denom_val
+        if num_type in ("complex", "complex_sci", "pure_imaginary"):
+            return convert_complex(value)
+        if num_type == "scientific":
+            if "e" not in value.lower():
+                raise ValueError(f"Invalid scientific notation: {value}")
+            parts = value.lower().split("e")
+            if len(parts) != 2:
+                raise ValueError(f"Invalid scientific notation: {value}")
+            if not (parts[1].lstrip("+-").isdigit()):
+                raise ValueError(f"Invalid scientific notation: {value}")
+            return float(value)
+        if num_type == "decimal":
+            return float(value)
+
+        raise ValueError(f"Unknown number type: {num_type}")
+    except Exception as e:
+        # Preserve the specific error type but wrap with more context
+        raise type(e)(f"Failed to parse {value} as {num_type}: {str(e)}")