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

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

@@ -1,456 +1,22 @@
-"""OpenAI client implementation."""
+"""OpenAI Completions API provider implementation."""
 
-from collections.abc import Sequence
-from typing import Literal
-from typing_extensions import Unpack
+from ..model_id import model_name
+from .base_provider import BaseOpenAICompletionsProvider
 
-from openai import AsyncOpenAI, 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 ..model_id import OpenAIModelId, model_name
-from . import _utils
-
-
-class OpenAICompletionsProvider(BaseProvider[OpenAI]):
-    """The client for the OpenAI LLM model."""
+class OpenAICompletionsProvider(BaseOpenAICompletionsProvider):
+    """Provider for OpenAI's ChatCompletions API."""
 
     id = "openai:completions"
     default_scope = "openai/"
+    default_base_url = None
+    api_key_env_var = "OPENAI_API_KEY"
+    api_key_required = False
+    provider_name = "OpenAI"
 
-    def __init__(
-        self,
-        *,
-        api_key: str | None = None,
-        base_url: str | None = None,
-        wrapped_by_openai_provider: bool = False,
-    ) -> None:
-        """Initialize the OpenAI client."""
-        self.client = OpenAI(api_key=api_key, base_url=base_url)
-        self.async_client = AsyncOpenAI(api_key=api_key, base_url=base_url)
-        self.active_provider_id: Literal["openai", "openai:completions"] = (
-            "openai" if wrapped_by_openai_provider else "openai:completions"
-        )
-
-    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 ChatCompletions 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.
-        """
-        input_messages, format, kwargs = _utils.encode_request(
-            model_id=model_id,
-            messages=messages,
-            tools=tools,
-            format=format,
-            params=params,
-        )
-
-        openai_response = self.client.chat.completions.create(**kwargs)
-
-        assistant_message, finish_reason = _utils.decode_response(
-            openai_response, model_id, self.active_provider_id
-        )
-
-        return Response(
-            raw=openai_response,
-            provider_id=self.active_provider_id,
-            model_id=model_id,
-            provider_model_name=model_name(model_id, "completions"),
-            params=params,
-            tools=tools,
-            input_messages=input_messages,
-            assistant_message=assistant_message,
-            finish_reason=finish_reason,
-            format=format,
-        )
-
-    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 ChatCompletions 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.
-        """
-        input_messages, format, kwargs = _utils.encode_request(
-            model_id=model_id,
-            messages=messages,
-            tools=tools,
-            format=format,
-            params=params,
-        )
-
-        openai_response = self.client.chat.completions.create(**kwargs)
-
-        assistant_message, finish_reason = _utils.decode_response(
-            openai_response, model_id, self.active_provider_id
-        )
-
-        return ContextResponse(
-            raw=openai_response,
-            provider_id=self.active_provider_id,
-            model_id=model_id,
-            provider_model_name=model_name(model_id, "completions"),
-            params=params,
-            tools=tools,
-            input_messages=input_messages,
-            assistant_message=assistant_message,
-            finish_reason=finish_reason,
-            format=format,
-        )
-
-    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 ChatCompletions 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.
-        """
-
-        input_messages, format, kwargs = _utils.encode_request(
-            model_id=model_id,
-            params=params,
-            messages=messages,
-            tools=tools,
-            format=format,
-        )
-
-        openai_response = await self.async_client.chat.completions.create(**kwargs)
-
-        assistant_message, finish_reason = _utils.decode_response(
-            openai_response, model_id, self.active_provider_id
-        )
-
-        return AsyncResponse(
-            raw=openai_response,
-            provider_id=self.active_provider_id,
-            model_id=model_id,
-            provider_model_name=model_name(model_id, "completions"),
-            params=params,
-            tools=tools,
-            input_messages=input_messages,
-            assistant_message=assistant_message,
-            finish_reason=finish_reason,
-            format=format,
-        )
-
-    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 ChatCompletions 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.
-        """
-        input_messages, format, kwargs = _utils.encode_request(
-            model_id=model_id,
-            params=params,
-            messages=messages,
-            tools=tools,
-            format=format,
-        )
-
-        openai_response = await self.async_client.chat.completions.create(**kwargs)
+    def _provider_model_name(self, model_id: str) -> str:
+        """Get the model name for tracking in Response.
 
-        assistant_message, finish_reason = _utils.decode_response(
-            openai_response, model_id, self.active_provider_id
-        )
-
-        return AsyncContextResponse(
-            raw=openai_response,
-            provider_id=self.active_provider_id,
-            model_id=model_id,
-            provider_model_name=model_name(model_id, "completions"),
-            params=params,
-            tools=tools,
-            input_messages=input_messages,
-            assistant_message=assistant_message,
-            finish_reason=finish_reason,
-            format=format,
-        )
-
-    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 ChatCompletions 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.
+        Returns the model name with :completions suffix for tracking which API was used.
         """
