ai 7.0.94 → 7.0.96

package/docs/07-reference/01-ai-sdk-core/21-get-batch-status.mdx

@@ -0,0 +1,133 @@
+---
+title: experimental_getBatchStatus
+description: API Reference for experimental_getBatchStatus.
+---
+
+# `experimental_getBatchStatus()`
+
+<Note type="warning">
+  Batch support is experimental and the API may change in patch releases.
+</Note>
+
+Retrieves the latest status of an asynchronous batch. For a complete guide to
+the batch lifecycle, see [Batch](/docs/ai-sdk-core/batch).
+
+```ts
+import { anthropic } from '@ai-sdk/anthropic';
+import { experimental_getBatchStatus as getBatchStatus } from 'ai';
+
+const status = await getBatchStatus({
+  provider: anthropic,
+  batch,
+});
+
+console.log(status.status, status.requestCounts);
+```
+
+## Import
+
+<Snippet
+  text={`import { experimental_getBatchStatus } from "ai"`}
+  prompt={false}
+/>
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'provider',
+      type: 'Experimental_BatchProvider',
+      isOptional: true,
+      description:
+        'The provider used to access the batch. Defaults to the global provider, or the AI Gateway when no global provider is configured.',
+    },
+    {
+      name: 'batch',
+      type: 'Experimental_BatchReference',
+      description:
+        'The serializable reference returned by experimental_startBatch.',
+    },
+    {
+      name: 'providerOptions',
+      type: 'ProviderOptions',
+      isOptional: true,
+      description: 'Additional provider-specific options for status retrieval.',
+    },
+    {
+      name: 'maxRetries',
+      type: 'number',
+      isOptional: true,
+      description:
+        'Maximum number of retries for status retrieval. Set to 0 to disable retries. Default: 2.',
+    },
+    {
+      name: 'abortSignal',
+      type: 'AbortSignal',
+      isOptional: true,
+      description: 'An optional abort signal to cancel the request.',
+    },
+    {
+      name: 'timeout',
+      type: 'number | { totalMs?: number }',
+      isOptional: true,
+      description: 'Maximum time allowed for the status request.',
+    },
+    {
+      name: 'headers',
+      type: 'Record<string, string | undefined>',
+      isOptional: true,
+      description: 'Additional HTTP headers for the request.',
+    },
+  ]}
+/>
+
+### Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: 'status',
+      type: "'pending' | 'completed' | 'failed'",
+      description: 'The latest normalized batch status.',
+    },
+    {
+      name: 'rawStatus',
+      type: 'string',
+      isOptional: true,
+      description: 'The provider-specific batch status, when available.',
+    },
+    {
+      name: 'requestCounts',
+      type: '{ total: number; pending: number; completed: number; failed: number }',
+      isOptional: true,
+      description: 'Provider-reported request counts.',
+    },
+    {
+      name: 'error',
+      type: 'Experimental_BatchError',
+      isOptional: true,
+      description: 'Error details when the batch fails.',
+    },
+    {
+      name: 'createdAt',
+      type: 'string',
+      isOptional: true,
+      description: 'Creation timestamp, when provided by the provider.',
+    },
+    {
+      name: 'expiresAt',
+      type: 'string',
+      isOptional: true,
+      description: 'Expiration timestamp, when provided by the provider.',
+    },
+    {
+      name: 'providerMetadata',
+      type: 'ProviderMetadata',
+      isOptional: true,
+      description: 'Provider-specific metadata for the batch.',
+    },
+  ]}
+/>

package/docs/07-reference/01-ai-sdk-core/22-get-batch-results.mdx

