lionagi 0.14.11__py3-none-any.whl → 0.15.0__py3-none-any.whl

lionagi/ln/_to_list.py

@@ -0,0 +1,175 @@
+from dataclasses import dataclass
+from enum import Enum as _Enum
+from typing import Any, ClassVar, Iterable, Mapping
+
+from pydantic import BaseModel
+from pydantic_core import PydanticUndefinedType
+
+from ._hash import hash_dict
+from ._models import Params
+from ._types import UndefinedType, UnsetType
+
+__all__ = ("to_list", "ToListParams")
+
+
+_SKIP_TYPE = (str, bytes, bytearray, Mapping, BaseModel, _Enum)
+_TUPLE_SET_TYPES = (tuple, set, frozenset)
+_SKIP_TUPLE_SET = (*_SKIP_TYPE, *_TUPLE_SET_TYPES)
+_SINGLETONE_TYPES = (UndefinedType, UnsetType, PydanticUndefinedType)
+_BYTE_LIKE_TYPES = (str, bytes, bytearray)
+
+
+def to_list(
+    input_: Any,
+    /,
+    *,
+    flatten: bool = False,
+    dropna: bool = False,
+    unique: bool = False,
+    use_values: bool = False,
+    flatten_tuple_set: bool = False,
+) -> list:
+    """Convert input to a list with optional transformations.
+
+    Transforms various input types into a list with configurable processing
+    options for flattening, filtering, and value extraction.
+
+    Args:
+        input_: Value to convert to list.
+        flatten: If True, recursively flatten nested iterables.
+        dropna: If True, remove None and undefined values.
+        unique: If True, remove duplicates (requires flatten=True).
+        use_values: If True, extract values from enums/mappings.
+        flatten_tuple_items: If True, include tuples in flattening.
+        flatten_set_items: If True, include sets in flattening.
+
+    Raises:
+        ValueError: If unique=True is used without flatten=True.
+    """
+
+    def _process_list(
+        lst: list[Any],
+        flatten: bool,
+        dropna: bool,
+    ) -> list[Any]:
+        """Process list according to flatten and dropna options.
+
+        Args:
+            lst: Input list to process.
+            flatten: Whether to flatten nested iterables.
+            dropna: Whether to remove None/undefined values.
+        """
+        result = []
+        skip_types = _SKIP_TYPE if flatten_tuple_set else _SKIP_TUPLE_SET
+
+        for item in lst:
+            if dropna and (
+                item is None or isinstance(item, _SINGLETONE_TYPES)
+            ):
+                continue
+
+            is_iterable = isinstance(item, Iterable)
+            should_skip = isinstance(item, skip_types)
+
+            if is_iterable and not should_skip:
+                item_list = list(item)
+                if flatten:
+                    result.extend(_process_list(item_list, flatten, dropna))
+                else:
+                    result.append(_process_list(item_list, flatten, dropna))
+            else:
+                result.append(item)
+
+        return result
+
+    def _to_list_type(input_: Any, use_values: bool) -> list[Any]:
+        """Convert input to initial list based on type.
+
+        Args:
+            input_: Value to convert to list.
+            use_values: Whether to extract values from containers.
+        """
+        if input_ is None or isinstance(input_, _SINGLETONE_TYPES):
+            return []
+
+        if isinstance(input_, list):
+            return input_
+
+        if isinstance(input_, type) and issubclass(input_, _Enum):
+            members = input_.__members__.values()
+            return (
+                [member.value for member in members]
+                if use_values
+                else list(members)
+            )
+
+        if isinstance(input_, _BYTE_LIKE_TYPES):
+            return list(input_) if use_values else [input_]
+
+        if isinstance(input_, Mapping):
+            return (
+                list(input_.values())
+                if use_values and hasattr(input_, "values")
+                else [input_]
+            )
+
+        if isinstance(input_, BaseModel):
+            return [input_]
+
+        if isinstance(input_, Iterable) and not isinstance(
+            input_, _BYTE_LIKE_TYPES
+        ):
+            return list(input_)
+
+        return [input_]
+
+    if unique and not flatten:
+        raise ValueError("unique=True requires flatten=True")
+
+    initial_list = _to_list_type(input_, use_values=use_values)
+    processed = _process_list(initial_list, flatten=flatten, dropna=dropna)
+
+    if unique:
+        seen = set()
+        out = []
+        try:
+            return [x for x in processed if not (x in seen or seen.add(x))]
+        except TypeError:
+            for i in processed:
+                hash_value = None
+                try:
+                    hash_value = hash(i)
+                except TypeError:
+                    if isinstance(i, (BaseModel, Mapping)):
+                        hash_value = hash_dict(i)
+                    else:
+                        raise ValueError(
+                            "Unhashable type encountered in list unique value processing."
+                        )
+                if hash_value not in seen:
+                    seen.add(hash_value)
+                    out.append(i)
+            return out
+
+    return processed
+
+
+@dataclass(slots=True, frozen=True, init=False)
+class ToListParams(Params):
+    _func: ClassVar[Any] = to_list
+
+    flatten: bool
+    """If True, recursively flatten nested iterables."""
+    dropna: bool
+    """If True, remove None and undefined values."""
+    unique: bool
+    """If True, remove duplicates (requires flatten=True)."""
+    use_values: bool
+    """If True, extract values from enums/mappings."""
+    flatten_tuple_set: bool
+    """If True, include tuples and sets in flattening."""
+
+    def __call__(self, input_: Any, **kw) -> list:
+        """Convert parameters to a list."""
+        partial = self.as_partial()
+        return partial(input_, **kw)

