@ai-sdk/openai 3.0.13 → 3.0.15

package/src/chat/openai-chat-options.ts

@@ -0,0 +1,186 @@
+import { InferSchema, lazySchema, zodSchema } from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+// https://platform.openai.com/docs/models
+export type OpenAIChatModelId =
+  | 'o1'
+  | 'o1-2024-12-17'
+  | 'o3-mini'
+  | 'o3-mini-2025-01-31'
+  | 'o3'
+  | 'o3-2025-04-16'
+  | 'o4-mini'
+  | 'o4-mini-2025-04-16'
+  | 'gpt-4.1'
+  | 'gpt-4.1-2025-04-14'
+  | 'gpt-4.1-mini'
+  | 'gpt-4.1-mini-2025-04-14'
+  | 'gpt-4.1-nano'
+  | 'gpt-4.1-nano-2025-04-14'
+  | 'gpt-4o'
+  | 'gpt-4o-2024-05-13'
+  | 'gpt-4o-2024-08-06'
+  | 'gpt-4o-2024-11-20'
+  | 'gpt-4o-mini'
+  | 'gpt-4o-mini-2024-07-18'
+  | 'gpt-4-turbo'
+  | 'gpt-4-turbo-2024-04-09'
+  | 'gpt-4'
+  | 'gpt-4-0613'
+  | 'gpt-4.5-preview'
+  | 'gpt-4.5-preview-2025-02-27'
+  | 'gpt-3.5-turbo-0125'
+  | 'gpt-3.5-turbo'
+  | 'gpt-3.5-turbo-1106'
+  | 'chatgpt-4o-latest'
+  | 'gpt-5'
+  | 'gpt-5-2025-08-07'
+  | 'gpt-5-mini'
+  | 'gpt-5-mini-2025-08-07'
+  | 'gpt-5-nano'
+  | 'gpt-5-nano-2025-08-07'
+  | 'gpt-5-chat-latest'
+  | 'gpt-5.1'
+  | 'gpt-5.1-chat-latest'
+  | 'gpt-5.2'
+  | 'gpt-5.2-chat-latest'
+  | 'gpt-5.2-pro'
+  | (string & {});
+
+export const openaiChatLanguageModelOptions = lazySchema(() =>
+  zodSchema(
+    z.object({
+      /**
+       * Modify the likelihood of specified tokens appearing in the completion.
+       *
+       * Accepts a JSON object that maps tokens (specified by their token ID in
+       * the GPT tokenizer) to an associated bias value from -100 to 100.
+       */
+      logitBias: z.record(z.coerce.number<string>(), z.number()).optional(),
+
+      /**
+       * Return the log probabilities of the tokens.
+       *
+       * Setting to true will return the log probabilities of the tokens that
+       * were generated.
+       *
+       * Setting to a number will return the log probabilities of the top n
+       * tokens that were generated.
+       */
+      logprobs: z.union([z.boolean(), z.number()]).optional(),
+
+      /**
+       * Whether to enable parallel function calling during tool use. Default to true.
+       */
+      parallelToolCalls: z.boolean().optional(),
+
+      /**
+       * A unique identifier representing your end-user, which can help OpenAI to
+       * monitor and detect abuse.
+       */
+      user: z.string().optional(),
+
+      /**
+       * Reasoning effort for reasoning models. Defaults to `medium`.
+       */
+      reasoningEffort: z
+        .enum(['none', 'minimal', 'low', 'medium', 'high', 'xhigh'])
+        .optional(),
+
+      /**
+       * Maximum number of completion tokens to generate. Useful for reasoning models.
+       */
+      maxCompletionTokens: z.number().optional(),
+
+      /**
+       * Whether to enable persistence in responses API.
+       */
+      store: z.boolean().optional(),
+
+      /**
+       * Metadata to associate with the request.
+       */
+      metadata: z.record(z.string().max(64), z.string().max(512)).optional(),
+
+      /**
+       * Parameters for prediction mode.
+       */
+      prediction: z.record(z.string(), z.any()).optional(),
+
+      /**
+       * Service tier for the request.
+       * - 'auto': Default service tier. The request will be processed with the service tier configured in the
+       *           Project settings. Unless otherwise configured, the Project will use 'default'.
+       * - 'flex': 50% cheaper processing at the cost of increased latency. Only available for o3 and o4-mini models.
+       * - 'priority': Higher-speed processing with predictably low latency at premium cost. Available for Enterprise customers.
+       * - 'default': The request will be processed with the standard pricing and performance for the selected model.
+       *
+       * @default 'auto'
+       */
+      serviceTier: z.enum(['auto', 'flex', 'priority', 'default']).optional(),
+
+      /**
+       * Whether to use strict JSON schema validation.
+       *
+       * @default true
+       */
+      strictJsonSchema: z.boolean().optional(),
+
+      /**
+       * Controls the verbosity of the model's responses.
+       * Lower values will result in more concise responses, while higher values will result in more verbose responses.
+       */
+      textVerbosity: z.enum(['low', 'medium', 'high']).optional(),
+
+      /**
+       * A cache key for prompt caching. Allows manual control over prompt caching behavior.
+       * Useful for improving cache hit rates and working around automatic caching issues.
+       */
+      promptCacheKey: z.string().optional(),
+
+      /**
+       * The retention policy for the prompt cache.
+       * - 'in_memory': Default. Standard prompt caching behavior.
+       * - '24h': Extended prompt caching that keeps cached prefixes active for up to 24 hours.
+       *          Currently only available for 5.1 series models.
+       *
+       * @default 'in_memory'
+       */
+      promptCacheRetention: z.enum(['in_memory', '24h']).optional(),
+
+      /**
+       * A stable identifier used to help detect users of your application
+       * that may be violating OpenAI's usage policies. The IDs should be a
+       * string that uniquely identifies each user. We recommend hashing their
+       * username or email address, in order to avoid sending us any identifying
+       * information.
+       */
+      safetyIdentifier: z.string().optional(),
+
+      /**
+       * Override the system message mode for this model.
+       * - 'system': Use the 'system' role for system messages (default for most models)
+       * - 'developer': Use the 'developer' role for system messages (used by reasoning models)
+       * - 'remove': Remove system messages entirely
+       *
+       * If not specified, the mode is automatically determined based on the model.
+       */
+      systemMessageMode: z.enum(['system', 'developer', 'remove']).optional(),
+
+      /**
+       * Force treating this model as a reasoning model.
+       *
+       * This is useful for "stealth" reasoning models (e.g. via a custom baseURL)
+       * where the model ID is not recognized by the SDK's allowlist.
+       *
+       * When enabled, the SDK applies reasoning-model parameter compatibility rules
+       * and defaults `systemMessageMode` to `developer` unless overridden.
+       */
+      forceReasoning: z.boolean().optional(),
+    }),
+  ),
+);
+
+export type OpenAIChatLanguageModelOptions = InferSchema<
+  typeof openaiChatLanguageModelOptions
+>;

