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

lionagi/libs/parse/nested/ninsert.py

@@ -0,0 +1,103 @@
+from typing import Any
+
+from ..type_convert.to_list import to_list
+
+
+def ninsert(
+    nested_structure: dict[Any, Any] | list[Any],
+    /,
+    indices: list[str | int],
+    value: Any,
+    *,
+    current_depth: int = 0,
+) -> None:
+    """
+    Inserts a value into a nested structure at a specified path.
+
+    Navigates a nested dictionary or list based on a sequence of indices or
+    keys and inserts `value` at the final location. This method can create
+    intermediate dictionaries or lists as needed.
+
+    Args:
+        nested_structure: The nested structure to modify.
+        indices: The sequence of keys or indices defining the insertion path.
+        value: The value to insert at the specified location.
+        current_depth: Internal use only; tracks the current depth during
+            recursive calls.
+
+    Raises:
+        ValueError: If the indices list is empty.
+        TypeError: If an invalid key or container type is encountered.
+
+    Examples:
+        >>> subject_ = {'a': {'b': [1, 2]}}
+        >>> ninsert(subject_, ['a', 'b', 2], 3)
+        >>> assert subject_ == {'a': {'b': [1, 2, 3]}}
+
+        >>> subject_ = []
+        >>> ninsert(subject_, [0, 'a'], 1)
+        >>> assert subject_ == [{'a': 1}]
+    """
+    if not indices:
+        raise ValueError("Indices list cannot be empty")
+
+    indices = to_list(indices)
+    for i, part in enumerate(indices[:-1]):
+        if isinstance(part, int):
+            if isinstance(nested_structure, dict):
+                raise TypeError(
+                    f"Unsupported key type: {type(part).__name__}."
+                    "Only string keys are acceptable.",
+                )
+            while len(nested_structure) <= part:
+                nested_structure.append(None)
+            if nested_structure[part] is None or not isinstance(
+                nested_structure[part], (dict, list)
+            ):
+                next_part = indices[i + 1]
+                nested_structure[part] = (
+                    [] if isinstance(next_part, int) else {}
+                )
+        elif isinstance(nested_structure, dict):
+            if part is None:
+                raise TypeError("Cannot use NoneType as a key in a dictionary")
+            if isinstance(part, (float, complex)):
+                raise TypeError(
+                    f"Unsupported key type: {type(part).__name__}."
+                    "Only string keys are acceptable.",
+                )
+            if part not in nested_structure:
+                next_part = indices[i + 1]
+                nested_structure[part] = (
+                    [] if isinstance(next_part, int) else {}
+                )
+        else:
+            raise TypeError(
+                f"Invalid container type: {type(nested_structure)} "
+                "encountered during insertion"
+            )
+
+        nested_structure = nested_structure[part]
+        current_depth += 1
+
+    last_part = indices[-1]
+    if isinstance(last_part, int):
+        if isinstance(nested_structure, dict):
+            raise TypeError(
+                f"Unsupported key type: {type(last_part).__name__}."
+                "Only string keys are acceptable.",
+            )
+        while len(nested_structure) <= last_part:
+            nested_structure.append(None)
+        nested_structure[last_part] = value
+    elif isinstance(nested_structure, list):
+        raise TypeError("Cannot use non-integer index on a list")
+    else:
+        if last_part is None:
+            raise TypeError("Cannot use NoneType as a key in a dictionary")
+        if isinstance(last_part, (float, complex)):
+            raise TypeError(
+                f"Unsupported key type: {type(last_part).__name__}."
+                "Only string keys are acceptable.",
+            )
+        nested_structure[last_part] = value

lionagi/libs/parse/nested/nmerge.py

