Improve docs

dlarocque · dlarocque · commit 49255b91266e · 2025-05-26T14:11:24.000-04:00
diff --git a/common/api-review/ai.api.md b/common/api-review/ai.api.md
@@ -491,7 +491,6 @@ export interface GoogleSearch {
 
 // @public
 export interface GoogleSearchTool {
-    // (undocumented)
     googleSearch: GoogleSearch;
 }
 
@@ -518,7 +517,7 @@ export interface GroundingMetadata {
     groundingAttributions: GroundingAttribution[];
     groundingChunks?: GroundingChunk[];
     groundingSupports?: GroundingSupport[];
-    // (undocumented)
+    // @deprecated (undocumented)
     retrievalQueries?: string[];
     searchEntryPoint?: SearchEntrypoint;
     webSearchQueries?: string[];
@@ -874,8 +873,6 @@ export enum SchemaType {
 // @public
 export interface SearchEntrypoint {
     renderedContent: string;
-    renderedContentElement: HTMLDivElement;
-    sdkBlob?: string;
 }
 
 // @public
@@ -992,6 +989,7 @@ export interface WebAttribution {
 
 // @public
 export interface WebGroundingChunk {
+    domain?: string;
     title?: string;
     uri?: string;
 }
diff --git a/docs-devsite/ai.googlesearch.md b/docs-devsite/ai.googlesearch.md
@@ -10,7 +10,9 @@ https://github.com/firebase/firebase-js-sdk
 {% endcomment %}
 
 # GoogleSearch interface
-TODO(dlarocque)
+Configuration for the [GoogleSearchTool](./ai.googlesearchtool.md#googlesearchtool_interface)<!-- -->.
+
+Currently, this interface is empty and serves as a placeholder for future configuration options.
 
 <b>Signature:</b>
 
diff --git a/docs-devsite/ai.googlesearchtool.md b/docs-devsite/ai.googlesearchtool.md
@@ -10,7 +10,9 @@ https://github.com/firebase/firebase-js-sdk
 {% endcomment %}
 
 # GoogleSearchTool interface
-TODO(dlarocque)
+A tool that allows the generative model to connect to Google Search to access and incorporate up-to-date information from the web into its responses.
+
+When this tool is used, the model's responses may include "Grounded Results" which are subject to the Grounding with Google Search terms outlined in the [Service Specific Terms](https://cloud.google.com/terms/service-terms)<!-- -->.
 
 <b>Signature:</b>
 
@@ -22,10 +24,12 @@ export declare interface GoogleSearchTool
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [googleSearch](./ai.googlesearchtool.md#googlesearchtoolgooglesearch) | [GoogleSearch](./ai.googlesearch.md#googlesearch_interface) |  |
+|  [googleSearch](./ai.googlesearchtool.md#googlesearchtoolgooglesearch) | [GoogleSearch](./ai.googlesearch.md#googlesearch_interface) | Specifies the Google Search configuration. Currently, this is an empty object, but it's reserved for future configuration options. |
 
 ## GoogleSearchTool.googleSearch
 
+Specifies the Google Search configuration. Currently, this is an empty object, but it's reserved for future configuration options.
+
 <b>Signature:</b>
 
 ```typescript
diff --git a/docs-devsite/ai.groundingchunk.md b/docs-devsite/ai.groundingchunk.md
@@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk
 {% endcomment %}
 
 # GroundingChunk interface
-A grounding chunk.
+Represents a chunk of retrieved data that supports a claim in the model's response. This is part of the grounding information provided when grounding is enabled.
 
 <b>Signature:</b>
 
@@ -22,11 +22,11 @@ export interface GroundingChunk
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [web](./ai.groundingchunk.md#groundingchunkweb) | [WebGroundingChunk](./ai.webgroundingchunk.md#webgroundingchunk_interface) | A grounding chunk from the web. |
+|  [web](./ai.groundingchunk.md#groundingchunkweb) | [WebGroundingChunk](./ai.webgroundingchunk.md#webgroundingchunk_interface) | Contains details if the grounding chunk is from a web source. |
 
 ## GroundingChunk.web
 
-A grounding chunk from the web.
+Contains details if the grounding chunk is from a web source.
 
 <b>Signature:</b>
 
diff --git a/docs-devsite/ai.groundingmetadata.md b/docs-devsite/ai.groundingmetadata.md
@@ -23,11 +23,11 @@ export interface GroundingMetadata
 |  Property | Type | Description |
 |  --- | --- | --- |
 |  [groundingAttributions](./ai.groundingmetadata.md#groundingmetadatagroundingattributions) | [GroundingAttribution](./ai.groundingattribution.md#groundingattribution_interface)<!-- -->\[\] |  |
-|  [groundingChunks](./ai.groundingmetadata.md#groundingmetadatagroundingchunks) | [GroundingChunk](./ai.groundingchunk.md#groundingchunk_interface)<!-- -->\[\] | List of supporting references retrieved from the specified grounding source. |
-|  [groundingSupports](./ai.groundingmetadata.md#groundingmetadatagroundingsupports) | [GroundingSupport](./ai.groundingsupport.md#groundingsupport_interface)<!-- -->\[\] | List of grounding support. |
+|  [groundingChunks](./ai.groundingmetadata.md#groundingmetadatagroundingchunks) | [GroundingChunk](./ai.groundingchunk.md#groundingchunk_interface)<!-- -->\[\] | A list of [GroundingChunk](./ai.groundingchunk.md#groundingchunk_interface) objects. Each chunk represents a piece of retrieved content (e.g. from a web page). that the model used to ground its response. |
+|  [groundingSupports](./ai.groundingmetadata.md#groundingmetadatagroundingsupports) | [GroundingSupport](./ai.groundingsupport.md#groundingsupport_interface)<!-- -->\[\] | A list of [GroundingSupport](./ai.groundingsupport.md#groundingsupport_interface) objects. Each object details how specific segments of the model's response are supported by the <code>groundingChunks</code>. |
 |  [retrievalQueries](./ai.groundingmetadata.md#groundingmetadataretrievalqueries) | string\[\] |  |
-|  [searchEntryPoint](./ai.groundingmetadata.md#groundingmetadatasearchentrypoint) | [SearchEntrypoint](./ai.searchentrypoint.md#searchentrypoint_interface) | Google search entry for the following web searches. |
-|  [webSearchQueries](./ai.groundingmetadata.md#groundingmetadatawebsearchqueries) | string\[\] | Web search queries for the following-up web search. |
+|  [searchEntryPoint](./ai.groundingmetadata.md#groundingmetadatasearchentrypoint) | [SearchEntrypoint](./ai.searchentrypoint.md#searchentrypoint_interface) | Google search entry for the following web searches. An HTML/CSS snippet that can be embedded in a web page to display a Google Search Entry point for follow-up web searches related to the model's response. |
+|  [webSearchQueries](./ai.groundingmetadata.md#groundingmetadatawebsearchqueries) | string\[\] | A list of web search queries that the model performed to gather the grounding information. These can be used to allow users to explore the search results themselves. |
 
 ## GroundingMetadata.groundingAttributions
 
@@ -43,7 +43,7 @@ groundingAttributions: GroundingAttribution[];
 
 ## GroundingMetadata.groundingChunks
 
-List of supporting references retrieved from the specified grounding source.
+A list of [GroundingChunk](./ai.groundingchunk.md#groundingchunk_interface) objects. Each chunk represents a piece of retrieved content (e.g. from a web page). that the model used to ground its response.
 
 <b>Signature:</b>
 
@@ -53,7 +53,7 @@ groundingChunks?: GroundingChunk[];
 
 ## GroundingMetadata.groundingSupports
 
-List of grounding support.
+A list of [GroundingSupport](./ai.groundingsupport.md#groundingsupport_interface) objects. Each object details how specific segments of the model's response are supported by the `groundingChunks`<!-- -->.
 
 <b>Signature:</b>
 
@@ -63,6 +63,11 @@ groundingSupports?: GroundingSupport[];
 
 ## GroundingMetadata.retrievalQueries
 
+> Warning: This API is now obsolete.
+> 
+> Use [GroundingMetadata.groundingSupports](./ai.groundingmetadata.md#groundingmetadatagroundingsupports) instead.
+> 
+
 <b>Signature:</b>
 
 ```typescript
@@ -71,7 +76,7 @@ retrievalQueries?: string[];
 
 ## GroundingMetadata.searchEntryPoint
 
-Google search entry for the following web searches.
+Google search entry for the following web searches. An HTML/CSS snippet that can be embedded in a web page to display a Google Search Entry point for follow-up web searches related to the model's response.
 
 <b>Signature:</b>
 
@@ -81,7 +86,7 @@ searchEntryPoint?: SearchEntrypoint;
 
 ## GroundingMetadata.webSearchQueries
 
-Web search queries for the following-up web search.
+A list of web search queries that the model performed to gather the grounding information. These can be used to allow users to explore the search results themselves.
 
 <b>Signature:</b>
 
diff --git a/docs-devsite/ai.groundingsupport.md b/docs-devsite/ai.groundingsupport.md
@@ -10,7 +10,7 @@ https://github.com/firebase/firebase-js-sdk
 {% endcomment %}
 
 # GroundingSupport interface
-Grounding support.
+Provides information about how a specific segment of the model's response is supported by the retrieved grounding chunks.
 
 <b>Signature:</b>
 
@@ -22,13 +22,13 @@ export interface GroundingSupport
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [confidenceScores](./ai.groundingsupport.md#groundingsupportconfidencescores) | number\[\] | Confidence score of the supporting references. Ranges from 0 to 1, where 1 is the most confident. This list must have the same size has the <code>groundingChunkIndices</code>. |
-|  [groundingChunkIndices](./ai.groundingsupport.md#groundingsupportgroundingchunkindices) | number\[\] | A list of indices into <code>groundingChunk</code> specifying the citations associated with the claim. For example, <code>[1,3,4]</code> means that <code>groundingChunk[1]</code>, <code>groundingChunk[3]</code>, and <code>groundingChunk[4]</code> are the retrieved content to the attributed claim. |
-|  [segment](./ai.groundingsupport.md#groundingsupportsegment) | [Segment](./ai.segment.md#segment_interface) | Segment of the content that this support is associated with. |
+|  [confidenceScores](./ai.groundingsupport.md#groundingsupportconfidencescores) | number\[\] | A list of confidence scores, corresponding to each index in <code>groundingChunkIndices</code>. Each score indicates the model's confidence that the correspondingly indexed grounding chunk supports the claim in the response segment. Scores range from 0.0 to 1.0, where 1.0 is the highest confidence. This list will have the same number of elements as <code>groundingChunkIndices</code>. |
+|  [groundingChunkIndices](./ai.groundingsupport.md#groundingsupportgroundingchunkindices) | number\[\] | A list of indices that refer to specific [GroundingChunk](./ai.groundingchunk.md#groundingchunk_interface) objects within the [GroundingMetadata.groundingChunks](./ai.groundingmetadata.md#groundingmetadatagroundingchunks) array. These referenced chunks are the sources that support the claim made in the associated <code>segment</code> of the response. For example, an array <code>[1, 3, 4]</code> means that <code>groundingChunks[1]</code>, <code>groundingChunks[3]</code>, and <code>groundingChunks[4]</code> are the retrieved content supporting this part of the response. |
+|  [segment](./ai.groundingsupport.md#groundingsupportsegment) | [Segment](./ai.segment.md#segment_interface) | Specifies the segment of the model's response content that this grounding support pertains to. |
 
 ## GroundingSupport.confidenceScores
 
-Confidence score of the supporting references. Ranges from 0 to 1, where 1 is the most confident. This list must have the same size has the `groundingChunkIndices`<!-- -->.
+A list of confidence scores, corresponding to each index in `groundingChunkIndices`<!-- -->. Each score indicates the model's confidence that the correspondingly indexed grounding chunk supports the claim in the response segment. Scores range from 0.0 to 1.0, where 1.0 is the highest confidence. This list will have the same number of elements as `groundingChunkIndices`<!-- -->.
 
 <b>Signature:</b>
 
@@ -38,7 +38,7 @@ confidenceScores?: number[];
 
 ## GroundingSupport.groundingChunkIndices
 
-A list of indices into `groundingChunk` specifying the citations associated with the claim. For example, `[1,3,4]` means that `groundingChunk[1]`<!-- -->, `groundingChunk[3]`<!-- -->, and `groundingChunk[4]` are the retrieved content to the attributed claim.
+A list of indices that refer to specific [GroundingChunk](./ai.groundingchunk.md#groundingchunk_interface) objects within the [GroundingMetadata.groundingChunks](./ai.groundingmetadata.md#groundingmetadatagroundingchunks) array. These referenced chunks are the sources that support the claim made in the associated `segment` of the response. For example, an array `[1, 3, 4]` means that `groundingChunks[1]`<!-- -->, `groundingChunks[3]`<!-- -->, and `groundingChunks[4]` are the retrieved content supporting this part of the response.
 
 <b>Signature:</b>
 
@@ -48,7 +48,7 @@ groundingChunkIndices?: number[];
 
 ## GroundingSupport.segment
 
-Segment of the content that this support is associated with.
+Specifies the segment of the model's response content that this grounding support pertains to.
 
 <b>Signature:</b>
 
diff --git a/docs-devsite/ai.md b/docs-devsite/ai.md
@@ -95,12 +95,12 @@ The Firebase AI Web SDK.
 |  [GenerateContentStreamResult](./ai.generatecontentstreamresult.md#generatecontentstreamresult_interface) | Result object returned from [GenerativeModel.generateContentStream()](./ai.generativemodel.md#generativemodelgeneratecontentstream) call. Iterate over <code>stream</code> to get chunks as they come in and/or use the <code>response</code> promise to get the aggregated response when the stream is done. |
 |  [GenerationConfig](./ai.generationconfig.md#generationconfig_interface) | Config options for content-related requests |
 |  [GenerativeContentBlob](./ai.generativecontentblob.md#generativecontentblob_interface) | Interface for sending an image. |
-|  [GoogleSearch](./ai.googlesearch.md#googlesearch_interface) | TODO(dlarocque) |
-|  [GoogleSearchTool](./ai.googlesearchtool.md#googlesearchtool_interface) | TODO(dlarocque) |
+|  [GoogleSearch](./ai.googlesearch.md#googlesearch_interface) | Configuration for the [GoogleSearchTool](./ai.googlesearchtool.md#googlesearchtool_interface)<!-- -->. |
+|  [GoogleSearchTool](./ai.googlesearchtool.md#googlesearchtool_interface) | A tool that allows the generative model to connect to Google Search to access and incorporate up-to-date information from the web into its responses.<!-- -->When this tool is used, the model's responses may include "Grounded Results" which are subject to the Grounding with Google Search terms outlined in the [Service Specific Terms](https://cloud.google.com/terms/service-terms)<!-- -->. |
 |  [GroundingAttribution](./ai.groundingattribution.md#groundingattribution_interface) |  |
-|  [GroundingChunk](./ai.groundingchunk.md#groundingchunk_interface) | A grounding chunk. |
+|  [GroundingChunk](./ai.groundingchunk.md#groundingchunk_interface) | Represents a chunk of retrieved data that supports a claim in the model's response. This is part of the grounding information provided when grounding is enabled. |
 |  [GroundingMetadata](./ai.groundingmetadata.md#groundingmetadata_interface) | Metadata returned to client when grounding is enabled. |
-|  [GroundingSupport](./ai.groundingsupport.md#groundingsupport_interface) | Grounding support. |
+|  [GroundingSupport](./ai.groundingsupport.md#groundingsupport_interface) | Provides information about how a specific segment of the model's response is supported by the retrieved grounding chunks. |
 |  [ImagenGCSImage](./ai.imagengcsimage.md#imagengcsimage_interface) | An image generated by Imagen, stored in a Cloud Storage for Firebase bucket.<!-- -->This feature is not available yet. |
 |  [ImagenGenerationConfig](./ai.imagengenerationconfig.md#imagengenerationconfig_interface) | <b><i>(Public Preview)</i></b> Configuration options for generating images with Imagen.<!-- -->See the [documentation](http://firebase.google.com/docs/vertex-ai/generate-images-imagen) for more details. |
 |  [ImagenGenerationResponse](./ai.imagengenerationresponse.md#imagengenerationresponse_interface) | <b><i>(Public Preview)</i></b> The response from a request to generate images with Imagen. |
@@ -121,15 +121,15 @@ The Firebase AI Web SDK.
 |  [SchemaRequest](./ai.schemarequest.md#schemarequest_interface) | Final format for [Schema](./ai.schema.md#schema_class) params passed to backend requests. |
 |  [SchemaShared](./ai.schemashared.md#schemashared_interface) | Basic [Schema](./ai.schema.md#schema_class) properties shared across several Schema-related types. |
 |  [SearchEntrypoint](./ai.searchentrypoint.md#searchentrypoint_interface) | Google search entry point. |
-|  [Segment](./ai.segment.md#segment_interface) | Segment of the content |
+|  [Segment](./ai.segment.md#segment_interface) | Represents a specific segment within a [Content](./ai.content.md#content_interface) object, often used to pinpoint the exact location of text or data that grounding information refers to. |
 |  [StartChatParams](./ai.startchatparams.md#startchatparams_interface) | Params for [GenerativeModel.startChat()](./ai.generativemodel.md#generativemodelstartchat)<!-- -->. |
 |  [TextPart](./ai.textpart.md#textpart_interface) | Content part interface if the part represents a text string. |
 |  [ToolConfig](./ai.toolconfig.md#toolconfig_interface) | Tool config. This config is shared for all tools provided in the request. |
 |  [UsageMetadata](./ai.usagemetadata.md#usagemetadata_interface) | Usage metadata about a [GenerateContentResponse](./ai.generatecontentresponse.md#generatecontentresponse_interface)<!-- -->. |
 |  [VertexAIOptions](./ai.vertexaioptions.md#vertexaioptions_interface) | Options when initializing the Firebase AI SDK. |
 |  [VideoMetadata](./ai.videometadata.md#videometadata_interface) | Describes the input video content. |
 |  [WebAttribution](./ai.webattribution.md#webattribution_interface) |  |
-|  [WebGroundingChunk](./ai.webgroundingchunk.md#webgroundingchunk_interface) | A grounding reference from the web. |
+|  [WebGroundingChunk](./ai.webgroundingchunk.md#webgroundingchunk_interface) | A grounding chunk from the web. |
 
 ## Variables
 
diff --git a/docs-devsite/ai.searchentrypoint.md b/docs-devsite/ai.searchentrypoint.md
@@ -22,38 +22,27 @@ export interface SearchEntrypoint
 
 |  Property | Type | Description |
 |  --- | --- | --- |
-|  [renderedContent](./ai.searchentrypoint.md#searchentrypointrenderedcontent) | string | Web content snippet that can be embedded in a web page. |
-|  [renderedContentElement](./ai.searchentrypoint.md#searchentrypointrenderedcontentelement) | HTMLDivElement | attachShadow(<!-- -->{<!-- -->mode: 'open'<!-- -->}<!-- -->).innerHTML = renderedContent https://developer.mozilla.org/en-US/docs/Web/API/Web\_components/Using\_shadow\_DOM - prevents CSS conflicts - "black box" structure that can't be modified by accident (very good in this context)<!-- -->this could be a helper method createEncapsulatedElement(htmlContent): HTMLDivElement |
-|  [sdkBlob](./ai.searchentrypoint.md#searchentrypointsdkblob) | string | Base64-encoded JSON array of &lt;<!-- -->search term, search url<!-- -->&gt; |
+|  [renderedContent](./ai.searchentrypoint.md#searchentrypointrenderedcontent) | string | HTML/CSS snippet that can be embedded in a web page. The snippet is designed to avoid undesired interaction with the rest of the page's CSS.<!-- -->To ensure proper rendering and prevent CSS conflicts, it is recommended to encapsulate this <code>renderedContent</code> within a shadow DOM when embedding it into a webpage. See [MDN: Using shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM)<!-- -->. |
 
 ## SearchEntrypoint.renderedContent
 
-Web content snippet that can be embedded in a web page.
+HTML/CSS snippet that can be embedded in a web page. The snippet is designed to avoid undesired interaction with the rest of the page's CSS.
+
+To ensure proper rendering and prevent CSS conflicts, it is recommended to encapsulate this `renderedContent` within a shadow DOM when embedding it into a webpage. See [MDN: Using shadow DOM](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_shadow_DOM)<!-- -->.
 
 <b>Signature:</b>
 
 ```typescript
 renderedContent: string;
 ```
 
-## SearchEntrypoint.renderedContentElement
-
-attachShadow(<!-- -->{<!-- -->mode: 'open'<!-- -->}<!-- -->).innerHTML = renderedContent https://developer.mozilla.org/en-US/docs/Web/API/Web\_components/Using\_shadow\_DOM - prevents CSS conflicts - "black box" structure that can't be modified by accident (very good in this context)
+### Example
 
-this could be a helper method createEncapsulatedElement(htmlContent): HTMLDivElement
 
-<b>Signature:</b>
+```javascript
+const container = document.createElement('div');
+document.body.appendChild(container);
+container.attachShadow({ mode: 'open' }).innerHTML = renderedContent;
 
-```typescript
-renderedContentElement: HTMLDivElement;
 ```
 
-## SearchEntrypoint.sdkBlob
-
-Base64-encoded JSON array of &lt;<!-- -->search term, search url<!-- -->&gt;
-
-<b>Signature:</b>
-
-```typescript
-sdkBlob?: string;
-```
diff --git a/docs-devsite/ai.segment.md b/docs-devsite/ai.segment.md
diff --git a/docs-devsite/ai.webgroundingchunk.md b/docs-devsite/ai.webgroundingchunk.md
diff --git a/packages/ai/src/types/requests.ts b/packages/ai/src/types/requests.ts
diff --git a/packages/ai/src/types/responses.ts b/packages/ai/src/types/responses.ts
