lionagi 0.14.8__py3-none-any.whl → 0.14.10__py3-none-any.whl

lionagi/service/connections/providers/oai_.py

@@ -2,107 +2,126 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+OpenAI and OpenAI-compatible endpoint configurations.
+
+This module provides endpoint configurations for:
+- OpenAI (chat, response, embedding)
+- OpenRouter (OpenAI-compatible)
+- Groq (OpenAI-compatible)
+
+Each provider has a helper function (_get_*_config) that creates
+configurations with sensible defaults that can be overridden.
+"""
+
 from pydantic import BaseModel
 
 from lionagi.config import settings
 from lionagi.service.connections.endpoint import Endpoint
 from lionagi.service.connections.endpoint_config import EndpointConfig
-from lionagi.service.third_party.openai_models import (
-    CreateChatCompletionRequest,
-    CreateResponse,
+from lionagi.service.third_party.openai_model_names import (
+    REASONING_MODELS,
+    is_reasoning_model,
 )
 
 __all__ = (
     "OpenaiChatEndpoint",
     "OpenaiResponseEndpoint",
+    "OpenaiEmbedEndpoint",
     "OpenrouterChatEndpoint",
+    "GroqChatEndpoint",
+    "OPENAI_CHAT_ENDPOINT_CONFIG",
+    "OPENAI_RESPONSE_ENDPOINT_CONFIG",
+    "OPENAI_EMBEDDING_ENDPOINT_CONFIG",
+    "OPENROUTER_CHAT_ENDPOINT_CONFIG",
     "OPENROUTER_GEMINI_ENDPOINT_CONFIG",
+    "GROQ_CHAT_ENDPOINT_CONFIG",
+    "REASONING_MODELS",
+    "REASONING_NOT_SUPPORT_PARAMS",
 )
 
 
-OPENAI_CHAT_ENDPOINT_CONFIG = EndpointConfig(
-    name="openai_chat",
-    provider="openai",
-    base_url="https://api.openai.com/v1",
-    endpoint="chat/completions",
-    kwargs={"model": "gpt-4.1-nano"},
-    api_key=settings.OPENAI_API_KEY or "dummy-key-for-testing",
-    auth_type="bearer",
-    content_type="application/json",
-    method="POST",
-    requires_tokens=True,
-    request_options=CreateChatCompletionRequest,
-)
-
-OPENAI_RESPONSE_ENDPOINT_CONFIG = EndpointConfig(
+def _get_openai_config(**kwargs):
+    """Create OpenAI endpoint configuration with defaults."""
+    config = dict(
+        name="openai_chat",
+        provider="openai",
+        base_url="https://api.openai.com/v1",
+        endpoint="chat/completions",
+        kwargs={"model": settings.OPENAI_DEFAULT_MODEL},
+        api_key=settings.OPENAI_API_KEY or "dummy-key-for-testing",
+        auth_type="bearer",
+        content_type="application/json",
+        method="POST",
+        requires_tokens=True,
+        # NOTE: OpenAI models have incorrect role literals, only use for param validation
+        # request_options=CreateChatCompletionRequest,
+    )
+    config.update(kwargs)
+    return EndpointConfig(**config)
+
+
+def _get_openrouter_config(**kwargs):
+    """Create OpenRouter endpoint configuration with defaults."""
+    config = dict(
+        name="openrouter_chat",
+        provider="openrouter",
+        base_url="https://openrouter.ai/api/v1",
+        endpoint="chat/completions",
+        kwargs={"model": "google/gemini-2.5-flash"},
+        api_key=settings.OPENROUTER_API_KEY or "dummy-key-for-testing",
+        auth_type="bearer",
+        content_type="application/json",
+        method="POST",
+        # NOTE: OpenRouter uses OpenAI-compatible format
+        # request_options=CreateChatCompletionRequest,
+    )
+    config.update(kwargs)
+    return EndpointConfig(**config)
+
+
+def _get_groq_config(**kwargs):
+    """Create Groq endpoint configuration with defaults."""
+    config = dict(
+        name="groq_chat",
+        provider="groq",
+        base_url="https://api.groq.com/openai/v1",
+        endpoint="chat/completions",
+        kwargs={"model": "llama-3.3-70b-versatile"},
+        api_key=settings.GROQ_API_KEY or "dummy-key-for-testing",
+        auth_type="bearer",
+        content_type="application/json",
+        method="POST",
+    )
+    config.update(kwargs)
+    return EndpointConfig(**config)
+
+
+# OpenAI endpoints
+OPENAI_CHAT_ENDPOINT_CONFIG = _get_openai_config()
+
+OPENAI_RESPONSE_ENDPOINT_CONFIG = _get_openai_config(
     name="openai_response",
-    provider="openai",
-    base_url="https://api.openai.com/v1",
-    endpoint="chat/completions",  # OpenAI responses API uses same endpoint
-    kwargs={"model": "gpt-4o"},
-    api_key=settings.OPENAI_API_KEY or "dummy-key-for-testing",
-    auth_type="bearer",
-    content_type="application/json",
-    method="POST",
-    requires_tokens=True,
-    request_options=CreateResponse,
-)
-
-OPENROUTER_CHAT_ENDPOINT_CONFIG = EndpointConfig(
-    name="openrouter_chat",
-    provider="openrouter",
-    base_url="https://openrouter.ai/api/v1",
-    endpoint="chat/completions",
-    kwargs={"model": "google/gemini-2.5-flash"},
-    api_key=settings.OPENROUTER_API_KEY or "dummy-key-for-testing",
-    auth_type="bearer",
-    content_type="application/json",
-    method="POST",
-    request_options=CreateChatCompletionRequest,
+    endpoint="responses",
 )
 
-OPENAI_EMBEDDING_ENDPOINT_CONFIG = EndpointConfig(
+OPENAI_EMBEDDING_ENDPOINT_CONFIG = _get_openai_config(
     name="openai_embed",
-    provider="openai",
-    base_url="https://api.openai.com/v1",
     endpoint="embeddings",
     kwargs={"model": "text-embedding-3-small"},
-    api_key=settings.OPENAI_API_KEY or "dummy-key-for-testing",
-    auth_type="bearer",
-    content_type="application/json",
-    method="POST",
-)
-
-GROQ_CHAT_ENDPOINT_CONFIG = EndpointConfig(
-    name="groq_chat",
-    provider="groq",
-    base_url="https://api.groq.com/openai/v1",
-    endpoint="chat/completions",
-    api_key=settings.GROQ_API_KEY or "dummy-key-for-testing",
-    auth_type="bearer",
-    content_type="application/json",
-    method="POST",
 )
 
+# OpenRouter endpoints
+OPENROUTER_CHAT_ENDPOINT_CONFIG = _get_openrouter_config()
 
-REASONING_MODELS = (
-    "o1",
-    "o1-2024-12-17",
-    "o1-preview-2024-09-12",
-    "o1-pro",
-    "o1-pro-2025-03-19",
-    "o3-pro",
-    "o3-pro-2025-06-10",
-    "o3",
-    "o3-2025-04-16",
-    "o4-mini",
-    "o4-mini-2025-04-16",
-    "o3-mini",
-    "o3-mini-2025-01-31",
-    "o1-mini",
-    "o1-mini-2024-09-12",
+OPENROUTER_GEMINI_ENDPOINT_CONFIG = _get_openrouter_config(
+    name="openrouter_gemini",
+    kwargs={"model": "google/gemini-2.5-flash"},
 )
 
+# Groq endpoints
+GROQ_CHAT_ENDPOINT_CONFIG = _get_groq_config()
+
 REASONING_NOT_SUPPORT_PARAMS = (
     "temperature",
     "top_p",
@@ -113,7 +132,8 @@ REASONING_NOT_SUPPORT_PARAMS = (
 
 
 class OpenaiChatEndpoint(Endpoint):
-    def __init__(self, config=OPENAI_CHAT_ENDPOINT_CONFIG, **kwargs):
+    def __init__(self, config=None, **kwargs):
+        config = config or _get_openai_config()
         super().__init__(config, **kwargs)
 
     def create_payload(
@@ -129,7 +149,11 @@ class OpenaiChatEndpoint(Endpoint):
 
         # Handle reasoning models
         model = payload.get("model")
-        if model in REASONING_MODELS:
+        if (
+            model
+            and is_reasoning_model(model)
+            and not model.startswith("gpt-5")
+        ):
             # Remove unsupported parameters for reasoning models
             for param in REASONING_NOT_SUPPORT_PARAMS:
                 payload.pop(param, None)
@@ -146,20 +170,31 @@ class OpenaiChatEndpoint(Endpoint):
 
 
 class OpenaiResponseEndpoint(Endpoint):
-    def __init__(self, config=OPENAI_RESPONSE_ENDPOINT_CONFIG, **kwargs):
+    def __init__(self, config=None, **kwargs):
+        config = config or _get_openai_config(
+            name="openai_response",
+            endpoint="responses",
+        )
         super().__init__(config, **kwargs)
 
 
 class OpenrouterChatEndpoint(Endpoint):
-    def __init__(self, config=OPENROUTER_CHAT_ENDPOINT_CONFIG, **kwargs):
+    def __init__(self, config=None, **kwargs):
+        config = config or _get_openrouter_config()
         super().__init__(config, **kwargs)
 
 
 class GroqChatEndpoint(Endpoint):
-    def __init__(self, config=GROQ_CHAT_ENDPOINT_CONFIG, **kwargs):
+    def __init__(self, config=None, **kwargs):
+        config = config or _get_groq_config()
         super().__init__(config, **kwargs)
 
 
 class OpenaiEmbedEndpoint(Endpoint):
-    def __init__(self, config=OPENAI_EMBEDDING_ENDPOINT_CONFIG, **kwargs):
+    def __init__(self, config=None, **kwargs):
+        config = config or _get_openai_config(
+            name="openai_embed",
+            endpoint="embeddings",
+            kwargs={"model": "text-embedding-3-small"},
+        )
         super().__init__(config, **kwargs)

lionagi/service/connections/providers/ollama_.py

@@ -2,31 +2,50 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Ollama endpoint configuration.
+
+Ollama provides local model hosting with both native and OpenAI-compatible APIs.
+This module configures the OpenAI-compatible endpoint for consistency.
+"""
+
 from pydantic import BaseModel
 
 from lionagi.service.connections.endpoint import Endpoint
 from lionagi.service.connections.endpoint_config import EndpointConfig