@@ -0,0 +1,109 @@
+---
+title: experimental_getBatchResults
+description: API Reference for experimental_getBatchResults.
+---
+
+# `experimental_getBatchResults()`
+
+<Note type="warning">
+  Batch support is experimental and the API may change in patch releases.
+</Note>
+
+Returns an async iterable of terminal results for the requests in an
+asynchronous batch. For a complete guide to the batch lifecycle, see
+[Batch](/docs/ai-sdk-core/batch).
+
+```ts
+import { anthropic } from '@ai-sdk/anthropic';
+import { experimental_getBatchResults as getBatchResults } from 'ai';
+
+for await (const item of getBatchResults({ provider: anthropic, batch })) {
+  if (item.status === 'succeeded') {
+    console.log(item.id, item.text);
+  } else {
+    console.error(item.id, item.error);
+  }
+}
+```
+
+## Import
+
+<Snippet
+  text={`import { experimental_getBatchResults } from "ai"`}
+  prompt={false}
+/>
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'provider',
+      type: 'Experimental_BatchProvider',
+      isOptional: true,
+      description:
+        'The provider used to access the batch. Defaults to the global provider, or the AI Gateway when no global provider is configured.',
+    },
+    {
+      name: 'batch',
+      type: 'Experimental_BatchReference',
+      description:
+        'The serializable reference returned by experimental_startBatch.',
+    },
+    {
+      name: 'tools',
+      type: 'ToolSet',
+      isOptional: true,
+      description:
+        'The client-defined tools provided on requests in the batch. Used to validate and normalize returned tool calls; execute functions are never invoked.',
+    },
+    {
+      name: 'providerOptions',
+      type: 'ProviderOptions',
+      isOptional: true,
+      description: 'Additional provider-specific options for result retrieval.',
+    },
+    {
+      name: 'maxRetries',
+      type: 'number',
+      isOptional: true,
+      description:
+        'Maximum number of retries for result retrieval. Set to 0 to disable retries. Default: 2.',
+    },
+    {
+      name: 'abortSignal',
+      type: 'AbortSignal',
+      isOptional: true,
+      description: 'An optional abort signal to cancel result retrieval.',
+    },
+    {
+      name: 'timeout',
+      type: 'number | { totalMs?: number }',
+      isOptional: true,
+      description: 'Maximum time allowed for result retrieval.',
+    },
+    {
+      name: 'headers',
+      type: 'Record<string, string | undefined>',
+      isOptional: true,
+      description: 'Additional HTTP headers for the request.',
+    },
+  ]}
+/>
+
+### Returns
+
+An `AsyncIterableStream<Experimental_BatchItemResult>` of succeeded,
+failed, cancelled, or expired request results. You can consume the stream as
+either an async iterable or a `ReadableStream`.
+
+Successful items contain `id`, `status: 'succeeded'`, `text`, normalized
+`content` (including text, reasoning, sources, files, tool calls, and tool
+results),
+`finishReason`, `usage`, and optional response and provider metadata. `text` is
+the concatenation of text parts and can be an empty string when a result
+contains no text parts.
+Failed, cancelled, and expired items contain the request `id`, their terminal
+status, and optional error details.

package/docs/07-reference/01-ai-sdk-core/23-cancel-batch.mdx

@@ -0,0 +1,96 @@
+---
+title: experimental_cancelBatch
+description: API Reference for experimental_cancelBatch.
+---
+
+# `experimental_cancelBatch()`
+
+<Note type="warning">
+  Batch support is experimental and the API may change in patch releases.
+</Note>
+
+Requests cancellation of an asynchronous batch. A successful call means that
+the provider accepted the cancellation request, not that cancellation has
+finished. For a complete guide to the batch lifecycle, see
+[Batch](/docs/ai-sdk-core/batch).
+
+```ts
+import { experimental_cancelBatch as cancelBatch } from 'ai';
+
+const result = await cancelBatch({
+  provider,
+  batch,
+});
+
+console.log(result.providerMetadata);
+```
+
+## Import
+
+<Snippet
+  text={`import { experimental_cancelBatch } from "ai"`}
+  prompt={false}
+/>
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'provider',
+      type: 'Experimental_BatchProvider',
+      isOptional: true,
+      description:
+        'The provider used to access the batch. Defaults to the global provider, or the AI Gateway when no global provider is configured.',
+    },
+    {
+      name: 'batch',
+      type: 'Experimental_BatchReference',
+      description:
+        'The serializable reference returned by experimental_startBatch.',
+    },
+    {
+      name: 'providerOptions',
+      type: 'ProviderOptions',
+      isOptional: true,
+      description:
+        'Additional provider-specific options for the cancellation request.',
+    },
+    {
+      name: 'abortSignal',
+      type: 'AbortSignal',
+      isOptional: true,
+      description: 'An optional abort signal to cancel the API request.',
+    },
+    {
+      name: 'timeout',
+      type: 'number | { totalMs?: number }',
+      isOptional: true,
+      description: 'Maximum time allowed for the cancellation request.',
+    },
+    {
+      name: 'headers',
+      type: 'Record<string, string | undefined>',
+      isOptional: true,
+      description: 'Additional HTTP headers for the request.',
+    },
+  ]}
+/>
+
+### Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: 'providerMetadata',
+      type: 'ProviderMetadata',
+      isOptional: true,
+      description: 'Provider-specific metadata from the cancellation response.',
+    },
+  ]}
+/>
+
+Calling this function with a provider that does not support batch cancellation
+throws an `UnsupportedFunctionalityError`.

