@tanstack/ai-grok 0.0.1 → 0.1.0

package/src/message-types.ts

@@ -0,0 +1,67 @@
+/**
+ * Grok-specific metadata types for multimodal content parts.
+ * These types extend the base ContentPart metadata with Grok-specific options.
+ *
+ * Grok uses an OpenAI-compatible API, so metadata types are similar to OpenAI.
+ *
+ * @see https://docs.x.ai
+ */
+
+/**
+ * Metadata for Grok image content parts.
+ * Controls how the model processes and analyzes images.
+ */
+export interface GrokImageMetadata {
+  /**
+   * Controls how the model processes the image.
+   * - 'auto': Let the model decide based on image size and content
+   * - 'low': Use low resolution processing (faster, cheaper, less detail)
+   * - 'high': Use high resolution processing (slower, more expensive, more detail)
+   *
+   * @default 'auto'
+   */
+  detail?: 'auto' | 'low' | 'high'
+}
+
+/**
+ * Metadata for Grok audio content parts.
+ * Specifies the audio format for proper processing.
+ */
+export interface GrokAudioMetadata {
+  /**
+   * The format of the audio.
+   * Supported formats: mp3, wav, flac, etc.
+   * @default 'mp3'
+   */
+  format?: 'mp3' | 'wav' | 'flac' | 'ogg' | 'webm' | 'aac'
+}
+
+/**
+ * Metadata for Grok video content parts.
+ * Note: Video support in Grok is limited; check current API capabilities.
+ */
+export interface GrokVideoMetadata {}
+
+/**
+ * Metadata for Grok document content parts.
+ * Note: Direct document support may vary; PDFs often need to be converted to images.
+ */
+export interface GrokDocumentMetadata {}
+
+/**
+ * Metadata for Grok text content parts.
+ * Currently no specific metadata options for text in Grok.
+ */
+export interface GrokTextMetadata {}
+
+/**
+ * Map of modality types to their Grok-specific metadata types.
+ * Used for type inference when constructing multimodal messages.
+ */
+export interface GrokMessageMetadataByModality {
+  text: GrokTextMetadata
+  image: GrokImageMetadata
+  audio: GrokAudioMetadata
+  video: GrokVideoMetadata
+  document: GrokDocumentMetadata
+}

package/src/model-meta.ts

