@ai-sdk/provider-utils 4.0.4 → 4.0.6

package/src/to-json-schema/zod3-to-json-schema/zod3-to-json-schema.ts

@@ -0,0 +1,93 @@
+import { ZodSchema } from 'zod/v3';
+import { Options } from './options';
+import { parseDef } from './parse-def';
+import { JsonSchema7Type } from './parse-types';
+import { getRefs } from './refs';
+import { parseAnyDef } from './parsers/any';
+
+const zod3ToJsonSchema = (
+  schema: ZodSchema<any>,
+  options?: Partial<Options> | string,
+): JsonSchema7Type & {
+  $schema?: string;
+  definitions?: {
+    [key: string]: JsonSchema7Type;
+  };
+} => {
+  const refs = getRefs(options);
+
+  let definitions =
+    typeof options === 'object' && options.definitions
+      ? Object.entries(options.definitions).reduce(
+          (acc: { [key: string]: JsonSchema7Type }, [name, schema]) => ({
+            ...acc,
+            [name]:
+              parseDef(
+                schema._def,
+                {
+                  ...refs,
+                  currentPath: [...refs.basePath, refs.definitionPath, name],
+                },
+                true,
+              ) ?? parseAnyDef(),
+          }),
+          {},
+        )
+      : undefined;
+
+  const name =
+    typeof options === 'string'
+      ? options
+      : options?.nameStrategy === 'title'
+        ? undefined
+        : options?.name;
+
+  const main =
+    parseDef(
+      schema._def,
+      name === undefined
+        ? refs
+        : {
+            ...refs,
+            currentPath: [...refs.basePath, refs.definitionPath, name],
+          },
+      false,
+    ) ?? (parseAnyDef() as JsonSchema7Type);
+
+  const title =
+    typeof options === 'object' &&
+    options.name !== undefined &&
+    options.nameStrategy === 'title'
+      ? options.name
+      : undefined;
+
+  if (title !== undefined) {
+    main.title = title;
+  }
+
+  const combined: ReturnType<typeof zod3ToJsonSchema> =
+    name === undefined
+      ? definitions
+        ? {
+            ...main,
+            [refs.definitionPath]: definitions,
+          }
+        : main
+      : {
+          $ref: [
+            ...(refs.$refStrategy === 'relative' ? [] : refs.basePath),
+            refs.definitionPath,
+            name,
+          ].join('/'),
+          [refs.definitionPath]: {
+            ...definitions,
+            [name]: main,
+          },
+        };
+
+  combined.$schema = 'http://json-schema.org/draft-07/schema#';
+
+  return combined;
+};
+
+export { zod3ToJsonSchema };

package/src/types/assistant-model-message.ts

@@ -0,0 +1,39 @@
+import {
+  FilePart,
+  ReasoningPart,
+  TextPart,
+  ToolCallPart,
+  ToolResultPart,
+} from './content-part';
+import { ProviderOptions } from './provider-options';
+import { ToolApprovalRequest } from './tool-approval-request';
+
+/**
+An assistant message. It can contain text, tool calls, or a combination of text and tool calls.
+ */
+export type AssistantModelMessage = {
+  role: 'assistant';
+  content: AssistantContent;
+
+  /**
+  Additional provider-specific metadata. They are passed through
+  to the provider from the AI SDK and enable provider-specific
+  functionality that can be fully encapsulated in the provider.
+   */
+  providerOptions?: ProviderOptions;
+};
+
+/**
+Content of an assistant message.
+It can be a string or an array of text, image, reasoning, redacted reasoning, and tool call parts.
+ */
+export type AssistantContent =
+  | string
+  | Array<
+      | TextPart
+      | FilePart
+      | ReasoningPart
+      | ToolCallPart
+      | ToolResultPart
+      | ToolApprovalRequest
+    >;

package/src/types/content-part.ts

