mirascope 1.25.7__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/clients/openai/responses/_utils/decode.py

@@ -0,0 +1,194 @@
+"""OpenAI Responses response decoding."""
+
+from typing import Any, Literal
+
+from openai import AsyncStream, Stream
+from openai.types import responses as openai_types
+from openai.types.responses.response_stream_event import ResponseStreamEvent
+
+from .....content import (
+    AssistantContentPart,
+    Text,
+    TextChunk,
+    TextEndChunk,
+    TextStartChunk,
+    Thought,
+    ThoughtChunk,
+    ThoughtEndChunk,
+    ThoughtStartChunk,
+    ToolCall,
+    ToolCallChunk,
+    ToolCallEndChunk,
+    ToolCallStartChunk,
+)
+from .....messages import AssistantMessage
+from .....responses import (
+    AsyncChunkIterator,
+    ChunkIterator,
+    FinishReason,
+    FinishReasonChunk,
+    RawMessageChunk,
+    RawStreamEventChunk,
+)
+from ..model_ids import OpenAIResponsesModelId
+
+INCOMPLETE_DETAILS_TO_FINISH_REASON = {
+    "max_output_tokens": FinishReason.MAX_TOKENS,
+    "content_filter": FinishReason.REFUSAL,
+}
+
+
+def _serialize_output_item(
+    item: openai_types.ResponseOutputItem,
+) -> dict[str, Any]:
+    """Returns the item serialized as a dictionary."""
+    return {key: value for key, value in item.model_dump().items() if value is not None}
+
+
+def decode_response(
+    response: openai_types.Response,
+    model_id: OpenAIResponsesModelId,
+) -> tuple[AssistantMessage, FinishReason | None]:
+    """Convert OpenAI Responses Response to mirascope AssistantMessage."""
+    parts: list[AssistantContentPart] = []
+    finish_reason: FinishReason | None = None
+    refused = False
+
+    for output_item in response.output:
+        if output_item.type == "message":
+            for content in output_item.content:
+                if content.type == "output_text":
+                    parts.append(Text(text=content.text))
+                elif content.type == "refusal":
+                    parts.append(Text(text=content.refusal))
+                    refused = True
+        elif output_item.type == "function_call":
+            parts.append(
+                ToolCall(
+                    id=output_item.call_id,
+                    name=output_item.name,
+                    args=output_item.arguments,
+                )
+            )
+        elif output_item.type == "reasoning":
+            for summary_part in output_item.summary:
+                if summary_part.type == "summary_text":
+                    parts.append(Thought(thought=summary_part.text))
+            if output_item.content:  # pragma: no cover
+                # TODO: Add test case covering this
+                # (Likely their open-source models output reasoning_text rather than summaries)
+                for reasoning_content in output_item.content:
+                    if reasoning_content.type == "reasoning_text":
+                        parts.append(Thought(thought=reasoning_content.text))
+
+        else:
+            raise NotImplementedError(f"Unsupported output item: {output_item.type}")
+
+    if refused:
+        finish_reason = FinishReason.REFUSAL
+    elif details := response.incomplete_details:
+        finish_reason = INCOMPLETE_DETAILS_TO_FINISH_REASON.get(details.reason or "")
+
+    assistant_message = AssistantMessage(
+        content=parts,
+        provider="openai:responses",
+        model_id=model_id,
+        raw_message=[
+            _serialize_output_item(output_item) for output_item in response.output
+        ],
+    )
+
+    return assistant_message, finish_reason
+
+
+class _OpenAIResponsesChunkProcessor:
+    """Processes OpenAI Responses streaming events and maintains state across chunks."""
+
+    def __init__(self) -> None:
+        self.current_content_type: Literal["text", "tool_call", "thought"] | None = None
+        self.refusal_encountered = False
+
+    def process_chunk(self, event: ResponseStreamEvent) -> ChunkIterator:
+        """Process a single OpenAI Responses stream event and yield the appropriate content chunks."""
+        yield RawStreamEventChunk(raw_stream_event=event)
+
+        if hasattr(event, "type"):
+            if event.type == "response.output_text.delta":
+                if not self.current_content_type:
+                    yield TextStartChunk()
+                    self.current_content_type = "text"
+                yield TextChunk(delta=event.delta)
+            elif event.type == "response.output_text.done":
+                yield TextEndChunk()
+                self.current_content_type = None
+            if event.type == "response.refusal.delta":
+                if not self.current_content_type:
+                    yield TextStartChunk()
+                    self.current_content_type = "text"
+                yield TextChunk(delta=event.delta)
+            elif event.type == "response.refusal.done":
+                yield TextEndChunk()
+                self.refusal_encountered = True
+                self.current_content_type = None
+            elif event.type == "response.output_item.added":
+                item = event.item
+                if item.type == "function_call":
+                    self.current_tool_call_id = item.call_id
+                    self.current_tool_call_name = item.name
+                    yield ToolCallStartChunk(
+                        id=item.call_id,
+                        name=item.name,
+                    )
+                    self.current_content_type = "tool_call"
+            elif event.type == "response.function_call_arguments.delta":
+                yield ToolCallChunk(delta=event.delta)
+            elif event.type == "response.function_call_arguments.done":
+                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:
+                    yield ThoughtStartChunk()
+                    self.current_content_type = "thought"
+                yield ThoughtChunk(delta=event.delta)
+            elif (
+                event.type == "response.reasoning_summary_text.done"
+                or event.type == "response.reasoning_text.done"
+            ):
+                yield ThoughtEndChunk()
+                self.current_content_type = None
+            elif event.type == "response.incomplete":
+                details = event.response.incomplete_details
+                reason = (details and details.reason) or ""
+                finish_reason = INCOMPLETE_DETAILS_TO_FINISH_REASON.get(reason)
+                if finish_reason:
+                    yield FinishReasonChunk(finish_reason=finish_reason)
+            elif event.type == "response.completed":
+                yield RawMessageChunk(
+                    raw_message=[
+                        _serialize_output_item(item) for item in event.response.output
+                    ]
+                )
+                if self.refusal_encountered:
+                    yield FinishReasonChunk(finish_reason=FinishReason.REFUSAL)
+
+
+def decode_stream(
+    openai_stream: Stream[ResponseStreamEvent],
+) -> ChunkIterator:
+    """Returns a ChunkIterator converted from an OpenAI Stream[ResponseStreamEvent]"""
+    processor = _OpenAIResponsesChunkProcessor()
+    for event in openai_stream:
+        yield from processor.process_chunk(event)
+
+
+async def decode_async_stream(
+    openai_stream: AsyncStream[ResponseStreamEvent],
+) -> AsyncChunkIterator:
+    """Returns an AsyncChunkIterator converted from an OpenAI AsyncStream[ResponseStreamEvent]"""
+    processor = _OpenAIResponsesChunkProcessor()
+    async for event in openai_stream:
+        for item in processor.process_chunk(event):
+            yield item

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