@@ -0,0 +1,298 @@
+/**
+ * Model metadata interface for documentation and type inference
+ */
+interface ModelMeta {
+  name: string
+  supports: {
+    input: Array<'text' | 'image' | 'audio' | 'video' | 'document'>
+    output: Array<'text' | 'image' | 'audio' | 'video'>
+    capabilities?: Array<'reasoning' | 'tool_calling' | 'structured_outputs'>
+  }
+  max_input_tokens?: number
+  max_output_tokens?: number
+  context_window?: number
+  knowledge_cutoff?: string
+  pricing?: {
+    input: {
+      normal: number
+      cached?: number
+    }
+    output: {
+      normal: number
+    }
+  }
+}
+
+const GROK_4_1_FAST_REASONING = {
+  name: 'grok-4-1-fast-reasoning',
+  context_window: 2_000_000,
+  supports: {
+    input: ['text', 'image'],
+    output: ['text'],
+    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],
+  },
+  pricing: {
+    input: {
+      normal: 0.2,
+      cached: 0.05,
+    },
+    output: {
+      normal: 0.5,
+    },
+  },
+} as const satisfies ModelMeta
+
+const GROK_4_1_FAST_NON_REASONING = {
+  name: 'grok-4-1-fast-non-reasoning',
+  context_window: 2_000_000,
+  supports: {
+    input: ['text', 'image'],
+    output: ['text'],
+    capabilities: ['structured_outputs', 'tool_calling'],
+  },
+  pricing: {
+    input: {
+      normal: 0.2,
+      cached: 0.05,
+    },
+    output: {
+      normal: 0.5,
+    },
+  },
+} as const satisfies ModelMeta
+
+const GROK_CODE_FAST_1 = {
+  name: 'grok-code-fast-1',
+  context_window: 256_000,
+  supports: {
+    input: ['text'],
+    output: ['text'],
+    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],
+  },
+  pricing: {
+    input: {
+      normal: 0.2,
+      cached: 0.02,
+    },
+    output: {
+      normal: 1.5,
+    },
+  },
+} as const satisfies ModelMeta
+
+const GROK_4_FAST_REASONING = {
+  name: 'grok-4-fast-reasoning',
+  context_window: 2_000_000,
+  supports: {
+    input: ['text', 'image'],
+    output: ['text'],
+    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],
+  },
+  pricing: {
+    input: {
+      normal: 0.2,
+      cached: 0.05,
+    },
+    output: {
+      normal: 0.5,
+    },
+  },
+} as const satisfies ModelMeta
+
+const GROK_4_FAST_NON_REASONING = {
+  name: 'grok-4-fast-non-reasoning',
+  context_window: 2_000_000,
+  supports: {
+    input: ['text', 'image'],
+    output: ['text'],
+    capabilities: ['structured_outputs', 'tool_calling'],
+  },
+  pricing: {
+    input: {
+      normal: 0.2,
+      cached: 0.05,
+    },
+    output: {
+      normal: 0.5,
+    },
+  },
+} as const satisfies ModelMeta
+
+const GROK_4 = {
+  name: 'grok-4',
+  context_window: 256_000,
+  supports: {
+    input: ['text', 'image'],
+    output: ['text'],
+    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],
+  },
+  pricing: {
+    input: {
+      normal: 3,
+      cached: 0.75,
+    },
+    output: {
+      normal: 15,
+    },
+  },
+} as const satisfies ModelMeta
+
+const GROK_3_MINI = {
+  name: 'grok-3-mini',
+  context_window: 131_072,
+  supports: {
+    input: ['text'],
+    output: ['text'],
+    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],
+  },
+  pricing: {
+    input: {
+      normal: 0.3,
+      cached: 0.075,
+    },
+    output: {
+      normal: 0.5,
+    },
+  },
+} as const satisfies ModelMeta
+
+const GROK_3 = {
+  name: 'grok-3',
+  context_window: 131_072,
+  supports: {
+    input: ['text'],
+    output: ['text'],
+    capabilities: ['structured_outputs', 'tool_calling'],
+  },
+  pricing: {
+    input: {
+      normal: 3,
+      cached: 0.75,
+    },
+    output: {
+      normal: 15,
+    },
+  },
+} as const satisfies ModelMeta
+
+const GROK_2_VISION = {
+  name: 'grok-2-vision-1212',
+  context_window: 32_768,
+  supports: {
+    input: ['text', 'image'],
+    output: ['text'],
+    capabilities: ['structured_outputs', 'tool_calling'],
+  },
+  pricing: {
+    input: {
+      normal: 2,
+    },
+    output: {
+      normal: 10,
+    },
+  },
+} as const satisfies ModelMeta
+
+const GROK_2_IMAGE = {
+  name: 'grok-2-image-1212',
+  supports: {
+    input: ['text'],
+    output: ['image'],
+  },
+  pricing: {
+    input: {
+      normal: 0.07,
+    },
+    output: {
+      normal: 0.07,
+    },
+  },
+} as const satisfies ModelMeta
+
+/**
+ * Grok Chat Models
+ * Based on xAI's available models as of 2025
+ */
+export const GROK_CHAT_MODELS = [
+  GROK_4_1_FAST_REASONING.name,
+  GROK_4_1_FAST_NON_REASONING.name,
+  GROK_CODE_FAST_1.name,
+  GROK_4_FAST_REASONING.name,
+  GROK_4_FAST_NON_REASONING.name,
+  GROK_4.name,
+  GROK_3.name,
+  GROK_3_MINI.name,
+  GROK_2_VISION.name,
+] as const
+
+/**
+ * Grok Image Generation Models
+ */
+export const GROK_IMAGE_MODELS = [GROK_2_IMAGE.name] as const
+
+/**
+ * Type-only map from Grok chat model name to its supported input modalities.
+ * Used for type inference when constructing multimodal messages.
+ */
+export type GrokModelInputModalitiesByName = {
+  [GROK_4_1_FAST_REASONING.name]: typeof GROK_4_1_FAST_REASONING.supports.input
+  [GROK_4_1_FAST_NON_REASONING.name]: typeof GROK_4_1_FAST_NON_REASONING.supports.input
+  [GROK_CODE_FAST_1.name]: typeof GROK_CODE_FAST_1.supports.input
+  [GROK_4_FAST_REASONING.name]: typeof GROK_4_FAST_REASONING.supports.input
+  [GROK_4_FAST_NON_REASONING.name]: typeof GROK_4_FAST_NON_REASONING.supports.input
+  [GROK_4.name]: typeof GROK_4.supports.input
+  [GROK_3.name]: typeof GROK_3.supports.input
+  [GROK_3_MINI.name]: typeof GROK_3_MINI.supports.input
+  [GROK_2_VISION.name]: typeof GROK_2_VISION.supports.input
+}
+
+/**
+ * Type-only map from Grok chat model name to its provider options type.
+ * Since Grok uses OpenAI-compatible API, we reuse OpenAI provider options.
+ */
+export type GrokChatModelProviderOptionsByName = {
+  [K in (typeof GROK_CHAT_MODELS)[number]]: GrokProviderOptions
+}
+
+/**
+ * Grok-specific provider options
+ * Based on OpenAI-compatible API options
+ */
+export interface GrokProviderOptions {
+  /** Temperature for response generation (0-2) */
+  temperature?: number
+  /** Maximum tokens in the response */
+  max_tokens?: number
+  /** Top-p sampling parameter */
+  top_p?: number
+  /** Frequency penalty (-2.0 to 2.0) */
+  frequency_penalty?: number
+  /** Presence penalty (-2.0 to 2.0) */
+  presence_penalty?: number
+  /** Stop sequences */
+  stop?: string | Array<string>
+  /** A unique identifier representing your end-user */
+  user?: string
+}
+
+// ===========================
+// Type Resolution Helpers
+// ===========================
+
+/**
+ * Resolve provider options for a specific model.
+ * If the model has explicit options in the map, use those; otherwise use base options.
+ */
+export type ResolveProviderOptions<TModel extends string> =
+  TModel extends keyof GrokChatModelProviderOptionsByName
+    ? GrokChatModelProviderOptionsByName[TModel]
+    : GrokProviderOptions
+
+/**
+ * Resolve input modalities for a specific model.
+ * If the model has explicit modalities in the map, use those; otherwise use text only.
+ */
+export type ResolveInputModalities<TModel extends string> =
+  TModel extends keyof GrokModelInputModalitiesByName
+    ? GrokModelInputModalitiesByName[TModel]
+    : readonly ['text']