@@ -0,0 +1,379 @@
+import { JSONValue } from '@ai-sdk/provider';
+import { DataContent } from './data-content';
+import { ProviderOptions } from './provider-options';
+
+/**
+Text content part of a prompt. It contains a string of text.
+ */
+export interface TextPart {
+  type: 'text';
+
+  /**
+The text content.
+   */
+  text: string;
+
+  /**
+Additional provider-specific metadata. They are passed through
+to the provider from the AI SDK and enable provider-specific
+functionality that can be fully encapsulated in the provider.
+ */
+  providerOptions?: ProviderOptions;
+}
+
+/**
+Image content part of a prompt. It contains an image.
+ */
+export interface ImagePart {
+  type: 'image';
+
+  /**
+Image data. Can either be:
+
+- data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
+- URL: a URL that points to the image
+   */
+  image: DataContent | URL;
+
+  /**
+Optional IANA media type of the image.
+
+@see https://www.iana.org/assignments/media-types/media-types.xhtml
+   */
+  mediaType?: string;
+
+  /**
+Additional provider-specific metadata. They are passed through
+to the provider from the AI SDK and enable provider-specific
+functionality that can be fully encapsulated in the provider.
+ */
+  providerOptions?: ProviderOptions;
+}
+
+/**
+File content part of a prompt. It contains a file.
+ */
+export interface FilePart {
+  type: 'file';
+
+  /**
+File data. Can either be:
+
+- data: a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer
+- URL: a URL that points to the image
+   */
+  data: DataContent | URL;
+
+  /**
+Optional filename of the file.
+   */
+  filename?: string;
+
+  /**
+IANA media type of the file.
+
+@see https://www.iana.org/assignments/media-types/media-types.xhtml
+   */
+  mediaType: string;
+
+  /**
+Additional provider-specific metadata. They are passed through
+to the provider from the AI SDK and enable provider-specific
+functionality that can be fully encapsulated in the provider.
+ */
+  providerOptions?: ProviderOptions;
+}
+
+/**
+ * Reasoning content part of a prompt. It contains a reasoning.
+ */
+export interface ReasoningPart {
+  type: 'reasoning';
+
+  /**
+The reasoning text.
+   */
+  text: string;
+
+  /**
+Additional provider-specific metadata. They are passed through
+to the provider from the AI SDK and enable provider-specific
+functionality that can be fully encapsulated in the provider.
+ */
+  providerOptions?: ProviderOptions;
+}
+
+/**
+Tool call content part of a prompt. It contains a tool call (usually generated by the AI model).
+ */
+export interface ToolCallPart {
+  type: 'tool-call';
+
+  /**
+ID of the tool call. This ID is used to match the tool call with the tool result.
+ */
+  toolCallId: string;
+
+  /**
+Name of the tool that is being called.
+ */
+  toolName: string;
+
+  /**
+Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema.
+   */
+  input: unknown;
+
+  /**
+Additional provider-specific metadata. They are passed through
+to the provider from the AI SDK and enable provider-specific
+functionality that can be fully encapsulated in the provider.
+ */
+  providerOptions?: ProviderOptions;
+
+  /**
+Whether the tool call was executed by the provider.
+ */
+  providerExecuted?: boolean;
+}
+
+/**
+Tool result content part of a prompt. It contains the result of the tool call with the matching ID.
+ */
+export interface ToolResultPart {
+  type: 'tool-result';
+
+  /**
+ID of the tool call that this result is associated with.
+ */
+  toolCallId: string;
+
+  /**
+Name of the tool that generated this result.
+  */
+  toolName: string;
+
+  /**
+Result of the tool call. This is a JSON-serializable object.
+   */
+  output: ToolResultOutput;
+
+  /**
+Additional provider-specific metadata. They are passed through
+to the provider from the AI SDK and enable provider-specific
+functionality that can be fully encapsulated in the provider.
+ */
+  providerOptions?: ProviderOptions;
+}
+
+/**
+ * Output of a tool result.
+ */
+export type ToolResultOutput =
+  | {
+      /**
+       * Text tool output that should be directly sent to the API.
+       */
+      type: 'text';
+      value: string;
+
+      /**
+       * Provider-specific options.
+       */
+      providerOptions?: ProviderOptions;
+    }
+  | {
+      type: 'json';
+      value: JSONValue;
+
+      /**
+       * Provider-specific options.
+       */
+      providerOptions?: ProviderOptions;
+    }
+  | {
+      /**
+       * Type when the user has denied the execution of the tool call.
+       */
+      type: 'execution-denied';
+
+      /**
+       * Optional reason for the execution denial.
+       */
+      reason?: string;
+
+      /**
+       * Provider-specific options.
+       */
+      providerOptions?: ProviderOptions;
+    }
+  | {
+      type: 'error-text';
+      value: string;
+
+      /**
+       * Provider-specific options.
+       */
+      providerOptions?: ProviderOptions;
+    }
+  | {
+      type: 'error-json';
+      value: JSONValue;
+
+      /**
+       * Provider-specific options.
+       */
+      providerOptions?: ProviderOptions;
+    }
+  | {
+      type: 'content';
+      value: Array<
+        | {
+            type: 'text';
+
+            /**
+Text content.
+*/
+            text: string;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: ProviderOptions;
+          }
+        | {
+            /**
+             * @deprecated Use image-data or file-data instead.
+             */
+            type: 'media';
+            data: string;
+            mediaType: string;
+          }
+        | {
+            type: 'file-data';
+
+            /**
+Base-64 encoded media data.
+*/
+            data: string;
+
+            /**
+IANA media type.
+@see https://www.iana.org/assignments/media-types/media-types.xhtml
+*/
+            mediaType: string;
+
+            /**
+             * Optional filename of the file.
+             */
+            filename?: string;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: ProviderOptions;
+          }
+        | {
+            type: 'file-url';
+
+            /**
+             * URL of the file.
+             */
+            url: string;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: ProviderOptions;
+          }
+        | {
+            type: 'file-id';
+
+            /**
+             * ID of the file.
+             *
+             * If you use multiple providers, you need to
+             * specify the provider specific ids using
+             * the Record option. The key is the provider
+             * name, e.g. 'openai' or 'anthropic'.
+             */
+            fileId: string | Record<string, string>;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: ProviderOptions;
+          }
+        | {
+            /**
+             * Images that are referenced using base64 encoded data.
+             */
+            type: 'image-data';
+
+            /**
+Base-64 encoded image data.
+*/
+            data: string;
+
+            /**
+IANA media type.
+@see https://www.iana.org/assignments/media-types/media-types.xhtml
+*/
+            mediaType: string;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: ProviderOptions;
+          }
+        | {
+            /**
+             * Images that are referenced using a URL.
+             */
+            type: 'image-url';
+
+            /**
+             * URL of the image.
+             */
+            url: string;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: ProviderOptions;
+          }
+        | {
+            /**
+             * Images that are referenced using a provider file id.
+             */
+            type: 'image-file-id';
+
+            /**
+             * Image that is referenced using a provider file id.
+             *
+             * If you use multiple providers, you need to
+             * specify the provider specific ids using
+             * the Record option. The key is the provider
+             * name, e.g. 'openai' or 'anthropic'.
+             */
+            fileId: string | Record<string, string>;
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: ProviderOptions;
+          }
+        | {
+            /**
+             * Custom content part. This can be used to implement
+             * provider-specific content parts.
+             */
+            type: 'custom';
+
+            /**
+             * Provider-specific options.
+             */
+            providerOptions?: ProviderOptions;
+          }
+      >;
+    };

