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

lionagi/core/generic/progression.py

@@ -0,0 +1,388 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+import contextlib
+from collections.abc import Iterator
+from typing import Any, Self
+
+from pydantic import field_validator
+from typing_extensions import override
+
+from lionagi.core.typing import ID, Field, ItemNotFoundError, LnID, Ordering
+from lionagi.libs.parse import to_list
+
+from .element import Element
+from .utils import to_list_type, validate_order
+
+
+class Progression(Element, Ordering):
+    """A flexible, ordered sequence container for Lion IDs.
+
+    The Progression class provides an ordered sequence of Lion IDs with support
+    for standard sequence operations, ID validation, and element containment
+    checks. It maintains order while ensuring ID validity and uniqueness.
+
+    Key Features:
+        - Ordered sequence operations
+        - ID validation and uniqueness
+        - Element containment checks
+        - Memory efficient storage
+        - Slice operations
+
+    Attributes:
+        name (str | None): Optional name for the progression
+        order (list[ID.ID]): Ordered list of Lion IDs
+    """
+
+    name: str | None = Field(
+        None,
+        title="Name",
+        description="The name of the progression.",
+    )
+
+    order: list[ID.ID] = Field(
+        default_factory=list,
+        title="Order",
+        description="The order of the progression.",
+    )
+
+    @field_validator("order", mode="before")
+    def _validate_order(cls, value: ID.RefSeq) -> list[LnID]:
+        if not value:
+            return []
+        try:
+            return validate_order(value)
+        except Exception as e:
+            raise ValueError(f"Invalid order: {e}")
+
+    def __contains__(self, item: ID.RefSeq | ID.Ref) -> bool:
+        """Check if item(s) are in the progression."""
+        if item is None or not self.order:
+            return False
+
+        item = to_list_type(item) if not isinstance(item, list) else item
+
+        check = False
+        for i in item:
+            check = False
+            if isinstance(i, str):
+                check = i in self.order
+            elif isinstance(i, Element):
+                check = i.ln_id in self.order
+            if not check:
+                return False
+        return check
+
+    def __list__(self) -> list[LnID]:
+        """Return a copy of the order."""
+        return self.order[:]
+
+    def __len__(self) -> int:
+        """Get the length of the progression."""
+        return len(self.order)
+
+    def __getitem__(self, key: int | slice) -> ID.IDSeq:
+        """Get an item or slice of items from the progression.
+
+        Args:
+            key: Integer index or slice object.
+
+        Returns:
+            Single ID for integer key, new Progression for slice.
+
+        Raises:
+            TypeError: If key is not int or slice.
+            ItemNotFoundError: If index out of range.
+        """
+        if not isinstance(key, (int, slice)):
+            key_cls = key.__class__.__name__
+            raise TypeError(
+                f"indices must be integers or slices, not {key_cls}"
+            )
+
+        try:
+            a = self.order[key]
+            if not a:
+                raise ItemNotFoundError(f"index {key} item not found")
+            if isinstance(key, slice):
+                return self.__class__(order=a)
+            else:
+                return a
+        except IndexError:
+            raise ItemNotFoundError(f"index {key} item not found")
+
+    def __setitem__(self, key: int | slice, value: ID.RefSeq) -> None:
+        """Set an item or slice of items in the progression.
+
+        Args:
+            key: Integer index or slice object.
+            value: Item(s) to set.
+        """
+        a = validate_order(value)
+        self.order[key] = a if isinstance(key, int) else a
+        self.order = to_list(self.order, flatten=True)
+
+    def __delitem__(self, key: int | slice) -> None:
+        """Delete an item or slice of items from the progression."""
+        del self.order[key]
+
+    def __iter__(self) -> Iterator[LnID]:
+        """Iterate over the items in the progression."""
+        return iter(self.order)
+
+    def __next__(self) -> LnID:
+        """Return the next item in the progression."""
+        try:
+            return next(iter(self.order))
+        except StopIteration:
+            raise StopIteration("No more items in the progression")
+
+    def size(self) -> int:
+        """Get the size of the progression."""
+        return len(self)
+
+    def clear(self) -> None:
+        """Clear the progression."""
+        self.order.clear()
+
+    def append(self, item: ID.RefSeq, /) -> None:
+        """Append an item to the end of the progression.
+
+        Args:
+            item: Item or sequence to append.
+        """
+        item_ = validate_order(item)
+        self.order.extend(item_)
+
+    def pop(self, index: int = None, /) -> str:
+        """Remove and return an item from the progression.
+
+        Args:
+            index: Optional index to pop from. Default is last item.
+
+        Returns:
+            The removed item's ID.
+
+        Raises:
+            ItemNotFoundError: If progression is empty or index invalid.
+        """
+        try:
+            if index is None:
+                return self.order.pop()
+            return self.order.pop(index)
+        except IndexError as e:
+            raise ItemNotFoundError("pop index out of range") from e
+
+    def include(self, item: ID.RefSeq, /) -> None:
+        """Include item(s) in the progression if not already present.
+
+        Args:
+            item: Item or sequence to include.
+        """
+        item_ = validate_order(item)
+        for i in item_:
+            if i not in self.order:
+                self.order.append(i)
+
+    def exclude(self, item: int | ID.RefSeq, /) -> None:
+        """Exclude an item or items from the progression.
+
+        Args:
+            item: Item or sequence to exclude.
+        """
+        for i in validate_order(item):
+            while i in self:
+                self.remove(i)
+
+    def is_empty(self) -> bool:
+        """Check if the progression is empty."""
+        return not self.order
+
+    def reverse(self) -> "Progression":
+        """Return a reversed progression."""
+        return self.__class__(order=list(reversed(self.order)), name=self.name)
+
+    def __reverse__(self) -> "Progression":
+        """Return a reversed progression."""
+        return self.reverse()
+
+    @override
+    def __eq__(self, other: "Progression", /) -> bool:
+        """Compare two Progression instances for equality."""
+        if not isinstance(other, Progression):
+            return NotImplemented
+        return self.order == other.order and self.name == other.name
+
+    def index(self, item: Any, /, start: int = 0, end: int = None) -> int:
+        """Return the index of an item in the progression.
+
+        Args:
+            item: Item to find.
+            start: Start index for search.
+            end: Optional end index for search.
+
+        Returns:
+            Index of the item.
+
+        Raises:
+            ValueError: If item not found.
+        """
+        return (
+            self.order.index(ID.get_id(item), start, end)
+            if end
+            else self.order.index(ID.get_id(item), start)
+        )
+
+    def remove(self, item: ID.RefSeq, /) -> None:
+        """Remove the next occurrence of an item from the progression.
+
+        Args:
+            item: Item or sequence to remove.
+
+        Raises:
+            ItemNotFoundError: If item not found.
+        """
+        if item in self:
+            item = validate_order(item)
+            l_ = list(self.order)
+
+            with contextlib.suppress(ValueError):
+                for i in item:
+                    l_.remove(i)
+                self.order = l_
+                return
+
+        raise ItemNotFoundError(f"{item}")
+
+    def popleft(self) -> str:
+        """Remove and return the leftmost item from the progression.
+
+        Returns:
+            The first item's ID.
+
+        Raises:
+            ItemNotFoundError: If progression is empty.
+        """
+        try:
+            return self.order.pop(0)
+        except IndexError as e:
+            raise ItemNotFoundError from e
+
+    def extend(self, item: "Progression", /) -> None:
+        """Extend the progression from the right with another progression.
+
+        Args:
+            item: Progression to extend with.
+
+        Raises:
+            TypeError: If item is not a Progression.
+        """
+        if not isinstance(item, Progression):
+            raise TypeError(expected_type=Progression, actual_type=type(item))
+        self.order.extend(item.order)
+
+    def count(self, item: ID.Ref, /) -> int:
+        """Return the number of occurrences of an item.
+
+        Args:
+            item: Item to count.
+
+        Returns:
+            Number of occurrences.
+        """
+        if not self.order or item not in self:
+            return 0
+        return self.order.count(ID.get_id(item))
+
+    @override
+    def __bool__(self) -> bool:
+        """Check if the container is not empty."""
+        return not self.is_empty()
+
+    def __add__(self, other: ID.RefSeq) -> "Progression":
+        """Returns a new progression with items added to the end.
+
+        Args:
+            other: Items to add.
+
+        Returns:
+            New Progression with added items.
+        """
+        other = validate_order(other)
+        new_order = list(
+            self.order
+        )  # Create a new list to avoid modifying original
+        new_order.extend(other)
+        return self.__class__(order=new_order)
+
+    def __radd__(self, other: ID.RefSeq) -> "Progression":
+        """Reverse add operation."""
+        return self + other
+
+    def __iadd__(self, other: ID.RefSeq) -> Self:
+        """Add an item to the end of the progression in-place."""
+        self.append(other)
+        return self
+
+    def __isub__(self, other: ID.RefSeq) -> Self:
+        """Remove an item from the progression in-place."""
+        self.remove(other)
+        return self
+
+    def __sub__(self, other: ID.RefSeq) -> "Progression":
+        """Remove an item or items from the progression.
+
+        Args:
+            other: Items to remove.
+
+        Returns:
+            New Progression with items removed.
+        """
+        other = validate_order(other)
+        new_order = list(self)
+        for i in other:
+            new_order.remove(i)
+        return self.__class__(order=new_order)
+
+    @override
+    def __repr__(self) -> str:
+        return f"Progression({self.order})"
+
+    @override
+    def __str__(self) -> str:
+        """Return a string representation of the progression."""
+        if len(a := str(self.order)) > 50:
+            a = a[:50] + "..."
+        return f"Progression(name={self.name}, size={len(self)}, items={a})"
+
+    def insert(self, index: int, item: ID.RefSeq, /) -> None:
+        """Insert an item at the specified index.
+
+        Args:
+            index: Position to insert at.
+            item: Item or sequence to insert.
+        """
+        item_ = validate_order(item)
+        for i in reversed(item_):
+            self.order.insert(index, ID.get_id(i))
+
+    def __hash__(self) -> int:
+        return hash(self.ln_id)
+
+
+def progression(
+    order: ID.RefSeq = None,
+    name: str = None,
+    /,
+) -> Progression:
+    """Create a new Progression instance.
+
+    Args:
+        order: Initial order of items.
+        name: Optional name for the progression.
+
+    Returns:
+        New Progression instance.
+    """
+    return Progression(order=order, name=name)