package/src/text/text-provider-options.ts

@@ -0,0 +1,77 @@
+import type { FunctionTool } from '../tools/function-tool'
+
+/**
+ * Grok Text Provider Options
+ *
+ * Grok uses an OpenAI-compatible Chat Completions API.
+ * However, not all OpenAI features may be supported by Grok.
+ */
+
+/**
+ * Base provider options for Grok text/chat models
+ */
+export interface GrokBaseOptions {
+  /**
+   * A unique identifier representing your end-user.
+   * Can help xAI to monitor and detect abuse.
+   */
+  user?: string
+}
+
+/**
+ * Grok-specific provider options for text/chat
+ * Based on OpenAI-compatible API options
+ */
+export interface GrokTextProviderOptions extends GrokBaseOptions {
+  /**
+   * Temperature for response generation (0-2)
+   * Higher values make output more random, lower values more focused
+   */
+  temperature?: number
+  /**
+   * Top-p sampling parameter (0-1)
+   * Alternative to temperature, nucleus sampling
+   */
+  top_p?: number
+  /**
+   * Maximum tokens in the response
+   */
+  max_tokens?: number
+  /**
+   * Frequency penalty (-2.0 to 2.0)
+   */
+  frequency_penalty?: number
+  /**
+   * Presence penalty (-2.0 to 2.0)
+   */
+  presence_penalty?: number
+  /**
+   * Stop sequences
+   */
+  stop?: string | Array<string>
+}
+
+/**
+ * Internal options interface for validation
+ * Used internally by the adapter
+ */
+export interface InternalTextProviderOptions extends GrokTextProviderOptions {
+  model: string
+  stream?: boolean
+  tools?: Array<FunctionTool>
+}
+
+/**
+ * External provider options (what users pass in)
+ */
+export type ExternalTextProviderOptions = GrokTextProviderOptions
+
+/**
+ * Validates text provider options
+ */
+export function validateTextProviderOptions(
+  _options: InternalTextProviderOptions,
+): void {
+  // Basic validation can be added here if needed
+  // For now, Grok API will handle validation
+}

