mirascope 2.0.1__py3-none-any.whl → 2.1.0__py3-none-any.whl

mirascope/llm/prompts/prompts.py

@@ -1,11 +1,12 @@
 """Concrete Prompt classes for generating messages with tools and formatting."""
 
-from collections.abc import Sequence
-from dataclasses import dataclass
-from typing import Generic, overload
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Generic, TypeVar, overload
 
+from ..._utils import copy_function_metadata
 from ..context import Context, DepsT
-from ..formatting import Format, FormattableT, OutputParser
+from ..formatting import FormatSpec, FormattableT
 from ..messages import Message, promote_to_messages
 from ..models import Model
 from ..providers import ModelId
@@ -19,12 +20,7 @@ from ..responses import (
     Response,
     StreamResponse,
 )
-from ..tools import (
-    AsyncContextToolkit,
-    AsyncToolkit,
-    ContextToolkit,
-    Toolkit,
-)
+from ..tools import AsyncContextToolkit, AsyncToolkit, ContextToolkit, Toolkit
 from ..types import P
 from .protocols import (
     AsyncContextMessageTemplate,
@@ -33,9 +29,26 @@ from .protocols import (
     MessageTemplate,
 )
 
+FunctionT = TypeVar("FunctionT", bound=Callable[..., Any])
+
+
+@dataclass(kw_only=True)
+class BasePrompt(Generic[FunctionT]):
+    """Base class for all Prompt types with shared metadata functionality."""
+
+    fn: FunctionT
+    """The underlying prompt function that generates message content."""
+
+    __name__: str = field(init=False, repr=False, default="")
+    """The name of the underlying function (preserved for decorator stacking)."""
+
+    def __post_init__(self) -> None:
+        """Preserve standard function attributes for decorator stacking."""
+        copy_function_metadata(self, self.fn)
+
 
 @dataclass
-class Prompt(Generic[P, FormattableT]):
+class Prompt(BasePrompt[MessageTemplate[P]], Generic[P, FormattableT]):
     """A prompt that can be called with a model to generate a response.
 
     Created by decorating a `MessageTemplate` with `llm.prompt`. The decorated
@@ -45,15 +58,10 @@ class Prompt(Generic[P, FormattableT]):
     It can be invoked with a model: `prompt(model, *args, **kwargs)`.
     """
 
-    fn: MessageTemplate[P]
-    """The underlying prompt function that generates message content."""
-
     toolkit: Toolkit
     """The toolkit containing this prompt's tools."""
 
-    format: (
-        type[FormattableT] | Format[FormattableT] | OutputParser[FormattableT] | None
-    )
+    format: FormatSpec[FormattableT] | None
     """The response format for the generated response."""
 
     def messages(self, *args: P.args, **kwargs: P.kwargs) -> Sequence[Message]:
@@ -134,7 +142,7 @@ class Prompt(Generic[P, FormattableT]):
 
 
 @dataclass
-class AsyncPrompt(Generic[P, FormattableT]):
+class AsyncPrompt(BasePrompt[AsyncMessageTemplate[P]], Generic[P, FormattableT]):
     """An async prompt that can be called with a model to generate a response.
 
     Created by decorating an async `MessageTemplate` with `llm.prompt`. The decorated
@@ -144,15 +152,10 @@ class AsyncPrompt(Generic[P, FormattableT]):
     It can be invoked with a model: `await prompt(model, *args, **kwargs)`.
     """
 
-    fn: AsyncMessageTemplate[P]
-    """The underlying async prompt function that generates message content."""
-
     toolkit: AsyncToolkit
     """The toolkit containing this prompt's async tools."""
 
-    format: (
-        type[FormattableT] | Format[FormattableT] | OutputParser[FormattableT] | None
-    )
+    format: FormatSpec[FormattableT] | None
     """The response format for the generated response."""
 
     async def messages(self, *args: P.args, **kwargs: P.kwargs) -> Sequence[Message]:
@@ -235,7 +238,9 @@ class AsyncPrompt(Generic[P, FormattableT]):
 
 
 @dataclass
-class ContextPrompt(Generic[P, DepsT, FormattableT]):
+class ContextPrompt(
+    BasePrompt[ContextMessageTemplate[P, DepsT]], Generic[P, DepsT, FormattableT]
+):
     """A context-aware prompt that can be called with a model to generate a response.
 
     Created by decorating a `ContextMessageTemplate` with `llm.prompt`. The decorated
@@ -246,15 +251,10 @@ class ContextPrompt(Generic[P, DepsT, FormattableT]):
     It can be invoked with a model: `prompt(model, ctx, *args, **kwargs)`.
     """
 
-    fn: ContextMessageTemplate[P, DepsT]
-    """The underlying context-aware prompt function that generates message content."""
-
     toolkit: ContextToolkit[DepsT]
     """The toolkit containing this prompt's context-aware tools."""
 
-    format: (
-        type[FormattableT] | Format[FormattableT] | OutputParser[FormattableT] | None
-    )
+    format: FormatSpec[FormattableT] | None
     """The response format for the generated response."""
 
     def messages(
@@ -361,7 +361,9 @@ class ContextPrompt(Generic[P, DepsT, FormattableT]):
 
 
 @dataclass
-class AsyncContextPrompt(Generic[P, DepsT, FormattableT]):
+class AsyncContextPrompt(
+    BasePrompt[AsyncContextMessageTemplate[P, DepsT]], Generic[P, DepsT, FormattableT]
+):
     """An async context-aware prompt that can be called with a model to generate a response.
 
     Created by decorating an async `ContextMessageTemplate` with `llm.prompt`. The decorated
@@ -372,15 +374,10 @@ class AsyncContextPrompt(Generic[P, DepsT, FormattableT]):
     It can be invoked with a model: `await prompt(model, ctx, *args, **kwargs)`.
     """
 
-    fn: AsyncContextMessageTemplate[P, DepsT]
-    """The underlying async context-aware prompt function that generates message content."""
-
     toolkit: AsyncContextToolkit[DepsT]
     """The toolkit containing this prompt's async context-aware tools."""
 
-    format: (
-        type[FormattableT] | Format[FormattableT] | OutputParser[FormattableT] | None
-    )
+    format: FormatSpec[FormattableT] | None
     """The response format for the generated response."""
 
     async def messages(

mirascope/llm/providers/anthropic/_utils/beta_decode.py

@@ -44,7 +44,7 @@ from ....responses import (
     UsageDeltaChunk,
 )
 from ..model_id import model_name
-from .decode import decode_usage
+from .decode import decode_usage, extract_tool_usage
 
 BETA_FINISH_REASON_MAP = {
     "max_tokens": FinishReason.MAX_TOKENS,
@@ -53,7 +53,9 @@ BETA_FINISH_REASON_MAP = {
 }
 
 
-def _decode_beta_assistant_content(content: BetaContentBlock) -> AssistantContentPart:
+def _decode_beta_assistant_content(
+    content: BetaContentBlock,
+) -> AssistantContentPart | None:
     """Convert Beta content block to mirascope AssistantContentPart."""
     if content.type == "text":
         return Text(text=content.text)
@@ -65,6 +67,8 @@ def _decode_beta_assistant_content(content: BetaContentBlock) -> AssistantConten
         )
     elif content.type == "thinking":
         return Thought(thought=content.thinking)
+    elif content.type in ("server_tool_use", "web_search_tool_result"):
+        return None  # Skip server-side tool content, preserved in raw_message
     else:
         raise NotImplementedError(
             f"Support for beta content type `{content.type}` is not yet implemented."
@@ -78,7 +82,13 @@ def beta_decode_response(
     include_thoughts: bool,
 ) -> tuple[AssistantMessage, FinishReason | None, Usage]:
     """Convert Beta message to mirascope AssistantMessage and usage."""
-    content = [_decode_beta_assistant_content(part) for part in response.content]
+    content = [
+        part
+        for part in (
+            _decode_beta_assistant_content(block) for block in response.content
+        )
+        if part is not None
+    ]
     if not include_thoughts:
         content = [part for part in content if part.type != "thought"]
     assistant_message = AssistantMessage(
@@ -157,6 +167,8 @@ class _BetaChunkProcessor:
                     "type": "redacted_thinking",
                     "data": content_block.data,
                 }
+            elif content_block.type in ("server_tool_use", "web_search_tool_result"):
+                pass  # Skip server-side tool content
             else:
                 raise NotImplementedError(
                     f"Support for beta content block type `{content_block.type}` "
@@ -164,8 +176,8 @@ class _BetaChunkProcessor:
                 )
 
         elif event.type == "content_block_delta":
-            if self.current_block_param is None:  # pragma: no cover
-                raise RuntimeError("Received delta without a current block")
+            if self.current_block_param is None:
+                return  # Skip deltas for server-side tool content
 
             delta = event.delta
             if delta.type == "text_delta":
@@ -198,14 +210,16 @@ class _BetaChunkProcessor:
                         f"Received signature_delta for {self.current_block_param['type']} block"
                     )
                 self.current_block_param["signature"] += delta.signature
+            elif delta.type == "citations_delta":
+                pass  # Skip citations delta, preserved in raw_message
             else:
                 raise RuntimeError(
                     f"Received unsupported delta type: {delta.type}"
                 )  # pragma: no cover
 
         elif event.type == "content_block_stop":
-            if self.current_block_param is None:  # pragma: no cover
-                raise RuntimeError("Received stop without a current block")
+            if self.current_block_param is None:
+                return  # Skip stop for server-side tool content
 
             block_type = self.current_block_param["type"]
 
@@ -245,6 +259,7 @@ class _BetaChunkProcessor:
                 cache_read_tokens=usage.cache_read_input_tokens or 0,
                 cache_write_tokens=usage.cache_creation_input_tokens or 0,
                 reasoning_tokens=0,
+                provider_tool_usage=extract_tool_usage(usage),
             )
 
     def raw_message_chunk(self) -> RawMessageChunk:

mirascope/llm/providers/anthropic/_utils/beta_encode.py

@@ -7,12 +7,15 @@ from typing_extensions import Required
 from anthropic import Omit
 from anthropic.types.anthropic_beta_param import AnthropicBetaParam
 from anthropic.types.beta import (
+    BetaCacheControlEphemeralParam,
     BetaContentBlockParam,
     BetaMessageParam,
     BetaTextBlockParam,
     BetaThinkingConfigParam,
     BetaToolChoiceParam,
     BetaToolParam,
+    BetaToolUnionParam,
+    BetaWebSearchTool20250305Param,
 )
 from pydantic import BaseModel
 
@@ -20,12 +23,12 @@ from ....content import ContentPart
 from ....exceptions import FeatureNotSupportedError
 from ....formatting import (
     Format,
+    FormatSpec,
     FormattableT,
-    OutputParser,
     resolve_format,
 )
 from ....messages import AssistantMessage, Message, UserMessage
-from ....tools import AnyToolSchema, BaseToolkit
+from ....tools import AnyToolSchema, BaseToolkit, ProviderTool, WebSearchTool
 from ...base import _utils as _base_utils
 from ..model_id import model_name
 from ..model_info import MODELS_WITHOUT_STRICT_STRUCTURED_OUTPUTS
@@ -49,7 +52,7 @@ class BetaParseKwargs(TypedDict, total=False):
     max_tokens: Required[int]
     messages: Sequence[BetaMessageParam]
     system: Sequence[BetaTextBlockParam] | Omit
-    tools: Sequence[BetaToolParam] | Omit
+    tools: Sequence[BetaToolUnionParam] | Omit
     tool_choice: BetaToolChoiceParam | Omit
     temperature: float | Omit
     top_p: float | Omit
@@ -135,8 +138,8 @@ def _beta_encode_messages(
 
 
 def _beta_convert_tool_to_tool_param(
-    tool: AnyToolSchema, model_supports_strict: bool
-) -> BetaToolParam:
+    tool: "AnyToolSchema | ProviderTool", model_supports_strict: bool
+) -> BetaToolUnionParam:
     """Convert a single Mirascope tool to Beta Anthropic tool format.
 
     If the tool has strict=True (or None, and the model supports strict), the schema
@@ -144,6 +147,14 @@ def _beta_convert_tool_to_tool_param(
     by adding additionalProperties: false to all object schemas, and strict=True
     is passed to the API.
     """
+    if isinstance(tool, WebSearchTool):
+        return BetaWebSearchTool20250305Param(
+            type="web_search_20250305", name="web_search"
+        )
+    if isinstance(tool, ProviderTool):
+        raise FeatureNotSupportedError(
+            f"Provider tool {tool.name}", provider_id="anthropic-beta"
+        )
     schema_dict = tool.parameters.model_dump(by_alias=True, exclude_none=True)
     schema_dict["type"] = "object"
 
@@ -163,11 +174,8 @@ def beta_encode_request(
     *,
     model_id: str,
     messages: Sequence[Message],
-    tools: Sequence[AnyToolSchema] | BaseToolkit[AnyToolSchema] | None,
-    format: type[FormattableT]
-    | Format[FormattableT]
-    | OutputParser[FormattableT]
-    | None,
+    tools: BaseToolkit[AnyToolSchema],
+    format: FormatSpec[FormattableT] | None,
     params: "Params",
 ) -> tuple[Sequence[Message], Format[FormattableT] | None, BetaParseKwargs]:
     """Prepares a request for the Anthropic beta.messages.parse method."""
@@ -185,13 +193,11 @@ def beta_encode_request(
         }
     )
 
-    tools = tools.tools if isinstance(tools, BaseToolkit) else tools or []
-
     model_supports_strict = (
         model_name(model_id) not in MODELS_WITHOUT_STRICT_STRUCTURED_OUTPUTS
     )
     # Check for strict tools on models that don't support them
-    if _base_utils.has_strict_tools(tools) and not model_supports_strict:
+    if _base_utils.has_strict_tools(tools.tools) and not model_supports_strict:
         raise FeatureNotSupportedError(
             feature="strict tools",
             provider_id="anthropic",
@@ -204,7 +210,7 @@ def beta_encode_request(
         _beta_convert_tool_to_tool_param(
             tool, model_supports_strict=model_supports_strict
         )
-        for tool in tools
+        for tool in tools.tools
     ]
     format = resolve_format(format, default_mode=DEFAULT_FORMAT_MODE)
 
@@ -226,7 +232,7 @@ def beta_encode_request(
                     format_tool_schema, model_supports_strict=model_supports_strict
                 )
             )
-            if tools:
+            if tools.tools:
                 kwargs["tool_choice"] = {"type": "any"}
             else:
                 kwargs["tool_choice"] = {
@@ -243,7 +249,7 @@ def beta_encode_request(
     if anthropic_tools:
         # Add cache control to the last tool for prompt caching
         last_tool = anthropic_tools[-1]
-        last_tool["cache_control"] = {"type": "ephemeral"}
+        last_tool["cache_control"] = BetaCacheControlEphemeralParam(type="ephemeral")
         kwargs["tools"] = anthropic_tools
 
     system_message_content, remaining_messages = _base_utils.extract_system_message(

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

@@ -5,7 +5,7 @@ from typing import Any, TypeAlias, cast
 
 from anthropic import types as anthropic_types
 from anthropic.lib.streaming import AsyncMessageStreamManager, MessageStreamManager
-from anthropic.types.beta import BetaUsage
+from anthropic.types.beta import BetaMessageDeltaUsage, BetaUsage
 
 from ....content import (
     AssistantContentPart,
@@ -28,6 +28,7 @@ from ....responses import (
     ChunkIterator,
     FinishReason,
     FinishReasonChunk,
+    ProviderToolUsage,
     RawMessageChunk,
     RawStreamEventChunk,
     Usage,
@@ -43,7 +44,7 @@ ANTHROPIC_FINISH_REASON_MAP = {
 
 def _decode_assistant_content(
     content: anthropic_types.ContentBlock,
-) -> AssistantContentPart:
+) -> AssistantContentPart | None:
     """Convert Anthropic content block to mirascope AssistantContentPart."""
     if content.type == "text":
         return Text(text=content.text)
@@ -55,12 +56,39 @@ def _decode_assistant_content(
         )
     elif content.type == "thinking":
         return Thought(thought=content.thinking)
+    elif content.type in ("server_tool_use", "web_search_tool_result"):
+        return None  # Skip server-side tool content, preserved in raw_message
     else:
         raise NotImplementedError(
             f"Support for content type `{content.type}` is not yet implemented."
         )
 
 
+def extract_tool_usage(
+    usage: (
+        anthropic_types.Usage
+        | anthropic_types.MessageDeltaUsage
+        | BetaUsage
+        | BetaMessageDeltaUsage
+    ),
+) -> list[ProviderToolUsage] | None:
+    """Extract provider tool usage from Anthropic usage object."""
+    server_tool_use = getattr(usage, "server_tool_use", None)
+    if server_tool_use is None:
+        return None
+
+    tools: list[ProviderToolUsage] = []
+
+    # Web search
+    web_search_requests = getattr(server_tool_use, "web_search_requests", None)
+    if web_search_requests and web_search_requests > 0:
+        tools.append(
+            ProviderToolUsage(name="web_search", call_count=web_search_requests)
+        )
+
+    return tools if tools else None
+
+
 def decode_usage(
     usage: anthropic_types.Usage | BetaUsage,
 ) -> Usage:
@@ -76,6 +104,7 @@ def decode_usage(
         cache_read_tokens=cache_read_tokens,
         cache_write_tokens=cache_write_tokens,
         reasoning_tokens=0,
+        provider_tool_usage=extract_tool_usage(usage),
         raw=usage,
     )
 
@@ -87,7 +116,11 @@ def decode_response(
     include_thoughts: bool,
 ) -> tuple[AssistantMessage, FinishReason | None, Usage]:
     """Convert Anthropic message to mirascope AssistantMessage and usage."""
-    content = [_decode_assistant_content(part) for part in response.content]
+    content = [
+        part
+        for part in (_decode_assistant_content(block) for block in response.content)
+        if part is not None
+    ]
     if not include_thoughts:
         content = [part for part in content if part.type != "thought"]
     assistant_message = AssistantMessage(
@@ -166,12 +199,14 @@ class _AnthropicChunkProcessor:
                     "type": "redacted_thinking",
                     "data": content_block.data,
                 }
+            elif content_block.type in ("server_tool_use", "web_search_tool_result"):
+                pass  # Skip server-side tool content
             else:
                 raise NotImplementedError
 
         elif event.type == "content_block_delta":
-            if self.current_block_param is None:  # pragma: no cover
-                raise RuntimeError("Received delta without a current block")
+            if self.current_block_param is None:
+                return  # Skip deltas for server-side tool content
 
             delta = event.delta
             if delta.type == "text_delta":
@@ -204,14 +239,16 @@ class _AnthropicChunkProcessor:
                         f"Received signature_delta for {self.current_block_param['type']} block"
                     )
                 self.current_block_param["signature"] += delta.signature
+            elif delta.type == "citations_delta":
+                pass  # Skip citations delta, preserved in raw_message
             else:
                 raise RuntimeError(
                     f"Received unsupported delta type: {delta.type}"
                 )  # pragma: no cover
 
         elif event.type == "content_block_stop":
-            if self.current_block_param is None:  # pragma: no cover
-                raise RuntimeError("Received stop without a current block")
+            if self.current_block_param is None:
+                return  # Skip stop for server-side tool content
 
             block_type = self.current_block_param["type"]
 
@@ -251,6 +288,7 @@ class _AnthropicChunkProcessor:
                 cache_read_tokens=usage.cache_read_input_tokens or 0,
                 cache_write_tokens=usage.cache_creation_input_tokens or 0,
                 reasoning_tokens=0,
+                provider_tool_usage=extract_tool_usage(usage),
             )
 
     def raw_message_chunk(self) -> RawMessageChunk:

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

@@ -14,12 +14,18 @@ from ....content import ContentPart, ImageMimeType
 from ....exceptions import FeatureNotSupportedError
 from ....formatting import (
     Format,
+    FormatSpec,
     FormattableT,
-    OutputParser,
     resolve_format,
 )
 from ....messages import AssistantMessage, Message, UserMessage
-from ....tools import FORMAT_TOOL_NAME, AnyToolSchema, BaseToolkit
+from ....tools import (
+    FORMAT_TOOL_NAME,
+    AnyToolSchema,
+    BaseToolkit,
+    ProviderTool,
+    WebSearchTool,
+)
 from ...base import _utils as _base_utils
 from ..model_id import AnthropicModelId, model_name
 
@@ -138,7 +144,7 @@ class MessageCreateKwargs(TypedDict, total=False):
     max_tokens: Required[int]
     messages: Sequence[anthropic_types.MessageParam]
     system: Sequence[anthropic_types.TextBlockParam] | Omit
-    tools: Sequence[anthropic_types.ToolParam] | Omit
+    tools: Sequence[anthropic_types.ToolUnionParam] | Omit
     tool_choice: anthropic_types.ToolChoiceParam | Omit
     temperature: float | Omit
     top_p: float | Omit
@@ -323,8 +329,18 @@ def _encode_messages(
 
 
 @lru_cache(maxsize=128)
-def convert_tool_to_tool_param(tool: AnyToolSchema) -> anthropic_types.ToolParam:
+def convert_tool_to_tool_param(
+    tool: AnyToolSchema | ProviderTool,
+) -> anthropic_types.ToolUnionParam:
     """Convert a single Mirascope tool to Anthropic tool format with caching."""
+    if isinstance(tool, WebSearchTool):
+        return anthropic_types.WebSearchTool20250305Param(
+            type="web_search_20250305", name="web_search"
+        )
+    if isinstance(tool, ProviderTool):
+        raise FeatureNotSupportedError(
+            f"Provider tool {tool.name}", provider_id="anthropic"
+        )
     schema_dict = tool.parameters.model_dump(by_alias=True, exclude_none=True)
     schema_dict["type"] = "object"
     return anthropic_types.ToolParam(
@@ -338,11 +354,8 @@ def encode_request(
     *,
     model_id: AnthropicModelId,
     messages: Sequence[Message],
-    tools: Sequence[AnyToolSchema] | BaseToolkit[AnyToolSchema] | None,
-    format: type[FormattableT]
-    | Format[FormattableT]
-    | OutputParser[FormattableT]
-    | None,
+    tools: BaseToolkit[AnyToolSchema],
+    format: FormatSpec[FormattableT] | None,
     params: Params,
 ) -> tuple[Sequence[Message], Format[FormattableT] | None, MessageCreateKwargs]:
     """Prepares a request for the Anthropic messages.create method."""
@@ -355,10 +368,8 @@ def encode_request(
         {"model": model_name(model_id), "max_tokens": max_tokens, **processed}
     )
 
-    tools = tools.tools if isinstance(tools, BaseToolkit) else tools or []
-
     # Check for strict tools - the non-beta API doesn't support them
-    if _base_utils.has_strict_tools(tools):
+    if _base_utils.has_strict_tools(tools.tools):
         raise FeatureNotSupportedError(
             feature="strict tools",
             provider_id="anthropic",
@@ -366,7 +377,7 @@ def encode_request(
             message="Anthropic provider does not support strict tools. Try the beta provider.",
         )
 
-    anthropic_tools = [convert_tool_to_tool_param(tool) for tool in tools]
+    anthropic_tools = [convert_tool_to_tool_param(tool) for tool in tools.tools]
     format = resolve_format(format, default_mode=DEFAULT_FORMAT_MODE)
     if format is not None:
         if format.mode == "strict":
@@ -378,7 +389,7 @@ def encode_request(
         if format.mode == "tool":
             format_tool_schema = format.create_tool_schema()
             anthropic_tools.append(convert_tool_to_tool_param(format_tool_schema))
-            if tools:
+            if tools.tools:
                 kwargs["tool_choice"] = {"type": "any"}
             else:
                 kwargs["tool_choice"] = {
@@ -395,7 +406,9 @@ def encode_request(
     if anthropic_tools:
         # Add cache control to the last tool for prompt caching
         last_tool = anthropic_tools[-1]
-        last_tool["cache_control"] = {"type": "ephemeral"}
+        last_tool["cache_control"] = anthropic_types.CacheControlEphemeralParam(
+            type="ephemeral"
+        )
         kwargs["tools"] = anthropic_tools
 
     system_message_content, remaining_messages = _base_utils.extract_system_message(