@@ -0,0 +1,333 @@
+"""OpenAI Responses message encoding and request preparation."""
+
+from collections.abc import Sequence
+from typing import TypedDict, cast
+
+from openai import Omit
+from openai.types.responses import (
+    FunctionToolParam,
+    ResponseFormatTextJSONSchemaConfigParam,
+    ResponseFunctionToolCallParam,
+    ResponseInputContentParam,
+    ResponseInputItemParam,
+    ResponseInputParam,
+    ResponseInputTextParam,
+    ResponseTextConfigParam,
+    ToolChoiceAllowedParam,
+    ToolChoiceFunctionParam,
+    response_create_params,
+)
+from openai.types.responses.easy_input_message_param import EasyInputMessageParam
+from openai.types.responses.response_input_image_param import ResponseInputImageParam
+from openai.types.responses.response_input_param import (
+    FunctionCallOutput,
+    Message as ResponseInputMessageParam,
+)
+from openai.types.shared_params import Reasoning
+from openai.types.shared_params.response_format_json_object import (
+    ResponseFormatJSONObject,
+)
+from openai.types.shared_params.responses_model import ResponsesModel
+
+from .....exceptions import FeatureNotSupportedError
+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 OpenAIResponsesModelId
+from .model_features import NON_REASONING_MODELS
+
+
+class ResponseCreateKwargs(TypedDict, total=False):
+    """Kwargs to the OpenAI `client.responses.create` method."""
+
+    model: ResponsesModel
+    input: str | ResponseInputParam
+    instructions: str
+    temperature: float
+    max_output_tokens: int
+    top_p: float
+    tools: list[FunctionToolParam] | Omit
+    tool_choice: response_create_params.ToolChoice | Omit
+    text: ResponseTextConfigParam
+    reasoning: Reasoning | Omit
+
+
+def _encode_user_message(
+    message: UserMessage,
+) -> ResponseInputParam:
+    if len(message.content) == 1 and (first := message.content[0]).type == "text":
+        return [EasyInputMessageParam(content=first.text, role="user")]
+
+    current_content: list[ResponseInputContentParam] = []
+    result: ResponseInputParam = []
+
+    def flush_message_content() -> None:
+        nonlocal current_content
+        if current_content:
+            result.append(
+                ResponseInputMessageParam(
+                    content=current_content, role="user", type="message"
+                )
+            )
+            current_content = []
+
+    for part in message.content:
+        if part.type == "text":
+            current_content.append(
+                ResponseInputTextParam(text=part.text, type="input_text")
+            )
+        elif part.type == "image":
+            image_url = (
+                part.source.url
+                if part.source.type == "url_image_source"
+                else f"data:{part.source.mime_type};base64,{part.source.data}"
+            )
+
+            current_content.append(
+                ResponseInputImageParam(
+                    image_url=image_url, detail="auto", type="input_image"
+                )
+            )
+        elif part.type == "tool_output":
+            flush_message_content()
+            result.append(
+                FunctionCallOutput(
+                    call_id=part.id,
+                    output=str(part.value),
+                    type="function_call_output",
+                )
+            )
+        elif part.type == "audio":
+            raise FeatureNotSupportedError(
+                "audio input",
+                "openai:responses",
+                message='provider "openai:responses" does not support audio inputs. Try using "openai:completions" instead',
+            )
+        else:
+            raise NotImplementedError(
+                f"Unsupported user content part type: {part.type}"
+            )
+    flush_message_content()
+
+    return result
+
+
+def _encode_assistant_message(
+    message: AssistantMessage, encode_thoughts: bool
+) -> ResponseInputParam:
+    result: ResponseInputParam = []
+
+    # Note: OpenAI does not provide any way to encode multiplie pieces of assistant-generated
+    # text as adjacent content within the same Message, except as part of
+    # ResponseOutputMessageParam which requires OpenAI-provided `id` and `status` on the message,
+    # and `annotations` and `logprobs` on the output text.
+    # Rather than generating a fake or nonexistent fields and triggering potentially undefined
+    # server-side behavior, we use `EasyInputMessageParam` for assistant generated text,
+    # with the caveat that assistant messages containing multiple text parts will be encoded
+    # as though they are separate messages.
+    # (It would seem as though the `Message` class in `response_input_param.py` would be suitable,
+    # especially as it supports the "assistant" role; however attempting to use it triggers a server
+    # error when text of type input_text is passed as part of an assistant message.)
+    for part in message.content:
+        if part.type == "text":
+            result.append(EasyInputMessageParam(content=part.text, role="assistant"))
+        elif part.type == "thought":
+            if encode_thoughts:
+                result.append(
+                    EasyInputMessageParam(
+                        content="**Thinking:** " + part.thought, role="assistant"
+                    )
+                )
+        elif part.type == "tool_call":
+            result.append(
+                ResponseFunctionToolCallParam(
+                    call_id=part.id,
+                    name=part.name,
+                    arguments=part.args,
+                    type="function_call",
+                )
+            )
+        else:
+            raise NotImplementedError(
+                f"Unsupported assistant content part type: {part.type}"
+            )
+
+    return result
+
+
+def _encode_message(
+    message: Message, model_id: OpenAIResponsesModelId, encode_thoughts: bool
+) -> ResponseInputParam:
+    """Convert a Mirascope Message to OpenAI Responses input items.
+
+    Returns a list because tool calls and tool outputs become separate input items
+    in the Responses API, not part of message content.
+    """
+
+    if message.role == "system":
+        # Responses API allows multiple "developer" messages, so rather than using the
+        # instructions field, we convert system messages as we find them.
+        # Unlike other LLM APIs, the system message does not need to be the first message.
+        return [EasyInputMessageParam(role="developer", content=message.content.text)]
+
+    if (
+        message.role == "assistant"
+        and message.provider == "openai:responses"
+        and message.model_id == model_id
+        and message.raw_message
+        and not encode_thoughts
+    ):
+        return cast(ResponseInputParam, message.raw_message)
+
+    if message.role == "assistant":
+        return _encode_assistant_message(message, encode_thoughts)
+    else:
+        return _encode_user_message(message)
+
+
+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"
+    _shared_utils._ensure_additional_properties_false(schema_dict)
+
+    return FunctionToolParam(
+        type="function",
+        name=tool.name,
+        description=tool.description,
+        parameters=schema_dict,
+        strict=tool.strict,
+    )
+
+
+def _create_strict_response_format(
+    format: Format[FormattableT],
+) -> ResponseFormatTextJSONSchemaConfigParam:
+    """Create OpenAI Responses strict response format from a Mirascope Format.
+
+    Args:
+        format: The `Format` instance containing schema and metadata
+
+    Returns:
+        ResponseFormatTextJSONSchemaConfigParam for strict structured outputs
+    """
+    schema = format.schema.copy()
+    _shared_utils._ensure_additional_properties_false(schema)
+
+    response_format: ResponseFormatTextJSONSchemaConfigParam = {
+        "type": "json_schema",
+        "name": format.name,
+        "schema": schema,
+    }
+    if format.description:
+        response_format["description"] = format.description
+    response_format["strict"] = True
+
+    return response_format
+
+
+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: OpenAIResponsesModelId,
+    messages: Sequence[Message],
+    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."""
+    kwargs: ResponseCreateKwargs = ResponseCreateKwargs(
+        {
+            "model": model_id,
+        }
+    )
+    encode_thoughts = False
+
+    with _base_utils.ensure_all_params_accessed(
+        params=params,
+        provider="openai:responses",
+        unsupported_params=["top_k", "seed", "stop_sequences"],
+    ) as param_accessor:
+        if param_accessor.temperature is not None:
+            kwargs["temperature"] = param_accessor.temperature
+        if param_accessor.max_tokens is not None:
+            kwargs["max_output_tokens"] = param_accessor.max_tokens
+        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:
+                param_accessor.emit_warning_for_unused_param(
+                    "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
+                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 _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":
+            kwargs["text"] = {"format": _create_strict_response_format(format)}
+        elif format.mode == "tool":
+            format_tool_shared_utils = _formatting_utils.create_tool_schema(format)
+            openai_tools.append(
+                _convert_tool_to_function_tool_param(format_tool_shared_utils)
+            )
+            if tools:
+                kwargs["tool_choice"] = ToolChoiceAllowedParam(
+                    type="allowed_tools",
+                    mode="required",
+                    tools=[
+                        {"type": "function", "name": tool["name"]}
+                        for tool in openai_tools
+                    ],
+                )
+            else:
+                kwargs["tool_choice"] = ToolChoiceFunctionParam(
+                    type="function",
+                    name=FORMAT_TOOL_NAME,
+                )
+        elif (
+            format.mode == "json"
+            and model_id not in _shared_utils.MODELS_WITHOUT_JSON_OBJECT_SUPPORT
+        ):
+            kwargs["text"] = {"format": ResponseFormatJSONObject(type="json_object")}
+
+        if format.formatting_instructions:
+            messages = _base_utils.add_system_instructions(
+                messages, format.formatting_instructions
+            )
+
+    encoded_messages: list[ResponseInputItemParam] = []
+    for message in messages:
+        encoded_messages.extend(_encode_message(message, model_id, encode_thoughts))
+    kwargs["input"] = encoded_messages
+
+    if openai_tools:
+        kwargs["tools"] = openai_tools
+
+    return messages, format, kwargs

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."""