package/src/tools/function-tool.ts

@@ -0,0 +1,45 @@
+import { makeGrokStructuredOutputCompatible } from '../utils/schema-converter'
+import type { JSONSchema, Tool } from '@tanstack/ai'
+import type OpenAI from 'openai'
+
+// Use Chat Completions API tool format (not Responses API)
+export type FunctionTool = OpenAI.Chat.Completions.ChatCompletionTool
+
+/**
+ * Converts a standard Tool to Grok ChatCompletionTool format.
+ *
+ * Tool schemas are already converted to JSON Schema in the ai layer.
+ * We apply Grok-specific transformations for strict mode:
+ * - All properties in required array
+ * - Optional fields made nullable
+ * - additionalProperties: false
+ *
+ * This enables strict mode for all tools automatically.
+ */
+export function convertFunctionToolToAdapterFormat(tool: Tool): FunctionTool {
+  // Tool schemas are already converted to JSON Schema in the ai layer
+  // Apply Grok-specific transformations for strict mode
+  const inputSchema = (tool.inputSchema ?? {
+    type: 'object',
+    properties: {},
+    required: [],
+  }) as JSONSchema
+
+  const jsonSchema = makeGrokStructuredOutputCompatible(
+    inputSchema,
+    inputSchema.required || [],
+  )
+
+  // Ensure additionalProperties is false for strict mode
+  jsonSchema.additionalProperties = false
+
+  return {
+    type: 'function',
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: jsonSchema,
+      strict: true, // Always use strict mode since our schema converter handles the requirements
+    },
+  } satisfies FunctionTool
+}

package/src/tools/index.ts

@@ -0,0 +1,5 @@
+export {
+  convertFunctionToolToAdapterFormat,
+  type FunctionTool,
+} from './function-tool'
+export { convertToolsToProviderFormat } from './tool-converter'

package/src/tools/tool-converter.ts

@@ -0,0 +1,17 @@
+import { convertFunctionToolToAdapterFormat } from './function-tool'
+import type { FunctionTool } from './function-tool'
+import type { Tool } from '@tanstack/ai'
+
+/**
+ * Converts an array of standard Tools to Grok-specific format
+ * Grok uses OpenAI-compatible API, so we primarily support function tools
+ */
+export function convertToolsToProviderFormat(
+  tools: Array<Tool>,
+): Array<FunctionTool> {
+  return tools.map((tool) => {
+    // For Grok, all tools are converted as function tools
+    // Grok uses OpenAI-compatible API which primarily supports function tools
+    return convertFunctionToolToAdapterFormat(tool)
+  })
+}

package/src/utils/client.ts