-from lionagi.service.third_party.openai_models import (
-    CreateChatCompletionRequest,
-)
 from lionagi.utils import is_import_installed
 
+__all__ = (
+    "OllamaChatEndpoint",
+    "OLLAMA_CHAT_ENDPOINT_CONFIG",
+)
+
 _HAS_OLLAMA = is_import_installed("ollama")
 
-OLLAMA_CHAT_ENDPOINT_CONFIG = EndpointConfig(
-    name="ollama_chat",
-    provider="ollama",
-    base_url="http://localhost:11434/v1",  # Ollama desktop client default
-    endpoint="chat/completions",  # Use full OpenAI-compatible endpoint
-    kwargs={},  # Empty kwargs, model will be provided at runtime
-    openai_compatible=False,  # Use HTTP transport
-    api_key=None,  # No API key needed
-    method="POST",
-    content_type="application/json",
-    auth_type="none",  # No authentication
-    default_headers={},  # No auth headers needed
-    request_options=CreateChatCompletionRequest,  # Use Pydantic model for validation
-)
+
+def _get_ollama_config(**kwargs):
+    """Create Ollama endpoint configuration with defaults."""
+    config = dict(
+        name="ollama_chat",
+        provider="ollama",
+        base_url="http://localhost:11434/v1",  # OpenAI-compatible endpoint
+        endpoint="chat/completions",
+        kwargs={},  # Model will be provided at runtime
+        openai_compatible=False,  # Use HTTP transport
+        api_key=None,  # No API key needed
+        method="POST",
+        content_type="application/json",
+        auth_type="none",  # No authentication
+        default_headers={},  # No auth headers needed
+        # NOTE: Not using request_options due to OpenAI model role literal issues
+        # request_options=CreateChatCompletionRequest,
+    )
+    config.update(kwargs)
+    return EndpointConfig(**config)
+
+
+# Default OpenAI-compatible configuration
+OLLAMA_CHAT_ENDPOINT_CONFIG = _get_ollama_config()
 
 
 class OllamaChatEndpoint(Endpoint):
