@ai-sdk/xai 0.0.0-64aae7dd-20260114144918 → 0.0.0-98261322-20260122142521

package/src/xai-chat-options.ts

@@ -0,0 +1,131 @@
+import { z } from 'zod/v4';
+
+// https://console.x.ai and see "View models"
+export type XaiChatModelId =
+  | 'grok-4-1'
+  | 'grok-4-1-fast-reasoning'
+  | 'grok-4-1-fast-non-reasoning'
+  | 'grok-4-fast-non-reasoning'
+  | 'grok-4-fast-reasoning'
+  | 'grok-code-fast-1'
+  | 'grok-4'
+  | 'grok-4-0709'
+  | 'grok-4-latest'
+  | 'grok-3'
+  | 'grok-3-latest'
+  | 'grok-3-fast'
+  | 'grok-3-fast-latest'
+  | 'grok-3-mini'
+  | 'grok-3-mini-latest'
+  | 'grok-3-mini-fast'
+  | 'grok-3-mini-fast-latest'
+  | 'grok-2-vision-1212'
+  | 'grok-2-vision'
+  | 'grok-2-vision-latest'
+  | 'grok-2-image-1212'
+  | 'grok-2-image'
+  | 'grok-2-image-latest'
+  | 'grok-2-1212'
+  | 'grok-2'
+  | 'grok-2-latest'
+  | 'grok-vision-beta'
+  | 'grok-beta'
+  | (string & {});
+
+// search source schemas
+const webSourceSchema = z.object({
+  type: z.literal('web'),
+  country: z.string().length(2).optional(),
+  excludedWebsites: z.array(z.string()).max(5).optional(),
+  allowedWebsites: z.array(z.string()).max(5).optional(),
+  safeSearch: z.boolean().optional(),
+});
+
+const xSourceSchema = z.object({
+  type: z.literal('x'),
+  excludedXHandles: z.array(z.string()).optional(),
+  includedXHandles: z.array(z.string()).optional(),
+  postFavoriteCount: z.number().int().optional(),
+  postViewCount: z.number().int().optional(),
+  /**
+   * @deprecated use `includedXHandles` instead
+   */
+  xHandles: z.array(z.string()).optional(),
+});
+
+const newsSourceSchema = z.object({
+  type: z.literal('news'),
+  country: z.string().length(2).optional(),
+  excludedWebsites: z.array(z.string()).max(5).optional(),
+  safeSearch: z.boolean().optional(),
+});
+
+const rssSourceSchema = z.object({
+  type: z.literal('rss'),
+  links: z.array(z.string().url()).max(1), // currently only supports one RSS link
+});
+
+const searchSourceSchema = z.discriminatedUnion('type', [
+  webSourceSchema,
+  xSourceSchema,
+  newsSourceSchema,
+  rssSourceSchema,
+]);
+
+// xai-specific provider options
+export const xaiProviderOptions = z.object({
+  reasoningEffort: z.enum(['low', 'high']).optional(),
+
+  /**
+   * Whether to enable parallel function calling during tool use.
+   * When true, the model can call multiple functions in parallel.
+   * When false, the model will call functions sequentially.
+   * Defaults to true.
+   */
+  parallel_function_calling: z.boolean().optional(),
+
+  searchParameters: z
+    .object({
+      /**
+       * search mode preference
+       * - "off": disables search completely
+       * - "auto": model decides whether to search (default)
+       * - "on": always enables search
+       */
+      mode: z.enum(['off', 'auto', 'on']),
+
+      /**
+       * whether to return citations in the response
+       * defaults to true
+       */
+      returnCitations: z.boolean().optional(),
+
+      /**
+       * start date for search data (ISO8601 format: YYYY-MM-DD)
+       */
+      fromDate: z.string().optional(),
+
+      /**
+       * end date for search data (ISO8601 format: YYYY-MM-DD)
+       */
+      toDate: z.string().optional(),
+
+      /**
+       * maximum number of search results to consider
+       * defaults to 20
+       */
+      maxSearchResults: z.number().min(1).max(50).optional(),
+
+      /**
+       * data sources to search from.
+       * defaults to [{ type: 'web' }, { type: 'x' }] if not specified.
+       *
+       * @example
+       * sources: [{ type: 'web', country: 'US' }, { type: 'x' }]
+       */
+      sources: z.array(searchSourceSchema).optional(),
+    })
+    .optional(),
+});
+
+export type XaiProviderOptions = z.infer<typeof xaiProviderOptions>;

