lionagi 0.15.14__py3-none-any.whl → 0.16.1__py3-none-any.whl

lionagi/operations/ReAct/utils.py

@@ -18,8 +18,7 @@ class PlannedAction(HashableModel):
     action_type: str | None = Field(
         default=None,
         description=(
-            "The name or type of tool/action to invoke. "
-            "(e.g., 'search_exa', 'reader_tool')"
+            "The name or type of tool/action to invoke. (e.g., 'search_exa', 'reader_tool')"
         ),
     )
     description: str | None = Field(

lionagi/operations/flow.py

@@ -12,7 +12,8 @@ using Events for synchronization and CapacityLimiter for concurrency control.
 import os
 from typing import Any
 
-from lionagi.ln import AlcallParams, CapacityLimiter, ConcurrencyEvent
+from lionagi.ln._async_call import AlcallParams
+from lionagi.ln.concurrency import CapacityLimiter, ConcurrencyEvent
 from lionagi.operations.node import Operation
 from lionagi.protocols.types import EventStatus, Graph
 from lionagi.session.branch import Branch

lionagi/operations/operate/operate.py

@@ -23,6 +23,29 @@ if TYPE_CHECKING:
     from lionagi.session.branch import Branch
 
 
+def _handle_response_format_kwargs(
+    operative_model: type[BaseModel] = None,
+    request_model: type[BaseModel] = None,
+    response_format: type[BaseModel] = None,
+):
+    if operative_model:
+        logging.warning(
+            "`operative_model` is deprecated. Use `response_format` instead."
+        )
+    if (
+        (operative_model and response_format)
+        or (operative_model and request_model)
+        or (response_format and request_model)
+    ):
+        raise ValueError(
+            "Cannot specify both `operative_model` and `response_format` (or `request_model`) "
+            "as they are aliases of each other."
+        )
+
+    # Use the final chosen format
+    return response_format or operative_model or request_model
+
+
 async def operate(
     branch: "Branch",
     *,
@@ -66,22 +89,9 @@ async def operate(
     include_token_usage_to_model: bool = False,
     **kwargs,
 ) -> list | BaseModel | None | dict | str:
-    if operative_model:
-        logging.warning(
-            "`operative_model` is deprecated. Use `response_format` instead."
-        )
-    if (
-        (operative_model and response_format)
-        or (operative_model and request_model)
-        or (response_format and request_model)
-    ):
-        raise ValueError(
-            "Cannot specify both `operative_model` and `response_format` (or `request_model`) "
-            "as they are aliases of each other."
-        )
-
-    # Use the final chosen format
-    response_format = response_format or operative_model or request_model
+    response_format = _handle_response_format_kwargs(
+        operative_model, request_model, response_format
+    )
 
     # Decide which chat model to use
     chat_model = chat_model or imodel or branch.chat_model

lionagi/protocols/action/function_calling.py

@@ -130,10 +130,7 @@ class FunctionCalling(Event):
         Returns:
             A string containing the class name and key attributes.
         """
-        return (
-            f"FunctionCalling(function={self.func_tool.function}, "
-            f"arguments={self.arguments})"
-        )
+        return f"FunctionCalling(function={self.func_tool.function}, arguments={self.arguments})"
 
     def to_dict(self) -> dict[str, Any]:
         """Convert instance to dictionary.

lionagi/protocols/contracts.py

@@ -0,0 +1,46 @@
+# Copyright (c) 2023 - 2025, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""V1 Observable Protocol for gradual evolution.
+
+This module provides the runtime-checkable ObservableProto for V1 components
+while maintaining compatibility with V0's nominal Observable ABC.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+__all__ = (
+    "ObservableProto",
+    "Observable",
+    "LegacyObservable",
+)
+
+
+@runtime_checkable
+class ObservableProto(Protocol):
+    """Structural Observable Protocol for V1 components.
+
+    This protocol defines the minimal contract for observable objects:
+    they must have an 'id' property. The return type is permissive (Any)
+    to maintain compatibility with V0's IDType wrapper while enabling
+    V1 evolution.
+
+    All V0 Element subclasses automatically satisfy this protocol without
+    any code changes, enabling zero-risk gradual migration.
+    """
+
+    @property
+    def id(self) -> object:
+        """Unique identifier. Accepts IDType, UUID, or string."""
+        ...
+
+
+# Convenience alias for V1 consumers (keeps import names short)
+Observable = ObservableProto
+
+# Keep legacy nominal ABC for places that need issubclass checks (e.g., Pile)
+# Do NOT remove – Pile and others rely on issubclass(..., Observable) nominal checks.
+from ._concepts import Observable as LegacyObservable

lionagi/protocols/generic/element.py

@@ -313,7 +313,6 @@ class Element(BaseModel, Observable):
         if mode == "db":
             dict_ = orjson.loads(self.to_json(decode=False))
             dict_["node_metadata"] = dict_.pop("metadata", {})
-            dict_["created_at"] = self.created_datetime.isoformat(sep=" ")
             return dict_
 
     def as_jsonable(self) -> dict:
@@ -321,19 +320,13 @@ class Element(BaseModel, Observable):
         return self.to_dict(mode="json")
 
     @classmethod
-    def from_dict(cls, data: dict, /, mode: str = "python") -> Element:
+    def from_dict(cls, data: dict) -> Element:
         """Deserializes a dictionary into an Element or subclass of Element.
 
         If `lion_class` in `metadata` refers to a subclass, this method
         is polymorphic, it will attempt to create an instance of that subclass.
-
-        Args:
-            data (dict): A dictionary of field data.
-            mode (str): Format mode - "python" for normal dicts, "db" for database format.
         """
         # Preprocess database format if needed
-        if mode == "db":
-            data = cls._preprocess_db_data(data.copy())
         metadata = {}
 
         if "node_metadata" in data:
@@ -367,56 +360,6 @@ class Element(BaseModel, Observable):
         data["metadata"] = metadata
         return cls.model_validate(data)
 
-    @classmethod
-    def _preprocess_db_data(cls, data: dict) -> dict:
-        """Preprocess raw database data for Element compatibility."""
-        import datetime as dt
-        import json
-
-        # Handle created_at field - convert datetime string to timestamp
-        if "created_at" in data and isinstance(data["created_at"], str):
-            try:
-                # Parse datetime string and convert to timestamp
-                dt_obj = dt.datetime.fromisoformat(
-                    data["created_at"].replace(" ", "T")
-                )
-                # Treat as UTC if naive
-                if dt_obj.tzinfo is None:
-                    dt_obj = dt_obj.replace(tzinfo=dt.timezone.utc)
-                data["created_at"] = dt_obj.timestamp()
-            except (ValueError, TypeError):
-                # Keep as string if parsing fails
-                pass
-
-        # Handle JSON string fields - parse to dict/list
-        json_fields = ["content", "node_metadata", "embedding"]
-        for field in json_fields:
-            if field in data and isinstance(data[field], str):
-                if data[field] in ("null", ""):
-                    data[field] = None if field == "embedding" else {}
-                else:
-                    try:
-                        data[field] = json.loads(data[field])
-                    except (json.JSONDecodeError, TypeError):
-                        # Keep as empty dict for metadata fields, None for embedding
-                        data[field] = {} if field != "embedding" else None
-
-        # Handle node_metadata -> metadata mapping
-        if "node_metadata" in data:
-            if (
-                data["node_metadata"] == "null"
-                or data["node_metadata"] is None
-            ):
-                data["metadata"] = {}
-            else:
-                data["metadata"] = (
-                    data["node_metadata"] if data["node_metadata"] else {}
-                )
-            # Remove node_metadata to avoid Pydantic validation error
-            data.pop("node_metadata", None)
-
-        return data
-
     def to_json(self, decode: bool = True) -> str:
         """Converts this Element to a JSON string."""
         dict_ = self._to_dict()

lionagi/protocols/generic/event.py

@@ -5,13 +5,13 @@
 from __future__ import annotations
 
 import contextlib
-from enum import Enum
+from enum import Enum as _Enum
 from typing import Any
 
 from pydantic import Field, field_serializer
 
 from lionagi import ln
-from lionagi.utils import to_dict
+from lionagi.utils import Unset, to_dict
 
 from .element import Element
 
@@ -22,10 +22,10 @@ __all__ = (
 )
 
 
-_SIMPLE_TYPE = (str, bytes, bytearray, int, float, type(None), Enum)
+_SIMPLE_TYPE = (str, bytes, bytearray, int, float, type(None), _Enum)
 
 
-class EventStatus(str, ln.Enum):
+class EventStatus(str, ln.types.Enum):
     """Status states for tracking action execution progress.
 
     Attributes:
@@ -96,7 +96,7 @@ class Execution:
         Returns:
             dict: A dictionary representation of the execution state.
         """
-        res_ = ln.Unset
+        res_ = Unset
         json_serializable = True
 
         if not isinstance(self.response, _SIMPLE_TYPE):
@@ -119,7 +119,7 @@ class Execution:
                     res_ = d_
                     json_serializable = True
 
-        if res_ is ln.Unset and not json_serializable:
+        if res_ is Unset and not json_serializable:
             res_ = "<unserializable>"
 
         return {

lionagi/protocols/generic/processor.py

@@ -5,7 +5,11 @@
 import asyncio
 from typing import Any, ClassVar
 
-from lionagi.ln import ConcurrencyEvent, Semaphore, create_task_group
+from lionagi.ln.concurrency import (
+    ConcurrencyEvent,
+    Semaphore,
+    create_task_group,
+)
 
 from .._concepts import Observer
 from .element import ID
@@ -166,9 +170,9 @@ class Processor(Observer):
                                 async with self._concurrency_sem:
                                     await consume_stream(event)
 
-                            await tg.start_soon(stream_with_sem, next_event)
+                            tg.start_soon(stream_with_sem, next_event)
                         else:
-                            await tg.start_soon(consume_stream, next_event)
+                            tg.start_soon(consume_stream, next_event)
                     else:
                         # For non-streaming, just invoke
                         if self._concurrency_sem:
@@ -177,9 +181,9 @@ class Processor(Observer):
                                 async with self._concurrency_sem:
                                     await event.invoke()
 
-                            await tg.start_soon(invoke_with_sem, next_event)
+                            tg.start_soon(invoke_with_sem, next_event)
                         else:
-                            await tg.start_soon(next_event.invoke)
+                            tg.start_soon(next_event.invoke)
                     events_processed += 1
 
                 prev_event = next_event

lionagi/protocols/graph/graph.py

@@ -87,8 +87,7 @@ class Graph(Element, Relational, Generic[T]):
             or edge.tail not in self.internal_nodes
         ):
             raise RelationError(
-                "Failed to add edge: Either edge head or tail node does"
-                " not exist in the graph."
+                "Failed to add edge: Either edge head or tail node does not exist in the graph."
             )
         try:
             self.internal_edges.insert(len(self.internal_edges), edge)

lionagi/protocols/graph/node.py

@@ -63,7 +63,7 @@ class Node(Element, Relational, AsyncAdaptable, Adaptable):
         self, obj_key: str, many=False, **kwargs: Any
     ) -> Any:
         kwargs["adapt_meth"] = "to_dict"
