mirascope 1.0.5__py3-none-any.whl → 2.1.1__py3-none-any.whl

mirascope/llm/providers/openai/responses/provider.py

@@ -0,0 +1,472 @@
+"""OpenAI Responses API client implementation."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+from typing_extensions import Unpack
+
+from openai import AsyncOpenAI, BadRequestError as OpenAIBadRequestError, OpenAI
+
+from ....context import Context, DepsT
+from ....exceptions import BadRequestError, NotFoundError
+from ....formatting import FormatSpec, FormattableT
+from ....messages import Message
+from ....responses import (
+    AsyncContextResponse,
+    AsyncContextStreamResponse,
+    AsyncResponse,
+    AsyncStreamResponse,
+    ContextResponse,
+    ContextStreamResponse,
+    Response,
+    StreamResponse,
+)
+from ....tools import AsyncContextToolkit, AsyncToolkit, ContextToolkit, Toolkit
+from ...base import BaseProvider
+from .. import _utils as _shared_utils
+from ..model_id import OpenAIModelId, model_name
+from . import _utils
+
+if TYPE_CHECKING:
+    from ....models import Params
+
+
+class OpenAIResponsesProvider(BaseProvider[OpenAI]):
+    """The client for the OpenAI Responses API."""
+
+    id = "openai:responses"
+    default_scope = "openai/"
+    error_map = {
+        **_shared_utils.OPENAI_ERROR_MAP,
+        OpenAIBadRequestError: lambda e: NotFoundError
+        if hasattr(e, "code") and e.code == "model_not_found"  # pyright: ignore[reportAttributeAccessIssue,reportUnknownMemberType]
+        else BadRequestError,
+    }
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+    ) -> None:
+        """Initialize the OpenAI Responses client."""
+        self.client = OpenAI(api_key=api_key, base_url=base_url)
+        self.async_client = AsyncOpenAI(api_key=api_key, base_url=base_url)
+
+    def get_error_status(self, e: Exception) -> int | None:
+        """Extract HTTP status code from OpenAI exception."""
+        return getattr(e, "status_code", None)
+
+    def _call(
+        self,
+        *,
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        toolkit: Toolkit,
+        format: FormatSpec[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> Response | Response[FormattableT]:
+        """Generate an `llm.Response` by synchronously calling the OpenAI Responses API.
+
+        Args:
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            An `llm.Response` object containing the LLM-generated content.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=toolkit,
+            format=format,
+            params=params,
+        )
+        openai_response = self.client.responses.create(**kwargs)
+
+        include_thoughts = _utils.get_include_thoughts(params)
+        assistant_message, finish_reason, usage = _utils.decode_response(
+            openai_response, model_id, self.id, include_thoughts=include_thoughts
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return Response(
+            raw=openai_response,
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=toolkit,
+            input_messages=messages,
+            assistant_message=assistant_message,
+            finish_reason=finish_reason,
+            usage=usage,
+            format=format,
+        )
+
+    async def _call_async(
+        self,
+        *,
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        toolkit: AsyncToolkit,
+        format: FormatSpec[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> AsyncResponse | AsyncResponse[FormattableT]:
+        """Generate an `llm.AsyncResponse` by asynchronously calling the OpenAI Responses API.
+
+        Args:
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            An `llm.AsyncResponse` object containing the LLM-generated content.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=toolkit,
+            format=format,
+            params=params,
+        )
+        openai_response = await self.async_client.responses.create(**kwargs)
+
+        include_thoughts = _utils.get_include_thoughts(params)
+        assistant_message, finish_reason, usage = _utils.decode_response(
+            openai_response, model_id, self.id, include_thoughts=include_thoughts
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return AsyncResponse(
+            raw=openai_response,
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=toolkit,
+            input_messages=messages,
+            assistant_message=assistant_message,
+            finish_reason=finish_reason,
+            usage=usage,
+            format=format,
+        )
+
+    def _stream(
+        self,
+        *,
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        toolkit: Toolkit,
+        format: FormatSpec[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> StreamResponse | StreamResponse[FormattableT]:
+        """Generate a `llm.StreamResponse` by synchronously streaming from the OpenAI Responses API.
+
+        Args:
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            A `llm.StreamResponse` object containing the LLM-generated content stream.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=toolkit,
+            format=format,
+            params=params,
+        )
+        openai_stream = self.client.responses.create(
+            **kwargs,
+            stream=True,
+        )
+
+        include_thoughts = _utils.get_include_thoughts(params)
+        chunk_iterator = _utils.decode_stream(
+            openai_stream, include_thoughts=include_thoughts
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return StreamResponse(
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=toolkit,
+            input_messages=messages,
+            chunk_iterator=chunk_iterator,
+            format=format,
+        )
+
+    async def _stream_async(
+        self,
+        *,
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        toolkit: AsyncToolkit,
+        format: FormatSpec[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
+        """Generate a `llm.AsyncStreamResponse` by asynchronously streaming from the OpenAI Responses API.
+
+        Args:
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            A `llm.AsyncStreamResponse` object containing the LLM-generated content stream.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=toolkit,
+            format=format,
+            params=params,
+        )
+        openai_stream = await self.async_client.responses.create(
+            **kwargs,
+            stream=True,
+        )
+
+        include_thoughts = _utils.get_include_thoughts(params)
+        chunk_iterator = _utils.decode_async_stream(
+            openai_stream, include_thoughts=include_thoughts
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return AsyncStreamResponse(
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=toolkit,
+            input_messages=messages,
+            chunk_iterator=chunk_iterator,
+            format=format,
+        )
+
+    def _context_call(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        toolkit: ContextToolkit[DepsT],
+        format: FormatSpec[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> ContextResponse[DepsT] | ContextResponse[DepsT, FormattableT]:
+        """Generate a `llm.ContextResponse` by synchronously calling the OpenAI Responses API with context.
+
+        Args:
+            ctx: The context object containing dependencies.
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            A `llm.ContextResponse` object containing the LLM-generated content and context.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=toolkit,
+            format=format,
+            params=params,
+        )
+        openai_response = self.client.responses.create(**kwargs)
+
+        include_thoughts = _utils.get_include_thoughts(params)
+        assistant_message, finish_reason, usage = _utils.decode_response(
+            openai_response, model_id, self.id, include_thoughts=include_thoughts
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return ContextResponse(
+            raw=openai_response,
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=toolkit,
+            input_messages=messages,
+            assistant_message=assistant_message,
+            finish_reason=finish_reason,
+            usage=usage,
+            format=format,
+        )
+
+    async def _context_call_async(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        toolkit: AsyncContextToolkit[DepsT],
+        format: FormatSpec[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> AsyncContextResponse[DepsT] | AsyncContextResponse[DepsT, FormattableT]:
+        """Generate a `llm.AsyncContextResponse` by asynchronously calling the OpenAI Responses API with context.
+
+        Args:
+            ctx: The context object containing dependencies.
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            A `llm.AsyncContextResponse` object containing the LLM-generated content and context.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=toolkit,
+            format=format,
+            params=params,
+        )
+        openai_response = await self.async_client.responses.create(**kwargs)
+
+        include_thoughts = _utils.get_include_thoughts(params)
+        assistant_message, finish_reason, usage = _utils.decode_response(
+            openai_response, model_id, self.id, include_thoughts=include_thoughts
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return AsyncContextResponse(
+            raw=openai_response,
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=toolkit,
+            input_messages=messages,
+            assistant_message=assistant_message,
+            finish_reason=finish_reason,
+            usage=usage,
+            format=format,
+        )
+
+    def _context_stream(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        toolkit: ContextToolkit[DepsT],
+        format: FormatSpec[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> ContextStreamResponse[DepsT] | ContextStreamResponse[DepsT, FormattableT]:
+        """Generate a `llm.ContextStreamResponse` by synchronously streaming from the OpenAI Responses API with context.
+
+        Args:
+            ctx: The context object containing dependencies.
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            A `llm.ContextStreamResponse` object containing the LLM-generated content stream and context.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=toolkit,
+            format=format,
+            params=params,
+        )
+
+        openai_stream = self.client.responses.create(
+            **kwargs,
+            stream=True,
+        )
+
+        include_thoughts = _utils.get_include_thoughts(params)
+        chunk_iterator = _utils.decode_stream(
+            openai_stream, include_thoughts=include_thoughts
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return ContextStreamResponse(
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=toolkit,
+            input_messages=messages,
+            chunk_iterator=chunk_iterator,
+            format=format,
+        )
+
+    async def _context_stream_async(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        toolkit: AsyncContextToolkit[DepsT],
+        format: FormatSpec[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> (
+        AsyncContextStreamResponse[DepsT]
+        | AsyncContextStreamResponse[DepsT, FormattableT]
+    ):
+        """Generate a `llm.AsyncContextStreamResponse` by asynchronously streaming from the OpenAI Responses API with context.
+
+        Args:
+            ctx: The context object containing dependencies.
+            model_id: Model identifier to use.
+            messages: Messages to send to the LLM.
+            tools: Optional tools that the model may invoke.
+            format: Optional response format specifier.
+            **params: Additional parameters to configure output (e.g. temperature). See `llm.Params`.
+
+        Returns:
+            A `llm.AsyncContextStreamResponse` object containing the LLM-generated content stream and context.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=toolkit,
+            format=format,
+            params=params,
+        )
+
+        openai_stream = await self.async_client.responses.create(
+            **kwargs,
+            stream=True,
+        )
+
+        include_thoughts = _utils.get_include_thoughts(params)
+        chunk_iterator = _utils.decode_async_stream(
+            openai_stream, include_thoughts=include_thoughts
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return AsyncContextStreamResponse(
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=toolkit,
+            input_messages=messages,
+            chunk_iterator=chunk_iterator,
+            format=format,
+        )

mirascope/llm/providers/openrouter/__init__.py

@@ -0,0 +1,5 @@
+"""OpenRouter provider for accessing multiple LLM providers via OpenRouter's API."""
+
+from .provider import OpenRouterProvider
+
+__all__ = ["OpenRouterProvider"]

mirascope/llm/providers/openrouter/provider.py

@@ -0,0 +1,67 @@
+"""OpenRouter provider implementation."""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from ..openai.completions._utils import (
+    CompletionsModelFeatureInfo,
+    feature_info_for_openai_model,
+)
+from ..openai.completions.base_provider import BaseOpenAICompletionsProvider
+from ..openai.model_id import model_name as openai_model_name
+
+
+class OpenRouterProvider(BaseOpenAICompletionsProvider):
+    """Provider for OpenRouter's OpenAI-compatible API.
+
+    Inherits from BaseOpenAICompletionsProvider with OpenRouter-specific configuration:
+    - Uses OpenRouter's API endpoint
+    - Requires OPENROUTER_API_KEY
+
+    Usage:
+        Option 1: Use "openrouter/" prefix for explicit OpenRouter models:
+
+        ```python
+        from mirascope import llm
+
+        llm.register_provider("openrouter", scope="openrouter/")
+
+        @llm.call("openrouter/openai/gpt-4o")
+        def my_prompt():
+            return [llm.messages.user("Hello!")]
+        ```
+
+        Option 2: Route existing model IDs through OpenRouter:
+
+        ```python
+        from mirascope import llm
+
+        # Register for openai and anthropic models via OpenRouter
+        llm.register_provider("openrouter", scope=["openai/", "anthropic/"])
+
+        # Now openai/ models go through OpenRouter
+        @llm.call("openai/gpt-4")
+        def my_prompt():
+            return [llm.messages.user("Hello!")]
+        ```
+    """
+
+    id: ClassVar[str] = "openrouter"
+    default_scope: ClassVar[str | list[str]] = []
+    default_base_url: ClassVar[str | None] = "https://openrouter.ai/api/v1"
+    api_key_env_var: ClassVar[str] = "OPENROUTER_API_KEY"
+    api_key_required: ClassVar[bool] = True
+    provider_name: ClassVar[str | None] = "OpenRouter"
+
+    def _model_name(self, model_id: str) -> str:
+        """Strip 'openrouter/' prefix from model ID for OpenRouter API."""
+        return model_id.removeprefix("openrouter/")
+
+    def _model_feature_info(self, model_id: str) -> CompletionsModelFeatureInfo:
+        """Return OpenAI feature info for openai/* models, empty info otherwise."""
+        base_model_id = model_id.removeprefix("openrouter/")
+        if base_model_id.startswith("openai/"):
+            openai_name = openai_model_name(base_model_id, None)
+            return feature_info_for_openai_model(openai_name)
+        return CompletionsModelFeatureInfo()

mirascope/llm/providers/provider_id.py

@@ -0,0 +1,26 @@
+"""Identifiers for all registered providers."""
+
+from typing import Literal, TypeAlias, get_args
+
+KnownProviderId: TypeAlias = Literal[
+    "anthropic",  # Anthropic provider via AnthropicProvider
+    "anthropic-beta",  # Anthropic beta provider via AnthropicBetaProvider
+    "google",  # Google provider via GoogleProvider
+    "mirascope",  # Mirascope Router provider via MirascopeProvider
+    "mlx",  # Local inference powered by `mlx-lm`, via MLXProvider
+    "ollama",  # Ollama provider via OllamaProvider
+    "openai",  # OpenAI provider via OpenAIProvider (prefers Responses routing when available)
+    "openrouter",  # OpenRouter provider via OpenRouterProvider
+    "together",  # Together AI provider via TogetherProvider
+]
+KNOWN_PROVIDER_IDS = get_args(KnownProviderId)
+
+ProviderId = KnownProviderId | str
+
+OpenAICompletionsCompatibleProviderId: TypeAlias = Literal[
+    "ollama",  # Ollama (OpenAI-compatible)
+    "openai",  # OpenAI via OpenAIProvider (routes to completions)
+    "openai:completions",  # OpenAI Completions API directly
+    "openrouter",  # OpenRouter (OpenAI-compatible)
+    "together",  # Together AI (OpenAI-compatible)
+]