package/src/xai-chat-prompt.ts

@@ -0,0 +1,44 @@
+export type XaiChatPrompt = Array<XaiChatMessage>;
+
+export type XaiChatMessage =
+  | XaiSystemMessage
+  | XaiUserMessage
+  | XaiAssistantMessage
+  | XaiToolMessage;
+
+export interface XaiSystemMessage {
+  role: 'system';
+  content: string;
+}
+
+export interface XaiUserMessage {
+  role: 'user';
+  content: string | Array<XaiUserMessageContent>;
+}
+
+export type XaiUserMessageContent =
+  | { type: 'text'; text: string }
+  | { type: 'image_url'; image_url: { url: string } };
+
+export interface XaiAssistantMessage {
+  role: 'assistant';
+  content: string;
+  tool_calls?: Array<{
+    id: string;
+    type: 'function';
+    function: { name: string; arguments: string };
+  }>;
+}
+
+export interface XaiToolMessage {
+  role: 'tool';
+  tool_call_id: string;
+  content: string;
+}
+
+// xai tool choice
+export type XaiToolChoice =
+  | 'auto'
+  | 'none'
+  | 'required'
+  | { type: 'function'; function: { name: string } };

package/src/xai-error.ts

@@ -0,0 +1,19 @@
+import { createJsonErrorResponseHandler } from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+// Add error schema and structure
+export const xaiErrorDataSchema = z.object({
+  error: z.object({
+    message: z.string(),
+    type: z.string().nullish(),
+    param: z.any().nullish(),
+    code: z.union([z.string(), z.number()]).nullish(),
+  }),
+});
+
+export type XaiErrorData = z.infer<typeof xaiErrorDataSchema>;
+
+export const xaiFailedResponseHandler = createJsonErrorResponseHandler({
+  errorSchema: xaiErrorDataSchema,
+  errorToMessage: data => data.error.message,
+});

package/src/xai-image-settings.ts

@@ -0,0 +1 @@
+export type XaiImageModelId = 'grok-2-image' | (string & {});

package/src/xai-prepare-tools.ts

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

package/src/xai-provider.test.ts

