mirascope 2.0.0a2__py3-none-any.whl → 2.0.0a4__py3-none-any.whl

mirascope/llm/providers/openai/provider.py

@@ -0,0 +1,398 @@
+"""Unified OpenAI client implementation."""
+
+from collections.abc import Sequence
+from typing_extensions import Unpack
+
+from openai import OpenAI
+
+from ...context import Context, DepsT
+from ...formatting import Format, FormattableT
+from ...messages import Message
+from ...responses import (
+    AsyncContextResponse,
+    AsyncContextStreamResponse,
+    AsyncResponse,
+    AsyncStreamResponse,
+    ContextResponse,
+    ContextStreamResponse,
+    Response,
+    StreamResponse,
+)
+from ...tools import (
+    AsyncContextTool,
+    AsyncContextToolkit,
+    AsyncTool,
+    AsyncToolkit,
+    ContextTool,
+    ContextToolkit,
+    Tool,
+    Toolkit,
+)
+from ..base import BaseProvider, Params
+from .completions import OpenAICompletionsProvider
+from .model_id import OPENAI_KNOWN_MODELS, OpenAIModelId
+from .responses import OpenAIResponsesProvider
+
+
+def _has_audio_content(messages: Sequence[Message]) -> bool:
+    """Returns whether a sequence of messages contains any audio content."""
+    for message in messages:
+        if message.role == "system":
+            continue
+        for content in message.content:
+            if content.type == "audio":
+                return True
+    return False
+
+
+def choose_api_mode(model_id: OpenAIModelId, messages: Sequence[Message]) -> str:
+    """Choose between 'responses' or 'completions' API based on model_id and messages.
+
+    Args:
+        model_id: The model identifier.
+        messages: The messages to send to the LLM.
+
+    Returns:
+        Either "responses" or "completions" depending on the model and message content.
+
+    If the user manually specified an api mode (by appending it as a suffix to the model
+    id), then we use it.
+
+    Otherwise, we prefer the responses API where supported (because it has better
+    reasoning support and better prompt caching). However we will use the :completions api
+    if the messages contain any audio content, as audio content is not yet supported in
+    the responses API.
+    """
+    if model_id.endswith(":completions"):
+        return "completions"
+    elif model_id.endswith(":responses"):
+        return "responses"
+
+    if _has_audio_content(messages):
+        return "completions"
+
+    if f"{model_id}:responses" in OPENAI_KNOWN_MODELS:
+        # Prefer responses api when we know it is available
+        return "responses"
+    elif f"{model_id}:completions" in OPENAI_KNOWN_MODELS:
+        # If we know from testing that the completions api is available, and
+        # (implied by above) that responses wasn't, then we should use completions
+        return "completions"
+
+    # If we don't have either :responses or :completions in the known_models, it's
+    # likely that this is a new model we haven't tested. We default to responses api for
+    # openai/ models (on the assumption that they are new models and OpenAI prefers
+    # the responses API) but completions for other models (on the assumption that they
+    # are other models routing through the OpenAI completions API)
+    if model_id.startswith("openai/"):
+        return "responses"
+    else:
+        return "completions"
+
+
+class OpenAIRoutedCompletionsProvider(OpenAICompletionsProvider):
+    """OpenAI completions client that reports provider_id as 'openai'."""
+
+    id = "openai"
+
+
+class OpenAIRoutedResponsesProvider(OpenAIResponsesProvider):
+    """OpenAI responses client that reports provider_id as 'openai'."""
+
+    id = "openai"
+
+
+class OpenAIProvider(BaseProvider[OpenAI]):
+    """Unified provider for OpenAI that routes to Completions or Responses API based on model_id."""
+
+    id = "openai"
+    default_scope = "openai/"
+
+    def __init__(
+        self, *, api_key: str | None = None, base_url: str | None = None
+    ) -> None:
+        """Initialize the OpenAI provider with both subclients."""
+        self._completions_provider = OpenAIRoutedCompletionsProvider(
+            api_key=api_key, base_url=base_url
+        )
+        self._responses_provider = OpenAIRoutedResponsesProvider(
+            api_key=api_key, base_url=base_url
+        )
+        # Use completions client's underlying OpenAI client as the main one
+        self.client = self._completions_provider.client
+
+    def _choose_subprovider(
+        self, model_id: OpenAIModelId, messages: Sequence[Message]
+    ) -> OpenAICompletionsProvider | OpenAIResponsesProvider:
+        """Choose the appropriate provider based on model_id and messages.
+
+        Args:
+            model_id: The model identifier.
+            messages: The messages to send to the LLM.
+
+        Returns:
+            The responses or completions subclient.
+        """
+        api_mode = choose_api_mode(model_id, messages)
+        if api_mode == "responses":
+            return self._responses_provider
+        return self._completions_provider
+
+    def _call(
+        self,
+        *,
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool] | Toolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> Response | Response[FormattableT]:
+        """Generate an `llm.Response` by synchronously calling the OpenAI 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.
+        """
+        client = self._choose_subprovider(model_id, messages)
+        return client.call(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            **params,
+        )
+
+    def _context_call(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool | ContextTool[DepsT]]
+        | ContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
+        """Generate an `llm.ContextResponse` by synchronously calling the OpenAI API.
+
+        Args:
+            ctx: Context object with dependencies for tools.
+            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.ContextResponse` object containing the LLM-generated content.
+        """
+        client = self._choose_subprovider(model_id, messages)
+        return client.context_call(
+            ctx=ctx,
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            **params,
+        )
+
+    async def _call_async(
+        self,
+        *,
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> AsyncResponse | AsyncResponse[FormattableT]:
+        """Generate an `llm.AsyncResponse` by asynchronously calling the OpenAI 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.
+        """
+        return await self._choose_subprovider(model_id, messages).call_async(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            **params,
+        )
+
+    async def _context_call_async(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
+        | AsyncContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
+        """Generate an `llm.AsyncContextResponse` by asynchronously calling the OpenAI API.
+
+        Args:
+            ctx: Context object with dependencies for tools.
+            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.AsyncContextResponse` object containing the LLM-generated content.
+        """
+        return await self._choose_subprovider(model_id, messages).context_call_async(
+            ctx=ctx,
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            **params,
+        )
+
+    def _stream(
+        self,
+        *,
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool] | Toolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> StreamResponse | StreamResponse[FormattableT]:
+        """Generate an `llm.StreamResponse` by synchronously streaming from the OpenAI 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.StreamResponse` object for iterating over the LLM-generated content.
+        """
+        client = self._choose_subprovider(model_id, messages)
+        return client.stream(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            **params,
+        )
+
+    def _context_stream(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        tools: Sequence[Tool | ContextTool[DepsT]]
+        | ContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> ContextStreamResponse[DepsT] | ContextStreamResponse[DepsT, FormattableT]:
+        """Generate an `llm.ContextStreamResponse` by synchronously streaming from the OpenAI API.
+
+        Args:
+            ctx: Context object with dependencies for tools.
+            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.ContextStreamResponse` object for iterating over the LLM-generated content.
+        """
+        client = self._choose_subprovider(model_id, messages)
+        return client.context_stream(
+            ctx=ctx,
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            **params,
+        )
+
+    async def _stream_async(
+        self,
+        *,
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
+        """Generate an `llm.AsyncStreamResponse` by asynchronously streaming from the OpenAI 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.AsyncStreamResponse` object for asynchronously iterating over the LLM-generated content.
+        """
+        return await self._choose_subprovider(model_id, messages).stream_async(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            **params,
+        )
+
+    async def _context_stream_async(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: OpenAIModelId,
+        messages: Sequence[Message],
+        tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
+        | AsyncContextToolkit[DepsT]
+        | None = None,
+        format: type[FormattableT] | Format[FormattableT] | None = None,
+        **params: Unpack[Params],
+    ) -> (
+        AsyncContextStreamResponse[DepsT]
+        | AsyncContextStreamResponse[DepsT, FormattableT]
+    ):
+        """Generate an `llm.AsyncContextStreamResponse` by asynchronously streaming from the OpenAI API.
+
+        Args:
+            ctx: Context object with dependencies for tools.
+            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.AsyncContextStreamResponse` object for asynchronously iterating over the LLM-generated content.
+        """
+        return await self._choose_subprovider(model_id, messages).context_stream_async(
+            ctx=ctx,
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            **params,
+        )

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

@@ -0,0 +1,21 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .provider import OpenAIResponsesProvider
+else:
+    try:
+        from .provider import OpenAIResponsesProvider
+    except ImportError:  # pragma: no cover
+        from ..._missing_import_stubs import (
+            create_import_error_stub,
+            create_provider_stub,
+        )
+
+        OpenAIResponsesProvider = create_provider_stub(
+            "openai", "OpenAIResponsesProvider"
+        )
+
+
+__all__ = [
+    "OpenAIResponsesProvider",
+]

mirascope/llm/{clients → providers}/openai/responses/_utils/decode.py

@@ -29,8 +29,10 @@ from .....responses import (
     FinishReasonChunk,
     RawMessageChunk,
     RawStreamEventChunk,
+    Usage,
+    UsageDeltaChunk,
 )
-from ..model_ids import OpenAIResponsesModelId
+from ...model_id import OpenAIModelId, model_name
 
 INCOMPLETE_DETAILS_TO_FINISH_REASON = {
     "max_output_tokens": FinishReason.MAX_TOKENS,
@@ -38,6 +40,33 @@ INCOMPLETE_DETAILS_TO_FINISH_REASON = {
 }
 
 
+def _decode_usage(
+    usage: openai_types.ResponseUsage | None,
+) -> Usage | None:
+    """Convert OpenAI ResponseUsage to Mirascope Usage."""
+    if usage is None:  # pragma: no cover
+        return None
+
+    return Usage(
+        input_tokens=usage.input_tokens,
+        output_tokens=usage.output_tokens,
+        cache_read_tokens=(
+            usage.input_tokens_details.cached_tokens
+            if usage.input_tokens_details
+            else None
+        )
+        or 0,
+        cache_write_tokens=0,
+        reasoning_tokens=(
+            usage.output_tokens_details.reasoning_tokens
+            if usage.output_tokens_details
+            else None
+        )
+        or 0,
+        raw=usage,
+    )
+
+
 def _serialize_output_item(
     item: openai_types.ResponseOutputItem,
 ) -> dict[str, Any]:
@@ -47,9 +76,10 @@ def _serialize_output_item(
 
 def decode_response(
     response: openai_types.Response,
-    model_id: OpenAIResponsesModelId,
-) -> tuple[AssistantMessage, FinishReason | None]:
-    """Convert OpenAI Responses Response to mirascope AssistantMessage."""
+    model_id: OpenAIModelId,
+    provider_id: str,
+) -> tuple[AssistantMessage, FinishReason | None, Usage | None]:
+    """Convert OpenAI Responses Response to mirascope AssistantMessage and usage."""
     parts: list[AssistantContentPart] = []
     finish_reason: FinishReason | None = None
     refused = False
@@ -91,14 +121,16 @@ def decode_response(
 
     assistant_message = AssistantMessage(
         content=parts,
-        provider="openai:responses",
+        provider_id=provider_id,
         model_id=model_id,
+        provider_model_name=model_name(model_id, "responses"),
         raw_message=[
             _serialize_output_item(output_item) for output_item in response.output
         ],
     )
 
-    return assistant_message, finish_reason
+    usage = _decode_usage(response.usage)
+    return assistant_message, finish_reason, usage
 
 
 class _OpenAIResponsesChunkProcessor:
@@ -174,6 +206,27 @@ class _OpenAIResponsesChunkProcessor:
                 if self.refusal_encountered:
                     yield FinishReasonChunk(finish_reason=FinishReason.REFUSAL)
 
+                # Emit usage delta if present
+                if event.response.usage:
+                    usage = event.response.usage
+                    yield UsageDeltaChunk(
+                        input_tokens=usage.input_tokens,
+                        output_tokens=usage.output_tokens,
+                        cache_read_tokens=(
+                            usage.input_tokens_details.cached_tokens
+                            if usage.input_tokens_details
+                            else None
+                        )
+                        or 0,
+                        cache_write_tokens=0,
+                        reasoning_tokens=(
+                            usage.output_tokens_details.reasoning_tokens
+                            if usage.output_tokens_details
+                            else None
+                        )
+                        or 0,
+                    )
+
 
 def decode_stream(
     openai_stream: Stream[ResponseStreamEvent],

mirascope/llm/{clients → providers}/openai/responses/_utils/encode.py

@@ -37,11 +37,14 @@ from .....formatting import (
     resolve_format,
 )
 from .....messages import AssistantMessage, Message, UserMessage
-from .....tools import FORMAT_TOOL_NAME, BaseToolkit, ToolSchema
+from .....tools import FORMAT_TOOL_NAME, AnyToolSchema, BaseToolkit
 from ....base import Params, _utils as _base_utils
-from ...shared import _utils as _shared_utils
-from ..model_ids import OpenAIResponsesModelId
-from .model_features import NON_REASONING_MODELS
+from ...model_id import OpenAIModelId, model_name
+from ...model_info import (
+    MODELS_WITHOUT_JSON_OBJECT_SUPPORT,
+    MODELS_WITHOUT_JSON_SCHEMA_SUPPORT,
+    NON_REASONING_MODELS,
+)
 
 
 class ResponseCreateKwargs(TypedDict, total=False):
@@ -107,8 +110,8 @@ def _encode_user_message(
         elif part.type == "audio":
             raise FeatureNotSupportedError(
                 "audio input",
-                "openai:responses",
-                message='provider "openai:responses" does not support audio inputs. Try using "openai:completions" instead',
+                "openai",
+                message='provider "openai" does not support audio inputs when using :responses api. Try appending :completions to your model instead.',
             )
         else:
             raise NotImplementedError(
@@ -163,7 +166,7 @@ def _encode_assistant_message(
 
 
 def _encode_message(
-    message: Message, model_id: OpenAIResponsesModelId, encode_thoughts: bool
+    message: Message, model_id: OpenAIModelId, encode_thoughts: bool
 ) -> ResponseInputParam:
     """Convert a Mirascope Message to OpenAI Responses input items.
 
@@ -179,8 +182,9 @@ def _encode_message(
 
     if (
         message.role == "assistant"
-        and message.provider == "openai:responses"
-        and message.model_id == model_id
+        and message.provider_id in ("openai", "openai:responses")
+        and message.provider_model_name
+        == model_name(model_id=model_id, api_mode="responses")
         and message.raw_message
         and not encode_thoughts
     ):
@@ -192,11 +196,11 @@ def _encode_message(
         return _encode_user_message(message)
 
 
-def _convert_tool_to_function_tool_param(tool: ToolSchema) -> FunctionToolParam:
+def _convert_tool_to_function_tool_param(tool: AnyToolSchema) -> FunctionToolParam:
     """Convert a Mirascope ToolSchema to OpenAI Responses FunctionToolParam."""
     schema_dict = tool.parameters.model_dump(by_alias=True, exclude_none=True)
     schema_dict["type"] = "object"
-    _shared_utils._ensure_additional_properties_false(schema_dict)
+    _base_utils.ensure_additional_properties_false(schema_dict)
 
     return FunctionToolParam(
         type="function",
@@ -219,7 +223,7 @@ def _create_strict_response_format(
         ResponseFormatTextJSONSchemaConfigParam for strict structured outputs
     """
     schema = format.schema.copy()
-    _shared_utils._ensure_additional_properties_false(schema)
+    _base_utils.ensure_additional_properties_false(schema)
 
     response_format: ResponseFormatTextJSONSchemaConfigParam = {
         "type": "json_schema",
@@ -243,23 +247,33 @@ def _compute_reasoning(thinking: bool) -> Reasoning:
 
 def encode_request(
     *,
-    model_id: OpenAIResponsesModelId,
+    model_id: OpenAIModelId,
     messages: Sequence[Message],
-    tools: Sequence[ToolSchema] | BaseToolkit | None,
+    tools: Sequence[AnyToolSchema] | BaseToolkit[AnyToolSchema] | None,
     format: type[FormattableT] | Format[FormattableT] | None,
     params: Params,
 ) -> tuple[Sequence[Message], Format[FormattableT] | None, ResponseCreateKwargs]:
     """Prepares a request for the `OpenAI.responses.create` method."""
+    if model_id.endswith(":completions"):
+        raise FeatureNotSupportedError(
+            feature="completions API",
+            provider_id="openai:responses",
+            model_id=model_id,
+            message=f"Cannot use completions model with responses client: {model_id}",
+        )
+
+    base_model_name = model_name(model_id, None)
+
     kwargs: ResponseCreateKwargs = ResponseCreateKwargs(
         {
-            "model": model_id,
+            "model": base_model_name,
         }
     )
     encode_thoughts = False
 
     with _base_utils.ensure_all_params_accessed(
         params=params,
-        provider="openai:responses",
+        provider_id="openai",
         unsupported_params=["top_k", "seed", "stop_sequences"],
     ) as param_accessor:
         if param_accessor.temperature is not None:
@@ -269,9 +283,9 @@ def encode_request(
         if param_accessor.top_p is not None:
             kwargs["top_p"] = param_accessor.top_p
         if param_accessor.thinking is not None:
-            if model_id in NON_REASONING_MODELS:
+            if base_model_name in NON_REASONING_MODELS:
                 param_accessor.emit_warning_for_unused_param(
-                    "thinking", param_accessor.thinking, "openai:responses", model_id
+                    "thinking", param_accessor.thinking, "openai", model_id
                 )
             else:
                 # Assume model supports reasoning unless explicitly listed as non-reasoning
@@ -283,9 +297,7 @@ def encode_request(
     tools = tools.tools if isinstance(tools, BaseToolkit) else tools or []
     openai_tools = [_convert_tool_to_function_tool_param(tool) for tool in tools]
 
-    model_supports_strict = (
-        model_id not in _shared_utils.MODELS_WITHOUT_JSON_SCHEMA_SUPPORT
-    )
+    model_supports_strict = model_id not in MODELS_WITHOUT_JSON_SCHEMA_SUPPORT
     default_mode = "strict" if model_supports_strict else "tool"
 
     format = resolve_format(format, default_mode=default_mode)
@@ -312,8 +324,7 @@ def encode_request(
                     name=FORMAT_TOOL_NAME,
                 )
         elif (
-            format.mode == "json"
-            and model_id not in _shared_utils.MODELS_WITHOUT_JSON_OBJECT_SUPPORT
+            format.mode == "json" and model_id not in MODELS_WITHOUT_JSON_OBJECT_SUPPORT
         ):
             kwargs["text"] = {"format": ResponseFormatJSONObject(type="json_object")}