@tanstack/ai-grok 0.12.4 → 0.14.0

package/src/model-meta.ts

@@ -1,13 +1,18 @@
 /**
  * Model metadata interface for documentation and type inference
  */
+import type {
+  GrokBuildProviderOptions,
+  GrokTextProviderOptions,
+} from './text/text-provider-options'
+
 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'>
-    tools?: ReadonlyArray<never>
+    tools?: ReadonlyArray<GrokProviderToolKind>
   }
   max_input_tokens?: number
   max_output_tokens?: number
@@ -24,184 +29,18 @@ interface ModelMeta {
   }
 }
 
-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'],
-    tools: [] as const,
-  },
-  pricing: {
-    input: {
-      normal: 0.2,
-      cached: 0.05,
-    },
-    output: {
-      normal: 0.5,
-    },
-  },
-} as const satisfies ModelMeta
+export type GrokProviderToolKind =
+  | 'web_search'
+  | 'x_search'
+  | 'file_search'
+  | 'mcp'
 
-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'],
-    tools: [] as const,
-  },
-  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'],
-    tools: [] as const,
-  },
-  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'],
-    tools: [] as const,
-  },
-  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'],
-    tools: [] as const,
-  },
-  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'],
-    tools: [] as const,
-  },
-  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'],
-    tools: [] as const,
-  },
-  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'],
-    tools: [] as const,
-  },
-  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'],
-    tools: [] as const,
-  },
-  pricing: {
-    input: {
-      normal: 2,
-    },
-    output: {
-      normal: 10,
-    },
-  },
-} as const satisfies ModelMeta
+const GROK_RESPONSES_TOOLS = [
+  'web_search',
+  'x_search',
+  'file_search',
+  'mcp',
+] as const satisfies ReadonlyArray<GrokProviderToolKind>
 
 const GROK_2_IMAGE = {
   name: 'grok-2-image-1212',
@@ -252,46 +91,43 @@ const GROK_IMAGINE_IMAGE_QUALITY = {
   },
 } as const satisfies ModelMeta
 
-/**
- * Grok Chat Models
- * Based on xAI's available models as of 2025
- */
-const GROK_4_20 = {
-  name: 'grok-4.20',
-  context_window: 2_000_000,
+// Imagine API video models. Pricing is per second of generated video
+// (output only); generated videos carry an audio track.
+//
+// grok-imagine-video (v1.0) supports both text-to-video (a starting image is
+// optional) and image-to-video. grok-imagine-video-1.5 is image-to-video
+// only: a starting-frame image is required (the text prompt describes the
+// desired motion) — its text-to-video is rejected by the API.
+const GROK_IMAGINE_VIDEO = {
+  name: 'grok-imagine-video',
   supports: {
-    input: ['text', 'image', 'document'],
-    output: ['text'],
-    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],
-    tools: [] as const,
+    input: ['text', 'image'],
+    output: ['video', 'audio'],
   },
   pricing: {
     input: {
-      normal: 2,
-      cached: 0.2,
+      normal: 0,
     },
     output: {
-      normal: 6,
+      // per second of video
+      normal: 0.05,
     },
   },
 } as const satisfies ModelMeta
 
-const GROK_4_20_MULTI_AGENT = {
-  name: 'grok-4.20-multi-agent',
-  context_window: 2_000_000,
+const GROK_IMAGINE_VIDEO_1_5 = {
+  name: 'grok-imagine-video-1.5',
   supports: {
-    input: ['text', 'image', 'document'],
-    output: ['text'],
-    capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],
-    tools: [] as const,
+    input: ['text', 'image'],
+    output: ['video', 'audio'],
   },
   pricing: {
     input: {
-      normal: 2,
-      cached: 0.2,
+      normal: 0,
     },
     output: {
-      normal: 6,
+      // per second of video
+      normal: 0.08,
     },
   },
 } as const satisfies ModelMeta
@@ -303,7 +139,7 @@ const GROK_4_3 = {
     input: ['text', 'image'],
     output: ['text'],
     capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],