package/docs/07-reference/01-ai-sdk-core/24-list-batches.mdx

@@ -0,0 +1,121 @@
+---
+title: experimental_listBatches
+description: API Reference for experimental_listBatches.
+---
+
+# `experimental_listBatches()`
+
+<Note type="warning">
+  Batch support is experimental and the API may change in patch releases.
+</Note>
+
+Lists a page of asynchronous batches and their latest normalized statuses. For
+a complete guide to the batch lifecycle, see [Batch](/docs/ai-sdk-core/batch).
+
+```ts
+import { experimental_listBatches as listBatches } from 'ai';
+
+const page = await listBatches({
+  provider,
+  limit: 20,
+  cursor,
+});
+
+console.log(page.batches, page.nextCursor);
+```
+
+## Import
+
+<Snippet
+  text={`import { experimental_listBatches } from "ai"`}
+  prompt={false}
+/>
+
+## API Signature
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'provider',
+      type: 'Experimental_BatchProvider',
+      isOptional: true,
+      description:
+        'The provider whose batches should be listed. Defaults to the global provider, or the AI Gateway when no global provider is configured.',
+    },
+    {
+      name: 'limit',
+      type: 'number',
+      isOptional: true,
+      description: 'Maximum number of batches to return in this page.',
+    },
+    {
+      name: 'cursor',
+      type: 'string',
+      isOptional: true,
+      description:
+        'Opaque cursor returned as nextCursor by the previous list operation.',
+    },
+    {
+      name: 'providerOptions',
+      type: 'ProviderOptions',
+      isOptional: true,
+      description: 'Additional provider-specific options for listing batches.',
+    },
+    {
+      name: 'maxRetries',
+      type: 'number',
+      isOptional: true,
+      description:
+        'Maximum number of retries for listing batches. Set to 0 to disable retries. Default: 2.',
+    },
+    {
+      name: 'abortSignal',
+      type: 'AbortSignal',
+      isOptional: true,
+      description: 'An optional abort signal to cancel the request.',
+    },
+    {
+      name: 'timeout',
+      type: 'number | { totalMs?: number }',
+      isOptional: true,
+      description: 'Maximum time allowed for the list request.',
+    },
+    {
+      name: 'headers',
+      type: 'Record<string, string | undefined>',
+      isOptional: true,
+      description: 'Additional HTTP headers for the request.',
+    },
+  ]}
+/>
+
+### Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: 'batches',
+      type: 'Array<Experimental_Batch>',
+      description:
+        'The batches in this page. Each item contains a serializable batch reference and its latest normalized status.',
+    },
+    {
+      name: 'nextCursor',
+      type: 'string',
+      isOptional: true,
+      description:
+        'Opaque cursor to pass as cursor to retrieve the next page. Omitted when there are no more batches.',
+    },
+    {
+      name: 'providerMetadata',
+      type: 'ProviderMetadata',
+      isOptional: true,
+      description: 'Provider-specific metadata for the list operation.',
+    },
+  ]}
+/>
+
+Calling this function with a provider that does not support listing batches
+throws an `UnsupportedFunctionalityError`.

