@tanstack/ai-grok 0.12.4 → 0.14.0

package/README.md

@@ -28,11 +28,10 @@ export XAI_API_KEY="xai-..."
 import { grokText } from '@tanstack/ai-grok'
 import { generate } from '@tanstack/ai'
 
-const adapter = grokText()
+const adapter = grokText('grok-build-0.1')
 
 const result = await generate({
   adapter,
-  model: 'grok-3',
   messages: [
     { role: 'user', content: 'Explain quantum computing in simple terms' },
   ],
@@ -47,11 +46,10 @@ console.log(result.text)
 import { grokSummarize } from '@tanstack/ai-grok'
 import { summarize } from '@tanstack/ai'
 
-const adapter = grokSummarize()
+const adapter = grokSummarize('grok-build-0.1')
 
 const result = await summarize({
   adapter,
-  model: 'grok-3',
   text: 'Long article text...',
   style: 'bullet-points',
 })
@@ -83,27 +81,17 @@ console.log(result.images[0].url)
 ```typescript
 import { createGrokText } from '@tanstack/ai-grok'
 
-const adapter = createGrokText('xai-your-api-key-here')
+const adapter = createGrokText('grok-build-0.1', 'xai-your-api-key-here')
 ```
 
-## Supported Models
+## Supported Chat Models
 
-### Chat Models
-
-- `grok-4` - Latest flagship model
-- `grok-3` - Previous generation model
-- `grok-3-mini` - Smaller, faster model
-- `grok-4-fast` - Fast inference model
-- `grok-4.1-fast` - Production-focused fast model
-- `grok-2-vision-1212` - Vision-capable model (text + image input)
-
-### Image Models
-
-- `grok-2-image-1212` - Image generation model
+- `grok-build-0.1` - Build-focused reasoning model with text + image input
+- `grok-4.3` - Reasoning, structured outputs, tool calling, text + image input
 
 ## Features
 
-- ✅ Streaming chat completions
+- ✅ Streaming chat via xAI Responses API
 - ✅ Structured output (JSON Schema)
 - ✅ Function/tool calling
 - ✅ Multimodal input (text + images for vision models)

package/dist/esm/adapters/summarize.d.ts

@@ -13,14 +13,14 @@ export type GrokSummarizeModel = (typeof GROK_CHAT_MODELS)[number];
  * Creates a Grok summarize adapter with explicit API key.
  * Type resolution happens here at the call site.
  *
- * @param model - The model name (e.g., 'grok-3', 'grok-4')
+ * @param model - The model name (e.g., 'grok-build-0.1')
  * @param apiKey - Your xAI API key
  * @param config - Optional additional configuration
  * @returns Configured Grok summarize adapter instance with resolved types
  *
  * @example
  * ```typescript
- * const adapter = createGrokSummarize('grok-3', "xai-...");
+ * const adapter = createGrokSummarize('grok-build-0.1', "xai-...");
  * ```
  */
 export declare function createGrokSummarize<TModel extends GrokSummarizeModel>(model: TModel, apiKey: string, config?: Omit<GrokSummarizeConfig, 'apiKey'>): ChatStreamSummarizeAdapter<TModel, InferTextProviderOptions<GrokTextAdapter<TModel>>>;
@@ -32,7 +32,7 @@ export declare function createGrokSummarize<TModel extends GrokSummarizeModel>(m
  * - `process.env` (Node.js)
  * - `window.env` (Browser with injected env)
  *
- * @param model - The model name (e.g., 'grok-3', 'grok-4')
+ * @param model - The model name (e.g., 'grok-build-0.1')
  * @param config - Optional configuration (excluding apiKey which is auto-detected)
  * @returns Configured Grok summarize adapter instance with resolved types
  * @throws Error if XAI_API_KEY is not found in environment
@@ -40,7 +40,7 @@ export declare function createGrokSummarize<TModel extends GrokSummarizeModel>(m
  * @example
  * ```typescript
  * // Automatically uses XAI_API_KEY from environment
- * const adapter = grokSummarize('grok-3');
+ * const adapter = grokSummarize('grok-build-0.1');
  *
  * await summarize({
  *   adapter,

package/dist/esm/adapters/summarize.js.map

@@ -1 +1 @@
-{"version":3,"file":"summarize.js","sources":["../../../src/adapters/summarize.ts"],"sourcesContent":["import { ChatStreamSummarizeAdapter } from '@tanstack/ai/adapters'\nimport { getGrokApiKeyFromEnv } from '../utils'\nimport { GrokTextAdapter } from './text'\nimport type { InferTextProviderOptions } from '@tanstack/ai/adapters'\nimport type { GROK_CHAT_MODELS } from '../model-meta'\nimport type { GrokClientConfig } from '../utils'\n\n/**\n * Configuration for Grok summarize adapter\n */\nexport interface GrokSummarizeConfig extends GrokClientConfig {}\n\n/** Model type for Grok summarization */\nexport type GrokSummarizeModel = (typeof GROK_CHAT_MODELS)[number]\n\n/**\n * Creates a Grok summarize adapter with explicit API key.\n * Type resolution happens here at the call site.\n *\n * @param model - The model name (e.g., 'grok-3', 'grok-4')\n * @param apiKey - Your xAI API key\n * @param config - Optional additional configuration\n * @returns Configured Grok summarize adapter instance with resolved types\n *\n * @example\n * ```typescript\n * const adapter = createGrokSummarize('grok-3', \"xai-...\");\n * ```\n */\nexport function createGrokSummarize<TModel extends GrokSummarizeModel>(\n  model: TModel,\n  apiKey: string,\n  config?: Omit<GrokSummarizeConfig, 'apiKey'>,\n): ChatStreamSummarizeAdapter<\n  TModel,\n  InferTextProviderOptions<GrokTextAdapter<TModel>>\n> {\n  return new ChatStreamSummarizeAdapter(\n    new GrokTextAdapter({ apiKey, ...config }, model),\n    model,\n    'grok',\n  )\n}\n\n/**\n * Creates a Grok summarize adapter with automatic API key detection from environment variables.\n * Type resolution happens here at the call site.\n *\n * Looks for `XAI_API_KEY` in:\n * - `process.env` (Node.js)\n * - `window.env` (Browser with injected env)\n *\n * @param model - The model name (e.g., 'grok-3', 'grok-4')\n * @param config - Optional configuration (excluding apiKey which is auto-detected)\n * @returns Configured Grok summarize adapter instance with resolved types\n * @throws Error if XAI_API_KEY is not found in environment\n *\n * @example\n * ```typescript\n * // Automatically uses XAI_API_KEY from environment\n * const adapter = grokSummarize('grok-3');\n *\n * await summarize({\n *   adapter,\n *   text: \"Long article text...\"\n * });\n * ```\n */\nexport function grokSummarize<TModel extends GrokSummarizeModel>(\n  model: TModel,\n  config?: Omit<GrokSummarizeConfig, 'apiKey'>,\n): ChatStreamSummarizeAdapter<\n  TModel,\n  InferTextProviderOptions<GrokTextAdapter<TModel>>\n> {\n  return createGrokSummarize(model, getGrokApiKeyFromEnv(), config)\n}\n"],"names":[],"mappings":";;;;;AA6BO,SAAS,oBACd,OACA,QACA,QAIA;AACA,SAAO,IAAI;AAAA,IACT,IAAI,gBAAgB,EAAE,QAAQ,GAAG,OAAA,GAAU,KAAK;AAAA,IAChD;AAAA,IACA;AAAA,EAAA;AAEJ;AA0BO,SAAS,cACd,OACA,QAIA;AACA,SAAO,oBAAoB,OAAO,qBAAA,GAAwB,MAAM;AAClE;"}
+{"version":3,"file":"summarize.js","sources":["../../../src/adapters/summarize.ts"],"sourcesContent":["import { ChatStreamSummarizeAdapter } from '@tanstack/ai/adapters'\nimport { getGrokApiKeyFromEnv } from '../utils'\nimport { GrokTextAdapter } from './text'\nimport type { InferTextProviderOptions } from '@tanstack/ai/adapters'\nimport type { GROK_CHAT_MODELS } from '../model-meta'\nimport type { GrokClientConfig } from '../utils'\n\n/**\n * Configuration for Grok summarize adapter\n */\nexport interface GrokSummarizeConfig extends GrokClientConfig {}\n\n/** Model type for Grok summarization */\nexport type GrokSummarizeModel = (typeof GROK_CHAT_MODELS)[number]\n\n/**\n * Creates a Grok summarize adapter with explicit API key.\n * Type resolution happens here at the call site.\n *\n * @param model - The model name (e.g., 'grok-build-0.1')\n * @param apiKey - Your xAI API key\n * @param config - Optional additional configuration\n * @returns Configured Grok summarize adapter instance with resolved types\n *\n * @example\n * ```typescript\n * const adapter = createGrokSummarize('grok-build-0.1', \"xai-...\");\n * ```\n */\nexport function createGrokSummarize<TModel extends GrokSummarizeModel>(\n  model: TModel,\n  apiKey: string,\n  config?: Omit<GrokSummarizeConfig, 'apiKey'>,\n): ChatStreamSummarizeAdapter<\n  TModel,\n  InferTextProviderOptions<GrokTextAdapter<TModel>>\n> {\n  return new ChatStreamSummarizeAdapter(\n    new GrokTextAdapter({ apiKey, ...config }, model),\n    model,\n    'grok',\n  )\n}\n\n/**\n * Creates a Grok summarize adapter with automatic API key detection from environment variables.\n * Type resolution happens here at the call site.\n *\n * Looks for `XAI_API_KEY` in:\n * - `process.env` (Node.js)\n * - `window.env` (Browser with injected env)\n *\n * @param model - The model name (e.g., 'grok-build-0.1')\n * @param config - Optional configuration (excluding apiKey which is auto-detected)\n * @returns Configured Grok summarize adapter instance with resolved types\n * @throws Error if XAI_API_KEY is not found in environment\n *\n * @example\n * ```typescript\n * // Automatically uses XAI_API_KEY from environment\n * const adapter = grokSummarize('grok-build-0.1');\n *\n * await summarize({\n *   adapter,\n *   text: \"Long article text...\"\n * });\n * ```\n */\nexport function grokSummarize<TModel extends GrokSummarizeModel>(\n  model: TModel,\n  config?: Omit<GrokSummarizeConfig, 'apiKey'>,\n): ChatStreamSummarizeAdapter<\n  TModel,\n  InferTextProviderOptions<GrokTextAdapter<TModel>>\n> {\n  return createGrokSummarize(model, getGrokApiKeyFromEnv(), config)\n}\n"],"names":[],"mappings":";;;;;AA6BO,SAAS,oBACd,OACA,QACA,QAIA;AACA,SAAO,IAAI;AAAA,IACT,IAAI,gBAAgB,EAAE,QAAQ,GAAG,OAAA,GAAU,KAAK;AAAA,IAChD;AAAA,IACA;AAAA,EAAA;AAEJ;AA0BO,SAAS,cACd,OACA,QAIA;AACA,SAAO,oBAAoB,OAAO,qBAAA,GAAwB,MAAM;AAClE;"}

package/dist/esm/adapters/text.d.ts

@@ -1,9 +1,9 @@
-import { default as OpenAI } from 'openai';
-import { OpenAIBaseChatCompletionsTextAdapter } from '@tanstack/openai-base';
+import { OpenAIBaseResponsesTextAdapter } from '@tanstack/openai-base';
 import { GROK_CHAT_MODELS, GrokChatModelToolCapabilitiesByName, ResolveInputModalities, ResolveProviderOptions } from '../model-meta.js';
-import { Modality } from '@tanstack/ai';
+import { Modality, TextOptions } from '@tanstack/ai';
 import { GrokMessageMetadataByModality } from '../message-types.js';
 import { GrokClientConfig } from '../utils.js';
+import { ResponseCreateParams } from 'openai/resources/responses/responses';
 /**
  * Resolve tool capabilities for a specific Grok model.
  */
@@ -21,49 +21,31 @@ export type { ExternalTextProviderOptions as GrokTextProviderOptions } from '../
  * Grok Text (Chat) Adapter
  *
  * Tree-shakeable adapter for Grok chat/text completion functionality.
- * Uses OpenAI-compatible Chat Completions API (not Responses API).
+ * Uses xAI's OpenAI-compatible Responses API.
  *
- * Delegates implementation to {@link OpenAIBaseChatCompletionsTextAdapter}
+ * Delegates implementation to {@link OpenAIBaseResponsesTextAdapter}
  * from `@tanstack/openai-base` and threads Grok-specific tool-capability
  * typing through the 5th generic of the base class.
  */
-export declare class GrokTextAdapter<TModel extends (typeof GROK_CHAT_MODELS)[number], TProviderOptions extends Record<string, any> = ResolveProviderOptions<TModel>, TInputModalities extends ReadonlyArray<Modality> = ResolveInputModalities<TModel>, TToolCapabilities extends ReadonlyArray<string> = ResolveToolCapabilities<TModel>> extends OpenAIBaseChatCompletionsTextAdapter<TModel, TProviderOptions, TInputModalities, GrokMessageMetadataByModality, TToolCapabilities> {
+export declare class GrokTextAdapter<TModel extends (typeof GROK_CHAT_MODELS)[number], TProviderOptions extends Record<string, unknown> = ResolveProviderOptions<TModel>, TInputModalities extends ReadonlyArray<Modality> = ResolveInputModalities<TModel>, TToolCapabilities extends ReadonlyArray<string> = ResolveToolCapabilities<TModel>> extends OpenAIBaseResponsesTextAdapter<TModel, TProviderOptions, TInputModalities, GrokMessageMetadataByModality, TToolCapabilities> {
     readonly kind: "text";
     readonly name: "grok";
     constructor(config: GrokTextConfig, model: TModel);
-    /**
-     * Surfaces xAI reasoning deltas on Grok reasoning models. The DeepSeek-style
-     * convention puts the chain-of-thought on `delta.reasoning_content`; some
-     * Grok variants also populate `delta.reasoning`. Reading both keeps
-     * reasoning flowing through the base's REASONING_* lifecycle for both
-     * `chatStream` and `structuredOutputStream`.
-     */
-    protected extractReasoning(chunk: OpenAI.Chat.Completions.ChatCompletionChunk): {
-        text: string;
-    } | undefined;
-    /**
-     * Grok's combined tools + schema support is gated to the Grok 4 family
-     * per xAI's structured-output docs; Grok 2 / 3 reject the combination.
-     * The wiring on the wire is already correct (inherits the OpenAI Chat
-     * Completions `response_format: json_schema` attach from the base
-     * adapter); this override just narrows the capability claim to the
-     * supported model family.
-     */
-    supportsCombinedToolsAndSchema(): boolean;
+    protected mapOptionsToRequest(options: TextOptions<TProviderOptions>): Omit<ResponseCreateParams, 'stream'>;
 }
 /**
  * Creates a Grok text adapter with explicit API key.
  * Type resolution happens here at the call site.
  *
- * @param model - The model name (e.g., 'grok-3', 'grok-4')
+ * @param model - The model name (e.g., 'grok-build-0.1')
  * @param apiKey - Your xAI API key
  * @param config - Optional additional configuration
  * @returns Configured Grok text adapter instance with resolved types
  *
  * @example
  * ```typescript
- * const adapter = createGrokText('grok-3', "xai-...");
- * // adapter has type-safe providerOptions for grok-3
+ * const adapter = createGrokText('grok-build-0.1', "xai-...");
+ * // adapter has type-safe providerOptions for grok-build-0.1
  * ```
  */
 export declare function createGrokText<TModel extends (typeof GROK_CHAT_MODELS)[number]>(model: TModel, apiKey: string, config?: Omit<GrokTextConfig, 'apiKey'>): GrokTextAdapter<TModel>;
@@ -75,7 +57,7 @@ export declare function createGrokText<TModel extends (typeof GROK_CHAT_MODELS)[
  * - `process.env` (Node.js)
  * - `window.env` (Browser with injected env)
  *
- * @param model - The model name (e.g., 'grok-3', 'grok-4')
+ * @param model - The model name (e.g., 'grok-build-0.1')
  * @param config - Optional configuration (excluding apiKey which is auto-detected)
  * @returns Configured Grok text adapter instance with resolved types
  * @throws Error if XAI_API_KEY is not found in environment
@@ -83,7 +65,7 @@ export declare function createGrokText<TModel extends (typeof GROK_CHAT_MODELS)[
  * @example
  * ```typescript
  * // Automatically uses XAI_API_KEY from environment
- * const adapter = grokText('grok-3');
+ * const adapter = grokText('grok-build-0.1');
  *
  * const stream = chat({
  *   adapter,

package/dist/esm/adapters/text.js

@@ -1,38 +1,32 @@
 import OpenAI from "openai";
-import { OpenAIBaseChatCompletionsTextAdapter } from "@tanstack/openai-base";
+import { OpenAIBaseResponsesTextAdapter } from "@tanstack/openai-base";
 import { withGrokDefaults, getGrokApiKeyFromEnv } from "../utils/client.js";
-import { GROK_COMBINED_TOOLS_AND_SCHEMA_MODELS } from "../model-meta.js";
-class GrokTextAdapter extends OpenAIBaseChatCompletionsTextAdapter {
+import { convertToolsToProviderFormat } from "../tools/index.js";
+class GrokTextAdapter extends OpenAIBaseResponsesTextAdapter {
   kind = "text";
   name = "grok";
   constructor(config, model) {
     super(model, "grok", new OpenAI(withGrokDefaults(config)));
   }
-  /**
-   * Surfaces xAI reasoning deltas on Grok reasoning models. The DeepSeek-style
-   * convention puts the chain-of-thought on `delta.reasoning_content`; some
-   * Grok variants also populate `delta.reasoning`. Reading both keeps
-   * reasoning flowing through the base's REASONING_* lifecycle for both
-   * `chatStream` and `structuredOutputStream`.
-   */
-  extractReasoning(chunk) {
-    const delta = chunk.choices[0]?.delta;
-    const raw = delta?.reasoning_content ?? delta?.reasoning;
-    if (typeof raw === "string" && raw.length > 0) {
-      return { text: raw };
+  mapOptionsToRequest(options) {
+    const { tools: _baseTools, ...request } = super.mapOptionsToRequest({
+      ...options,
+      tools: void 0
+    });
+    if (this.model === "grok-build-0.1" && request.reasoning !== void 0) {
+      throw new Error(
+        "grok-build-0.1 does not support reasoning modelOptions; omit reasoning for this model."
+      );
     }
-    return void 0;
-  }
-  /**
-   * Grok's combined tools + schema support is gated to the Grok 4 family
-   * per xAI's structured-output docs; Grok 2 / 3 reject the combination.
-   * The wiring on the wire is already correct (inherits the OpenAI Chat
-   * Completions `response_format: json_schema` attach from the base
-   * adapter); this override just narrows the capability claim to the
-   * supported model family.
-   */
-  supportsCombinedToolsAndSchema() {
-    return GROK_COMBINED_TOOLS_AND_SCHEMA_MODELS.has(this.model);
+    const tools = options.tools ? convertToolsToProviderFormat(options.tools) : void 0;
+    return {
+      ...request,
+      // xAI recommends encrypted reasoning for reasoning-capable Responses
+      // requests; callers can still override either field in modelOptions.
+      store: request.store ?? false,
+      include: request.include ?? ["reasoning.encrypted_content"],
+      ...tools && tools.length > 0 && { tools }
+    };
   }
 }
 function createGrokText(model, apiKey, config) {

package/dist/esm/adapters/text.js.map

@@ -1 +1 @@
-{"version":3,"file":"text.js","sources":["../../../src/adapters/text.ts"],"sourcesContent":["import OpenAI from 'openai'\nimport { OpenAIBaseChatCompletionsTextAdapter } from '@tanstack/openai-base'\nimport { getGrokApiKeyFromEnv, withGrokDefaults } from '../utils/client'\nimport { GROK_COMBINED_TOOLS_AND_SCHEMA_MODELS } from '../model-meta'\nimport type {\n  GROK_CHAT_MODELS,\n  GrokChatModelToolCapabilitiesByName,\n  ResolveInputModalities,\n  ResolveProviderOptions,\n} from '../model-meta'\nimport type { Modality } from '@tanstack/ai'\nimport type { GrokMessageMetadataByModality } from '../message-types'\nimport type { GrokClientConfig } from '../utils'\n\n/**\n * Resolve tool capabilities for a specific Grok model.\n */\ntype ResolveToolCapabilities<TModel extends string> =\n  TModel extends keyof GrokChatModelToolCapabilitiesByName\n    ? NonNullable<GrokChatModelToolCapabilitiesByName[TModel]>\n    : readonly []\n\n/**\n * Configuration for Grok text adapter\n */\nexport interface GrokTextConfig extends GrokClientConfig {}\n\n/**\n * Alias for TextProviderOptions for external use\n */\nexport type { ExternalTextProviderOptions as GrokTextProviderOptions } from '../text/text-provider-options'\n\n/**\n * Grok Text (Chat) Adapter\n *\n * Tree-shakeable adapter for Grok chat/text completion functionality.\n * Uses OpenAI-compatible Chat Completions API (not Responses API).\n *\n * Delegates implementation to {@link OpenAIBaseChatCompletionsTextAdapter}\n * from `@tanstack/openai-base` and threads Grok-specific tool-capability\n * typing through the 5th generic of the base class.\n */\nexport class GrokTextAdapter<\n  TModel extends (typeof GROK_CHAT_MODELS)[number],\n  TProviderOptions extends Record<string, any> = ResolveProviderOptions<TModel>,\n  TInputModalities extends ReadonlyArray<Modality> =\n    ResolveInputModalities<TModel>,\n  TToolCapabilities extends ReadonlyArray<string> =\n    ResolveToolCapabilities<TModel>,\n> extends OpenAIBaseChatCompletionsTextAdapter<\n  TModel,\n  TProviderOptions,\n  TInputModalities,\n  GrokMessageMetadataByModality,\n  TToolCapabilities\n> {\n  override readonly kind = 'text' as const\n  override readonly name = 'grok' as const\n\n  constructor(config: GrokTextConfig, model: TModel) {\n    super(model, 'grok', new OpenAI(withGrokDefaults(config)))\n  }\n\n  /**\n   * Surfaces xAI reasoning deltas on Grok reasoning models. The DeepSeek-style\n   * convention puts the chain-of-thought on `delta.reasoning_content`; some\n   * Grok variants also populate `delta.reasoning`. Reading both keeps\n   * reasoning flowing through the base's REASONING_* lifecycle for both\n   * `chatStream` and `structuredOutputStream`.\n   */\n  protected override extractReasoning(\n    chunk: OpenAI.Chat.Completions.ChatCompletionChunk,\n  ): { text: string } | undefined {\n    const delta = chunk.choices[0]?.delta as\n      | { reasoning?: unknown; reasoning_content?: unknown }\n      | undefined\n    const raw = delta?.reasoning_content ?? delta?.reasoning\n    if (typeof raw === 'string' && raw.length > 0) {\n      return { text: raw }\n    }\n    return undefined\n  }\n\n  /**\n   * Grok's combined tools + schema support is gated to the Grok 4 family\n   * per xAI's structured-output docs; Grok 2 / 3 reject the combination.\n   * The wiring on the wire is already correct (inherits the OpenAI Chat\n   * Completions `response_format: json_schema` attach from the base\n   * adapter); this override just narrows the capability claim to the\n   * supported model family.\n   */\n  override supportsCombinedToolsAndSchema(): boolean {\n    return GROK_COMBINED_TOOLS_AND_SCHEMA_MODELS.has(this.model)\n  }\n}\n\n/**\n * Creates a Grok text adapter with explicit API key.\n * Type resolution happens here at the call site.\n *\n * @param model - The model name (e.g., 'grok-3', 'grok-4')\n * @param apiKey - Your xAI API key\n * @param config - Optional additional configuration\n * @returns Configured Grok text adapter instance with resolved types\n *\n * @example\n * ```typescript\n * const adapter = createGrokText('grok-3', \"xai-...\");\n * // adapter has type-safe providerOptions for grok-3\n * ```\n */\nexport function createGrokText<\n  TModel extends (typeof GROK_CHAT_MODELS)[number],\n>(\n  model: TModel,\n  apiKey: string,\n  config?: Omit<GrokTextConfig, 'apiKey'>,\n): GrokTextAdapter<TModel> {\n  return new GrokTextAdapter({ apiKey, ...config }, model)\n}\n\n/**\n * Creates a Grok text adapter with automatic API key detection from environment variables.\n * Type resolution happens here at the call site.\n *\n * Looks for `XAI_API_KEY` in:\n * - `process.env` (Node.js)\n * - `window.env` (Browser with injected env)\n *\n * @param model - The model name (e.g., 'grok-3', 'grok-4')\n * @param config - Optional configuration (excluding apiKey which is auto-detected)\n * @returns Configured Grok text adapter instance with resolved types\n * @throws Error if XAI_API_KEY is not found in environment\n *\n * @example\n * ```typescript\n * // Automatically uses XAI_API_KEY from environment\n * const adapter = grokText('grok-3');\n *\n * const stream = chat({\n *   adapter,\n *   messages: [{ role: \"user\", content: \"Hello!\" }]\n * });\n * ```\n */\nexport function grokText<TModel extends (typeof GROK_CHAT_MODELS)[number]>(\n  model: TModel,\n  config?: Omit<GrokTextConfig, 'apiKey'>,\n): GrokTextAdapter<TModel> {\n  const apiKey = getGrokApiKeyFromEnv()\n  return createGrokText(model, apiKey, config)\n}\n"],"names":[],"mappings":";;;;AA0CO,MAAM,wBAOH,qCAMR;AAAA,EACkB,OAAO;AAAA,EACP,OAAO;AAAA,EAEzB,YAAY,QAAwB,OAAe;AACjD,UAAM,OAAO,QAAQ,IAAI,OAAO,iBAAiB,MAAM,CAAC,CAAC;AAAA,EAC3D;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASmB,iBACjB,OAC8B;AAC9B,UAAM,QAAQ,MAAM,QAAQ,CAAC,GAAG;AAGhC,UAAM,MAAM,OAAO,qBAAqB,OAAO;AAC/C,QAAI,OAAO,QAAQ,YAAY,IAAI,SAAS,GAAG;AAC7C,aAAO,EAAE,MAAM,IAAA;AAAA,IACjB;AACA,WAAO;AAAA,EACT;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUS,iCAA0C;AACjD,WAAO,sCAAsC,IAAI,KAAK,KAAK;AAAA,EAC7D;AACF;AAiBO,SAAS,eAGd,OACA,QACA,QACyB;AACzB,SAAO,IAAI,gBAAgB,EAAE,QAAQ,GAAG,OAAA,GAAU,KAAK;AACzD;AA0BO,SAAS,SACd,OACA,QACyB;AACzB,QAAM,SAAS,qBAAA;AACf,SAAO,eAAe,OAAO,QAAQ,MAAM;AAC7C;"}
+{"version":3,"file":"text.js","sources":["../../../src/adapters/text.ts"],"sourcesContent":["import OpenAI from 'openai'\nimport { OpenAIBaseResponsesTextAdapter } from '@tanstack/openai-base'\nimport { getGrokApiKeyFromEnv, withGrokDefaults } from '../utils/client'\nimport { convertToolsToProviderFormat } from '../tools'\nimport type {\n  GROK_CHAT_MODELS,\n  GrokChatModelToolCapabilitiesByName,\n  ResolveInputModalities,\n  ResolveProviderOptions,\n} from '../model-meta'\nimport type { Modality, TextOptions } from '@tanstack/ai'\nimport type { GrokMessageMetadataByModality } from '../message-types'\nimport type { GrokClientConfig } from '../utils'\nimport type { ResponseCreateParams } from 'openai/resources/responses/responses'\n\n/**\n * Resolve tool capabilities for a specific Grok model.\n */\ntype ResolveToolCapabilities<TModel extends string> =\n  TModel extends keyof GrokChatModelToolCapabilitiesByName\n    ? NonNullable<GrokChatModelToolCapabilitiesByName[TModel]>\n    : readonly []\n\n/**\n * Configuration for Grok text adapter\n */\nexport interface GrokTextConfig extends GrokClientConfig {}\n\n/**\n * Alias for TextProviderOptions for external use\n */\nexport type { ExternalTextProviderOptions as GrokTextProviderOptions } from '../text/text-provider-options'\n\n/**\n * Grok Text (Chat) Adapter\n *\n * Tree-shakeable adapter for Grok chat/text completion functionality.\n * Uses xAI's OpenAI-compatible Responses API.\n *\n * Delegates implementation to {@link OpenAIBaseResponsesTextAdapter}\n * from `@tanstack/openai-base` and threads Grok-specific tool-capability\n * typing through the 5th generic of the base class.\n */\nexport class GrokTextAdapter<\n  TModel extends (typeof GROK_CHAT_MODELS)[number],\n  TProviderOptions extends Record<string, unknown> =\n    ResolveProviderOptions<TModel>,\n  TInputModalities extends ReadonlyArray<Modality> =\n    ResolveInputModalities<TModel>,\n  TToolCapabilities extends ReadonlyArray<string> =\n    ResolveToolCapabilities<TModel>,\n> extends OpenAIBaseResponsesTextAdapter<\n  TModel,\n  TProviderOptions,\n  TInputModalities,\n  GrokMessageMetadataByModality,\n  TToolCapabilities\n> {\n  override readonly kind = 'text' as const\n  override readonly name = 'grok' as const\n\n  constructor(config: GrokTextConfig, model: TModel) {\n    super(model, 'grok', new OpenAI(withGrokDefaults(config)))\n  }\n\n  protected override mapOptionsToRequest(\n    options: TextOptions<TProviderOptions>,\n  ): Omit<ResponseCreateParams, 'stream'> {\n    const { tools: _baseTools, ...request } = super.mapOptionsToRequest({\n      ...options,\n      tools: undefined,\n    })\n    void _baseTools\n\n    if (this.model === 'grok-build-0.1' && request.reasoning !== undefined) {\n      throw new Error(\n        'grok-build-0.1 does not support reasoning modelOptions; omit reasoning for this model.',\n      )\n    }\n\n    const tools = options.tools\n      ? convertToolsToProviderFormat(options.tools)\n      : undefined\n\n    return {\n      ...request,\n      // xAI recommends encrypted reasoning for reasoning-capable Responses\n      // requests; callers can still override either field in modelOptions.\n      store: request.store ?? false,\n      include: request.include ?? ['reasoning.encrypted_content'],\n      ...(tools &&\n        tools.length > 0 && { tools: tools as ResponseCreateParams['tools'] }),\n    }\n  }\n}\n\n/**\n * Creates a Grok text adapter with explicit API key.\n * Type resolution happens here at the call site.\n *\n * @param model - The model name (e.g., 'grok-build-0.1')\n * @param apiKey - Your xAI API key\n * @param config - Optional additional configuration\n * @returns Configured Grok text adapter instance with resolved types\n *\n * @example\n * ```typescript\n * const adapter = createGrokText('grok-build-0.1', \"xai-...\");\n * // adapter has type-safe providerOptions for grok-build-0.1\n * ```\n */\nexport function createGrokText<\n  TModel extends (typeof GROK_CHAT_MODELS)[number],\n>(\n  model: TModel,\n  apiKey: string,\n  config?: Omit<GrokTextConfig, 'apiKey'>,\n): GrokTextAdapter<TModel> {\n  return new GrokTextAdapter({ apiKey, ...config }, model)\n}\n\n/**\n * Creates a Grok text adapter with automatic API key detection from environment variables.\n * Type resolution happens here at the call site.\n *\n * Looks for `XAI_API_KEY` in:\n * - `process.env` (Node.js)\n * - `window.env` (Browser with injected env)\n *\n * @param model - The model name (e.g., 'grok-build-0.1')\n * @param config - Optional configuration (excluding apiKey which is auto-detected)\n * @returns Configured Grok text adapter instance with resolved types\n * @throws Error if XAI_API_KEY is not found in environment\n *\n * @example\n * ```typescript\n * // Automatically uses XAI_API_KEY from environment\n * const adapter = grokText('grok-build-0.1');\n *\n * const stream = chat({\n *   adapter,\n *   messages: [{ role: \"user\", content: \"Hello!\" }]\n * });\n * ```\n */\nexport function grokText<TModel extends (typeof GROK_CHAT_MODELS)[number]>(\n  model: TModel,\n  config?: Omit<GrokTextConfig, 'apiKey'>,\n): GrokTextAdapter<TModel> {\n  const apiKey = getGrokApiKeyFromEnv()\n  return createGrokText(model, apiKey, config)\n}\n"],"names":[],"mappings":";;;;AA2CO,MAAM,wBAQH,+BAMR;AAAA,EACkB,OAAO;AAAA,EACP,OAAO;AAAA,EAEzB,YAAY,QAAwB,OAAe;AACjD,UAAM,OAAO,QAAQ,IAAI,OAAO,iBAAiB,MAAM,CAAC,CAAC;AAAA,EAC3D;AAAA,EAEmB,oBACjB,SACsC;AACtC,UAAM,EAAE,OAAO,YAAY,GAAG,QAAA,IAAY,MAAM,oBAAoB;AAAA,MAClE,GAAG;AAAA,MACH,OAAO;AAAA,IAAA,CACR;AAGD,QAAI,KAAK,UAAU,oBAAoB,QAAQ,cAAc,QAAW;AACtE,YAAM,IAAI;AAAA,QACR;AAAA,MAAA;AAAA,IAEJ;AAEA,UAAM,QAAQ,QAAQ,QAClB,6BAA6B,QAAQ,KAAK,IAC1C;AAEJ,WAAO;AAAA,MACL,GAAG;AAAA;AAAA;AAAA,MAGH,OAAO,QAAQ,SAAS;AAAA,MACxB,SAAS,QAAQ,WAAW,CAAC,6BAA6B;AAAA,MAC1D,GAAI,SACF,MAAM,SAAS,KAAK,EAAE,MAAA;AAAA,IAA8C;AAAA,EAE1E;AACF;AAiBO,SAAS,eAGd,OACA,QACA,QACyB;AACzB,SAAO,IAAI,gBAAgB,EAAE,QAAQ,GAAG,OAAA,GAAU,KAAK;AACzD;AA0BO,SAAS,SACd,OACA,QACyB;AACzB,QAAM,SAAS,qBAAA;AACf,SAAO,eAAe,OAAO,QAAQ,MAAM;AAC7C;"}

package/dist/esm/adapters/video.d.ts

@@ -0,0 +1,128 @@
+import { BaseVideoAdapter, DurationOptions } from '@tanstack/ai/adapters';
+import { VideoGenerationOptions, VideoJobResult, VideoStatusResult, VideoUrlResult } from '@tanstack/ai';
+import { GrokVideoModel } from '../model-meta.js';
+import { GrokVideoModelDurationByName, GrokVideoModelInputModalitiesByName, GrokVideoModelProviderOptionsByName, GrokVideoModelSizeByName, GrokVideoProviderOptions } from '../video/video-provider-options.js';
+import { GrokClientConfig } from '../utils.js';
+/**
+ * Configuration for Grok video adapter.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export interface GrokVideoConfig extends GrokClientConfig {
+}
+/**
+ * Grok Video Generation Adapter (xAI Imagine API)
+ *
+ * Tree-shakeable adapter for the grok-imagine video models using the
+ * async jobs/polling architecture: create a generation request, poll it,
+ * then read the completed video URL.
+ *
+ * `grok-imagine-video` (v1.0) supports text-to-video and image-to-video.
+ * `grok-imagine-video-1.5` is image-to-video only — every request needs an
+ * image prompt part as the starting frame, and the adapter rejects a
+ * text-only prompt with a clear error rather than a raw API 400.
+ *
+ * The Imagine video endpoints are not part of the OpenAI SDK surface (and
+ * xAI rejects the SDK's multipart paths), so requests are plain JSON calls
+ * issued with the configured `fetch` (or the global one).
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ *
+ * Features:
+ * - Async job-based video generation (1–15 second clips with audio)
+ * - Aspect-ratio sizing via the "aspectRatio_resolution" size template
+ *   (e.g. '16:9_720p'), consistent with the grok-imagine image models
+ * - Image-to-video via an `image` prompt part (starting frame URL or data URI)
+ * - Usage reporting: billed seconds (`unitsBilled`) and exact cost
+ */
+export declare class GrokVideoAdapter<TModel extends GrokVideoModel> extends BaseVideoAdapter<TModel, GrokVideoProviderOptions, GrokVideoModelProviderOptionsByName, GrokVideoModelSizeByName, GrokVideoModelInputModalitiesByName, GrokVideoModelDurationByName> {
+    readonly name: "grok";
+    private readonly clientConfig;
+    constructor(config: GrokVideoConfig, model: TModel);
+    private get fetch();
+    private request;
+    /**
+     * Reads the error message out of an Imagine API error body
+     * (`{"code": "...", "error": "..."}`), falling back to the raw text.
+     */
+    private errorMessage;
+    createVideoJob(options: VideoGenerationOptions<GrokVideoProviderOptions, GrokVideoModelSizeByName[TModel], GrokVideoModelDurationByName[TModel]>): Promise<VideoJobResult>;
+    private retrieveJob;
+    getVideoStatus(jobId: string): Promise<VideoStatusResult>;
+    getVideoUrl(jobId: string): Promise<VideoUrlResult>;
+    /**
+     * Maps Imagine API job statuses onto the generic video status set. The
+     * API reports 'pending' while queued/generating (with a numeric
+     * `progress`), then a terminal 'done' / 'failed' / 'expired'.
+     */
+    protected mapStatus(apiStatus: string | undefined): 'pending' | 'processing' | 'completed' | 'failed';
+    /**
+     * Both grok-imagine video models accept a continuous 1–15 integer-second
+     * range. Consumers can use this to render UI without provider knowledge.
+     */
+    availableDurations(): DurationOptions<GrokVideoModelDurationByName[TModel]>;
+    /**
+     * Coerce a raw seconds value to the closest valid duration (clamped to
+     * [1, 15] and rounded to whole seconds).
+     */
+    snapDuration(seconds: number): GrokVideoModelDurationByName[TModel] | undefined;
+}
+/**
+ * Creates a Grok video adapter with an explicit API key.
+ * Type resolution happens here at the call site.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ *
+ * @param model - The model name (e.g., 'grok-imagine-video')
+ * @param apiKey - Your xAI API key
+ * @param config - Optional additional configuration
+ * @returns Configured Grok video adapter instance with resolved types
+ *
+ * @example
+ * ```typescript
+ * // grok-imagine-video (v1.0) supports text-to-video.
+ * const adapter = createGrokVideo('grok-imagine-video', 'xai-...');
+ *
+ * const { jobId } = await generateVideo({
+ *   adapter,
+ *   prompt: 'A beautiful sunset over the ocean',
+ *   size: '16:9_720p',
+ *   duration: 5
+ * });
+ * ```
+ */
+export declare function createGrokVideo<TModel extends GrokVideoModel>(model: TModel, apiKey: string, config?: Omit<GrokVideoConfig, 'apiKey'>): GrokVideoAdapter<TModel>;
+/**
+ * Creates a Grok video adapter with automatic API key detection from environment variables.
+ * Type resolution happens here at the call site.
+ *
+ * Looks for `XAI_API_KEY` in:
+ * - `process.env` (Node.js)
+ * - `window.env` (Browser with injected env)
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ *
+ * @param model - The model name (e.g., 'grok-imagine-video-1.5')
+ * @param config - Optional configuration (excluding apiKey which is auto-detected)
+ * @returns Configured Grok video adapter instance with resolved types
+ * @throws Error if XAI_API_KEY is not found in environment
+ *
+ * @example
+ * ```typescript
+ * // Automatically uses XAI_API_KEY from environment
+ * const adapter = grokVideo('grok-imagine-video-1.5');
+ *
+ * // Image-to-video only: the prompt must carry a starting-frame image part.
+ * const { jobId } = await generateVideo({
+ *   adapter,
+ *   prompt: [
+ *     { type: 'text', content: 'Make the cat start playing the piano' },
+ *     { type: 'image', source: { type: 'url', value: 'https://example.com/cat.png' } },
+ *   ],
+ * });
+ *
+ * // Poll for status
+ * const status = await getVideoJobStatus({ adapter, jobId });
+ * ```
+ */
+export declare function grokVideo<TModel extends GrokVideoModel>(model: TModel, config?: Omit<GrokVideoConfig, 'apiKey'>): GrokVideoAdapter<TModel>;