package/src/chat/openai-chat-prepare-tools.test.ts

@@ -0,0 +1,322 @@
+import { describe, expect, it } from 'vitest';
+import { prepareChatTools } from './openai-chat-prepare-tools';
+
+describe('prepareChatTools', () => {
+  it('should return undefined tools and toolChoice when tools are null', () => {
+    const result = prepareChatTools({
+      tools: undefined,
+    });
+
+    expect(result).toEqual({
+      tools: undefined,
+      toolChoice: undefined,
+      toolWarnings: [],
+    });
+  });
+
+  it('should return undefined tools and toolChoice when tools are empty', () => {
+    const result = prepareChatTools({
+      tools: [],
+    });
+
+    expect(result).toEqual({
+      tools: undefined,
+      toolChoice: undefined,
+      toolWarnings: [],
+    });
+  });
+
+  it('should correctly prepare function tools', () => {
+    const result = prepareChatTools({
+      tools: [
+        {
+          type: 'function',
+          name: 'testFunction',
+          description: 'A test function',
+          inputSchema: { type: 'object', properties: {} },
+        },
+      ],
+    });
+
+    expect(result).toMatchInlineSnapshot(`
+    {
+      "toolChoice": undefined,
+      "toolWarnings": [],
+      "tools": [
+        {
+          "function": {
+            "description": "A test function",
+            "name": "testFunction",
+            "parameters": {
+              "properties": {},
+              "type": "object",
+            },
+          },
+          "type": "function",
+        },
+      ],
+    }
+  `);
+  });
+
+  it('should add warnings for unsupported tools', () => {
+    const result = prepareChatTools({
+      tools: [
+        {
+          type: 'provider',
+          id: 'openai.unsupported_tool',
+          name: 'unsupported_tool',
+          args: {},
+        },
+      ],
+    });
+
+    expect(result.tools).toEqual([]);
+    expect(result.toolChoice).toBeUndefined();
+    expect(result.toolWarnings).toMatchInlineSnapshot(`
+    [
+      {
+        "feature": "tool type: provider",
+        "type": "unsupported",
+      },
+    ]
+  `);
+  });
+
+  it('should handle tool choice "auto"', () => {
+    const result = prepareChatTools({
+      tools: [
+        {
+          type: 'function',
+          name: 'testFunction',
+          description: 'Test',
+          inputSchema: {},
+        },
+      ],
+      toolChoice: { type: 'auto' },
+    });
+    expect(result.toolChoice).toEqual('auto');
+  });
+
+  it('should handle tool choice "required"', () => {
+    const result = prepareChatTools({
+      tools: [
+        {
+          type: 'function',
+          name: 'testFunction',
+          description: 'Test',
+          inputSchema: {},
+        },
+      ],
+      toolChoice: { type: 'required' },
+    });
+    expect(result.toolChoice).toEqual('required');
+  });
+
+  it('should handle tool choice "none"', () => {
+    const result = prepareChatTools({
+      tools: [
+        {
+          type: 'function',
+          name: 'testFunction',
+          description: 'Test',
+          inputSchema: {},
+        },
+      ],
+      toolChoice: { type: 'none' },
+    });
+    expect(result.toolChoice).toEqual('none');
+  });
+
+  it('should handle tool choice "tool"', () => {
+    const result = prepareChatTools({
+      tools: [
+        {
+          type: 'function',
+          name: 'testFunction',
+          description: 'Test',
+          inputSchema: {},
+        },
+      ],
+      toolChoice: { type: 'tool', toolName: 'testFunction' },
+    });
+    expect(result.toolChoice).toEqual({
+      type: 'function',
+      function: { name: 'testFunction' },
+    });
+  });
+
+  it('should pass through strict mode when strict is true', () => {
+    const result = prepareChatTools({
+      tools: [
+        {
+          type: 'function',
+          name: 'testFunction',
+          description: 'A test function',
+          inputSchema: { type: 'object', properties: {} },
+          strict: true,
+        },
+      ],
+    });
+
+    expect(result).toMatchInlineSnapshot(`
+    {
+      "toolChoice": undefined,
+      "toolWarnings": [],
+      "tools": [
+        {
+          "function": {
+            "description": "A test function",
+            "name": "testFunction",
+            "parameters": {
+              "properties": {},
+              "type": "object",
+            },
+            "strict": true,
+          },
+          "type": "function",
+        },
+      ],
+    }
+  `);
+  });
+
+  it('should pass through strict mode when strict is false', () => {
+    const result = prepareChatTools({
+      tools: [
+        {
+          type: 'function',
+          name: 'testFunction',
+          description: 'A test function',
+          inputSchema: { type: 'object', properties: {} },
+          strict: false,
+        },
+      ],
+    });
+
+    expect(result).toMatchInlineSnapshot(`
+    {
+      "toolChoice": undefined,
+      "toolWarnings": [],
+      "tools": [
+        {
+          "function": {
+            "description": "A test function",
+            "name": "testFunction",
+            "parameters": {
+              "properties": {},
+              "type": "object",
+            },
+            "strict": false,
+          },
+          "type": "function",
+        },
+      ],
+    }
+  `);
+  });
+
+  it('should not include strict mode when strict is undefined', () => {
+    const result = prepareChatTools({
+      tools: [
+        {
+          type: 'function',
+          name: 'testFunction',
+          description: 'A test function',
+          inputSchema: { type: 'object', properties: {} },
+        },
+      ],
+    });
+
+    expect(result).toMatchInlineSnapshot(`
+    {
+      "toolChoice": undefined,
+      "toolWarnings": [],
+      "tools": [
+        {
+          "function": {
+            "description": "A test function",
+            "name": "testFunction",
+            "parameters": {
+              "properties": {},
+              "type": "object",
+            },
+          },
+          "type": "function",
+        },
+      ],
+    }
+  `);
+  });
+
+  it('should pass through strict mode for multiple tools with different strict settings', () => {
+    const result = prepareChatTools({
+      tools: [
+        {
+          type: 'function',
+          name: 'strictTool',
+          description: 'A strict tool',
+          inputSchema: { type: 'object', properties: {} },
+          strict: true,
+        },
+        {
+          type: 'function',
+          name: 'nonStrictTool',
+          description: 'A non-strict tool',
+          inputSchema: { type: 'object', properties: {} },
+          strict: false,
+        },
+        {
+          type: 'function',
+          name: 'defaultTool',
+          description: 'A tool without strict setting',
+          inputSchema: { type: 'object', properties: {} },
+        },
+      ],
+    });
+
+    expect(result).toMatchInlineSnapshot(`
+    {
+      "toolChoice": undefined,
+      "toolWarnings": [],
+      "tools": [
+        {
+          "function": {
+            "description": "A strict tool",
+            "name": "strictTool",
+            "parameters": {
+              "properties": {},
+              "type": "object",
+            },
+            "strict": true,
+          },
+          "type": "function",
+        },
+        {
+          "function": {
+            "description": "A non-strict tool",
+            "name": "nonStrictTool",
+            "parameters": {
+              "properties": {},
+              "type": "object",
+            },
+            "strict": false,
+          },
+          "type": "function",
+        },
+        {
+          "function": {
+            "description": "A tool without strict setting",
+            "name": "defaultTool",
+            "parameters": {
+              "properties": {},
+              "type": "object",
+            },
+          },
+          "type": "function",
+        },
+      ],
+    }
+  `);
+  });
+});

