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

lionagi/core/generic/component.py

@@ -0,0 +1,422 @@
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from pydantic import field_serializer
+from typing_extensions import override
+
+from lionagi.core._class_registry import get_class
+from lionagi.core.typing import (
+    UNDEFINED,
+    Any,
+    ClassVar,
+    Field,
+    FieldInfo,
+    FieldModel,
+    Note,
+    OperableModel,
+    PydanticUndefined,
+    TypeVar,
+)
+from lionagi.libs.utils import copy, time
+from lionagi.protocols.adapters.adapter import Adapter, AdapterRegistry
+from lionagi.protocols.registries._component_registry import (
+    ComponentAdapterRegistry,
+)
+
+from .element import Element
+
+FIELD_NAME = TypeVar("FIELD_NAME", bound=str)
+
+DEFAULT_SERIALIZATION_INCLUDE: set[str] = {
+    "ln_id",
+    "timestamp",
+    "metadata",
+    "content",
+    "embedding",
+}
+
+
+class Component(Element, OperableModel):
+    """Extended base class for components in the Lion framework.
+
+    The Component class extends Element with additional functionality for:
+    - Metadata management through Note objects
+    - Content storage of any type
+    - Vector embeddings storage
+    - Dynamic field management
+    - Adapter registry integration
+    - Enhanced serialization
+
+    Key Features:
+        - Flexible metadata storage
+        - Content of any type
+        - Vector embeddings support
+        - Dynamic field addition/updates
+        - Last update tracking
+        - Recursive serialization
+        - Adapter pattern support
+
+    Attributes:
+        metadata (Note): Additional metadata for the component. Stores arbitrary
+            nested data.
+        content (Any): The main content of the Component. Can be of any type.
+        embedding (list[float]): Vector embedding for the component. Used for
+            similarity operations.
+    """
+
+    metadata: Note = Field(
+        default_factory=Note,
+        description="Additional metadata for the component",
+    )
+
+    content: Any = Field(
+        default=None,
+        description="The main content of the Component",
+    )
+
+    embedding: list[float] = Field(default_factory=list)
+
+    _adapter_registry: ClassVar = ComponentAdapterRegistry
+
+    @field_serializer("metadata")
+    def _serialize_metadata(self, value: Note) -> dict:
+        """Serialize metadata Note recursively."""
+        return self._serialize_note_recursive(value)
+
+    def _serialize_note_recursive(self, note: Note) -> dict:
+        """Recursively serialize a Note object and its nested Notes."""
+        result = {}
+        for key, value in note.items():
+            if isinstance(value, Note):
+                result[key] = self._serialize_note_recursive(value)
+            else:
+                result[key] = value
+        return result
+
+    def add_field(
+        self,
+        field_name: FIELD_NAME,
+        /,
+        value: Any = UNDEFINED,
+        annotation: type = UNDEFINED,
+        field_obj: FieldInfo = UNDEFINED,
+        field_model: FieldModel = UNDEFINED,
+        **kwargs,
+    ) -> None:
+        """
+        Add a new field to the component's extra fields.
+
+        Args:
+            field_name: The name of the field to add.
+            value: The value of the field.
+            annotation: Type annotation for the field.
+            field_obj: A pre-configured FieldInfo object.
+            **kwargs: Additional keyword arguments for Field configuration.
+
+        Raises:
+            ValueError: If the field already exists.
+        """
+        if field_name in self.all_fields:
+            raise ValueError(f"Field '{field_name}' already exists")
+
+        self.update_field(
+            field_name,
+            value=value,
+            annotation=annotation,
+            field_obj=field_obj,
+            field_model=field_model,
+            **kwargs,
+        )
+
+    def update_field(
+        self,
+        field_name: FIELD_NAME,
+        /,
+        value: Any = UNDEFINED,
+        annotation: type = UNDEFINED,
+        field_obj: FieldInfo = UNDEFINED,
+        field_model: FieldModel = UNDEFINED,
+        **kwargs,
+    ) -> None:
+        """
+        Update an existing field or create a new one if it doesn't exist.
+
+        Args:
+            field_name: The name of the field to update or create.
+            value: The new value for the field.
+            annotation: Type annotation for the field.
+            field_obj: A pre-configured FieldInfo object.
+            **kwargs: Additional keyword arguments for Field configuration.
+
+        Raises:
+            ValueError: If both 'default' and 'default_factory' are
+                        provided in kwargs.
+        """
+        super().update_field(
+            field_name,
+            value=value,
+            annotation=annotation,
+            field_obj=field_obj,
+            field_model=field_model,
+            **kwargs,
+        )
+        self._add_last_update(field_name)
+
+    def _add_last_update(self, field_name: FIELD_NAME, /) -> None:
+        current_time = time()
+        self.metadata.set(["last_updated", field_name], current_time)
+
+    @override
+    def to_dict(self, **kwargs: Any) -> dict[str, Any]:
+        """
+        Convert the component to a dictionary representation.
+
+        Args:
+            **kwargs: Additional arguments to pass to model_dump.
+
+        Returns:
+            dict[str, Any]: A dictionary representation of the component.
+        """
+        dict_ = self.model_dump(**kwargs)
+        if isinstance(self.content, Note):
+            dict_["content"] = self._serialize_note_recursive(self.content)
+        extra_fields = dict_.pop("extra_fields", {})
+        dict_ = {**dict_, **extra_fields, "lion_class": self.class_name()}
+        for i in list(dict_.keys()):
+            if dict_[i] is UNDEFINED:
+                dict_.pop(i)
+        return dict_
+
+    def to_note(self, **kwargs: Any) -> Note:
+        """Convert the component to a Note object."""
+        return Note(**self.to_dict(**kwargs))
+
+    @override
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], /, **kwargs: Any) -> "Component":
+        """
+        Create a component instance from a dictionary.
+
+        Args:
+            data: The dictionary containing component data.
+            **kwargs: Additional arguments for Pydantic model validation.
+
+        Returns:
+            T: An instance of the Component class or its subclass.
+        """
+        input_data = copy(data)
+        if "lion_class" in input_data:
+            cls = get_class(input_data.pop("lion_class"))
+        if cls.from_dict.__func__ != Component.from_dict.__func__:
+            return cls.from_dict(input_data, **kwargs)
+
+        extra_fields = {}
+        for k, v in list(input_data.items()):
+            if k not in cls.model_fields:
+                extra_fields[k] = input_data.pop(k)
+        obj = cls.model_validate(input_data, **kwargs)
+        for k, v in extra_fields.items():
+            obj.update_field(k, value=v)
+
+        metadata = copy(data.get("metadata", {}))
+        last_updated = metadata.get("last_updated", None)
+        if last_updated is not None:
+            obj.metadata.set(["last_updated"], last_updated)
+        else:
+            obj.metadata.pop(["last_updated"], None)
+        return obj
+
+    @override
+    def __setattr__(self, field_name: str, value: Any) -> None:
+        """Set attribute value with metadata tracking.
+
+        This method prevents direct assignment to metadata and extra_fields,
+        and tracks the last update time of modified fields.
+
+        Args:
+            field_name: Name of the field to set.
+            value: Value to set.
+
+        Raises:
+            AttributeError: If attempting to directly assign to metadata or
+                extra_fields.
+        """
+        if field_name == "metadata":
+            raise AttributeError("Cannot directly assign to metadata.")
+        elif field_name == "extra_fields":
+            raise AttributeError("Cannot directly assign to extra_fields")
+        if field_name in self.extra_fields:
+            object.__setattr__(self, field_name, value)
+        else:
+            super().__setattr__(field_name, value)
+
+        self._add_last_update(field_name)
+
+    @override
+    def __getattr__(self, field_name: str) -> Any:
+        """Get attribute value with default handling.
+
+        This method provides access to extra fields with proper default value
+        handling.
+
+        Args:
+            field_name: Name of the field to get.
+
+        Returns:
+            The field value or UNDEFINED if no default exists.
+
+        Raises:
+            AttributeError: If the field doesn't exist.
+        """
+        if field_name in self.extra_fields:
+            default_ = self.extra_fields[field_name].default
+            if default_ is not PydanticUndefined:
+                return default_
+            return UNDEFINED
+
+        cls_name = self.__class__.__name__
+        raise AttributeError(
+            f"'{cls_name}' object has no attribute '{field_name}'",
+        )
+
+    @override
+    def __str__(self) -> str:
+        """Return a concise string representation of the component."""
+        content_preview = str(self.content)[:50]
+        if len(content_preview) == 50:
+            content_preview += "..."
+
+        output_str = (
+            f"{self.__class__.__name__}("
+            f"ln_id={self.ln_id[:8]}..., "
+            f"timestamp={str(self.created_datetime)[:-6]}, "
+            f"content='{content_preview}', "
+            f"metadata_keys={list(self.metadata.keys())}, "
+        )
+
+        for i, j in self.model_dump().items():
+            if i not in DEFAULT_SERIALIZATION_INCLUDE:
+                if isinstance(j, dict):
+                    output_str += f"{i}={list(j.keys())}, "
+                elif isinstance(j, str):
+                    j_preview = j[:50]
+                    if len(j_preview) == 50:
+                        j_preview = j_preview + "..."
+                    output_str += f"{i}={j_preview}, "
+                else:
+                    output_str += f"{i}={j}, "
+
+        output_str += f"extra_fields_keys={list(self.extra_fields.keys())})"
+
+        return output_str
+
+    @override
+    def __repr__(self) -> str:
+        """Return a detailed string representation of the component."""
+
+        def truncate_dict(
+            d: dict[str, Any], max_items: int = 5, max_str_len: int = 50
+        ) -> dict[str, Any]:
+            items = list(d.items())[:max_items]
+            truncated = {
+                k: (
+                    v[:max_str_len] + "..."
+                    if isinstance(v, str) and len(v) > max_str_len
+                    else v
+                )
+                for k, v in items
+            }
+            if len(d) > max_items:
+                truncated["..."] = f"({len(d) - max_items} more items)"
+            return truncated
+
+        content_repr = repr(self.content)
+        if len(content_repr) > 100:
+            content_repr = content_repr[:97] + "..."
+
+        dict_ = self.model_dump()
+        extra_fields = dict_.pop("extra_fields", {})
+
+        repr_str = (
+            f"{self.class_name()}("
+            f"ln_id={repr(self.ln_id)}, "
+            f"timestamp={str(self.created_datetime)[:-6]}, "
+            f"content={content_repr}, "
+            f"metadata={truncate_dict(self.metadata.content)}, "
+        )
+
+        for i, j in dict_.items():
+            if i not in DEFAULT_SERIALIZATION_INCLUDE:
+                if isinstance(j, dict):
+                    repr_str += f"{i}={truncate_dict(j)}, "
+                elif isinstance(j, str):
+                    j_repr = j
+                    if len(j) > 100:
+                        j_repr = j[:97] + "..."
+                    repr_str += f"{i}={j_repr}, "
+                else:
+                    repr_str += f"{i}={j}, "
+
+        repr_str += f"extra_fields={truncate_dict(extra_fields)})"
+        return repr_str
+
+    def adapt_to(self, obj_key: str, /, *args, **kwargs: Any) -> Any:
+        """Convert this component to another format using registered adapters.
+
+        Args:
+            obj_key: Key identifying the target format.
+            *args: Additional positional arguments for the adapter.
+            **kwargs: Additional keyword arguments for the adapter.
+
+        Returns:
+            Any: The component converted to the target format.
+        """
+        return self._get_adapter_registry().adapt_to(
+            self, obj_key, *args, **kwargs
+        )
+
+    @classmethod
+    def list_adapters(cls):
+        """List all registered adapters for this component type.
+
+        Returns:
+            list: Available adapters for this component type.
+        """
+        return cls._get_adapter_registry().list_adapters()
+
+    @classmethod
+    def register_adapter(cls, adapter: type[Adapter]):
+        """Register a new adapter for this component type.
+
+        Args:
+            adapter: The adapter class to register.
+        """
+        cls._get_adapter_registry().register(adapter)
+
+    @classmethod
+    def _get_adapter_registry(cls) -> AdapterRegistry:
+        """Get the converter registry for the class."""
+        if isinstance(cls._adapter_registry, type):
+            cls._adapter_registry = cls._adapter_registry()
+        return cls._adapter_registry
+
+    @classmethod
+    def adapt_from(cls, obj: Any, obj_key: str, /, **kwargs: Any):
+        """Create a component instance from another format using registered adapters.
+
+        Args:
+            obj: The object to convert from.
+            obj_key: Key identifying the source format.
+            **kwargs: Additional arguments for the adapter.
+
+        Returns:
+            Component: A new component instance.
+        """
+        dict_ = cls._get_adapter_registry().adapt_from(
+            cls, obj, obj_key, **kwargs
+        )
+        return cls.from_dict(dict_)
+
+
+__all__ = ["Component"]