-        input_messages, format, kwargs = _utils.encode_request(
-            model_id=model_id,
-            messages=messages,
-            tools=tools,
-            format=format,
-            params=params,
-        )
-
-        openai_stream = self.client.chat.completions.create(
-            **kwargs,
-            stream=True,
-        )
-
-        chunk_iterator = _utils.decode_stream(openai_stream)
-
-        return StreamResponse(
-            provider_id=self.active_provider_id,
-            model_id=model_id,
-            provider_model_name=model_name(model_id, "completions"),
-            params=params,
-            tools=tools,
-            input_messages=input_messages,
-            chunk_iterator=chunk_iterator,
-            format=format,
-        )
-
-    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 ChatCompletions 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.
-        """
-        input_messages, format, kwargs = _utils.encode_request(
-            model_id=model_id,
-            messages=messages,
-            tools=tools,
-            format=format,
-            params=params,
-        )
-
-        openai_stream = self.client.chat.completions.create(
-            **kwargs,
-            stream=True,
-        )
-
-        chunk_iterator = _utils.decode_stream(openai_stream)
-
-        return ContextStreamResponse(
-            provider_id=self.active_provider_id,
-            model_id=model_id,
-            provider_model_name=model_name(model_id, "completions"),
-            params=params,
-            tools=tools,
-            input_messages=input_messages,
-            chunk_iterator=chunk_iterator,
-            format=format,
-        )
-
-    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 ChatCompletions 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.
-        """
-
-        input_messages, format, kwargs = _utils.encode_request(
-            model_id=model_id,
-            messages=messages,
-            tools=tools,
-            format=format,
-            params=params,
-        )
-
-        openai_stream = await self.async_client.chat.completions.create(
-            **kwargs,
-            stream=True,
-        )
-
-        chunk_iterator = _utils.decode_async_stream(openai_stream)
-
-        return AsyncStreamResponse(
-            provider_id=self.active_provider_id,
-            model_id=model_id,
-            provider_model_name=model_name(model_id, "completions"),
-            params=params,
-            tools=tools,
-            input_messages=input_messages,
-            chunk_iterator=chunk_iterator,
-            format=format,
-        )
-
-    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 ChatCompletions 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.
-        """
-        input_messages, format, kwargs = _utils.encode_request(
-            model_id=model_id,
-            messages=messages,
-            tools=tools,
-            format=format,
-            params=params,
-        )
-
-        openai_stream = await self.async_client.chat.completions.create(
-            **kwargs,
-            stream=True,
-        )
-
-        chunk_iterator = _utils.decode_async_stream(openai_stream)
-
-        return AsyncContextStreamResponse(
-            provider_id=self.active_provider_id,
-            model_id=model_id,
-            provider_model_name=model_name(model_id, "completions"),
-            params=params,
-            tools=tools,
-            input_messages=input_messages,
-            chunk_iterator=chunk_iterator,
-            format=format,
-        )
+        return model_name(model_id, "completions")

mirascope/llm/providers/openai/model_info.py

@@ -131,6 +131,19 @@ OpenAIKnownModels = Literal[
     "openai/gpt-5.1-codex-max:responses",
     "openai/gpt-5.1-codex-mini",
     "openai/gpt-5.1-codex-mini:responses",
+    "openai/gpt-5.2",
+    "openai/gpt-5.2:completions",
+    "openai/gpt-5.2:responses",
+    "openai/gpt-5.2-2025-12-11",
+    "openai/gpt-5.2-2025-12-11:completions",
+    "openai/gpt-5.2-2025-12-11:responses",
+    "openai/gpt-5.2-chat-latest",
+    "openai/gpt-5.2-chat-latest:completions",
+    "openai/gpt-5.2-chat-latest:responses",
+    "openai/gpt-5.2-pro",
+    "openai/gpt-5.2-pro:responses",
+    "openai/gpt-5.2-pro-2025-12-11",
+    "openai/gpt-5.2-pro-2025-12-11:responses",
     "openai/o1",
     "openai/o1:completions",
     "openai/o1:responses",
@@ -168,9 +181,11 @@ OpenAIKnownModels = Literal[
 
 
 MODELS_WITHOUT_AUDIO_SUPPORT: set[str] = {
+    "chatgpt-4o-latest",
     "gpt-3.5-turbo",
     "gpt-3.5-turbo-0125",
     "gpt-3.5-turbo-1106",
+    "gpt-3.5-turbo-16k",
     "gpt-4",
     "gpt-4-0125-preview",
     "gpt-4-0613",
@@ -179,15 +194,19 @@ MODELS_WITHOUT_AUDIO_SUPPORT: set[str] = {
     "gpt-4-turbo-2024-04-09",
     "gpt-4-turbo-preview",
     "gpt-4.1",
+    "gpt-4.1-2025-04-14",
     "gpt-4.1-mini",
+    "gpt-4.1-mini-2025-04-14",
     "gpt-4.1-nano",
     "gpt-4.1-nano-2025-04-14",
     "gpt-4o",
     "gpt-4o-2024-05-13",
     "gpt-4o-2024-08-06",
+    "gpt-4o-2024-11-20",
     "gpt-4o-mini",
     "gpt-4o-mini-2024-07-18",
     "gpt-4o-mini-search-preview",
+    "gpt-4o-mini-search-preview-2025-03-11",
     "gpt-4o-search-preview",
     "gpt-4o-search-preview-2025-03-11",
     "gpt-5",
@@ -200,6 +219,9 @@ MODELS_WITHOUT_AUDIO_SUPPORT: set[str] = {
     "gpt-5-search-api",
     "gpt-5-search-api-2025-10-14",
     "gpt-5.1-chat-latest",
+    "gpt-5.2",
+    "gpt-5.2-2025-12-11",
+    "gpt-5.2-chat-latest",
     "o1",
     "o1-2024-12-17",
     "o3",
@@ -244,3 +266,38 @@ NON_REASONING_MODELS: set[str] = {
 
 Models not in this set are assumed to support reasoning (optimistic default).
 """
