lionagi 0.1.1__py3-none-any.whl → 0.2.0__py3-none-any.whl

lionagi/core/collections/abc/concepts.py

@@ -0,0 +1,297 @@
+"""
+Copyright 2024 HaiyangLi
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+"""This module defines abstract base classes for LionAGI."""
+
+from abc import ABC, abstractmethod
+from collections.abc import Generator
+from typing import Any, Iterator, TypeVar
+
+from pydantic import Field, BaseModel, field_validator
+
+from .component import LionIDable, get_lion_id
+from .exceptions import LionTypeError
+
+T = TypeVar("T")
+
+
+class Record(ABC):
+    """
+    Abstract base class for managing a collection of unique LionAGI items.
+
+    Accepts LionIDable for retrieval and requires Component instances for
+    addition.
+
+    Methods:
+        keys: Return an iterator over the ln_id of items in the record.
+        values: Return an iterator over items in the record.
+        get: Retrieve an item by identifier.
+        __getitem__: Return an item using a LionIDable identifier.
+        __setitem__: Add or update an item in the record.
+        __contains__: Check if an item is in the record.
+        __len__: Return the number of items in the record.
+        __iter__: Iterate over items in the record.
+    """
+
+    @abstractmethod
+    def keys(self) -> Generator[str, None, None]:
+        """Return an iterator over the ln_id of items in the record."""
+
+    @abstractmethod
+    def values(self) -> Generator[T, None, None]:
+        """Return an iterator over items in the record."""
+
+    @abstractmethod
+    def get(self, item: LionIDable, /, default: Any = None) -> T:
+        """
+        Retrieve an item by identifier.
+
+        Accepts a LionIDable object. Returns the default if the item is not
+        found.
+
+        Args:
+            item (LionIDable): The identifier of the item to retrieve.
+            default (Any): The default value to return if the item is not found.
+
+        Returns:
+            T: The retrieved item or the default value.
+        """
+
+    @abstractmethod
+    def __getitem__(self, item: LionIDable) -> T:
+        """
+        Return an item using a LionIDable identifier.
+
+        Raises:
+            KeyError: If the item ID is not found.
+
+        Args:
+            item (LionIDable): The identifier of the item to retrieve.
+
+        Returns:
+            T: The retrieved item.
+        """
+
+    @abstractmethod
+    def __setitem__(self, item: LionIDable, value: T) -> None:
+        """
+        Add or update an item in the record.
+
+        The value must be a Component instance.
+
+        Args:
+            item (LionIDable): The identifier of the item to add or update.
+            value (T): The Component instance to add or update.
+        """
+
+    @abstractmethod
+    def __contains__(self, item: LionIDable) -> bool:
+        """
+        Check if an item is in the record, using either an ID or an object.
+
+        Args:
+            item (LionIDable): The identifier or object to check.
+
+        Returns:
+            bool: True if the item is in the record, False otherwise.
+        """
+
+    @abstractmethod
+    def __len__(self) -> int:
+        """
+        Return the number of items in the record.
+
+        Returns:
+            int: The number of items in the record.
+        """
+
+    @abstractmethod
+    def __iter__(self) -> Iterator[T]:
+        """
+        Iterate over items in the record.
+
+        Yields:
+            T: The items in the record.
+        """
+
+
+class Ordering(ABC):
+    """Represents sequencing of certain order."""
+
+    @abstractmethod
+    def __len__(self) -> int:
+        """
+        Return the number of item ids in the ordering.
+
+        Or the number of orderings in another ordering.
+        """
+
+    @abstractmethod
+    def __contains__(self, item: Any) -> bool:
+        """Check if an item id is in the ordering."""
+
+
+class Condition(ABC):
+    """Represents a condition in a given context."""
+
+    @abstractmethod
+    async def applies(self, value: Any, /, *args: Any, **kwargs: Any) -> Any:
+        """Asynchronously determine if the condition applies to the given value.
+
+        Args:
+            value (Any): The value to check against the condition.
+            *args: Additional positional arguments.
+            **kwargs: Additional keyword arguments.
+
+        Returns:
+            Any: The result of applying the condition to the value.
+        """
+
+
+class Actionable(ABC):
+    """Represents an action that can be invoked with arguments."""
+
+    @abstractmethod
+    async def invoke(self, /, *args: Any, **kwargs: Any) -> Any:
+        """
+        Invoke the action asynchronously with the given arguments.
+
+        Args:
+            *args: Positional arguments for invoking the action.
+            **kwargs: Keyword arguments for invoking the action.
+
+        Returns:
+            Any: The result of invoking the action.
+        """
+
+
+class Progressable(ABC):
+    """Represents a process that can progress forward asynchronously."""
+
+    @abstractmethod
+    async def forward(self, /, *args: Any, **kwargs: Any) -> None:
+        """Move the process forward asynchronously.
+
+        Args:
+            *args: Positional arguments for moving the process forward.
+            **kwargs: Keyword arguments for moving the process forward.
+        """
+
+
+class Relatable(ABC):
+    """Defines a relationship that can be established with arguments."""
+
+    @abstractmethod
+    def relate(self, /, *args: Any, **kwargs: Any) -> None:
+        """Establish a relationship based on the provided arguments.
+
+        Args:
+            *args: Positional arguments for establishing the relationship.
+            **kwargs: Keyword arguments for establishing the relationship.
+        """
+
+
+class Sendable(BaseModel, ABC):
+    """Represents an object that can be sent with a sender and recipient."""
+
+    sender: str = Field(
+        "N/A",
+        title="Sender",
+        description=("The id of the sender node, or 'system', 'user', or 'assistant'."),
+    )
+
+    recipient: str = Field(
+        "N/A",
+        title="Recipient",
+        description=(
+            "The id of the recipient node, or 'system', 'user', or 'assistant'."
+        ),
+    )
+
+    @field_validator("sender", "recipient", mode="before")
+    def _validate_sender_recipient(cls, value):
+        """Validate the sender and recipient fields.
+
+        Args:
+            value (Any): The value to validate.
+
+        Returns:
+            str: The validated value.
+
+        Raises:
+            LionTypeError: If the value is invalid.
+        """
+        if value is None:
+            return "N/A"
+
+        if value in ["system", "user", "N/A", "assistant"]:
+            return value
+
+        a = get_lion_id(value)
+        if not isinstance(a, str) or len(a) != 32:
+            raise LionTypeError(
+                "Invalid sender or recipient value. "
+                "Expected a valid node id or one of "
+                "'system' or 'user'."
+            )
+        return a
+
+
+class Executable(ABC):
+    """Represents an object that can be executed with arguments."""
+
+    @abstractmethod
+    async def execute(self, /, *args: Any, **kwargs: Any) -> Any:
+        """Execute the object with the given arguments asynchronously.
+
+        Args:
+            *args: Positional arguments for executing the object.
+            **kwargs: Keyword arguments for executing the object.
+
+        Returns:
+            Any: The result of executing the object.
+        """
+
+
+class Directive(ABC):
+    """Represents a directive that can be directed with arguments."""
+
+    # @abstractmethod
+    # async def direct(self, *args, **kwargs):
+    #     """Direct the directive with the given arguments asynchronously.
+
+    #     Args:
+    #         *args: Positional arguments for directing the directive.
+    #         **kwargs: Keyword arguments for directing the directive.
+    #     """
+
+    @property
+    def class_name(self) -> str:
+        """Get the class name of the directive.
+
+        Returns:
+            str: The class name of the directive.
+        """
+        return self._class_name()
+
+    @classmethod
+    def _class_name(cls) -> str:
+        """Get the class name of the directive.
+
+        Returns:
+            str: The class name of the directive.
+        """
+        return cls.__name__

