@google/genai 1.7.0 → 1.8.0

package/README.md

@@ -275,6 +275,49 @@ async function main() {
 main();
 ```
 
+#### Model Context Protocol (MCP) support (experimental)
+
+Built-in [MCP](https://modelcontextprotocol.io/introduction) support is an
+experimental feature. You can pass a local MCP server as a tool directly.
+
+```javascript
+import { GoogleGenAI, FunctionCallingConfigMode , mcpToTool} from '@google/genai';
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+// Create server parameters for stdio connection
+const serverParams = new StdioClientTransport({
+  command: "npx", // Executable
+  args: ["-y", "@philschmid/weather-mcp"] // MCP Server
+});
+
+const client = new Client(
+  {
+    name: "example-client",
+    version: "1.0.0"
+  }
+);
+
+// Configure the client
+const ai = new GoogleGenAI({});
+
+// Initialize the connection between client and server
+await client.connect(serverParams);
+
+// Send request to the model with MCP tools
+const response = await ai.models.generateContent({
+  model: "gemini-2.5-flash",
+  contents: `What is the weather in London in ${new Date().toLocaleDateString()}?`,
+  config: {
+    tools: [mcpToTool(client)],  // uses the session, will automatically call the tool using automatic function calling
+  },
+});
+console.log(response.text);
+
+// Close the connection
+await client.close();
+```
+
 ### Generate Content
 
 #### How to structure `contents` argument for `generateContent`

package/dist/genai.d.ts

@@ -66,6 +66,20 @@ export declare enum AdapterSize {
     ADAPTER_SIZE_THIRTY_TWO = "ADAPTER_SIZE_THIRTY_TWO"
 }
 
+/** The generic reusable api auth config. Deprecated. Please use AuthConfig (google/cloud/aiplatform/master/auth.proto) instead. */
+export declare interface ApiAuth {
+    /** The API secret. */
+    apiKeyConfig?: ApiAuthApiKeyConfig;
+}
+
+/** The API secret. */
+export declare interface ApiAuthApiKeyConfig {
+    /** Required. The SecretManager secret version resource name storing API key. e.g. projects/{project}/secrets/{secret}/versions/{version} */
+    apiKeySecretVersion?: string;
+    /** The API key string. Either this or `api_key_secret_version` must be set. */
+    apiKeyString?: string;
+}
+
 /**
  * The ApiClient class is used to send requests to the Gemini API or Vertex AI
  * endpoints.
@@ -222,9 +236,26 @@ export declare interface ApiKeyConfig {
     apiKeyString?: string;
 }
 
+/** The API spec that the external API implements. */
+export declare enum ApiSpec {
+    /**
+     * Unspecified API spec. This value should not be used.
+     */
+    API_SPEC_UNSPECIFIED = "API_SPEC_UNSPECIFIED",
+    /**
+     * Simple search API spec.
+     */
+    SIMPLE_SEARCH = "SIMPLE_SEARCH",
+    /**
+     * Elastic search API spec.
+     */
+    ELASTIC_SEARCH = "ELASTIC_SEARCH"
+}
+
 /** Representation of an audio chunk. */
 export declare interface AudioChunk {
-    /** Raw byets of audio data. */
+    /** Raw bytes of audio data.
+     * @remarks Encoded as base64 string. */
     data?: string;
     /** MIME type of the audio chunk. */
     mimeType?: string;
@@ -454,6 +485,18 @@ export declare class Batches extends BaseModule {
      */
     cancel(params: types.CancelBatchJobParameters): Promise<void>;
     private listInternal;
+    /**
+     * Deletes a batch job.
+     *
+     * @param params - The parameters for the delete request.
+     * @return The empty response returned by the API.
+     *
+     * @example
+     * ```ts
+     * await ai.batches.delete({name: '...'}); // The server-generated resource name.
+     * ```
+     */
+    delete(params: types.DeleteBatchJobParameters): Promise<types.DeleteResourceJob>;
 }
 
 /** Config for batches.create return value. */
@@ -560,7 +603,8 @@ export declare enum Behavior {
 declare interface Blob_2 {
     /** Optional. Display name of the blob. Used to provide a label or filename to distinguish blobs. This field is not currently used in the Gemini GenerateContent calls. */
     displayName?: string;
-    /** Required. Raw bytes. */
+    /** Required. Raw bytes.
+     * @remarks Encoded as base64 string. */
     data?: string;
     /** Required. The IANA standard MIME type of the source data. */
     mimeType?: string;
@@ -590,7 +634,11 @@ export declare enum BlockedReason {
     /**
      * Candidates blocked due to prohibited content.
      */
-    PROHIBITED_CONTENT = "PROHIBITED_CONTENT"
+    PROHIBITED_CONTENT = "PROHIBITED_CONTENT",
+    /**
+     * Candidates blocked due to unsafe image generation content.
+     */
+    IMAGE_SAFETY = "IMAGE_SAFETY"
 }
 
 /** A resource used in LLM queries for users to explicitly specify what to cache. */
@@ -956,7 +1004,7 @@ export declare interface CitationMetadata {
     citations?: Citation[];
 }
 
-/** Result of executing the [ExecutableCode]. Always follows a `part` containing the [ExecutableCode]. */
+/** Result of executing the [ExecutableCode]. Only generated when using the [CodeExecution] tool, and always follows a `part` containing the [ExecutableCode]. */
 export declare interface CodeExecutionResult {
     /** Required. Outcome of the code execution. */
     outcome?: Outcome;
@@ -1444,6 +1492,30 @@ export declare interface DatasetStats {
     userOutputTokenDistribution?: DatasetDistribution;
 }
 
+/** Optional parameters for models.get method. */
+export declare interface DeleteBatchJobConfig {
+    /** Used to override HTTP request options. */
+    httpOptions?: HttpOptions;
+    /** Abort signal which can be used to cancel the request.
+
+     NOTE: AbortSignal is a client-only operation. Using it to cancel an
+     operation will not cancel the request in the service. You will still
+     be charged usage for any applicable operations.
+     */
+    abortSignal?: AbortSignal;
+}
+
+/** Config for batches.delete parameters. */
+export declare interface DeleteBatchJobParameters {
+    /** A fully-qualified BatchJob resource name or ID.
+     Example: "projects/.../locations/.../batchPredictionJobs/456"
+     or "456" when project and location are initialized in the client.
+     */
+    name: string;
+    /** Optional parameters for the request. */
+    config?: DeleteBatchJobConfig;
+}
+
 /** Optional parameters for caches.delete method. */
 export declare interface DeleteCachedContentConfig {
     /** Used to override HTTP request options. */
@@ -1519,6 +1591,13 @@ export declare interface DeleteModelParameters {
 export declare class DeleteModelResponse {
 }
 
+/** The return value of delete operation. */
+export declare interface DeleteResourceJob {
+    name?: string;
+    done?: boolean;
+    error?: JobError;
+}
+
 /** Statistics computed for datasets used for distillation. */
 export declare interface DistillationDataStats {
     /** Output only. Statistics computed for the training dataset. */
@@ -1803,7 +1882,19 @@ export declare enum EndSensitivity {
 export declare interface EnterpriseWebSearch {
 }
 
-/** Code generated by the model that is meant to be executed, and the result returned to the model. Generated when using the [FunctionDeclaration] tool and [FunctionCallingConfig] mode is set to [Mode.CODE]. */
+/** Required. The environment being operated. */
+export declare enum Environment {
+    /**
+     * Defaults to browser.
+     */
+    ENVIRONMENT_UNSPECIFIED = "ENVIRONMENT_UNSPECIFIED",
+    /**
+     * Operates in a web browser.
+     */
+    ENVIRONMENT_BROWSER = "ENVIRONMENT_BROWSER"
+}
+
+/** Code generated by the model that is meant to be executed, and the result returned to the model. Generated when using the [CodeExecution] tool, in which the code will be automatically executed, and a corresponding [CodeExecutionResult] will also be generated. */
 export declare interface ExecutableCode {
     /** Required. The code to be executed. */
     code?: string;
@@ -1811,6 +1902,36 @@ export declare interface ExecutableCode {
     language?: Language;
 }
 
+/** Retrieve from data source powered by external API for grounding. The external API is not owned by Google, but need to follow the pre-defined API spec. */
+export declare interface ExternalApi {
+    /** The authentication config to access the API. Deprecated. Please use auth_config instead. */
+    apiAuth?: ApiAuth;
+    /** The API spec that the external API implements. */
+    apiSpec?: ApiSpec;
+    /** The authentication config to access the API. */
+    authConfig?: AuthConfig;
+    /** Parameters for the elastic search API. */
+    elasticSearchParams?: ExternalApiElasticSearchParams;
+    /** The endpoint of the external API. The system will call the API at this endpoint to retrieve the data for grounding. Example: https://acme.com:443/search */
+    endpoint?: string;
+    /** Parameters for the simple search API. */
+    simpleSearchParams?: ExternalApiSimpleSearchParams;
+}
+
+/** The search parameters to use for the ELASTIC_SEARCH spec. */
+export declare interface ExternalApiElasticSearchParams {
+    /** The ElasticSearch index to use. */
+    index?: string;
+    /** Optional. Number of hits (chunks) to request. When specified, it is passed to Elasticsearch as the `num_hits` param. */
+    numHits?: number;
+    /** The ElasticSearch search template to use. */
+    searchTemplate?: string;
+}
+
+/** The search parameters to use for SIMPLE_SEARCH spec. */
+export declare interface ExternalApiSimpleSearchParams {
+}
+
 /** Options for feature selection preference. */
 export declare enum FeatureSelectionPreference {
     FEATURE_SELECTION_PREFERENCE_UNSPECIFIED = "FEATURE_SELECTION_PREFERENCE_UNSPECIFIED",
@@ -2746,6 +2867,8 @@ export declare interface GenerationConfig {
     audioTimestamp?: boolean;
     /** Optional. Number of candidates to generate. */
     candidateCount?: number;
+    /** Optional. If enabled, the model will detect emotions and adapt its responses accordingly. */
+    enableAffectiveDialog?: boolean;
     /** Optional. Frequency penalties. */
     frequencyPenalty?: number;
     /** Optional. Logit probabilities. */
@@ -2756,6 +2879,8 @@ export declare interface GenerationConfig {
     mediaResolution?: MediaResolution;
     /** Optional. Positive penalties. */
     presencePenalty?: number;
+    /** Optional. Output schema of the generated response. This is an alternative to `response_schema` that accepts [JSON Schema](https://json-schema.org/). If set, `response_schema` must be omitted, but `response_mime_type` is required. While the full JSON Schema may be sent, not all features are supported. Specifically, only the following properties are supported: - `$id` - `$defs` - `$ref` - `$anchor` - `type` - `format` - `title` - `description` - `enum` (for strings and numbers) - `items` - `prefixItems` - `minItems` - `maxItems` - `minimum` - `maximum` - `anyOf` - `oneOf` (interpreted the same as `anyOf`) - `properties` - `additionalProperties` - `required` The non-standard `propertyOrdering` property may also be set. Cyclic references are unrolled to a limited degree and, as such, may only be used within non-required properties. (Nullable properties are not sufficient.) If `$ref` is set on a sub-schema, no other properties, except for than those starting as a `$`, may be set. */
+    responseJsonSchema?: unknown;
     /** Optional. If true, export the logprobs results in response. */
     responseLogprobs?: boolean;
     /** Optional. Output response mimetype of the generated candidate text. Supported mimetype: - `text/plain`: (default) Text output. - `application/json`: JSON response in the candidates. The model needs to be prompted to output the appropriate response type, otherwise the behavior is undefined. This is a preview feature. */
@@ -2764,8 +2889,6 @@ export declare interface GenerationConfig {
     responseModalities?: Modality[];
     /** Optional. The `Schema` object allows the definition of input and output data types. These types can be objects, but also primitives and arrays. Represents a select subset of an [OpenAPI 3.0 schema object](https://spec.openapis.org/oas/v3.0.3#schema). If set, a compatible response_mime_type must also be set. Compatible mimetypes: `application/json`: Schema for JSON response. */
     responseSchema?: Schema;
-    /** Optional. Output schema of the generated response. This is an alternative to `response_schema` that accepts [JSON Schema](https://json-schema.org/). If set, `response_schema` must be omitted, but `response_mime_type` is required. While the full JSON Schema may be sent, not all features are supported. Specifically, only the following properties are supported: - `$id` - `$defs` - `$ref` - `$anchor` - `type` - `format` - `title` - `description` - `enum` (for strings and numbers) - `items` - `prefixItems` - `minItems` - `maxItems` - `minimum` - `maximum` - `anyOf` - `oneOf` (interpreted the same as `anyOf`) - `properties` - `additionalProperties` - `required` The non-standard `propertyOrdering` property may also be set. Cyclic references are unrolled to a limited degree and, as such, may only be used within non-required properties. (Nullable properties are not sufficient.) If `$ref` is set on a sub-schema, no other properties, except for than those starting as a `$`, may be set. */
-    responseJsonSchema?: unknown;
     /** Optional. Routing configuration. */
     routingConfig?: GenerationConfigRoutingConfig;
     /** Optional. Seed. */
@@ -3138,7 +3261,7 @@ export declare interface GroundingMetadata {
 
 /** Grounding support. */
 export declare interface GroundingSupport {
-    /** Confidence score of the support references. Ranges from 0 to 1. 1 is the most confident. This list must have the same size as the grounding_chunk_indices. */
+    /** Confidence score of the support references. Ranges from 0 to 1. 1 is the most confident. For Gemini 2.0 and before, this list must have the same size as the grounding_chunk_indices. For Gemini 2.5 and after, this list will be empty and should be ignored. */
     confidenceScores?: number[];
     /** A list of indices (into 'grounding_chunk') specifying the citations associated with the claim. For instance [1,3,4] means that grounding_chunk[1], grounding_chunk[3], grounding_chunk[4] are the retrieved content attributed to the claim. */
     groundingChunkIndices?: number[];
@@ -3215,7 +3338,23 @@ export declare enum HarmCategory {
     /**
      * Deprecated: Election filter is not longer supported. The harm category is civic integrity.
      */
-    HARM_CATEGORY_CIVIC_INTEGRITY = "HARM_CATEGORY_CIVIC_INTEGRITY"
+    HARM_CATEGORY_CIVIC_INTEGRITY = "HARM_CATEGORY_CIVIC_INTEGRITY",
+    /**
+     * The harm category is image hate.
+     */
+    HARM_CATEGORY_IMAGE_HATE = "HARM_CATEGORY_IMAGE_HATE",
+    /**
+     * The harm category is image dangerous content.
+     */
+    HARM_CATEGORY_IMAGE_DANGEROUS_CONTENT = "HARM_CATEGORY_IMAGE_DANGEROUS_CONTENT",
+    /**
+     * The harm category is image harassment.
+     */
+    HARM_CATEGORY_IMAGE_HARASSMENT = "HARM_CATEGORY_IMAGE_HARASSMENT",
+    /**
+     * The harm category is image sexually explicit content.
+     */
+    HARM_CATEGORY_IMAGE_SEXUALLY_EXPLICIT = "HARM_CATEGORY_IMAGE_SEXUALLY_EXPLICIT"
 }
 
 /** Output only. Harm probability levels in the content. */
@@ -3349,7 +3488,8 @@ declare interface Image_2 {
     gcsUri?: string;
     /** The image bytes data. ``Image`` can contain a value for this field
      or the ``gcs_uri`` field but not both.
-     */
+
+     * @remarks Encoded as base64 string. */
     imageBytes?: string;
     /** The MIME type of the image. */
     mimeType?: string;
@@ -4361,6 +4501,8 @@ export declare interface LiveServerSessionResumptionUpdate {
 }
 
 export declare interface LiveServerSetupComplete {
+    /** The session id of the live session. */
+    sessionId?: string;
 }
 
 /** Request for the client to execute the `function_calls` and return the responses with the matching `id`s. */
@@ -5094,7 +5236,8 @@ export declare interface Part {
     inlineData?: Blob_2;
     /** Optional. URI based data. */
     fileData?: FileData;
-    /** An opaque signature for the thought so it can be reused in subsequent requests. */
+    /** An opaque signature for the thought so it can be reused in subsequent requests.
+     * @remarks Encoded as base64 string. */
     thoughtSignature?: string;
     /** Optional. Result of executing the [ExecutableCode]. */
     codeExecutionResult?: CodeExecutionResult;
@@ -5299,6 +5442,8 @@ export declare class ReplayResponse {
 export declare interface Retrieval {
     /** Optional. Deprecated. This option is no longer supported. */
     disableAttribution?: boolean;
+    /** Use data source powered by external API for grounding. */
+    externalApi?: ExternalApi;
     /** Set to use data source powered by Vertex AI Search. */
     vertexAiSearch?: VertexAISearch;
     /** Set to use data source powered by Vertex RAG store. User data is uploaded via the VertexRagDataService. */
@@ -5347,6 +5492,8 @@ export declare interface SafetyRating {
     blocked?: boolean;
     /** Output only. Harm category. */
     category?: HarmCategory;
+    /** Output only. The overwritten threshold for the safety category of Gemini 2.0 image out. If minors are detected in the output image, the threshold of each safety category will be overwritten if user sets a lower threshold. */
+    overwrittenThreshold?: HarmBlockThreshold;
     /** Output only. Harm probability levels in the content. */
     probability?: HarmProbability;
     /** Output only. Harm probability score. */
@@ -5483,7 +5630,8 @@ export declare type SchemaUnion = Schema | unknown;
 export declare interface SearchEntryPoint {
     /** Optional. Web content snippet that can be embedded in a web page or an app webview. */
     renderedContent?: string;
-    /** Optional. Base64 encoded JSON representing array of tuple. */
+    /** Optional. Base64 encoded JSON representing array of tuple.
+     * @remarks Encoded as base64 string. */
     sdkBlob?: string;
 }
 
@@ -5804,7 +5952,7 @@ export declare interface SupervisedHyperParameters {
     adapterSize?: AdapterSize;
     /** Optional. Number of complete passes the model makes over the entire training dataset during training. */
     epochCount?: string;
-    /** Optional. Multiplier for adjusting the default learning rate. */
+    /** Optional. Multiplier for adjusting the default learning rate. Mutually exclusive with `learning_rate`. */
     learningRateMultiplier?: number;
 }
 
@@ -5874,9 +6022,9 @@ export declare interface SupervisedTuningSpec {
     exportLastCheckpointOnly?: boolean;
     /** Optional. Hyperparameters for SFT. */
     hyperParameters?: SupervisedHyperParameters;
-    /** Required. Cloud Storage path to file containing training dataset for tuning. The dataset must be formatted as a JSONL file. */
+    /** Required. Training dataset used for tuning. The dataset can be specified as either a Cloud Storage path to a JSONL file or as the resource name of a Vertex Multimodal Dataset. */
     trainingDatasetUri?: string;
-    /** Optional. Cloud Storage path to file containing validation dataset for tuning. The dataset must be formatted as a JSONL file. */
+    /** Optional. Validation dataset used for tuning. The dataset can be specified as either a Cloud Storage path to a JSONL file or as the resource name of a Vertex Multimodal Dataset. */
     validationDatasetUri?: string;
 }
 
@@ -6005,7 +6153,8 @@ export declare interface TokensInfo {
     role?: string;
     /** A list of token ids from the input. */
     tokenIds?: string[];
-    /** A list of tokens from the input. */
+    /** A list of tokens from the input.
+     * @remarks Encoded as base64 string. */
     tokens?: string[];
 }
 
@@ -6030,12 +6179,20 @@ export declare interface Tool {
     urlContext?: UrlContext;
     /** Optional. CodeExecution tool type. Enables the model to execute code as part of generation. */
     codeExecution?: ToolCodeExecution;
+    /** Optional. Tool to support the model interacting directly with the computer. If enabled, it automatically populates computer-use specific Function Declarations. */
+    computerUse?: ToolComputerUse;
 }
 
 /** Tool that executes code generated by the model, and automatically returns the result to the model. See also [ExecutableCode]and [CodeExecutionResult] which are input and output to this tool. */
 export declare interface ToolCodeExecution {
 }
 
+/** Tool to support computer use. */
+export declare interface ToolComputerUse {
+    /** Required. The environment being operated. */
+    environment?: Environment;
+}
+
 /** Tool config.
 
  This config is shared for all tools provided in the request.
@@ -6119,6 +6276,8 @@ export declare interface TunedModelInfo {
 export declare interface TuningDataset {
     /** GCS URI of the file containing training dataset in JSONL format. */
     gcsUri?: string;
+    /** The resource name of the Vertex Multimodal Dataset that is used as training dataset. Example: 'projects/my-project-id-or-number/locations/my-location/datasets/my-dataset-id'. */
+    vertexDatasetResource?: string;
     /** Inline examples with simple input/output text. */
     examples?: TuningExample[];
 }
@@ -6176,6 +6335,10 @@ export declare interface TuningJob {
     labels?: Record<string, string>;
     /** Output only. The resource name of the PipelineJob associated with the TuningJob. Format: `projects/{project}/locations/{location}/pipelineJobs/{pipeline_job}`. */
     pipelineJob?: string;
+    /** Output only. Reserved for future use. */
+    satisfiesPzi?: boolean;
+    /** Output only. Reserved for future use. */
+    satisfiesPzs?: boolean;
     /** The service account that the tuningJob workload runs as. If not specified, the Vertex AI Secure Fine-Tuned Service Agent in the project will be used. See https://cloud.google.com/iam/docs/service-agents#vertex-ai-secure-fine-tuning-service-agent Users starting the pipeline must have the `iam.serviceAccounts.actAs` permission on this service account. */
     serviceAccount?: string;
     /** Optional. The display name of the TunedModel. The name can be up to 128 characters long and can consist of any UTF-8 characters. */
@@ -6224,6 +6387,8 @@ declare class Tunings extends BaseModule {
 export declare interface TuningValidationDataset {
     /** GCS URI of the file containing validation dataset in JSONL format. */
     gcsUri?: string;
+    /** The resource name of the Vertex Multimodal Dataset that is used as training dataset. Example: 'projects/my-project-id-or-number/locations/my-location/datasets/my-dataset-id'. */
+    vertexDatasetResource?: string;
 }
 
 /** Options about which input is included in the user's turn. */
@@ -6297,6 +6462,9 @@ declare namespace types {
         HarmBlockThreshold,
         Mode,
         AuthType,
+        ApiSpec,
+        Environment,
+        UrlRetrievalStatus,
         FinishReason,
         HarmProbability,
         HarmSeverity,
@@ -6310,7 +6478,6 @@ declare namespace types {
         Behavior,
         DynamicRetrievalConfigMode,
         FunctionCallingConfigMode,
-        UrlRetrievalStatus,
         SafetyFilterLevel,
         PersonGeneration,
         ImagePromptLanguage,
@@ -6356,6 +6523,11 @@ declare namespace types {
         AuthConfig,
         GoogleMaps,
         UrlContext,
+        ApiAuthApiKeyConfig,
+        ApiAuth,
+        ExternalApiElasticSearchParams,
+        ExternalApiSimpleSearchParams,
+        ExternalApi,
         VertexAISearchDataStoreSpec,
         VertexAISearch,
         VertexRagStoreRagResource,
@@ -6368,6 +6540,7 @@ declare namespace types {
         VertexRagStore,
         Retrieval,
         ToolCodeExecution,
+        ToolComputerUse,
         Tool,
         FunctionCallingConfig,
         LatLng,
@@ -6532,6 +6705,9 @@ declare namespace types {
         ListBatchJobsConfig,
         ListBatchJobsParameters,
         ListBatchJobsResponse,
+        DeleteBatchJobConfig,
+        DeleteBatchJobParameters,
+        DeleteResourceJob,
         GetOperationConfig,
         GetOperationParameters,
         FetchPredictOperationConfig,
@@ -6880,7 +7056,8 @@ export declare interface VertexRagStoreRagResource {
 export declare interface Video {
     /** Path to another storage. */
     uri?: string;
-    /** Video bytes. */
+    /** Video bytes.
+     * @remarks Encoded as base64 string. */
     videoBytes?: string;
     /** Video encoding, for example "video/mp4". */
     mimeType?: string;