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

mirascope/llm/responses/usage.py

@@ -6,6 +6,38 @@ from dataclasses import dataclass
 from typing import Any, Literal
 
 
+@dataclass(kw_only=True)
+class ProviderToolUsage:
+    """Usage data for a provider's server-side tool.
+
+    Tracks usage of tools executed by the provider that have separate pricing
+    beyond standard token costs (e.g., web search, code execution).
+    """
+
+    name: str
+    """Tool name matching our ProviderTool.name (e.g., "web_search").
+
+    This is the consistent cross-provider identifier that matches
+    the corresponding Mirascope ProviderTool class (e.g., WebSearchTool.name).
+    """
+
+    call_count: int = 0
+    """Number of invocations/calls of this tool."""
+
+    duration_seconds: float | None = None
+    """Duration in seconds for time-based tools (e.g., code execution).
+
+    None if not applicable to this tool type.
+    """
+
+    metadata: dict[str, Any] | None = None
+    """Provider-specific metadata for debugging/analytics.
+
+    Examples:
+    - Google grounding: {"queries": ["query1", "query2"]}
+    """
+
+
 @dataclass(kw_only=True)
 class UsageDeltaChunk:
     """A chunk containing incremental token usage information from a streaming response.
@@ -31,6 +63,9 @@ class UsageDeltaChunk:
     reasoning_tokens: int = 0
     """Delta in reasoning/thinking tokens."""
 
+    provider_tool_usage: list[ProviderToolUsage] | None = None
+    """Provider tool usage (emitted in final chunk only)."""
+
 
 @dataclass(kw_only=True)
 class Usage:
@@ -86,6 +121,15 @@ class Usage:
     Will be 0 if not reported by the provider or if the model does not support reasoning.
     """
 
+    provider_tool_usage: list[ProviderToolUsage] | None = None
+    """Provider tool usage data for tools with separate pricing.
+
+    Tracks usage of server-side tools executed by the provider (e.g., web search,
+    code execution) that have pricing beyond standard token costs.
+
+    Will be None if no provider tools were used.
+    """
+
     raw: Any = None
     """The raw usage object from the provider."""
 

mirascope/llm/tools/__init__.py

@@ -2,6 +2,7 @@
 
 from .decorator import ToolDecorator, tool
 from .protocols import AsyncContextToolFn, AsyncToolFn, ContextToolFn, ToolFn
