Search grounding (#271)

* Add preliminary search grouding change without unittest.

* Add support for stream generating content

* Generate doc and change set.

* Resolve comment

Author: junyanxu

.changeset/dirty-shrimps-lick.md

@@ -0,0 +1,5 @@
+---
+"@google/generative-ai": minor
+---
+
+Add search grounding feature to SDK.

.changeset/shy-panthers-thank.md

@@ -0,0 +1,5 @@
+---
+"@google/generative-ai": minor
+---
+
+Add support for search grounding

common/api-review/generative-ai-server.api.md

@@ -471,8 +471,10 @@ export interface TextPart {
     text: string;
 }
 
+// Warning: (ae-forgotten-export) The symbol "GoogleSearchRetrievalTool" needs to be exported by the entry point index.d.ts
+//
 // @public
-export type Tool = FunctionDeclarationsTool | CodeExecutionTool;
+export type Tool = FunctionDeclarationsTool | CodeExecutionTool | GoogleSearchRetrievalTool;
 
 // @public
 export interface ToolConfig {

common/api-review/generative-ai.api.md

@@ -155,6 +155,20 @@ export interface CountTokensResponse {
     totalTokens: number;
 }
 
+// @public
+export interface DynamicRetrievalConfig {
+    dynamicThreshold?: number;
+    mode?: DynamicRetrievalMode;
+}
+
+// @public
+export enum DynamicRetrievalMode {
+    // (undocumented)
+    MODE_DYNAMIC = "MODE_DYNAMIC",
+    // (undocumented)
+    MODE_UNSPECIFIED = "MODE_UNSPECIFIED"
+}
+
 // @public
 export interface EmbedContentRequest {
     // (undocumented)
@@ -378,6 +392,7 @@ export interface GenerateContentCandidate {
     finishMessage?: string;
     // (undocumented)
     finishReason?: FinishReason;
+    groundingMetadata?: GroundingMetadata;
     // (undocumented)
     index: number;
     logprobsResult?: LogprobsResult;
@@ -517,6 +532,51 @@ export class GoogleGenerativeAIResponseError<T> extends GoogleGenerativeAIError
     response?: T;
 }
 
+// @public
+export interface GoogleSearchRetrieval {
+    dynamicRetrievalConfig?: DynamicRetrievalConfig;
+}
+
+// @public
+export interface GoogleSearchRetrievalTool {
+    googleSearchRetrieval?: GoogleSearchRetrieval;
+}
+
+// @public
+export interface GroundingChunk {
+    web?: GroundingChunkWeb;
+}
+
+// @public
+export interface GroundingChunkWeb {
+    title?: string;
+    uri?: string;
+}
+
+// @public
+export interface GroundingMetadata {
+    groundingChuncks?: GroundingChunk[];
+    groundingSupport?: GroundingSupport[];
+    retrievalMetadata?: RetrievalMetadata;
+    searchEntryPoint?: SearchEntryPoint;
+    webSearchQueries: string[];
+}
+
+// @public
+export interface GroundingSupport {
+    confidenceScores?: number[];
+    groundingChunckIndices?: number[];
+    segment?: string;
+}
+
+// @public
+export interface GroundingSupportSegment {
+    endIndex?: number;
+    partIndex?: number;
+    startIndex?: number;
+    text?: string;
+}
+
 // @public
 export enum HarmBlockThreshold {
     // (undocumented)
@@ -641,6 +701,11 @@ export interface RequestOptions {
 export interface ResponseSchema extends Schema {
 }
 
+// @public
+export interface RetrievalMetadata {
+    googleSearchDynamicRetrievalScore?: number;
+}
+
 // @public
 export interface SafetyRating {
     // (undocumented)
@@ -682,6 +747,12 @@ export enum SchemaType {
     STRING = "string"
 }
 
+// @public
+export interface SearchEntryPoint {
+    renderedContent?: string;
+    sdkBlob?: string;
+}
+
 // @public
 export interface SingleRequestOptions extends RequestOptions {
     signal?: AbortSignal;
@@ -735,7 +806,7 @@ export interface TextPart {
 }
 
 // @public
-export type Tool = FunctionDeclarationsTool | CodeExecutionTool;
+export type Tool = FunctionDeclarationsTool | CodeExecutionTool | GoogleSearchRetrievalTool;
 
 // @public
 export interface ToolConfig {

docs/reference/main/generative-ai.dynamicretrievalconfig.dynamicthreshold.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [DynamicRetrievalConfig](./generative-ai.dynamicretrievalconfig.md) &gt; [dynamicThreshold](./generative-ai.dynamicretrievalconfig.dynamicthreshold.md)
+
+## DynamicRetrievalConfig.dynamicThreshold property
+
+The threshold to be used in dynamic retrieval. If not set, a system default value is used.
+
+**Signature:**
+
+```typescript
+dynamicThreshold?: number;
+```

docs/reference/main/generative-ai.dynamicretrievalconfig.md

@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [DynamicRetrievalConfig](./generative-ai.dynamicretrievalconfig.md)
+
+## DynamicRetrievalConfig interface
+
+Specifies the dynamic retrieval configuration for the given source.
+
+**Signature:**
+
+```typescript
+export declare interface DynamicRetrievalConfig 
+```
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [dynamicThreshold?](./generative-ai.dynamicretrievalconfig.dynamicthreshold.md) |  | number | _(Optional)_ The threshold to be used in dynamic retrieval. If not set, a system default value is used. |
+|  [mode?](./generative-ai.dynamicretrievalconfig.mode.md) |  | [DynamicRetrievalMode](./generative-ai.dynamicretrievalmode.md) | _(Optional)_ The mode of the predictor to be used in dynamic retrieval. |
+

docs/reference/main/generative-ai.dynamicretrievalconfig.mode.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [DynamicRetrievalConfig](./generative-ai.dynamicretrievalconfig.md) &gt; [mode](./generative-ai.dynamicretrievalconfig.mode.md)
+
+## DynamicRetrievalConfig.mode property
+
+The mode of the predictor to be used in dynamic retrieval.
+
+**Signature:**
+
+```typescript
+mode?: DynamicRetrievalMode;
+```

docs/reference/main/generative-ai.dynamicretrievalmode.md

@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [DynamicRetrievalMode](./generative-ai.dynamicretrievalmode.md)
+
+## DynamicRetrievalMode enum
+
+The mode of the predictor to be used in dynamic retrieval.
+
+**Signature:**
+
+```typescript
+export declare enum DynamicRetrievalMode 
+```
+
+## Enumeration Members
+
+|  Member | Value | Description |
+|  --- | --- | --- |
+|  MODE\_DYNAMIC | <code>&quot;MODE_DYNAMIC&quot;</code> |  |
+|  MODE\_UNSPECIFIED | <code>&quot;MODE_UNSPECIFIED&quot;</code> |  |
+

docs/reference/main/generative-ai.generatecontentcandidate.groundingmetadata.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [GenerateContentCandidate](./generative-ai.generatecontentcandidate.md) &gt; [groundingMetadata](./generative-ai.generatecontentcandidate.groundingmetadata.md)
+
+## GenerateContentCandidate.groundingMetadata property
+
+Search grounding metadata.
+
+**Signature:**
+
+```typescript
+groundingMetadata?: GroundingMetadata;
+```

docs/reference/main/generative-ai.generatecontentcandidate.md

@@ -21,6 +21,7 @@ export interface GenerateContentCandidate
 |  [content](./generative-ai.generatecontentcandidate.content.md) |  | [Content](./generative-ai.content.md) |  |
 |  [finishMessage?](./generative-ai.generatecontentcandidate.finishmessage.md) |  | string | _(Optional)_ |
 |  [finishReason?](./generative-ai.generatecontentcandidate.finishreason.md) |  | [FinishReason](./generative-ai.finishreason.md) | _(Optional)_ |
+|  [groundingMetadata?](./generative-ai.generatecontentcandidate.groundingmetadata.md) |  | [GroundingMetadata](./generative-ai.groundingmetadata.md) | _(Optional)_ Search grounding metadata. |
 |  [index](./generative-ai.generatecontentcandidate.index.md) |  | number |  |
 |  [logprobsResult?](./generative-ai.generatecontentcandidate.logprobsresult.md) |  | [LogprobsResult](./generative-ai.logprobsresult.md) | _(Optional)_ Log-likelihood scores for the response tokens and top tokens. |
 |  [safetyRatings?](./generative-ai.generatecontentcandidate.safetyratings.md) |  | [SafetyRating](./generative-ai.safetyrating.md)<!-- -->\[\] | _(Optional)_ |

docs/reference/main/generative-ai.googlesearchretrieval.dynamicretrievalconfig.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [GoogleSearchRetrieval](./generative-ai.googlesearchretrieval.md) &gt; [dynamicRetrievalConfig](./generative-ai.googlesearchretrieval.dynamicretrievalconfig.md)
+
+## GoogleSearchRetrieval.dynamicRetrievalConfig property
+
+Specifies the dynamic retrieval configuration for the given source.
+
+**Signature:**
+
+```typescript
+dynamicRetrievalConfig?: DynamicRetrievalConfig;
+```

docs/reference/main/generative-ai.googlesearchretrieval.md

@@ -0,0 +1,20 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [GoogleSearchRetrieval](./generative-ai.googlesearchretrieval.md)
+
+## GoogleSearchRetrieval interface
+
+Retrieval tool that is powered by Google search.
+
+**Signature:**
+
+```typescript
+export declare interface GoogleSearchRetrieval 
+```
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [dynamicRetrievalConfig?](./generative-ai.googlesearchretrieval.dynamicretrievalconfig.md) |  | [DynamicRetrievalConfig](./generative-ai.dynamicretrievalconfig.md) | _(Optional)_ Specifies the dynamic retrieval configuration for the given source. |
+

docs/reference/main/generative-ai.googlesearchretrievaltool.googlesearchretrieval.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [GoogleSearchRetrievalTool](./generative-ai.googlesearchretrievaltool.md) &gt; [googleSearchRetrieval](./generative-ai.googlesearchretrievaltool.googlesearchretrieval.md)
+
+## GoogleSearchRetrievalTool.googleSearchRetrieval property
+
+Google search retrieval tool config.
+
+**Signature:**
+
+```typescript
+googleSearchRetrieval?: GoogleSearchRetrieval;
+```

docs/reference/main/generative-ai.googlesearchretrievaltool.md

@@ -0,0 +1,20 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [GoogleSearchRetrievalTool](./generative-ai.googlesearchretrievaltool.md)
+
+## GoogleSearchRetrievalTool interface
+
+Retrieval tool that is powered by Google search.
+
+**Signature:**
+
+```typescript
+export declare interface GoogleSearchRetrievalTool 
+```
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [googleSearchRetrieval?](./generative-ai.googlesearchretrievaltool.googlesearchretrieval.md) |  | [GoogleSearchRetrieval](./generative-ai.googlesearchretrieval.md) | _(Optional)_ Google search retrieval tool config. |
+

docs/reference/main/generative-ai.groundingchunk.md

@@ -0,0 +1,20 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [GroundingChunk](./generative-ai.groundingchunk.md)
+
+## GroundingChunk interface
+
+Grounding chunk.
+
+**Signature:**
+
+```typescript
+export declare interface GroundingChunk 
+```
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [web?](./generative-ai.groundingchunk.web.md) |  | [GroundingChunkWeb](./generative-ai.groundingchunkweb.md) | _(Optional)_ Chunk from the web. |
+

docs/reference/main/generative-ai.groundingchunk.web.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [GroundingChunk](./generative-ai.groundingchunk.md) &gt; [web](./generative-ai.groundingchunk.web.md)
+
+## GroundingChunk.web property
+
+Chunk from the web.
+
+**Signature:**
+
+```typescript
+web?: GroundingChunkWeb;
+```

docs/reference/main/generative-ai.groundingchunkweb.md

@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [GroundingChunkWeb](./generative-ai.groundingchunkweb.md)
+
+## GroundingChunkWeb interface
+
+Chunk from the web.
+
+**Signature:**
+
+```typescript
+export declare interface GroundingChunkWeb 
+```
+
+## Properties
+
+|  Property | Modifiers | Type | Description |
+|  --- | --- | --- | --- |
+|  [title?](./generative-ai.groundingchunkweb.title.md) |  | string | _(Optional)_ Title of the chunk. |
+|  [uri?](./generative-ai.groundingchunkweb.uri.md) |  | string | _(Optional)_ URI reference of the chunk. |
+

docs/reference/main/generative-ai.groundingchunkweb.title.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [GroundingChunkWeb](./generative-ai.groundingchunkweb.md) &gt; [title](./generative-ai.groundingchunkweb.title.md)
+
+## GroundingChunkWeb.title property
+
+Title of the chunk.
+
+**Signature:**
+
+```typescript
+title?: string;
+```

docs/reference/main/generative-ai.groundingchunkweb.uri.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [@google/generative-ai](./generative-ai.md) &gt; [GroundingChunkWeb](./generative-ai.groundingchunkweb.md) &gt; [uri](./generative-ai.groundingchunkweb.uri.md)
+
+## GroundingChunkWeb.uri property
+
+URI reference of the chunk.
+
+**Signature:**
+
+```typescript
+uri?: string;
+```