mirascope 2.0.0a5__py3-none-any.whl → 2.0.1__py3-none-any.whl

mirascope/llm/providers/base/base_provider.py

@@ -9,8 +9,8 @@ from typing import TYPE_CHECKING, Any, ClassVar, Generic, TypeAlias, cast, overl
 from typing_extensions import TypeVar, Unpack
 
 from ...context import Context, DepsT
-from ...exceptions import APIError, MirascopeLLMError
-from ...formatting import Format, FormattableT
+from ...exceptions import APIError, ProviderError
+from ...formatting import Format, FormattableT, OutputParser
 from ...messages import Message, UserContent, user
 from ...responses import (
     AsyncChunkIterator,
@@ -34,10 +34,9 @@ from ...tools import (
     Tool,
     Toolkit,
 )
-from .params import Params
 
 if TYPE_CHECKING:
-    from ...exceptions import MirascopeLLMError
+    from ...models import Params
     from ..provider_id import ProviderId
 
 ProviderClientT = TypeVar("ProviderClientT")
@@ -47,7 +46,7 @@ Provider: TypeAlias = "BaseProvider[Any]"
 
 ProviderErrorMap: TypeAlias = Mapping[
     type[Exception],
-    "type[MirascopeLLMError] | Callable[[Exception], type[MirascopeLLMError]]",
+    "type[ProviderError] | Callable[[Exception], type[ProviderError]]",
 ]
 """Mapping from provider SDK exceptions to Mirascope error types.
 
@@ -85,7 +84,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
                 (e.g., lambda e: NotFoundError if e.code == "model_not_found" else BadRequestError)
 
     The mapping is walked via the exception's MRO, allowing both specific error handling
-    and fallback to base SDK error types (e.g., AnthropicError -> APIError).
+    and fallback to base SDK error types (e.g., AnthropicError -> ProviderError).
     """
 
     client: ProviderClientT
@@ -96,7 +95,7 @@ class BaseProvider(Generic[ProviderClientT], ABC):
 
         Walks the exception's MRO to find the first matching error type in the
         provider's error_map, allowing both specific error handling and fallback
-        to base SDK error types (e.g., AnthropicError -> APIError).
+        to base SDK error types (e.g., AnthropicError -> ProviderError).
         """
         try:
             yield
@@ -107,16 +106,24 @@ class BaseProvider(Generic[ProviderClientT], ABC):
                     error_type_or_fn = self.error_map[error_class]
 
                     if isinstance(error_type_or_fn, type):
-                        error_type = cast(type[MirascopeLLMError], error_type_or_fn)
+                        error_type = cast(type[ProviderError], error_type_or_fn)
                     else:
                         error_type = error_type_or_fn(e)
 
                     # Construct Mirascope error with metadata
-                    error: MirascopeLLMError = error_type(str(e))
-                    if isinstance(error, APIError):
-                        error.status_code = self.get_error_status(e)
-                    error.provider = self.id
-                    error.original_exception = e
+                    if issubclass(error_type, APIError):
+                        error: ProviderError = error_type(
+                            str(e),
+                            provider=self.id,
+                            status_code=self.get_error_status(e),
+                            original_exception=e,
+                        )
+                    else:
+                        error = error_type(
+                            str(e),
+                            provider=self.id,
+                            original_exception=e,
+                        )
                     raise error from e
 
             # Not in error_map - not a provider error, re-raise as-is
@@ -170,7 +177,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         model_id: str,
         messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None,
         **params: Unpack[Params],
     ) -> Response | Response[FormattableT]:
         """Generate an `llm.Response` with an optional response format."""
@@ -182,7 +192,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         model_id: str,
         messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> Response | Response[FormattableT]:
         """Generate an `llm.Response` by synchronously calling this client's LLM provider.
@@ -213,7 +226,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         model_id: str,
         messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> Response | Response[FormattableT]:
         """Implementation for call(). Subclasses override this method."""
@@ -261,7 +277,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None,
         **params: Unpack[Params],
     ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
         """Generate an `llm.ContextResponse` with an optional response format."""
@@ -276,7 +295,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
         """Generate an `llm.ContextResponse` by synchronously calling this client's LLM provider.
@@ -312,7 +334,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
         """Implementation for context_call(). Subclasses override this method."""
@@ -351,7 +376,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         model_id: str,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None,
         **params: Unpack[Params],
     ) -> AsyncResponse | AsyncResponse[FormattableT]:
         """Generate an `llm.AsyncResponse` with an optional response format."""
@@ -363,7 +391,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         model_id: str,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> AsyncResponse | AsyncResponse[FormattableT]:
         """Generate an `llm.AsyncResponse` by asynchronously calling this client's LLM provider.
@@ -394,7 +425,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         model_id: str,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> AsyncResponse | AsyncResponse[FormattableT]:
         """Implementation for call_async(). Subclasses override this method."""
@@ -442,7 +476,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None,
         **params: Unpack[Params],
     ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
         """Generate an `llm.AsyncContextResponse` with an optional response format."""
@@ -457,7 +494,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
         """Generate an `llm.AsyncContextResponse` by asynchronously calling this client's LLM provider.
@@ -493,7 +533,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
         """Implementation for context_call_async(). Subclasses override this method."""
@@ -532,7 +575,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         model_id: str,
         messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None,
         **params: Unpack[Params],
     ) -> StreamResponse | StreamResponse[FormattableT]:
         """Stream an `llm.StreamResponse` with an optional response format."""
@@ -544,7 +590,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         model_id: str,
         messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> StreamResponse | StreamResponse[FormattableT]:
         """Generate an `llm.StreamResponse` by synchronously streaming from this client's LLM provider.
@@ -579,7 +628,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         model_id: str,
         messages: Sequence[Message],
         tools: Sequence[Tool] | Toolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> StreamResponse | StreamResponse[FormattableT]:
         """Implementation for stream(). Subclasses override this method."""
@@ -627,7 +679,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None,
         **params: Unpack[Params],
     ) -> (
         ContextStreamResponse[DepsT, None] | ContextStreamResponse[DepsT, FormattableT]
@@ -644,7 +699,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> (
         ContextStreamResponse[DepsT, None] | ContextStreamResponse[DepsT, FormattableT]
@@ -686,7 +744,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         tools: Sequence[Tool | ContextTool[DepsT]]
         | ContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> (
         ContextStreamResponse[DepsT, None] | ContextStreamResponse[DepsT, FormattableT]
@@ -727,7 +788,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         model_id: str,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None,
         **params: Unpack[Params],
     ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
         """Stream an `llm.AsyncStreamResponse` with an optional response format."""
@@ -739,7 +803,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         model_id: str,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
         """Generate an `llm.AsyncStreamResponse` by asynchronously streaming from this client's LLM provider.
@@ -774,7 +841,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         model_id: str,
         messages: Sequence[Message],
         tools: Sequence[AsyncTool] | AsyncToolkit | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
         """Implementation for stream_async(). Subclasses override this method."""
@@ -822,7 +892,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None,
         **params: Unpack[Params],
     ) -> (
         AsyncContextStreamResponse[DepsT, None]
@@ -840,7 +913,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> (
         AsyncContextStreamResponse[DepsT, None]
@@ -883,7 +959,10 @@ class BaseProvider(Generic[ProviderClientT], ABC):
         tools: Sequence[AsyncTool | AsyncContextTool[DepsT]]
         | AsyncContextToolkit[DepsT]
         | None = None,
-        format: type[FormattableT] | Format[FormattableT] | None = None,
+        format: type[FormattableT]
+        | Format[FormattableT]
+        | OutputParser[FormattableT]
+        | None = None,
         **params: Unpack[Params],
     ) -> (
         AsyncContextStreamResponse[DepsT, None]

mirascope/llm/providers/google/__init__.py

@@ -1,21 +1,6 @@
 """Google client implementation."""
 
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from .model_id import GoogleModelId
-    from .provider import GoogleProvider
-else:
-    try:
-        from .model_id import GoogleModelId
-        from .provider import GoogleProvider
-    except ImportError:  # pragma: no cover
-        from .._missing_import_stubs import (
-            create_import_error_stub,
-            create_provider_stub,
-        )
-
-        GoogleProvider = create_provider_stub("google", "GoogleProvider")
-        GoogleModelId = str
+from .model_id import GoogleModelId
+from .provider import GoogleProvider
 
 __all__ = ["GoogleModelId", "GoogleProvider"]

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

@@ -1,3 +1,4 @@
+from ...base._utils import get_include_thoughts
 from .decode import (
     decode_async_stream,
     decode_response,
@@ -12,4 +13,5 @@ __all__ = [
     "decode_response",
     "decode_stream",
     "encode_request",
+    "get_include_thoughts",
 ]

mirascope/llm/providers/google/_utils/decode.py

@@ -126,6 +126,8 @@ def _decode_candidate_content(
 def decode_response(
     response: genai_types.GenerateContentResponse,
     model_id: GoogleModelId,
+    *,
+    include_thoughts: bool,
 ) -> tuple[AssistantMessage, FinishReason | None, Usage | None]:
     """Returns an `AssistantMessage`, `FinishReason`, and `Usage` extracted from a `GenerateContentResponse`"""
     content: Sequence[AssistantContentPart] = []
@@ -134,6 +136,8 @@ def decode_response(
 
     if response.candidates and (candidate := response.candidates[0]):
         content = _decode_candidate_content(candidate)
+        if not include_thoughts:
+            content = [part for part in content if part.type != "thought"]
         candidate_content = candidate.content
         if candidate.finish_reason:
             finish_reason = GOOGLE_FINISH_REASON_MAP.get(candidate.finish_reason)
@@ -155,12 +159,13 @@ def decode_response(
 class _GoogleChunkProcessor:
     """Processes Google stream chunks and maintains state across chunks."""
 
-    def __init__(self) -> None:
+    def __init__(self, *, include_thoughts: bool) -> None:
         self.current_content_type: Literal["text", "tool_call", "thought"] | None = None
         self.accumulated_parts: list[genai_types.Part] = []
         self.reconstructed_content = genai_types.Content(parts=[])
         # Track previous cumulative usage to compute deltas
         self.prev_usage = Usage()
+        self.include_thoughts = include_thoughts
 
     def process_chunk(
         self, chunk: genai_types.GenerateContentResponse
@@ -175,27 +180,34 @@ class _GoogleChunkProcessor:
         for part in candidate.content.parts:
             self.accumulated_parts.append(part)
             if self.current_content_type == "thought" and not part.thought:
-                yield ThoughtEndChunk()
+                if self.include_thoughts:
+                    yield ThoughtEndChunk()
                 self.current_content_type = None
-            elif self.current_content_type == "text" and not part.text:
-                yield TextEndChunk()  # pragma: no cover
-                self.current_content_type = None  # pragma: no cover
-            elif self.current_content_type == "tool_call" and not part.function_call:
+            elif (
+                self.current_content_type == "text" and not part.text
+            ):  # pragma: no cover
+                yield TextEndChunk()
+                self.current_content_type = None
+            elif (
+                self.current_content_type == "tool_call" and not part.function_call
+            ):  # pragma: no cover
                 # In testing, Gemini never emits tool calls and text in the same message
                 # (even when specifically asked in system and user prompt), so
                 # the following code is uncovered but included for completeness
-                yield ToolCallEndChunk()  # pragma: no cover
-                self.current_content_type = None  # pragma: no cover
+                yield ToolCallEndChunk(id=UNKNOWN_TOOL_ID)
+                self.current_content_type = None
 
             if part.thought:
                 if self.current_content_type is None:
-                    yield ThoughtStartChunk()
+                    if self.include_thoughts:
+                        yield ThoughtStartChunk()
                     self.current_content_type = "thought"
                 if not part.text:
                     raise ValueError(
                         "Inside thought part with no text content"
                     )  # pragma: no cover
-                yield ThoughtChunk(delta=part.text)
+                if self.include_thoughts:
+                    yield ThoughtChunk(delta=part.text)
 
             elif part.text:
                 if self.current_content_type is None:
@@ -210,23 +222,29 @@ class _GoogleChunkProcessor:
                         "Required name missing on Google function call"
                     )  # pragma: no cover
 
+                tool_id = function_call.id or UNKNOWN_TOOL_ID
+                self.current_content_type = "tool_call"
+
                 yield ToolCallStartChunk(
-                    id=function_call.id or UNKNOWN_TOOL_ID,
+                    id=tool_id,
                     name=function_call.name,
                 )
 
                 yield ToolCallChunk(
+                    id=tool_id,
                     delta=json.dumps(function_call.args)
                     if function_call.args
                     else "{}",
                 )
-                yield ToolCallEndChunk()
+                yield ToolCallEndChunk(id=tool_id)
+                self.current_content_type = None
 
         if candidate.finish_reason:
             if self.current_content_type == "text":
                 yield TextEndChunk()
             elif self.current_content_type == "thought":
-                yield ThoughtEndChunk()  # pragma: no cover
+                if self.include_thoughts:  # pragma: no cover
+                    yield ThoughtEndChunk()
             elif self.current_content_type is not None:
                 raise NotImplementedError
 
@@ -266,9 +284,11 @@ class _GoogleChunkProcessor:
 
 def decode_stream(
     google_stream: Iterator[genai_types.GenerateContentResponse],
+    *,
+    include_thoughts: bool,
 ) -> ChunkIterator:
     """Returns a ChunkIterator converted from a Google stream."""
-    processor = _GoogleChunkProcessor()
+    processor = _GoogleChunkProcessor(include_thoughts=include_thoughts)
     for chunk in google_stream:
         yield from processor.process_chunk(chunk)
     yield processor.raw_message_chunk()
@@ -276,9 +296,11 @@ def decode_stream(
 
 async def decode_async_stream(
     google_stream: AsyncIterator[genai_types.GenerateContentResponse],
+    *,
+    include_thoughts: bool,
 ) -> AsyncChunkIterator:
     """Returns an AsyncChunkIterator converted from a Google async stream."""
-    processor = _GoogleChunkProcessor()
+    processor = _GoogleChunkProcessor(include_thoughts=include_thoughts)
     async for chunk in google_stream:
         for item in processor.process_chunk(chunk):
             yield item