@ai-sdk/google 3.0.113 → 3.0.116

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/google",
-  "version": "3.0.113",
+  "version": "3.0.116",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -37,7 +37,7 @@
   },
   "dependencies": {
     "@ai-sdk/provider": "3.0.15",
-    "@ai-sdk/provider-utils": "4.0.48"
+    "@ai-sdk/provider-utils": "4.0.49"
   },
   "devDependencies": {
     "@types/node": "20.17.24",

package/src/convert-json-schema-to-openapi-schema.ts

@@ -14,6 +14,18 @@ type ReferenceContext = {
   resolvingReferences: ReadonlySet<string>;
 };
 
+const recursiveReferenceFunctionalityPrefix =
+  'recursive JSON Schema reference:';
+
+export function isRecursiveJSONSchemaReferenceError(
+  error: unknown,
+): error is UnsupportedFunctionalityError {
+  return (
+    UnsupportedFunctionalityError.isInstance(error) &&
+    error.functionality.startsWith(recursiveReferenceFunctionalityPrefix)
+  );
+}
+
 /**
  * Converts JSON Schema 7 to OpenAPI Schema 3.0
  */
@@ -88,10 +100,6 @@ function convertJSONSchemaDefinition(
   if (required) result.required = required;
   if (format) result.format = format;
 
-  if (constValue !== undefined) {
-    result.enum = [constValue];
-  }
-
   // Handle type
   if (type) {
     if (Array.isArray(type)) {
@@ -113,9 +121,11 @@ function convertJSONSchemaDefinition(
     }
   }
 
-  // Handle enum
-  if (enumValues !== undefined) {
-    result.enum = enumValues;
+  const values =
+    enumValues ?? (constValue !== undefined ? [constValue] : undefined);
+
+  if (values !== undefined) {
+    addEnumToSchema({ values, type, result });
   }
 
   if (properties != null) {
@@ -189,6 +199,123 @@ function convertJSONSchemaDefinition(
   return result;
 }
 
+type EnumValues = NonNullable<JSONSchema7['enum']>;
+type EnumType = 'string' | 'number' | 'integer' | 'boolean';
+type GoogleEnumSchema = {
+  type?: JSONSchema7['type'];
+  enum?: JSONSchema7['enum'];
+  format?: JSONSchema7['format'];
+  anyOf?: JSONSchema7['anyOf'];
+  nullable?: boolean;
+};
+
+function addEnumToSchema({
+  values,
+  type,
+  result,
+}: {
+  values: EnumValues;
+  type: JSONSchema7['type'];
+  result: GoogleEnumSchema;
+}) {
+  const nullable =
+    (Array.isArray(type) && type.includes('null')) ||
+    (type === undefined && values.includes(null));
+
+  // Gemini uses nullable instead of a null enum member.
+  const enumValues = nullable ? values.filter(value => value !== null) : values;
+
+  if (values.length > 0 && values.every(value => value === null)) {
+    const typeAllowsNull =
+      type === undefined ||
+      type === 'null' ||
+      (Array.isArray(type) && type.includes('null'));
+
+    if (typeAllowsNull) {
+      result.type = 'null';
+      if (Array.isArray(type)) {
+        delete result.anyOf;
+      }
+      return;
+    }
+  }
+
+  const enumType = getEnumType({ values: enumValues, type });
+
+  if (enumType === undefined) {
+    throw new UnsupportedFunctionalityError({
+      functionality: 'JSON Schema enum with mixed or unsupported values',
+      message:
+        'Google does not support this JSON Schema enum. Enum values must share one supported primitive type and match the schema type.',
+    });
+  }
+
+  result.type = enumType;
+
+  // The earlier type-array conversion created anyOf. The enum gives us one
+  // concrete value type, so store that type directly.
+  if (Array.isArray(type)) {
+    delete result.anyOf;
+  }
+
+  if (nullable) {
+    result.nullable = true;
+  }
+
+  if (enumType === 'string') {
+    result.enum = enumValues;
+  } else {
+    result.format = 'enum';
+    result.enum = enumValues.map(String);
+  }
+}
+
+function getEnumType({
+  values,
+  type,
+}: {
+  values: EnumValues;
+  type: JSONSchema7['type'];
+}): EnumType | undefined {
+  if (values.length === 0) {
+    return undefined;
+  }
+
+  const typeAllows = (enumType: EnumType) =>
+    type === undefined ||
+    type === enumType ||
+    (Array.isArray(type) && type.includes(enumType));
+
+  if (
+    typeAllows('string') &&
+    values.every(value => typeof value === 'string')
+  ) {
+    return 'string';
+  }
+
+  if (
+    (typeAllows('number') || typeAllows('integer')) &&
+    values.every(value => typeof value === 'number' && Number.isFinite(value))
+  ) {
+    if (typeAllows('number')) {
+      return 'number';
+    }
+
+    if (values.every(value => Number.isInteger(value))) {
+      return 'integer';
+    }
+  }
+
+  if (
+    typeAllows('boolean') &&
+    values.every(value => typeof value === 'boolean')
+  ) {
+    return 'boolean';
+  }
+
+  return undefined;
+}
+
 function convertJSONSchemaReference({
   jsonSchema,
   reference,
@@ -207,7 +334,7 @@ function convertJSONSchemaReference({
 
   if (referenceContext.resolvingReferences.has(referenceKey)) {
     throw new UnsupportedFunctionalityError({
-      functionality: `recursive JSON Schema reference: ${reference}`,
+      functionality: `${recursiveReferenceFunctionalityPrefix} ${reference}`,
       message:
         'Google schema conversion does not support recursive JSON Schema references.',
     });
@@ -306,6 +433,7 @@ function throwUnsupportedReference(reference: string): never {
       'Google schema conversion only supports references to direct children of root-level $defs or definitions.',
   });
 }
+
 function isEmptyObjectSchema(jsonSchema: JSONSchema7Definition): boolean {
   return (
     jsonSchema != null &&

package/src/google-prepare-tools.ts

@@ -3,10 +3,25 @@ import {
   type LanguageModelV3CallOptions,
   type SharedV3Warning,
 } from '@ai-sdk/provider';
-import { convertJSONSchemaToOpenAPISchema } from './convert-json-schema-to-openapi-schema';
+import {
+  convertJSONSchemaToOpenAPISchema,
+  isRecursiveJSONSchemaReferenceError,
+} from './convert-json-schema-to-openapi-schema';
 import type { GoogleGenerativeAIModelId } from './google-generative-ai-options';
 import { getGoogleModelCapabilities } from './google-model-capabilities';
 
+type FunctionTool = Extract<
+  NonNullable<LanguageModelV3CallOptions['tools']>[number],
+  { type: 'function' }
+>;
+
+type GoogleFunctionDeclaration = {
+  name: string;
+  description: string;
+  parameters?: unknown;
+  parametersJsonSchema?: unknown;
+};
+
 export function prepareTools({
   tools,
   toolChoice,
@@ -21,11 +36,7 @@ export function prepareTools({
   tools:
     | Array<
         | {
-            functionDeclarations: Array<{
-              name: string;
-              description: string;
-              parameters: unknown;
-            }>;
+            functionDeclarations: GoogleFunctionDeclaration[];
           }
         | Record<string, any>
       >
@@ -172,18 +183,10 @@ export function prepareTools({
     });
 
     if (hasFunctionTools && usesGemini3Features && googleTools.length > 0) {
-      const functionDeclarations: Array<{
-        name: string;
-        description: string;
-        parameters: unknown;
-      }> = [];
+      const functionDeclarations: GoogleFunctionDeclaration[] = [];
       for (const tool of tools) {
         if (tool.type === 'function') {
-          functionDeclarations.push({
-            name: tool.name,
-            description: tool.description ?? '',
-            parameters: convertJSONSchemaToOpenAPISchema(tool.inputSchema),
-          });
+          functionDeclarations.push(prepareFunctionDeclaration(tool));
         }
       }
 
@@ -238,11 +241,7 @@ export function prepareTools({
   for (const tool of tools) {
     switch (tool.type) {
       case 'function':
-        functionDeclarations.push({
-          name: tool.name,
-          description: tool.description ?? '',
-          parameters: convertJSONSchemaToOpenAPISchema(tool.inputSchema),
-        });
+        functionDeclarations.push(prepareFunctionDeclaration(tool));
         if (tool.strict === true) {
           hasStrictTools = true;
         }
@@ -314,3 +313,28 @@ export function prepareTools({
     }
   }
 }
+
+function prepareFunctionDeclaration(
+  tool: FunctionTool,
+): GoogleFunctionDeclaration {
+  const declaration = {
+    name: tool.name,
+    description: tool.description ?? '',
+  };
+
+  try {
+    return {
+      ...declaration,
+      parameters: convertJSONSchemaToOpenAPISchema(tool.inputSchema),
+    };
+  } catch (error) {
+    if (!isRecursiveJSONSchemaReferenceError(error)) {
+      throw error;
+    }
+
+    return {
+      ...declaration,
+      parametersJsonSchema: tool.inputSchema,
+    };
+  }
+}

package/src/google-provider.ts

@@ -4,6 +4,7 @@ import type {
   ImageModelV3,
   LanguageModelV3,
   ProviderV3,
+  TranscriptionModelV3,
 } from '@ai-sdk/provider';
 import {
   generateId,
@@ -32,6 +33,8 @@ import {
 } from './interactions/google-interactions-language-model';
 import type { GoogleInteractionsModelId } from './interactions/google-interactions-language-model-options';
 import type { GoogleInteractionsAgentName } from './interactions/google-interactions-agent';
+import { GoogleTranscriptionModel } from './transcription/google-transcription-model';
+import type { GoogleTranscriptionModelId } from './transcription/google-transcription-model-options';
 
 export interface GoogleGenerativeAIProvider extends ProviderV3 {
   (modelId: GoogleGenerativeAIModelId): LanguageModelV3;
@@ -75,6 +78,17 @@ export interface GoogleGenerativeAIProvider extends ProviderV3 {
     modelId: GoogleGenerativeAIEmbeddingModelId,
   ): EmbeddingModelV3;
 
+  /**
+   * Creates a model for transcription (speech-to-text), e.g.
+   * `gemini-3.5-transcribe`.
+   */
+  transcription(modelId: GoogleTranscriptionModelId): TranscriptionModelV3;
+
+  /**
+   * Creates a model for transcription (speech-to-text).
+   */
+  transcriptionModel(modelId: GoogleTranscriptionModelId): TranscriptionModelV3;
+
   /**
    * Creates a model for video generation.
    */
@@ -245,6 +259,14 @@ export function createGoogleGenerativeAI(
       fetch: options.fetch,
     });
 
+  const createTranscriptionModel = (modelId: GoogleTranscriptionModelId) =>
+    new GoogleTranscriptionModel(modelId, {
+      provider: `${providerName}.transcription`,
+      baseURL,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
+
   const createVideoModel = (modelId: GoogleGenerativeAIVideoModelId) =>
     new GoogleGenerativeAIVideoModel(modelId, {
       provider: providerName,
@@ -291,6 +313,8 @@ export function createGoogleGenerativeAI(
   provider.textEmbeddingModel = createEmbeddingModel;
   provider.image = createImageModel;
   provider.imageModel = createImageModel;
+  provider.transcription = createTranscriptionModel;
+  provider.transcriptionModel = createTranscriptionModel;
   provider.video = createVideoModel;
   provider.videoModel = createVideoModel;
   provider.interactions = createInteractionsModel;

package/src/index.ts

@@ -27,6 +27,11 @@ export type {
 } from './interactions/google-interactions-language-model-options';
 export type { GoogleInteractionsProviderMetadata } from './interactions/google-interactions-provider-metadata';
 export type { GoogleInteractionsAgentName } from './interactions/google-interactions-agent';
+export { GoogleTranscriptionModel } from './transcription/google-transcription-model';
+export type {
+  GoogleTranscriptionModelId,
+  GoogleTranscriptionModelOptions,
+} from './transcription/google-transcription-model-options';
 export { createGoogleGenerativeAI, google } from './google-provider';
 export type {
   GoogleGenerativeAIProvider,

package/src/transcription/google-transcription-model-options.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod/v4';
+
+export type GoogleTranscriptionModelId =
+  | 'gemini-3.5-transcribe'
+  | 'gemini-3.5-transcribe-live'
+  | (string & {});
+
+/**
+ * Speech recognition options for Gemini transcription models
+ * (`gemini-3.5-transcribe`). Maps onto Google's `AudioTranscriptionConfig`.
+ * The live variant (`gemini-3.5-transcribe-live`) requires streaming
+ * transcription, which is only available in AI SDK v7.
+ */
+export const googleTranscriptionModelOptions = z.object({
+  /**
+   * BCP-47 language codes providing hints about the languages present in the
+   * audio. If omitted or empty, defaults to automatic language detection.
+   */
+  languageCodes: z.array(z.string()).optional(),
+
+  /**
+   * Custom vocabulary phrases, which bias the speech recognition model
+   * toward recognizing specific terms.
+   */
+  customVocabulary: z.array(z.string()).optional(),
+
+  /**
+   * Enables word-level timestamp generation.
+   */
+  wordTimestamp: z.boolean().optional(),
+
+  /**
+   * Enables speaker diarization.
+   */
+  diarization: z.boolean().optional(),
+
+  /**
+   * Transcription output formatting mode.
+   *
+   * - `VERBATIM` (default): exact literal transcript preserving filler
+   *   words, repetitions, and false starts.
+   * - `SMART`: cleans up and structures the transcript in real time —
+   *   disfluency removal, inline self-corrections, structured formatting
+   *   (lists, numbers, dates, paragraph breaks), and grammar/casing polish.
+   */
+  mode: z.enum(['SMART', 'VERBATIM']).optional(),
+});
+
+export type GoogleTranscriptionModelOptions = z.infer<
+  typeof googleTranscriptionModelOptions
+>;

package/src/transcription/google-transcription-model.ts

@@ -0,0 +1,243 @@
+import {
+  InvalidArgumentError,
+  type JSONObject,
+  type SharedV3Warning,
+  type TranscriptionModelV3,
+} from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  convertToBase64,
+  createJsonResponseHandler,
+  parseProviderOptions,
+  postJsonToApi,
+  resolve,
+  type FetchFunction,
+  type Resolvable,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import { googleFailedResponseHandler } from '../google-error';
+import {
+  googleTranscriptionModelOptions,
+  type GoogleTranscriptionModelId,
+  type GoogleTranscriptionModelOptions,
+} from './google-transcription-model-options';
+
+/**
+ * Live transcription (`*-live` model variants) requires streaming support,
+ * which is only available in AI SDK v7 (transcription specification v4).
+ */
+function isLiveTranscriptionModelId(modelId: string): boolean {
+  return modelId.includes('-live');
+}
+
+interface GoogleTranscriptionModelConfig {
+  provider: string;
+  baseURL: string;
+  headers?: Resolvable<Record<string, string | undefined>>;
+  fetch?: FetchFunction;
+  _internal?: {
+    currentDate?: () => Date;
+  };
+}
+
+/**
+ * Gemini transcription (speech-to-text) via the Interactions API
+ * (e.g. `gemini-3.5-transcribe`).
+ *
+ * @see https://ai.google.dev/gemini-api/docs/transcribe
+ */
+export class GoogleTranscriptionModel implements TranscriptionModelV3 {
+  readonly specificationVersion = 'v3';
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  constructor(
+    readonly modelId: GoogleTranscriptionModelId,
+    private readonly config: GoogleTranscriptionModelConfig,
+  ) {}
+
+  private async parseOptions(
+    providerOptions: Record<string, unknown> | undefined,
+  ): Promise<GoogleTranscriptionModelOptions | undefined> {
+    return parseProviderOptions({
+      provider: 'google',
+      providerOptions,
+      schema: googleTranscriptionModelOptions,
+    });
+  }
+
+  async doGenerate(
+    options: Parameters<TranscriptionModelV3['doGenerate']>[0],
+  ): Promise<Awaited<ReturnType<TranscriptionModelV3['doGenerate']>>> {
+    if (isLiveTranscriptionModelId(this.modelId)) {
+      throw new InvalidArgumentError({
+        argument: 'modelId',
+        message:
+          `Model '${this.modelId}' only supports streaming transcription, ` +
+          `which requires AI SDK v7. Use a unary model such as 'gemini-3.5-transcribe'.`,
+      });
+    }
+
+    const currentDate = this.config._internal?.currentDate?.() ?? new Date();
+    const warnings: SharedV3Warning[] = [];
+    const googleOptions = await this.parseOptions(options.providerOptions);
+    const transcriptionConfig = buildTranscriptionConfig(googleOptions);
+
+    // Unary transcription is served by the Interactions API
+    // (https://ai.google.dev/gemini-api/docs/transcribe).
+    const requestBody = {
+      model: this.modelId,
+      input: [
+        {
+          type: 'audio',
+          data: convertToBase64(options.audio),
+          mime_type: options.mediaType,
+        },
+      ],
+      ...(transcriptionConfig != null
+        ? { generation_config: { transcription_config: transcriptionConfig } }
+        : {}),
+    };
+
+    const {
+      value: response,
+      responseHeaders,
+      rawValue: rawResponse,
+    } = await postJsonToApi({
+      url: `${this.config.baseURL}/interactions`,
+      headers: combineHeaders(
+        this.config.headers ? await resolve(this.config.headers) : undefined,
+        options.headers,
+      ),
+      body: requestBody,
+      failedResponseHandler: googleFailedResponseHandler,
+      successfulResponseHandler: createJsonResponseHandler(
+        googleInteractionsTranscriptionResponseSchema,
+      ),
+      abortSignal: options.abortSignal,
+      fetch: this.config.fetch,
+    });
+
+    let text = '';
+    const segments: Array<{
+      text: string;
+      startSecond: number;
+      endSecond: number;
+    }> = [];
+    for (const step of response.steps ?? []) {
+      for (const content of step.content ?? []) {
+        if (content.type !== 'text' || content.text == null) continue;
+        text += content.text;
+        for (const annotation of content.annotations ?? []) {
+          if (annotation.type !== 'word_info') continue;
+          const startSecond = parseOffsetSeconds(annotation.start_offset);
+          const endSecond = parseOffsetSeconds(annotation.end_offset);
+          if (
+            annotation.text == null ||
+            startSecond == null ||
+            endSecond == null
+          ) {
+            continue;
+          }
+          segments.push({ text: annotation.text, startSecond, endSecond });
+        }
+      }
+    }
+
+    return {
+      text,
+      segments,
+      language: undefined,
+      durationInSeconds: undefined,
+      warnings,
+      response: {
+        timestamp: currentDate,
+        modelId: this.modelId,
+        headers: responseHeaders,
+        body: rawResponse,
+      },
+      ...(response.usage != null
+        ? {
+            providerMetadata: {
+              google: { usage: response.usage as JSONObject },
+            },
+          }
+        : {}),
+    };
+  }
+}
+
+/**
+ * Builds the Interactions API `transcription_config` (snake_case wire) from
+ * provider options; returns undefined when no options are set. Diarization
+ * and word timestamps are expressed inside the `mode` object per
+ * https://ai.google.dev/gemini-api/docs/transcribe.
+ */
+function buildTranscriptionConfig(
+  options: GoogleTranscriptionModelOptions | undefined,
+): Record<string, unknown> | undefined {
+  if (options == null) return undefined;
+  const config: Record<string, unknown> = {};
+  if (options.languageCodes != null) {
+    config.language_codes = options.languageCodes;
+  }
+  if (options.customVocabulary != null) {
+    config.custom_vocabulary = options.customVocabulary;
+  }
+  if (
+    options.mode != null ||
+    options.diarization === true ||
+    options.wordTimestamp === true
+  ) {
+    config.mode = {
+      type: (options.mode ?? 'VERBATIM').toLowerCase(),
+      ...(options.diarization === true ? { diarization_mode: 'speaker' } : {}),
+      ...(options.wordTimestamp === true
+        ? { timestamp_granularities: ['word'] }
+        : {}),
+    };
+  }
+  return Object.keys(config).length > 0 ? config : undefined;
+}
+
+/** Parses a Google duration offset such as `"1s"` or `"9.400s"` to seconds. */
+function parseOffsetSeconds(
+  offset: string | undefined | null,
+): number | undefined {
+  if (offset == null) return undefined;
+  const parsed = Number.parseFloat(offset);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+const googleInteractionsWordAnnotationSchema = z.object({
+  type: z.string().nullish(),
+  text: z.string().nullish(),
+  speaker: z.string().nullish(),
+  start_offset: z.string().nullish(),
+  end_offset: z.string().nullish(),
+});
+
+const googleInteractionsTranscriptionResponseSchema = z.object({
+  status: z.string().nullish(),
+  steps: z
+    .array(
+      z.object({
+        type: z.string().nullish(),
+        content: z
+          .array(
+            z.object({
+              type: z.string().nullish(),
+              text: z.string().nullish(),
+              annotations: z
+                .array(googleInteractionsWordAnnotationSchema)
+                .nullish(),
+            }),
+          )
+          .nullish(),
+      }),
+    )
+    .nullish(),
+  usage: z.record(z.string(), z.unknown()).nullish(),
+});