@@ -0,0 +1,155 @@
+from collections import defaultdict
+from collections.abc import Callable, Sequence
+from itertools import chain
+from typing import Any
+
+from .utils import is_homogeneous
+
+
+def nmerge(
+    nested_structure: Sequence[dict[str, Any] | list[Any]],
+    /,
+    *,
+    overwrite: bool = False,
+    dict_sequence: bool = False,
+    sort_list: bool = False,
+    custom_sort: Callable[[Any], Any] | None = None,
+) -> dict[str, Any] | list[Any]:
+    """
+    Merge multiple dictionaries, lists, or sequences into a unified structure.
+
+    Args:
+        nested_structure: A sequence containing dictionaries, lists, or other
+            iterable objects to merge.
+        overwrite: If True, overwrite existing keys in dictionaries with
+            those from subsequent dictionaries.
+        dict_sequence: Enables unique key generation for duplicate keys by
+            appending a sequence number. Applicable only if `overwrite` is
+            False.
+        sort_list: When True, sort the resulting list after merging. It does
+            not affect dictionaries.
+        custom_sort: An optional callable that defines custom sorting logic
+            for the merged list.
+
+    Returns:
+        A merged dictionary or list, depending on the types present in
+        `nested_structure`.
+
+    Raises:
+        TypeError: If `nested_structure` contains objects of incompatible
+            types that cannot be merged.
+    """
+    if not isinstance(nested_structure, list):
+        raise TypeError("Please input a list")
+    if is_homogeneous(nested_structure, dict):
+        return _merge_dicts(nested_structure, overwrite, dict_sequence)
+    elif is_homogeneous(nested_structure, list):
+        return _merge_sequences(nested_structure, sort_list, custom_sort)
+    else:
+        raise TypeError(
+            "All items in the input list must be of the same type, "
+            "either dict, list, or Iterable."
+        )
+
+
+def _deep_merge_dicts(
+    dict1: dict[str, Any], dict2: dict[str, Any]
+) -> dict[str, Any]:
+    """
+    Recursively merges two dictionaries, combining values where keys overlap.
+
+    Args:
+        dict1: The first dictionary.
+        dict2: The second dictionary.
+
+    Returns:
+        The merged dictionary.
+    """
+    for key in dict2:
+        if key in dict1:
+            if isinstance(dict1[key], dict) and isinstance(dict2[key], dict):
+                _deep_merge_dicts(dict1[key], dict2[key])
+            else:
+                if not isinstance(dict1[key], list):
+                    dict1[key] = [dict1[key]]
+                dict1[key].append(dict2[key])
+        else:
+            dict1[key] = dict2[key]
+    return dict1
+
+
+def _merge_dicts(
+    iterables: list[dict[str, Any]],
+    dict_update: bool,
+    dict_sequence: bool,
+) -> dict[str, Any]:
+    """
+    Merges a list of dictionaries into a single dictionary, with options for
+    handling duplicate keys and sequences.
+
+    Args:
+        iterables: A list of dictionaries to merge.
+        dict_update: If True, overwrite existing keys in dictionaries
+            with those from subsequent dictionaries.
+        dict_sequence: Enables unique key generation for duplicate keys
+            by appending a sequence number
+
+    Returns:
+        The merged dictionary.
+    """
+    merged_dict = {}  # {'a': [1, 2]}
+    sequence_counters = defaultdict(int)
+    list_values = {}
+
+    for d in iterables:  # [{'a': [1, 2]}, {'a': [3, 4]}]
+        for key, value in d.items():  # {'a': [3, 4]}
+            if key not in merged_dict or dict_update:
+                if (
+                    key in merged_dict
+                    and isinstance(merged_dict[key], dict)
+                    and isinstance(value, dict)
+                ):
+                    _deep_merge_dicts(merged_dict[key], value)
+                else:
+                    merged_dict[key] = value  # {'a': [1, 2]}
+                    if isinstance(value, list):
+                        list_values[key] = True
+            elif dict_sequence:
+                sequence_counters[key] += 1
+                new_key = f"{key}{sequence_counters[key]}"
+                merged_dict[new_key] = value
+            else:
+                if not isinstance(merged_dict[key], list) or list_values.get(
+                    key, False
+                ):
+                    merged_dict[key] = [merged_dict[key]]
+                merged_dict[key].append(value)
+
+    return merged_dict
+
+
+def _merge_sequences(
+    iterables: list[list[Any]],
+    sort_list: bool,
+    custom_sort: Callable[[Any], Any] | None = None,
+) -> list[Any]:
+    """
+    Merges a list of lists into a single list, with options for sorting and
+    custom sorting logic.
+
+    Args:
+        iterables: A list of lists to merge.
+        sort_list: When True, sort the resulting list after merging.
+        custom_sort: An optional callable that defines custom sorting logic
+            for the merged list.
+
+    Returns:
+        The merged list.
+    """
+    merged_list = list(chain(*iterables))
+    if sort_list:
+        if custom_sort:
+            return sorted(merged_list, key=custom_sort)
+        else:
+            return sorted(merged_list, key=lambda x: (isinstance(x, str), x))
+    return merged_list