lionagi/core/generic/types.py

@@ -0,0 +1,23 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from lionagi.core.generic.component import Component
+from lionagi.core.generic.element import Element
+from lionagi.core.generic.log import Log
+from lionagi.core.generic.log_manager import LogManager
+from lionagi.core.generic.pile import Pile
+from lionagi.core.generic.progression import Progression
+from lionagi.core.generic.utils import to_list_type
+
+__all__ = [
+    "Component",
+    "Flow",
+    "Log",
+    "Pile",
+    "Progression",
+    "Node",
+    "to_list_type",
+    "Element",
+    "LogManager",
+]

lionagi/core/generic/utils.py

@@ -0,0 +1,50 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from collections import deque
+from collections.abc import Generator
+from typing import Any, TypeVar
+
+from lionagi.core.typing import ID, IDError
+
+from .element import Element
+
+T = TypeVar("T")
+
+
+def to_list_type(value: Any, /) -> list[Any]:
+    """Convert input to a list format"""
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value] if ID.is_id(value) else []
+    if isinstance(value, Element):
+        return [value]
+    if hasattr(value, "values") and callable(value.values):
+        return list(value.values())
+    if isinstance(value, list | tuple | set | deque | Generator):
+        return list(value)
+    return [value]
+
+
+def validate_order(value: Any, /) -> list[str]:
+    """Validate and standardize order representation"""
+
+    try:
+        result = []
+        for item in to_list_type(value):
+            if isinstance(item, str) and ID.is_id(item):
+                result.append(item)
+            elif isinstance(item, Element):
+                result.append(item.ln_id)
+            else:
+                id_ = ID.get_id(item)
+                if id_:
+                    result.append(id_)
+        return result
+    except Exception as e:
+        raise IDError("Must only contain valid Lion IDs.") from e
+
+
+# File: autoos/container/util.py