package/src/chat/openai-chat-prepare-tools.ts

@@ -0,0 +1,84 @@
+import {
+  LanguageModelV3CallOptions,
+  SharedV3Warning,
+  UnsupportedFunctionalityError,
+} from '@ai-sdk/provider';
+import {
+  OpenAIChatToolChoice,
+  OpenAIChatFunctionTool,
+} from './openai-chat-api';
+
+export function prepareChatTools({
+  tools,
+  toolChoice,
+}: {
+  tools: LanguageModelV3CallOptions['tools'];
+  toolChoice?: LanguageModelV3CallOptions['toolChoice'];
+}): {
+  tools?: OpenAIChatFunctionTool[];
+  toolChoice?: OpenAIChatToolChoice;
+  toolWarnings: Array<SharedV3Warning>;
+} {
+  // when the tools array is empty, change it to undefined to prevent errors:
+  tools = tools?.length ? tools : undefined;
+
+  const toolWarnings: SharedV3Warning[] = [];
+
+  if (tools == null) {
+    return { tools: undefined, toolChoice: undefined, toolWarnings };
+  }
+
+  const openaiTools: OpenAIChatFunctionTool[] = [];
+
+  for (const tool of tools) {
+    switch (tool.type) {
+      case 'function':
+        openaiTools.push({
+          type: 'function',
+          function: {
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.inputSchema,
+            ...(tool.strict != null ? { strict: tool.strict } : {}),
+          },
+        });
+        break;
+      default:
+        toolWarnings.push({
+          type: 'unsupported',
+          feature: `tool type: ${tool.type}`,
+        });
+        break;
+    }
+  }
+
+  if (toolChoice == null) {
+    return { tools: openaiTools, toolChoice: undefined, toolWarnings };
+  }
+
+  const type = toolChoice.type;
+
+  switch (type) {
+    case 'auto':
+    case 'none':
+    case 'required':
+      return { tools: openaiTools, toolChoice: type, toolWarnings };
+    case 'tool':
+      return {
+        tools: openaiTools,
+        toolChoice: {
+          type: 'function',
+          function: {
+            name: toolChoice.toolName,
+          },
+        },
+        toolWarnings,
+      };
+    default: {
+      const _exhaustiveCheck: never = type;
+      throw new UnsupportedFunctionalityError({
+        functionality: `tool choice type: ${_exhaustiveCheck}`,
+      });
+    }
+  }
+}

