@ai-sdk/google 4.0.51 → 4.0.53

package/docs/15-google.mdx

@@ -1067,10 +1067,13 @@ The following Zod features are known to not work with Google:
 ### Text Batches
 
 <Note type="warning">
-  Text batch APIs are experimental and may change in future releases.
+  Text batch support is experimental and the API may change in patch releases.
 </Note>
 
-The Google provider supports the [Gemini Batch API](https://ai.google.dev/gemini-api/docs/batch-api) for text generation.
+The Google provider supports asynchronous text generation through the
+[Gemini Batch API](https://ai.google.dev/gemini-api/docs/batch-api). Use the
+experimental text batch APIs to start a batch, poll its status, and stream its
+results:
 
 ```ts
 import { google } from '@ai-sdk/google';
@@ -1079,32 +1082,39 @@ import {
   experimental_getBatchStatus as getBatchStatus,
   experimental_startTextBatch as startTextBatch,
 } from 'ai';
+import { setTimeout } from 'node:timers/promises';
 
 const model = google('gemini-3.6-flash');
 
 const batch = await startTextBatch({
   model,
   requests: [
-    { id: 'france', prompt: 'What is the capital of France?' },
-    { id: 'germany', prompt: 'What is the capital of Germany?' },
+    { id: 'capital-france', prompt: 'What is the capital of France?' },
+    { id: 'capital-germany', prompt: 'What is the capital of Germany?' },
   ],
 });
 
-// Persist `batch` and check its status later, or poll for status updates.
-const { status } = await getBatchStatus({ model, batch });
+let status = batch.status;
+while (status === 'pending') {
+  await setTimeout(60_000);
+  ({ status } = await getBatchStatus({ model, batch }));
+}
 
-if (status !== 'pending') {
-  for await (const item of getBatchResults({ model, batch })) {
-    if (item.status === 'succeeded') {
-      console.log(item.id, item.text);
-    } else {
-      console.error(item.id, item.error);
-    }
+for await (const item of getBatchResults({ model, batch })) {
+  if (item.status === 'succeeded') {
+    console.log(item.id, item.text);
+  } else {
+    console.error(item.id, item.error);
   }
 }
 ```
 
-Starting a batch returns a serializable reference that can be persisted and used to retrieve the batch results later, or poll for status updates.
+`startTextBatch` returns a serializable batch reference. Persist this reference
+to check the batch status or retrieve its results from another process. Results
+can arrive in a different order from the input requests, so match each result by
+its `id`.
+
+#### Webhooks
 
 You can pass a `webhookUrl` to receive a notification when the batch reaches a terminal state:
 
@@ -1112,8 +1122,8 @@ You can pass a `webhookUrl` to receive a notification when the batch reaches a t
 const batch = await startTextBatch({
   model,
   requests: [
-    { id: 'france', prompt: 'What is the capital of France?' },
-    { id: 'germany', prompt: 'What is the capital of Germany?' },
+    { id: 'capital-france', prompt: 'What is the capital of France?' },
+    { id: 'capital-germany', prompt: 'What is the capital of Germany?' },
   ],
   webhookUrl: 'https://example.com/api/google-batch-webhook',
 });
@@ -1121,6 +1131,8 @@ const batch = await startTextBatch({
 
 Google sends a thin event to the webhook URL. After receiving and verifying the event, use the persisted batch reference with `getBatchStatus` or `getBatchResults`. Your application is responsible for handling the webhook and [verifying Google's dynamic webhook signature](https://ai.google.dev/gemini-api/docs/webhooks#verify_dynamic_signatures_jwks).
 
+#### Large Batches
+
 When the serialized batch creation body is under 20 MB, the provider sends the requests inline. At 20 MB or more, it uploads a JSONL input file through the Gemini Files API.
 
 ## Realtime Models

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/google",
-  "version": "4.0.51",
+  "version": "4.0.53",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -36,7 +36,7 @@
   },
   "dependencies": {
     "@ai-sdk/provider": "4.0.8",
-    "@ai-sdk/provider-utils": "5.0.30"
+    "@ai-sdk/provider-utils": "5.0.32"
   },
   "devDependencies": {
     "@ai-sdk/test-server": "2.0.1",

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
  */
@@ -205,7 +217,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.',
     });

package/src/google-batch.ts

@@ -1,5 +1,4 @@
 import {
-  EmptyResponseBodyError,
   InvalidArgumentError,
   InvalidResponseDataError,
   type Experimental_BatchLanguageModelV4 as BatchLanguageModelV4,
@@ -14,11 +13,12 @@ import {
 import {
   combineHeaders,
   convertAsyncIteratorToReadableStream,
+  createJsonLinesResponseHandler,
   createJsonResponseHandler,
   generateId,
   getFromApi,
   lazySchema,
-  parseJSON,
+  normalizeBatchRequestCounts,
   postJsonToApi,
   postToApi,
   resolve,
@@ -399,18 +399,20 @@ export class GoogleBatchLanguageModel
       .map(segment => encodeURIComponent(segment))
       .join('/');
 
-    const { value: stream } = await getFromApi({
+    const { value: lines } = await getFromApi({
       url: `${this.getBaseOrigin()}/download/v1beta/${encodedResponsesFile}:download?alt=media`,
       headers: await this.getHeaders(options.headers),
       failedResponseHandler: googleFailedResponseHandler,
-      successfulResponseHandler: rawStreamResponseHandler,
+      successfulResponseHandler: createJsonLinesResponseHandler(
+        googleBatchResultLineSchema,
+      ),
       abortSignal: options.abortSignal,
       fetch: this.batchConfig.fetch,
       validateUrl: false,
     });
 
     return convertAsyncIteratorToReadableStream(
-      this.iterateBatchResults(parseJsonLines(stream)),
+      this.iterateBatchResults(lines),
     );
   }
 
@@ -626,22 +628,12 @@ function convertGoogleRequestCounts(
   const failed = parseCount(counts?.failedRequestCount ?? 0);
   const pending = parseCount(counts?.pendingRequestCount ?? 0);
 
-  if (
-    total == null ||
-    completed == null ||
-    failed == null ||
-    pending == null ||
-    completed + failed + pending !== total
-  ) {
-    return undefined;
-  }
-
-  return {
+  return normalizeBatchRequestCounts({
     total,
     pending,
     completed,
     failed,
-  };
+  });
 }
 
 function parseCount(value: string | number | null | undefined) {
@@ -676,64 +668,3 @@ const googleUploadUrlResponseHandler: ResponseHandler<string> = async ({
 
   return { value: uploadUrl };
 };
-
-const rawStreamResponseHandler: ResponseHandler<
-  ReadableStream<Uint8Array>
-> = async ({ response }) => {
-  if (response.body == null) {
-    throw new EmptyResponseBodyError();
-  }
-
-  return { value: response.body };
-};
-
-async function* parseJsonLines(
-  stream: ReadableStream<Uint8Array>,
-): AsyncGenerator<GoogleBatchResultLine> {
-  const reader = stream.getReader();
-  const decoder = new TextDecoder();
-  let buffer = '';
-  let finished = false;
-
-  try {
-    while (true) {
-      const { done, value } = await reader.read();
-
-      if (done) {
-        finished = true;
-        buffer += decoder.decode();
-        break;
-      }
-
-      buffer += decoder.decode(value, { stream: true });
-
-      let lineEnd = buffer.indexOf('\n');
-      while (lineEnd !== -1) {
-        const line = buffer.slice(0, lineEnd).replace(/\r$/, '');
-        buffer = buffer.slice(lineEnd + 1);
-
-        if (line.trim().length > 0) {
-          yield await parseJSON({
-            text: line,
-            schema: googleBatchResultLineSchema,
-          });
-        }
-
-        lineEnd = buffer.indexOf('\n');
-      }
-    }
-
-    const finalLine = buffer.replace(/\r$/, '');
-    if (finalLine.trim().length > 0) {
-      yield await parseJSON({
-        text: finalLine,
-        schema: googleBatchResultLineSchema,
-      });
-    }
-  } finally {
-    if (!finished) {
-      await reader.cancel().catch(() => {});
-    }
-    reader.releaseLock();
-  }
-}

package/src/google-files.ts

@@ -34,6 +34,17 @@ interface GoogleFilesConfig {
   fetch?: FetchFunction;
 }
 
+function encodePathSegment(value: string): string {
+  const encodedValue = encodeURIComponent(value);
+
+  // URL parsing normalizes both literal and percent-encoded dot segments.
+  return encodedValue === '.'
+    ? '%252E'
+    : encodedValue === '..'
+      ? '%252E%252E'
+      : encodedValue;
+}
+
 export class GoogleFiles implements FilesV4 {
   readonly specificationVersion = 'v4';
 
@@ -106,7 +117,7 @@ export class GoogleFiles implements FilesV4 {
         'X-Goog-Upload-Offset': '0',
         'X-Goog-Upload-Command': 'upload, finalize',
       },
-      body: fileBytes,
+      body: ensureArrayBufferBacked(fileBytes),
     });
 
     if (!uploadResponse.ok) {
@@ -137,8 +148,14 @@ export class GoogleFiles implements FilesV4 {
 
       await delay(pollIntervalMs);
 
+      const fileNameMatch = /^files\/([^/]+)$/.exec(file.name);
+      const filePath =
+        fileNameMatch != null
+          ? `files/${encodePathSegment(fileNameMatch[1])}`
+          : encodePathSegment(file.name);
+
       const { value: fileStatus } = await getFromApi({
-        url: `${this.config.baseURL}/${file.name}`,
+        url: `${this.config.baseURL}/${filePath}`,
         validateUrl: false,
         headers: combineHeaders(resolvedHeaders),
         successfulResponseHandler: createJsonResponseHandler(
@@ -182,6 +199,14 @@ export class GoogleFiles implements FilesV4 {
   }
 }
 
+function ensureArrayBufferBacked(data: Uint8Array): Uint8Array<ArrayBuffer> {
+  if (data.buffer instanceof ArrayBuffer) {
+    return data as Uint8Array<ArrayBuffer>;
+  }
+
+  return new Uint8Array(data);
+}
+
 type GoogleFileResource = {
   name: string;
   displayName?: string | null;

package/src/google-prepare-tools.ts

@@ -3,10 +3,25 @@ import {
   type LanguageModelV4CallOptions,
   type SharedV4Warning,
 } 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 { GoogleModelId } from './google-language-model-options';
 import { getGoogleModelCapabilities } from './google-model-capabilities';
 
+type FunctionTool = Extract<
+  NonNullable<LanguageModelV4CallOptions['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/interactions/build-google-interactions-stream-transform.ts

@@ -6,7 +6,10 @@ import type {
   SharedV4ProviderMetadata,
   SharedV4Warning,
 } from '@ai-sdk/provider';
-import type { ParseResult } from '@ai-sdk/provider-utils';
+import {
+  createProviderStreamError,
+  type ParseResult,
+} from '@ai-sdk/provider-utils';
 import type {
   GoogleInteractionsEvent,
   GoogleInteractionsUsage,
@@ -821,10 +824,15 @@ export function buildGoogleInteractionsStreamTransform({
             { event_type: 'error' }
           >;
           finishStatus = 'failed';
-          const errorPayload = event.error ?? {
-            message: 'Unknown interaction error',
-          };
-          controller.enqueue({ type: 'error', error: errorPayload });
+          controller.enqueue({
+            type: 'error',
+            error: createProviderStreamError({
+              message: event.error?.message ?? 'Unknown interaction error',
+              type: event.event_type,
+              code: event.error?.code ?? undefined,
+              data: event,
+            }),
+          });
           break;
         }