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

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

@@ -0,0 +1,8 @@
+"""OpenAI ChatCompletions registered LLM models."""
+
+from typing import TypeAlias
+
+from openai.types import ChatModel
+
+OpenAICompletionsModelId: TypeAlias = ChatModel | str
+"""The OpenAI ChatCompletions model ids registered with Mirascope."""

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

@@ -0,0 +1,9 @@
+from .clients import OpenAIResponsesClient, client, get_client
+from .model_ids import OpenAIResponsesModelId
+
+__all__ = [
+    "OpenAIResponsesClient",
+    "OpenAIResponsesModelId",
+    "client",
+    "get_client",
+]

mirascope/llm/clients/openai/responses/_utils/__init__.py

@@ -0,0 +1,13 @@
+from .decode import (
+    decode_async_stream,
+    decode_response,
+    decode_stream,
+)
+from .encode import encode_request
+
+__all__ = [
+    "decode_async_stream",
+    "decode_response",
+    "decode_stream",
+    "encode_request",
+]

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

@@ -29,10 +29,8 @@ from .....responses import (
     FinishReasonChunk,
     RawMessageChunk,
     RawStreamEventChunk,
-    Usage,
-    UsageDeltaChunk,
 )
-from ...model_id import OpenAIModelId, model_name
+from ..model_ids import OpenAIResponsesModelId
 
 INCOMPLETE_DETAILS_TO_FINISH_REASON = {
     "max_output_tokens": FinishReason.MAX_TOKENS,
@@ -40,33 +38,6 @@ 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]:
@@ -76,12 +47,9 @@ def _serialize_output_item(
 
 def decode_response(
     response: openai_types.Response,
-    model_id: OpenAIModelId,
-    provider_id: str,
-    *,
-    include_thoughts: bool,
-) -> tuple[AssistantMessage, FinishReason | None, Usage | None]:
-    """Convert OpenAI Responses Response to mirascope AssistantMessage and usage."""
+    model_id: OpenAIResponsesModelId,
+) -> tuple[AssistantMessage, FinishReason | None]:
+    """Convert OpenAI Responses Response to mirascope AssistantMessage."""
     parts: list[AssistantContentPart] = []
     finish_reason: FinishReason | None = None
     refused = False
@@ -116,9 +84,6 @@ def decode_response(
         else:
             raise NotImplementedError(f"Unsupported output item: {output_item.type}")
 
-    if not include_thoughts:
-        parts = [part for part in parts if part.type != "thought"]
-
     if refused:
         finish_reason = FinishReason.REFUSAL
     elif details := response.incomplete_details:
@@ -126,25 +91,22 @@ def decode_response(
 
     assistant_message = AssistantMessage(
         content=parts,
-        provider_id=provider_id,
+        provider="openai:responses",
         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
         ],
     )
 
-    usage = _decode_usage(response.usage)
-    return assistant_message, finish_reason, usage
+    return assistant_message, finish_reason
 
 
 class _OpenAIResponsesChunkProcessor:
     """Processes OpenAI Responses streaming events and maintains state across chunks."""
 
-    def __init__(self, *, include_thoughts: bool) -> None:
+    def __init__(self) -> None:
         self.current_content_type: Literal["text", "tool_call", "thought"] | None = None
         self.refusal_encountered = False
-        self.include_thoughts = include_thoughts
 
     def process_chunk(self, event: ResponseStreamEvent) -> ChunkIterator:
         """Process a single OpenAI Responses stream event and yield the appropriate content chunks."""
@@ -179,26 +141,23 @@ class _OpenAIResponsesChunkProcessor:
                     )
                     self.current_content_type = "tool_call"
             elif event.type == "response.function_call_arguments.delta":
-                yield ToolCallChunk(id=self.current_tool_call_id, delta=event.delta)
+                yield ToolCallChunk(delta=event.delta)
             elif event.type == "response.function_call_arguments.done":
-                yield ToolCallEndChunk(id=self.current_tool_call_id)
+                yield ToolCallEndChunk()
                 self.current_content_type = None
             elif (
                 event.type == "response.reasoning_text.delta"
                 or event.type == "response.reasoning_summary_text.delta"
             ):
                 if not self.current_content_type:
-                    if self.include_thoughts:
-                        yield ThoughtStartChunk()
+                    yield ThoughtStartChunk()
                     self.current_content_type = "thought"
-                if self.include_thoughts:
-                    yield ThoughtChunk(delta=event.delta)
+                yield ThoughtChunk(delta=event.delta)
             elif (
                 event.type == "response.reasoning_summary_text.done"
                 or event.type == "response.reasoning_text.done"
             ):
-                if self.include_thoughts:
-                    yield ThoughtEndChunk()
+                yield ThoughtEndChunk()
                 self.current_content_type = None
             elif event.type == "response.incomplete":
                 details = event.response.incomplete_details
@@ -215,46 +174,21 @@ 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],
-    *,
-    include_thoughts: bool,
 ) -> ChunkIterator:
     """Returns a ChunkIterator converted from an OpenAI Stream[ResponseStreamEvent]"""
-    processor = _OpenAIResponsesChunkProcessor(include_thoughts=include_thoughts)
+    processor = _OpenAIResponsesChunkProcessor()
     for event in openai_stream:
         yield from processor.process_chunk(event)
 
 
 async def decode_async_stream(
     openai_stream: AsyncStream[ResponseStreamEvent],
-    *,
-    include_thoughts: bool,
 ) -> AsyncChunkIterator:
     """Returns an AsyncChunkIterator converted from an OpenAI AsyncStream[ResponseStreamEvent]"""
-    processor = _OpenAIResponsesChunkProcessor(include_thoughts=include_thoughts)
+    processor = _OpenAIResponsesChunkProcessor()
     async for event in openai_stream:
         for item in processor.process_chunk(event):
             yield item

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

@@ -1,9 +1,7 @@
 """OpenAI Responses message encoding and request preparation."""
 
-from __future__ import annotations
-
 from collections.abc import Sequence