lionagi/core/collections/abc/exceptions.py

@@ -0,0 +1,150 @@
+"""
+Copyright 2024 HaiyangLi
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+# import logging
+
+# # Configure logging
+# logging.basicConfig(
+#     level=logging.ERROR,
+#     format="%(asctime)s:%(levelname)s:%(message)s",
+# )
+
+
+class LionAGIError(Exception):
+    """Base class for all exceptions in the LionAGI system."""
+
+    def __init__(self, message=None):
+        if message is None:
+            message = "An unspecified error occurred in the LionAGI system."
+        super().__init__(message)
+
+
+class LionValueError(LionAGIError):
+    """Exception raised for errors in the input value."""
+
+    def __init__(self, message=None):
+        if message is None:
+            message = "An error occurred in the input value."
+        super().__init__(message)
+
+
+class LionTypeError(LionAGIError):
+    """Exception raised for type mismatch or type checking errors."""
+
+    def __init__(self, message=None):
+        if message is None:
+            message = "Item must be identifiable, `ln_id` or `Component`"
+        super().__init__(message)
+
+
+class LionItemError(LionAGIError):
+    """Base class for exceptions related to LionAGI items."""
+
+    def __init__(self, item, message=None):
+        if message is None:
+            message = "An error occurred with the specified item."
+        super().__init__(f"{message} Item: '{item}'.")
+
+
+class ItemNotFoundError(LionItemError):
+    """Exception raised when a specified item is not found."""
+
+    def __init__(self, item):
+        super().__init__(item, "Item not found.")
+
+
+class ItemInvalidError(LionItemError):
+    """Exception raised when an invalid item is used in an operation."""
+
+    def __init__(self, item):
+        super().__init__(item, "The item is invalid for this operation.")
+
+
+class FieldError(LionAGIError):
+    """Exception raised for errors in field validation."""
+
+    def __init__(self, field, message=None):
+        if message is None:
+            message = "An error occurred with the specified field."
+        super().__init__(f"{message}: {field}.")
+
+
+class LionOperationError(LionAGIError):
+    """Base class for exceptions related to operational failures."""
+
+    def __init__(self, operation, message=None):
+        if message is None:
+            message = "An operation failed."
+        super().__init__(f"{message} Operation: '{operation}'.")
+
+
+class ConcurrencyError(LionOperationError):
+    """Exception raised for errors due to concurrency issues."""
+
+    def __init__(self, operation=None):
+        if operation is None:
+            operation = "a concurrent operation"
+        super().__init__(operation, "A concurrency error occurred during")
+
+
+class RelationError(LionAGIError):
+    """Exception raised for errors in relation operations."""
+
+    def __init__(self, message=None):
+        if message is None:
+            message = "Nodes are not related."
+        super().__init__(message)
+
+
+class ActionError(LionAGIError):
+    """Exception raised for errors in action operations."""
+
+    def __init__(self, message=None):
+        if message is None:
+            message = "An error occurred with the specified action."
+        super().__init__(message)
+
+
+class ModelLimitExceededError(LionOperationError):
+    """Exception raised when a resource limit is exceeded."""
+
+    def __init__(self, message=None):
+        if message is None:
+            message = "The model limit has been exceeded."
+        super().__init__("Model", message)
+
+
+class TimeoutError(LionOperationError):
+    """Exception raised when an operation times out."""
+
+    def __init__(self, operation, timeout):
+        super().__init__(operation, f"Operation timed out after {timeout} seconds.")
+
+
+class ServiceError(LionAGIError):
+    """Exception raised for errors in endpoint configuration."""
+
+    def __init__(self, message, errors=None):
+        super().__init__(message, errors)
+
+    @classmethod
+    def unavailable(cls, endpoint, service, err_msg=None):
+        msg = f"{endpoint} is currently unavailable"
+        if err_msg:
+            msg += f": {err_msg}"
+        else:
+            msg += f" for {service.__class__.__name__}"
+        return cls(msg)

lionagi/core/collections/abc/util.py

@@ -0,0 +1,45 @@
+base_lion_fields = [
+    "ln_id",
+    "timestamp",
+    "metadata",
+    "extra_fields",
+    "content",
+    "created",
+    "embedding",
+]
+
+lc_meta_fields = ["lc", "type", "id", "langchain", "lc_type", "lc_id"]
+
+llama_meta_fields = [
+    "id_",
+    "embedding",
+    "excluded_embed_metadata_keys",
+    "excluded_llm_metadata_keys",
+    "relationships",
+    "start_char_idx",
+    "end_char_idx",
+    "class_name",
+    "text_template",
+    "metadata_template",
+    "metadata_seperator",
+]
+
+SYSTEM_FIELDS = [
+    "ln_id",
+    "timestamp",
+    "metadata",
+    "meta",
+    "extra_fields",
+    "content",
+    "created",
+    "form",
+    "report",
+    "work",
+    "assignment",
+    "assignments",
+    "input_fields",
+    "requested_fields",
+    "instruction",
+    "system",
+    "strict",
+]

lionagi/core/collections/exchange.py

@@ -0,0 +1,161 @@
+"""
+Copyright 2024 HaiyangLi
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+"""
+
+from typing import TypeVar, Generic
+from .abc import Element, Field, Sendable
+from .pile import Pile, pile
+from .progression import Progression, progression
+
+T = TypeVar("T")
+
+
+class Exchange(Element, Generic[T]):
+    """
+    Item exchange system designed to handle incoming and outgoing flows of items.
+
+    Attributes:
+        pile (Pile[T]): The pile of items in the exchange.
+        pending_ins (dict[str, Progression]): The pending incoming items to the exchange.
+        pending_outs (Progression): The progression of pending outgoing items.
+    """
+
+    pile: Pile[T] = Field(
+        default_factory=lambda: pile(),
+        description="The pile of items in the exchange.",
+        title="pending items",
+    )
+
+    pending_ins: dict[str, Progression] = Field(
+        default_factory=dict,
+        description="The pending incoming items to the exchange.",
+        title="pending incoming items",
+        examples=["{'sender_id': Progression}"],
+    )
+
+    pending_outs: Progression = Field(
+        default_factory=lambda: progression(),
+        description="The pending outgoing items to the exchange.",
+        title="pending outgoing items",
+    )
+
+    def __contains__(self, item):
+        """
+        Check if an item is in the pile.
+
+        Args:
+            item: The item to check.
+
+        Returns:
+            bool: True if the item is in the pile, False otherwise.
+        """
+        return item in self.pile
+
+    @property
+    def unassigned(self) -> Pile[T]:
+        """
+        if the item is not in the pending_ins or pending_outs, it is unassigned.
+        """
+        return pile(
+            [
+                item
+                for item in self.pile
+                if (
+                    all(item not in j for j in self.pending_ins.values())
+                    and item not in self.pending_outs
+                )
+            ]
+        )
+
+    @property
+    def senders(self) -> list[str]:
+        """
+        Get the list of senders for the pending incoming items.
+
+        Returns:
+            list[str]: The list of sender IDs.
+        """
+        return list(self.pending_ins.keys())
+
+    def exclude(self, item) -> bool:
+        """
+        Exclude an item from the exchange.
+
+        Args:
+            item: The item to exclude.
+
+        Returns:
+            bool: True if the item was successfully excluded, False otherwise.
+        """
+        return (
+            self.pile.exclude(item)
+            and all([v.exclude(item) for v in self.pending_ins.values()])
+            and self.pending_outs.exclude(item)
+        )
+
+    def include(self, item, direction=None) -> bool:
+        """
+        Include an item in the exchange in a specified direction.
+
+        Args:
+            item: The item to include.
+            direction (str): The direction to include the item ('in' or 'out').
+
+        Returns:
+            bool: True if the item was successfully included, False otherwise.
+        """
+        if self.pile.include(item):
+            item = self.pile[item]
+            item = [item] if not isinstance(item, list) else item
+            for i in item:
+                if not self._include(i, direction=direction):
+                    return False
+            return True
+
+    def _include(self, item: Sendable, direction) -> bool:
+        """
+        Helper method to include an item in the exchange in a specified direction.
+
+        Args:
+            item (Sendable): The item to include.
+            direction (str): The direction to include the item ('in' or 'out').
+
+        Returns:
+            bool: True if the item was successfully included, False otherwise.
+        """
+        if direction == "in":
+            if item.sender not in self.pending_ins:
+                self.pending_ins[item.sender] = progression()
+            return self.pending_ins[item.sender].include(item)
+
+        if direction == "out":
+            return self.pending_outs.include(item)
+
+        return True
+
+    def to_dict(self) -> dict:
+        """
+        Convert the exchange to a dictionary.
+
+        Returns:
+            dict: The dictionary representation of the exchange.
+        """
+        return self.model_dump(by_alias=True)
+
+    def __bool__(self):
+        return True
+
+    def __len__(self):
+        return len(self.pile)