package/src/chat/openai-chat-prompt.ts

@@ -0,0 +1,70 @@
+export type OpenAIChatPrompt = Array<ChatCompletionMessage>;
+
+export type ChatCompletionMessage =
+  | ChatCompletionSystemMessage
+  | ChatCompletionDeveloperMessage
+  | ChatCompletionUserMessage
+  | ChatCompletionAssistantMessage
+  | ChatCompletionToolMessage;
+
+export interface ChatCompletionSystemMessage {
+  role: 'system';
+  content: string;
+}
+
+export interface ChatCompletionDeveloperMessage {
+  role: 'developer';
+  content: string;
+}
+
+export interface ChatCompletionUserMessage {
+  role: 'user';
+  content: string | Array<ChatCompletionContentPart>;
+}
+
+export type ChatCompletionContentPart =
+  | ChatCompletionContentPartText
+  | ChatCompletionContentPartImage
+  | ChatCompletionContentPartInputAudio
+  | ChatCompletionContentPartFile;
+
+export interface ChatCompletionContentPartText {
+  type: 'text';
+  text: string;
+}
+
+export interface ChatCompletionContentPartImage {
+  type: 'image_url';
+  image_url: { url: string };
+}
+
+export interface ChatCompletionContentPartInputAudio {
+  type: 'input_audio';
+  input_audio: { data: string; format: 'wav' | 'mp3' };
+}
+
+export interface ChatCompletionContentPartFile {
+  type: 'file';
+  file: { filename: string; file_data: string } | { file_id: string };
+}
+
+export interface ChatCompletionAssistantMessage {
+  role: 'assistant';
+  content?: string | null;
+  tool_calls?: Array<ChatCompletionMessageToolCall>;
+}
+
+export interface ChatCompletionMessageToolCall {
+  type: 'function';
+  id: string;
+  function: {
+    arguments: string;
+    name: string;
+  };
+}
+
+export interface ChatCompletionToolMessage {
+  role: 'tool';
+  content: string;
+  tool_call_id: string;
+}

