lionagi 0.15.13__py3-none-any.whl → 0.16.0__py3-none-any.whl

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/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/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/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/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/match_endpoint.py

@@ -47,6 +47,15 @@ def match_endpoint(
         from .providers.perplexity_ import PerplexityChatEndpoint
 
         return PerplexityChatEndpoint(None, **kwargs)
+    if provider == "nvidia_nim":
+        if "embed" in endpoint:
+            from .providers.nvidia_nim_ import NvidiaNimEmbedEndpoint
+
+            return NvidiaNimEmbedEndpoint(None, **kwargs)
+        if "chat" in endpoint or "completion" in endpoint:
+            from .providers.nvidia_nim_ import NvidiaNimChatEndpoint
+
+            return NvidiaNimChatEndpoint(None, **kwargs)
     if provider == "claude_code":
         if "cli" in endpoint:
             from .providers.claude_code_cli import ClaudeCodeCLIEndpoint

lionagi/service/connections/providers/nvidia_nim_.py

@@ -0,0 +1,100 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+NVIDIA NIM endpoint configurations.
+
+This module provides endpoint configurations for NVIDIA NIM (NVIDIA Inference Microservices),
+which offers GPU-accelerated inference for various AI models through an OpenAI-compatible API.
+
+NVIDIA NIM features:
+- OpenAI-compatible API endpoints
+- GPU-accelerated inference
+- Support for various open-source models (Llama, Mistral, etc.)
+- Both cloud-hosted and self-hosted options
+- Free tier with 1000 credits for development
+
+API Documentation: https://docs.nvidia.com/nim/
+Build Portal: https://build.nvidia.com/
+"""
+
+from lionagi.config import settings
+from lionagi.service.connections.endpoint import Endpoint
+from lionagi.service.connections.endpoint_config import EndpointConfig
+
+__all__ = (
+    "NvidiaNimChatEndpoint",
+    "NvidiaNimEmbedEndpoint",
+    "NVIDIA_NIM_CHAT_ENDPOINT_CONFIG",
+    "NVIDIA_NIM_EMBED_ENDPOINT_CONFIG",
+)
+
+
+def _get_nvidia_nim_config(**kwargs):
+    """Create NVIDIA NIM endpoint configuration with defaults.
+
+    NVIDIA NIM uses the integrate.api.nvidia.com endpoint for cloud-hosted models.
+    Authentication is via bearer token (API key from build.nvidia.com).
+    """
+    config = dict(
+        name="nvidia_nim_chat",
+        provider="nvidia_nim",
+        base_url="https://integrate.api.nvidia.com/v1",
+        endpoint="chat/completions",
+        kwargs={"model": "meta/llama3-8b-instruct"},  # Default model
+        api_key=settings.NVIDIA_NIM_API_KEY or "dummy-key-for-testing",
+        auth_type="bearer",
+        content_type="application/json",
+        method="POST",
+        requires_tokens=True,
+        # OpenAI-compatible format
+    )
+    config.update(kwargs)
+    return EndpointConfig(**config)
+
+
+# Chat endpoint configuration
+NVIDIA_NIM_CHAT_ENDPOINT_CONFIG = _get_nvidia_nim_config()
+
+# Embedding endpoint configuration
+# Note: You'll need to verify which embedding models are available on NVIDIA NIM
+NVIDIA_NIM_EMBED_ENDPOINT_CONFIG = _get_nvidia_nim_config(
+    name="nvidia_nim_embed",
+    endpoint="embeddings",
+    kwargs={"model": "nvidia/nv-embed-v1"},  # Example embedding model
+)
+
+
+class NvidiaNimChatEndpoint(Endpoint):
+    """NVIDIA NIM chat completion endpoint.
+
+    Supports various open-source models including:
+    - meta/llama3-8b-instruct
+    - meta/llama3-70b-instruct
+    - meta/llama3.1-405b-instruct
+    - mistralai/mixtral-8x7b-instruct-v0.1
+    - google/gemma-7b
+    - And many more...
+
+    Get your API key from: https://build.nvidia.com/
+    """
+
+    def __init__(self, config=None, **kwargs):
+        config = config or _get_nvidia_nim_config()
+        super().__init__(config, **kwargs)
+
+
+class NvidiaNimEmbedEndpoint(Endpoint):
+    """NVIDIA NIM embedding endpoint.
+
+    Note: Verify available embedding models at https://build.nvidia.com/
+    """
+
+    def __init__(self, config=None, **kwargs):
+        config = config or _get_nvidia_nim_config(
+            name="nvidia_nim_embed",
+            endpoint="embeddings",
+            kwargs={"model": "nvidia/nv-embed-v1"},
+        )
+        super().__init__(config, **kwargs)

lionagi/utils.py

@@ -5,7 +5,6 @@
 import contextlib
 import copy as _copy
 import dataclasses
-import importlib.util
 import json
 import logging
 import types
@@ -37,11 +36,29 @@ from pydantic_core import PydanticUndefinedType
 from typing_extensions import deprecated
 
 from .libs.validate.xml_parser import xml_to_dict
-from .ln import DataClass, Enum, KeysDict, Params, Undefined, UndefinedType
-from .ln import extract_json as to_json
-from .ln import fuzzy_json as fuzzy_parse_json
-from .ln import hash_dict, to_list
-from .ln.concurrency import is_coro_func
+from .ln import (
+    extract_json,
+    fuzzy_json,
+    get_bins,
+    hash_dict,
+    import_module,
+    is_coro_func,
+    is_import_installed,
+    to_list,
+)
+from .ln.types import (
+    DataClass,
+    Enum,
+    KeysDict,
+    MaybeSentinel,
+    MaybeUndefined,
+    MaybeUnset,
+    Params,
+    Undefined,
+    UndefinedType,
+    Unset,
+    UnsetType,
+)
 from .settings import Settings
 
 R = TypeVar("R")
@@ -52,6 +69,9 @@ logger = logging.getLogger(__name__)
 
 UNDEFINED = Undefined
 
+to_json = extract_json
+fuzzy_parse_json = fuzzy_json
+
 __all__ = (
     "UndefinedType",
     "KeysDict",
@@ -76,7 +96,6 @@ __all__ = (
     "get_bins",
     "EventStatus",
     "logger",
-    "throttle",
     "max_concurrent",
     "force_async",
     "breakdown_pydantic_annotation",
@@ -87,6 +106,14 @@ __all__ = (
     "is_union_type",
     "union_members",
     "to_json",
+    "Unset",
+    "UnsetType",
+    "Undefined",
+    "MaybeSentinel",
+    "MaybeUndefined",
+    "MaybeUnset",
+    "is_import_installed",
+    "import_module",
 )
 
 
@@ -888,60 +915,3 @@ def _is_pydantic_model(x: Any) -> bool:
         return isclass(x) and issubclass(x, BaseModel)
     except TypeError:
         return False
-
-
-def import_module(
-    package_name: str,
-    module_name: str = None,
-    import_name: str | list = None,
-) -> Any:
-    """
-    Import a module by its path.
-
-    Args:
-        module_path: The path of the module to import.
-
-    Returns:
-        The imported module.
-
-    Raises:
-        ImportError: If the module cannot be imported.
-    """
-    try:
-        full_import_path = (
-            f"{package_name}.{module_name}" if module_name else package_name
-        )
-
-        if import_name:
-            import_name = (
-                [import_name]
-                if not isinstance(import_name, list)
-                else import_name
-            )
-            a = __import__(
-                full_import_path,
-                fromlist=import_name,
-            )
-            if len(import_name) == 1:
-                return getattr(a, import_name[0])
-            return [getattr(a, name) for name in import_name]
-        else:
-            return __import__(full_import_path)
-
-    except ImportError as e:
-        raise ImportError(
-            f"Failed to import module {full_import_path}: {e}"
-        ) from e
-
-
-def is_import_installed(package_name: str) -> bool:
-    """
-    Check if a package is installed.
-
-    Args:
-        package_name: The name of the package to check.
-
-    Returns:
-        bool: True if the package is installed, False otherwise.
-    """
-    return importlib.util.find_spec(package_name) is not None

lionagi/version.py

@@ -1 +1 @@
-__version__ = "0.15.13"
+__version__ = "0.16.0"

{lionagi-0.15.13.dist-info → lionagi-0.16.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: lionagi
-Version: 0.15.13
+Version: 0.16.0
 Summary: An Intelligence Operating System.
 Author-email: HaiyangLi <quantocean.li@gmail.com>
 License:            Apache License
@@ -223,12 +223,14 @@ Requires-Dist: aiocache>=0.12.0
 Requires-Dist: aiohttp>=3.11.0
 Requires-Dist: anyio>=4.7.0
 Requires-Dist: backoff>=2.0.0
+Requires-Dist: exceptiongroup>=1.3.0
 Requires-Dist: jinja2>=3.0.0
 Requires-Dist: json-repair>=0.40.0
+Requires-Dist: msgspec>=0.18.0
 Requires-Dist: pillow>=10.0.0
 Requires-Dist: psutil>=6.0.0
 Requires-Dist: pydantic-settings>=2.8.0
-Requires-Dist: pydapter[pandas]>=1.0.4
+Requires-Dist: pydapter[pandas]>=1.0.5
 Requires-Dist: python-dotenv>=1.1.0
 Requires-Dist: tiktoken>=0.9.0
 Requires-Dist: toml>=0.8.0