feat(interaction-api): Add grounding tool usage breakdown to Interaction Usage.

google/genai/_interactions/types/usage.py

@@ -18,11 +18,14 @@
 from typing import List, Optional
 from typing_extensions import Literal
 
+from pydantic import Field as FieldInfo
+
 from .._models import BaseModel
 
 __all__ = [
     "Usage",
     "CachedTokensByModality",
+    "GroundingToolCountByCategory",
     "InputTokensByModality",
     "OutputTokensByModality",
     "ToolUseTokensByModality",
@@ -39,6 +42,16 @@ class CachedTokensByModality(BaseModel):
     """Number of tokens for the modality."""
 
 
+class GroundingToolCountByCategory(BaseModel):
+    """The number of calls by a single tool category."""
+
+    count: Optional[int] = None
+    """The number of calls by the tool category."""
+
+    tool_category: Optional[Literal["search", "map", "retrieval"]] = FieldInfo(alias="toolCategory", default=None)
+    """The tool category associated with the count."""
+
+
 class InputTokensByModality(BaseModel):
     """The token count for a single response modality."""
 
@@ -75,6 +88,9 @@ class Usage(BaseModel):
     cached_tokens_by_modality: Optional[List[CachedTokensByModality]] = None
     """A breakdown of cached token usage by modality."""
 
+    grounding_tool_count_by_category: Optional[List[GroundingToolCountByCategory]] = None
+    """A breakdown of tool usage count by category."""
+
     input_tokens_by_modality: Optional[List[InputTokensByModality]] = None
     """A breakdown of input token usage by modality."""
 

google/genai/_interactions/types/usage_param.py

@@ -18,11 +18,14 @@
 from __future__ import annotations
 
 from typing import Iterable
-from typing_extensions import Literal, TypedDict
+from typing_extensions import Literal, Annotated, TypedDict
+
+from .._utils import PropertyInfo
 
 __all__ = [
     "UsageParam",
     "CachedTokensByModality",
+    "GroundingToolCountByCategory",
     "InputTokensByModality",
     "OutputTokensByModality",
     "ToolUseTokensByModality",
@@ -39,6 +42,16 @@ class CachedTokensByModality(TypedDict, total=False):
     """Number of tokens for the modality."""
 
 
+class GroundingToolCountByCategory(TypedDict, total=False):
+    """The number of calls by a single tool category."""
+
+    count: int
+    """The number of calls by the tool category."""
+
+    tool_category: Annotated[Literal["search", "map", "retrieval"], PropertyInfo(alias="toolCategory")]
+    """The tool category associated with the count."""
+
+
 class InputTokensByModality(TypedDict, total=False):
     """The token count for a single response modality."""
 
@@ -75,6 +88,9 @@ class UsageParam(TypedDict, total=False):
     cached_tokens_by_modality: Iterable[CachedTokensByModality]
     """A breakdown of cached token usage by modality."""
 
+    grounding_tool_count_by_category: Iterable[GroundingToolCountByCategory]
+    """A breakdown of tool usage count by category."""
+
     input_tokens_by_modality: Iterable[InputTokensByModality]
     """A breakdown of input token usage by modality."""