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

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

@@ -19,11 +19,14 @@ 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 ...shared import _utils as _shared_utils
-from ..model_ids import OpenAICompletionsModelId
-from .model_features import MODEL_FEATURES
+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,
+)
 
 
 class ChatCompletionCreateKwargs(TypedDict, total=False):
@@ -49,7 +52,7 @@ class ChatCompletionCreateKwargs(TypedDict, total=False):
 
 def _encode_user_message(
     message: UserMessage,
-    model_id: OpenAICompletionsModelId,
+    model_id: OpenAIModelId,
 ) -> list[openai_types.ChatCompletionMessageParam]:
     """Convert Mirascope `UserMessage` to a list of OpenAI `ChatCompletionMessageParam`.
 
@@ -98,11 +101,11 @@ def _encode_user_message(
             )
             current_content.append(content)
         elif part.type == "audio":
-            model_status = MODEL_FEATURES.get(model_id)
-            if model_status == "no_audio_support":
+            base_model_name = model_name(model_id, None)
+            if base_model_name in MODELS_WITHOUT_AUDIO_SUPPORT:
                 raise FeatureNotSupportedError(
                     feature="Audio inputs",
-                    provider="openai:completions",
+                    provider_id="openai",
                     message=f"Model '{model_id}' does not support audio inputs.",
                 )
 
@@ -111,7 +114,7 @@ def _encode_user_message(
                 if audio_format not in ("wav", "mp3"):
                     raise FeatureNotSupportedError(
                         feature=f"Audio format: {audio_format}",
-                        provider="openai:completions",
+                        provider_id="openai",
                         message="OpenAI only supports 'wav' and 'mp3' audio formats.",
                     )  # pragma: no cover
                 audio_content = openai_types.ChatCompletionContentPartInputAudioParam(
@@ -141,13 +144,14 @@ def _encode_user_message(
 
 
 def _encode_assistant_message(
-    message: AssistantMessage, model_id: OpenAICompletionsModelId, encode_thoughts: bool
+    message: AssistantMessage, model_id: OpenAIModelId, encode_thoughts: bool
 ) -> openai_types.ChatCompletionAssistantMessageParam:
     """Convert Mirascope `AssistantMessage` to OpenAI `ChatCompletionAssistantMessageParam`."""
 
     if (
-        message.provider == "openai:completions"
-        and message.model_id == model_id
+        message.provider_id in ("openai", "openai:completions")
+        and message.provider_model_name
+        == model_name(model_id=model_id, api_mode="completions")
         and message.raw_message
         and not encode_thoughts
     ):
@@ -188,7 +192,7 @@ def _encode_assistant_message(
     elif text_params:
         content = text_params
 
-    message_params = {
+    message_params: openai_types.ChatCompletionAssistantMessageParam = {
         "role": "assistant",
         "content": content,
     }
@@ -199,7 +203,7 @@ def _encode_assistant_message(
 
 
 def _encode_message(
-    message: Message, model_id: OpenAICompletionsModelId, encode_thoughts: bool
+    message: Message, model_id: OpenAIModelId, encode_thoughts: bool
 ) -> list[openai_types.ChatCompletionMessageParam]:
     """Convert a Mirascope `Message` to OpenAI `ChatCompletionMessageParam` format.
 