@@ -0,0 +1,167 @@
+import { describe, it, expect, vi, beforeEach, Mock } from 'vitest';
+import { createXai } from './xai-provider';
+import { loadApiKey } from '@ai-sdk/provider-utils';
+import { XaiChatLanguageModel } from './xai-chat-language-model';
+import { OpenAICompatibleImageModel } from '@ai-sdk/openai-compatible';
+
+const XaiChatLanguageModelMock = XaiChatLanguageModel as unknown as Mock;
+const OpenAICompatibleImageModelMock =
+  OpenAICompatibleImageModel as unknown as Mock;
+
+vi.mock('./xai-chat-language-model', () => ({
+  XaiChatLanguageModel: vi.fn(),
+}));
+
+vi.mock('@ai-sdk/openai-compatible', () => ({
+  OpenAICompatibleChatLanguageModel: vi.fn(),
+  OpenAICompatibleCompletionLanguageModel: vi.fn(),
+  OpenAICompatibleEmbeddingModel: vi.fn(),
+  OpenAICompatibleImageModel: vi.fn(),
+}));
+
+vi.mock('./xai-image-model', () => ({
+  XaiImageModel: vi.fn(),
+}));
+
+vi.mock('@ai-sdk/provider-utils', async () => {
+  const actual = await vi.importActual('@ai-sdk/provider-utils');
+  return {
+    ...actual,
+    loadApiKey: vi.fn().mockReturnValue('mock-api-key'),
+    withoutTrailingSlash: vi.fn(url => url),
+    createJsonErrorResponseHandler: vi.fn().mockReturnValue(() => {}),
+    generateId: vi.fn().mockReturnValue('mock-id'),
+  };
+});
+
+vi.mock('./version', () => ({
+  VERSION: '0.0.0-test',
+}));
+
+describe('xAIProvider', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('createXAI', () => {
+    it('should create an XAIProvider instance with default options', () => {
+      const provider = createXai();
+      const model = provider('model-id');
+
+      const constructorCall = XaiChatLanguageModelMock.mock.calls[0];
+      const config = constructorCall[1];
+      config.headers();
+
+      expect(loadApiKey).toHaveBeenCalledWith({
+        apiKey: undefined,
+        environmentVariableName: 'XAI_API_KEY',
+        description: 'xAI API key',
+      });
+    });
+
+    it('should create an XAIProvider instance with custom options', () => {
+      const options = {
+        apiKey: 'custom-key',
+        baseURL: 'https://custom.url',
+        headers: { 'Custom-Header': 'value' },
+      };
+      const provider = createXai(options);
+      provider('model-id');
+
+      const constructorCall = XaiChatLanguageModelMock.mock.calls[0];
+      const config = constructorCall[1];
+      config.headers();
+
+      expect(loadApiKey).toHaveBeenCalledWith({
+        apiKey: 'custom-key',
+        environmentVariableName: 'XAI_API_KEY',
+        description: 'xAI API key',
+      });
+    });
+
+    it('should return a chat model when called as a function', () => {
+      const provider = createXai();
+      const modelId = 'foo-model-id';
+
+      const model = provider(modelId);
+      expect(model).toBeInstanceOf(XaiChatLanguageModel);
+    });
+  });
+
+  describe('chatModel', () => {
+    it('should construct a chat model with correct configuration', () => {
+      const provider = createXai();
+      const modelId = 'xai-chat-model';
+
+      const model = provider.chat(modelId);
+
+      expect(model).toBeInstanceOf(XaiChatLanguageModel);
+    });
+
+    it('should pass the includeUsage option to the chat model, to make sure usage is reported while streaming', () => {
+      const provider = createXai();
+      const modelId = 'xai-chat-model';
+
+      const model = provider.chat(modelId);
+
+      expect(model).toBeInstanceOf(XaiChatLanguageModel);
+
+      const constructorCall = XaiChatLanguageModelMock.mock.calls[0];
+
+      expect(constructorCall[0]).toBe(modelId);
+      expect(constructorCall[1].provider).toBe('xai.chat');
+      expect(constructorCall[1].baseURL).toBe('https://api.x.ai/v1');
+    });
+  });
+
+  describe('imageModel', () => {
+    it('should construct an image model with correct configuration', () => {
+      const provider = createXai();
+      const modelId = 'grok-2-image';
+
+      const model = provider.imageModel(modelId);
+
+      expect(model).toBeInstanceOf(OpenAICompatibleImageModel);
+
+      const constructorCall = OpenAICompatibleImageModelMock.mock.calls[0];
+      expect(constructorCall[0]).toBe(modelId);
+
+      const config = constructorCall[1];
+      expect(config.provider).toBe('xai.image');
+      expect(config.url({ path: '/test-path' })).toBe(
+        'https://api.x.ai/v1/test-path',
+      );
+    });
+
+    it('should use custom baseURL for image model', () => {
+      const customBaseURL = 'https://custom.xai.api';
+      const provider = createXai({ baseURL: customBaseURL });
+      const modelId = 'grok-2-image';
+
+      provider.imageModel(modelId);
+
+      const constructorCall = OpenAICompatibleImageModelMock.mock.calls[0];
+      const config = constructorCall[1];
+      expect(config.url({ path: '/test-path' })).toBe(
+        `${customBaseURL}/test-path`,
+      );
+    });
+
+    it('should pass custom headers to image model', () => {
+      const customHeaders = { 'Custom-Header': 'test-value' };
+      const provider = createXai({ headers: customHeaders });
+
+      provider.imageModel('grok-2-image');
+
+      const constructorCall = OpenAICompatibleImageModelMock.mock.calls[0];
+      const config = constructorCall[1];
+      const headers = config.headers();
+
+      expect(headers).toMatchObject({
+        authorization: 'Bearer mock-api-key',
+        'custom-header': 'test-value',
+        'user-agent': 'ai-sdk/xai/0.0.0-test',
+      });
+    });
+  });
+});

package/src/xai-provider.ts