lionagi/libs/parse/nested/npop.py

@@ -0,0 +1,66 @@
+from collections.abc import Sequence
+from typing import Any
+
+from ...constants import UNDEFINED
+from ..type_convert.to_list import to_list
+
+
+def npop(
+    input_: dict[str, Any] | list[Any],
+    /,
+    indices: str | int | Sequence[str | int],
+    default: Any = UNDEFINED,
+) -> Any:
+    """
+    Perform a nested pop operation on the input structure.
+
+    This function navigates through the nested structure using the provided
+    indices and removes and returns the value at the final location.
+
+    Args:
+        input_: The input nested structure (dict or list) to pop from.
+        indices: A single index or a sequence of indices to navigate the
+            nested structure.
+        default: The value to return if the key is not found. If not
+            provided, a KeyError will be raised.
+
+    Returns:
+        The value at the specified nested location.
+
+    Raises:
+        ValueError: If the indices list is empty.
+        KeyError: If a key is not found in a dictionary.
+        IndexError: If an index is out of range for a list.
+        TypeError: If an operation is not supported on the current data type.
+    """
+    if not indices:
+        raise ValueError("Indices list cannot be empty")
+
+    indices = to_list(indices)
+
+    current = input_
+    for key in indices[:-1]:
+        if isinstance(current, dict):
+            if current.get(key):
+                current = current[key]
+            else:
+                raise KeyError(f"{key} is not found in {current}")
+        elif isinstance(current, list) and isinstance(key, int):
+            if key >= len(current):
+                raise KeyError(
+                    f"{key} exceeds the length of the list {current}"
+                )
+            elif key < 0:
+                raise ValueError("list index cannot be negative")
+            current = current[key]
+
+    last_key = indices[-1]
+    try:
+        return current.pop(
+            last_key,
+        )
+    except Exception as e:
+        if default is not UNDEFINED:
+            return default
+        else:
+            raise KeyError(f"Invalid npop. Error: {e}")

lionagi/libs/parse/nested/nset.py

@@ -0,0 +1,89 @@
+from collections.abc import Sequence
+from typing import Any
+
+from ..type_convert.to_list import to_list
+from .utils import ensure_list_index
+
+
+def nset(
+    nested_structure: dict[str, Any] | list[Any],
+    /,
+    indices: str | int | Sequence[str | int],
+    value: Any,
+) -> None:
+    """Set a value within a nested structure at the specified path.
+
+    This method allows setting a value deep within a nested dictionary or list
+    by specifying a path to the target location using a sequence of indices.
+    Each index in the sequence represents a level in the nested structure,
+    with integers used for list indices and strings for dictionary keys.
+
+    Args:
+        nested_structure: The nested structure to modify.
+        indices: The path of indices leading to the target location.
+        value: The value to set at the specified location.
+
+    Raises:
+        ValueError: If the indices sequence is empty.
+        TypeError: If the target container is not a list or dictionary,
+                   or if the index type is incorrect.
+
+    Examples:
+        >>> data = {'a': {'b': [10, 20]}}
+        >>> nset(data, ['a', 'b', 1], 99)
+        >>> assert data == {'a': {'b': [10, 99]}}
+
+        >>> data = [0, [1, 2], 3]
+        >>> nset(data, [1, 1], 99)
+        >>> assert data == [0, [1, 99], 3]
+    """
+
+    if not indices:
+        raise ValueError(
+            "Indices list is empty, cannot determine target container"
+        )
+
+    _indices = to_list(indices)
+    target_container = nested_structure
+
+    for i, index in enumerate(_indices[:-1]):
+        if isinstance(target_container, list):
+            if not isinstance(index, int):
+                raise TypeError("Cannot use non-integer index on a list")
+            ensure_list_index(target_container, index)
+            if target_container[index] is None:
+                next_index = _indices[i + 1]
+                target_container[index] = (
+                    [] if isinstance(next_index, int) else {}
+                )
+        elif isinstance(target_container, dict):
+            if isinstance(index, int):
+                raise TypeError(
+                    f"Unsupported key type: {type(index).__name__}. "
+                    "Only string keys are acceptable."
+                )
+            if index not in target_container:
+                next_index = _indices[i + 1]
+                target_container[index] = (
+                    [] if isinstance(next_index, int) else {}
+                )
+        else:
+            raise TypeError("Target container is not a list or dictionary")
+
+        target_container = target_container[index]
+
+    last_index = _indices[-1]
+    if isinstance(target_container, list):
+        if not isinstance(last_index, int):
+            raise TypeError("Cannot use non-integer index on a list")
+        ensure_list_index(target_container, last_index)
+        target_container[last_index] = value
+    elif isinstance(target_container, dict):
+        if not isinstance(last_index, str):
+            raise TypeError(
+                f"Unsupported key type: {type(last_index).__name__}. "
+                "Only string keys are acceptable."
+            )
+        target_container[last_index] = value
+    else:
+        raise TypeError("Cannot set value on non-list/dict element")