@@ -0,0 +1,45 @@
+import OpenAI_SDK from 'openai'
+
+export interface GrokClientConfig {
+  apiKey: string
+  baseURL?: string
+}
+
+/**
+ * Creates a Grok SDK client instance using OpenAI SDK with xAI's base URL
+ */
+export function createGrokClient(config: GrokClientConfig): OpenAI_SDK {
+  return new OpenAI_SDK({
+    apiKey: config.apiKey,
+    baseURL: config.baseURL || 'https://api.x.ai/v1',
+  })
+}
+
+/**
+ * Gets Grok API key from environment variables
+ * @throws Error if XAI_API_KEY is not found
+ */
+export function getGrokApiKeyFromEnv(): string {
+  const env =
+    typeof globalThis !== 'undefined' && (globalThis as any).window?.env
+      ? (globalThis as any).window.env
+      : typeof process !== 'undefined'
+        ? process.env
+        : undefined
+  const key = env?.XAI_API_KEY
+
+  if (!key) {
+    throw new Error(
+      'XAI_API_KEY is required. Please set it in your environment variables or use the factory function with an explicit API key.',
+    )
+  }
+
+  return key
+}
+
+/**
+ * Generates a unique ID with a prefix
+ */
+export function generateId(prefix: string): string {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(7)}`
+}

package/src/utils/index.ts

@@ -0,0 +1,10 @@
+export {
+  createGrokClient,
+  getGrokApiKeyFromEnv,
+  generateId,
+  type GrokClientConfig,
+} from './client'
+export {
+  makeGrokStructuredOutputCompatible,
+  transformNullsToUndefined,
+} from './schema-converter'

package/src/utils/schema-converter.ts

@@ -0,0 +1,110 @@
+/**
+ * Recursively transform null values to undefined in an object.
+ *
+ * This is needed because Grok's structured output (via OpenAI-compatible API) requires all fields to be
+ * in the `required` array, with optional fields made nullable (type: ["string", "null"]).
+ * When Grok returns null for optional fields, we need to convert them back to
+ * undefined to match the original Zod schema expectations.
+ *
+ * @param obj - Object to transform
+ * @returns Object with nulls converted to undefined
+ */
+export function transformNullsToUndefined<T>(obj: T): T {
+  if (obj === null) {
+    return undefined as unknown as T
+  }
+
+  if (Array.isArray(obj)) {
+    return obj.map((item) => transformNullsToUndefined(item)) as unknown as T
+  }
+
+  if (typeof obj === 'object') {
+    const result: Record<string, unknown> = {}
+    for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {
+      const transformed = transformNullsToUndefined(value)
+      // Only include the key if the value is not undefined
+      // This makes { notes: null } become {} (field absent) instead of { notes: undefined }
+      if (transformed !== undefined) {
+        result[key] = transformed
+      }
+    }
+    return result as T
+  }
+
+  return obj
+}
+
+/**
+ * Transform a JSON schema to be compatible with Grok's structured output requirements (OpenAI-compatible).
+ * Grok requires:
+ * - All properties must be in the `required` array
+ * - Optional fields should have null added to their type union
+ * - additionalProperties must be false for objects
+ *
+ * @param schema - JSON schema to transform
+ * @param originalRequired - Original required array (to know which fields were optional)
+ * @returns Transformed schema compatible with Grok structured output
+ */
+export function makeGrokStructuredOutputCompatible(
+  schema: Record<string, any>,
+  originalRequired: Array<string> = [],
+): Record<string, any> {
+  const result = { ...schema }
+
+  // Handle object types
+  if (result.type === 'object' && result.properties) {
+    const properties = { ...result.properties }
+    const allPropertyNames = Object.keys(properties)
+
+    // Transform each property
+    for (const propName of allPropertyNames) {
+      const prop = properties[propName]
+      const wasOptional = !originalRequired.includes(propName)
+
+      // Recursively transform nested objects/arrays
+      if (prop.type === 'object' && prop.properties) {
+        properties[propName] = makeGrokStructuredOutputCompatible(
+          prop,
+          prop.required || [],
+        )
+      } else if (prop.type === 'array' && prop.items) {
+        properties[propName] = {
+          ...prop,
+          items: makeGrokStructuredOutputCompatible(
+            prop.items,
+            prop.items.required || [],
+          ),
+        }
+      } else if (wasOptional) {
+        // Make optional fields nullable by adding null to the type
+        if (prop.type && !Array.isArray(prop.type)) {
+          properties[propName] = {
+            ...prop,
+            type: [prop.type, 'null'],
+          }
+        } else if (Array.isArray(prop.type) && !prop.type.includes('null')) {
+          properties[propName] = {
+            ...prop,
+            type: [...prop.type, 'null'],
+          }
+        }
+      }
+    }
+
+    result.properties = properties
+    // ALL properties must be required for Grok structured output
+    result.required = allPropertyNames
+    // additionalProperties must be false
+    result.additionalProperties = false
+  }
+
+  // Handle array types with object items
+  if (result.type === 'array' && result.items) {
+    result.items = makeGrokStructuredOutputCompatible(
+      result.items,
+      result.items.required || [],
+    )
+  }
+
+  return result
+}