@@ -0,0 +1,162 @@
+import {
+  OpenAICompatibleImageModel,
+  ProviderErrorStructure,
+} from '@ai-sdk/openai-compatible';
+import {
+  ImageModelV3,
+  LanguageModelV3,
+  NoSuchModelError,
+  ProviderV3,
+} from '@ai-sdk/provider';
+import {
+  FetchFunction,
+  generateId,
+  loadApiKey,
+  withoutTrailingSlash,
+  withUserAgentSuffix,
+} from '@ai-sdk/provider-utils';
+import { XaiChatLanguageModel } from './xai-chat-language-model';
+import { XaiChatModelId } from './xai-chat-options';
+import { XaiErrorData, xaiErrorDataSchema } from './xai-error';
+import { XaiImageModelId } from './xai-image-settings';
+import { XaiResponsesLanguageModel } from './responses/xai-responses-language-model';
+import { XaiResponsesModelId } from './responses/xai-responses-options';
+import { xaiTools } from './tool';
+import { VERSION } from './version';
+
+const xaiErrorStructure: ProviderErrorStructure<XaiErrorData> = {
+  errorSchema: xaiErrorDataSchema,
+  errorToMessage: data => data.error.message,
+};
+
+export interface XaiProvider extends ProviderV3 {
+  /**
+Creates an Xai chat model for text generation.
+   */
+  (modelId: XaiChatModelId): LanguageModelV3;
+
+  /**
+Creates an Xai language model for text generation.
+   */
+  languageModel(modelId: XaiChatModelId): LanguageModelV3;
+
+  /**
+Creates an Xai chat model for text generation.
+   */
+  chat: (modelId: XaiChatModelId) => LanguageModelV3;
+
+  /**
+Creates an Xai responses model for agentic tool calling.
+   */
+  responses: (modelId: XaiResponsesModelId) => LanguageModelV3;
+
+  /**
+Creates an Xai image model for image generation.
+   */
+  image(modelId: XaiImageModelId): ImageModelV3;
+
+  /**
+Creates an Xai image model for image generation.
+   */
+  imageModel(modelId: XaiImageModelId): ImageModelV3;
+
+  /**
+Server-side agentic tools for use with the responses API.
+   */
+  tools: typeof xaiTools;
+
+  /**
+   * @deprecated Use `embeddingModel` instead.
+   */
+  textEmbeddingModel(modelId: string): never;
+}
+
+export interface XaiProviderSettings {
+  /**
+Base URL for the xAI API calls.
+     */
+  baseURL?: string;
+
+  /**
+API key for authenticating requests.
+   */
+  apiKey?: string;
+
+  /**
+Custom headers to include in the requests.
+   */
+  headers?: Record<string, string>;
+
+  /**
+Custom fetch implementation. You can use it as a middleware to intercept requests,
+or to provide a custom fetch implementation for e.g. testing.
+  */
+  fetch?: FetchFunction;
+}
+
+export function createXai(options: XaiProviderSettings = {}): XaiProvider {
+  const baseURL = withoutTrailingSlash(
+    options.baseURL ?? 'https://api.x.ai/v1',
+  );
+  const getHeaders = () =>
+    withUserAgentSuffix(
+      {
+        Authorization: `Bearer ${loadApiKey({
+          apiKey: options.apiKey,
+          environmentVariableName: 'XAI_API_KEY',
+          description: 'xAI API key',
+        })}`,
+        ...options.headers,
+      },
+      `ai-sdk/xai/${VERSION}`,
+    );
+
+  const createChatLanguageModel = (modelId: XaiChatModelId) => {
+    return new XaiChatLanguageModel(modelId, {
+      provider: 'xai.chat',
+      baseURL,
+      headers: getHeaders,
+      generateId,
+      fetch: options.fetch,
+    });
+  };
+
+  const createResponsesLanguageModel = (modelId: XaiResponsesModelId) => {
+    return new XaiResponsesLanguageModel(modelId, {
+      provider: 'xai.responses',
+      baseURL,
+      headers: getHeaders,
+      generateId,
+      fetch: options.fetch,
+    });
+  };
+
+  const createImageModel = (modelId: XaiImageModelId) => {
+    return new OpenAICompatibleImageModel(modelId, {
+      provider: 'xai.image',
+      url: ({ path }) => `${baseURL}${path}`,
+      headers: getHeaders,
+      fetch: options.fetch,
+      errorStructure: xaiErrorStructure,
+    });
+  };
+
+  const provider = (modelId: XaiChatModelId) =>
+    createChatLanguageModel(modelId);
+
+  provider.specificationVersion = 'v3' as const;
+  provider.languageModel = createChatLanguageModel;
+  provider.chat = createChatLanguageModel;
+  provider.responses = createResponsesLanguageModel;
+  provider.embeddingModel = (modelId: string) => {
+    throw new NoSuchModelError({ modelId, modelType: 'embeddingModel' });
+  };
+  provider.textEmbeddingModel = provider.embeddingModel;
+  provider.imageModel = createImageModel;
+  provider.image = createImageModel;
+  provider.tools = xaiTools;
+
+  return provider;
+}
+
+export const xai = createXai();