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

lionagi/ln/_to_list.py

@@ -0,0 +1,176 @@
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass
+from enum import Enum as _Enum
+from typing import Any, ClassVar
+
+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,15 @@
+import asyncio
+from collections.abc import Callable
+from functools import lru_cache
+from typing import Any
+
+__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/manager.py

@@ -1,6 +1,7 @@
 from collections.abc import Callable
 
 from lionagi.protocols._concepts import Manager
+from lionagi.utils import is_coro_func
 
 """
 experimental
@@ -8,14 +9,15 @@ experimental
 
 
 class OperationManager(Manager):
-    def __init__(self, *args, **kwargs):
+    def __init__(self):
         super().__init__()
         self.registry: dict[str, Callable] = {}
-        self.register_operations(*args, **kwargs)
 
-    def register_operations(self, *args, **kwargs) -> None:
-        operations = {}
-        if args:
-            operations = {i.__name__ for i in args if hasattr(i, "__name__")}
-        operations.update(kwargs)
-        self.registry.update(operations)
+    def register(self, operation: str, func: Callable, update: bool = False):
+        if operation in self.registry and not update:
+            raise ValueError(f"Operation '{operation}' is already registered.")
+        if not is_coro_func(func):
+            raise ValueError(
+                f"Operation '{operation}' must be an async function."
+            )
+        self.registry[operation] = func

lionagi/operations/node.py

@@ -26,7 +26,7 @@ logger = logging.getLogger("operation")
 
 
 class Operation(Node, Event):
-    operation: BranchOperations
+    operation: BranchOperations | str
     parameters: dict[str, Any] | BaseModel = Field(
         default_factory=dict,
         description="Parameters for the operation",
@@ -74,12 +74,11 @@ class Operation(Node, Event):
         return self.execution.response if self.execution else None
 
     async def invoke(self, branch: Branch):
-        meth = getattr(branch, self.operation, None)
+        meth = branch.get_operation(self.operation)
         if meth is None:
             raise ValueError(f"Unsupported operation type: {self.operation}")
 
         start = asyncio.get_event_loop().time()
-
         try:
             self.execution.status = EventStatus.PROCESSING
             self.branch_id = branch.id

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/event.py

@@ -2,11 +2,16 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+import contextlib
+import json
 from enum import Enum
 from typing import Any
 
 from pydantic import Field, field_serializer
 
+from lionagi.ln import Unset
+from lionagi.utils import to_dict
+
 from .element import Element
 
 __all__ = (
@@ -16,6 +21,9 @@ __all__ = (
 )
 
 
+_SIMPLE_TYPE = (str, bytes, bytearray, int, float, type(None), Enum)
+
+
 class EventStatus(str, Enum):
     """Status states for tracking action execution progress.
 
@@ -79,6 +87,44 @@ class Execution:
             f"response={self.response}, error={self.error})"
         )
 
+    def to_dict(self) -> dict:
+        """Converts the execution state to a dictionary.
+
+        Returns:
+            dict: A dictionary representation of the execution state.
+        """
+        res_ = Unset
+        json_serializable = True
+
+        if not isinstance(self.response, _SIMPLE_TYPE):
+            json_serializable = False
+            try:
+                # check whether response is JSON serializable
+                json.dumps(self.response)
+                res_ = self.response
+                json_serializable = True
+            except Exception:
+                with contextlib.suppress(Exception):
+                    # attempt to convert to dict
+                    d_ = to_dict(
+                        self.response,
+                        recursive=True,
+                        recursive_python_only=False,
+                    )
+                    json.dumps(d_)
+                    res_ = d_
+                    json_serializable = True
+
+        if res_ is Unset and not json_serializable:
+            res_ = "<unserializable>"
+
+        return {
+            "status": self.status.value,
+            "duration": self.duration,
+            "response": res_ or self.response,
+            "error": self.error,
+        }
+
 
 class Event(Element):
     """Extends Element with an execution state.
@@ -101,12 +147,7 @@ class Event(Element):
             dict: The serialized data containing status, duration, response,
             and error fields.
         """
-        return {
-            "status": val.status.value,
-            "duration": val.duration,
-            "response": val.response,
-            "error": val.error,
-        }
+        return val.to_dict()
 
     @property
     def response(self) -> Any:

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

@@ -2,7 +2,7 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-from collections.abc import AsyncGenerator
+from collections.abc import AsyncGenerator, Callable
 from enum import Enum
 from typing import Any, Literal
 
@@ -14,6 +14,7 @@ from lionagi.config import settings
 from lionagi.fields import Instruct
 from lionagi.libs.schema.as_readable import as_readable
 from lionagi.models.field_model import FieldModel
+from lionagi.operations.manager import OperationManager
 from lionagi.protocols.action.tool import FuncTool, Tool, ToolRef
 from lionagi.protocols.types import (
     ID,
@@ -47,7 +48,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, is_coro_func
 
 from .prompts import LION_SYSTEM_MESSAGE
 
@@ -109,6 +112,7 @@ class Branch(Element, Communicatable, Relational):
     _action_manager: ActionManager | None = PrivateAttr(None)
     _imodel_manager: iModelManager | None = PrivateAttr(None)
     _log_manager: LogManager | None = PrivateAttr(None)
+    _operation_manager: OperationManager | None = PrivateAttr(None)
 
     def __init__(
         self,
@@ -229,6 +233,8 @@ class Branch(Element, Communicatable, Relational):
         else:
             self._log_manager = LogManager(**Settings.Config.LOG, logs=logs)
 
+        self._operation_manager = OperationManager()
+
     # -------------------------------------------------------------------------
     # Properties to expose managers and core data
     # -------------------------------------------------------------------------
@@ -302,6 +308,11 @@ class Branch(Element, Communicatable, Relational):
         """
         return self._action_manager.registry
 
+    def get_operation(self, operation: str) -> Callable | None:
+        if hasattr(self, operation):
+            return getattr(self, operation)
+        return self._operation_manager.registry.get(operation)
+
     # -------------------------------------------------------------------------
     # Cloning
     # -------------------------------------------------------------------------
@@ -1268,7 +1279,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,