feat: Breaking change to Interactions API to refactor TextContent annotations to use specific citation types

PiperOrigin-RevId: 884559523

Author: Annhiluc

google/genai/_interactions/types/__init__.py

@@ -33,15 +33,18 @@
 from .content_stop import ContentStop as ContentStop
 from .image_config import ImageConfig as ImageConfig
 from .text_content import TextContent as TextContent
+from .url_citation import URLCitation as URLCitation
 from .allowed_tools import AllowedTools as AllowedTools
 from .audio_content import AudioContent as AudioContent
 from .content_delta import ContentDelta as ContentDelta
 from .content_param import ContentParam as ContentParam
 from .content_start import ContentStart as ContentStart
+from .file_citation import FileCitation as FileCitation
 from .image_content import ImageContent as ImageContent
 from .speech_config import SpeechConfig as SpeechConfig
 from .video_content import VideoContent as VideoContent
 from .function_param import FunctionParam as FunctionParam
+from .place_citation import PlaceCitation as PlaceCitation
 from .thinking_level import ThinkingLevel as ThinkingLevel
 from .thought_content import ThoughtContent as ThoughtContent
 from .annotation_param import AnnotationParam as AnnotationParam
@@ -52,14 +55,17 @@
 from .image_config_param import ImageConfigParam as ImageConfigParam
 from .text_content_param import TextContentParam as TextContentParam
 from .tool_choice_config import ToolChoiceConfig as ToolChoiceConfig
+from .url_citation_param import URLCitationParam as URLCitationParam
 from .url_context_result import URLContextResult as URLContextResult
 from .allowed_tools_param import AllowedToolsParam as AllowedToolsParam
 from .audio_content_param import AudioContentParam as AudioContentParam
+from .file_citation_param import FileCitationParam as FileCitationParam
 from .image_content_param import ImageContentParam as ImageContentParam
 from .speech_config_param import SpeechConfigParam as SpeechConfigParam
 from .video_content_param import VideoContentParam as VideoContentParam
 from .dynamic_agent_config import DynamicAgentConfig as DynamicAgentConfig
 from .google_search_result import GoogleSearchResult as GoogleSearchResult
+from .place_citation_param import PlaceCitationParam as PlaceCitationParam
 from .function_call_content import FunctionCallContent as FunctionCallContent
 from .interaction_sse_event import InteractionSSEEvent as InteractionSSEEvent
 from .thought_content_param import ThoughtContentParam as ThoughtContentParam

google/genai/_interactions/types/annotation.py

@@ -15,28 +15,14 @@
 
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-from typing import Optional
+from typing import Union
+from typing_extensions import Annotated, TypeAlias
 
-from .._models import BaseModel
+from .._utils import PropertyInfo
+from .url_citation import URLCitation
+from .file_citation import FileCitation
+from .place_citation import PlaceCitation
 
 __all__ = ["Annotation"]
 
-
-class Annotation(BaseModel):
-    """Citation information for model-generated content."""
-
-    end_index: Optional[int] = None
-    """End of the attributed segment, exclusive."""
-
-    source: Optional[str] = None
-    """Source attributed for a portion of the text.
-
-    Could be a URL, title, or
-    other identifier.
-    """
-
-    start_index: Optional[int] = None
-    """Start of segment of the response that is attributed to this source.
-
-    Index indicates the start of the segment, measured in bytes.
-    """
+Annotation: TypeAlias = Annotated[Union[URLCitation, FileCitation, PlaceCitation], PropertyInfo(discriminator="type")]

google/genai/_interactions/types/annotation_param.py

@@ -17,26 +17,13 @@
 
 from __future__ import annotations
 
-from typing_extensions import TypedDict
+from typing import Union
+from typing_extensions import TypeAlias
 
-__all__ = ["AnnotationParam"]
-
-
-class AnnotationParam(TypedDict, total=False):
-    """Citation information for model-generated content."""
-
-    end_index: int
-    """End of the attributed segment, exclusive."""
+from .url_citation_param import URLCitationParam
+from .file_citation_param import FileCitationParam
+from .place_citation_param import PlaceCitationParam
 
-    source: str
-    """Source attributed for a portion of the text.
-
-    Could be a URL, title, or
-    other identifier.
-    """
-
-    start_index: int
-    """Start of segment of the response that is attributed to this source.
+__all__ = ["AnnotationParam"]
 
-    Index indicates the start of the segment, measured in bytes.
-    """
+AnnotationParam: TypeAlias = Union[URLCitationParam, FileCitationParam, PlaceCitationParam]

google/genai/_interactions/types/content_delta.py

@@ -60,7 +60,6 @@
     "DeltaMCPServerToolResultResultItemsItem",
     "DeltaFileSearchCall",
     "DeltaFileSearchResult",
-    "DeltaFileSearchResultResult",
     "DeltaGoogleMapsCall",
     "DeltaGoogleMapsResult",
 ]