-        kwargs["mode"] = "db"
+        kwargs["adapt_kw"] = {"mode": "db"}
         return await super().adapt_to_async(
             obj_key=obj_key, many=many, **kwargs
         )
@@ -77,7 +77,6 @@ class Node(Element, Relational, AsyncAdaptable, Adaptable):
         **kwargs: Any,
     ) -> Node:
         kwargs["adapt_meth"] = "from_dict"
-        kwargs["mode"] = "db"
         return await super().adapt_from_async(
             obj, obj_key=obj_key, many=many, **kwargs
         )
@@ -87,7 +86,7 @@ class Node(Element, Relational, AsyncAdaptable, Adaptable):
         Convert this Node to another format using a registered adapter.
         """
         kwargs["adapt_meth"] = "to_dict"
-        kwargs["mode"] = "db"
+        kwargs["adapt_kw"] = {"mode": "db"}
         return super().adapt_to(obj_key=obj_key, many=many, **kwargs)
 
     @classmethod
@@ -104,7 +103,6 @@ class Node(Element, Relational, AsyncAdaptable, Adaptable):
         auto-delegate to the correct subclass via from_dict.
         """
         kwargs["adapt_meth"] = "from_dict"
-        kwargs["mode"] = "db"
         return super().adapt_from(obj, obj_key=obj_key, many=many, **kwargs)
 
     @field_serializer("content")

