@ai-sdk/openai-compatible 2.0.15 → 2.0.17

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

@@ -0,0 +1,34 @@
+import { z } from 'zod/v4';
+
+export type OpenAICompatibleChatModelId = string;
+
+export const openaiCompatibleProviderOptions = z.object({
+  /**
+   * A unique identifier representing your end-user, which can help the provider to
+   * monitor and detect abuse.
+   */
+  user: z.string().optional(),
+
+  /**
+   * Reasoning effort for reasoning models. Defaults to `medium`.
+   */
+  reasoningEffort: z.string().optional(),
+
+  /**
+   * Controls the verbosity of the generated text. Defaults to `medium`.
+   */
+  textVerbosity: z.string().optional(),
+
+  /**
+   * Whether to use strict JSON schema validation.
+   * When true, the model uses constrained decoding to guarantee schema compliance.
+   * Only used when the provider supports structured outputs and a schema is provided.
+   *
+   * @default true
+   */
+  strictJsonSchema: z.boolean().optional(),
+});
+
+export type OpenAICompatibleProviderOptions = z.infer<
+  typeof openaiCompatibleProviderOptions
+>;

package/src/chat/openai-compatible-metadata-extractor.ts

@@ -0,0 +1,48 @@
+import { SharedV3ProviderMetadata } from '@ai-sdk/provider';
+
+/**
+Extracts provider-specific metadata from API responses.
+Used to standardize metadata handling across different LLM providers while allowing
+provider-specific metadata to be captured.
+*/
+export type MetadataExtractor = {
+  /**
+   * Extracts provider metadata from a complete, non-streaming response.
+   *
+   * @param parsedBody - The parsed response JSON body from the provider's API.
+   *
+   * @returns Provider-specific metadata or undefined if no metadata is available.
+   *          The metadata should be under a key indicating the provider id.
+   */
+  extractMetadata: ({
+    parsedBody,
+  }: {
+    parsedBody: unknown;
+  }) => Promise<SharedV3ProviderMetadata | undefined>;
+
+  /**
+   * Creates an extractor for handling streaming responses. The returned object provides
+   * methods to process individual chunks and build the final metadata from the accumulated
+   * stream data.
+   *
+   * @returns An object with methods to process chunks and build metadata from a stream
+   */
+  createStreamExtractor: () => {
+    /**
+     * Process an individual chunk from the stream. Called for each chunk in the response stream
+     * to accumulate metadata throughout the streaming process.
+     *
+     * @param parsedChunk - The parsed JSON response chunk from the provider's API
+     */
+    processChunk(parsedChunk: unknown): void;
+
+    /**
+     * Builds the metadata object after all chunks have been processed.
+     * Called at the end of the stream to generate the complete provider metadata.
+     *
+     * @returns Provider-specific metadata or undefined if no metadata is available.
+     *          The metadata should be under a key indicating the provider id.
+     */
+    buildMetadata(): SharedV3ProviderMetadata | undefined;
+  };
+};

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