package/src/types/data-content.ts

@@ -0,0 +1,4 @@
+/**
+Data content. Can either be a base64-encoded string, a Uint8Array, an ArrayBuffer, or a Buffer.
+ */
+export type DataContent = string | Uint8Array | ArrayBuffer | Buffer;

package/src/types/execute-tool.ts

@@ -0,0 +1,27 @@
+import { isAsyncIterable } from '../is-async-iterable';
+import { ToolExecutionOptions, ToolExecuteFunction } from './tool';
+
+export async function* executeTool<INPUT, OUTPUT>({
+  execute,
+  input,
+  options,
+}: {
+  execute: ToolExecuteFunction<INPUT, OUTPUT>;
+  input: INPUT;
+  options: ToolExecutionOptions;
+}): AsyncGenerator<
+  { type: 'preliminary'; output: OUTPUT } | { type: 'final'; output: OUTPUT }
+> {
+  const result = execute(input, options);
+
+  if (isAsyncIterable(result)) {
+    let lastOutput: OUTPUT | undefined;
+    for await (const output of result) {
+      lastOutput = output;
+      yield { type: 'preliminary', output };
+    }
+    yield { type: 'final', output: lastOutput! };
+  } else {
+    yield { type: 'final', output: await result };
+  }
+}

package/src/types/index.ts