lionagi/protocols/ids.py

@@ -0,0 +1,82 @@
+# Copyright (c) 2023 - 2025, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""ID bridge utilities for V0/V1 compatibility.
+
+This module provides utilities to convert between V0's IDType and V1's
+canonical UUID representation, enabling seamless interoperability during
+the gradual evolution process.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import UUID
+
+from .generic.element import Element, IDType
+
+__all__ = (
+    "to_uuid",
+    "canonical_id",
+)
+
+
+def to_uuid(value: Any) -> UUID:
+    """Convert ID-like values (IDType | UUID | str | Element) to UUID (v4).
+
+    Optimized version that avoids string conversion when possible by directly
+    accessing IDType's internal UUID. Falls back to V0's IDType.validate()
+    for validation semantics only when necessary.
+
+    Args:
+        value: An ID-like value to convert (IDType, UUID, str, or Element)
+
+    Returns:
+        UUID: A validated UUIDv4
+
+    Raises:
+        IDError: If the value cannot be converted to a valid UUIDv4
+
+    Examples:
+        >>> element = Element()
+        >>> uuid_val = to_uuid(element)
+        >>> isinstance(uuid_val, UUID)
+        True
+        >>> to_uuid("550e8400-e29b-41d4-a716-446655440000")
+        UUID('550e8400-e29b-41d4-a716-446655440000')
+    """
+    if isinstance(value, Element):
+        return value.id._id
+    if isinstance(value, UUID):
+        return value
+    if hasattr(value, "_id") and isinstance(value._id, UUID):
+        return value._id
+    # Fallback: Validate then access ._id directly (no string conversion)
+    validated_id = IDType.validate(value)
+    return validated_id._id
+
+
+def canonical_id(obj: Any) -> UUID:
+    """Accept an Observable-like object or raw ID and return canonical UUID.
+
+    Safe to use across V0/V1 without changing class definitions. Prefers
+    attribute access (.id) but falls back to treating the object as a raw ID.
+
+    Args:
+        obj: An Observable object with .id attribute, or a raw ID value
+
+    Returns:
+        UUID: The canonical UUID representation
+
+    Examples:
+        >>> element = Element()
+        >>> uuid_val = canonical_id(element)
+        >>> isinstance(uuid_val, UUID)
+        True
+        >>> canonical_id("550e8400-e29b-41d4-a716-446655440000")
+        UUID('550e8400-e29b-41d4-a716-446655440000')
+    """
+    # Prefer attribute access; fall back to treating obj as a raw id
+    id_like = getattr(obj, "id", obj)
+    return to_uuid(id_like)