@@ -0,0 +1,336 @@
+import { describe, expect, it } from 'vitest';
+import { prepareTools } from './openai-compatible-prepare-tools';
+
+describe('prepareTools', () => {
+  it('should return undefined tools and toolChoice when tools are null', () => {
+    const result = prepareTools({
+      tools: undefined,
+      toolChoice: undefined,
+    });
+
+    expect(result).toEqual({
+      tools: undefined,
+      toolChoice: undefined,
+      toolWarnings: [],
+    });
+  });
+
+  it('should return undefined tools and toolChoice when tools are empty', () => {
+    const result = prepareTools({
+      tools: [],
+      toolChoice: undefined,
+    });
+
+    expect(result).toEqual({
+      tools: undefined,
+      toolChoice: undefined,
+      toolWarnings: [],
+    });
+  });
+
+  it('should correctly prepare function tools', () => {
+    const result = prepareTools({
+      tools: [
+        {
+          type: 'function',
+          name: 'testFunction',
+          description: 'A test function',
+          inputSchema: { type: 'object', properties: {} },
+        },
+      ],
+      toolChoice: undefined,
+    });
+
+    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 provider-defined tools', () => {
+    const result = prepareTools({
+      tools: [
+        {
+          type: 'provider',
+          id: 'some.unsupported_tool',
+          name: 'unsupported_tool',
+          args: {},
+        },
+      ],
+      toolChoice: undefined,
+    });
+
+    expect(result.tools).toEqual([]);
+    expect(result.toolChoice).toBeUndefined();
+    expect(result.toolWarnings).toMatchInlineSnapshot(`
+      [
+        {
+          "feature": "provider-defined tool some.unsupported_tool",
+          "type": "unsupported",
+        },
+      ]
+    `);
+  });
+
+  it('should handle tool choice "auto"', () => {
+    const result = prepareTools({
+      tools: [
+        {
+          type: 'function',
+          name: 'testFunction',
+          description: 'Test',
+          inputSchema: {},
+        },
+      ],
+      toolChoice: { type: 'auto' },
+    });
+
+    expect(result.toolChoice).toEqual('auto');
+  });
+
+  it('should handle tool choice "required"', () => {
+    const result = prepareTools({
+      tools: [
+        {
+          type: 'function',
+          name: 'testFunction',
+          description: 'Test',
+          inputSchema: {},
+        },
+      ],
+      toolChoice: { type: 'required' },
+    });
+
+    expect(result.toolChoice).toEqual('required');
+  });
+
+  it('should handle tool choice "none"', () => {
+    const result = prepareTools({
+      tools: [
+        {
+          type: 'function',
+          name: 'testFunction',
+          description: 'Test',
+          inputSchema: {},
+        },
+      ],
+      toolChoice: { type: 'none' },
+    });
+
+    expect(result.toolChoice).toEqual('none');
+  });
+
+  it('should handle tool choice "tool"', () => {
+    const result = prepareTools({
+      tools: [
+        {
+          type: 'function',
+          name: 'testFunction',
+          description: 'Test',
+          inputSchema: {},
+        },
+      ],
+      toolChoice: { type: 'tool', toolName: 'testFunction' },
+    });
+
+    expect(result.toolChoice).toEqual({
+      type: 'function',
+      function: { name: 'testFunction' },
+    });
+  });
+
+  describe('strict mode', () => {
+    it('should pass through strict mode when strict is true', () => {
+      const result = prepareTools({
+        tools: [
+          {
+            type: 'function',
+            name: 'testFunction',
+            description: 'A test function',
+            inputSchema: { type: 'object', properties: {} },
+            strict: true,
+          },
+        ],
+        toolChoice: undefined,
+      });
+
+      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 = prepareTools({
+        tools: [
+          {
+            type: 'function',
+            name: 'testFunction',
+            description: 'A test function',
+            inputSchema: { type: 'object', properties: {} },
+            strict: false,
+          },
+        ],
+        toolChoice: undefined,
+      });
+
+      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 = prepareTools({
+        tools: [
+          {
+            type: 'function',
+            name: 'testFunction',
+            description: 'A test function',
+            inputSchema: { type: 'object', properties: {} },
+          },
+        ],
+        toolChoice: undefined,
+      });
+
+      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 = prepareTools({
+        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: {} },
+          },
+        ],
+        toolChoice: undefined,
+      });
+
+      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-compatible-prepare-tools.ts

@@ -0,0 +1,98 @@
+import {
+  LanguageModelV3CallOptions,
+  SharedV3Warning,
+  UnsupportedFunctionalityError,
+} from '@ai-sdk/provider';
+
+export function prepareTools({
+  tools,
+  toolChoice,
+}: {
+  tools: LanguageModelV3CallOptions['tools'];
+  toolChoice?: LanguageModelV3CallOptions['toolChoice'];
+}): {
+  tools:
+    | undefined
+    | Array<{
+        type: 'function';
+        function: {
+          name: string;
+          description: string | undefined;
+          parameters: unknown;
+          strict?: boolean;
+        };
+      }>;
+  toolChoice:
+    | { type: 'function'; function: { name: string } }
+    | 'auto'
+    | 'none'
+    | 'required'
+    | undefined;
+  toolWarnings: 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 openaiCompatTools: Array<{
+    type: 'function';
+    function: {
+      name: string;
+      description: string | undefined;
+      parameters: unknown;
+      strict?: boolean;
+    };
+  }> = [];
+
+  for (const tool of tools) {
+    if (tool.type === 'provider') {
+      toolWarnings.push({
+        type: 'unsupported',
+        feature: `provider-defined tool ${tool.id}`,
+      });
+    } else {
+      openaiCompatTools.push({
+        type: 'function',
+        function: {
+          name: tool.name,
+          description: tool.description,
+          parameters: tool.inputSchema,
+          ...(tool.strict != null ? { strict: tool.strict } : {}),
+        },
+      });
+    }
+  }
+
+  if (toolChoice == null) {
+    return { tools: openaiCompatTools, toolChoice: undefined, toolWarnings };
+  }
+
+  const type = toolChoice.type;
+
+  switch (type) {
+    case 'auto':
+    case 'none':
+    case 'required':
+      return { tools: openaiCompatTools, toolChoice: type, toolWarnings };
+    case 'tool':
+      return {
+        tools: openaiCompatTools,
+        toolChoice: {
+          type: 'function',
+          function: { name: toolChoice.toolName },
+        },
+        toolWarnings,
+      };
+    default: {
+      const _exhaustiveCheck: never = type;
+      throw new UnsupportedFunctionalityError({
+        functionality: `tool choice type: ${_exhaustiveCheck}`,
+      });
+    }
+  }
+}

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

@@ -0,0 +1,46 @@
+import { LanguageModelV3Usage } from '@ai-sdk/provider';
+
+export function convertOpenAICompatibleCompletionUsage(
+  usage:
+    | {
+        prompt_tokens?: number | null;
+        completion_tokens?: number | null;
+      }
+    | 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: promptTokens,
+      noCache: promptTokens,
+      cacheRead: undefined,
+      cacheWrite: undefined,
+    },
+    outputTokens: {
+      total: completionTokens,
+      text: completionTokens,
+      reasoning: undefined,
+    },
+    raw: usage,
+  };
+}

package/src/completion/convert-to-openai-compatible-completion-prompt.ts

@@ -0,0 +1,93 @@
+import {
+  InvalidPromptError,
+  LanguageModelV3Prompt,
+  UnsupportedFunctionalityError,
+} from '@ai-sdk/provider';
+
+export function convertToOpenAICompatibleCompletionPrompt({
+  prompt,
+  user = 'user',
+  assistant = 'assistant',
+}: {
+  prompt: LanguageModelV3Prompt;
+  user?: string;
+  assistant?: string;
+}): {
+  prompt: string;
+  stopSequences?: string[];
+} {
+  // transform to a chat message format:
+  let text = '';
+
+  // if first message is a system message, add it to the text:
+  if (prompt[0].role === 'system') {
+    text += `${prompt[0].content}\n\n`;
+    prompt = prompt.slice(1);
+  }
+
+  for (const { role, content } of prompt) {
+    switch (role) {
+      case 'system': {
+        throw new InvalidPromptError({
+          message: 'Unexpected system message in prompt: ${content}',
+          prompt,
+        });
+      }
+
+      case 'user': {
+        const userMessage = content
+          .map(part => {
+            switch (part.type) {
+              case 'text': {
+                return part.text;
+              }
+            }
+          })
+          .filter(Boolean)
+          .join('');
+
+        text += `${user}:\n${userMessage}\n\n`;
+        break;
+      }
+
+      case 'assistant': {
+        const assistantMessage = content
+          .map(part => {
+            switch (part.type) {
+              case 'text': {
+                return part.text;
+              }
+              case 'tool-call': {
+                throw new UnsupportedFunctionalityError({
+                  functionality: 'tool-call messages',
+                });
+              }
+            }
+          })
+          .join('');
+
+        text += `${assistant}:\n${assistantMessage}\n\n`;
+        break;
+      }
+
+      case 'tool': {
+        throw new UnsupportedFunctionalityError({
+          functionality: 'tool messages',
+        });
+      }
+
+      default: {
+        const _exhaustiveCheck: never = role;
+        throw new Error(`Unsupported role: ${_exhaustiveCheck}`);
+      }
+    }
+  }
+
+  // Assistant message prefix:
+  text += `${assistant}:\n`;
+
+  return {
+    prompt: text,
+    stopSequences: [`\n${user}:`],
+  };
+}

package/src/completion/get-response-metadata.ts

@@ -0,0 +1,15 @@
+export function getResponseMetadata({
+  id,
+  model,
+  created,
+}: {
+  id?: string | undefined | null;
+  created?: number | undefined | null;
+  model?: string | undefined | null;
+}) {
+  return {
+    id: id ?? undefined,
+    modelId: model ?? undefined,
+    timestamp: created != null ? new Date(created * 1000) : undefined,
+  };
+}

package/src/completion/map-openai-compatible-finish-reason.ts

@@ -0,0 +1,19 @@
+import { LanguageModelV3FinishReason } from '@ai-sdk/provider';
+
+export function mapOpenAICompatibleFinishReason(
+  finishReason: string | null | undefined,
+): LanguageModelV3FinishReason['unified'] {
+  switch (finishReason) {
+    case 'stop':
+      return 'stop';
+    case 'length':
+      return 'length';
+    case 'content_filter':
+      return 'content-filter';
+    case 'function_call':
+    case 'tool_calls':
+      return 'tool-calls';
+    default:
+      return 'other';
+  }
+}