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

lionagi/ln/{types.py → types/base.py}

@@ -3,152 +3,26 @@ from __future__ import annotations
 from collections.abc import Sequence
 from dataclasses import dataclass, field
 from enum import Enum as _Enum
-from typing import Any, ClassVar, Final, Literal, TypeVar, Union
+from typing import Any, ClassVar
 
 from typing_extensions import TypedDict, override
 
+from ._sentinel import Undefined, Unset, is_sentinel
+
 __all__ = (
-    "Undefined",
-    "Unset",
-    "MaybeUndefined",
-    "MaybeUnset",
-    "MaybeSentinel",
-    "SingletonType",
-    "UndefinedType",
-    "UnsetType",
-    "KeysDict",
-    "T",
     "Enum",
-    "is_sentinel",
-    "not_sentinel",
+    "ModelConfig",
     "Params",
     "DataClass",
-    "KeysLike",
     "Meta",
+    "KeysDict",
+    "KeysLike",
 )
 
-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]
-
-
-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):
+    """Enhanced Enum with allowed() classmethod."""
+
     @classmethod
     def allowed(cls) -> tuple[str, ...]:
         return tuple(e.value for e in cls)
@@ -160,18 +34,46 @@ class KeysDict(TypedDict, total=False):
     key: Any  # Represents any key-type pair
 
 
+@dataclass(slots=True, frozen=True)
+class ModelConfig:
+    """Configuration for Params and DataClass behavior.
+
+    Attributes:
+        none_as_sentinel: If True, None is treated as a sentinel value (excluded from to_dict).
+        empty_as_sentinel: If True, empty collections are treated as sentinels (excluded from to_dict).
+        strict: If True, no sentinels allowed (all fields must have values).
+        prefill_unset: If True, unset fields are prefilled with Unset.
+        use_enum_values: If True, use enum values instead of enum instances in to_dict().
+    """
+
+    # Sentinel handling (controls what gets excluded from to_dict)
+    none_as_sentinel: bool = False
+    empty_as_sentinel: bool = False
+
+    # Validation
+    strict: bool = False
+    prefill_unset: bool = True
+
+    # Serialization
+    use_enum_values: bool = False
+
+
 @dataclass(slots=True, frozen=True, init=False)
 class Params:
-    """Base class for parameters used in various functions."""
+    """Base class for parameters used in various functions.
 
-    _none_as_sentinel: ClassVar[bool] = False
-    """If True, None is treated as a sentinel value."""
+    Use the ModelConfig class attribute to customize behavior:
 
-    _strict: ClassVar[bool] = False
-    """No sentinels allowed if strict is True."""
+    Example:
+        @dataclass(slots=True, frozen=True, init=False)
+        class MyParams(Params):
+            _config: ClassVar[ModelConfig] = ModelConfig(strict=True)
+            param1: str
+            param2: int
+    """
 