+from .provider_tools import ProviderTool
 from .tool_schema import (
     FORMAT_TOOL_NAME,
     AnyToolFn,
@@ -19,21 +20,38 @@ from .toolkit import (
     ToolkitT,
 )
 from .tools import AsyncContextTool, AsyncTool, ContextTool, Tool, ToolT
+from .types import (
+    AnyTools,
+    AsyncContextTools,
+    AsyncTools,
+    ContextTools,
+    Tools,
+    normalize_async_context_tools,
+    normalize_async_tools,
+    normalize_context_tools,
+    normalize_tools,
+)
+from .web_search_tool import WebSearchTool
 
 __all__ = [
     "FORMAT_TOOL_NAME",
     "AnyToolFn",
     "AnyToolSchema",
+    "AnyTools",
     "AsyncContextTool",
     "AsyncContextToolFn",
     "AsyncContextToolkit",
+    "AsyncContextTools",
     "AsyncTool",
     "AsyncToolFn",
     "AsyncToolkit",
+    "AsyncTools",
     "BaseToolkit",
     "ContextTool",
     "ContextToolFn",
     "ContextToolkit",
+    "ContextTools",
+    "ProviderTool",
     "Tool",
     "ToolDecorator",
     "ToolFn",
@@ -43,5 +61,11 @@ __all__ = [
     "ToolT",
     "Toolkit",
     "ToolkitT",
+    "Tools",
+    "WebSearchTool",
+    "normalize_async_context_tools",
+    "normalize_async_tools",
+    "normalize_context_tools",
+    "normalize_tools",
     "tool",
 ]

mirascope/llm/tools/provider_tools.py

@@ -0,0 +1,18 @@
+"""Base class for provider-native tools."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ProviderTool:
+    """Base class for tools executed natively by providers.
+
+    Unlike regular tools which define functions that you execute locally,
+    provider tools are capabilities built into the provider's API.
+    The provider handles execution entirely server-side.
+
+    Provider tools have no sync/async distinction since they are not
+    executed by your code - they are configuration passed to the provider.
+    """
+
+    name: str

mirascope/llm/tools/tool_schema.py

@@ -40,8 +40,7 @@ ToolFnT = TypeVar(
     covariant=True,
 )
 
-AnyToolSchema: TypeAlias = "ToolSchema[AnyToolFn]"
-ToolSchemaT = TypeVar("ToolSchemaT", bound=AnyToolSchema, covariant=True)
+ToolSchemaT = TypeVar("ToolSchemaT", bound="ToolSchema[AnyToolFn]", covariant=True)
 
 
 ModelJsonSchema = TypedDict(
@@ -317,3 +316,6 @@ class ToolSchema(Generic[ToolFnT]):
         is performed.
         """
         return tool_call.name == self.name
+
+
+AnyToolSchema: TypeAlias = ToolSchema[AnyToolFn]

mirascope/llm/tools/toolkit.py

@@ -6,6 +6,7 @@ from ..content import ToolCall, ToolOutput
 from ..context import Context, DepsT
 from ..exceptions import ToolNotFoundError
 from ..types import Jsonable
+from .provider_tools import ProviderTool
 from .tool_schema import ToolSchemaT
 from .tools import AsyncContextTool, AsyncTool, ContextTool, Tool
 
@@ -24,13 +25,24 @@ class BaseToolkit(Generic[ToolSchemaT]):
     including name validation and tool lookup.
     """
 
-    tools: Sequence[ToolSchemaT]
+    tools: Sequence[ToolSchemaT | ProviderTool]
     """The tools included in the toolkit."""
 
     tools_dict: dict[str, ToolSchemaT]
-    """A mapping from tool names to tools in the toolkit."""
+    """A mapping from tool names to tools in the toolkit.
 
-    def __init__(self, tools: Sequence[ToolSchemaT] | None) -> None:
+    This dict does not include any `ProviderTool`s, since they do not correspond
+    to tool calls that your code executes.
+    """
+
+    provider_tools_dict: dict[str, ProviderTool]
+    """A mapping from provider tool names to provider tools in the toolkit.
+
+    Provider tools are capabilities built into the provider's API (like web search)
+    that are executed server-side, not by your code.
+    """
+
+    def __init__(self, tools: Sequence[ToolSchemaT | ProviderTool] | None) -> None:
         """Initialize the toolkit with a collection of tools.
 
         Args:
@@ -41,10 +53,16 @@ class BaseToolkit(Generic[ToolSchemaT]):
         """
         self.tools = tools or []
         self.tools_dict = {}
+        self.provider_tools_dict = {}
         for tool in self.tools:
-            if tool.name in self.tools_dict:
-                raise ValueError(f"Multiple tools with name: {tool.name}")
-            self.tools_dict[tool.name] = tool
+            if isinstance(tool, ProviderTool):
+                if tool.name in self.provider_tools_dict:
+                    raise ValueError(f"Multiple provider tools with name: {tool.name}")
+                self.provider_tools_dict[tool.name] = tool
+            else:
+                if tool.name in self.tools_dict:
+                    raise ValueError(f"Multiple tools with name: {tool.name}")
+                self.tools_dict[tool.name] = tool
 
     def get(self, tool_call: ToolCall) -> ToolSchemaT:
         """Get a tool that can execute a specific tool call.

mirascope/llm/tools/types.py

@@ -0,0 +1,112 @@
+"""Type aliases for tool parameter types used in provider signatures."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TypeAlias
+from typing_extensions import TypeAliasType
+
+from ..context import DepsT
+from .provider_tools import ProviderTool
+from .tool_schema import AnyToolSchema
+from .toolkit import (
+    AsyncContextToolkit,
+    AsyncToolkit,
+    BaseToolkit,
+    ContextToolkit,
+    Toolkit,
+)
+from .tools import AsyncContextTool, AsyncTool, ContextTool, Tool
+
+AnyTools: TypeAlias = (
+    Sequence[AnyToolSchema | ProviderTool] | BaseToolkit[AnyToolSchema]
+)
+
+Tools: TypeAlias = Sequence[Tool | ProviderTool] | Toolkit
+"""Type alias for sync tool parameters: a sequence of Tools or a Toolkit."""
+
+AsyncTools: TypeAlias = Sequence[AsyncTool | ProviderTool] | AsyncToolkit
+"""Type alias for async tool parameters: a sequence of AsyncTools or an AsyncToolkit."""
+
+ContextTools = TypeAliasType(
+    "ContextTools",
+    Sequence[Tool | ContextTool[DepsT] | ProviderTool] | ContextToolkit[DepsT],
+    type_params=(DepsT,),
+)
+"""Type alias for sync context tool parameters: a sequence of Tools/ContextTools or a ContextToolkit."""
+
+AsyncContextTools = TypeAliasType(
+    "AsyncContextTools",
+    Sequence[AsyncTool | AsyncContextTool[DepsT] | ProviderTool]
+    | AsyncContextToolkit[DepsT],
+    type_params=(DepsT,),
+)
+"""Type alias for async context tool parameters: a sequence of AsyncTools/AsyncContextTools or an AsyncContextToolkit."""
+
+
+def normalize_tools(tools: Tools | None) -> Toolkit:
+    """Normalize tools input to a Toolkit.
+
+    Args:
+        tools: A sequence of Tools, a Toolkit, or None.
+
+    Returns:
+        A Toolkit containing the tools (or an empty Toolkit if None).
+    """
+    if tools is None:
+        return Toolkit(None)
+    if isinstance(tools, Toolkit):
+        return tools
+    return Toolkit(tools)
+
+
+def normalize_async_tools(tools: AsyncTools | None) -> AsyncToolkit:
+    """Normalize async tools input to an AsyncToolkit.
+
+    Args:
+        tools: A sequence of AsyncTools, an AsyncToolkit, or None.
+
+    Returns:
+        An AsyncToolkit containing the tools (or an empty AsyncToolkit if None).
+    """
+    if tools is None:
+        return AsyncToolkit(None)
+    if isinstance(tools, AsyncToolkit):
+        return tools
+    return AsyncToolkit(tools)
+
+
+def normalize_context_tools(
+    tools: ContextTools[DepsT] | None,
+) -> ContextToolkit[DepsT]:
+    """Normalize context tools input to a ContextToolkit.
+
+    Args:
+        tools: A sequence of Tools/ContextTools, a ContextToolkit, or None.
+
+    Returns:
+        A ContextToolkit containing the tools (or an empty ContextToolkit if None).
+    """
+    if tools is None:
+        return ContextToolkit(None)
+    if isinstance(tools, ContextToolkit):
+        return tools
+    return ContextToolkit(tools)
+
+
+def normalize_async_context_tools(
+    tools: AsyncContextTools[DepsT] | None,
+) -> AsyncContextToolkit[DepsT]:
+    """Normalize async context tools input to an AsyncContextToolkit.
+
+    Args:
+        tools: A sequence of AsyncTools/AsyncContextTools, an AsyncContextToolkit, or None.
+
+    Returns:
+        An AsyncContextToolkit containing the tools (or an empty AsyncContextToolkit if None).
+    """
+    if tools is None:
+        return AsyncContextToolkit(None)
+    if isinstance(tools, AsyncContextToolkit):
+        return tools
+    return AsyncContextToolkit(tools)

mirascope/llm/tools/web_search_tool.py

@@ -0,0 +1,32 @@
+"""Web search tool for provider-native web search capabilities."""
+
+from dataclasses import dataclass, field
+
+from .provider_tools import ProviderTool
+
+
+@dataclass(frozen=True)
+class WebSearchTool(ProviderTool):
+    """Web search tool that allows the model to search the internet.
+
+    This is a provider tool - the search is executed server-side by the provider,
+    not by your code. The model decides when to search based on the prompt,
+    and the provider returns search results with citations.
+
+    Supported providers include Anthropic, Google, and OpenAI (when using the Responses API).
+
+    Example:
+        ```python
+        from mirascope import llm
+
+        @llm.call("anthropic/claude-sonnet-4-5", tools=[llm.WebSearchTool()])
+        def search_web(query: str) -> str:
+            return f"Search the web for: {query}"
+
+        response = search_web("Who won the 2024 Super Bowl?")
+        print(response.text())  # Response includes citations from web search
+        ```
+    """
+
+    name: str = field(default="web_search", init=False)
+    """The tool name. Always "web_search" for this tool type."""

mirascope/ops/__init__.py

@@ -12,9 +12,18 @@ stub_module_if_missing("mirascope.ops", "ops")
 # ruff: noqa: E402
 from ._internal.configuration import configure, tracer_context
 from ._internal.context import propagated_context
-from ._internal.instrumentation.llm import (
+from ._internal.instrumentation import (
+    instrument_anthropic,
+    instrument_google_genai,
     instrument_llm,
+    instrument_openai,
+    is_anthropic_instrumented,
+    is_google_genai_instrumented,
+    is_openai_instrumented,
+    uninstrument_anthropic,
+    uninstrument_google_genai,
     uninstrument_llm,
+    uninstrument_openai,
 )
 from ._internal.propagation import (
     ContextPropagator,
@@ -99,13 +108,22 @@ __all__ = [
     "extract_session_id",
     "get_propagator",
     "inject_context",
+    "instrument_anthropic",
+    "instrument_google_genai",
     "instrument_llm",
+    "instrument_openai",
+    "is_anthropic_instrumented",
+    "is_google_genai_instrumented",
+    "is_openai_instrumented",
     "propagated_context",
     "reset_propagator",
     "session",
     "span",
     "trace",
     "tracer_context",
+    "uninstrument_anthropic",
+    "uninstrument_google_genai",
     "uninstrument_llm",
+    "uninstrument_openai",
     "version",
 ]

mirascope/ops/_internal/instrumentation/__init__.py

@@ -1,8 +1,28 @@
 """Instrumentation modules for various frameworks and libraries."""
 
 from .llm import instrument_llm, uninstrument_llm
+from .providers import (
+    instrument_anthropic,
+    instrument_google_genai,
+    instrument_openai,
+    is_anthropic_instrumented,
+    is_google_genai_instrumented,
+    is_openai_instrumented,
+    uninstrument_anthropic,
+    uninstrument_google_genai,
+    uninstrument_openai,
+)
 
 __all__ = [
+    "instrument_anthropic",
+    "instrument_google_genai",
     "instrument_llm",
+    "instrument_openai",
+    "is_anthropic_instrumented",
+    "is_google_genai_instrumented",
+    "is_openai_instrumented",
+    "uninstrument_anthropic",
+    "uninstrument_google_genai",
     "uninstrument_llm",
+    "uninstrument_openai",
 ]

mirascope/ops/_internal/instrumentation/llm/common.py

@@ -17,10 +17,11 @@ from opentelemetry.semconv.attributes import error_attributes as ErrorAttributes
 from opentelemetry.trace import SpanKind, Status, StatusCode
 
 from .....llm import (
-    AnyToolFn,
+    AnyTools,
     AnyToolSchema,
     BaseToolkit,
     Format,
+    FormatSpec,
     FormattableT,
     Jsonable,
     Message,
@@ -28,9 +29,9 @@ from .....llm import (
     ModelId,
     Params,
     ProviderId,
+    ProviderTool,
     RootResponse,
     ToolkitT,
-    ToolSchema,
 )
 from ...configuration import get_tracer
 from ...utils import json_dumps
@@ -45,6 +46,7 @@ from .serialize import (
     serialize_mirascope_cost,
     serialize_mirascope_messages,
     serialize_mirascope_usage,
+    serialize_tools,
 )
 
 logger = logging.getLogger(__name__)
@@ -64,10 +66,7 @@ else:
     Tracer = None
 
 
-ToolsParam: TypeAlias = (
-    Sequence[ToolSchema[AnyToolFn]] | BaseToolkit[AnyToolSchema] | None
-)
-FormatParam: TypeAlias = Format[FormattableT] | None
+FormatParam: TypeAlias = FormatSpec[FormattableT] | None
 ParamsDict: TypeAlias = Mapping[str, str | int | float | bool | Sequence[str] | None]
 SpanAttributes: TypeAlias = Mapping[str, AttributeValue]
 AttributeSetter: TypeAlias = Callable[[str, AttributeValue], None]
@@ -180,53 +179,13 @@ def _assign_request_message_attributes(
     )
 
 
-def _collect_tool_schemas(
-    tools: Sequence[ToolSchema[AnyToolFn]] | BaseToolkit[AnyToolSchema],
-) -> list[ToolSchema[AnyToolFn]]:
-    """Collect ToolSchema instances from a tools parameter."""
-    iterable = list(tools.tools) if isinstance(tools, BaseToolkit) else list(tools)
-    schemas: list[ToolSchema[AnyToolFn]] = []
-    for tool in iterable:
-        if isinstance(tool, ToolSchema):
-            schemas.append(tool)
-    return schemas
-
-
-def _serialize_tool_definitions(
-    tools: ToolsParam,
-    format: FormatParam = None,
-) -> str | None:
-    """Serialize tool definitions to JSON for span attributes."""
-    if tools is None:
-        tool_schemas: list[ToolSchema[AnyToolFn]] = []
-    else:
-        tool_schemas = _collect_tool_schemas(tools)
-
-    if isinstance(format, Format) and format.mode == "tool":
-        tool_schemas.append(format.create_tool_schema())
-
-    if not tool_schemas:
-        return None
-    definitions: list[dict[str, str | int | bool | dict[str, str | int | bool]]] = []
-    for tool in tool_schemas:
-        tool_def: dict[str, str | int | bool | dict[str, str | int | bool]] = {
-            "name": tool.name,
-            "description": tool.description,
-            "parameters": tool.parameters.model_dump(by_alias=True, mode="json"),
-        }
-        if tool.strict is not None:
-            tool_def["strict"] = tool.strict
-        definitions.append(tool_def)
-    return json_dumps(definitions)
-
-
 def _build_request_attributes(
     *,
     operation: str,
     provider: ProviderId,
     model_id: ModelId,
     messages: Sequence[Message],
-    tools: ToolsParam,
+    tools: AnyTools | None,
     format: FormatParam,
     params: ParamsDict,
 ) -> dict[str, AttributeValue]:
@@ -244,7 +203,18 @@ def _build_request_attributes(
         messages=messages,
     )
 
-    tool_payload = _serialize_tool_definitions(tools, format=format)
+    tool_schemas: list[AnyToolSchema | ProviderTool] = []
+    if tools is None:
+        tool_schemas = []
+    elif isinstance(tools, BaseToolkit):
+        tool_schemas = list(tools.tools)
+    else:
+        tool_schemas = list(tools)
+
+    if isinstance(format, Format) and format.mode == "tool":
+        tool_schemas.append(format.create_tool_schema())
+
+    tool_payload = serialize_tools(tool_schemas)
     if tool_payload:
         # The incubating semconv module does not yet expose a constant for this key.
         attrs["gen_ai.tool.definitions"] = tool_payload
@@ -477,7 +447,7 @@ def start_model_span(
     model: Model,
     *,
     messages: Sequence[Message],
-    tools: ToolsParam,
+    tools: AnyTools | None,
     format: FormatParam,
     activate: bool = True,
 ) -> Iterator[SpanContext]: