mirascope 2.0.0__py3-none-any.whl → 2.0.0a1__py3-none-any.whl

mirascope/llm/clients/google/model_ids.py

@@ -0,0 +1,15 @@
+"""Google registered LLM models."""
+
+from typing import Literal, TypeAlias
+
+GoogleModelId: TypeAlias = (
+    Literal[
+        "gemini-2.5-pro",
+        "gemini-2.5-flash",
+        "gemini-2.5-flash-lite",
+        "gemini-2.0-flash",
+        "gemini-2.0-flash-lite",
+    ]
+    | str
+)
+"""The Google model ids registered with Mirascope."""

mirascope/llm/clients/openai/__init__.py

@@ -0,0 +1,25 @@
+"""OpenAI client implementation."""
+
+from .completions import (
+    OpenAICompletionsClient,
+    OpenAICompletionsModelId,
+    client as completions_client,
+    get_client as get_completions_client,
+)
+from .responses import (
+    OpenAIResponsesClient,
+    OpenAIResponsesModelId,
+    client as responses_client,
+    get_client as get_responses_client,
+)
+
+__all__ = [
+    "OpenAICompletionsClient",
+    "OpenAICompletionsModelId",
+    "OpenAIResponsesClient",
+    "OpenAIResponsesModelId",
+    "completions_client",
+    "get_completions_client",
+    "get_responses_client",
+    "responses_client",
+]

mirascope/llm/clients/openai/completions/__init__.py

@@ -0,0 +1,28 @@
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .clients import OpenAICompletionsClient, client, get_client
+    from .model_ids import OpenAICompletionsModelId
+else:
+    try:
+        from .clients import OpenAICompletionsClient, client, get_client
+        from .model_ids import OpenAICompletionsModelId
+    except ImportError:  # pragma: no cover
+        from ..._missing_import_stubs import (
+            create_client_stub,
+            create_import_error_stub,
+        )
+
+        OpenAICompletionsClient = create_client_stub(
+            "openai", "OpenAICompletionsClient"
+        )
+        OpenAICompletionsModelId = str
+        client = create_import_error_stub("openai", "OpenAICompletionsClient")
+        get_client = create_import_error_stub("openai", "OpenAICompletionsClient")
+
+__all__ = [
+    "OpenAICompletionsClient",
+    "OpenAICompletionsModelId",
+    "client",
+    "get_client",
+]

mirascope/llm/{providers/google → clients/openai/completions}/_utils/__init__.py

@@ -1,17 +1,13 @@
-from ...base._utils import get_include_thoughts
 from .decode import (
     decode_async_stream,
     decode_response,
     decode_stream,
 )
 from .encode import encode_request
-from .errors import GOOGLE_ERROR_MAP
 
 __all__ = [
-    "GOOGLE_ERROR_MAP",
     "decode_async_stream",
     "decode_response",
     "decode_stream",
     "encode_request",
-    "get_include_thoughts",
 ]

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

@@ -4,7 +4,6 @@ from typing import Literal
 
 from openai import AsyncStream, Stream
 from openai.types import chat as openai_types
