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

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

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

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

@@ -0,0 +1,470 @@
+"""OpenAI Responses API client implementation."""
+
+from collections.abc import Sequence
+from typing import Literal
+from typing_extensions import Unpack
+
+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 OpenAIResponsesProvider(BaseProvider[OpenAI]):
+    """The client for the OpenAI Responses API."""
+
+    id = "openai:responses"
+    default_scope = "openai/"
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        wrapped_by_openai_provider: bool = False,
+    ) -> None:
+        """Initialize the OpenAI Responses 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:responses"] = (
+            "openai" if wrapped_by_openai_provider else "openai:responses"
+        )
+
+    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 Responses 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.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        openai_response = self.client.responses.create(**kwargs)
+
+        assistant_message, finish_reason = _utils.decode_response(
+            openai_response, model_id, self.active_provider_id
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return Response(
+            raw=openai_response,
+            provider_id=self.active_provider_id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=tools,
+            input_messages=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 Responses 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.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        openai_response = await self.async_client.responses.create(**kwargs)
+
+        assistant_message, finish_reason = _utils.decode_response(
+            openai_response, model_id, self.active_provider_id
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return AsyncResponse(
+            raw=openai_response,
+            provider_id=self.active_provider_id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=tools,
+            input_messages=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 a `llm.StreamResponse` by synchronously streaming from the OpenAI Responses 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:
+            A `llm.StreamResponse` object containing the LLM-generated content stream.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        openai_stream = self.client.responses.create(
+            **kwargs,
+            stream=True,
+        )
+
+        chunk_iterator = _utils.decode_stream(
+            openai_stream,
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return StreamResponse(
+            provider_id=self.active_provider_id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=tools,
+            input_messages=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 a `llm.AsyncStreamResponse` by asynchronously streaming from the OpenAI Responses 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:
+            A `llm.AsyncStreamResponse` object containing the LLM-generated content stream.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        openai_stream = await self.async_client.responses.create(
+            **kwargs,
+            stream=True,
+        )
+
+        chunk_iterator = _utils.decode_async_stream(
+            openai_stream,
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return AsyncStreamResponse(
+            provider_id=self.active_provider_id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=tools,
+            input_messages=messages,
+            chunk_iterator=chunk_iterator,
+            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] | ContextResponse[DepsT, FormattableT]:
+        """Generate a `llm.ContextResponse` by synchronously calling the OpenAI Responses API with context.
+
+        Args:
+            ctx: The context object containing dependencies.
+            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:
+            A `llm.ContextResponse` object containing the LLM-generated content and context.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        openai_response = self.client.responses.create(**kwargs)
+
+        assistant_message, finish_reason = _utils.decode_response(
+            openai_response, model_id, self.active_provider_id
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return ContextResponse(
+            raw=openai_response,
+            provider_id=self.active_provider_id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=tools,
+            input_messages=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] | AsyncContextResponse[DepsT, FormattableT]:
+        """Generate a `llm.AsyncContextResponse` by asynchronously calling the OpenAI Responses API with context.
+
+        Args:
+            ctx: The context object containing dependencies.
+            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:
+            A `llm.AsyncContextResponse` object containing the LLM-generated content and context.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        openai_response = await self.async_client.responses.create(**kwargs)
+
+        assistant_message, finish_reason = _utils.decode_response(
+            openai_response, model_id, self.active_provider_id
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return AsyncContextResponse(
+            raw=openai_response,
+            provider_id=self.active_provider_id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=tools,
+            input_messages=messages,
+            assistant_message=assistant_message,
+            finish_reason=finish_reason,
+            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 a `llm.ContextStreamResponse` by synchronously streaming from the OpenAI Responses API with context.
+
+        Args:
+            ctx: The context object containing dependencies.
+            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:
+            A `llm.ContextStreamResponse` object containing the LLM-generated content stream and context.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        openai_stream = self.client.responses.create(
+            **kwargs,
+            stream=True,
+        )
+
+        chunk_iterator = _utils.decode_stream(
+            openai_stream,
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return ContextStreamResponse(
+            provider_id=self.active_provider_id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=tools,
+            input_messages=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 a `llm.AsyncContextStreamResponse` by asynchronously streaming from the OpenAI Responses API with context.
+
+        Args:
+            ctx: The context object containing dependencies.
+            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:
+            A `llm.AsyncContextStreamResponse` object containing the LLM-generated content stream and context.
+        """
+        messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+
+        openai_stream = await self.async_client.responses.create(
+            **kwargs,
+            stream=True,
+        )
+
+        chunk_iterator = _utils.decode_async_stream(
+            openai_stream,
+        )
+        provider_model_name = model_name(model_id, "responses")
+
+        return AsyncContextStreamResponse(
+            provider_id=self.active_provider_id,
+            model_id=model_id,
+            provider_model_name=provider_model_name,
+            params=params,
+            tools=tools,
+            input_messages=messages,
+            chunk_iterator=chunk_iterator,
+            format=format,
+        )

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

@@ -1,5 +1,7 @@
 """Shared utils for all OpenAI clients."""
 
+from typing import cast
+
 MODELS_WITHOUT_JSON_SCHEMA_SUPPORT = {
     "chatgpt-4o-latest",
     "gpt-3.5-turbo",
@@ -43,13 +45,15 @@ MODELS_WITHOUT_JSON_OBJECT_SUPPORT = {
 }
 
 
-def _ensure_additional_properties_false(obj: object) -> None:
+def ensure_additional_properties_false(obj: object) -> None:
     """Recursively adds additionalProperties = False to a schema, required by OpenAI API."""
     if isinstance(obj, dict):
+        obj = cast(dict[str, object], obj)
         if obj.get("type") == "object" and "additionalProperties" not in obj:
             obj["additionalProperties"] = False
         for value in obj.values():
-            _ensure_additional_properties_false(value)
+            ensure_additional_properties_false(value)
     elif isinstance(obj, list):
+        obj = cast(list[object], obj)
         for item in obj:
-            _ensure_additional_properties_false(item)
+            ensure_additional_properties_false(item)

mirascope/llm/providers/provider_id.py

@@ -0,0 +1,13 @@
+"""Identifiers for all registered providers."""
+
+from typing import Literal, TypeAlias, get_args
+
+KnownProviderId: TypeAlias = Literal[
+    "anthropic",  # Anthropic provider via AnthropicProvider
+    "google",  # Google provider via GoogleProvider
+    "openai",  # OpenAI provider via OpenAIProvider
+    "mlx",  # Local inference powered by `mlx-lm`, via MLXProvider
+]
+KNOWN_PROVIDER_IDS = get_args(KnownProviderId)
+
+ProviderId = KnownProviderId | str