+
+MODELS_WITHOUT_JSON_SCHEMA_SUPPORT: set[str] = {
+    "chatgpt-4o-latest",
+    "gpt-3.5-turbo",
+    "gpt-3.5-turbo-0125",
+    "gpt-3.5-turbo-1106",
+    "gpt-3.5-turbo-16k",
+    "gpt-4",
+    "gpt-4-0125-preview",
+    "gpt-4-0613",
+    "gpt-4-1106-preview",
+    "gpt-4-turbo",
+    "gpt-4-turbo-2024-04-09",
+    "gpt-4-turbo-preview",
+    "gpt-4o-2024-05-13",
+}
+"""Models that do not support JSON schema (structured outputs).
+
+Models not in this set are assumed to support JSON schema (optimistic default).
+"""
+
+MODELS_WITHOUT_JSON_OBJECT_SUPPORT: set[str] = {
+    "gpt-4",
+    "gpt-4-0613",
+    "gpt-4o-mini-search-preview",
+    "gpt-4o-mini-search-preview-2025-03-11",
+    "gpt-4o-search-preview",
+    "gpt-4o-search-preview-2025-03-11",
+    "gpt-5-search-api",
+    "gpt-5-search-api-2025-10-14",
+}
+"""Models that do not support JSON object mode.
+
+Models not in this set are assumed to support JSON object mode (optimistic default).
+"""

mirascope/llm/providers/openai/provider.py

@@ -90,6 +90,18 @@ def choose_api_mode(model_id: OpenAIModelId, messages: Sequence[Message]) -> str
         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."""
 
@@ -100,11 +112,11 @@ class OpenAIProvider(BaseProvider[OpenAI]):
         self, *, api_key: str | None = None, base_url: str | None = None
     ) -> None:
         """Initialize the OpenAI provider with both subclients."""
-        self._completions_provider = OpenAICompletionsProvider(
-            api_key=api_key, base_url=base_url, wrapped_by_openai_provider=True
+        self._completions_provider = OpenAIRoutedCompletionsProvider(
+            api_key=api_key, base_url=base_url
         )
-        self._responses_provider = OpenAIResponsesProvider(
-            api_key=api_key, base_url=base_url, wrapped_by_openai_provider=True
+        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

mirascope/llm/providers/openai/responses/_utils/decode.py

@@ -29,6 +29,8 @@ from .....responses import (
     FinishReasonChunk,
     RawMessageChunk,
     RawStreamEventChunk,
+    Usage,
+    UsageDeltaChunk,
 )
 from ...model_id import OpenAIModelId, model_name
 
@@ -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]:
@@ -48,9 +77,9 @@ def _serialize_output_item(
 def decode_response(
     response: openai_types.Response,
     model_id: OpenAIModelId,
-    provider_id: Literal["openai", "openai:responses"],
-) -> tuple[AssistantMessage, FinishReason | None]:
-    """Convert OpenAI Responses Response to mirascope AssistantMessage."""
+    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
@@ -100,7 +129,8 @@ def decode_response(
         ],
     )
 
-    return assistant_message, finish_reason
+    usage = _decode_usage(response.usage)
+    return assistant_message, finish_reason, usage
 
 
 class _OpenAIResponsesChunkProcessor:
@@ -176,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],