lionagi/libs/parse/nested/to_flat_list.py

@@ -0,0 +1,64 @@
+from collections.abc import Generator, Iterable
+from typing import Any
+
+from pydantic_core import PydanticUndefinedType
+
+from lionagi.libs.constants import UndefinedType
+
+
+def _flatten_list_generator(
+    lst_: list[Any], dropna: bool
+) -> Generator[Any, None, None]:
+    for i in lst_:
+        if isinstance(i, list):
+            yield from _flatten_list_generator(i, dropna)
+        else:
+            yield i
+
+
+def to_flat_list(
+    input_: Any, /, *, dropna: bool = False, unique: bool = True
+) -> list[Any]:
+    if isinstance(input_, type(None) | UndefinedType | PydanticUndefinedType):
+        return []
+
+    if not isinstance(input_, Iterable) or isinstance(
+        input_, (str, bytes, bytearray, dict)
+    ):
+        return [input_]
+
+    if isinstance(input_, list):
+        return _flatten_list(input_, dropna, unique=unique)
+
+    if isinstance(input_, tuple):
+        return _flatten_list(list(input_), dropna, unique=unique)
+
+    if isinstance(input_, set):
+        return list(_dropna_iterator(list(input_))) if dropna else list(input_)
+
+    try:
+        iterable_list = list(input_)
+        return _flatten_list(iterable_list, dropna, unique=unique)
+
+    except Exception as e:
+        raise ValueError(
+            f"Could not convert {type(input_)} object to list: {e}"
+        ) from e
+
+
+def _dropna_iterator(lst_: list[Any]) -> iter:
+    return (item for item in lst_ if item is not None)
+
+
+def _flatten_list(
+    lst_: list[Any], dropna: bool = False, unique: bool = False
+) -> list[Any]:
+    flattened_list = list(_flatten_list_generator(lst_, dropna))
+    if dropna:
+        flattened_list = list(_dropna_iterator(flattened_list))
+    if unique:
+        try:
+            flattened_list = list(set(flattened_list))
+        except Exception:
+            pass
+    return flattened_list

lionagi/libs/parse/nested/utils.py

