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

mirascope/llm/providers/mlx/__init__.py

@@ -1,22 +1,7 @@
 """MLX client implementation."""
 
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from .model_id import MLXModelId
-    from .provider import MLXProvider
-else:
-    try:
-        from .model_id import MLXModelId
-        from .provider import MLXProvider
-    except ImportError:  # pragma: no cover
-        from .._missing_import_stubs import (
-            create_import_error_stub,
-            create_provider_stub,
-        )
-
-        MLXProvider = create_provider_stub("mlx", "MLXProvider")
-        MLXModelId = str
+from .model_id import MLXModelId
+from .provider import MLXProvider
 
 __all__ = [
     "MLXModelId",

mirascope/llm/providers/mlx/_utils.py

@@ -2,14 +2,21 @@ from collections.abc import Callable
 from typing import TypeAlias, TypedDict
 
 import mlx.core as mx
+from huggingface_hub.errors import LocalEntryNotFoundError
 from mlx_lm.generate import GenerationResponse
 from mlx_lm.sample_utils import make_sampler
 
+from ...exceptions import NotFoundError
 from ...responses import FinishReason, Usage
-from ..base import Params, _utils as _base_utils
+from ..base import Params, ProviderErrorMap, _utils as _base_utils
 
 Sampler: TypeAlias = Callable[[mx.array], mx.array]
 
+# Error mapping for MLX provider
+MLX_ERROR_MAP: ProviderErrorMap = {
+    LocalEntryNotFoundError: NotFoundError,
+}
+
 
 class MakeSamplerKwargs(TypedDict, total=False):
     """Keyword arguments to be used for `mlx_lm`-s `make_sampler` function.
@@ -69,7 +76,7 @@ def encode_params(params: Params) -> tuple[int | None, StreamGenerateKwargs]:
     with _base_utils.ensure_all_params_accessed(
         params=params,
         provider_id="mlx",
-        unsupported_params=["stop_sequences", "thinking", "encode_thoughts_as_text"],
+        unsupported_params=["stop_sequences", "thinking"],
     ) as param_accessor:
         if param_accessor.max_tokens is not None:
             kwargs["max_tokens"] = param_accessor.max_tokens

mirascope/llm/providers/mlx/provider.py

@@ -70,6 +70,14 @@ class MLXProvider(BaseProvider[None]):
 
     id = "mlx"
     default_scope = "mlx-community/"
+    error_map = _utils.MLX_ERROR_MAP
+
+    def get_error_status(self, e: Exception) -> int | None:
+        """Extract HTTP status code from MLX exception.
+
+        MLX/HuggingFace Hub exceptions don't have status codes.
+        """
+        return None
 
     def _call(
         self,

mirascope/llm/providers/ollama/__init__.py

@@ -1,18 +1,6 @@
 """Ollama provider implementation."""
 
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from .provider import OllamaProvider
-else:
-    try:
-        from .provider import OllamaProvider
-    except ImportError:  # pragma: no cover
-        from .._missing_import_stubs import (
-            create_provider_stub,
-        )
-
-        OllamaProvider = create_provider_stub("openai", "OllamaProvider")
+from .provider import OllamaProvider
 
 __all__ = [
     "OllamaProvider",

mirascope/llm/providers/openai/__init__.py

@@ -1,6 +1,15 @@
 """OpenAI client implementation."""
 
+from .completions.base_provider import BaseOpenAICompletionsProvider
+from .completions.provider import OpenAICompletionsProvider
 from .model_id import OpenAIModelId
 from .provider import OpenAIProvider
+from .responses.provider import OpenAIResponsesProvider
 
-__all__ = ["OpenAIModelId", "OpenAIProvider"]
+__all__ = [
+    "BaseOpenAICompletionsProvider",
+    "OpenAICompletionsProvider",
+    "OpenAIModelId",
+    "OpenAIProvider",
+    "OpenAIResponsesProvider",
+]

mirascope/llm/providers/openai/_utils/__init__.py

@@ -0,0 +1,5 @@
+"""Shared OpenAI utilities."""
+
+from .errors import OPENAI_ERROR_MAP
+
+__all__ = ["OPENAI_ERROR_MAP"]

mirascope/llm/providers/openai/_utils/errors.py

@@ -0,0 +1,46 @@
+"""OpenAI error handling utilities."""
+
+from openai import (
+    APIConnectionError as OpenAIAPIConnectionError,
+    APIResponseValidationError as OpenAIAPIResponseValidationError,
+    APITimeoutError as OpenAIAPITimeoutError,
+    AuthenticationError as OpenAIAuthenticationError,
+    BadRequestError as OpenAIBadRequestError,
+    ConflictError as OpenAIConflictError,
+    InternalServerError as OpenAIInternalServerError,
+    NotFoundError as OpenAINotFoundError,
+    OpenAIError,
+    PermissionDeniedError as OpenAIPermissionDeniedError,
+    RateLimitError as OpenAIRateLimitError,
+    UnprocessableEntityError as OpenAIUnprocessableEntityError,
+)
+
+from ....exceptions import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ConnectionError,
+    NotFoundError,
+    PermissionError,
+    RateLimitError,
+    ResponseValidationError,
+    ServerError,
+    TimeoutError,
+)
+from ...base import ProviderErrorMap
+
+# Shared error mapping used by OpenAI Responses and Completions providers
+OPENAI_ERROR_MAP: ProviderErrorMap = {
+    OpenAIAuthenticationError: AuthenticationError,
+    OpenAIPermissionDeniedError: PermissionError,
+    OpenAINotFoundError: NotFoundError,
+    OpenAIBadRequestError: BadRequestError,
+    OpenAIUnprocessableEntityError: BadRequestError,
+    OpenAIConflictError: BadRequestError,
+    OpenAIRateLimitError: RateLimitError,
+    OpenAIInternalServerError: ServerError,
+    OpenAIAPITimeoutError: TimeoutError,
+    OpenAIAPIConnectionError: ConnectionError,
+    OpenAIAPIResponseValidationError: ResponseValidationError,
+    OpenAIError: APIError,  # Catch-all for unknown OpenAI errors
+}

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

@@ -1,23 +1,5 @@
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from .base_provider import BaseOpenAICompletionsProvider
-    from .provider import OpenAICompletionsProvider
-else:
-    try:
-        from .base_provider import BaseOpenAICompletionsProvider
-        from .provider import OpenAICompletionsProvider
-    except ImportError:  # pragma: no cover
-        from ..._missing_import_stubs import (
-            create_provider_stub,
-        )
-
-        BaseOpenAICompletionsProvider = create_provider_stub(
-            "openai", "BaseOpenAICompletionsProvider"
-        )
-        OpenAICompletionsProvider = create_provider_stub(
-            "openai", "OpenAICompletionsProvider"
-        )
+from .base_provider import BaseOpenAICompletionsProvider
+from .provider import OpenAICompletionsProvider
 
 __all__ = [
     "BaseOpenAICompletionsProvider",

mirascope/llm/providers/openai/completions/_utils/decode.py

@@ -117,6 +117,7 @@ class _OpenAIChunkProcessor:
     def __init__(self) -> None:
         self.current_content_type: Literal["text", "tool_call"] | None = None
         self.current_tool_index: int | None = None
+        self.current_tool_id: str | None = None
         self.refusal_encountered = False
 
     def process_chunk(self, chunk: openai_types.ChatCompletionChunk) -> ChunkIterator:
@@ -180,7 +181,9 @@ class _OpenAIChunkProcessor:
                     self.current_tool_index is not None
                     and self.current_tool_index < index
                 ):
-                    yield ToolCallEndChunk()
+                    if self.current_tool_id is None:  # pragma: no cover
+                        raise RuntimeError("No current_tool_id for ToolCallChunk")
+                    yield ToolCallEndChunk(id=self.current_tool_id)
                     self.current_tool_index = None
 
                 if self.current_tool_index is None:
@@ -201,15 +204,23 @@ class _OpenAIChunkProcessor:
                         id=tool_id,
                         name=name,
                     )
+                    self.current_tool_id = tool_id
 
                 if tool_call_delta.function and tool_call_delta.function.arguments:
-                    yield ToolCallChunk(delta=tool_call_delta.function.arguments)
+                    if self.current_tool_id is None:  # pragma: no cover
+                        raise RuntimeError("No current_tool_id for ToolCallChunk")
+                    yield ToolCallChunk(
+                        id=self.current_tool_id,
+                        delta=tool_call_delta.function.arguments,
+                    )
 
         if choice.finish_reason:
             if self.current_content_type == "text":
                 yield TextEndChunk()
             elif self.current_content_type == "tool_call":
-                yield ToolCallEndChunk()
+                if self.current_tool_id is None:  # pragma: no cover
+                    raise RuntimeError("No current_tool_id for ToolCallChunk")
+                yield ToolCallEndChunk(id=self.current_tool_id)
             elif self.current_content_type is not None:  # pragma: no cover
                 raise NotImplementedError()
 

mirascope/llm/providers/openai/completions/_utils/encode.py

@@ -15,7 +15,6 @@ from .....exceptions import (
 from .....formatting import (
     Format,
     FormattableT,
-    _utils as _formatting_utils,
     resolve_format,
 )
 from .....messages import AssistantMessage, Message, UserMessage
@@ -144,7 +143,7 @@ def _encode_user_message(
 
 
 def _encode_assistant_message(
-    message: AssistantMessage, model_id: OpenAIModelId, encode_thoughts: bool
+    message: AssistantMessage, model_id: OpenAIModelId, encode_thoughts_as_text: bool
 ) -> openai_types.ChatCompletionAssistantMessageParam:
     """Convert Mirascope `AssistantMessage` to OpenAI `ChatCompletionAssistantMessageParam`."""
 
@@ -153,7 +152,7 @@ def _encode_assistant_message(
         and message.provider_model_name
         == model_name(model_id=model_id, api_mode="completions")
         and message.raw_message
-        and not encode_thoughts
+        and not encode_thoughts_as_text
     ):
         return cast(
             openai_types.ChatCompletionAssistantMessageParam, message.raw_message
@@ -177,7 +176,7 @@ def _encode_assistant_message(
                 )
             )
         elif part.type == "thought":
-            if encode_thoughts:
+            if encode_thoughts_as_text:
                 text_params.append(
                     openai_types.ChatCompletionContentPartTextParam(
                         text="**Thinking:** " + part.thought, type="text"
@@ -203,7 +202,7 @@ def _encode_assistant_message(
 
 
 def _encode_message(
-    message: Message, model_id: OpenAIModelId, encode_thoughts: bool
+    message: Message, model_id: OpenAIModelId, encode_thoughts_as_text: bool
 ) -> list[openai_types.ChatCompletionMessageParam]:
     """Convert a Mirascope `Message` to OpenAI `ChatCompletionMessageParam` format.
 
@@ -224,7 +223,7 @@ def _encode_message(
     elif message.role == "user":
         return _encode_user_message(message, model_id)
     elif message.role == "assistant":
-        return [_encode_assistant_message(message, model_id, encode_thoughts)]
+        return [_encode_assistant_message(message, model_id, encode_thoughts_as_text)]
     else:
         raise ValueError(f"Unsupported role: {message.role}")  # pragma: no cover
 
@@ -299,12 +298,12 @@ def encode_request(
             "model": base_model_name,
         }
     )
-    encode_thoughts = False
+    encode_thoughts_as_text = False
 
     with _base_utils.ensure_all_params_accessed(
         params=params,
         provider_id="openai",
-        unsupported_params=["top_k", "thinking"],
+        unsupported_params=["top_k"],
     ) as param_accessor:
         if param_accessor.temperature is not None:
             kwargs["temperature"] = param_accessor.temperature
@@ -317,8 +316,10 @@ def encode_request(
             kwargs["seed"] = param_accessor.seed
         if param_accessor.stop_sequences is not None:
             kwargs["stop"] = param_accessor.stop_sequences
-        if param_accessor.encode_thoughts_as_text is not None:
-            encode_thoughts = True
+        if param_accessor.thinking is not None:
+            thinking = param_accessor.thinking
+            if thinking.get("encode_thoughts_as_text"):
+                encode_thoughts_as_text = True
 
     tools = tools.tools if isinstance(tools, BaseToolkit) else tools or []
 
@@ -345,7 +346,7 @@ def encode_request(
                     "function": {"name": FORMAT_TOOL_NAME},
                 }
                 kwargs["parallel_tool_calls"] = False
-            format_tool_schema = _formatting_utils.create_tool_schema(format)
+            format_tool_schema = format.create_tool_schema()
             openai_tools.append(_convert_tool_to_tool_param(format_tool_schema))
         elif (
             format.mode == "json"
@@ -363,7 +364,9 @@ def encode_request(
 
     encoded_messages: list[openai_types.ChatCompletionMessageParam] = []
     for message in messages:
-        encoded_messages.extend(_encode_message(message, model_id, encode_thoughts))
+        encoded_messages.extend(
+            _encode_message(message, model_id, encode_thoughts_as_text)
+        )
     kwargs["messages"] = encoded_messages
 
     return messages, format, kwargs

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

@@ -31,6 +31,7 @@ from ....tools import (
     Toolkit,
 )
 from ...base import BaseProvider, Params
+from .. import _utils as _shared_utils
 from ..model_id import model_name as openai_model_name
 from . import _utils
 
@@ -44,6 +45,7 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
     api_key_env_var: ClassVar[str]
     api_key_required: ClassVar[bool] = True
     provider_name: ClassVar[str | None] = None
+    error_map = _shared_utils.OPENAI_ERROR_MAP
 
     def __init__(
         self,
@@ -77,6 +79,10 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             base_url=resolved_base_url,
         )
 
+    def get_error_status(self, e: Exception) -> int | None:
+        """Extract HTTP status code from OpenAI exception."""
+        return getattr(e, "status_code", None)
+
     def _model_name(self, model_id: str) -> str:
         """Extract the model name to send to the API."""
         return openai_model_name(model_id, None)
@@ -114,7 +120,6 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             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(
@@ -171,7 +176,6 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             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(
@@ -224,7 +228,6 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             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(
@@ -281,7 +284,6 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             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(
@@ -334,7 +336,6 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             params=params,
         )
         kwargs["model"] = self._model_name(model_id)
-
         openai_stream = self.client.chat.completions.create(
             **kwargs,
             stream=True,
@@ -436,7 +437,6 @@ class BaseOpenAICompletionsProvider(BaseProvider[OpenAI]):
             params=params,
         )
         kwargs["model"] = self._model_name(model_id)
-
         openai_stream = await self.async_client.chat.completions.create(
             **kwargs,
             stream=True,

mirascope/llm/providers/openai/provider.py

@@ -3,9 +3,10 @@
 from collections.abc import Sequence
 from typing_extensions import Unpack
 
-from openai import OpenAI
+from openai import BadRequestError as OpenAIBadRequestError, OpenAI
 
 from ...context import Context, DepsT
+from ...exceptions import BadRequestError, NotFoundError
 from ...formatting import Format, FormattableT
 from ...messages import Message
 from ...responses import (
@@ -29,6 +30,7 @@ from ...tools import (
     Toolkit,
 )
 from ..base import BaseProvider, Params
+from . import _utils
 from .completions import OpenAICompletionsProvider
 from .model_id import OPENAI_KNOWN_MODELS, OpenAIModelId
 from .responses import OpenAIResponsesProvider
@@ -107,6 +109,13 @@ class OpenAIProvider(BaseProvider[OpenAI]):
 
     id = "openai"
     default_scope = "openai/"
+    # Include special handling for model_not_found from Responses API
+    error_map = {
+        **_utils.OPENAI_ERROR_MAP,
+        OpenAIBadRequestError: lambda e: NotFoundError
+        if hasattr(e, "code") and e.code == "model_not_found"  # pyright: ignore[reportUnknownMemberType, reportAttributeAccessIssue]
+        else BadRequestError,
+    }
 
     def __init__(
         self, *, api_key: str | None = None, base_url: str | None = None
@@ -121,6 +130,10 @@ class OpenAIProvider(BaseProvider[OpenAI]):
         # Use completions client's underlying OpenAI client as the main one
         self.client = self._completions_provider.client
 
+    def get_error_status(self, e: Exception) -> int | None:
+        """Extract HTTP status code from OpenAI exception."""
+        return getattr(e, "status_code", None)  # pragma: no cover
+
     def _choose_subprovider(
         self, model_id: OpenAIModelId, messages: Sequence[Message]
     ) -> OpenAICompletionsProvider | OpenAIResponsesProvider:

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

@@ -1,20 +1,4 @@
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from .provider import OpenAIResponsesProvider
-else:
-    try:
-        from .provider import OpenAIResponsesProvider
-    except ImportError:  # pragma: no cover
-        from ..._missing_import_stubs import (
-            create_import_error_stub,
-            create_provider_stub,
-        )
-
-        OpenAIResponsesProvider = create_provider_stub(
-            "openai", "OpenAIResponsesProvider"
-        )
-
+from .provider import OpenAIResponsesProvider
 
 __all__ = [
     "OpenAIResponsesProvider",

mirascope/llm/providers/openai/responses/_utils/decode.py

@@ -173,9 +173,9 @@ class _OpenAIResponsesChunkProcessor:
                     )
                     self.current_content_type = "tool_call"
             elif event.type == "response.function_call_arguments.delta":
-                yield ToolCallChunk(delta=event.delta)
+                yield ToolCallChunk(id=self.current_tool_call_id, delta=event.delta)
             elif event.type == "response.function_call_arguments.done":
-                yield ToolCallEndChunk()
+                yield ToolCallEndChunk(id=self.current_tool_call_id)
                 self.current_content_type = None
             elif (
                 event.type == "response.reasoning_text.delta"

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

@@ -23,7 +23,7 @@ from openai.types.responses.response_input_param import (
     FunctionCallOutput,
     Message as ResponseInputMessageParam,
 )
-from openai.types.shared_params import Reasoning
+from openai.types.shared_params import Reasoning, ReasoningEffort
 from openai.types.shared_params.response_format_json_object import (
     ResponseFormatJSONObject,
 )
@@ -33,12 +33,11 @@ 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, AnyToolSchema, BaseToolkit
-from ....base import Params, _utils as _base_utils
+from ....base import Params, ThinkingLevel, _utils as _base_utils
 from ...model_id import OpenAIModelId, model_name
 from ...model_info import (
     MODELS_WITHOUT_JSON_OBJECT_SUPPORT,
@@ -46,6 +45,17 @@ from ...model_info import (
     NON_REASONING_MODELS,
 )
 
+# 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",
+}
+
 
 class ResponseCreateKwargs(TypedDict, total=False):
     """Kwargs to the OpenAI `client.responses.create` method."""
@@ -237,12 +247,25 @@ def _create_strict_response_format(
     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 _compute_reasoning(
+    level: ThinkingLevel,
+    include_summaries: bool,
+) -> Reasoning:
+    """Compute the OpenAI `Reasoning` config based on ThinkingConfig.
+
+    Args:
+        level: The thinking level
+        include_summaries: 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_summaries:
+        reasoning["summary"] = "auto"
+
+    return reasoning
 
 
 def encode_request(
@@ -283,16 +306,21 @@ 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:
                 param_accessor.emit_warning_for_unused_param(
-                    "thinking", param_accessor.thinking, "openai", model_id
+                    "thinking", thinking_config, "openai", 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
+                level = thinking_config.get("level")
+                include_summaries = thinking_config.get("include_summaries", True)
+                kwargs["reasoning"] = _compute_reasoning(level, include_summaries)
+
+            # Handle encode_thoughts_as_text from ThinkingConfig
+            if thinking_config.get("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]
@@ -305,9 +333,9 @@ def encode_request(
         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)
+            format_tool_schema = format.create_tool_schema()
             openai_tools.append(
-                _convert_tool_to_function_tool_param(format_tool_shared_utils)
+                _convert_tool_to_function_tool_param(format_tool_schema)
             )
             if tools:
                 kwargs["tool_choice"] = ToolChoiceAllowedParam(