feat(ai): add support for grounding with google search

.changeset/five-kids-grow.md

@@ -0,0 +1,6 @@
+---
+'firebase': minor
+'@firebase/ai': minor
+---
+
+Add support for Grounding with Google Search.

common/api-review/ai.api.md

@@ -485,6 +485,15 @@ export interface GoogleAIGenerateContentResponse {
     usageMetadata?: UsageMetadata;
 }
 
+// @public
+export interface GoogleSearch {
+}
+
+// @public
+export interface GoogleSearchTool {
+    googleSearch: GoogleSearch;
+}
+
 // @public @deprecated (undocumented)
 export interface GroundingAttribution {
     // (undocumented)
@@ -497,16 +506,30 @@ export interface GroundingAttribution {
     web?: WebAttribution;
 }
 
+// @public
+export interface GroundingChunk {
+    web?: WebGroundingChunk;
+}
+
 // @public
 export interface GroundingMetadata {
     // @deprecated (undocumented)
     groundingAttributions: GroundingAttribution[];
-    // (undocumented)
+    groundingChunks?: GroundingChunk[];
+    groundingSupports?: GroundingSupport[];
+    // @deprecated (undocumented)
     retrievalQueries?: string[];
-    // (undocumented)
+    searchEntryPoint?: SearchEntrypoint;
     webSearchQueries?: string[];
 }
 
+// @public
+export interface GroundingSupport {
+    confidenceScores?: number[];
+    groundingChunkIndices?: number[];
+    segment?: Segment;
+}
+
 // @public
 export enum HarmBlockMethod {
     PROBABILITY = "PROBABILITY",
@@ -852,14 +875,17 @@ export enum SchemaType {
     STRING = "string"
 }
 
-// @public (undocumented)
+// @public
+export interface SearchEntrypoint {
+    renderedContent: string;
+}
+
+// @public
 export interface Segment {
-    // (undocumented)
     endIndex: number;
-    // (undocumented)
     partIndex: number;
-    // (undocumented)
     startIndex: number;
+    text: string;
 }
 
 // @public
@@ -896,7 +922,7 @@ export interface TextPart {
 }
 
 // @public
-export type Tool = FunctionDeclarationsTool;
+export type Tool = FunctionDeclarationsTool | GoogleSearchTool;
 
 // @public
 export interface ToolConfig {
@@ -956,5 +982,12 @@ export interface WebAttribution {
     uri: string;
 }
 
+// @public
+export interface WebGroundingChunk {
+    domain?: string;
+    title?: string;
+    uri?: string;
+}
+
 
 ```

docs-devsite/_toc.yaml

@@ -76,10 +76,18 @@ toc:
     path: /docs/reference/js/ai.generativemodel.md
   - title: GoogleAIBackend
     path: /docs/reference/js/ai.googleaibackend.md
+  - title: GoogleSearch
+    path: /docs/reference/js/ai.googlesearch.md
+  - title: GoogleSearchTool
+    path: /docs/reference/js/ai.googlesearchtool.md
   - title: GroundingAttribution
     path: /docs/reference/js/ai.groundingattribution.md
+  - title: GroundingChunk
+    path: /docs/reference/js/ai.groundingchunk.md
   - title: GroundingMetadata
     path: /docs/reference/js/ai.groundingmetadata.md
+  - title: GroundingSupport
+    path: /docs/reference/js/ai.groundingsupport.md
   - title: ImagenGCSImage
     path: /docs/reference/js/ai.imagengcsimage.md
   - title: ImagenGenerationConfig
@@ -130,6 +138,8 @@ toc:
     path: /docs/reference/js/ai.schemarequest.md
   - title: SchemaShared
     path: /docs/reference/js/ai.schemashared.md
+  - title: SearchEntrypoint
+    path: /docs/reference/js/ai.searchentrypoint.md
   - title: Segment
     path: /docs/reference/js/ai.segment.md
   - title: StartChatParams
@@ -150,6 +160,8 @@ toc:
     path: /docs/reference/js/ai.videometadata.md
   - title: WebAttribution
     path: /docs/reference/js/ai.webattribution.md
+  - title: WebGroundingChunk
+    path: /docs/reference/js/ai.webgroundingchunk.md
 - title: analytics
   path: /docs/reference/js/analytics.md
   section:

docs-devsite/ai.googlesearch.md

@@ -0,0 +1,21 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+https://github.com/firebase/firebase-js-sdk
+{% endcomment %}
+
+# GoogleSearch interface
+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>
+
+```typescript
+export declare interface GoogleSearch 
+```

docs-devsite/ai.googlesearchtool.md

@@ -0,0 +1,37 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+https://github.com/firebase/firebase-js-sdk
+{% endcomment %}
+
+# 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)<!-- -->.
+
+<b>Signature:</b>
+
+```typescript
+export declare interface GoogleSearchTool 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [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
+googleSearch: GoogleSearch;
+```

docs-devsite/ai.groundingchunk.md

@@ -0,0 +1,35 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+https://github.com/firebase/firebase-js-sdk
+{% endcomment %}
+
+# 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.
+
+<b>Signature:</b>
+
+```typescript
+export interface GroundingChunk 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [web](./ai.groundingchunk.md#groundingchunkweb) | [WebGroundingChunk](./ai.webgroundingchunk.md#webgroundingchunk_interface) | Contains details if the grounding chunk is from a web source. |
+
+## GroundingChunk.web
+
+Contains details if the grounding chunk is from a web source.
+
+<b>Signature:</b>
+
+```typescript
+web?: WebGroundingChunk;
+```

docs-devsite/ai.groundingmetadata.md

@@ -23,8 +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)<!-- -->\[\] | 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\[\] |  |
-|  [webSearchQueries](./ai.groundingmetadata.md#groundingmetadatawebsearchqueries) | string\[\] |  |
+|  [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
 
@@ -38,16 +41,53 @@ export interface GroundingMetadata
 groundingAttributions: GroundingAttribution[];
 ```
 
+## GroundingMetadata.groundingChunks
+
+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>
+
+```typescript
+groundingChunks?: GroundingChunk[];
+```
+
+## GroundingMetadata.groundingSupports
+
+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>
+
+```typescript
+groundingSupports?: GroundingSupport[];
+```
+
 ## GroundingMetadata.retrievalQueries
 
+> Warning: This API is now obsolete.
+> 
+> Use [GroundingMetadata.groundingSupports](./ai.groundingmetadata.md#groundingmetadatagroundingsupports) instead.
+> 
+
 <b>Signature:</b>
 
 ```typescript
 retrievalQueries?: string[];
 ```
 
+## GroundingMetadata.searchEntryPoint
+
+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>
+
+```typescript
+searchEntryPoint?: SearchEntrypoint;
+```
+
 ## GroundingMetadata.webSearchQueries
 
+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>
 
 ```typescript

docs-devsite/ai.groundingsupport.md

@@ -0,0 +1,57 @@
+Project: /docs/reference/js/_project.yaml
+Book: /docs/reference/_book.yaml
+page_type: reference
+
+{% comment %}
+DO NOT EDIT THIS FILE!
+This is generated by the JS SDK team, and any local changes will be
+overwritten. Changes should be made in the source code at
+https://github.com/firebase/firebase-js-sdk
+{% endcomment %}
+
+# GroundingSupport interface
+Provides information about how a specific segment of the model's response is supported by the retrieved grounding chunks.
+
+<b>Signature:</b>
+
+```typescript
+export interface GroundingSupport 
+```
+
+## Properties
+
+|  Property | Type | Description |
+|  --- | --- | --- |
+|  [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
+
+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>
+
+```typescript
+confidenceScores?: number[];
+```
+
+## GroundingSupport.groundingChunkIndices
+
+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>
+
+```typescript
+groundingChunkIndices?: number[];
+```
+
+## GroundingSupport.segment
+
+Specifies the segment of the model's response content that this grounding support pertains to.
+
+<b>Signature:</b>
+
+```typescript
+segment?: Segment;
+```

docs-devsite/ai.md

@@ -95,8 +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) | 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) | 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) | 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. |
@@ -116,14 +120,16 @@ The Firebase AI Web SDK.
 |  [SchemaParams](./ai.schemaparams.md#schemaparams_interface) | Params passed to [Schema](./ai.schema.md#schema_class) static methods to create specific [Schema](./ai.schema.md#schema_class) classes. |
 |  [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. |
-|  [Segment](./ai.segment.md#segment_interface) |  |
+|  [SearchEntrypoint](./ai.searchentrypoint.md#searchentrypoint_interface) | Google search entry point. |
+|  [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 chunk from the web. |
 
 ## Variables
 
@@ -400,7 +406,7 @@ Defines a tool that model can call to access external knowledge.
 <b>Signature:</b>
 
 ```typescript
-export declare type Tool = FunctionDeclarationsTool;
+export declare type Tool = FunctionDeclarationsTool | GoogleSearchTool;
 ```
 
 ## TypedSchema