-from openai.types.completion_usage import CompletionUsage
 
 from .....content import (
     AssistantContentPart,
@@ -24,10 +23,8 @@ from .....responses import (
     FinishReason,
     FinishReasonChunk,
     RawStreamEventChunk,
-    Usage,
-    UsageDeltaChunk,
 )
-from ...model_id import OpenAIModelId, model_name
+from ..model_ids import OpenAICompletionsModelId
 
 OPENAI_FINISH_REASON_MAP = {
     "length": FinishReason.MAX_TOKENS,
@@ -35,40 +32,11 @@ OPENAI_FINISH_REASON_MAP = {
 }
 
 
-def _decode_usage(
-    usage: CompletionUsage | None,
-) -> Usage | None:
-    """Convert OpenAI CompletionUsage to Mirascope Usage."""
-    if usage is None:  # pragma: no cover
-        return None
-
-    return Usage(
-        input_tokens=usage.prompt_tokens,
-        output_tokens=usage.completion_tokens,
-        cache_read_tokens=(
-            usage.prompt_tokens_details.cached_tokens
-            if usage.prompt_tokens_details
-            else None
-        )
-        or 0,
-        cache_write_tokens=0,
-        reasoning_tokens=(
-            usage.completion_tokens_details.reasoning_tokens
-            if usage.completion_tokens_details
-            else None
-        )
-        or 0,
-        raw=usage,
-    )
-
-
 def decode_response(
     response: openai_types.ChatCompletion,
-    model_id: OpenAIModelId,
-    provider_id: str,
-    provider_model_name: str | None = None,
-) -> tuple[AssistantMessage, FinishReason | None, Usage | None]:
-    """Convert OpenAI ChatCompletion to mirascope AssistantMessage and usage."""
+    model_id: OpenAICompletionsModelId,
+) -> tuple[AssistantMessage, FinishReason | None]:
+    """Convert OpenAI ChatCompletion to mirascope AssistantMessage."""
     choice = response.choices[0]
     message = choice.message
     refused = False
@@ -101,14 +69,12 @@ def decode_response(
 
     assistant_message = AssistantMessage(
         content=parts,
-        provider_id=provider_id,
+        provider="openai:completions",
         model_id=model_id,
-        provider_model_name=provider_model_name or model_name(model_id, "completions"),
         raw_message=message.model_dump(exclude_none=True),
     )
 
-    usage = _decode_usage(response.usage)
-    return assistant_message, finish_reason, usage
+    return assistant_message, finish_reason
 
 
 class _OpenAIChunkProcessor:
@@ -117,33 +83,12 @@ class _OpenAIChunkProcessor:
     def __init__(self) -> None:
         self.current_content_type: Literal["text", "tool_call"] | None = None
         self.current_tool_index: int | None = None
-        self.current_tool_id: str | None = None
         self.refusal_encountered = False
 
     def process_chunk(self, chunk: openai_types.ChatCompletionChunk) -> ChunkIterator:
         """Process a single OpenAI chunk and yield the appropriate content chunks."""
         yield RawStreamEventChunk(raw_stream_event=chunk)
 
-        if chunk.usage:
-            usage = chunk.usage
-            yield UsageDeltaChunk(
-                input_tokens=usage.prompt_tokens,
-                output_tokens=usage.completion_tokens,
-                cache_read_tokens=(
-                    usage.prompt_tokens_details.cached_tokens
-                    if usage.prompt_tokens_details
-                    else None
-                )
-                or 0,
-                cache_write_tokens=0,
-                reasoning_tokens=(
-                    usage.completion_tokens_details.reasoning_tokens
-                    if usage.completion_tokens_details
-                    else None
-                )
-                or 0,
-            )
-
         choice = chunk.choices[0] if chunk.choices else None
         if not choice:
             return  # pragma: no cover
@@ -181,9 +126,7 @@ class _OpenAIChunkProcessor:
                     self.current_tool_index is not None
                     and self.current_tool_index < index
                 ):
-                    if self.current_tool_id is None:  # pragma: no cover
-                        raise RuntimeError("No current_tool_id for ToolCallChunk")
-                    yield ToolCallEndChunk(id=self.current_tool_id)
+                    yield ToolCallEndChunk()
                     self.current_tool_index = None
 
                 if self.current_tool_index is None:
@@ -204,23 +147,15 @@ class _OpenAIChunkProcessor:
                         id=tool_id,
                         name=name,
                     )
-                    self.current_tool_id = tool_id
 
                 if tool_call_delta.function and tool_call_delta.function.arguments:
-                    if self.current_tool_id is None:  # pragma: no cover
-                        raise RuntimeError("No current_tool_id for ToolCallChunk")
-                    yield ToolCallChunk(
-                        id=self.current_tool_id,
-                        delta=tool_call_delta.function.arguments,
-                    )
+                    yield ToolCallChunk(delta=tool_call_delta.function.arguments)
 
         if choice.finish_reason:
             if self.current_content_type == "text":
                 yield TextEndChunk()
             elif self.current_content_type == "tool_call":