@@ -227,12 +231,12 @@ def _encode_message(
 
 @lru_cache(maxsize=128)
 def _convert_tool_to_tool_param(
-    tool: ToolSchema,
+    tool: AnyToolSchema,
 ) -> 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"
-    _shared_utils._ensure_additional_properties_false(schema_dict)
+    _base_utils.ensure_additional_properties_false(schema_dict)
     return openai_types.ChatCompletionToolParam(
         type="function",
         function={
@@ -257,7 +261,7 @@ def _create_strict_response_format(
     """
     schema = format.schema.copy()
 
-    _shared_utils._ensure_additional_properties_false(schema)
+    _base_utils.ensure_additional_properties_false(schema)
 
     json_schema = JSONSchema(
         name=format.name,
@@ -274,23 +278,32 @@ def _create_strict_response_format(
 
 def encode_request(
     *,
-    model_id: OpenAICompletionsModelId,
+    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, 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": model_id,
+            "model": base_model_name,
         }
     )
     encode_thoughts = False
 
     with _base_utils.ensure_all_params_accessed(
         params=params,
-        provider="openai:completions",
+        provider_id="openai",
         unsupported_params=["top_k", "thinking"],
     ) as param_accessor:
         if param_accessor.temperature is not None:
@@ -311,9 +324,7 @@ def encode_request(
 
     openai_tools = [_convert_tool_to_tool_param(tool) for tool in tools]
 
-    model_supports_strict = (
-        model_id not in _shared_utils.MODELS_WITHOUT_JSON_SCHEMA_SUPPORT
-    )
+    model_supports_strict = base_model_name not in 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:
@@ -321,7 +332,7 @@ def encode_request(
             if not model_supports_strict:
                 raise FormattingModeNotSupportedError(
                     formatting_mode="strict",
-                    provider="openai:completions",
+                    provider_id="openai",
                     model_id=model_id,
                 )
             kwargs["response_format"] = _create_strict_response_format(format)
@@ -338,7 +349,7 @@ def encode_request(
             openai_tools.append(_convert_tool_to_tool_param(format_tool_schema))
         elif (
             format.mode == "json"
-            and model_id not in _shared_utils.MODELS_WITHOUT_JSON_OBJECT_SUPPORT
+            and base_model_name not in MODELS_WITHOUT_JSON_OBJECT_SUPPORT
         ):
             kwargs["response_format"] = {"type": "json_object"}
 

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

@@ -0,0 +1,513 @@
+"""Base class for OpenAI Completions-compatible providers."""
+
+import os
+from collections.abc import Sequence
+from typing import ClassVar
+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 model_name as openai_model_name
+from . import _utils
+
+
+class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
+    """Base class for providers that use OpenAI Completions-compatible APIs."""
+
+    id: ClassVar[str]
+    default_scope: ClassVar[str | list[str]]
+    default_base_url: ClassVar[str | None] = None
+    api_key_env_var: ClassVar[str]
+    api_key_required: ClassVar[bool] = True
+    provider_name: ClassVar[str | None] = None
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+    ) -> None:
+        """Initialize the OpenAI Completions-compatible provider client."""
+        resolved_api_key = api_key or os.environ.get(self.api_key_env_var)
+
+        if self.api_key_required and not resolved_api_key:
+            name = self.provider_name or self.id.split(":")[0].capitalize()
+            raise ValueError(
+                f"{name} API key is required. "
+                f"Set the {self.api_key_env_var} environment variable "
+                f"or pass the api_key parameter to register_provider()."
+            )
+
+        resolved_base_url = base_url or self.default_base_url
+
+        effective_api_key: str | None = resolved_api_key
+        if resolved_base_url is not None and not effective_api_key:
+            effective_api_key = "not-needed"
+
+        self.client = OpenAI(
+            api_key=effective_api_key,
+            base_url=resolved_base_url,
+        )
+        self.async_client = AsyncOpenAI(
+            api_key=effective_api_key,
+            base_url=resolved_base_url,
+        )
+
+    def _model_name(self, model_id: str) -> str:
+        """Extract the model name to send to the API."""
+        return openai_model_name(model_id, None)
+
+    def _provider_model_name(self, model_id: str) -> str:
+        """Get the model name for tracking in Response."""
+        return self._model_name(model_id)
+
+    def _call(
+        self,
+        *,
+        model_id: str,
+        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 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,
+        )
+        kwargs["model"] = self._model_name(model_id)
+
+        openai_response = self.client.chat.completions.create(**kwargs)
+
+        assistant_message, finish_reason, usage = _utils.decode_response(
+            openai_response,
+            model_id,
+            self.id,
+            self._provider_model_name(model_id),
+        )
+
+        return Response(
+            raw=openai_response,
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=self._provider_model_name(model_id),
+            params=params,
+            tools=tools,
+            input_messages=input_messages,
+            assistant_message=assistant_message,
+            finish_reason=finish_reason,
+            usage=usage,
+            format=format,
+        )
+
+    def _context_call(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: str,
+        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 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,
+        )
+        kwargs["model"] = self._model_name(model_id)
+
+        openai_response = self.client.chat.completions.create(**kwargs)
+
+        assistant_message, finish_reason, usage = _utils.decode_response(
+            openai_response,
+            model_id,
+            self.id,
+            self._provider_model_name(model_id),
+        )
+
+        return ContextResponse(
+            raw=openai_response,
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=self._provider_model_name(model_id),
+            params=params,
+            tools=tools,
+            input_messages=input_messages,
+            assistant_message=assistant_message,
+            finish_reason=finish_reason,
+            usage=usage,
+            format=format,
+        )
+
+    async def _call_async(
+        self,
+        *,
+        model_id: str,
+        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 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,
+        )
+        kwargs["model"] = self._model_name(model_id)
+
+        openai_response = await self.async_client.chat.completions.create(**kwargs)
+
+        assistant_message, finish_reason, usage = _utils.decode_response(
+            openai_response,
+            model_id,
+            self.id,
+            self._provider_model_name(model_id),
+        )
+
+        return AsyncResponse(
+            raw=openai_response,
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=self._provider_model_name(model_id),
+            params=params,
+            tools=tools,
+            input_messages=input_messages,
+            assistant_message=assistant_message,
+            finish_reason=finish_reason,
+            usage=usage,
+            format=format,
+        )
+
+    async def _context_call_async(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: str,
+        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 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,
+        )
+        kwargs["model"] = self._model_name(model_id)
+
+        openai_response = await self.async_client.chat.completions.create(**kwargs)
+
+        assistant_message, finish_reason, usage = _utils.decode_response(
+            openai_response,
+            model_id,
+            self.id,
+            self._provider_model_name(model_id),
+        )
+
+        return AsyncContextResponse(
+            raw=openai_response,
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=self._provider_model_name(model_id),
+            params=params,
+            tools=tools,
+            input_messages=input_messages,
+            assistant_message=assistant_message,
+            finish_reason=finish_reason,
+            usage=usage,
+            format=format,
+        )
+
+    def _stream(
+        self,
+        *,
+        model_id: str,
+        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 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.
+        """
+        input_messages, format, kwargs = _utils.encode_request(
+            model_id=model_id,
+            messages=messages,
+            tools=tools,
+            format=format,
+            params=params,
+        )
+        kwargs["model"] = self._model_name(model_id)
+
+        openai_stream = self.client.chat.completions.create(
+            **kwargs,
+            stream=True,
+            stream_options={"include_usage": True},
+        )
+
+        chunk_iterator = _utils.decode_stream(openai_stream)
+
+        return StreamResponse(
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=self._provider_model_name(model_id),
+            params=params,
+            tools=tools,
+            input_messages=input_messages,
+            chunk_iterator=chunk_iterator,
+            format=format,
+        )
+
+    def _context_stream(
+        self,
+        *,
+        ctx: Context[DepsT],
+        model_id: str,
+        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 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,
+        )
+        kwargs["model"] = self._model_name(model_id)
+
+        openai_stream = self.client.chat.completions.create(
+            **kwargs,
+            stream=True,
+            stream_options={"include_usage": True},
+        )
+
+        chunk_iterator = _utils.decode_stream(openai_stream)
+
+        return ContextStreamResponse(
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=self._provider_model_name(model_id),
+            params=params,
+            tools=tools,
+            input_messages=input_messages,
+            chunk_iterator=chunk_iterator,
+            format=format,
+        )
+
+    async def _stream_async(
+        self,
+        *,
+        model_id: str,
+        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 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 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,
+        )
+        kwargs["model"] = self._model_name(model_id)
+
+        openai_stream = await self.async_client.chat.completions.create(
+            **kwargs,
+            stream=True,
+            stream_options={"include_usage": True},
+        )
+
+        chunk_iterator = _utils.decode_async_stream(openai_stream)
+
+        return AsyncStreamResponse(
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=self._provider_model_name(model_id),
+            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: str,
+        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 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 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,
+        )
+        kwargs["model"] = self._model_name(model_id)
+
+        openai_stream = await self.async_client.chat.completions.create(
+            **kwargs,
+            stream=True,
+            stream_options={"include_usage": True},
+        )
+
+        chunk_iterator = _utils.decode_async_stream(openai_stream)
+
+        return AsyncContextStreamResponse(
+            provider_id=self.id,
+            model_id=model_id,
+            provider_model_name=self._provider_model_name(model_id),
+            params=params,
+            tools=tools,
+            input_messages=input_messages,
+            chunk_iterator=chunk_iterator,
+            format=format,
+        )