@ai-sdk/google 3.0.9 → 3.0.11

package/src/google-generative-ai-options.ts

@@ -0,0 +1,193 @@
+import { InferSchema, lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+export type GoogleGenerativeAIModelId =
+  // Stable models
+  // https://ai.google.dev/gemini-api/docs/models/gemini
+  | 'gemini-1.5-flash'
+  | 'gemini-1.5-flash-latest'
+  | 'gemini-1.5-flash-001'
+  | 'gemini-1.5-flash-002'
+  | 'gemini-1.5-flash-8b'
+  | 'gemini-1.5-flash-8b-latest'
+  | 'gemini-1.5-flash-8b-001'
+  | 'gemini-1.5-pro'
+  | 'gemini-1.5-pro-latest'
+  | 'gemini-1.5-pro-001'
+  | 'gemini-1.5-pro-002'
+  | 'gemini-2.0-flash'
+  | 'gemini-2.0-flash-001'
+  | 'gemini-2.0-flash-live-001'
+  | 'gemini-2.0-flash-lite'
+  | 'gemini-2.0-pro-exp-02-05'
+  | 'gemini-2.0-flash-thinking-exp-01-21'
+  | 'gemini-2.0-flash-exp'
+  | 'gemini-2.5-pro'
+  | 'gemini-2.5-flash'
+  | 'gemini-2.5-flash-image-preview'
+  | 'gemini-2.5-flash-lite'
+  | 'gemini-2.5-flash-lite-preview-09-2025'
+  | 'gemini-2.5-flash-preview-04-17'
+  | 'gemini-2.5-flash-preview-09-2025'
+  | 'gemini-3-pro-preview'
+  | 'gemini-3-pro-image-preview'
+  | 'gemini-3-flash-preview'
+  // latest version
+  // https://ai.google.dev/gemini-api/docs/models#latest
+  | 'gemini-pro-latest'
+  | 'gemini-flash-latest'
+  | 'gemini-flash-lite-latest'
+  // Experimental models
+  // https://ai.google.dev/gemini-api/docs/models/experimental-models
+  | 'gemini-2.5-pro-exp-03-25'
+  | 'gemini-exp-1206'
+  | 'gemma-3-12b-it'
+  | 'gemma-3-27b-it'
+  | (string & {});
+
+export const googleGenerativeAIProviderOptions = lazySchema(() =>
+  zodSchema(
+    z.object({
+      responseModalities: z.array(z.enum(['TEXT', 'IMAGE'])).optional(),
+
+      thinkingConfig: z
+        .object({
+          thinkingBudget: z.number().optional(),
+          includeThoughts: z.boolean().optional(),
+          // https://ai.google.dev/gemini-api/docs/gemini-3?thinking=high#thinking_level
+          thinkingLevel: z
+            .enum(['minimal', 'low', 'medium', 'high'])
+            .optional(),
+        })
+        .optional(),
+
+      /**
+       * Optional.
+       * The name of the cached content used as context to serve the prediction.
+       * Format: cachedContents/{cachedContent}
+       */
+      cachedContent: z.string().optional(),
+
+      /**
+       * Optional. Enable structured output. Default is true.
+       *
+       * This is useful when the JSON Schema contains elements that are
+       * not supported by the OpenAPI schema version that
+       * Google Generative AI uses. You can use this to disable
+       * structured outputs if you need to.
+       */
+      structuredOutputs: z.boolean().optional(),
+
+      /**
+       * Optional. A list of unique safety settings for blocking unsafe content.
+       */
+      safetySettings: z
+        .array(
+          z.object({
+            category: z.enum([
+              'HARM_CATEGORY_UNSPECIFIED',
+              'HARM_CATEGORY_HATE_SPEECH',
+              'HARM_CATEGORY_DANGEROUS_CONTENT',
+              'HARM_CATEGORY_HARASSMENT',
+              'HARM_CATEGORY_SEXUALLY_EXPLICIT',
+              'HARM_CATEGORY_CIVIC_INTEGRITY',
+            ]),
+            threshold: z.enum([
+              'HARM_BLOCK_THRESHOLD_UNSPECIFIED',
+              'BLOCK_LOW_AND_ABOVE',
+              'BLOCK_MEDIUM_AND_ABOVE',
+              'BLOCK_ONLY_HIGH',
+              'BLOCK_NONE',
+              'OFF',
+            ]),
+          }),
+        )
+        .optional(),
+
+      threshold: z
+        .enum([
+          'HARM_BLOCK_THRESHOLD_UNSPECIFIED',
+          'BLOCK_LOW_AND_ABOVE',
+          'BLOCK_MEDIUM_AND_ABOVE',
+          'BLOCK_ONLY_HIGH',
+          'BLOCK_NONE',
+          'OFF',
+        ])
+        .optional(),
+
+      /**
+       * Optional. Enables timestamp understanding for audio-only files.
+       *
+       * https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/audio-understanding
+       */
+      audioTimestamp: z.boolean().optional(),
+
+      /**
+       * Optional. Defines labels used in billing reports. Available on Vertex AI only.
+       *
+       * https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/add-labels-to-api-calls
+       */
+      labels: z.record(z.string(), z.string()).optional(),
+
+      /**
+       * Optional. If specified, the media resolution specified will be used.
+       *
+       * https://ai.google.dev/api/generate-content#MediaResolution
+       */
+      mediaResolution: z
+        .enum([
+          'MEDIA_RESOLUTION_UNSPECIFIED',
+          'MEDIA_RESOLUTION_LOW',
+          'MEDIA_RESOLUTION_MEDIUM',
+          'MEDIA_RESOLUTION_HIGH',
+        ])
+        .optional(),
+
+      /**
+       * Optional. Configures the image generation aspect ratio for Gemini models.
+       *
+       * https://ai.google.dev/gemini-api/docs/image-generation#aspect_ratios
+       */
+      imageConfig: z
+        .object({
+          aspectRatio: z
+            .enum([
+              '1:1',
+              '2:3',
+              '3:2',
+              '3:4',
+              '4:3',
+              '4:5',
+              '5:4',
+              '9:16',
+              '16:9',
+              '21:9',
+            ])
+            .optional(),
+          imageSize: z.enum(['1K', '2K', '4K']).optional(),
+        })
+        .optional(),
+
+      /**
+       * Optional. Configuration for grounding retrieval.
+       * Used to provide location context for Google Maps and Google Search grounding.
+       *
+       * https://cloud.google.com/vertex-ai/generative-ai/docs/grounding/grounding-with-google-maps
+       */
+      retrievalConfig: z
+        .object({
+          latLng: z
+            .object({
+              latitude: z.number(),
+              longitude: z.number(),
+            })
+            .optional(),
+        })
+        .optional(),
+    }),
+  ),
+);
+
+export type GoogleGenerativeAIProviderOptions = InferSchema<
+  typeof googleGenerativeAIProviderOptions
+>;

package/src/google-generative-ai-prompt.ts

@@ -0,0 +1,38 @@
+import {
+  GroundingMetadataSchema,
+  UrlContextMetadataSchema,
+} from './google-generative-ai-language-model';
+import { type SafetyRatingSchema } from './google-generative-ai-language-model';
+
+export type GoogleGenerativeAIPrompt = {
+  systemInstruction?: GoogleGenerativeAISystemInstruction;
+  contents: Array<GoogleGenerativeAIContent>;
+};
+
+export type GoogleGenerativeAISystemInstruction = {
+  parts: Array<{ text: string }>;
+};
+
+export type GoogleGenerativeAIContent = {
+  role: 'user' | 'model';
+  parts: Array<GoogleGenerativeAIContentPart>;
+};
+
+export type GoogleGenerativeAIContentPart =
+  | { text: string; thought?: boolean; thoughtSignature?: string }
+  | { inlineData: { mimeType: string; data: string } }
+  | { functionCall: { name: string; args: unknown }; thoughtSignature?: string }
+  | { functionResponse: { name: string; response: unknown } }
+  | { fileData: { mimeType: string; fileUri: string } };
+
+export type GoogleGenerativeAIGroundingMetadata = GroundingMetadataSchema;
+
+export type GoogleGenerativeAIUrlContextMetadata = UrlContextMetadataSchema;
+
+export type GoogleGenerativeAISafetyRating = SafetyRatingSchema;
+
+export interface GoogleGenerativeAIProviderMetadata {
+  groundingMetadata: GoogleGenerativeAIGroundingMetadata | null;
+  urlContextMetadata: GoogleGenerativeAIUrlContextMetadata | null;
+  safetyRatings: GoogleGenerativeAISafetyRating[] | null;
+}

package/src/google-prepare-tools.test.ts

@@ -0,0 +1,474 @@
+import { LanguageModelV3ProviderTool } from '@ai-sdk/provider';
+import { expect, it } from 'vitest';
+import { prepareTools } from './google-prepare-tools';
+
+it('should return undefined tools and tool_choice when tools are null', () => {
+  const result = prepareTools({
+    tools: undefined,
+    modelId: 'gemini-2.5-flash',
+  });
+  expect(result).toEqual({
+    tools: undefined,
+    tool_choice: undefined,
+    toolWarnings: [],
+  });
+});
+
+it('should return undefined tools and tool_choice when tools are empty', () => {
+  const result = prepareTools({ tools: [], modelId: 'gemini-2.5-flash' });
+  expect(result).toEqual({
+    tools: undefined,
+    tool_choice: undefined,
+    toolWarnings: [],
+  });
+});
+
+it('should correctly prepare function tools', () => {
+  const result = prepareTools({
+    tools: [
+      {
+        type: 'function',
+        name: 'testFunction',
+        description: 'A test function',
+        inputSchema: { type: 'object', properties: {} },
+      },
+    ],
+    modelId: 'gemini-2.5-flash',
+  });
+  expect(result.tools).toEqual([
+    {
+      functionDeclarations: [
+        {
+          name: 'testFunction',
+          description: 'A test function',
+          parameters: undefined,
+        },
+      ],
+    },
+  ]);
+  expect(result.toolConfig).toBeUndefined();
+  expect(result.toolWarnings).toEqual([]);
+});
+
+it('should correctly prepare provider-defined tools as array', () => {
+  const result = prepareTools({
+    tools: [
+      {
+        type: 'provider',
+        id: 'google.google_search',
+        name: 'google_search',
+        args: {},
+      },
+      {
+        type: 'provider',
+        id: 'google.url_context',
+        name: 'url_context',
+        args: {},
+      },
+      {
+        type: 'provider',
+        id: 'google.file_search',
+        name: 'file_search',
+        args: { fileSearchStoreNames: ['projects/foo/fileSearchStores/bar'] },
+      },
+    ],
+    modelId: 'gemini-2.5-flash',
+  });
+  expect(result.tools).toEqual([
+    { googleSearch: {} },
+    { urlContext: {} },
+    {
+      fileSearch: {
+        fileSearchStoreNames: ['projects/foo/fileSearchStores/bar'],
+      },
+    },
+  ]);
+  expect(result.toolConfig).toBeUndefined();
+  expect(result.toolWarnings).toEqual([]);
+});
+
+it('should correctly prepare single provider-defined tool', () => {
+  const result = prepareTools({
+    tools: [
+      {
+        type: 'provider',
+        id: 'google.google_search',
+        name: 'google_search',
+        args: {},
+      },
+    ],
+    modelId: 'gemini-2.5-flash',
+  });
+  expect(result.tools).toEqual([{ googleSearch: {} }]);
+  expect(result.toolConfig).toBeUndefined();
+  expect(result.toolWarnings).toEqual([]);
+});
+
+it('should add warnings for unsupported tools', () => {
+  const result = prepareTools({
+    tools: [
+      {
+        type: 'provider',
+        id: 'unsupported.tool',
+        name: 'unsupported_tool',
+        args: {},
+      },
+    ],
+    modelId: 'gemini-2.5-flash',
+  });
+  expect(result.tools).toBeUndefined();
+  expect(result.toolConfig).toBeUndefined();
+  expect(result.toolWarnings).toMatchInlineSnapshot(`
+    [
+      {
+        "feature": "provider-defined tool unsupported.tool",
+        "type": "unsupported",
+      },
+    ]
+  `);
+});
+
+it('should add warnings for file search on unsupported models', () => {
+  const tool: LanguageModelV3ProviderTool = {
+    type: 'provider' as const,
+    id: 'google.file_search',
+    name: 'file_search',
+    args: { fileSearchStoreNames: ['projects/foo/fileSearchStores/bar'] },
+  };
+
+  const result = prepareTools({
+    tools: [tool],
+    modelId: 'gemini-1.5-flash-8b',
+  });
+
+  expect(result.tools).toBeUndefined();
+  expect(result.toolWarnings).toMatchInlineSnapshot(`
+    [
+      {
+        "details": "The file search tool is only supported with Gemini 2.5 models and Gemini 3 models.",
+        "feature": "provider-defined tool google.file_search",
+        "type": "unsupported",
+      },
+    ]
+  `);
+});
+
+it('should correctly prepare file search tool for gemini-2.5 models', () => {
+  const result = prepareTools({
+    tools: [
+      {
+        type: 'provider',
+        id: 'google.file_search',
+        name: 'file_search',
+        args: {
+          fileSearchStoreNames: ['projects/foo/fileSearchStores/bar'],
+          metadataFilter: 'author=Robert Graves',
+          topK: 5,
+        },
+      },
+    ],
+    modelId: 'gemini-2.5-pro',
+  });
+
+  expect(result.tools).toEqual([
+    {
+      fileSearch: {
+        fileSearchStoreNames: ['projects/foo/fileSearchStores/bar'],
+        metadataFilter: 'author=Robert Graves',
+        topK: 5,
+      },
+    },
+  ]);
+  expect(result.toolWarnings).toEqual([]);
+});
+
+it('should correctly prepare file search tool for gemini-3 models', () => {
+  const result = prepareTools({
+    tools: [
+      {
+        type: 'provider',
+        id: 'google.file_search',
+        name: 'file_search',
+        args: {
+          fileSearchStoreNames: ['projects/foo/fileSearchStores/bar'],
+          metadataFilter: 'author=Robert Graves',
+          topK: 5,
+        },
+      },
+    ],
+    modelId: 'gemini-3-pro-preview',
+  });
+
+  expect(result.tools).toEqual([
+    {
+      fileSearch: {
+        fileSearchStoreNames: ['projects/foo/fileSearchStores/bar'],
+        metadataFilter: 'author=Robert Graves',
+        topK: 5,
+      },
+    },
+  ]);
+  expect(result.toolWarnings).toEqual([]);
+});
+
+it('should handle tool choice "auto"', () => {
+  const result = prepareTools({
+    tools: [
+      {
+        type: 'function',
+        name: 'testFunction',
+        description: 'Test',
+        inputSchema: {},
+      },
+    ],
+    toolChoice: { type: 'auto' },
+    modelId: 'gemini-2.5-flash',
+  });
+  expect(result.toolConfig).toEqual({
+    functionCallingConfig: { mode: 'AUTO' },
+  });
+});
+
+it('should handle tool choice "required"', () => {
+  const result = prepareTools({
+    tools: [
+      {
+        type: 'function',
+        name: 'testFunction',
+        description: 'Test',
+        inputSchema: {},
+      },
+    ],
+    toolChoice: { type: 'required' },
+    modelId: 'gemini-2.5-flash',
+  });
+  expect(result.toolConfig).toEqual({
+    functionCallingConfig: { mode: 'ANY' },
+  });
+});
+
+it('should handle tool choice "none"', () => {
+  const result = prepareTools({
+    tools: [
+      {
+        type: 'function',
+        name: 'testFunction',
+        description: 'Test',
+        inputSchema: {},
+      },
+    ],
+    toolChoice: { type: 'none' },
+    modelId: 'gemini-2.5-flash',
+  });
+  expect(result.tools).toEqual([
+    {
+      functionDeclarations: [
+        {
+          name: 'testFunction',
+          description: 'Test',
+          parameters: {},
+        },
+      ],
+    },
+  ]);
+  expect(result.toolConfig).toEqual({
+    functionCallingConfig: { mode: 'NONE' },
+  });
+});
+
+it('should handle tool choice "tool"', () => {
+  const result = prepareTools({
+    tools: [
+      {
+        type: 'function',
+        name: 'testFunction',
+        description: 'Test',
+        inputSchema: {},
+      },
+    ],
+    toolChoice: { type: 'tool', toolName: 'testFunction' },
+    modelId: 'gemini-2.5-flash',
+  });
+  expect(result.toolConfig).toEqual({
+    functionCallingConfig: {
+      mode: 'ANY',
+      allowedFunctionNames: ['testFunction'],
+    },
+  });
+});
+
+it('should warn when mixing function and provider-defined tools', () => {
+  const result = prepareTools({
+    tools: [
+      {
+        type: 'function',
+        name: 'testFunction',
+        description: 'A test function',
+        inputSchema: { type: 'object', properties: {} },
+      },
+      {
+        type: 'provider',
+        id: 'google.google_search',
+        name: 'google_search',
+        args: {},
+      },
+    ],
+    modelId: 'gemini-2.5-flash',
+  });
+
+  expect(result.tools).toEqual([{ googleSearch: {} }]);
+
+  expect(result.toolWarnings).toMatchInlineSnapshot(`
+    [
+      {
+        "feature": "combination of function and provider-defined tools",
+        "type": "unsupported",
+      },
+    ]
+  `);
+
+  expect(result.toolConfig).toBeUndefined();
+});
+
+it('should handle tool choice with mixed tools (provider-defined tools only)', () => {
+  const result = prepareTools({
+    tools: [
+      {
+        type: 'function',
+        name: 'testFunction',
+        description: 'A test function',
+        inputSchema: { type: 'object', properties: {} },
+      },
+      {
+        type: 'provider',
+        id: 'google.google_search',
+        name: 'google_search',
+        args: {},
+      },
+    ],
+    toolChoice: { type: 'auto' },
+    modelId: 'gemini-2.5-flash',
+  });
+
+  expect(result.tools).toEqual([{ googleSearch: {} }]);
+
+  expect(result.toolConfig).toEqual(undefined);
+
+  expect(result.toolWarnings).toMatchInlineSnapshot(`
+    [
+      {
+        "feature": "combination of function and provider-defined tools",
+        "type": "unsupported",
+      },
+    ]
+  `);
+});
+
+it('should handle latest modelId for provider-defined tools correctly', () => {
+  const result = prepareTools({
+    tools: [
+      {
+        type: 'provider',
+        id: 'google.google_search',
+        name: 'google_search',
+        args: {},
+      },
+    ],
+    modelId: 'gemini-flash-latest',
+  });
+  expect(result.tools).toEqual([{ googleSearch: {} }]);
+  expect(result.toolConfig).toBeUndefined();
+  expect(result.toolWarnings).toEqual([]);
+});
+
+it('should handle gemini-3 modelId for provider-defined tools correctly', () => {
+  const result = prepareTools({
+    tools: [
+      {
+        type: 'provider',
+        id: 'google.google_search',
+        name: 'google_search',
+        args: {},
+      },
+    ],
+    modelId: 'gemini-3-pro-preview',
+  });
+  expect(result.tools).toEqual([{ googleSearch: {} }]);
+  expect(result.toolConfig).toBeUndefined();
+  expect(result.toolWarnings).toEqual([]);
+});
+
+it('should handle code execution tool', () => {
+  const result = prepareTools({
+    tools: [
+      {
+        type: 'provider',
+        id: 'google.code_execution',
+        name: 'code_execution',
+        args: {},
+      },
+    ],
+    modelId: 'gemini-2.5-flash',
+  });
+  expect(result.tools).toEqual([{ codeExecution: {} }]);
+  expect(result.toolConfig).toBeUndefined();
+  expect(result.toolWarnings).toEqual([]);
+});
+
+it('should handle url context tool alone', () => {
+  const result = prepareTools({
+    tools: [
+      {
+        type: 'provider',
+        id: 'google.url_context',
+        name: 'url_context',
+        args: {},
+      },
+    ],
+    modelId: 'gemini-2.5-flash',
+  });
+  expect(result.tools).toEqual([{ urlContext: {} }]);
+  expect(result.toolConfig).toBeUndefined();
+  expect(result.toolWarnings).toEqual([]);
+});
+
+it('should handle google maps tool', () => {
+  const result = prepareTools({
+    tools: [
+      {
+        type: 'provider',
+        id: 'google.google_maps',
+        name: 'google_maps',
+        args: {},
+      },
+    ],
+    modelId: 'gemini-2.5-flash',
+  });
+  expect(result.tools).toEqual([{ googleMaps: {} }]);
+  expect(result.toolConfig).toBeUndefined();
+  expect(result.toolWarnings).toEqual([]);
+});
+
+it('should add warnings for google maps on unsupported models', () => {
+  const result = prepareTools({
+    tools: [
+      {
+        type: 'provider',
+        id: 'google.google_maps',
+        name: 'google_maps',
+        args: {},
+      },
+    ],
+    modelId: 'gemini-1.5-flash',
+  });
+  expect(result.tools).toBeUndefined();
+  expect(result.toolWarnings).toMatchInlineSnapshot(`
+    [
+      {
+        "details": "The Google Maps grounding tool is not supported with Gemini models other than Gemini 2 or newer.",
+        "feature": "provider-defined tool google.google_maps",
+        "type": "unsupported",
+      },
+    ]
+  `);
+});