@tanstack/ai-grok 0.0.1 → 0.3.0

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

@@ -0,0 +1,118 @@
+/**
+ * Grok Image Generation Provider Options
+ *
+ * These are provider-specific options for Grok image generation.
+ * Grok uses the grok-2-image-1212 model for image generation.
+ */
+
+/**
+ * Supported sizes for grok-2-image-1212 model
+ */
+export type GrokImageSize = '1024x1024' | '1536x1024' | '1024x1536'
+
+/**
+ * Base provider options for Grok image models
+ */
+export interface GrokImageBaseProviderOptions {
+  /**
+   * A unique identifier representing your end-user.
+   * Can help xAI to monitor and detect abuse.
+   */
+  user?: string
+}
+
+/**
+ * Provider options for grok-2-image-1212 model
+ */
+export interface GrokImageProviderOptions extends GrokImageBaseProviderOptions {
+  /**
+   * The quality of the image.
+   * @default 'standard'
+   */
+  quality?: 'standard' | 'hd'
+
+  /**
+   * The format in which generated images are returned.
+   * URLs are only valid for 60 minutes after generation.
+   * @default 'url'
+   */
+  response_format?: 'url' | 'b64_json'
+}
+
+/**
+ * Type-only map from model name to its specific provider options.
+ */
+export type GrokImageModelProviderOptionsByName = {
+  'grok-2-image-1212': GrokImageProviderOptions
+}
+
+/**
+ * Type-only map from model name to its supported sizes.
+ */
+export type GrokImageModelSizeByName = {
+  'grok-2-image-1212': GrokImageSize
+}
+
+/**
+ * Internal options interface for validation
+ */
+interface ImageValidationOptions {
+  prompt: string
+  model: string
+}
+
+/**
+ * Validates that the provided size is supported by the model.
+ * Throws a descriptive error if the size is not supported.
+ */
+export function validateImageSize(
+  model: string,
+  size: string | undefined,
+): void {
+  if (!size) return
+
+  const validSizes: Record<string, Array<string>> = {
+    'grok-2-image-1212': ['1024x1024', '1536x1024', '1024x1536'],
+  }
+
+  const modelSizes = validSizes[model]
+  if (!modelSizes) {
+    throw new Error(`Unknown image model: ${model}`)
+  }
+
+  if (!modelSizes.includes(size)) {
+    throw new Error(
+      `Size "${size}" is not supported by model "${model}". ` +
+        `Supported sizes: ${modelSizes.join(', ')}`,
+    )
+  }
+}
+
+/**
+ * Validates that the number of images is within bounds for the model.
+ */
+export function validateNumberOfImages(
+  _model: string,
+  numberOfImages: number | undefined,
+): void {
+  if (numberOfImages === undefined) return
+
+  // grok-2-image-1212 supports 1-10 images per request
+  if (numberOfImages < 1 || numberOfImages > 10) {
+    throw new Error(
+      `Number of images must be between 1 and 10. Requested: ${numberOfImages}`,
+    )
+  }
+}
+
+export const validatePrompt = (options: ImageValidationOptions) => {
+  if (options.prompt.length === 0) {
+    throw new Error('Prompt cannot be empty.')
+  }
+  // Grok image model supports up to 4000 characters
+  if (options.prompt.length > 4000) {
+    throw new Error(
+      'For grok-2-image-1212, prompt length must be less than or equal to 4000 characters.',
+    )
+  }
+}

package/src/index.ts

@@ -0,0 +1,55 @@
+// ============================================================================
+// New Tree-Shakeable Adapters (Recommended)
+// ============================================================================
+
+// Text (Chat) adapter - for chat/text completion
+export {
+  GrokTextAdapter,
+  createGrokText,
+  grokText,
+  type GrokTextConfig,
+  type GrokTextProviderOptions,
+} from './adapters/text'
+
+// Summarize adapter - for text summarization
+export {
+  GrokSummarizeAdapter,
+  createGrokSummarize,
+  grokSummarize,
+  type GrokSummarizeConfig,
+  type GrokSummarizeProviderOptions,
+  type GrokSummarizeModel,
+} from './adapters/summarize'
+
+// Image adapter - for image generation
+export {
+  GrokImageAdapter,
+  createGrokImage,
+  grokImage,
+  type GrokImageConfig,
+  type GrokImageModel,
+} from './adapters/image'
+export type {
+  GrokImageProviderOptions,
+  GrokImageModelProviderOptionsByName,
+} from './image/image-provider-options'
+
+// ============================================================================
+// Type Exports
+// ============================================================================
+
+export type {
+  GrokChatModelProviderOptionsByName,
+  GrokModelInputModalitiesByName,
+  ResolveProviderOptions,
+  ResolveInputModalities,
+} from './model-meta'
+export { GROK_CHAT_MODELS, GROK_IMAGE_MODELS } from './model-meta'
+export type {
+  GrokTextMetadata,
+  GrokImageMetadata,
+  GrokAudioMetadata,
+  GrokVideoMetadata,
+  GrokDocumentMetadata,
+  GrokMessageMetadataByModality,
+} from './message-types'

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)
+  })
+}