lionagi/protocols/messages/instruction.py

@@ -587,8 +587,7 @@ class Instruction(RoledMessage):
 
         if request_model and request_fields:
             raise ValueError(
-                "You cannot pass both request_model and request_fields "
-                "to create_instruction"
+                "You cannot pass both request_model and request_fields to create_instruction"
             )
         if guidance:
             self.guidance = guidance

lionagi/protocols/messages/manager.py

@@ -216,8 +216,7 @@ class MessageManager(Manager):
         """
         if not isinstance(action_request, ActionRequest):
             raise ValueError(
-                "Error: please provide a corresponding action request for an "
-                "action response."
+                "Error: please provide a corresponding action request for an action response."
             )
         params = {
             "action_request": action_request,

lionagi/protocols/messages/message.py

@@ -241,10 +241,7 @@ class RoledMessage(Node, Sendable):
             if len(str(self.content)) > 75
             else str(self.content)
         )
-        return (
-            f"Message(role={self.role}, sender={self.sender}, "
-            f"content='{content_preview}')"
-        )
+        return f"Message(role={self.role}, sender={self.sender}, content='{content_preview}')"
 
 
 # File: lionagi/protocols/messages/message.py

lionagi/protocols/types.py

@@ -2,18 +2,11 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
-from ._concepts import (
-    Collective,
-    Communicatable,
-    Condition,
-    Manager,
-    Observable,
-    Observer,
-    Ordering,
-    Relational,
-    Sendable,
-)
+from ._concepts import Collective, Communicatable, Condition, Manager
+from ._concepts import Observable as LegacyObservable
+from ._concepts import Observer, Ordering, Relational, Sendable
 from .action.manager import ActionManager, FunctionCalling, Tool, ToolRef
+from .contracts import Observable, ObservableProto
 from .forms.flow import FlowDefinition, FlowStep
 from .forms.report import BaseForm, Form, Report
 from .generic.element import ID, Element, IDError, IDType, validate_order
@@ -30,6 +23,7 @@ from .generic.processor import Executor, Processor
 from .generic.progression import Progression, prog
 from .graph.edge import EdgeCondition
 from .graph.graph import Edge, Graph, Node
+from .ids import canonical_id, to_uuid
 from .mail.exchange import Exchange, Mail, Mailbox, Package, PackageCategory
 from .mail.manager import MailManager
 from .messages.base import (
@@ -56,11 +50,15 @@ __all__ = (
     "Communicatable",
     "Condition",
     "Manager",
-    "Observable",
+    "Observable",  # V1 Protocol (preferred)
+    "ObservableProto",  # Explicit V1 Protocol name
+    "LegacyObservable",  # V0 ABC (deprecated)
     "Observer",
     "Ordering",
     "Relational",
     "Sendable",
+    "canonical_id",  # V0/V1 bridge utility
+    "to_uuid",  # ID conversion utility
     "ID",
     "Element",
     "IDError",

lionagi/service/connections/providers/claude_code_.py

@@ -56,8 +56,7 @@ class ClaudeCodeEndpoint(Endpoint):
                 "Please install it with `uv pip install lionagi[claude_code_sdk]`."
             )
         warnings.warn(
-            "The claude_code `query` endpoint is deprecated. "
-            "Use `query_cli` endpoint instead.",
+            "The claude_code `query` endpoint is deprecated. Use `query_cli` endpoint instead.",
             DeprecationWarning,
         )
 

lionagi/service/resilience.py

@@ -216,8 +216,7 @@ class CircuitBreaker:
                     self._metrics["rejected_count"] += 1
 
                     logger.warning(
-                        f"Circuit '{self.name}' is HALF_OPEN and at capacity. "
-                        f"Try again later."
+                        f"Circuit '{self.name}' is HALF_OPEN and at capacity. Try again later."
                     )
 
                     return False

lionagi/tools/memory/tools.py

@@ -63,8 +63,7 @@ class MemoryRequest(BaseModel):
     content: str | None = Field(
         None,
         description=(
-            "Content to store. REQUIRED if action='store'. "
-            "For other actions, leave it None."
+            "Content to store. REQUIRED if action='store'. For other actions, leave it None."
         ),
     )
 
@@ -96,8 +95,7 @@ class MemoryRequest(BaseModel):
     query: str | None = Field(
         None,
         description=(
-            "Query text for semantic search. "
-            "REQUIRED for actions: 'recall', 'search', 'explore'."
+            "Query text for semantic search. REQUIRED for actions: 'recall', 'search', 'explore'."
         ),
     )