-    _prefill_unset: ClassVar[bool] = True
-    """If True, unset fields are prefilled with Unset."""
+    _config: ClassVar[ModelConfig] = ModelConfig()
+    """Configuration for this Params class."""
 
     _allowed_keys: ClassVar[set[str]] = field(
         default=set(), init=False, repr=False
@@ -193,9 +95,23 @@ class Params:
     @classmethod
     def _is_sentinel(cls, value: Any) -> bool:
         """Check if a value is a sentinel (Undefined or Unset)."""
-        if value is None and cls._none_as_sentinel:
-            return True
-        return is_sentinel(value)
+        return is_sentinel(
+            value,
+            none_as_sentinel=cls._config.none_as_sentinel,
+            empty_as_sentinel=cls._config.empty_as_sentinel,
+        )
+
+    @classmethod
+    def _normalize_value(cls, value: Any) -> Any:
+        """Normalize a value for serialization.
+
+        Handles:
+        - Enum values if use_enum_values is True
+        - Can be extended for other transformations
+        """
+        if cls._config.use_enum_values and isinstance(value, _Enum):
+            return value.value
+        return value
 
     @classmethod
     def allowed(cls) -> set[str]:
@@ -210,10 +126,12 @@ class Params:
     @override
     def _validate(self) -> None:
         def _validate_strict(k):
-            if self._strict and self._is_sentinel(getattr(self, k, Unset)):
+            if self._config.strict and self._is_sentinel(
+                getattr(self, k, Unset)
+            ):
                 raise ValueError(f"Missing required parameter: {k}")
             if (
-                self._prefill_unset
+                self._config.prefill_unset
                 and getattr(self, k, Undefined) is Undefined
             ):
                 object.__setattr__(self, k, Unset)
@@ -236,14 +154,14 @@ class Params:
         data = {}
         exclude = exclude or set()
         for k in self.allowed():
-            if k not in exclude and not self._is_sentinel(
-                v := getattr(self, k, Undefined)
-            ):
-                data[k] = v
+            if k not in exclude:
+                v = getattr(self, k, Undefined)
+                if not self._is_sentinel(v):
+                    data[k] = self._normalize_value(v)
         return data
 
     def __hash__(self) -> int:
-        from ._hash import hash_dict
+        from .._hash import hash_dict
 
         return hash_dict(self.to_dict())
 
@@ -261,16 +179,20 @@ class Params:
 
 @dataclass(slots=True)
 class DataClass:
-    """A base class for data classes with strict parameter handling."""
+    """A base class for data classes with strict parameter handling.
 
-    _none_as_sentinel: ClassVar[bool] = False
-    """If True, None is treated as a sentinel value."""
+    Use the ModelConfig class attribute to customize behavior:
 
-    _strict: ClassVar[bool] = False
-    """No sentinels allowed if strict is True."""
+    Example:
+        @dataclass(slots=True)
+        class MyDataClass(DataClass):
+            _config: ClassVar[ModelConfig] = ModelConfig(strict=True, prefill_unset=False)
+            field1: str
+            field2: int
+    """
 
-    _prefill_unset: ClassVar[bool] = True
-    """If True, unset fields are prefilled with Unset."""
+    _config: ClassVar[ModelConfig] = ModelConfig()
+    """Configuration for this DataClass."""
 
     _allowed_keys: ClassVar[set[str]] = field(
         default=set(), init=False, repr=False
@@ -294,10 +216,12 @@ class DataClass:
     @override
     def _validate(self) -> None:
         def _validate_strict(k):
-            if self._strict and self._is_sentinel(getattr(self, k, Unset)):
+            if self._config.strict and self._is_sentinel(
+                getattr(self, k, Unset)
+            ):
                 raise ValueError(f"Missing required parameter: {k}")
             if (
-                self._prefill_unset
+                self._config.prefill_unset
                 and getattr(self, k, Undefined) is Undefined
             ):
                 self.__setattr__(k, Unset)
@@ -309,18 +233,34 @@ class DataClass:
         data = {}
         exclude = exclude or set()
         for k in type(self).allowed():
-            if k not in exclude and not self._is_sentinel(
-                v := getattr(self, k)
-            ):
-                data[k] = v
+            if k not in exclude:
+                v = getattr(self, k)
+                if not self._is_sentinel(v):
+                    data[k] = self._normalize_value(v)
         return data
 
     @classmethod
     def _is_sentinel(cls, value: Any) -> bool:
         """Check if a value is a sentinel (Undefined or Unset)."""
-        if value is None and cls._none_as_sentinel:
-            return True
-        return is_sentinel(value)
+        return is_sentinel(
+            value,
+            none_as_sentinel=cls._config.none_as_sentinel,
+            empty_as_sentinel=cls._config.empty_as_sentinel,
+        )
+
+    @classmethod
+    def _normalize_value(cls, value: Any) -> Any:
+        """Normalize a value for serialization.
+
+        Handles:
+        - Enum values if use_enum_values is True
+        - Can be extended for other transformations
+        """
+        from enum import Enum as _Enum
+
+        if cls._config.use_enum_values and isinstance(value, _Enum):
+            return value.value
+        return value
 
     def with_updates(self, **kwargs: Any) -> DataClass:
         """Return a new instance with updated fields."""
@@ -329,7 +269,7 @@ class DataClass:
         return type(self)(**dict_)
 
     def __hash__(self) -> int:
-        from ._hash import hash_dict
+        from .._hash import hash_dict
 
         return hash_dict(self.to_dict())
 

lionagi/ln/types/operable.py

@@ -0,0 +1,221 @@
+"""Operable - Container for Spec collections with model generation.
+
+This module provides the Operable class for managing collections of Spec objects
+and generating framework-specific models via adapters.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+from ._sentinel import MaybeUnset, Unset
+
+if TYPE_CHECKING:
+    from .spec import Spec
+
+__all__ = ("Operable",)
+
+
+@dataclass(frozen=True, slots=True, init=False)
+class Operable:
+    """Collection of Spec objects with model generation capabilities.
+
+    Operable manages an ordered collection of Spec objects and provides
+    methods to generate framework-specific models via adapters.
+
+    Attributes:
+        __op_fields__: Ordered tuple of Spec objects
+        name: Optional name for this operable
+
+    Example:
+        >>> from lionagi.ln.types import Spec, Operable
+        >>> specs = (
+        ...     Spec(str, name="username"),
+        ...     Spec(int, name="age"),
+        ... )
+        >>> operable = Operable(specs, name="User")
+        >>> UserModel = operable.create_model(adapter="pydantic")
+    """
+
+    __op_fields__: tuple[Spec, ...]
+    name: str | None
+
+    def __init__(
+        self,
+        specs: tuple[Spec, ...] | list[Spec] = (),
+        *,
+        name: str | None = None,
+    ):
+        """Initialize Operable with specs.
+
+        Args:
+            specs: Tuple or list of Spec objects
+            name: Optional name for this operable
+
+        Raises:
+            TypeError: If specs contains non-Spec objects
+            ValueError: If specs contains duplicate field names
+        """
+        # Import here to avoid circular import
+        from .spec import Spec
+
+        # Convert to tuple if list
+        if isinstance(specs, list):
+            specs = tuple(specs)
+
+        # Validate all items are Spec objects
+        for i, item in enumerate(specs):
+            if not isinstance(item, Spec):
+                raise TypeError(
+                    f"All specs must be Spec objects, got {type(item).__name__} "
+                    f"at index {i}"
+                )
+
+        # Check for duplicate names
+        names = [s.name for s in specs if s.name is not None]
+        if len(names) != len(set(names)):
+            from collections import Counter
+
+            duplicates = [
+                name for name, count in Counter(names).items() if count > 1
+            ]
+            raise ValueError(
+                f"Duplicate field names found: {duplicates}. "
+                "Each spec must have a unique name."
+            )
+
+        object.__setattr__(self, "__op_fields__", specs)
+        object.__setattr__(self, "name", name)
+
+    def allowed(self) -> set[str]:
+        """Get set of allowed field names.
+
+        Returns:
+            Set of field names from specs
+        """
+        return {i.name for i in self.__op_fields__}
+
+    def check_allowed(self, *args, as_boolean: bool = False):
+        """Check if field names are allowed.
+
+        Args:
+            *args: Field names to check
+            as_boolean: If True, return bool instead of raising
+
+        Returns:
+            True if all allowed, False if as_boolean=True and not all allowed
+
+        Raises:
+            ValueError: If as_boolean=False and not all allowed
+        """
+        if not set(args).issubset(self.allowed()):
+            if as_boolean:
+                return False
+            raise ValueError(
+                "Some specified fields are not allowed: "
+                f"{set(args).difference(self.allowed())}"
+            )
+        return True
+
+    def get(self, key: str, /, default=Unset) -> MaybeUnset[Spec]:
+        """Get Spec by field name.
+
+        Args:
+            key: Field name
+            default: Default value if not found
+
+        Returns:
+            Spec object or default
+        """
+        if not self.check_allowed(key, as_boolean=True):
+            return default
+        for i in self.__op_fields__:
+            if i.name == key:
+                return i
+        return default
+
+    def get_specs(
+        self,
+        *,
+        include: set[str] | None = None,
+        exclude: set[str] | None = None,
+    ) -> tuple[Spec, ...]:
+        """Get filtered tuple of Specs.
+
+        Args:
+            include: Only include these field names
+            exclude: Exclude these field names
+
+        Returns:
+            Filtered tuple of Specs
+
+        Raises:
+            ValueError: If both include and exclude specified, or if invalid names
+        """
+        if include is not None and exclude is not None:
+            raise ValueError("Cannot specify both include and exclude")
+
+        if include:
+            if self.check_allowed(*include, as_boolean=True) is False:
+                raise ValueError(
+                    "Some specified fields are not allowed: "
+                    f"{set(include).difference(self.allowed())}"
+                )
+            return tuple(
+                self.get(i) for i in include if self.get(i) is not Unset
+            )
+
+        if exclude:
+            _discards = {
+                self.get(i) for i in exclude if self.get(i) is not Unset
+            }
+            return tuple(s for s in self.__op_fields__ if s not in _discards)
+
+        return self.__op_fields__
+
+    def create_model(
+        self,
+        adapter: Literal["pydantic"] = "pydantic",
+        model_name: str | None = None,
+        include: set[str] | None = None,
+        exclude: set[str] | None = None,
+        **kw,
+    ):
+        """Create framework-specific model from specs.
+
+        Args:
+            adapter: Adapter type (currently only "pydantic")
+            model_name: Name for generated model
+            include: Only include these fields
+            exclude: Exclude these fields
+            **kw: Additional adapter-specific kwargs
+
+        Returns:
+            Generated model class
+
+        Raises:
+            ImportError: If adapter not installed
+            ValueError: If adapter not supported
+        """
+        match adapter:
+            case "pydantic":
+                try:
+                    from lionagi.adapters.spec_adapters import (
+                        PydanticSpecAdapter,
+                    )
+                except ImportError as e:
+                    raise ImportError(
+                        "PydanticSpecAdapter requires Pydantic. "
+                        "Install with: pip install pydantic"
+                    ) from e
+
+                kws = {
+                    "model_name": model_name or self.name or "DynamicModel",
+                    "include": include,
+                    "exclude": exclude,
+                    **kw,
+                }
+                return PydanticSpecAdapter.create_model(self, **kws)
+            case _:
+                raise ValueError(f"Unsupported adapter: {adapter}")