lionagi/ln/_types.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+from enum import Enum as _Enum
+from typing import Any, Final, Literal, TypeVar, Union
+
+from typing_extensions import TypedDict
+
+__all__ = (
+    "Undefined",
+    "Unset",
+    "MaybeUndefined",
+    "MaybeUnset",
+    "MaybeSentinel",
+    "SingletonType",
+    "UndefinedType",
+    "UnsetType",
+    "KeysDict",
+    "T",
+    "Enum",
+    "is_sentinel",
+    "not_sentinel",
+)
+
+T = TypeVar("T")
+
+
+class _SingletonMeta(type):
+    """Metaclass that guarantees exactly one instance per subclass.
+
+    This ensures that sentinel values maintain identity across the entire application,
+    allowing safe identity checks with 'is' operator.
+    """
+
+    _cache: dict[type, "SingletonType"] = {}
+
+    def __call__(cls, *a, **kw):
+        if cls not in cls._cache:
+            cls._cache[cls] = super().__call__(*a, **kw)
+        return cls._cache[cls]
+
+
+class SingletonType(metaclass=_SingletonMeta):
+    """Base class for singleton sentinel types.
+
+    Provides consistent interface for sentinel values with:
+    - Identity preservation across deepcopy
+    - Falsy boolean evaluation
+    - Clear string representation
+    """
+
+    __slots__: tuple[str, ...] = ()
+
+    def __deepcopy__(self, memo):  # copy & deepcopy both noop
+        return self
+
+    def __copy__(self):
+        return self
+
+    # concrete classes *must* override the two methods below
+    def __bool__(self) -> bool: ...
+    def __repr__(self) -> str: ...
+
+
+class UndefinedType(SingletonType):
+    """Sentinel for a key or field entirely missing from a namespace.
+
+    Use this when:
+    - A field has never been set
+    - A key doesn't exist in a mapping
+    - A value is conceptually undefined (not just unset)
+
+    Example:
+        >>> d = {"a": 1}
+        >>> d.get("b", Undefined) is Undefined
+        True
+    """
+
+    __slots__ = ()
+
+    def __bool__(self) -> Literal[False]:
+        return False
+
+    def __repr__(self) -> Literal["Undefined"]:
+        return "Undefined"
+
+    def __str__(self) -> Literal["Undefined"]:
+        return "Undefined"
+
+
+class UnsetType(SingletonType):
+    """Sentinel for a key present but value not yet provided.
+
+    Use this when:
+    - A parameter exists but hasn't been given a value
+    - Distinguishing between None and "not provided"
+    - API parameters that are optional but need explicit handling
+
+    Example:
+        >>> def func(param=Unset):
+        ...     if param is not Unset:
+        ...         # param was explicitly provided
+        ...         process(param)
+    """
+
+    __slots__ = ()
+
+    def __bool__(self) -> Literal[False]:
+        return False
+
+    def __repr__(self) -> Literal["Unset"]:
+        return "Unset"
+
+    def __str__(self) -> Literal["Unset"]:
+        return "Unset"
+
+
+Undefined: Final = UndefinedType()
+"""A key or field entirely missing from a namespace"""
+Unset: Final = UnsetType()
+"""A key present but value not yet provided."""
+
+MaybeUndefined = Union[T, UndefinedType]
+MaybeUnset = Union[T, UnsetType]
+MaybeSentinel = Union[T, UndefinedType, UnsetType]
+
+
+def is_sentinel(value: Any) -> bool:
+    """Check if a value is any sentinel (Undefined or Unset)."""
+    return value is Undefined or value is Unset
+
+
+def not_sentinel(value: Any) -> bool:
+    """Check if a value is NOT a sentinel. Useful for filtering operations."""
+    return value is not Undefined and value is not Unset
+
+
+class Enum(_Enum):
+    @classmethod
+    def allowed(cls) -> tuple[str, ...]:
+        return tuple(e.value for e in cls)
+
+
+class KeysDict(TypedDict, total=False):
+    """TypedDict for keys dictionary."""
+
+    key: Any  # Represents any key-type pair

lionagi/{libs → ln}/concurrency/__init__.py

@@ -22,8 +22,9 @@ from .resource_tracker import (
     untrack_resource,
 )
 from .task import TaskGroup, create_task_group
+from .utils import is_coro_func
 