@@ -0,0 +1,185 @@
+from typing import Any
+
+from ...constants import UNDEFINED
+
+
+def is_homogeneous(
+    iterables: list[Any] | dict[Any, Any], type_check: type | tuple[type, ...]
+) -> bool:
+    """
+    Check if all elements in a list or all values in a dict are of same type.
+
+    Args:
+        iterables: The list or dictionary to check.
+        type_check: The type to check against.
+
+    Returns:
+        True if all elements/values are of the same type, False otherwise.
+    """
+    if isinstance(iterables, list):
+        return all(isinstance(it, type_check) for it in iterables)
+
+    elif isinstance(iterables, dict):
+        return all(isinstance(val, type_check) for val in iterables.values())
+
+    else:
+        return isinstance(iterables, type_check)
+
+
+def is_same_dtype(
+    input_: list[Any] | dict[Any, Any],
+    dtype: type | None = None,
+    return_dtype: bool = False,
+) -> bool | tuple[bool, type | None]:
+    """
+    Check if all elements in a list or dict values are of the same data type.
+
+    Args:
+        input_: The input list or dictionary to check.
+        dtype: The data type to check against. If None, uses the type of the
+            first element.
+        return_dtype: If True, return the data type with the check result.
+
+    Returns:
+        If return_dtype is False, returns True if all elements are of the
+        same type (or if the input is empty), False otherwise.
+        If return_dtype is True, returns a tuple (bool, type | None).
+    """
+    if not input_:
+        return True
+
+    iterable = input_.values() if isinstance(input_, dict) else input_
+    first_element_type = type(next(iter(iterable), None))
+
+    dtype = dtype or first_element_type
+
+    result = all(isinstance(element, dtype) for element in iterable)
+    return (result, dtype) if return_dtype else result
+
+
+def is_structure_homogeneous(
+    structure: Any, return_structure_type: bool = False
+) -> bool | tuple[bool, type | None]:
+    """
+    Check if a nested structure is homogeneous (no mix of lists and dicts).
+
+    Args:
+        structure: The nested structure to check.
+        return_structure_type: If True, return the type of the homogeneous
+            structure.
+
+    Returns:
+        If return_structure_type is False, returns True if the structure is
+        homogeneous, False otherwise.
+        If True, returns a tuple (bool, type | None).
+
+    Examples:
+        >>> is_structure_homogeneous({'a': {'b': 1}, 'c': {'d': 2}})
+        True
+        >>> is_structure_homogeneous({'a': {'b': 1}, 'c': [1, 2]})
+        False
+    """
+
+    def _check_structure(substructure):
+        structure_type = None
+        if isinstance(substructure, list):
+            structure_type = list
+            for item in substructure:
+                if not isinstance(item, structure_type) and isinstance(
+                    item, list | dict
+                ):
+                    return False, None
+                result, _ = _check_structure(item)
+                if not result:
+                    return False, None
+        elif isinstance(substructure, dict):
+            structure_type = dict
+            for item in substructure.values():
+                if not isinstance(item, structure_type) and isinstance(
+                    item, list | dict
+                ):
+                    return False, None
+                result, _ = _check_structure(item)
+                if not result:
+                    return False, None
+        return True, structure_type
+
+    is_homogeneous, structure_type = _check_structure(structure)
+    return (
+        (is_homogeneous, structure_type)
+        if return_structure_type
+        else is_homogeneous
+    )
+
+
+def deep_update(
+    original: dict[Any, Any], update: dict[Any, Any]
+) -> dict[Any, Any]:
+    """
+    Recursively merge two dicts, updating nested dicts instead of overwriting.
+
+    Args:
+        original: The dictionary to update.
+        update: The dictionary containing updates to apply to `original`.
+
+    Returns:
+        The `original` dictionary after applying updates from `update`.
+
+    Note:
+        This method modifies the `original` dictionary in place.
+    """
+    for key, value in update.items():
+        if isinstance(value, dict) and key in original:
+            original[key] = deep_update(original.get(key, {}), value)
+        else:
+            original[key] = value
+    return original
+
+
+def get_target_container(
+    nested: list[Any] | dict[Any, Any], indices: list[int | str]
+) -> list[Any] | dict[Any, Any]:
+    """
+    Retrieve the target container in a nested structure using indices.
+
+    Args:
+        nested: The nested structure to navigate.
+        indices: A list of indices to navigate through the nested structure.
+
+    Returns:
+        The target container at the specified path.
+
+    Raises:
+        IndexError: If a list index is out of range.
+        KeyError: If a dictionary key is not found.
+        TypeError: If the current element is neither a list nor a dictionary.
+    """
+    current_element = nested
+    for index in indices:
+        if isinstance(current_element, list):
+            if isinstance(index, str) and index.isdigit():
+                index = int(index)
+
+            if isinstance(index, int) and 0 <= index < len(current_element):
+                current_element = current_element[index]
+
+            else:
+                raise IndexError("List index is invalid or out of range")
+
+        elif isinstance(current_element, dict):
+            if index in current_element:
+                current_element = current_element.get(index, None)
+            else:
+                raise KeyError("Key not found in dictionary")
+        else:
+            raise TypeError(
+                "Current element is neither a list nor a dictionary"
+            )
+    return current_element
+
+
+def ensure_list_index(
+    lst: list[Any], index: int, default: Any = UNDEFINED
+) -> None:
+    while len(lst) <= index:
+        lst.append(default if default is not UNDEFINED else None)

lionagi/libs/parse/string_parse/__init__.py

@@ -0,0 +1,11 @@
+"""String parsing utilities for code blocks and docstrings."""
+
+from .code_block import extract_code_block
+from .docstring import extract_docstring
+from .function_ import function_to_schema
+
+__all__ = [
+    "extract_code_block",
+    "extract_docstring",
+    "function_to_schema",
+]