lionagi/core/generic/edge.py

@@ -1,121 +1,163 @@
-from typing import Any
-
-from pydantic import Field, field_validator
-
-from lionagi.core.collections.abc import (
-    Component,
+# Copyright (c) 2023 - 2024, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+from lionagi.core.typing import (
+    ID,
+    Any,
+    BaseModel,
     Condition,
-    LionIDable,
-    get_lion_id,
+    ConfigDict,
+    Field,
+    Note,
+    Relational,
+    field_serializer,
 )
-from lionagi.core.generic.edge_condition import EdgeCondition
 
+from .element import Element
 
-class Edge(Component):
-    """Represents a directed edge between two nodes in a graph."""
 
-    head: str = Field(
-        ...,
-        title="Head",
-        description="The identifier of the head node of the edge.",
-    )
+class EdgeCondition(BaseModel, Condition):
+    """Represents a condition associated with an edge in the Lion framework.
 
-    tail: str = Field(
-        ...,
-        title="Out",
-        description="The identifier of the tail node of the edge.",
-    )
+    This class combines Condition characteristics with Pydantic's
+    BaseModel for robust data validation and serialization.
 
-    condition: Condition | EdgeCondition | None = Field(
-        default=None,
-        description="Optional condition that must be met for the edge "
-        "to be considered active.",
-    )
+    Attributes:
+        source (Any): The source for condition evaluation.
+    """
 