@@ -325,26 +324,13 @@ class DeltaFileSearchCall(BaseModel):
     """A signature hash for backend validation."""
 
 
-class DeltaFileSearchResultResult(BaseModel):
-    """The result of the File Search."""
-
-    file_search_store: Optional[str] = None
-    """The name of the file search store."""
-
-    text: Optional[str] = None
-    """The text of the search result."""
-
-    title: Optional[str] = None
-    """The title of the search result."""
-
-
 class DeltaFileSearchResult(BaseModel):
     call_id: str
     """ID to match the ID from the function call block."""
 
     type: Literal["file_search_result"]
 
-    result: Optional[List[DeltaFileSearchResultResult]] = None
+    result: Optional[List[object]] = None
 
     signature: Optional[str] = None
     """A signature hash for backend validation."""

google/genai/_interactions/types/file_citation.py

@@ -0,0 +1,44 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import Optional
+from typing_extensions import Literal
+
+from .._models import BaseModel
+
+__all__ = ["FileCitation"]
+
+
+class FileCitation(BaseModel):
+    """A file citation annotation."""
+
+    type: Literal["file_citation"]
+
+    document_uri: Optional[str] = None
+    """The URI of the file."""
+
+    end_index: Optional[int] = None
+    """End of the attributed segment, exclusive."""
+
+    file_name: Optional[str] = None
+    """The name of the file."""
+
+    source: Optional[str] = None
+    """Source attributed for a portion of the text."""
+
+    start_index: Optional[int] = None
+    """Start of segment of the response that is attributed to this source."""

google/genai/_interactions/types/file_citation_param.py

@@ -0,0 +1,43 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import Literal, Required, TypedDict
+
+__all__ = ["FileCitationParam"]
+
+
+class FileCitationParam(TypedDict, total=False):
+    """A file citation annotation."""
+
+    type: Required[Literal["file_citation"]]
+
+    document_uri: str
+    """The URI of the file."""
+
+    end_index: int
+    """End of the attributed segment, exclusive."""
+
+    file_name: str
+    """The name of the file."""
+
+    source: str
+    """Source attributed for a portion of the text."""
+
+    start_index: int
+    """Start of segment of the response that is attributed to this source."""

google/genai/_interactions/types/file_search_result_content.py

@@ -20,20 +20,7 @@
 
 from .._models import BaseModel
 
-__all__ = ["FileSearchResultContent", "Result"]
-
-
-class Result(BaseModel):
-    """The result of the File Search."""
-
-    file_search_store: Optional[str] = None
-    """The name of the file search store."""
-
-    text: Optional[str] = None
-    """The text of the search result."""
-
-    title: Optional[str] = None
-    """The title of the search result."""
+__all__ = ["FileSearchResultContent"]
 
 
 class FileSearchResultContent(BaseModel):
@@ -44,7 +31,7 @@ class FileSearchResultContent(BaseModel):
 
     type: Literal["file_search_result"]
 
-    result: Optional[List[Result]] = None
+    result: Optional[List[object]] = None
     """The results of the File Search."""
 
     signature: Optional[str] = None

google/genai/_interactions/types/file_search_result_content_param.py

@@ -24,20 +24,7 @@
 from .._utils import PropertyInfo
 from .._models import set_pydantic_config
 
-__all__ = ["FileSearchResultContentParam", "Result"]
-
-
-class Result(TypedDict, total=False):
-    """The result of the File Search."""
-
-    file_search_store: str
-    """The name of the file search store."""
-
-    text: str
-    """The text of the search result."""
-
-    title: str
-    """The title of the search result."""
+__all__ = ["FileSearchResultContentParam"]
 
 
 class FileSearchResultContentParam(TypedDict, total=False):
@@ -48,7 +35,7 @@ class FileSearchResultContentParam(TypedDict, total=False):
 
     type: Required[Literal["file_search_result"]]
 
-    result: Iterable[Result]
+    result: Iterable[object]
     """The results of the File Search."""
 
     signature: Annotated[Union[str, Base64FileInput], PropertyInfo(format="base64")]

google/genai/_interactions/types/google_search_result.py

@@ -27,9 +27,3 @@ class GoogleSearchResult(BaseModel):
 
     search_suggestions: Optional[str] = None
     """Web content snippet that can be embedded in a web page or an app webview."""
-
-    title: Optional[str] = None
-    """Title of the search result."""
-
-    url: Optional[str] = None
-    """URI reference of the search result."""

google/genai/_interactions/types/google_search_result_param.py

@@ -27,9 +27,3 @@ class GoogleSearchResultParam(TypedDict, total=False):
 
     search_suggestions: str
     """Web content snippet that can be embedded in a web page or an app webview."""
-
-    title: str
-    """Title of the search result."""
-
-    url: str
-    """URI reference of the search result."""