ai 7.0.93 → 7.0.95

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/index.mdx

@@ -53,6 +53,21 @@ 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: 'transcribe()',
       description: 'Generate a transcript from an audio file.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai",
-  "version": "7.0.93",
+  "version": "7.0.95",
   "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.75",
-    "@ai-sdk/provider": "4.0.10",
-    "@ai-sdk/provider-utils": "5.0.36"
+    "@ai-sdk/gateway": "4.0.76",
+    "@ai-sdk/provider": "4.0.11",
+    "@ai-sdk/provider-utils": "5.0.37"
   },
   "devDependencies": {
-    "@ai-sdk/amazon-bedrock": "5.0.75",
-    "@ai-sdk/deepseek": "3.0.39",
-    "@ai-sdk/google": "4.0.64",
-    "@ai-sdk/groq": "4.0.37",
-    "@ai-sdk/huggingface": "2.0.44",
-    "@ai-sdk/moonshotai": "3.0.45",
-    "@ai-sdk/openai": "4.0.59",
+    "@ai-sdk/amazon-bedrock": "5.0.79",
+    "@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.63",
     "@ai-sdk/test-server": "2.0.1",
-    "@ai-sdk/xai": "4.0.54",
+    "@ai-sdk/xai": "4.0.55",
     "@edge-runtime/vm": "^5.0.0",
     "@smithy/eventstream-codec": "^4.3.3",
     "@smithy/util-utf8": "^4.3.3",

package/src/batch/batch-types.ts

@@ -1,8 +1,10 @@
 import type {
+  Experimental_BatchV4 as BatchV4,
   Experimental_BatchV4Error as BatchV4Error,
+  Experimental_BatchV4ModelIds as BatchV4ModelIds,
   Experimental_BatchV4StartResult as BatchV4StartResult,
   Experimental_BatchV4Status as BatchV4Status,
-  Experimental_BatchLanguageModelV4 as BatchLanguageModelV4,
+  ProviderV4,
 } from '@ai-sdk/provider';
 import type {
   InferToolSetContext,
@@ -13,40 +15,31 @@ import type { ContentPart } from '../generate-text/content-part';
 import type { ToolOrder } from '../generate-text/tool-order';
 import type { LanguageModelCallOptions } from '../prompt/language-model-call-options';
 import type { Prompt } from '../prompt/prompt';
-import type {
-  FinishReason,
-  GlobalProviderModelId,
-  ToolChoice,
-} from '../types/language-model';
+import type { FinishReason, ToolChoice } from '../types/language-model';
 import type { ProviderMetadata } from '../types/provider-metadata';
 import type { LanguageModelUsage } from '../types/usage';
 
 /**
- * Language model input that can be used for durable batch processing.
- *
- * String model IDs are resolved through the global provider and checked for
- * batch support at runtime.
+ * Provider or lower-level batch interface used for batch processing.
  */
-export type BatchLanguageModel = GlobalProviderModelId | BatchLanguageModelV4;
+export type BatchProvider = ProviderV4 | BatchV4;
+
+type InferBatchModelIds<PROVIDER extends BatchProvider> =
+  PROVIDER extends BatchV4<infer MODEL_IDS>
+    ? MODEL_IDS
+    : PROVIDER extends { experimental_batch(): BatchV4<infer MODEL_IDS> }
+      ? MODEL_IDS
+      : BatchV4ModelIds;
 
 /**
- * The persisted reference for a text batch.
+ * The persisted reference for a batch.
  */
-export type TextBatchReference = {
-  readonly version: 1;
-  readonly type: 'text';
+export type BatchReference = {
+  readonly version: 2;
   readonly id: string;
   readonly provider: string;
-  readonly modelId: string;
 };
 
-/**
- * Persisted reference for any supported batch type.
- *
- * Additional modality-specific references can be added to this union.
- */
-export type BatchReference = TextBatchReference;
-
 /**
  * Serializable error information for a batch or batch item.
  */
@@ -58,55 +51,55 @@ export type BatchError = BatchV4Error;
 export type BatchStatus = BatchV4Status;
 
 /**
- * A text batch and its latest normalized lifecycle status.
+ * A batch and its latest normalized lifecycle status.
  */
-export type TextBatch = TextBatchReference & BatchStatus;
+export type Batch = BatchReference & BatchStatus;
 
 /**
  * One text generation request within a batch.
  */
-export type TextBatchRequest = Prompt &
+export type TextBatchRequest<
+  ModelId extends string = string,
+  TOOLS extends ToolSet = ToolSet,
+> = Prompt &
   LanguageModelCallOptions & {
     id: string;
+    type: 'text';
+    model: ModelId;
+    tools?: TOOLS;
+    toolChoice?: ToolChoice<NoInfer<TOOLS>>;
+    toolOrder?: ToolOrder<TOOLS>;
+    toolsContext?: InferToolSetContext<TOOLS>;
     providerOptions?: ProviderOptions;
   };
 
-type BatchRequestOptions = {
+/**
+ * One request within a batch, discriminated by modality.
+ */
+export type BatchRequest<
+  ModelIds extends BatchV4ModelIds = BatchV4ModelIds,
+  TOOLS extends ToolSet = ToolSet,
+> = TextBatchRequest<ModelIds['text'], TOOLS>;
+
+type BatchCallOptions = {
   abortSignal?: AbortSignal;
   headers?: Record<string, string | undefined>;
   timeout?: number | { totalMs?: number };
 };
 
 /**
- * Options for starting a text batch.
+ * Options for starting a batch.
  */
-export type StartTextBatchOptions<TOOLS extends ToolSet = ToolSet> = {
-  model: BatchLanguageModel;
-  requests: ReadonlyArray<TextBatchRequest>;
-
-  /**
-   * Tools that the model can call for every request in the batch.
-   *
-   * Tool definitions are sent to the provider, but their `execute` functions
-   * are never invoked by batch processing.
-   */
-  tools?: TOOLS;
-
-  /**
-   * The tool choice strategy. Default: 'auto'.
-   */
-  toolChoice?: ToolChoice<NoInfer<TOOLS>>;
-
+export type StartBatchOptions<
+  TOOLS extends ToolSet = ToolSet,
+  PROVIDER extends BatchProvider = BatchProvider,
+> = {
   /**
-   * Controls the order in which tools are sent to the provider. Tools not
-   * listed are appended alphabetically.
+   * Provider used to process the batch. Defaults to the global provider, or
+   * the Vercel AI Gateway when no global provider is configured.
    */
-  toolOrder?: ToolOrder<TOOLS>;
-
-  /**
-   * Context used when resolving dynamic tool descriptions.
-   */
-  toolsContext?: InferToolSetContext<TOOLS>;
+  provider?: PROVIDER;
+  requests: ReadonlyArray<BatchRequest<InferBatchModelIds<PROVIDER>, TOOLS>>;
 
   providerOptions?: ProviderOptions;
 
@@ -116,33 +109,42 @@ export type StartTextBatchOptions<TOOLS extends ToolSet = ToolSet> = {
    * unsupported warning.
    */
   webhookUrl?: string;
-} & BatchRequestOptions;
+} & BatchCallOptions;
 
 /**
- * The acknowledged text batch and warnings produced while starting it.
+ * The acknowledged batch and warnings produced while starting it.
  */
-export type StartTextBatchResult = TextBatch & {
+export type StartBatchResult = Batch & {
   readonly warnings: BatchV4StartResult['warnings'];
 };
 
 /**
- * Options shared by batch status and result retrieval operations.
+ * Options for retrieving batch status.
  */
-export type BatchOperationOptions<TOOLS extends ToolSet = ToolSet> = {
-  model: BatchLanguageModel;
-  batch: BatchReference;
-
+export type GetBatchStatusOptions = {
   /**
-   * Definitions for client tools that were provided to `startTextBatch`.
-   *
-   * The definitions are used only to validate and normalize returned tool
-   * calls. Their `execute` functions are never invoked.
+   * Provider used to access the batch. Defaults to the global provider, or
+   * the Vercel AI Gateway when no global provider is configured.
    */
-  tools?: TOOLS;
-
+  provider?: BatchProvider;
+  batch: BatchReference;
   providerOptions?: ProviderOptions;
   maxRetries?: number;
-} & BatchRequestOptions;
+} & BatchCallOptions;
+
+/**
+ * Options for retrieving batch results.
+ */
+export type GetBatchResultsOptions<TOOLS extends ToolSet = ToolSet> =
+  GetBatchStatusOptions & {
+    /**
+     * Definitions for client tools that were provided to `startBatch` requests.
+     *
+     * The definitions are used only to validate and normalize returned tool
+     * calls. Their `execute` functions are never invoked.
+     */
+    tools?: TOOLS;
+  };
 
 /**
  * A normalized result for a successful text batch item.
@@ -182,3 +184,9 @@ export type TextBatchItemResult<TOOLS extends ToolSet = ToolSet> =
       readonly error?: BatchError;
       readonly providerMetadata?: ProviderMetadata;
     };
+
+/**
+ * A complete terminal result for one request in a batch.
+ */
+export type BatchItemResult<TOOLS extends ToolSet = ToolSet> =
+  TextBatchItemResult<TOOLS>;