-                if self.current_tool_id is None:  # pragma: no cover
-                    raise RuntimeError("No current_tool_id for ToolCallChunk")
-                yield ToolCallEndChunk(id=self.current_tool_id)
+                yield ToolCallEndChunk()
             elif self.current_content_type is not None:  # pragma: no cover
                 raise NotImplementedError()
 

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

@@ -1,29 +1,29 @@
 """OpenAI completions message encoding and request preparation."""
 
-from __future__ import annotations
-
 from collections.abc import Sequence
 from functools import lru_cache
-from typing import TYPE_CHECKING, TypedDict, cast
+from typing import TypedDict, cast
 
 from openai import Omit
 from openai.types import chat as openai_types, shared_params as shared_openai_types
 from openai.types.shared_params.response_format_json_schema import JSONSchema
 
-from .....exceptions import FeatureNotSupportedError
-from .....formatting import Format, FormattableT, OutputParser, resolve_format
-from .....messages import AssistantMessage, Message, UserMessage
-from .....tools import FORMAT_TOOL_NAME, AnyToolSchema, BaseToolkit
-from ....base import _utils as _base_utils
-from ...model_id import OpenAIModelId, model_name
-from ...model_info import (
-    MODELS_WITHOUT_AUDIO_SUPPORT,
-    MODELS_WITHOUT_JSON_OBJECT_SUPPORT,
-    MODELS_WITHOUT_JSON_SCHEMA_SUPPORT,
+from .....exceptions import (
+    FeatureNotSupportedError,
+    FormattingModeNotSupportedError,
 )
-
-if TYPE_CHECKING:
-    from .....models import Params
+from .....formatting import (
+    Format,
+    FormattableT,
+    _utils as _formatting_utils,
+    resolve_format,
+)
+from .....messages import AssistantMessage, Message, UserMessage
+from .....tools import FORMAT_TOOL_NAME, BaseToolkit, ToolSchema
+from ....base import Params, _utils as _base_utils
+from ...shared import _utils as _shared_utils
+from ..model_ids import OpenAICompletionsModelId
+from .model_features import MODEL_FEATURES
 
 
 class ChatCompletionCreateKwargs(TypedDict, total=False):
@@ -49,7 +49,7 @@ class ChatCompletionCreateKwargs(TypedDict, total=False):
 
 def _encode_user_message(
     message: UserMessage,
-    model_id: OpenAIModelId,
+    model_id: OpenAICompletionsModelId,
 ) -> list[openai_types.ChatCompletionMessageParam]:
     """Convert Mirascope `UserMessage` to a list of OpenAI `ChatCompletionMessageParam`.
 
@@ -98,11 +98,11 @@ def _encode_user_message(
             )
             current_content.append(content)
         elif part.type == "audio":
-            base_model_name = model_name(model_id, None)
-            if base_model_name in MODELS_WITHOUT_AUDIO_SUPPORT:
+            model_status = MODEL_FEATURES.get(model_id)
+            if model_status == "no_audio_support":
                 raise FeatureNotSupportedError(
                     feature="Audio inputs",
-                    provider_id="openai",
+                    provider="openai:completions",
                     message=f"Model '{model_id}' does not support audio inputs.",
                 )
 
@@ -111,7 +111,7 @@ def _encode_user_message(
                 if audio_format not in ("wav", "mp3"):
                     raise FeatureNotSupportedError(
                         feature=f"Audio format: {audio_format}",
-                        provider_id="openai",
+                        provider="openai:completions",
                         message="OpenAI only supports 'wav' and 'mp3' audio formats.",
                     )  # pragma: no cover
                 audio_content = openai_types.ChatCompletionContentPartInputAudioParam(
@@ -127,7 +127,7 @@ def _encode_user_message(
             result.append(
                 openai_types.ChatCompletionToolMessageParam(
                     role="tool",
-                    content=str(part.result),
+                    content=str(part.value),
                     tool_call_id=part.id,
                 )
             )
@@ -141,16 +141,15 @@ def _encode_user_message(
 
 
 def _encode_assistant_message(
-    message: AssistantMessage, model_id: OpenAIModelId, encode_thoughts_as_text: bool
+    message: AssistantMessage, model_id: OpenAICompletionsModelId, encode_thoughts: bool
 ) -> openai_types.ChatCompletionAssistantMessageParam:
     """Convert Mirascope `AssistantMessage` to OpenAI `ChatCompletionAssistantMessageParam`."""
 
     if (
-        message.provider_id in ("openai", "openai:completions")
-        and message.provider_model_name
-        == model_name(model_id=model_id, api_mode="completions")
+        message.provider == "openai:completions"
+        and message.model_id == model_id
         and message.raw_message
-        and not encode_thoughts_as_text
+        and not encode_thoughts
     ):
         return cast(
             openai_types.ChatCompletionAssistantMessageParam, message.raw_message
@@ -174,7 +173,7 @@ def _encode_assistant_message(
                 )
             )
         elif part.type == "thought":
-            if encode_thoughts_as_text:
+            if encode_thoughts:
                 text_params.append(
                     openai_types.ChatCompletionContentPartTextParam(
                         text="**Thinking:** " + part.thought, type="text"
@@ -189,7 +188,7 @@ def _encode_assistant_message(
     elif text_params:
         content = text_params
 
-    message_params: openai_types.ChatCompletionAssistantMessageParam = {
+    message_params = {
         "role": "assistant",
         "content": content,
     }
@@ -200,7 +199,7 @@ def _encode_assistant_message(
 
 
 def _encode_message(
-    message: Message, model_id: OpenAIModelId, encode_thoughts_as_text: bool
+    message: Message, model_id: OpenAICompletionsModelId, encode_thoughts: bool
 ) -> list[openai_types.ChatCompletionMessageParam]:
     """Convert a Mirascope `Message` to OpenAI `ChatCompletionMessageParam` format.
 
@@ -221,29 +220,26 @@ def _encode_message(
     elif message.role == "user":
         return _encode_user_message(message, model_id)
     elif message.role == "assistant":
-        return [_encode_assistant_message(message, model_id, encode_thoughts_as_text)]
+        return [_encode_assistant_message(message, model_id, encode_thoughts)]
     else:
         raise ValueError(f"Unsupported role: {message.role}")  # pragma: no cover
 
 
 @lru_cache(maxsize=128)
 def _convert_tool_to_tool_param(
-    tool: AnyToolSchema,
+    tool: ToolSchema,
 ) -> openai_types.ChatCompletionToolParam:
     """Convert a single Mirascope `Tool` to OpenAI ChatCompletionToolParam with caching."""
     schema_dict = tool.parameters.model_dump(by_alias=True, exclude_none=True)
     schema_dict["type"] = "object"
-    _base_utils.ensure_additional_properties_false(schema_dict)
-    strict = True if tool.strict is None else tool.strict
-    if strict:
-        _base_utils.ensure_all_properties_required(schema_dict)
+    _shared_utils._ensure_additional_properties_false(schema_dict)
     return openai_types.ChatCompletionToolParam(
         type="function",
         function={
             "name": tool.name,
             "description": tool.description,
             "parameters": schema_dict,
-            "strict": strict,
+            "strict": tool.strict,
         },
     )
 
@@ -261,7 +257,7 @@ def _create_strict_response_format(
     """
     schema = format.schema.copy()
 
-    _base_utils.ensure_additional_properties_false(schema)
+    _shared_utils._ensure_additional_properties_false(schema)
 
     json_schema = JSONSchema(
         name=format.name,
@@ -278,36 +274,24 @@ def _create_strict_response_format(
 
 def encode_request(
     *,
-    model_id: OpenAIModelId,
+    model_id: OpenAICompletionsModelId,
     messages: Sequence[Message],
-    tools: Sequence[AnyToolSchema] | BaseToolkit[AnyToolSchema] | None,
-    format: type[FormattableT]
-    | Format[FormattableT]
-    | OutputParser[FormattableT]
-    | None,
+    tools: Sequence[ToolSchema] | BaseToolkit | None,
+    format: type[FormattableT] | Format[FormattableT] | None,
     params: Params,
 ) -> tuple[Sequence[Message], Format[FormattableT] | None, ChatCompletionCreateKwargs]:
     """Prepares a request for the `OpenAI.chat.completions.create` method."""
-    if model_id.endswith(":responses"):
-        raise FeatureNotSupportedError(
-            feature="responses API",
-            provider_id="openai:completions",
-            model_id=model_id,
-            message=f"Can't use completions client for responses model: {model_id}",
-        )
-    base_model_name = model_name(model_id, None)
-
     kwargs: ChatCompletionCreateKwargs = ChatCompletionCreateKwargs(
         {
-            "model": base_model_name,
+            "model": model_id,
         }
     )
-    encode_thoughts_as_text = False
+    encode_thoughts = False
 
     with _base_utils.ensure_all_params_accessed(
         params=params,
-        provider_id="openai",
-        unsupported_params=["top_k"],
+        provider="openai:completions",
+        unsupported_params=["top_k", "thinking"],
     ) as param_accessor:
         if param_accessor.temperature is not None:
             kwargs["temperature"] = param_accessor.temperature
@@ -320,24 +304,24 @@ def encode_request(
             kwargs["seed"] = param_accessor.seed
         if param_accessor.stop_sequences is not None:
             kwargs["stop"] = param_accessor.stop_sequences
-        if param_accessor.thinking is not None:
-            thinking = param_accessor.thinking
-            if thinking.get("encode_thoughts_as_text"):
-                encode_thoughts_as_text = True
+        if param_accessor.encode_thoughts_as_text is not None:
+            encode_thoughts = True
 
     tools = tools.tools if isinstance(tools, BaseToolkit) else tools or []
 
     openai_tools = [_convert_tool_to_tool_param(tool) for tool in tools]
 
-    model_supports_strict = base_model_name not in MODELS_WITHOUT_JSON_SCHEMA_SUPPORT
+    model_supports_strict = (
+        model_id not in _shared_utils.MODELS_WITHOUT_JSON_SCHEMA_SUPPORT
+    )
     default_mode = "strict" if model_supports_strict else "tool"
     format = resolve_format(format, default_mode=default_mode)
     if format is not None:
         if format.mode == "strict":
             if not model_supports_strict:
-                raise FeatureNotSupportedError(
-                    feature="formatting_mode:strict",
-                    provider_id="openai",
+                raise FormattingModeNotSupportedError(
+                    formatting_mode="strict",
+                    provider="openai:completions",
                     model_id=model_id,
                 )
             kwargs["response_format"] = _create_strict_response_format(format)
@@ -350,11 +334,11 @@ def encode_request(
                     "function": {"name": FORMAT_TOOL_NAME},
                 }
                 kwargs["parallel_tool_calls"] = False
-            format_tool_schema = format.create_tool_schema()
+            format_tool_schema = _formatting_utils.create_tool_schema(format)
             openai_tools.append(_convert_tool_to_tool_param(format_tool_schema))
         elif (
             format.mode == "json"
-            and base_model_name not in MODELS_WITHOUT_JSON_OBJECT_SUPPORT
+            and model_id not in _shared_utils.MODELS_WITHOUT_JSON_OBJECT_SUPPORT
         ):
             kwargs["response_format"] = {"type": "json_object"}
 
@@ -368,9 +352,7 @@ def encode_request(
 
     encoded_messages: list[openai_types.ChatCompletionMessageParam] = []
     for message in messages:
-        encoded_messages.extend(
-            _encode_message(message, model_id, encode_thoughts_as_text)
-        )
+        encoded_messages.extend(_encode_message(message, model_id, encode_thoughts))
     kwargs["messages"] = encoded_messages
 
     return messages, format, kwargs

mirascope/llm/clients/openai/completions/_utils/model_features.py

@@ -0,0 +1,81 @@
+"""OpenAI ChatCompletions models categorized by audio support.
+
+This file is auto-generated by scripts/update_openai_completions_model_features.py
+Run that script to update this map when OpenAI releases new models.
+"""
+
+from typing import Literal
+
+AudioFeatureSupport = Literal["supports_audio", "no_audio_support", "unavailable"]
+
+MODEL_FEATURES: dict[str, AudioFeatureSupport] = {
+    "chatgpt-4o-latest": "no_audio_support",
+    "codex-mini-latest": "unavailable",
+    "gpt-3.5-turbo": "no_audio_support",
+    "gpt-3.5-turbo-0125": "no_audio_support",
+    "gpt-3.5-turbo-0301": "unavailable",
+    "gpt-3.5-turbo-0613": "unavailable",
+    "gpt-3.5-turbo-1106": "no_audio_support",
+    "gpt-3.5-turbo-16k": "no_audio_support",
+    "gpt-3.5-turbo-16k-0613": "unavailable",
+    "gpt-4": "no_audio_support",
+    "gpt-4-0125-preview": "no_audio_support",
+    "gpt-4-0314": "unavailable",
+    "gpt-4-0613": "no_audio_support",
+    "gpt-4-1106-preview": "no_audio_support",
+    "gpt-4-32k": "unavailable",
+    "gpt-4-32k-0314": "unavailable",
+    "gpt-4-32k-0613": "unavailable",
+    "gpt-4-turbo": "no_audio_support",
+    "gpt-4-turbo-2024-04-09": "no_audio_support",
+    "gpt-4-turbo-preview": "no_audio_support",
+    "gpt-4-vision-preview": "unavailable",
+    "gpt-4.1": "no_audio_support",
+    "gpt-4.1-2025-04-14": "no_audio_support",
+    "gpt-4.1-mini": "no_audio_support",
+    "gpt-4.1-mini-2025-04-14": "no_audio_support",
+    "gpt-4.1-nano": "no_audio_support",
+    "gpt-4.1-nano-2025-04-14": "no_audio_support",
+    "gpt-4o": "no_audio_support",
+    "gpt-4o-2024-05-13": "no_audio_support",
+    "gpt-4o-2024-08-06": "no_audio_support",
+    "gpt-4o-2024-11-20": "no_audio_support",
+    "gpt-4o-audio-preview": "supports_audio",
+    "gpt-4o-audio-preview-2024-10-01": "supports_audio",
+    "gpt-4o-audio-preview-2024-12-17": "supports_audio",
+    "gpt-4o-audio-preview-2025-06-03": "supports_audio",
+    "gpt-4o-mini": "no_audio_support",
+    "gpt-4o-mini-2024-07-18": "no_audio_support",
+    "gpt-4o-mini-audio-preview": "supports_audio",
+    "gpt-4o-mini-audio-preview-2024-12-17": "supports_audio",
+    "gpt-4o-mini-search-preview": "no_audio_support",
+    "gpt-4o-mini-search-preview-2025-03-11": "no_audio_support",
+    "gpt-4o-search-preview": "no_audio_support",
+    "gpt-4o-search-preview-2025-03-11": "no_audio_support",
+    "gpt-5": "no_audio_support",
+    "gpt-5-2025-08-07": "no_audio_support",
+    "gpt-5-chat-latest": "no_audio_support",
+    "gpt-5-mini": "no_audio_support",
+    "gpt-5-mini-2025-08-07": "no_audio_support",
+    "gpt-5-nano": "no_audio_support",
+    "gpt-5-nano-2025-08-07": "no_audio_support",
+    "o1": "no_audio_support",
+    "o1-2024-12-17": "no_audio_support",
+    "o1-mini": "no_audio_support",
+    "o1-mini-2024-09-12": "no_audio_support",
+    "o1-preview": "unavailable",
+    "o1-preview-2024-09-12": "unavailable",
+    "o3": "no_audio_support",
+    "o3-2025-04-16": "no_audio_support",
+    "o3-mini": "no_audio_support",
+    "o3-mini-2025-01-31": "no_audio_support",
+    "o4-mini": "no_audio_support",
+    "o4-mini-2025-04-16": "no_audio_support",
+}
+"""Map of model IDs to their status.
+
+- "supports_audio": model exists and supports audio inputs
+- "no_audio_support": model exists but does not support audio inputs
+- "unavailable": model has been deprecated or removed
+- If model not in map: assume it exists and supports audio (optimistic default)
+"""