package/docs/07-reference/01-ai-sdk-core/index.mdx

@@ -53,6 +53,31 @@ AI SDK Core contains the following main functions:
         'Generate videos based on a given prompt using a video model.',
       href: '/docs/reference/ai-sdk-core/generate-video',
     },
+    {
+      title: 'experimental_startBatch()',
+      description: 'Start an asynchronous text-generation batch.',
+      href: '/docs/reference/ai-sdk-core/start-batch',
+    },
+    {
+      title: 'experimental_getBatchStatus()',
+      description: 'Retrieve the status of an asynchronous batch.',
+      href: '/docs/reference/ai-sdk-core/get-batch-status',
+    },
+    {
+      title: 'experimental_getBatchResults()',
+      description: 'Retrieve terminal results from an asynchronous batch.',
+      href: '/docs/reference/ai-sdk-core/get-batch-results',
+    },
+    {
+      title: 'experimental_cancelBatch()',
+      description: 'Request cancellation of an asynchronous batch.',
+      href: '/docs/reference/ai-sdk-core/cancel-batch',
+    },
+    {
+      title: 'experimental_listBatches()',
+      description: 'List asynchronous batches and their latest statuses.',
+      href: '/docs/reference/ai-sdk-core/list-batches',
+    },
     {
       title: 'transcribe()',
       description: 'Generate a transcript from an audio file.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "7.0.94",
+  "version": "7.0.96",
   "type": "module",
   "description": "AI SDK by Vercel - build apps like ChatGPT, Claude, Gemini, and more with a single interface for any model using the Vercel AI Gateway or go direct to OpenAI, Anthropic, Google, or any other model provider.",
   "license": "Apache-2.0",
@@ -42,20 +42,20 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/gateway": "4.0.76",
-    "@ai-sdk/provider": "4.0.11",
-    "@ai-sdk/provider-utils": "5.0.37"
+    "@ai-sdk/gateway": "4.0.77",
+    "@ai-sdk/provider": "4.0.12",
+    "@ai-sdk/provider-utils": "5.0.38"
   },
   "devDependencies": {
-    "@ai-sdk/amazon-bedrock": "5.0.77",
-    "@ai-sdk/deepseek": "3.0.40",
-    "@ai-sdk/google": "4.0.65",
-    "@ai-sdk/groq": "4.0.38",
-    "@ai-sdk/huggingface": "2.0.45",
-    "@ai-sdk/moonshotai": "3.0.46",
-    "@ai-sdk/openai": "4.0.61",
+    "@ai-sdk/amazon-bedrock": "5.0.80",
+    "@ai-sdk/deepseek": "3.0.41",
+    "@ai-sdk/google": "4.0.66",
+    "@ai-sdk/groq": "4.0.39",
+    "@ai-sdk/huggingface": "2.0.46",
+    "@ai-sdk/moonshotai": "3.0.47",
+    "@ai-sdk/openai": "4.0.64",
     "@ai-sdk/test-server": "2.0.1",
-    "@ai-sdk/xai": "4.0.55",
+    "@ai-sdk/xai": "4.0.56",
     "@edge-runtime/vm": "^5.0.0",
     "@smithy/eventstream-codec": "^4.3.3",
     "@smithy/util-utf8": "^4.3.3",

package/src/batch/batch-types.ts

@@ -118,6 +118,42 @@ export type StartBatchResult = Batch & {
   readonly warnings: BatchV4StartResult['warnings'];
 };
 
+/**
+ * Options for requesting cancellation of a batch.
+ */
+export type CancelBatchOptions = {
+  provider?: BatchProvider;
+  batch: BatchReference;
+  providerOptions?: ProviderOptions;
+} & BatchCallOptions;
+
+/**
+ * Result of requesting cancellation of a batch.
+ */
+export type CancelBatchResult = {
+  readonly providerMetadata?: ProviderMetadata;
+};
+
+/**
+ * Options for listing batches.
+ */
+export type ListBatchesOptions = {
+  provider?: BatchProvider;
+  providerOptions?: ProviderOptions;
+  limit?: number;
+  cursor?: string;
+  maxRetries?: number;
+} & BatchCallOptions;
+
+/**
+ * One page of listed batches.
+ */
+export type ListBatchesResult = {
+  readonly batches: Array<Batch>;
+  readonly nextCursor?: string;
+  readonly providerMetadata?: ProviderMetadata;
+};
+
 /**
  * Options for retrieving batch status.
  */

package/src/batch/batch.ts

@@ -31,14 +31,114 @@ import type {
   BatchProvider,
   BatchReference,
   BatchStatus,
+  CancelBatchOptions,
+  CancelBatchResult,
   GetBatchResultsOptions,
   GetBatchStatusOptions,
+  ListBatchesOptions,
+  ListBatchesResult,
   StartBatchOptions,
   StartBatchResult,
   TextBatchGenerationResult,
   TextBatchItemResult,
 } from './batch-types';
 
+/**
+ * Requests cancellation of a batch.
+ */
+export async function cancelBatch({
+  provider,
+  batch,
+  providerOptions,
+  abortSignal,
+  headers,
+  timeout,
+}: CancelBatchOptions): Promise<CancelBatchResult> {
+  const batchApi = resolveBatchApi(provider);
+  validateBatchReference({ batchApi, batch });
+
+  if (batchApi.doCancelBatch == null) {
+    throw new UnsupportedFunctionalityError({
+      functionality: 'batch cancellation',
+      message: 'The provider does not support batch cancellation.',
+    });
+  }
+
+  const operationAbortSignal = mergeAbortSignals(
+    abortSignal,
+    getTotalTimeoutMs(timeout),
+  );
+
+  try {
+    return await batchApi.doCancelBatch({
+      batchId: batch.id,
+      providerOptions,
+      abortSignal: operationAbortSignal,
+      headers: withUserAgentSuffix(headers ?? {}, `ai/${VERSION}`),
+    });
+  } catch (error) {
+    throw wrapGatewayError(error);
+  }
+}
+
+/**
+ * Lists a page of batches.
+ */
+export async function listBatches({
+  provider,
+  providerOptions,
+  limit,
+  cursor,
+  maxRetries,
+  abortSignal,
+  headers,
+  timeout,
+}: ListBatchesOptions = {}): Promise<ListBatchesResult> {
+  const batchApi = resolveBatchApi(provider);
+
+  const doListBatches = batchApi.doListBatches?.bind(batchApi);
+  if (doListBatches == null) {
+    throw new UnsupportedFunctionalityError({
+      functionality: 'batch listing',
+      message: 'The provider does not support listing batches.',
+    });
+  }
+
+  const operationAbortSignal = mergeAbortSignals(
+    abortSignal,
+    getTotalTimeoutMs(timeout),
+  );
+  const { retry } = prepareRetries({
+    maxRetries,
+    abortSignal: operationAbortSignal,
+  });
+
+  try {
+    const { batches, nextCursor, providerMetadata } = await retry(() =>
+      doListBatches({
+        providerOptions,
+        abortSignal: operationAbortSignal,
+        headers: withUserAgentSuffix(headers ?? {}, `ai/${VERSION}`),
+        ...(limit != null && { limit }),
+        ...(cursor != null && { cursor }),
+      }),
+    );
+
+    return {
+      batches: batches.map(({ batchId, ...status }) => ({
+        version: 2,
+        id: batchId,
+        provider: batchApi.provider,
+        ...status,
+      })),
+      ...(nextCursor != null && { nextCursor }),
+      ...(providerMetadata != null && { providerMetadata }),
+    };
+  } catch (error) {
+    throw wrapGatewayError(error);
+  }
+}
+
 /**
  * Starts a batch.
  */