-    tools: [],
+    tools: GROK_RESPONSES_TOOLS,
   },
   pricing: {
     input: {
@@ -323,7 +159,7 @@ const GROK_BUILD_0_1 = {
     input: ['text', 'image'],
     output: ['text'],
     capabilities: ['reasoning', 'structured_outputs', 'tool_calling'],
-    tools: [],
+    tools: GROK_RESPONSES_TOOLS,
   },
   pricing: {
     input: {
@@ -336,48 +172,10 @@ const GROK_BUILD_0_1 = {
   },
 } as const satisfies ModelMeta
 
-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,
-
-  GROK_4_20.name,
-  GROK_4_20_MULTI_AGENT.name,
-
-  GROK_4_3.name,
-
-  GROK_BUILD_0_1.name,
-] as const
-
 /**
- * Grok models that support combining `tools` + `response_format: json_schema`
- * in a single streaming Chat Completions request (per issue #605). xAI
- * docs gate this to the Grok 4 family — Grok 2 / 3 reject the
- * combination. Grok 2 image generation is not a chat model, omitted.
- *
- * Note: Grok streams tool-call arguments atomically (not token-streamed)
- * per the issue's source matrix; partial-JSON tool-arg parsing should be
- * skipped for Grok specifically. That's a separate adapter concern from
- * this set — the set only gates whether the engine takes the native
- * combined path vs the legacy finalization path.
+ * Grok chat models supported by the Responses adapter.
  */
-export const GROK_COMBINED_TOOLS_AND_SCHEMA_MODELS = new Set<string>([
-  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_4_20.name,
-  GROK_4_20_MULTI_AGENT.name,
-  GROK_4_3.name,
-])
+export const GROK_CHAT_MODELS = [GROK_BUILD_0_1.name, GROK_4_3.name] as const
 
 /**
  * Grok Image Generation Models
@@ -388,6 +186,16 @@ export const GROK_IMAGE_MODELS = [
   GROK_IMAGINE_IMAGE_QUALITY.name,
 ] as const
 
+/**
+ * Grok Video Generation Models (xAI Imagine API)
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export const GROK_VIDEO_MODELS = [
+  GROK_IMAGINE_VIDEO.name,
+  GROK_IMAGINE_VIDEO_1_5.name,
+] as const
+
 // xAI's `/v1/tts` endpoint is endpoint-addressed and does not take a `model`
 // parameter. This synthetic identifier satisfies the SDK's `TTSOptions.model`
 // contract and provides a stable value for logging and fixture matching.
@@ -441,6 +249,7 @@ export const GROK_REALTIME_MODELS = [
 
 export type GrokChatModel = (typeof GROK_CHAT_MODELS)[number]
 export type GrokImageModel = (typeof GROK_IMAGE_MODELS)[number]
+export type GrokVideoModel = (typeof GROK_VIDEO_MODELS)[number]
 export type GrokTTSModel = (typeof GROK_TTS_MODELS)[number]
 export type GrokTranscriptionModel = (typeof GROK_TRANSCRIPTION_MODELS)[number]
 export type GrokRealtimeModel = (typeof GROK_REALTIME_MODELS)[number]
@@ -450,68 +259,28 @@ export type GrokRealtimeModel = (typeof GROK_REALTIME_MODELS)[number]
  * 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
-  [GROK_4_20.name]: typeof GROK_4_20.supports.input
-  [GROK_4_20_MULTI_AGENT.name]: typeof GROK_4_20_MULTI_AGENT.supports.input
   [GROK_4_3.name]: typeof GROK_4_3.supports.input
   [GROK_BUILD_0_1.name]: typeof GROK_BUILD_0_1.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
-}
-
 /**
  * Type-only map from Grok chat model name to its supported provider tools.
- * Grok exposes no provider-specific tool factories, so every model gets an
- * empty tuple. This ensures that passing an Anthropic/OpenAI ProviderTool to
- * a Grok adapter produces a compile-time type error.
+ * Keeps Grok provider-tool factories type-checked against the models that
+ * advertise xAI Responses server-side tools.
  */
 export type GrokChatModelToolCapabilitiesByName = {
-  [GROK_4_1_FAST_REASONING.name]: typeof GROK_4_1_FAST_REASONING.supports.tools
-  [GROK_4_1_FAST_NON_REASONING.name]: typeof GROK_4_1_FAST_NON_REASONING.supports.tools
-  [GROK_CODE_FAST_1.name]: typeof GROK_CODE_FAST_1.supports.tools
-  [GROK_4_FAST_REASONING.name]: typeof GROK_4_FAST_REASONING.supports.tools
-  [GROK_4_FAST_NON_REASONING.name]: typeof GROK_4_FAST_NON_REASONING.supports.tools
-  [GROK_4.name]: typeof GROK_4.supports.tools
-  [GROK_3.name]: typeof GROK_3.supports.tools
-  [GROK_3_MINI.name]: typeof GROK_3_MINI.supports.tools
-  [GROK_2_VISION.name]: typeof GROK_2_VISION.supports.tools
-  [GROK_4_20.name]: typeof GROK_4_20.supports.tools
-  [GROK_4_20_MULTI_AGENT.name]: typeof GROK_4_20_MULTI_AGENT.supports.tools
+  [GROK_4_3.name]: typeof GROK_4_3.supports.tools
+  [GROK_BUILD_0_1.name]: typeof GROK_BUILD_0_1.supports.tools
 }
 
+export type GrokProviderOptions = GrokTextProviderOptions
+
 /**
- * Grok-specific provider options
- * Based on OpenAI-compatible API options
+ * Type-only map from Grok chat model name to its provider options type.
  */
-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
+export type GrokChatModelProviderOptionsByName = {
+  [GROK_4_3.name]: GrokProviderOptions
+  [GROK_BUILD_0_1.name]: GrokBuildProviderOptions
 }
 
 // ===========================

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

@@ -1,10 +1,22 @@
 /**
  * Grok Text Provider Options
  *
- * Grok uses an OpenAI-compatible Chat Completions API.
- * However, not all OpenAI features may be supported by Grok.
+ * Grok uses xAI's OpenAI-compatible Responses API. Engine-managed fields
+ * such as `model`, `input`, `tools`, and `text.format` are owned by the
+ * adapter; user-supplied values live under `modelOptions`.
  */
 
+import type { ResponseCreateParams } from 'openai/resources/responses/responses'
+
+export type GrokReasoningEffort = 'none' | 'low' | 'medium' | 'high'
+
+export type GrokReasoning = Omit<
+  NonNullable<ResponseCreateParams['reasoning']>,
+  'effort'
+> & {
+  effort?: GrokReasoningEffort
+}
+
 /**
  * Base provider options for Grok text/chat models
  */
@@ -18,9 +30,10 @@ export interface GrokBaseOptions {
 
 /**
  * Grok-specific provider options for text/chat
- * Based on OpenAI-compatible API options
+ * Based on xAI Responses API options
  */
-export interface GrokTextProviderOptions extends GrokBaseOptions {
+export interface GrokTextProviderOptions
+  extends GrokBaseOptions, Record<string, unknown> {
   /**
    * Temperature for response generation (0-2)
    * Higher values make output more random, lower values more focused
@@ -34,19 +47,26 @@ export interface GrokTextProviderOptions extends GrokBaseOptions {
   /**
    * Maximum tokens in the response
    */
-  max_tokens?: number
+  max_output_tokens?: number
   /**
-   * Frequency penalty (-2.0 to 2.0)
+   * Whether xAI should store the response. Defaults to `false` in the adapter.
    */
-  frequency_penalty?: number
+  store?: boolean
   /**
-   * Presence penalty (-2.0 to 2.0)
+   * Additional response fields to include. Defaults to encrypted reasoning.
    */
-  presence_penalty?: number
+  include?: ResponseCreateParams['include']
   /**
-   * Stop sequences
+   * xAI/OpenAI-compatible reasoning controls for reasoning-capable models.
    */
-  stop?: string | Array<string>
+  reasoning?: GrokReasoning
+}
+
+export type GrokBuildProviderOptions = Omit<
+  GrokTextProviderOptions,
+  'reasoning'
+> & {
+  reasoning?: never
 }
 
 /**