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

lionagi/libs/parse/type_convert/to_num.py

@@ -0,0 +1,358 @@
+import re
+from decimal import Decimal
+from typing import Any
+
+from lionagi.libs.constants import NUM_TYPES, PATTERNS, TYPE_MAP
+
+
+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)}")

lionagi/libs/parse/type_convert/to_str.py

@@ -0,0 +1,195 @@
+import json
+from collections.abc import Callable, Mapping
+from typing import Any, Literal
+
+from pydantic_core import PydanticUndefined, PydanticUndefinedType
+
+from lionagi.libs.constants import UNDEFINED, UndefinedType
+
+from ..xml.convert import dict_to_xml
+from .to_dict import to_dict
+
+
+def _serialize_as(
+    input_,
+    /,
+    *,
+    serialize_as: Literal["json", "xml"],
+    strip_lower: bool = False,
+    chars: str | None = None,
+    str_type: Literal["json", "xml"] | None = None,
+    use_model_dump: bool = False,
+    str_parser: Callable[[str], dict[str, Any]] | None = None,
+    parser_kwargs: dict = {},
+    **kwargs: Any,
+) -> str:
+    try:
+        dict_ = to_dict(
+            input_,
+            use_model_dump=use_model_dump,
+            str_type=str_type,
+            suppress=True,
+            parser=str_parser,
+            **parser_kwargs,
+        )
+        if any((str_type, chars)):
+            str_ = json.dumps(dict_)
+            str_ = _process_string(str_, strip_lower=strip_lower, chars=chars)
+            dict_ = json.loads(str_)
+
+        if serialize_as == "json":
+            return json.dumps(dict_, **kwargs)
+
+        if serialize_as == "xml":
+            return dict_to_xml(dict_, **kwargs)
+    except Exception as e:
+        raise ValueError(
+            f"Failed to serialize input of {type(input_).__name__} "
+            f"into <{str_type}>"
+        ) from e
+
+
+def _to_str_type(input_: Any, /) -> str:
+    if input_ in [set(), [], {}]:
+        return ""
+
+    if isinstance(input_, type(None) | UndefinedType | PydanticUndefinedType):
+        return ""
+
+    if isinstance(input_, bytes | bytearray):
+        return input_.decode("utf-8", errors="replace")
+
+    if isinstance(input_, str):
+        return input_
+
+    if isinstance(input_, Mapping):
+        return json.dumps(dict(input_))
+
+    try:
+        return str(input_)
+    except Exception as e:
+        raise ValueError(
+            f"Could not convert input of type <{type(input_).__name__}> "
+            "to string"
+        ) from e
+
+
+def to_str(
+    input_: Any,
+    /,
+    *,
+    strip_lower: bool = False,
+    chars: str | None = None,
+    str_type: Literal["json", "xml"] | None = None,
+    serialize_as: Literal["json", "xml"] | None = None,
+    use_model_dump: bool = False,
+    str_parser: Callable[[str], dict[str, Any]] | None = None,
+    parser_kwargs: dict = {},
+    **kwargs: Any,
+) -> str:
+    """Convert any input to its string representation.
+
+    Handles various input types, with options for serialization and formatting.
+
+    Args:
+        input_: The input to convert to a string.
+        strip_lower: If True, strip whitespace and convert to lowercase.
+        chars: Specific characters to strip from the result.
+        str_type: Type of string input ("json" or "xml") if applicable.
+        serialize_as: Output serialization format ("json" or "xml").
+        use_model_dump: Use model_dump for Pydantic models if available.
+        str_parser: Custom parser function for string inputs.
+        parser_kwargs: Additional keyword arguments for the parser.
+        **kwargs: Additional arguments passed to json.dumps or serialization.
+
+    Returns:
+        str: The string representation of the input.
+
+    Raises:
+        ValueError: If serialization or conversion fails.
+
+    Examples:
+        >>> to_str(123)
+        '123'
+        >>> to_str("  HELLO  ", strip_lower=True)
+        'hello'
+        >>> to_str({"a": 1}, serialize_as="json")
+        '{"a": 1}'
+        >>> to_str({"a": 1}, serialize_as="xml")
+        '<root><a>1</a></root>'
+    """
+
+    if serialize_as:
+        return _serialize_as(
+            input_,
+            serialize_as=serialize_as,
+            strip_lower=strip_lower,
+            chars=chars,
+            str_type=str_type,
+            use_model_dump=use_model_dump,
+            str_parser=str_parser,
+            parser_kwargs=parser_kwargs,
+            **kwargs,
+        )
+
+    str_ = _to_str_type(input_, **kwargs)
+    if any((strip_lower, chars)):
+        str_ = _process_string(str_, strip_lower=strip_lower, chars=chars)
+    return str_
+
+
+def _process_string(s: str, strip_lower: bool, chars: str | None) -> str:
+    if s in [UNDEFINED, PydanticUndefined, None, [], {}]:
+        return ""
+
+    if strip_lower:
+        s = s.lower()
+        s = s.strip(chars) if chars is not None else s.strip()
+    return s
+
+
+def strip_lower(
+    input_: Any,
+    /,
+    *,
+    chars: str | None = None,
+    str_type: Literal["json", "xml"] | None = None,
+    serialize_as: Literal["json", "xml"] | None = None,
+    use_model_dump: bool = False,
+    str_parser: Callable[[str], dict[str, Any]] | None = None,
+    parser_kwargs: dict = {},
+    **kwargs: Any,
+) -> str:
+    """
+    Convert input to stripped and lowercase string representation.
+
+    This function is a convenience wrapper around to_str that always
+    applies stripping and lowercasing.
+
+    Args:
+        input_: The input to convert to a string.
+        use_model_dump: If True, use model_dump for Pydantic models.
+        chars: Characters to strip from the result.
+        **kwargs: Additional arguments to pass to to_str.
+
+    Returns:
+        Stripped and lowercase string representation of the input.
+
+    Raises:
+        ValueError: If conversion fails.
+
+    Example:
+        >>> strip_lower("  HELLO WORLD  ")
+        'hello world'
+    """
+    return to_str(
+        input_,
+        strip_lower=True,
+        chars=chars,
+        str_type=str_type,
+        serialize_as=serialize_as,
+        use_model_dump=use_model_dump,
+        str_parser=str_parser,
+        parser_kwargs=parser_kwargs,
+        **kwargs,
+    )