lionagi/core/models/__init__.py

@@ -0,0 +1,5 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from .types import *

lionagi/core/models/base.py

@@ -0,0 +1,85 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from ..typing.pydantic_ import BaseModel
+from ..typing.typing_ import UNDEFINED, Any, Self
+
+common_config = {
+    "populate_by_name": True,
+    "arbitrary_types_allowed": True,
+    "use_enum_values": True,
+}
+
+
+class BaseAutoModel(BaseModel):
+    """Base model class with enhanced serialization capabilities.
+
+    Extends Pydantic's BaseModel to provide:
+    - Clean dictionary conversion with UNDEFINED handling
+    - Nested model serialization
+    - Hash generation based on model content
+    - Validation rules
+
+    Example:
+        ```python
+        class User(BaseAutoModel):
+            name: str = Field(min_length=2)
+            age: int | None = None
+            settings: dict = Field(default_factory=dict)
+
+        user = User(name="John", age=30)
+        data = user.to_dict(clean=True)  # Excludes UNDEFINED values
+        ```
+
+    Attributes:
+        model_config: Default configuration for all instances
+            - validate_default: True to validate default values
+            - populate_by_name: True to allow field population by alias
+            - arbitrary_types_allowed: True to allow any type
+            - use_enum_values: True to use enum values in serialization
+    """
+
+    def to_dict(self, clean: bool = False) -> dict[str, Any]:
+        """Convert model to dictionary, with optional cleaning.
+
+        Args:
+            clean: If True, exclude UNDEFINED values from output.
+                  If False, include all fields using model_dump().
+
+        Returns:
+            Dictionary representation of model with nested models serialized
+        """
+        if not clean:
+            return self.model_dump()
+        return {
+            k: v
+            for k, v in self.model_dump(exclude_unset=True).items()
+            if v is not UNDEFINED
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Self:
+        """Create model instance from dictionary data.
+
+        Args:
+            data: Dictionary containing field values
+
+        Returns:
+            New model instance
+
+        Raises:
+            ValueError: If required fields are missing or validation fails
+        """
+        return cls.model_validate(data)
+
+    def __hash__(self) -> int:
+        """Generate hash based on model's clean dictionary representation.
+
+        Returns:
+            Hash value that uniquely identifies the model's content
+        """
+        return hash(str(self.to_dict(True)))
+
+
+__all__ = ["BaseAutoModel"]

lionagi/core/models/field_model.py

@@ -0,0 +1,122 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from ..typing.pydantic_ import ConfigDict, Field, FieldInfo, field_validator
+from ..typing.typing_ import UNDEFINED, Any, Callable
+from .schema_model import SchemaModel, common_config
+
+
+class FieldModel(SchemaModel):
+    """Model for defining and managing field definitions.
+
+    Provides a structured way to define fields with:
+    - Type annotations and validation
+    - Default values and factories
+    - Documentation and metadata
+    - Serialization options
+
+    Example:
+        ```python
+        field = FieldModel(
+            name="age",
+            annotation=int,
+            default=0,
+            description="User age in years",
+            validator=lambda v: v if v >= 0 else 0
+        )
+        ```
+
+    Attributes:
+        default: Default field value
+        default_factory: Function to generate default value
+        title: Field title for documentation
+        description: Field description
+        examples: Example values
+        validators: Validation functions
+        exclude: Exclude from serialization
+        deprecated: Mark as deprecated
+        frozen: Mark as immutable
+        alias: Alternative field name
+        alias_priority: Priority for alias resolution
+        name: Field name (required)
+        annotation: Type annotation
+        validator: Validation function
+        validator_kwargs: Validator parameters
+
+    Notes:
+        - All attributes except 'name' can be UNDEFINED
+        - validator_kwargs are passed to field_validator decorator
+        - Cannot have both default and default_factory
+    """
+
+    model_config = ConfigDict(
+        extra="allow", validate_default=False, **common_config
+    )
+
+    # Field configuration attributes
+    default: Any = UNDEFINED  # Default value
+    default_factory: Callable = UNDEFINED  # Factory function for default value
+    title: str = UNDEFINED  # Field title
+    description: str = UNDEFINED  # Field description
+    examples: list = UNDEFINED  # Example values
+    validators: list = UNDEFINED  # Validation functions
+    exclude: bool = UNDEFINED  # Exclude from serialization
+    deprecated: bool = UNDEFINED  # Mark as deprecated
+    frozen: bool = UNDEFINED  # Mark as immutable
+    alias: str = UNDEFINED  # Alternative field name
+    alias_priority: int = UNDEFINED  # Priority for alias resolution
+
+    # Core field attributes
+    name: str = Field(..., exclude=True)  # Field name (required)
+    annotation: type | Any = Field(UNDEFINED, exclude=True)  # Type annotation
+    validator: Callable | Any = Field(
+        UNDEFINED, exclude=True
+    )  # Validation function
+    validator_kwargs: dict | Any = Field(
+        default_factory=dict, exclude=True
+    )  # Validator parameters
+
+    @property
+    def field_info(self) -> FieldInfo:
+        """Generate Pydantic FieldInfo object from field configuration.
+
+        Returns:
+            FieldInfo object with all configured attributes
+
+        Notes:
+            - Uses clean dict to exclude UNDEFINED values
+            - Sets annotation to Any if not specified
+            - Preserves all metadata in field_info
+        """
+        annotation = (
+            self.annotation if self.annotation is not UNDEFINED else Any
+        )
+        field_obj: FieldInfo = Field(**self.to_dict(True))  # type: ignore
+        field_obj.annotation = annotation
+        return field_obj
+
+    @property
+    def field_validator(self) -> dict[str, Callable] | None:
+        """Generate field validator configuration.
+
+        Returns:
+            Dictionary mapping validator name to function,
+            or None if no validator defined
+
+        Notes:
+            - Validator name is f"{field_name}_validator"
+            - Uses validator_kwargs if provided
+            - Returns None if validator is UNDEFINED
+        """
+        if self.validator is UNDEFINED:
+            return None
+        kwargs = self.validator_kwargs or {}
+        return {
+            f"{self.name}_validator": field_validator(self.name, **kwargs)(
+                self.validator
+            )
+        }
+
+
+__all__ = ["FieldModel"]