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

mirascope/llm/providers/anthropic/provider.py

@@ -6,7 +6,7 @@ from typing_extensions import Unpack
 from anthropic import Anthropic, AsyncAnthropic
 
 from ...context import Context, DepsT
-from ...formatting import Format, FormattableT
+from ...formatting import Format, FormattableT, resolve_format
 from ...messages import Message
 from ...responses import (
     AsyncContextResponse,
@@ -30,7 +30,24 @@ from ...tools import (
 )
 from ..base import BaseProvider, Params
 from . import _utils
+from .beta_provider import AnthropicBetaProvider
 from .model_id import AnthropicModelId, model_name
+from .model_info import MODELS_WITHOUT_STRICT_STRUCTURED_OUTPUTS
+
+
+def _should_use_beta(
+    model_id: AnthropicModelId,
+    format: type[FormattableT] | Format[FormattableT] | None,
+) -> bool:
+    """Determine whether to use the beta API based on format mode.
+
+    If the format resolves to strict mode, and the model plausibly has
+    strict structured output support, then we will use the beta provider.
+    """
+    resolved = resolve_format(format, default_mode=_utils.DEFAULT_FORMAT_MODE)
+    if resolved is None or resolved.mode != "strict":
+        return False
+    return model_name(model_id) not in MODELS_WITHOUT_STRICT_STRUCTURED_OUTPUTS
 
 
 class AnthropicProvider(BaseProvider[Anthropic]):
@@ -38,6 +55,7 @@ class AnthropicProvider(BaseProvider[Anthropic]):
 
     id = "anthropic"
     default_scope = "anthropic/"
+    _beta_provider: AnthropicBetaProvider
 
     def __init__(
         self, *, api_key: str | None = None, base_url: str | None = None
@@ -45,6 +63,7 @@ class AnthropicProvider(BaseProvider[Anthropic]):
         """Initialize the Anthropic client."""
         self.client = Anthropic(api_key=api_key, base_url=base_url)
         self.async_client = AsyncAnthropic(api_key=api_key, base_url=base_url)
+        self._beta_provider = AnthropicBetaProvider(api_key=api_key, base_url=base_url)
 
     def _call(
         self,
@@ -55,32 +74,27 @@ class AnthropicProvider(BaseProvider[Anthropic]):
         format: type[FormattableT] | Format[FormattableT] | None = None,
         **params: Unpack[Params],
     ) -> Response | Response[FormattableT]:
-        """Generate an `llm.Response` by synchronously calling the Anthropic Messages 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(
+        """Generate an `llm.Response` by synchronously calling the Anthropic Messages API."""
+        if _should_use_beta(model_id, format):
+            return self._beta_provider.call(
+                model_id=model_id,
+                messages=messages,
+                tools=tools,
+                format=format,
+                **params,
+            )
+
+        input_messages, resolved_format, kwargs = _utils.encode_request(
             model_id=model_id,
             messages=messages,
             tools=tools,
             format=format,
             params=params,
         )
-
         anthropic_response = self.client.messages.create(**kwargs)
-
-        assistant_message, finish_reason = _utils.decode_response(
+        assistant_message, finish_reason, usage = _utils.decode_response(
             anthropic_response, model_id
         )
-
         return Response(
             raw=anthropic_response,
             provider_id="anthropic",
@@ -91,7 +105,8 @@ class AnthropicProvider(BaseProvider[Anthropic]):
             input_messages=input_messages,
             assistant_message=assistant_message,
             finish_reason=finish_reason,
-            format=format,
+            usage=usage,
+            format=resolved_format,
         )
 
     def _context_call(
@@ -106,33 +121,28 @@ class AnthropicProvider(BaseProvider[Anthropic]):
         format: type[FormattableT] | Format[FormattableT] | None = None,
         **params: Unpack[Params],
     ) -> ContextResponse[DepsT, None] | ContextResponse[DepsT, FormattableT]:
-        """Generate an `llm.ContextResponse` by synchronously calling the Anthropic Messages 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(
+        """Generate an `llm.ContextResponse` by synchronously calling the Anthropic Messages API."""
+        if _should_use_beta(model_id, format):
+            return self._beta_provider.context_call(
+                ctx=ctx,
+                model_id=model_id,
+                messages=messages,
+                tools=tools,
+                format=format,
+                **params,
+            )
+
+        input_messages, resolved_format, kwargs = _utils.encode_request(
             model_id=model_id,
             messages=messages,
             tools=tools,
             format=format,
             params=params,
         )
-
         anthropic_response = self.client.messages.create(**kwargs)
-
-        assistant_message, finish_reason = _utils.decode_response(
+        assistant_message, finish_reason, usage = _utils.decode_response(
             anthropic_response, model_id
         )
-
         return ContextResponse(
             raw=anthropic_response,
             provider_id="anthropic",
@@ -143,7 +153,8 @@ class AnthropicProvider(BaseProvider[Anthropic]):
             input_messages=input_messages,
             assistant_message=assistant_message,
             finish_reason=finish_reason,
-            format=format,
+            usage=usage,
+            format=resolved_format,
         )
 
     async def _call_async(
@@ -155,32 +166,27 @@ class AnthropicProvider(BaseProvider[Anthropic]):
         format: type[FormattableT] | Format[FormattableT] | None = None,
         **params: Unpack[Params],
     ) -> AsyncResponse | AsyncResponse[FormattableT]:
-        """Generate an `llm.AsyncResponse` by asynchronously calling the Anthropic Messages 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(
+        """Generate an `llm.AsyncResponse` by asynchronously calling the Anthropic Messages API."""
+        if _should_use_beta(model_id, format):
+            return await self._beta_provider.call_async(
+                model_id=model_id,
+                messages=messages,
+                tools=tools,
+                format=format,
+                **params,
+            )
+
+        input_messages, resolved_format, kwargs = _utils.encode_request(
             model_id=model_id,
             messages=messages,
             tools=tools,
             format=format,
             params=params,
         )
-
         anthropic_response = await self.async_client.messages.create(**kwargs)
-
-        assistant_message, finish_reason = _utils.decode_response(
+        assistant_message, finish_reason, usage = _utils.decode_response(
             anthropic_response, model_id
         )
-
         return AsyncResponse(
             raw=anthropic_response,
             provider_id="anthropic",
@@ -191,7 +197,8 @@ class AnthropicProvider(BaseProvider[Anthropic]):
             input_messages=input_messages,
             assistant_message=assistant_message,
             finish_reason=finish_reason,
-            format=format,
+            usage=usage,
+            format=resolved_format,
         )
 
     async def _context_call_async(
@@ -206,33 +213,28 @@ class AnthropicProvider(BaseProvider[Anthropic]):
         format: type[FormattableT] | Format[FormattableT] | None = None,
         **params: Unpack[Params],
     ) -> AsyncContextResponse[DepsT, None] | AsyncContextResponse[DepsT, FormattableT]:
-        """Generate an `llm.AsyncContextResponse` by asynchronously calling the Anthropic Messages 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(
+        """Generate an `llm.AsyncContextResponse` by asynchronously calling the Anthropic Messages API."""
+        if _should_use_beta(model_id, format):
+            return await self._beta_provider.context_call_async(
+                ctx=ctx,
+                model_id=model_id,
+                messages=messages,
+                tools=tools,
+                format=format,
+                **params,
+            )
+
+        input_messages, resolved_format, kwargs = _utils.encode_request(
             model_id=model_id,
             messages=messages,
             tools=tools,
             format=format,
             params=params,
         )
-
         anthropic_response = await self.async_client.messages.create(**kwargs)
-
-        assistant_message, finish_reason = _utils.decode_response(
+        assistant_message, finish_reason, usage = _utils.decode_response(
             anthropic_response, model_id
         )
-
         return AsyncContextResponse(
             raw=anthropic_response,
             provider_id="anthropic",
@@ -243,7 +245,8 @@ class AnthropicProvider(BaseProvider[Anthropic]):
             input_messages=input_messages,
             assistant_message=assistant_message,
             finish_reason=finish_reason,
-            format=format,
+            usage=usage,
+            format=resolved_format,
         )
 
     def _stream(
@@ -255,30 +258,25 @@ class AnthropicProvider(BaseProvider[Anthropic]):
         format: type[FormattableT] | Format[FormattableT] | None = None,
         **params: Unpack[Params],
     ) -> StreamResponse | StreamResponse[FormattableT]:
-        """Generate an `llm.StreamResponse` by synchronously streaming from the Anthropic Messages 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(
+        """Generate an `llm.StreamResponse` by synchronously streaming from the Anthropic Messages API."""
+        if _should_use_beta(model_id, format):
+            return self._beta_provider.stream(
+                model_id=model_id,
+                messages=messages,
+                tools=tools,
+                format=format,
+                **params,
+            )
+
+        input_messages, resolved_format, kwargs = _utils.encode_request(
             model_id=model_id,
             messages=messages,
             tools=tools,
             format=format,
             params=params,
         )
-
         anthropic_stream = self.client.messages.stream(**kwargs)
-
         chunk_iterator = _utils.decode_stream(anthropic_stream)
-
         return StreamResponse(
             provider_id="anthropic",
             model_id=model_id,
@@ -287,7 +285,7 @@ class AnthropicProvider(BaseProvider[Anthropic]):
             tools=tools,
             input_messages=input_messages,
             chunk_iterator=chunk_iterator,
-            format=format,
+            format=resolved_format,
         )
 
     def _context_stream(
@@ -302,31 +300,26 @@ class AnthropicProvider(BaseProvider[Anthropic]):
         format: type[FormattableT] | Format[FormattableT] | None = None,
         **params: Unpack[Params],
     ) -> ContextStreamResponse[DepsT] | ContextStreamResponse[DepsT, FormattableT]:
-        """Generate an `llm.ContextStreamResponse` by synchronously streaming from the Anthropic Messages 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(
+        """Generate an `llm.ContextStreamResponse` by synchronously streaming from the Anthropic Messages API."""
+        if _should_use_beta(model_id, format):
+            return self._beta_provider.context_stream(
+                ctx=ctx,
+                model_id=model_id,
+                messages=messages,
+                tools=tools,
+                format=format,
+                **params,
+            )
+
+        input_messages, resolved_format, kwargs = _utils.encode_request(
             model_id=model_id,
             messages=messages,
             tools=tools,
             format=format,
             params=params,
         )
-
         anthropic_stream = self.client.messages.stream(**kwargs)
-
         chunk_iterator = _utils.decode_stream(anthropic_stream)
-
         return ContextStreamResponse(
             provider_id="anthropic",
             model_id=model_id,
@@ -335,7 +328,7 @@ class AnthropicProvider(BaseProvider[Anthropic]):
             tools=tools,
             input_messages=input_messages,
             chunk_iterator=chunk_iterator,
-            format=format,
+            format=resolved_format,
         )
 
     async def _stream_async(
@@ -347,30 +340,24 @@ class AnthropicProvider(BaseProvider[Anthropic]):
         format: type[FormattableT] | Format[FormattableT] | None = None,
         **params: Unpack[Params],
     ) -> AsyncStreamResponse | AsyncStreamResponse[FormattableT]:
-        """Generate an `llm.AsyncStreamResponse` by asynchronously streaming from the Anthropic Messages 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 asynchronously iterating over the LLM-generated content.
-        """
-        input_messages, format, kwargs = _utils.encode_request(
+        """Generate an `llm.AsyncStreamResponse` by asynchronously streaming from the Anthropic Messages API."""
+        if _should_use_beta(model_id, format):
+            return await self._beta_provider.stream_async(
+                model_id=model_id,
+                messages=messages,
+                tools=tools,
+                format=format,
+                **params,
+            )
+        input_messages, resolved_format, kwargs = _utils.encode_request(
             model_id=model_id,
             messages=messages,
             tools=tools,
             format=format,
             params=params,
         )
-
         anthropic_stream = self.async_client.messages.stream(**kwargs)
-
         chunk_iterator = _utils.decode_async_stream(anthropic_stream)
-
         return AsyncStreamResponse(
             provider_id="anthropic",
             model_id=model_id,
@@ -379,7 +366,7 @@ class AnthropicProvider(BaseProvider[Anthropic]):
             tools=tools,
             input_messages=input_messages,
             chunk_iterator=chunk_iterator,
-            format=format,
+            format=resolved_format,
         )
 
     async def _context_stream_async(
@@ -397,31 +384,26 @@ class AnthropicProvider(BaseProvider[Anthropic]):
         AsyncContextStreamResponse[DepsT]
         | AsyncContextStreamResponse[DepsT, FormattableT]
     ):
-        """Generate an `llm.AsyncContextStreamResponse` by asynchronously streaming from the Anthropic Messages 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 asynchronously iterating over the LLM-generated content.
-        """
-        input_messages, format, kwargs = _utils.encode_request(
+        """Generate an `llm.AsyncContextStreamResponse` by asynchronously streaming from the Anthropic Messages API."""
+        if _should_use_beta(model_id, format):
+            return await self._beta_provider.context_stream_async(
+                ctx=ctx,
+                model_id=model_id,
+                messages=messages,
+                tools=tools,
+                format=format,
+                **params,
+            )
+
+        input_messages, resolved_format, kwargs = _utils.encode_request(
             model_id=model_id,
             messages=messages,
             tools=tools,
             format=format,
             params=params,
         )
-
         anthropic_stream = self.async_client.messages.stream(**kwargs)
-
         chunk_iterator = _utils.decode_async_stream(anthropic_stream)
-
         return AsyncContextStreamResponse(
             provider_id="anthropic",
             model_id=model_id,
@@ -430,5 +412,5 @@ class AnthropicProvider(BaseProvider[Anthropic]):
             tools=tools,
             input_messages=input_messages,
             chunk_iterator=chunk_iterator,
-            format=format,
+            format=resolved_format,
         )

mirascope/llm/providers/base/_utils.py

@@ -1,7 +1,7 @@
 import logging
 from collections.abc import Generator, Sequence
 from contextlib import contextmanager
-from typing import TYPE_CHECKING, TypeAlias, get_type_hints
+from typing import TYPE_CHECKING, TypeAlias, cast, get_type_hints
 
 from ...content import Text
 from ...messages import AssistantMessage, Message, SystemMessage, UserMessage
@@ -16,6 +16,20 @@ logger = logging.getLogger(__name__)
 SystemMessageContent: TypeAlias = str | None
 
 
+def ensure_additional_properties_false(obj: object) -> None:
+    """Recursively adds additionalProperties = False to a schema, required for strict mode."""
+    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)
+    elif isinstance(obj, list):
+        obj = cast(list[object], obj)
+        for item in obj:
+            ensure_additional_properties_false(item)
+
+
 def add_system_instructions(
     messages: Sequence[Message], additional_system_instructions: str
 ) -> Sequence[Message]:

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

@@ -29,6 +29,8 @@ from ....responses import (
     FinishReasonChunk,
     RawMessageChunk,
     RawStreamEventChunk,
+    Usage,
+    UsageDeltaChunk,
 )
 from ..model_id import GoogleModelId, model_name
 from .encode import UNKNOWN_TOOL_ID
@@ -43,6 +45,30 @@ GOOGLE_FINISH_REASON_MAP = {
 }
 
 
+def _decode_usage(
+    usage: genai_types.GenerateContentResponseUsageMetadata | None,
+) -> Usage | None:
+    """Convert Google UsageMetadata to Mirascope Usage."""
+    if (
+        usage is None
+        or usage.prompt_token_count is None
+        or usage.candidates_token_count is None
+    ):  # pragma: no cover
+        return None
+
+    reasoning_tokens = usage.thoughts_token_count or 0
+    output_tokens = usage.candidates_token_count + reasoning_tokens
+
+    return Usage(
+        input_tokens=usage.prompt_token_count,
+        output_tokens=output_tokens,
+        cache_read_tokens=usage.cached_content_token_count or 0,
+        cache_write_tokens=0,
+        reasoning_tokens=usage.thoughts_token_count or 0,
+        raw=usage,
+    )
+
+
 def _decode_content_part(part: genai_types.Part) -> AssistantContentPart | None:
     """Returns an `AssistantContentPart` (or `None`) decoded from a google `Part`"""
     if part.thought and part.text:
@@ -100,8 +126,8 @@ def _decode_candidate_content(
 def decode_response(
     response: genai_types.GenerateContentResponse,
     model_id: GoogleModelId,
-) -> tuple[AssistantMessage, FinishReason | None]:
-    """Returns an `AssistantMessage` and `FinishReason` extracted from a `GenerateContentResponse`"""
+) -> tuple[AssistantMessage, FinishReason | None, Usage | None]:
+    """Returns an `AssistantMessage`, `FinishReason`, and `Usage` extracted from a `GenerateContentResponse`"""
     content: Sequence[AssistantContentPart] = []
     candidate_content: genai_types.Content | None = None
     finish_reason: FinishReason | None = None
@@ -122,7 +148,8 @@ def decode_response(
         raw_message=candidate_content.model_dump(),
     )
 
-    return assistant_message, finish_reason
+    usage = _decode_usage(response.usage_metadata)
+    return assistant_message, finish_reason, usage
 
 
 class _GoogleChunkProcessor:
@@ -132,6 +159,8 @@ class _GoogleChunkProcessor:
         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()
 
     def process_chunk(
         self, chunk: genai_types.GenerateContentResponse
@@ -207,6 +236,29 @@ class _GoogleChunkProcessor:
             if finish_reason is not None:
                 yield FinishReasonChunk(finish_reason=finish_reason)
 
+        # Emit usage delta if usage metadata is present
+        if chunk.usage_metadata:
+            usage_metadata = chunk.usage_metadata
+            current_input = usage_metadata.prompt_token_count or 0
+            current_output = usage_metadata.candidates_token_count or 0
+            current_cache_read = usage_metadata.cached_content_token_count or 0
+            current_reasoning = usage_metadata.thoughts_token_count or 0
+
+            yield UsageDeltaChunk(
+                input_tokens=current_input - self.prev_usage.input_tokens,
+                output_tokens=current_output - self.prev_usage.output_tokens,
+                cache_read_tokens=current_cache_read
+                - self.prev_usage.cache_read_tokens,
+                cache_write_tokens=0,
+                reasoning_tokens=current_reasoning - self.prev_usage.reasoning_tokens,
+            )
+
+            # Update previous usage
+            self.prev_usage.input_tokens = current_input
+            self.prev_usage.output_tokens = current_output
+            self.prev_usage.cache_read_tokens = current_cache_read
+            self.prev_usage.reasoning_tokens = current_reasoning
+
     def raw_message_chunk(self) -> RawMessageChunk:
         content = genai_types.Content(role="model", parts=self.accumulated_parts)
         return RawMessageChunk(raw_message=content.model_dump())

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

@@ -21,6 +21,7 @@ from ....messages import AssistantMessage, Message, UserMessage
 from ....tools import FORMAT_TOOL_NAME, AnyToolSchema, BaseToolkit
 from ...base import Params, _utils as _base_utils
 from ..model_id import GoogleModelId, model_name
+from ..model_info import MODELS_WITHOUT_STRUCTURED_OUTPUT_AND_TOOLS_SUPPORT
 
 UNKNOWN_TOOL_ID = "google_unknown_tool_id"
 
@@ -187,6 +188,7 @@ def encode_request(
         genai_types.GenerateContentConfigDict()
     )
     encode_thoughts = False
+    google_model_name = model_name(model_id)
 
     with _base_utils.ensure_all_params_accessed(
         params=params, provider_id="google"
@@ -219,17 +221,23 @@ def encode_request(
     tools = tools.tools if isinstance(tools, BaseToolkit) else tools or []
     google_tools: list[genai_types.ToolDict] = []
 
-    format = resolve_format(
-        format,
-        # Google does not support strict outputs when tools are present
-        # (Gemini 2.5 will error, 2.0 and below will ignore tools)
-        default_mode="strict" if not tools else "tool",
+    allows_strict_mode_with_tools = (
+        google_model_name not in MODELS_WITHOUT_STRUCTURED_OUTPUT_AND_TOOLS_SUPPORT
     )
+    # Older google models do not allow strict mode when using tools; if so, we use tool
+    # mode when tools are present by default for compatibility. Otherwise, prefer strict mode.
+    default_mode = "tool" if tools and not allows_strict_mode_with_tools else "strict"
+    format = resolve_format(format, default_mode=default_mode)
     if format is not None:
-        if format.mode in ("strict", "json") and tools:
+        if (
+            format.mode in ("strict", "json")
+            and tools
+            and not allows_strict_mode_with_tools
+        ):
             raise FeatureNotSupportedError(
                 feature=f"formatting_mode:{format.mode} with tools",
                 provider_id="google",
+                model_id=model_id,
             )
 
         if format.mode == "strict":