package/src/completion/convert-openai-completion-usage.ts

@@ -0,0 +1,46 @@
+import { LanguageModelV3Usage } from '@ai-sdk/provider';
+
+export type OpenAICompletionUsage = {
+  prompt_tokens?: number | null;
+  completion_tokens?: number | null;
+  total_tokens?: number | null;
+};
+
+export function convertOpenAICompletionUsage(
+  usage: OpenAICompletionUsage | undefined | null,
+): LanguageModelV3Usage {
+  if (usage == null) {
+    return {
+      inputTokens: {
+        total: undefined,
+        noCache: undefined,
+        cacheRead: undefined,
+        cacheWrite: undefined,
+      },
+      outputTokens: {
+        total: undefined,
+        text: undefined,
+        reasoning: undefined,
+      },
+      raw: undefined,
+    };
+  }
+
+  const promptTokens = usage.prompt_tokens ?? 0;
+  const completionTokens = usage.completion_tokens ?? 0;
+
+  return {
+    inputTokens: {
+      total: usage.prompt_tokens ?? undefined,
+      noCache: promptTokens,
+      cacheRead: undefined,
+      cacheWrite: undefined,
+    },
+    outputTokens: {
+      total: usage.completion_tokens ?? undefined,
+      text: completionTokens,
+      reasoning: undefined,
+    },
+    raw: usage,
+  };
+}