lionagi/libs/parse/types.py

@@ -0,0 +1,9 @@
+"""Parsing utilities for various data formats and structures."""
+
+from .flatten import *
+from .json import *
+from .nested import *
+from .string_parse import *
+from .type_convert import *
+from .validate import *
+from .xml import *

lionagi/libs/parse/validate/__init__.py

@@ -0,0 +1,14 @@
+"""Validation utilities for various data types and structures."""
+
+from .boolean import validate_boolean
+from .keys import KeysDict, validate_keys
+from .mapping import validate_mapping
+from .params import ValidateKeysParams
+
+__all__ = [
+    "validate_boolean",
+    "validate_keys",
+    "validate_mapping",
+    "KeysDict",
+    "ValidateKeysParams",
+]

lionagi/libs/parse/validate/boolean.py

@@ -0,0 +1,96 @@
+from numbers import Complex
+from typing import Any
+
+from lionagi.libs.constants import FALSE_VALUES, TRUE_VALUES
+
+
+def validate_boolean(x: Any, /) -> bool:
+    """
+    Forcefully validate and convert the input into a boolean value.
+
+    This function attempts to convert various input types to a boolean value.
+    It recognizes common string representations of true and false, as well
+    as numeric values. The conversion is case-insensitive.
+
+    Args:
+        x: The input to be converted to boolean. Can be:
+           - Boolean: returned as-is
+           - Number (including complex): converted using Python's bool rules
+           - String: converted based on common boolean representations
+           - None: raises TypeError
+           - Other types: converted to string and then evaluated
+
+    Returns:
+        bool: The boolean representation of the input.
+
+    Raises:
+        ValueError: If the input cannot be unambiguously converted to a boolean value.
+        TypeError: If the input type is unsupported or None.
+
+    Examples:
+        >>> validate_boolean(True)
+        True
+        >>> validate_boolean("yes")
+        True
+        >>> validate_boolean("OFF")
+        False
+        >>> validate_boolean(1)
+        True
+        >>> validate_boolean(0j)
+        False
+        >>> validate_boolean(1 + 1j)
+        True
+
+    Notes:
+        - String matching is case-insensitive
+        - Leading/trailing whitespace is stripped
+        - Numeric values follow Python's bool() rules
+        - Complex numbers: bool(0j) is False, bool(any other complex) is True
+        - None values raise TypeError
+        - Empty strings raise ValueError
+    """
+    if x is None:
+        raise TypeError("Cannot convert None to boolean")
+
+    if isinstance(x, bool):
+        return x
+
+    # Handle all numeric types (including complex) using Python's bool
+    if isinstance(x, (int, float, Complex)):
+        return bool(x)
+
+    # Convert to string if not already a string
+    if not isinstance(x, str):
+        try:
+            x = str(x)
+        except Exception as e:
+            raise TypeError(f"Cannot convert {type(x)} to boolean: {str(e)}")
+
+    # Handle string inputs
+    x_cleaned = str(x).strip().lower()
+
+    if not x_cleaned:
+        raise ValueError("Cannot convert empty string to boolean")
+
+    if x_cleaned in TRUE_VALUES:
+        return True
+
+    if x_cleaned in FALSE_VALUES:
+        return False
+
+    # Try numeric conversion as a last resort
+    try:
+        # Try to evaluate as a literal if it looks like a complex number
+        if "j" in x_cleaned:
+            try:
+                return bool(complex(x_cleaned))
+            except ValueError:
+                pass
+        return bool(float(x_cleaned))
+    except ValueError:
+        pass
+
+    raise ValueError(
+        f"Cannot convert '{x}' to boolean. Valid true values are: {sorted(TRUE_VALUES)}, "
+        f"valid false values are: {sorted(FALSE_VALUES)}"
+    )