@@ -0,0 +1,40 @@
+export type {
+  AssistantContent,
+  AssistantModelMessage,
+} from './assistant-model-message';
+export type {
+  FilePart,
+  ImagePart,
+  ReasoningPart,
+  TextPart,
+  ToolCallPart,
+  ToolResultOutput,
+  ToolResultPart,
+} from './content-part';
+export type { DataContent } from './data-content';
+export { executeTool } from './execute-tool';
+export type { ModelMessage } from './model-message';
+export type { ProviderOptions } from './provider-options';
+export type { SystemModelMessage } from './system-model-message';
+export {
+  dynamicTool,
+  tool,
+  type InferToolInput,
+  type InferToolOutput,
+  type Tool,
+  type ToolExecutionOptions,
+  type ToolExecuteFunction,
+  type ToolNeedsApprovalFunction,
+} from './tool';
+export type { ToolApprovalRequest } from './tool-approval-request';
+export type { ToolApprovalResponse } from './tool-approval-response';
+export type { ToolCall } from './tool-call';
+export type { ToolContent, ToolModelMessage } from './tool-model-message';
+export type { ToolResult } from './tool-result';
+export type { UserContent, UserModelMessage } from './user-model-message';
+import type { ToolExecutionOptions } from './tool';
+
+/**
+ * @deprecated Use ToolExecutionOptions instead.
+ */
+export type ToolCallOptions = ToolExecutionOptions;

package/src/types/model-message.ts

@@ -0,0 +1,14 @@
+import { AssistantModelMessage } from './assistant-model-message';
+import { SystemModelMessage } from './system-model-message';
+import { ToolModelMessage } from './tool-model-message';
+import { UserModelMessage } from './user-model-message';
+
+/**
+A message that can be used in the `messages` field of a prompt.
+It can be a user message, an assistant message, or a tool message.
+ */
+export type ModelMessage =
+  | SystemModelMessage
+  | UserModelMessage
+  | AssistantModelMessage
+  | ToolModelMessage;

package/src/types/provider-options.ts

@@ -0,0 +1,9 @@
+import { SharedV3ProviderOptions } from '@ai-sdk/provider';
+
+/**
+Additional provider-specific options.
+
+They are passed through to the provider from the AI SDK and enable
+provider-specific functionality that can be fully encapsulated in the provider.
+ */
+export type ProviderOptions = SharedV3ProviderOptions;

package/src/types/system-model-message.ts

@@ -0,0 +1,20 @@
+import { ProviderOptions } from './provider-options';
+
+/**
+ A system message. It can contain system information.
+
+ Note: using the "system" part of the prompt is strongly preferred
+ to increase the resilience against prompt injection attacks,
+ and because not all providers support several system messages.
+ */
+export type SystemModelMessage = {
+  role: 'system';
+  content: string;
+
+  /**
+    Additional provider-specific metadata. They are passed through
+    to the provider from the AI SDK and enable provider-specific
+    functionality that can be fully encapsulated in the provider.
+     */
+  providerOptions?: ProviderOptions;
+};

package/src/types/tool-approval-request.ts

@@ -0,0 +1,16 @@
+/**
+ * Tool approval request prompt part.
+ */
+export type ToolApprovalRequest = {
+  type: 'tool-approval-request';
+
+  /**
+   * ID of the tool approval.
+   */
+  approvalId: string;
+
+  /**
+   * ID of the tool call that the approval request is for.
+   */
+  toolCallId: string;
+};

package/src/types/tool-approval-response.ts

@@ -0,0 +1,27 @@
+/**
+ * Tool approval response prompt part.
+ */
+export type ToolApprovalResponse = {
+  type: 'tool-approval-response';
+
+  /**
+   * ID of the tool approval.
+   */
+  approvalId: string;
+
+  /**
+   * Flag indicating whether the approval was granted or denied.
+   */
+  approved: boolean;
+
+  /**
+   * Optional reason for the approval or denial.
+   */
+  reason?: string;
+
+  /**
+   * Flag indicating whether the tool call is provider-executed.
+   * Only provider-executed tool approval responses should be sent to the model.
+   */
+  providerExecuted?: boolean;
+};

package/src/types/tool-call.ts

@@ -0,0 +1,31 @@
+/**
+Typed tool call that is returned by generateText and streamText.
+It contains the tool call ID, the tool name, and the tool arguments.
+ */
+export interface ToolCall<NAME extends string, INPUT> {
+  /**
+ID of the tool call. This ID is used to match the tool call with the tool result.
+ */
+  toolCallId: string;
+
+  /**
+Name of the tool that is being called.
+ */
+  toolName: NAME;
+
+  /**
+Arguments of the tool call. This is a JSON-serializable object that matches the tool's input schema.
+   */
+  input: INPUT;
+
+  /**
+   * Whether the tool call will be executed by the provider.
+   * If this flag is not set or is false, the tool call will be executed by the client.
+   */
+  providerExecuted?: boolean;
+
+  /**
+   * Whether the tool is dynamic.
+   */
+  dynamic?: boolean;
+}