@@ -34,7 +53,7 @@ class OllamaChatEndpoint(Endpoint):
     Documentation: https://platform.openai.com/docs/api-reference/chat/create
     """
 
-    def __init__(self, config=OLLAMA_CHAT_ENDPOINT_CONFIG, **kwargs):
+    def __init__(self, config=None, **kwargs):
         if not _HAS_OLLAMA:
             raise ModuleNotFoundError(
                 "ollama is not installed, please install it with `pip install lionagi[ollama]`"
@@ -44,6 +63,7 @@ class OllamaChatEndpoint(Endpoint):
         if "api_key" in kwargs:
             kwargs.pop("api_key")
 
+        config = config or _get_ollama_config()
         super().__init__(config, **kwargs)
 
         from ollama import list as ollama_list  # type: ignore[import]

lionagi/service/connections/providers/perplexity_.py

@@ -2,28 +2,50 @@
 #
 # SPDX-License-Identifier: Apache-2.0
 
+"""
+Perplexity AI endpoint configuration.
+
+Perplexity provides real-time web search and Q&A capabilities through their Sonar API.
+This module configures endpoints for different Sonar model tiers.
+"""
+
 from lionagi.config import settings
 from lionagi.service.connections.endpoint import Endpoint
 from lionagi.service.connections.endpoint_config import EndpointConfig
 from lionagi.service.third_party.pplx_models import PerplexityChatRequest
 
-__all__ = ("PerplexityChatEndpoint",)
+__all__ = (
+    "PerplexityChatEndpoint",
+    "PERPLEXITY_CHAT_ENDPOINT_CONFIG",
+)
 
 
-ENDPOINT_CONFIG = EndpointConfig(
-    name="perplexity_chat",
-    provider="perplexity",
-    base_url="https://api.perplexity.ai",
-    endpoint="chat/completions",
-    method="POST",
-    kwargs={"model": "sonar"},
-    api_key=settings.PERPLEXITY_API_KEY or "dummy-key-for-testing",
-    auth_type="bearer",
-    content_type="application/json",
-    request_options=PerplexityChatRequest,
-)
+def _get_perplexity_config(**kwargs):
+    """Create Perplexity endpoint configuration with defaults."""
+    config = dict(
+        name="perplexity_chat",
+        provider="perplexity",
+        base_url="https://api.perplexity.ai",
+        endpoint="chat/completions",
+        method="POST",
+        kwargs={"model": "sonar"},  # Default to base sonar model
+        api_key=settings.PERPLEXITY_API_KEY or "dummy-key-for-testing",
+        auth_type="bearer",
+        content_type="application/json",
+        request_options=PerplexityChatRequest,
+    )
+    config.update(kwargs)
+    return EndpointConfig(**config)
+
+
+# Default configuration (users can specify model at runtime)
+PERPLEXITY_CHAT_ENDPOINT_CONFIG = _get_perplexity_config()
+
+# Legacy naming for backward compatibility
+ENDPOINT_CONFIG = PERPLEXITY_CHAT_ENDPOINT_CONFIG
 
 
 class PerplexityChatEndpoint(Endpoint):
-    def __init__(self, config=ENDPOINT_CONFIG, **kwargs):
+    def __init__(self, config=None, **kwargs):
+        config = config or _get_perplexity_config()
         super().__init__(config, **kwargs)

lionagi/service/connections/providers/types.py

@@ -0,0 +1,30 @@
+from .anthropic_ import AnthropicMessagesEndpoint
+from .claude_code_ import ClaudeCodeEndpoint, ClaudeCodeRequest
+from .claude_code_cli import ClaudeCodeCLIEndpoint
+from .exa_ import ExaSearchEndpoint, ExaSearchRequest
+from .oai_ import (
+    GroqChatEndpoint,
+    OpenaiChatEndpoint,
+    OpenaiEmbedEndpoint,
+    OpenaiResponseEndpoint,
+    OpenrouterChatEndpoint,
+)
+from .ollama_ import OllamaChatEndpoint
+from .perplexity_ import PerplexityChatEndpoint, PerplexityChatRequest
+
+__all__ = (
+    "AnthropicMessagesEndpoint",
+    "ClaudeCodeEndpoint",
+    "ClaudeCodeRequest",
+    "ClaudeCodeCLIEndpoint",
+    "ExaSearchEndpoint",
+    "ExaSearchRequest",
+    "OpenaiChatEndpoint",
+    "OpenaiEmbedEndpoint",
+    "OpenaiResponseEndpoint",
+    "OpenrouterChatEndpoint",
+    "GroqChatEndpoint",
+    "OllamaChatEndpoint",
+    "PerplexityChatEndpoint",
+    "PerplexityChatRequest",
+)

lionagi/service/hooks/__init__.py

@@ -0,0 +1,25 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from lionagi.protocols.types import DataLogger
+
+from ._types import AssosiatedEventInfo, HookDict, HookEventTypes
+from .hook_event import HookEvent
+from .hook_registry import HookRegistry
+
+global_hook_logger = DataLogger(
+    persist_dir="./data/logs",
+    subfolder="hooks",
+    file_prefix="hook",
+    capacity=1000,
+)
+
+
+__all__ = (
+    "HookEventTypes",
+    "HookDict",
+    "AssosiatedEventInfo",
+    "HookEvent",
+    "HookRegistry",
+    "global_hook_logger",
+)

lionagi/service/hooks/_types.py

@@ -0,0 +1,52 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import TypeVar
+
+from typing_extensions import TypedDict
+
+from lionagi.utils import StringEnum
+
+SC = TypeVar("SC")  # streaming chunk type
+
+__all__ = (
+    "HookEventTypes",
+    "ALLOWED_HOOKS_TYPES",
+    "HookDict",
+    "StreamHandlers",
+    "AssosiatedEventInfo",
+)
+
+
+class HookEventTypes(StringEnum):
+    PreEventCreate = "pre_event_create"
+    PreInvokation = "pre_invokation"
+    PostInvokation = "post_invokation"
+
+
+ALLOWED_HOOKS_TYPES = HookEventTypes.allowed()
+
+
+class HookDict(TypedDict):
+    pre_event_create: Callable | None
+    pre_invokation: Callable | None
+    post_invokation: Callable | None
+
+
+StreamHandlers = dict[str, Callable[[SC], Awaitable[None]]]
+
+
+class AssosiatedEventInfo(TypedDict, total=False):
+    """Information about the event associated with the hook."""
+
+    lion_class: str
+    """Full qualified name of the event class."""
+
+    event_id: str
+    """ID of the event."""
+
+    event_created_at: float
+    """Creation timestamp of the event."""

lionagi/service/hooks/_utils.py

@@ -0,0 +1,85 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from anyio import sleep
+
+from lionagi._errors import ValidationError
+from lionagi.utils import is_coro_func
+
+from ._types import ALLOWED_HOOKS_TYPES, HookEventTypes
+
+__all__ = (
+    "get_handler",
+    "validate_hooks",
+    "validate_stream_handlers",
+)
+
+
+def get_handler(d_: dict, k: str | type, get: bool = False, /):
+    handler = d_.get(k)
+    if handler is None and not get:
+        return None
+
+    if handler is not None:
+        if not is_coro_func(handler):
+
+            async def _func(x):
+                await sleep(0)
+                return handler(x)
+
+            return _func
+        return handler
+
+    async def _func(x):
+        await sleep(0)
+        return x
+
+    return _func
+
+
+def validate_hooks(kw):
+    """Validate that all hooks are callable."""
+    if not isinstance(kw, dict):
+        raise ValidationError.from_value(
+            kw,
+            expected="A dictionary of hooks",
+            message="Hooks must be a dictionary of callable functions",
+        )
+    for k, v in kw.items():
+        if not isinstance(k, HookEventTypes) or k not in ALLOWED_HOOKS_TYPES:
+            raise ValidationError.from_value(
+                k,
+                expected=f"One of {ALLOWED_HOOKS_TYPES}",
+                message=f"Hook key must be one of {ALLOWED_HOOKS_TYPES}, got {k}",
+            )
+        if not callable(v):
+            raise ValidationError.from_value(
+                v,
+                expected="A callable function",
+                message=f"Hook for {k} must be callable, got {type(v)}",
+            )
+
+
+def validate_stream_handlers(kw):
+    """Validate that all stream handlers are callable."""
+    if not isinstance(kw, dict):
+        raise ValidationError.from_value(
+            kw,
+            expected="A dictionary of stream handlers",
+            message="Stream handlers must be a dictionary of callable functions",
+        )
+    for k, v in kw.items():
+        if not isinstance(k, str | type):
+            raise ValidationError.from_value(
+                k,
+                expected="A name or type of the chunk being handled",
+                message=f"Stream handler key must be a string or type, got {type(k)}",
+            )
+        if not callable(v):
+            raise ValidationError.from_value(
+                v,
+                expected="A callable function",
+                message=f"Stream handler for {k} must be callable, got {type(v)}",
+            )

lionagi/service/hooks/hook_event.py

@@ -0,0 +1,67 @@
+# Copyright (c) 2025, HaiyangLi <quantocean.li at gmail dot com>
+# SPDX-License-Identifier: Apache-2.0
+
+from __future__ import annotations
+
+from typing import Any
+
+import anyio
+from pydantic import Field, PrivateAttr
+
+from lionagi.libs.concurrency import fail_after, get_cancelled_exc_class
+from lionagi.protocols.types import Event, EventStatus
+
+from ._types import AssosiatedEventInfo, HookEventTypes
+from .hook_registry import HookRegistry
+
+
+class HookEvent(Event):
+    registry: HookRegistry = Field(..., exclude=True)
+    hook_type: HookEventTypes
+    exit: bool = Field(False, exclude=True)
+    timeout: int = Field(30, exclude=True)
+    params: dict[str, Any] = Field(default_factory=dict, exclude=True)
+    event_like: Event | type[Event] = Field(..., exclude=True)
+    _should_exit: bool = PrivateAttr(False)
+    _exit_cause: BaseException | None = PrivateAttr(None)
+
+    assosiated_event_info: AssosiatedEventInfo | None = None
+
+    async def invoke(self):
+        start = anyio.current_time()
+        self.execution.status = EventStatus.PROCESSING
+        try:
+            with fail_after(self.timeout):
+                (res, se, st), meta = await self.registry.call(
+                    self.event_like,
+                    hook_type=self.hook_type,
+                    exit=self.exit,
+                    **self.params,
+                )
+
+                self.assosiated_event_info = AssosiatedEventInfo(**meta)
+                self._should_exit = se
+                self.execution.status = st
+                if isinstance(res, tuple) and len(res) == 2:
+                    self.execution.response = None
+                    self.execution.error = str(res[1])
+                    self._exit_cause = res[1]
+                    raise res[1]
+                if isinstance(res, Exception):
+                    self.execution.response = None
+                    self.execution.error = str(res)
+                    self._exit_cause = res
+                else:
+                    self.execution.response = res
+                    self.execution.error = None
+        except get_cancelled_exc_class():
+            raise
+
+        except Exception as e:
+            self.execution.status = EventStatus.FAILED
+            self.execution.response = None
+            self.execution.error = str(e)
+            self._should_exit = True
+
+        finally:
+            self.execution.duration = anyio.current_time() - start