-from typing import TYPE_CHECKING, TypedDict, cast
+from typing import TypedDict, cast
 
 from openai import Omit
 from openai.types.responses import (
@@ -25,7 +23,7 @@ from openai.types.responses.response_input_param import (
     FunctionCallOutput,
     Message as ResponseInputMessageParam,
 )
-from openai.types.shared_params import Reasoning, ReasoningEffort
+from openai.types.shared_params import Reasoning
 from openai.types.shared_params.response_format_json_object import (
     ResponseFormatJSONObject,
 )
@@ -35,32 +33,15 @@ from .....exceptions import FeatureNotSupportedError
 from .....formatting import (
     Format,
     FormattableT,
-    OutputParser,
+    _utils as _formatting_utils,
     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_JSON_OBJECT_SUPPORT,
-    MODELS_WITHOUT_JSON_SCHEMA_SUPPORT,
-    NON_REASONING_MODELS,
-)
-
-if TYPE_CHECKING:
-    from .....models import Params, ThinkingLevel
-
-# Thinking level to a float multiplier % of max tokens
-THINKING_LEVEL_TO_EFFORT: dict[ThinkingLevel, ReasoningEffort] = {
-    "default": "medium",
-    "none": "none",
-    "minimal": "minimal",
-    "low": "low",
-    "medium": "medium",
-    "high": "high",
-    "max": "xhigh",
-}
+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 OpenAIResponsesModelId
+from .model_features import NON_REASONING_MODELS
 
 
 class ResponseCreateKwargs(TypedDict, total=False):
@@ -119,15 +100,15 @@ def _encode_user_message(
             result.append(
                 FunctionCallOutput(
                     call_id=part.id,
-                    output=str(part.result),
+                    output=str(part.value),
                     type="function_call_output",
                 )
             )
         elif part.type == "audio":
             raise FeatureNotSupportedError(
                 "audio input",
-                "openai",
-                message='provider "openai" does not support audio inputs when using :responses api. Try appending :completions to your model instead.',
+                "openai:responses",
+                message='provider "openai:responses" does not support audio inputs. Try using "openai:completions" instead',
             )
         else:
             raise NotImplementedError(
@@ -182,7 +163,7 @@ def _encode_assistant_message(
 
 
 def _encode_message(
-    message: Message, model_id: OpenAIModelId, encode_thoughts: bool
+    message: Message, model_id: OpenAIResponsesModelId, encode_thoughts: bool
 ) -> ResponseInputParam:
     """Convert a Mirascope Message to OpenAI Responses input items.
 
@@ -198,9 +179,8 @@ def _encode_message(
 
     if (
         message.role == "assistant"
-        and message.provider_id in ("openai", "openai:responses")
-        and message.provider_model_name
-        == model_name(model_id=model_id, api_mode="responses")
+        and message.provider == "openai:responses"
+        and message.model_id == model_id
         and message.raw_message
         and not encode_thoughts
     ):
@@ -212,21 +192,18 @@ def _encode_message(
         return _encode_user_message(message)
 
 
-def _convert_tool_to_function_tool_param(tool: AnyToolSchema) -> FunctionToolParam:
+def _convert_tool_to_function_tool_param(tool: ToolSchema) -> 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"
-    _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 FunctionToolParam(
         type="function",
         name=tool.name,
         description=tool.description,
         parameters=schema_dict,
-        strict=strict,
+        strict=tool.strict,
     )
 
 
@@ -242,7 +219,7 @@ def _create_strict_response_format(
         ResponseFormatTextJSONSchemaConfigParam for strict structured outputs
     """
     schema = format.schema.copy()
-    _base_utils.ensure_additional_properties_false(schema)
+    _shared_utils._ensure_additional_properties_false(schema)
 
     response_format: ResponseFormatTextJSONSchemaConfigParam = {
         "type": "json_schema",
@@ -256,59 +233,33 @@ def _create_strict_response_format(
     return response_format
 
 
-def _compute_reasoning(
-    level: ThinkingLevel,
-    include_thoughts: bool,
-) -> Reasoning:
-    """Compute the OpenAI `Reasoning` config based on ThinkingConfig.
-
-    Args:
-        level: The thinking level
-        include_thoughts: Whether to include summary (True/False for auto)
-
-    Returns:
-        OpenAI Reasoning configuration
-    """
-    reasoning: Reasoning = {"effort": THINKING_LEVEL_TO_EFFORT.get(level) or "medium"}
-
-    if include_thoughts:
-        reasoning["summary"] = "auto"
-
-    return reasoning
+def _compute_reasoning(thinking: bool) -> Reasoning:
+    """Compute the OpenAI `Reasoning` config based on thinking settings."""
+    if thinking:
+        return {"effort": "medium", "summary": "auto"}
+    else:
+        return {"effort": "minimal"}
 
 
 def encode_request(
     *,
-    model_id: OpenAIModelId,
+    model_id: OpenAIResponsesModelId,
     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, 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": base_model_name,
+            "model": model_id,
         }
     )
     encode_thoughts = False
 
     with _base_utils.ensure_all_params_accessed(
         params=params,
-        provider_id="openai",
+        provider="openai:responses",
         unsupported_params=["top_k", "seed", "stop_sequences"],
     ) as param_accessor:
         if param_accessor.temperature is not None:
@@ -318,26 +269,23 @@ 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:
-            thinking_config = param_accessor.thinking
-            if base_model_name in NON_REASONING_MODELS:
+            if model_id in NON_REASONING_MODELS:
                 param_accessor.emit_warning_for_unused_param(
-                    "thinking", thinking_config, "openai", model_id
+                    "thinking", param_accessor.thinking, "openai:responses", model_id
                 )
             else:
                 # Assume model supports reasoning unless explicitly listed as non-reasoning
                 # This ensures new reasoning models work immediately without code updates
-                level = thinking_config.get("level")
-                include_thoughts = thinking_config.get("include_thoughts", False)
-                kwargs["reasoning"] = _compute_reasoning(level, include_thoughts)
-
-            # Handle encode_thoughts_as_text from ThinkingConfig
-            if thinking_config.get("encode_thoughts_as_text"):
-                encode_thoughts = True
+                kwargs["reasoning"] = _compute_reasoning(param_accessor.thinking)
+        if param_accessor.encode_thoughts_as_text:
+            encode_thoughts = True
 
     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 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)
@@ -345,9 +293,9 @@ def encode_request(
         if format.mode == "strict":
             kwargs["text"] = {"format": _create_strict_response_format(format)}
         elif format.mode == "tool":
-            format_tool_schema = format.create_tool_schema()
+            format_tool_shared_utils = _formatting_utils.create_tool_schema(format)
             openai_tools.append(
-                _convert_tool_to_function_tool_param(format_tool_schema)
+                _convert_tool_to_function_tool_param(format_tool_shared_utils)
             )
             if tools:
                 kwargs["tool_choice"] = ToolChoiceAllowedParam(
@@ -364,7 +312,8 @@ def encode_request(
                     name=FORMAT_TOOL_NAME,
                 )
         elif (
-            format.mode == "json" and model_id not in MODELS_WITHOUT_JSON_OBJECT_SUPPORT
+            format.mode == "json"
+            and model_id not in _shared_utils.MODELS_WITHOUT_JSON_OBJECT_SUPPORT
         ):
             kwargs["text"] = {"format": ResponseFormatJSONObject(type="json_object")}
 

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

@@ -0,0 +1,87 @@
+"""OpenAI Responses models categorized by reasoning support.
+
+This file is auto-generated by scripts/update_openai_responses_model_features.py
+Run that script to update these sets when OpenAI releases new models.
+"""
+
+REASONING_MODELS: set[str] = {
+    "codex-mini-latest",
+    "gpt-5",
+    "gpt-5-2025-08-07",
+    "gpt-5-mini",
+    "gpt-5-mini-2025-08-07",
+    "gpt-5-nano",
+    "gpt-5-nano-2025-08-07",
+    "o1",
+    "o1-2024-12-17",
+    "o1-pro",
+    "o1-pro-2025-03-19",
+    "o3",
+    "o3-2025-04-16",
+    "o3-mini",
+    "o3-mini-2025-01-31",
+    "o3-pro",
+    "o3-pro-2025-06-10",
+    "o4-mini",
+    "o4-mini-2025-04-16",
+}
+"""Models that have been tested and confirmed to support the reasoning parameter."""
+
+NON_REASONING_MODELS: set[str] = {
+    "chatgpt-4o-latest",
+    "gpt-3.5-turbo",
+    "gpt-3.5-turbo-0125",
+    "gpt-3.5-turbo-1106",
+    "gpt-4",
+    "gpt-4-0125-preview",
+    "gpt-4-0314",
+    "gpt-4-0613",
+    "gpt-4-1106-preview",
+    "gpt-4-turbo",
+    "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-5-chat-latest",
+}
+"""Models that have been tested and confirmed to NOT support the reasoning parameter."""
+
+NON_EXISTENT_MODELS: set[str] = {
+    "gpt-3.5-turbo-0301",
+    "gpt-3.5-turbo-0613",
+    "gpt-3.5-turbo-16k",
+    "gpt-3.5-turbo-16k-0613",
+    "gpt-4-32k",
+    "gpt-4-32k-0314",
+    "gpt-4-32k-0613",
+    "gpt-4-vision-preview",
+}
+"""Models that are listed in OpenAI's types but no longer exist in their API."""
+
+NO_RESPONSES_API_SUPPORT_MODELS: set[str] = {
+    "gpt-4o-audio-preview",
+    "gpt-4o-audio-preview-2024-10-01",
+    "gpt-4o-audio-preview-2024-12-17",
+    "gpt-4o-audio-preview-2025-06-03",
+    "gpt-4o-mini-audio-preview",
+    "gpt-4o-mini-audio-preview-2024-12-17",
+    "gpt-4o-mini-search-preview",
+    "gpt-4o-mini-search-preview-2025-03-11",
+    "gpt-4o-search-preview",
+    "gpt-4o-search-preview-2025-03-11",
+    "o1-mini",
+    "o1-mini-2024-09-12",
+    "o1-preview",
+    "o1-preview-2024-09-12",
+}
+"""Models that do not support the Responses API."""