-__all__ = [
+__all__ = (
     "TaskGroup",
     "create_task_group",
     "CancelScope",
@@ -46,4 +47,5 @@ __all__ = [
     "untrack_resource",
     "cleanup_check",
     "get_global_tracker",
-]
+    "is_coro_func",
+)

lionagi/ln/concurrency/utils.py

@@ -0,0 +1,14 @@
+import asyncio
+from functools import lru_cache
+from typing import Any, Callable
+
+__all__ = ("is_coro_func",)
+
+
+@lru_cache(maxsize=None)
+def _is_coro_func(func: Callable[..., Any]) -> bool:
+    return asyncio.iscoroutinefunction(func)
+
+
+def is_coro_func(func: Callable[..., Any]) -> bool:
+    return _is_coro_func(func)

lionagi/models/hashable_model.py

@@ -1,8 +1,7 @@
 from pydantic import BaseModel
 from typing_extensions import Self
 
-from lionagi.libs.hash.hash_dict import hash_dict
-from lionagi.utils import UNDEFINED
+from lionagi.utils import UNDEFINED, hash_dict
 
 
 class HashableModel(BaseModel):

lionagi/operations/brainstorm/brainstorm.py

@@ -12,10 +12,11 @@ from lionagi.fields.instruct import (
     Instruct,
     InstructResponse,
 )
+from lionagi.ln import alcall
 from lionagi.protocols.generic.element import ID
 from lionagi.session.branch import Branch
 from lionagi.session.session import Session
-from lionagi.utils import alcall, to_list
+from lionagi.utils import to_list
 
 from ..utils import prepare_instruct, prepare_session
 from .prompt import PROMPT

lionagi/operations/flow.py

@@ -12,9 +12,9 @@ using Events for synchronization and CapacityLimiter for concurrency control.
 import os
 from typing import Any
 
-from lionagi.libs.concurrency.primitives import CapacityLimiter
-from lionagi.libs.concurrency.primitives import Event as ConcurrencyEvent
-from lionagi.libs.concurrency.task import create_task_group
+from lionagi.ln.concurrency.primitives import CapacityLimiter
+from lionagi.ln.concurrency.primitives import Event as ConcurrencyEvent
+from lionagi.ln.concurrency.task import create_task_group
 from lionagi.operations.node import Operation
 from lionagi.protocols.types import EventStatus, Graph
 from lionagi.session.branch import Branch

lionagi/operations/plan/plan.py

@@ -11,10 +11,10 @@ from lionagi.fields.instruct import (
     Instruct,
     InstructResponse,
 )
+from lionagi.ln import alcall
 from lionagi.protocols.types import ID
 from lionagi.session.branch import Branch
 from lionagi.session.session import Session
-from lionagi.utils import alcall
 
 from ..utils import prepare_instruct, prepare_session
 from .prompt import EXPANSION_PROMPT, PLAN_PROMPT
@@ -366,8 +366,8 @@ async def plan(
                 parallel_chunk_results = await alcall(
                     all_chunks,
                     execute_chunk_sequentially,
-                    flatten=True,
-                    dropna=True,
+                    output_flatten=True,
+                    output_dropna=True,
                 )
 
                 out.execute = parallel_chunk_results

lionagi/protocols/generic/pile.py

@@ -54,7 +54,7 @@ def async_synchronized(func: Callable):
     return wrapper
 
 
-class Pile(Element, Collective[E], Generic[E], Adaptable, AsyncAdaptable):
+class Pile(Element, Collective[T], Generic[T], Adaptable, AsyncAdaptable):
     """Thread-safe async-compatible, ordered collection of elements.
 
     The Pile class provides a thread-safe, async-compatible collection with:

lionagi/service/hooks/_types.py

@@ -8,7 +8,7 @@ from typing import TypeVar
 
 from typing_extensions import TypedDict
 
-from lionagi.utils import StringEnum
+from lionagi.utils import Enum
 
 SC = TypeVar("SC")  # streaming chunk type
 
@@ -21,7 +21,7 @@ __all__ = (
 )
 
 
-class HookEventTypes(StringEnum):
+class HookEventTypes(str, Enum):
     PreEventCreate = "pre_event_create"
     PreInvokation = "pre_invokation"
     PostInvokation = "post_invokation"

lionagi/session/branch.py

@@ -47,7 +47,9 @@ from lionagi.service.connections.endpoint import Endpoint
 from lionagi.service.types import iModel, iModelManager
 from lionagi.settings import Settings
 from lionagi.tools.base import LionTool
-from lionagi.utils import UNDEFINED, alcall, bcall, copy
+from lionagi.utils import UNDEFINED
+from lionagi.utils import alcall as alcall_legacy
+from lionagi.utils import copy
 
 from .prompts import LION_SYSTEM_MESSAGE
 
@@ -1268,7 +1270,7 @@ class Branch(Element, Communicatable, Relational):
         action_request: ActionRequest | BaseModel | dict,
         **kwargs,
     ) -> list:
-        return await alcall(action_request, self._act, **kwargs)
+        return await alcall_legacy(action_request, self._act, **kwargs)
 
     async def _sequential_act(
         self,