mirascope 2.0.1__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

@@ -22,6 +22,7 @@ from docstring_parser import parse
 from pydantic import BaseModel, Field, create_model
 from pydantic.fields import FieldInfo
 
+from ..._utils import copy_function_metadata
 from ..content import ToolCall
 from ..types import Jsonable
 from .protocols import AsyncContextToolFn, AsyncToolFn, ContextToolFn, ToolFn
@@ -39,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(
@@ -159,11 +159,14 @@ class ToolSchema(Generic[ToolFnT]):
 
     strict: bool | None
     """Whether the tool should use strict mode when supported by the model.
-    
-    If set to None, will use the provider's default setting (usually as strict as 
+
+    If set to None, will use the provider's default setting (usually as strict as
     possible).
     """
 
+    __name__: str
+    """The name of the underlying function (preserved for decorator stacking)."""
+
     def __hash__(self) -> int:
         if not hasattr(self, "_hash"):
             self._hash = hash(
@@ -200,6 +203,7 @@ class ToolSchema(Generic[ToolFnT]):
         self.description = description
         self.parameters = parameters
         self.strict = strict
+        copy_function_metadata(self, fn)
 
     @classmethod
     def from_function(
@@ -312,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/closure.py

@@ -738,12 +738,15 @@ class _DependencyCollector:
             # For Python 3.13+
             return definition.func  # pyright: ignore[reportFunctionMemberAccess] # pragma: no cover
 
+        # Handle objects with .fn but no __qualname__ (e.g., old-style wrappers).
+        # With copy_function_metadata() now copying __qualname__ to ToolSchema, Prompt,
+        # Call, etc., this branch is no longer reached in normal usage.
         if (
             (wrapped_function := getattr(definition, "fn", None)) is not None
             and not hasattr(definition, "__qualname__")
             and callable(wrapped_function)
         ):
-            return wrapped_function
+            return wrapped_function  # pragma: no cover
 
         return definition
 

mirascope/ops/_internal/exporters/exporters.py

@@ -20,14 +20,17 @@ from ....api._generated.traces.types import (
     TracesCreateRequestResourceSpansItemResource,
     TracesCreateRequestResourceSpansItemResourceAttributesItem,
     TracesCreateRequestResourceSpansItemResourceAttributesItemValue,
+    TracesCreateRequestResourceSpansItemResourceAttributesItemValueArrayValue,
     TracesCreateRequestResourceSpansItemScopeSpansItem,
     TracesCreateRequestResourceSpansItemScopeSpansItemScope,
     TracesCreateRequestResourceSpansItemScopeSpansItemSpansItem,
     TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItem,
     TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItemValue,
+    TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItemValueArrayValue,
     TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemStatus,
 )
 from ....api.client import Mirascope
+from .utils import to_otlp_any_value
 
 logger = logging.getLogger(__name__)
 
@@ -282,17 +285,7 @@ class MirascopeOTLPExporter(SpanExporter):
     def _convert_attribute_value(
         self, value: AttributeValue
     ) -> TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItemValue:
-        """Convert OpenTelemetry AttributeValue to Mirascope API's KeyValueValue.
-
-        This conversion is necessary because the Fern-generated API client
-        expects KeyValueValue objects, not OpenTelemetry's AttributeValue types.
-
-        Args:
-            value: An OpenTelemetry AttributeValue (bool, int, float, str, or Sequence)
-
-        Returns:
-            A KeyValueValue object for the Mirascope API
-        """
+        """Convert OpenTelemetry AttributeValue to Mirascope API's KeyValueValue."""
         match value:
             case str():
                 return TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItemValue(
@@ -312,49 +305,21 @@ class MirascopeOTLPExporter(SpanExporter):
                 )
             case _:
                 return TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItemValue(
-                    string_value=str(list(value))
+                    array_value=TracesCreateRequestResourceSpansItemScopeSpansItemSpansItemAttributesItemValueArrayValue(
+                        values=[to_otlp_any_value(v) for v in value]
+                    )
                 )
 
     def _convert_event_attribute_value(
         self, value: AttributeValue
     ) -> dict[str, object]:
-        """Convert OpenTelemetry AttributeValue to OTLP event attribute value format.
-
-        This uses the OTLP JSON format with typed value wrappers (e.g., stringValue, intValue).
-
-        Args:
-            value: An OpenTelemetry AttributeValue (bool, int, float, str, or Sequence)
-
-        Returns:
-            A dict with the typed value (e.g., {"stringValue": "..."})
-        """
-        match value:
-            case str():
-                return {"stringValue": value}
-            case bool():
-                return {"boolValue": value}
-            case int():
-                return {"intValue": str(value)}
-            case float():
-                return {"doubleValue": value}
-            case _:
-                # Sequences - convert to string representation
-                return {"stringValue": str(list(value))}
+        """Convert OpenTelemetry AttributeValue to OTLP event attribute value format."""
+        return to_otlp_any_value(value)
 
     def _convert_resource_attribute_value(
         self, value: AttributeValue
     ) -> TracesCreateRequestResourceSpansItemResourceAttributesItemValue:
-        """Convert OpenTelemetry AttributeValue to Mirascope API's resource KeyValueValue.
-
-        This conversion is necessary because the Fern-generated API client
-        expects KeyValueValue objects, not OpenTelemetry's AttributeValue types.
-
-        Args:
-            value: An OpenTelemetry AttributeValue (bool, int, float, str, or Sequence)
-
-        Returns:
-            A KeyValueValue object for the Mirascope API resource attributes
-        """
+        """Convert OpenTelemetry AttributeValue to Mirascope API's resource KeyValueValue."""
         match value:
             case str():
                 return TracesCreateRequestResourceSpansItemResourceAttributesItemValue(
@@ -374,7 +339,9 @@ class MirascopeOTLPExporter(SpanExporter):
                 )
             case _:
                 return TracesCreateRequestResourceSpansItemResourceAttributesItemValue(
-                    string_value=str(list(value))
+                    array_value=TracesCreateRequestResourceSpansItemResourceAttributesItemValueArrayValue(
+                        values=[to_otlp_any_value(v) for v in value]
+                    )
                 )
 
     def shutdown(self) -> None:

mirascope/ops/_internal/exporters/utils.py

@@ -4,6 +4,43 @@ This module provides helper functions for formatting and converting
 OpenTelemetry data types for export.
 """
 
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+
+from opentelemetry.util.types import AttributeValue
+
+
+def to_otlp_any_value(value: AttributeValue) -> dict[str, object]:
+    """Convert AttributeValue to OTLP AnyValue (dict form).
+
+    - string/bool/int/float are converted to stringValue/boolValue/intValue/doubleValue
+    - Sequence (excluding str/bytes/Mapping) is converted to arrayValue.values
+    - Unsupported types fallback to stringValue=str(value)
+
+    Args:
+        value: An OpenTelemetry AttributeValue (bool, int, float, str, or Sequence)
+
+    Returns:
+        A dict representing OTLP AnyValue (e.g., {"stringValue": "..."})
+    """
+    match value:
+        case str():
+            return {"stringValue": value}
+        case bool():
+            return {"boolValue": value}
+        case int():
+            return {"intValue": str(value)}
+        case float():
+            return {"doubleValue": value}
+        case _ if isinstance(value, bytes | bytearray | memoryview | Mapping):
+            return {"stringValue": str(value)}
+        case _ if isinstance(value, Sequence):
+            values = [to_otlp_any_value(v) for v in value]
+            return {"arrayValue": {"values": values}}
+        case _:
+            return {"stringValue": str(value)}
+
 
 def format_trace_id(trace_id: int) -> str:
     """Format a trace ID as a 32-character hex string.

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",
 ]