lionagi 0.18.0__py3-none-any.whl → 0.18.2__py3-none-any.whl

lionagi/fields.py

@@ -0,0 +1,83 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .operations.fields import (
+        ActionRequestModel,
+        ActionResponseModel,
+        Instruct,
+        Reason,
+        get_default_field,
+    )
+
+_lazy_imports = {}
+
+
+def __getattr__(name: str):
+    if name in _lazy_imports:
+        return _lazy_imports[name]
+
+    if name == "ActionRequestModel":
+        from .operations.fields import ActionRequestModel
+
+        _lazy_imports[name] = ActionRequestModel
+        return ActionRequestModel
+
+    if name == "ActionResponseModel":
+        from .operations.fields import ActionResponseModel
+
+        _lazy_imports[name] = ActionResponseModel
+        return ActionResponseModel
+
+    if name == "Instruct":
+        from .operations.fields import Instruct
+
+        _lazy_imports[name] = Instruct
+        return Instruct
+
+    if name == "Reason":
+        from .operations.fields import Reason
+
+        _lazy_imports[name] = Reason
+        return Reason
+
+    from .operations.fields import get_default_field
+
+    if name == "get_default_field":
+
+        _lazy_imports[name] = get_default_field
+        return get_default_field
+
+    if name == "ACTION_REQUESTS_FIELD":
+        return get_default_field("action_requests")
+
+    if name == "ACTION_RESPONSES_FIELD":
+        return get_default_field("action_responses")
+
+    if name == "ACTION_REQUIRED_FIELD":
+        return get_default_field("action_required")
+
+    if name == "INSTRUCT_FIELD":
+        return get_default_field("instruct")
+
+    if name == "LIST_INSTRUCT_FIELD_MODEL":
+        return get_default_field("instruct", listable=True)
+
+    if name == "REASON_FIELD":
+        return get_default_field("reason")
+
+    raise AttributeError(f"module {__name__} has no attribute {name}")
+
+
+__all__ = (
+    "ACTION_REQUESTS_FIELD",
+    "ACTION_RESPONSES_FIELD",
+    "ACTION_REQUIRED_FIELD",
+    "INSTRUCT_FIELD",
+    "LIST_INSTRUCT_FIELD_MODEL",
+    "REASON_FIELD",
+    "ActionRequestModel",
+    "ActionResponseModel",
+    "Instruct",
+    "Reason",
+    "get_default_field",
+)

lionagi/ln/__init__.py

@@ -1,4 +1,4 @@
-from ._async_call import alcall, bcall
+from ._async_call import AlcallParams, BcallParams, alcall, bcall
 from ._hash import hash_dict
 from ._json_dump import (
     get_orjson_default,
@@ -80,4 +80,6 @@ __all__ = (
     "not_sentinel",
     "to_dict",
     "fuzzy_validate_mapping",
+    "AlcallParams",
+    "BcallParams",
 )

lionagi/ln/_async_call.py

@@ -15,7 +15,7 @@ from .concurrency import (
     is_coro_func,
     move_on_after,
 )
-from .types import Params, T, Unset, not_sentinel
+from .types import ModelConfig, Params, T, Unset, not_sentinel
 
 _INITIALIZED = False
 _MODEL_LIKE = None
@@ -262,7 +262,7 @@ async def bcall(
 @dataclass(slots=True, init=False, frozen=True)
 class AlcallParams(Params):
     # ClassVar attributes
-    _none_as_sentinel: ClassVar[bool] = True
+    _config: ClassVar[ModelConfig] = ModelConfig(none_as_sentinel=True)
     _func: ClassVar[Any] = alcall
 
     # input processing

lionagi/ln/concurrency/primitives.py

@@ -142,15 +142,15 @@ class CapacityLimiter:
         """Get the number of currently available tokens."""
         return self._lim.available_tokens
 
-    def acquire_on_behalf_of(self, borrower: object) -> None:
-        """Synchronously acquire capacity on behalf of another object.
+    async def acquire_on_behalf_of(self, borrower: object) -> None:
+        """Asynchronously acquire capacity on behalf of another object.
 
         For resource pooling where the acquirer differs from the releaser.
 
         Args:
             borrower: Object that will be responsible for releasing.
         """
-        self._lim.acquire_on_behalf_of(borrower)
+        await self._lim.acquire_on_behalf_of(borrower)
 
     def release_on_behalf_of(self, borrower: object) -> None:
         """Release capacity that was acquired on behalf of an object.
@@ -326,6 +326,6 @@ class Condition:
         """Wake up all tasks waiting on this condition."""
         self._condition.notify_all()
 
-    def statistics(self) -> anyio.abc.ConditionStatistics:
+    def statistics(self) -> anyio.ConditionStatistics:
         """Return statistics about waiting tasks."""
         return self._condition.statistics()

lionagi/ln/concurrency/task.py

@@ -7,6 +7,7 @@ from contextlib import asynccontextmanager
 from typing import Any, TypeVar
 
 import anyio
+import anyio.abc
 
 T = TypeVar("T")
 R = TypeVar("R")

lionagi/ln/fuzzy/_fuzzy_match.py

@@ -1,7 +1,7 @@
 from dataclasses import dataclass
 from typing import Any, ClassVar, Literal
 
-from ..types import KeysLike, Params, Unset
+from ..types import KeysLike, ModelConfig, Params, Unset
 from ._string_similarity import (
     SIMILARITY_ALGO_MAP,
     SIMILARITY_TYPE,
@@ -152,7 +152,7 @@ def fuzzy_match_keys(
 
 @dataclass(slots=True, init=False, frozen=True)
 class FuzzyMatchKeysParams(Params):
-    _none_as_sentinel: ClassVar[bool] = False
+    _config: ClassVar[ModelConfig] = ModelConfig(none_as_sentinel=False)
     _func: ClassVar[Any] = fuzzy_match_keys
 
     similarity_algo: SIMILARITY_TYPE | SimilarityFunc = "jaro_winkler"

lionagi/ln/types/__init__.py

@@ -0,0 +1,51 @@
+from ._sentinel import (
+    MaybeSentinel,
+    MaybeUndefined,
+    MaybeUnset,
+    SingletonType,
+    T,
+    Undefined,
+    UndefinedType,
+    Unset,
+    UnsetType,
+    is_sentinel,
+    not_sentinel,
+)
+from .base import (
+    DataClass,
+    Enum,
+    KeysDict,
+    KeysLike,
+    Meta,
+    ModelConfig,
+    Params,
+)
+from .operable import Operable
+from .spec import CommonMeta, Spec
+
+__all__ = (
+    # Sentinel types
+    "Undefined",
+    "Unset",
+    "MaybeUndefined",
+    "MaybeUnset",
+    "MaybeSentinel",
+    "SingletonType",
+    "UndefinedType",
+    "UnsetType",
+    "is_sentinel",
+    "not_sentinel",
+    # Base classes
+    "ModelConfig",
+    "Enum",
+    "Params",
+    "DataClass",
+    "Meta",
+    "KeysDict",
+    "KeysLike",
+    "T",
+    # Spec system
+    "Spec",
+    "CommonMeta",
+    "Operable",
+)

lionagi/ln/types/_sentinel.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from typing import Any, Final, Literal, TypeVar, Union
+
+__all__ = (
+    "Undefined",
+    "Unset",
+    "MaybeUndefined",
+    "MaybeUnset",
+    "MaybeSentinel",
+    "SingletonType",
+    "UndefinedType",
+    "UnsetType",
+    "is_sentinel",
+    "not_sentinel",
+    "T",
+)
+
+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"
+
+    def __reduce__(self):
+        """Ensure pickle preservation of singleton identity."""
+        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"
+
+    def __reduce__(self):
+        """Ensure pickle preservation of singleton identity."""
+        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]
+
+_EMPTY_TUPLE = (tuple(), set(), frozenset(), dict(), list(), "")
+
+
+def is_sentinel(
+    value: Any,
+    *,
+    none_as_sentinel: bool = False,
+    empty_as_sentinel: bool = False,
+) -> bool:
+    """Check if a value is any sentinel (Undefined or Unset)."""
+    if none_as_sentinel and value is None:
+        return True
+    if empty_as_sentinel and value in _EMPTY_TUPLE:
+        return True
+    return value is Undefined or value is Unset
+
+
+def not_sentinel(
+    value: Any, none_as_sentinel: bool = False, empty_as_sentinel: bool = False
+) -> bool:
+    """Check if a value is NOT a sentinel. Useful for filtering operations."""
+    return not is_sentinel(
+        value,
+        none_as_sentinel=none_as_sentinel,
+        empty_as_sentinel=empty_as_sentinel,
+    )