-    label: str | None = Field(
+    source: Any = Field(
         default=None,
-        description="An optional label for the edge.",
+        title="Source",
+        description="The source for condition evaluation",
     )
 
-    bundle: bool = Field(
-        default=False,
-        description="A flag indicating if the edge is bundled.",
+    model_config = ConfigDict(
+        extra="allow",
+        arbitrary_types_allowed=True,
     )
 
-    async def check_condition(self, obj: Any) -> bool:
-        """Check if the edge condition is met for the given object."""
-        if not self.condition:
-            raise ValueError("The condition for the edge is not set.")
-        check = await self.condition.applies(obj)
-        return check
 
-    @field_validator("head", "tail", mode="before")
-    def _validate_head_tail(cls, value):
-        """Validate the head and tail fields."""
-        return get_lion_id(value)
+class Edge(Element):
+    """
+    Represents an edge in a graph structure.
+
+    An edge connects a head node to a tail node and can store additional
+    properties such as conditions and labels. It is used to model relationship
+    between nodes in graph-based data structures.
+
+    Attributes:
+        properties (Note): Stores additional properties of the edge. This can
+            include conditions that must be met for the edge to be traversed
+            and labels that describe the edge.
+        head (str): The ID of the head node in the graph.
+        tail (str): The ID of the tail node in the graph.
+    """
+
+    properties: Note = Field(default_factory=Note)
+    head: ID[Relational].ID
+    tail: ID[Relational].ID
+
+    def __init__(
+        self,
+        head: ID[Relational].Ref,
+        tail: ID[Relational].Ref,
+        condition: EdgeCondition | None = None,
+        label: list[str] | None = None,
+        **kwargs,
+    ):
+        """
+        Initialize an Edge.
+
+        This constructor sets up an edge by linking a head node to a tail node,
+        with optional conditions and labels. Additional properties can also be
+        provided via keyword arguments.
+
+        Args:
+            head (Relational | str): The head node or its ID. This is the
+                starting point of the edge.
+            tail (Relational | str): The tail node or its ID. This is the end
+                point of the edge.
+            condition (EdgeCondition | None): An optional condition that must
+                be satisfied for the edge to be traversed.
+            label (list[str] | None): An optional list of labels that describe
+                the edge.
+            kwargs: Optional additional properties for the edge.
+        """
+        head = ID.get_id(head)
+        tail = ID.get_id(tail)
+
+        super().__init__(head=head, tail=tail)
 
-    def string_condition(self):
+        # Initialize properties
+        if condition:
+            self.properties.content["condition"] = condition
+        if label:
+            self.properties.content["label"] = label
+        for key, value in kwargs.items():
+            self.properties.content[key] = value
+
+    @field_serializer("properties")
+    def _serialize_properties(self, value: Note) -> dict[str, Any]:
         """
-        Retrieves the condition class source code as a string.
+        Serialize the properties of the edge.
+
+        This method converts the `properties` field into a format suitable for
+        storage or transmission, typically as part of serialization to JSON or
+        other formats.
 
-        This method is useful for serialization and debugging, allowing
-        the condition logic to be inspected or stored in a human-readable
-        format. It employs advanced introspection techniques to locate and
-        extract the exact class definition, handling edge cases like
-        dynamically defined classes or classes defined interactively.
+        Args:
+            value: The properties Note to serialize.
 
         Returns:
-            str | None: The condition class source code if available.
-                If the condition is None or the source code cannot be
-                located, this method returns None.
-
-        Raises:
-            TypeError: If the condition class source code cannot be found
-                due to the class being defined in a non-standard manner or
-                in the interactive interpreter (__main__ context).
+            The serialized properties.
         """
-        if self.condition is None:
-            return
-
-        import inspect
-        import sys
-
-        def new_getfile(object, _old_getfile=inspect.getfile):
-            if not inspect.isclass(object):
-                return _old_getfile(object)
-
-            # Lookup by parent module (as in current inspect)
-            if hasattr(object, "__module__"):
-                object_ = sys.modules.get(object.__module__)
-                if hasattr(object_, "__file__"):
-                    return object_.__file__
-
-            # If parent module is __main__, lookup by methods (NEW)
-            for name, member in inspect.getmembers(object):
-                if (
-                    inspect.isfunction(member)
-                    and object.__qualname__ + "." + member.__name__
-                    == member.__qualname__
-                ):
-                    return inspect.getfile(member)
-            else:
-                raise TypeError(f"Source for {object!r} not found")
-
-        inspect.getfile = new_getfile
-
-        import inspect
-
-        from IPython.core.magics.code import extract_symbols
-
-        obj = self.condition.__class__
-        cell_code = "".join(inspect.linecache.getlines(new_getfile(obj)))
-        class_code = extract_symbols(cell_code, obj.__name__)[0][0]
-        return class_code
-
-    def __len__(self):
-        """Return the length of the edge (always 1)."""
-        return 1
-
-    def __contains__(self, item: LionIDable) -> bool:
-        """Check if the given item is the head or tail of the edge."""
-        return get_lion_id(item) in (self.head, self.tail)
+        return value.content
+
+    async def check_condition(self, *args, **kwargs) -> bool:
+        """
+        Check if the edge's condition is satisfied.
+
+        This method checks whether the edge can be traversed by evaluating its
+        condition. If no condition is specified, the edge is considered
+        traversable by default.
+
+        Args:
+            *args: Variable length argument list.
+            **kwargs: Arbitrary keyword arguments.
+
+        Returns:
+            bool: True if the condition is satisfied or if no condition exists,
+                  False otherwise.
+        """
+        condition: EdgeCondition | None = self.properties.get(
+            "condition", None
+        )
+        if condition:
+            return await condition.apply(*args, **kwargs)
+        return True  # If no condition exists, the edge is always traversable
+
+    def update_property(self, key: str, value: Any) -> None:
+        """
+        Update a property value directly.
+
+        Args:
+            key: The property key to update.
+            value: The new value for the property.
+        """
+        self.properties.content[key] = value
+
+    def update_condition_source(self, source: dict) -> None:
+        """
+        Update the condition source.
+
+        Args:
+            source: The new source dictionary for the condition.
+        """
+        condition = self.properties.get("condition")
+        if condition:
+            condition.source = source
+
+
+__all__ = ["Edge"]