@tanstack/ai-grok 0.12.4 → 0.14.0

package/dist/esm/tools/index.js

@@ -1,6 +1,113 @@
-import { convertFunctionToolToChatCompletionsFormat, convertToolsToChatCompletionsFormat } from "@tanstack/openai-base";
+import { brandProviderTool } from "@tanstack/ai";
+import { convertFunctionToolToResponsesFormat } from "@tanstack/openai-base";
+import { convertFunctionToolToResponsesFormat as convertFunctionToolToResponsesFormat2 } from "@tanstack/openai-base";
+function providerTool(kind, description, metadata) {
+  return brandProviderTool({
+    name: kind,
+    description,
+    metadata: {
+      __kind: `grok.${kind}`,
+      ...metadata
+    }
+  });
+}
+function grokWebSearchTool(config = {}) {
+  if (config.filters?.allowed_domains !== void 0 && config.filters.excluded_domains !== void 0) {
+    throw new Error(
+      "allowed_domains and excluded_domains cannot both be provided."
+    );
+  }
+  if (config.filters?.allowed_domains !== void 0 && config.filters.allowed_domains.length > 5) {
+    throw new Error("allowed_domains supports at most 5 domains.");
+  }
+  if (config.filters?.excluded_domains !== void 0 && config.filters.excluded_domains.length > 5) {
+    throw new Error("excluded_domains supports at most 5 domains.");
+  }
+  return providerTool("web_search", "Search the web", {
+    type: "web_search",
+    ...config
+  });
+}
+function grokXSearchTool(config = {}) {
+  if (config.allowed_x_handles !== void 0 && config.excluded_x_handles !== void 0) {
+    throw new Error(
+      "allowed_x_handles and excluded_x_handles cannot both be provided."
+    );
+  }
+  if (config.allowed_x_handles !== void 0 && config.allowed_x_handles.length > 20) {
+    throw new Error("allowed_x_handles supports at most 20 handles.");
+  }
+  if (config.excluded_x_handles !== void 0 && config.excluded_x_handles.length > 20) {
+    throw new Error("excluded_x_handles supports at most 20 handles.");
+  }
+  return providerTool("x_search", "Search X posts", {
+    type: "x_search",
+    ...config
+  });
+}
+function grokFileSearchTool(config) {
+  if (config.vector_store_ids.length === 0) {
+    throw new Error("vector_store_ids must contain at least one collection id.");
+  }
+  if (config.max_num_results !== void 0) {
+    if (config.max_num_results < 1 || config.max_num_results > 50) {
+      throw new Error("max_num_results must be between 1 and 50.");
+    }
+  }
+  return providerTool("file_search", "Search xAI file collections", {
+    type: "file_search",
+    ...config
+  });
+}
+function grokMCPTool(config) {
+  if (!config.server_url) {
+    throw new Error("server_url must be provided.");
+  }
+  return providerTool("mcp", config.server_description || "Remote MCP server", {
+    type: "mcp",
+    ...config
+  });
+}
+function getGrokProviderToolKind(tool) {
+  const kind = tool.metadata?.__kind;
+  switch (kind) {
+    case "grok.web_search":
+      return "web_search";
+    case "grok.x_search":
+      return "x_search";
+    case "grok.file_search":
+      return "file_search";
+    case "grok.mcp":
+      return "mcp";
+    default:
+      return void 0;
+  }
+}
+function convertGrokProviderToolToAdapterFormat(tool, kind) {
+  const metadata = tool.metadata;
+  if (metadata.type !== kind) {
+    throw new Error(
+      `convertGrokProviderToolToAdapterFormat: tool "${tool.name}" has mismatched Grok tool metadata.`
+    );
+  }
+  const { __kind: _kind, ...toolConfig } = metadata;
+  return toolConfig;
+}
+function convertToolsToProviderFormat(tools) {
+  return tools.map((tool) => {
+    const grokProviderToolKind = getGrokProviderToolKind(tool);
+    if (grokProviderToolKind) {
+      return convertGrokProviderToolToAdapterFormat(tool, grokProviderToolKind);
+    }
+    return convertFunctionToolToResponsesFormat(tool);
+  });
+}
 export {
-  convertFunctionToolToChatCompletionsFormat as convertFunctionToolToAdapterFormat,
-  convertToolsToChatCompletionsFormat as convertToolsToProviderFormat
+  convertFunctionToolToResponsesFormat2 as convertFunctionToolToAdapterFormat,
+  convertToolsToProviderFormat,
+  grokFileSearchTool,
+  grokMCPTool,
+  grokWebSearchTool,
+  grokXSearchTool
 };
 //# sourceMappingURL=index.js.map

package/dist/esm/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}
+{"version":3,"file":"index.js","sources":["../../../src/tools/index.ts"],"sourcesContent":["import { brandProviderTool } from '@tanstack/ai'\nimport { convertFunctionToolToResponsesFormat } from '@tanstack/openai-base'\nimport type { ProviderTool, Tool } from '@tanstack/ai'\nimport type { ResponsesFunctionTool } from '@tanstack/openai-base'\nimport type { GrokProviderToolKind } from '../model-meta'\n\nexport type FunctionTool = ResponsesFunctionTool\n\nexport { convertFunctionToolToResponsesFormat as convertFunctionToolToAdapterFormat }\n\nexport type GrokProviderTool<TKind extends GrokProviderToolKind> = ProviderTool<\n  'grok',\n  TKind\n>\n\ntype GrokToolKindMarker<TKind extends GrokProviderToolKind> = `grok.${TKind}`\n\nexport interface GrokWebSearchToolConfig {\n  type: 'web_search'\n  filters?: {\n    allowed_domains?: Array<string>\n    excluded_domains?: Array<string>\n  }\n  enable_image_understanding?: boolean\n  enable_image_search?: boolean\n}\n\nexport interface GrokXSearchToolConfig {\n  type: 'x_search'\n  allowed_x_handles?: Array<string>\n  excluded_x_handles?: Array<string>\n  from_date?: string\n  to_date?: string\n  enable_image_understanding?: boolean\n  enable_video_understanding?: boolean\n}\n\nexport interface GrokFileSearchToolConfig {\n  type: 'file_search'\n  vector_store_ids: Array<string>\n  max_num_results?: number\n}\n\nexport interface GrokMCPToolConfig {\n  type: 'mcp'\n  server_label: string\n  server_url: string\n  allowed_tools?: Array<string>\n  server_description?: string\n  authorization?: string\n  headers?: Record<string, string>\n}\n\nexport type GrokServerTool =\n  | GrokWebSearchToolConfig\n  | GrokXSearchToolConfig\n  | GrokFileSearchToolConfig\n  | GrokMCPToolConfig\n\ntype GrokProviderToolMetadata<TKind extends GrokProviderToolKind> = Extract<\n  GrokServerTool,\n  { type: TKind }\n> & {\n  __kind: GrokToolKindMarker<TKind>\n}\n\nexport type GrokResponsesTool = GrokServerTool | ResponsesFunctionTool\n\nfunction providerTool<TKind extends GrokProviderToolKind>(\n  kind: TKind,\n  description: string,\n  metadata: Extract<GrokServerTool, { type: TKind }>,\n): GrokProviderTool<TKind> {\n  return brandProviderTool<GrokProviderTool<TKind>>({\n    name: kind,\n    description,\n    metadata: {\n      __kind: `grok.${kind}`,\n      ...metadata,\n    },\n  })\n}\n\nexport function grokWebSearchTool(\n  config: Omit<GrokWebSearchToolConfig, 'type'> = {},\n): GrokProviderTool<'web_search'> {\n  if (\n    config.filters?.allowed_domains !== undefined &&\n    config.filters.excluded_domains !== undefined\n  ) {\n    throw new Error(\n      'allowed_domains and excluded_domains cannot both be provided.',\n    )\n  }\n  if (\n    config.filters?.allowed_domains !== undefined &&\n    config.filters.allowed_domains.length > 5\n  ) {\n    throw new Error('allowed_domains supports at most 5 domains.')\n  }\n  if (\n    config.filters?.excluded_domains !== undefined &&\n    config.filters.excluded_domains.length > 5\n  ) {\n    throw new Error('excluded_domains supports at most 5 domains.')\n  }\n  return providerTool('web_search', 'Search the web', {\n    type: 'web_search',\n    ...config,\n  })\n}\n\nexport function grokXSearchTool(\n  config: Omit<GrokXSearchToolConfig, 'type'> = {},\n): GrokProviderTool<'x_search'> {\n  if (\n    config.allowed_x_handles !== undefined &&\n    config.excluded_x_handles !== undefined\n  ) {\n    throw new Error(\n      'allowed_x_handles and excluded_x_handles cannot both be provided.',\n    )\n  }\n  if (\n    config.allowed_x_handles !== undefined &&\n    config.allowed_x_handles.length > 20\n  ) {\n    throw new Error('allowed_x_handles supports at most 20 handles.')\n  }\n  if (\n    config.excluded_x_handles !== undefined &&\n    config.excluded_x_handles.length > 20\n  ) {\n    throw new Error('excluded_x_handles supports at most 20 handles.')\n  }\n  return providerTool('x_search', 'Search X posts', {\n    type: 'x_search',\n    ...config,\n  })\n}\n\nexport function grokFileSearchTool(\n  config: Omit<GrokFileSearchToolConfig, 'type'>,\n): GrokProviderTool<'file_search'> {\n  if (config.vector_store_ids.length === 0) {\n    throw new Error('vector_store_ids must contain at least one collection id.')\n  }\n  if (config.max_num_results !== undefined) {\n    if (config.max_num_results < 1 || config.max_num_results > 50) {\n      throw new Error('max_num_results must be between 1 and 50.')\n    }\n  }\n  return providerTool('file_search', 'Search xAI file collections', {\n    type: 'file_search',\n    ...config,\n  })\n}\n\nexport function grokMCPTool(\n  config: Omit<GrokMCPToolConfig, 'type'>,\n): GrokProviderTool<'mcp'> {\n  if (!config.server_url) {\n    throw new Error('server_url must be provided.')\n  }\n  return providerTool('mcp', config.server_description || 'Remote MCP server', {\n    type: 'mcp',\n    ...config,\n  })\n}\n\nfunction getGrokProviderToolKind(tool: Tool): GrokProviderToolKind | undefined {\n  const kind = (tool.metadata as { __kind?: unknown } | undefined)?.__kind\n  switch (kind) {\n    case 'grok.web_search':\n      return 'web_search'\n    case 'grok.x_search':\n      return 'x_search'\n    case 'grok.file_search':\n      return 'file_search'\n    case 'grok.mcp':\n      return 'mcp'\n    default:\n      return undefined\n  }\n}\n\nfunction convertGrokProviderToolToAdapterFormat(\n  tool: Tool,\n  kind: GrokProviderToolKind,\n): GrokServerTool {\n  const metadata = tool.metadata as GrokProviderToolMetadata<typeof kind>\n  if (metadata.type !== kind) {\n    throw new Error(\n      `convertGrokProviderToolToAdapterFormat: tool \"${tool.name}\" has mismatched Grok tool metadata.`,\n    )\n  }\n  const { __kind: _kind, ...toolConfig } = metadata\n  void _kind\n  return toolConfig\n}\n\nexport function convertToolsToProviderFormat(\n  tools: Array<Tool>,\n): Array<GrokResponsesTool> {\n  return tools.map((tool) => {\n    const grokProviderToolKind = getGrokProviderToolKind(tool)\n    if (grokProviderToolKind) {\n      return convertGrokProviderToolToAdapterFormat(tool, grokProviderToolKind)\n    }\n    return convertFunctionToolToResponsesFormat(tool)\n  })\n}\n"],"names":[],"mappings":";;;AAoEA,SAAS,aACP,MACA,aACA,UACyB;AACzB,SAAO,kBAA2C;AAAA,IAChD,MAAM;AAAA,IACN;AAAA,IACA,UAAU;AAAA,MACR,QAAQ,QAAQ,IAAI;AAAA,MACpB,GAAG;AAAA,IAAA;AAAA,EACL,CACD;AACH;AAEO,SAAS,kBACd,SAAgD,IAChB;AAChC,MACE,OAAO,SAAS,oBAAoB,UACpC,OAAO,QAAQ,qBAAqB,QACpC;AACA,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAEJ;AACA,MACE,OAAO,SAAS,oBAAoB,UACpC,OAAO,QAAQ,gBAAgB,SAAS,GACxC;AACA,UAAM,IAAI,MAAM,6CAA6C;AAAA,EAC/D;AACA,MACE,OAAO,SAAS,qBAAqB,UACrC,OAAO,QAAQ,iBAAiB,SAAS,GACzC;AACA,UAAM,IAAI,MAAM,8CAA8C;AAAA,EAChE;AACA,SAAO,aAAa,cAAc,kBAAkB;AAAA,IAClD,MAAM;AAAA,IACN,GAAG;AAAA,EAAA,CACJ;AACH;AAEO,SAAS,gBACd,SAA8C,IAChB;AAC9B,MACE,OAAO,sBAAsB,UAC7B,OAAO,uBAAuB,QAC9B;AACA,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAEJ;AACA,MACE,OAAO,sBAAsB,UAC7B,OAAO,kBAAkB,SAAS,IAClC;AACA,UAAM,IAAI,MAAM,gDAAgD;AAAA,EAClE;AACA,MACE,OAAO,uBAAuB,UAC9B,OAAO,mBAAmB,SAAS,IACnC;AACA,UAAM,IAAI,MAAM,iDAAiD;AAAA,EACnE;AACA,SAAO,aAAa,YAAY,kBAAkB;AAAA,IAChD,MAAM;AAAA,IACN,GAAG;AAAA,EAAA,CACJ;AACH;AAEO,SAAS,mBACd,QACiC;AACjC,MAAI,OAAO,iBAAiB,WAAW,GAAG;AACxC,UAAM,IAAI,MAAM,2DAA2D;AAAA,EAC7E;AACA,MAAI,OAAO,oBAAoB,QAAW;AACxC,QAAI,OAAO,kBAAkB,KAAK,OAAO,kBAAkB,IAAI;AAC7D,YAAM,IAAI,MAAM,2CAA2C;AAAA,IAC7D;AAAA,EACF;AACA,SAAO,aAAa,eAAe,+BAA+B;AAAA,IAChE,MAAM;AAAA,IACN,GAAG;AAAA,EAAA,CACJ;AACH;AAEO,SAAS,YACd,QACyB;AACzB,MAAI,CAAC,OAAO,YAAY;AACtB,UAAM,IAAI,MAAM,8BAA8B;AAAA,EAChD;AACA,SAAO,aAAa,OAAO,OAAO,sBAAsB,qBAAqB;AAAA,IAC3E,MAAM;AAAA,IACN,GAAG;AAAA,EAAA,CACJ;AACH;AAEA,SAAS,wBAAwB,MAA8C;AAC7E,QAAM,OAAQ,KAAK,UAA+C;AAClE,UAAQ,MAAA;AAAA,IACN,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT;AACE,aAAO;AAAA,EAAA;AAEb;AAEA,SAAS,uCACP,MACA,MACgB;AAChB,QAAM,WAAW,KAAK;AACtB,MAAI,SAAS,SAAS,MAAM;AAC1B,UAAM,IAAI;AAAA,MACR,iDAAiD,KAAK,IAAI;AAAA,IAAA;AAAA,EAE9D;AACA,QAAM,EAAE,QAAQ,OAAO,GAAG,eAAe;AAEzC,SAAO;AACT;AAEO,SAAS,6BACd,OAC0B;AAC1B,SAAO,MAAM,IAAI,CAAC,SAAS;AACzB,UAAM,uBAAuB,wBAAwB,IAAI;AACzD,QAAI,sBAAsB;AACxB,aAAO,uCAAuC,MAAM,oBAAoB;AAAA,IAC1E;AACA,WAAO,qCAAqC,IAAI;AAAA,EAClD,CAAC;AACH;"}

package/dist/esm/video/video-provider-options.d.ts

@@ -0,0 +1,135 @@
+import { DurationOptions } from '@tanstack/ai/adapters';
+import { GrokVideoModel } from '../model-meta.js';
+/**
+ * Aspect ratios accepted by the grok-imagine video models.
+ *
+ * Note: this is a narrower set than the grok-imagine image models — the
+ * video endpoint rejects the phone-screen ratios ('9:19.5', '9:20', …) and
+ * 'auto'.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export type GrokVideoAspectRatio = '1:1' | '16:9' | '9:16' | '4:3' | '3:4' | '3:2' | '2:3';
+/**
+ * Resolution tiers for the grok-imagine video models.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export type GrokVideoResolution = '480p' | '720p' | '1080p';
+/**
+ * Size strings for grok-imagine video models. The Imagine API is
+ * aspect-ratio based rather than pixel-size based; like the grok-imagine
+ * image models, the generic `size` option uses an
+ * `aspectRatio_resolution` template ("16:9_720p") — the resolution suffix
+ * is optional ("16:9" uses the API default).
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export type GrokVideoSize = GrokVideoAspectRatio | `${GrokVideoAspectRatio}_${GrokVideoResolution}`;
+/**
+ * Video duration limits enforced by the Imagine API (seconds).
+ */
+export declare const GROK_VIDEO_MIN_DURATION = 1;
+export declare const GROK_VIDEO_MAX_DURATION = 15;
+/**
+ * Parses a grok video size string into its components.
+ * Format: "aspectRatio" or "aspectRatio_resolution",
+ * e.g. "16:9_720p" → { aspectRatio: "16:9", resolution: "720p" }.
+ * Returns undefined when the string doesn't match the template.
+ */
+export declare function parseGrokVideoSize(size: string): {
+    aspectRatio: string;
+    resolution?: string;
+} | undefined;
+/**
+ * Validate the `size` template for a given grok video model.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export declare function validateVideoSize(model: string, size?: string): asserts size is GrokVideoSize | undefined;
+/**
+ * Per-model duration type. The Imagine API accepts any integer second in the
+ * 1–15 range, so this is a continuous range expressed as `number` (a literal
+ * union can't represent it). `snapDuration()` coerces a raw seconds value into
+ * the valid range at runtime.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export type GrokVideoModelDurationByName = {
+    'grok-imagine-video': number;
+    'grok-imagine-video-1.5': number;
+};
+/**
+ * Runtime duration table backing `availableDurations()` / `snapDuration()`.
+ * Both grok-imagine video models accept the same continuous 1–15 integer-second
+ * range.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export declare const GROK_VIDEO_DURATIONS: {
+    readonly [TModel in GrokVideoModel]: DurationOptions<GrokVideoModelDurationByName[TModel]>;
+};
+/**
+ * Look up the duration options for a grok video model.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export declare function getGrokVideoDurationOptions<TModel extends GrokVideoModel>(model: TModel): DurationOptions<GrokVideoModelDurationByName[TModel]>;
+/**
+ * Provider-specific options for grok video generation. These map directly
+ * onto the Imagine API request body and take precedence over the generic
+ * `size` / `duration` options when both are provided.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export interface GrokVideoProviderOptions {
+    /**
+     * Output aspect ratio.
+     */
+    aspect_ratio?: GrokVideoAspectRatio;
+    /**
+     * Output resolution tier.
+     */
+    resolution?: GrokVideoResolution;
+    /**
+     * Video duration in integer seconds (1–15).
+     */
+    duration?: number;
+}
+/**
+ * Type-only map from model name to its specific provider options.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export type GrokVideoModelProviderOptionsByName = {
+    'grok-imagine-video': GrokVideoProviderOptions;
+    'grok-imagine-video-1.5': GrokVideoProviderOptions;
+};
+/**
+ * Type-only map from model name to its supported `size` strings.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export type GrokVideoModelSizeByName = {
+    'grok-imagine-video': GrokVideoSize;
+    'grok-imagine-video-1.5': GrokVideoSize;
+};
+/**
+ * Type-only map from model name to the non-text prompt modalities it accepts.
+ * Both models accept an `image` prompt part as the starting frame:
+ * `grok-imagine-video` (v1.0) does text-to-video and image-to-video, while
+ * `grok-imagine-video-1.5` is image-to-video only (the image is required).
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export type GrokVideoModelInputModalitiesByName = {
+    'grok-imagine-video': readonly ['image'];
+    'grok-imagine-video-1.5': readonly ['image'];
+};
+/**
+ * True when the model only supports image-to-video (a starting frame is
+ * required).
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export declare function isImageToVideoOnlyModel(model: string): boolean;

package/dist/esm/video/video-provider-options.js

@@ -0,0 +1,67 @@
+const GROK_VIDEO_ASPECT_RATIOS = [
+  "1:1",
+  "16:9",
+  "9:16",
+  "4:3",
+  "3:4",
+  "3:2",
+  "2:3"
+];
+const GROK_VIDEO_RESOLUTIONS = ["480p", "720p", "1080p"];
+const GROK_VIDEO_MIN_DURATION = 1;
+const GROK_VIDEO_MAX_DURATION = 15;
+function parseGrokVideoSize(size) {
+  const match = size.match(/^([\d.]+:[\d.]+)(?:_(.+))?$/);
+  const [, aspectRatio, resolution] = match ?? [];
+  if (aspectRatio === void 0) return void 0;
+  return { aspectRatio, ...resolution !== void 0 && { resolution } };
+}
+function validateVideoSize(model, size) {
+  if (size === void 0) return;
+  const parsed = parseGrokVideoSize(size);
+  if (!parsed || !GROK_VIDEO_ASPECT_RATIOS.includes(parsed.aspectRatio)) {
+    throw new Error(
+      `Size "${size}" is not supported by model "${model}". Expected "aspectRatio" or "aspectRatio_resolution" (e.g. "16:9_720p") with aspect ratio one of: ${GROK_VIDEO_ASPECT_RATIOS.join(", ")}`
+    );
+  }
+  if (parsed.resolution !== void 0 && !GROK_VIDEO_RESOLUTIONS.includes(parsed.resolution)) {
+    throw new Error(
+      `Resolution "${parsed.resolution}" is not supported by model "${model}". Supported resolutions: ${GROK_VIDEO_RESOLUTIONS.join(", ")}`
+    );
+  }
+}
+const GROK_VIDEO_DURATIONS = {
+  "grok-imagine-video": {
+    kind: "range",
+    min: GROK_VIDEO_MIN_DURATION,
+    max: GROK_VIDEO_MAX_DURATION,
+    step: 1,
+    unit: "seconds"
+  },
+  "grok-imagine-video-1.5": {
+    kind: "range",
+    min: GROK_VIDEO_MIN_DURATION,
+    max: GROK_VIDEO_MAX_DURATION,
+    step: 1,
+    unit: "seconds"
+  }
+};
+function getGrokVideoDurationOptions(model) {
+  return GROK_VIDEO_DURATIONS[model];
+}
+const GROK_VIDEO_IMAGE_TO_VIDEO_ONLY = /* @__PURE__ */ new Set([
+  "grok-imagine-video-1.5"
+]);
+function isImageToVideoOnlyModel(model) {
+  return GROK_VIDEO_IMAGE_TO_VIDEO_ONLY.has(model);
+}
+export {
+  GROK_VIDEO_DURATIONS,
+  GROK_VIDEO_MAX_DURATION,
+  GROK_VIDEO_MIN_DURATION,
+  getGrokVideoDurationOptions,
+  isImageToVideoOnlyModel,
+  parseGrokVideoSize,
+  validateVideoSize
+};
+//# sourceMappingURL=video-provider-options.js.map

package/dist/esm/video/video-provider-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-provider-options.js","sources":["../../../src/video/video-provider-options.ts"],"sourcesContent":["/**\n * Grok Video Generation Provider Options (xAI Imagine API)\n *\n * Based on https://docs.x.ai/docs/guides/video-generations\n *\n * @experimental Video generation is an experimental feature and may change.\n */\n\nimport type { DurationOptions } from '@tanstack/ai/adapters'\nimport type { GrokVideoModel } from '../model-meta'\n\n/**\n * Aspect ratios accepted by the grok-imagine video models.\n *\n * Note: this is a narrower set than the grok-imagine image models — the\n * video endpoint rejects the phone-screen ratios ('9:19.5', '9:20', …) and\n * 'auto'.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport type GrokVideoAspectRatio =\n  | '1:1'\n  | '16:9'\n  | '9:16'\n  | '4:3'\n  | '3:4'\n  | '3:2'\n  | '2:3'\n\n/**\n * Resolution tiers for the grok-imagine video models.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport type GrokVideoResolution = '480p' | '720p' | '1080p'\n\n/**\n * Size strings for grok-imagine video models. The Imagine API is\n * aspect-ratio based rather than pixel-size based; like the grok-imagine\n * image models, the generic `size` option uses an\n * `aspectRatio_resolution` template (\"16:9_720p\") — the resolution suffix\n * is optional (\"16:9\" uses the API default).\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport type GrokVideoSize =\n  | GrokVideoAspectRatio\n  | `${GrokVideoAspectRatio}_${GrokVideoResolution}`\n\nconst GROK_VIDEO_ASPECT_RATIOS: ReadonlyArray<string> = [\n  '1:1',\n  '16:9',\n  '9:16',\n  '4:3',\n  '3:4',\n  '3:2',\n  '2:3',\n]\n\nconst GROK_VIDEO_RESOLUTIONS: ReadonlyArray<string> = ['480p', '720p', '1080p']\n\n/**\n * Video duration limits enforced by the Imagine API (seconds).\n */\nexport const GROK_VIDEO_MIN_DURATION = 1\nexport const GROK_VIDEO_MAX_DURATION = 15\n\n/**\n * Parses a grok video size string into its components.\n * Format: \"aspectRatio\" or \"aspectRatio_resolution\",\n * e.g. \"16:9_720p\" → { aspectRatio: \"16:9\", resolution: \"720p\" }.\n * Returns undefined when the string doesn't match the template.\n */\nexport function parseGrokVideoSize(\n  size: string,\n): { aspectRatio: string; resolution?: string } | undefined {\n  const match = size.match(/^([\\d.]+:[\\d.]+)(?:_(.+))?$/)\n  const [, aspectRatio, resolution] = match ?? []\n  if (aspectRatio === undefined) return undefined\n  return { aspectRatio, ...(resolution !== undefined && { resolution }) }\n}\n\n/**\n * Validate the `size` template for a given grok video model.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport function validateVideoSize(\n  model: string,\n  size?: string,\n): asserts size is GrokVideoSize | undefined {\n  if (size === undefined) return\n  const parsed = parseGrokVideoSize(size)\n  if (!parsed || !GROK_VIDEO_ASPECT_RATIOS.includes(parsed.aspectRatio)) {\n    throw new Error(\n      `Size \"${size}\" is not supported by model \"${model}\". Expected ` +\n        `\"aspectRatio\" or \"aspectRatio_resolution\" (e.g. \"16:9_720p\") with ` +\n        `aspect ratio one of: ${GROK_VIDEO_ASPECT_RATIOS.join(', ')}`,\n    )\n  }\n  if (\n    parsed.resolution !== undefined &&\n    !GROK_VIDEO_RESOLUTIONS.includes(parsed.resolution)\n  ) {\n    throw new Error(\n      `Resolution \"${parsed.resolution}\" is not supported by model \"${model}\". ` +\n        `Supported resolutions: ${GROK_VIDEO_RESOLUTIONS.join(', ')}`,\n    )\n  }\n}\n\n/**\n * Per-model duration type. The Imagine API accepts any integer second in the\n * 1–15 range, so this is a continuous range expressed as `number` (a literal\n * union can't represent it). `snapDuration()` coerces a raw seconds value into\n * the valid range at runtime.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport type GrokVideoModelDurationByName = {\n  'grok-imagine-video': number\n  'grok-imagine-video-1.5': number\n}\n\n/**\n * Runtime duration table backing `availableDurations()` / `snapDuration()`.\n * Both grok-imagine video models accept the same continuous 1–15 integer-second\n * range.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport const GROK_VIDEO_DURATIONS: {\n  readonly [TModel in GrokVideoModel]: DurationOptions<\n    GrokVideoModelDurationByName[TModel]\n  >\n} = {\n  'grok-imagine-video': {\n    kind: 'range',\n    min: GROK_VIDEO_MIN_DURATION,\n    max: GROK_VIDEO_MAX_DURATION,\n    step: 1,\n    unit: 'seconds',\n  },\n  'grok-imagine-video-1.5': {\n    kind: 'range',\n    min: GROK_VIDEO_MIN_DURATION,\n    max: GROK_VIDEO_MAX_DURATION,\n    step: 1,\n    unit: 'seconds',\n  },\n}\n\n/**\n * Look up the duration options for a grok video model.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport function getGrokVideoDurationOptions<TModel extends GrokVideoModel>(\n  model: TModel,\n): DurationOptions<GrokVideoModelDurationByName[TModel]> {\n  return GROK_VIDEO_DURATIONS[model]\n}\n\n/**\n * Provider-specific options for grok video generation. These map directly\n * onto the Imagine API request body and take precedence over the generic\n * `size` / `duration` options when both are provided.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport interface GrokVideoProviderOptions {\n  /**\n   * Output aspect ratio.\n   */\n  aspect_ratio?: GrokVideoAspectRatio\n\n  /**\n   * Output resolution tier.\n   */\n  resolution?: GrokVideoResolution\n\n  /**\n   * Video duration in integer seconds (1–15).\n   */\n  duration?: number\n}\n\n/**\n * Type-only map from model name to its specific provider options.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport type GrokVideoModelProviderOptionsByName = {\n  'grok-imagine-video': GrokVideoProviderOptions\n  'grok-imagine-video-1.5': GrokVideoProviderOptions\n}\n\n/**\n * Type-only map from model name to its supported `size` strings.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport type GrokVideoModelSizeByName = {\n  'grok-imagine-video': GrokVideoSize\n  'grok-imagine-video-1.5': GrokVideoSize\n}\n\n/**\n * Type-only map from model name to the non-text prompt modalities it accepts.\n * Both models accept an `image` prompt part as the starting frame:\n * `grok-imagine-video` (v1.0) does text-to-video and image-to-video, while\n * `grok-imagine-video-1.5` is image-to-video only (the image is required).\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport type GrokVideoModelInputModalitiesByName = {\n  'grok-imagine-video': readonly ['image']\n  'grok-imagine-video-1.5': readonly ['image']\n}\n\n/**\n * Models that only support image-to-video — a starting-frame image is\n * required and text-to-video is rejected by the Imagine API. Used by the\n * adapter to fail fast with a clear message instead of surfacing the raw\n * \"Text-to-video is not supported for this model\" 400.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nconst GROK_VIDEO_IMAGE_TO_VIDEO_ONLY: ReadonlySet<string> = new Set([\n  'grok-imagine-video-1.5',\n])\n\n/**\n * True when the model only supports image-to-video (a starting frame is\n * required).\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport function isImageToVideoOnlyModel(model: string): boolean {\n  return GROK_VIDEO_IMAGE_TO_VIDEO_ONLY.has(model)\n}\n"],"names":[],"mappings":"AAiDA,MAAM,2BAAkD;AAAA,EACtD;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAEA,MAAM,yBAAgD,CAAC,QAAQ,QAAQ,OAAO;AAKvE,MAAM,0BAA0B;AAChC,MAAM,0BAA0B;AAQhC,SAAS,mBACd,MAC0D;AAC1D,QAAM,QAAQ,KAAK,MAAM,6BAA6B;AACtD,QAAM,GAAG,aAAa,UAAU,IAAI,SAAS,CAAA;AAC7C,MAAI,gBAAgB,OAAW,QAAO;AACtC,SAAO,EAAE,aAAa,GAAI,eAAe,UAAa,EAAE,aAAW;AACrE;AAOO,SAAS,kBACd,OACA,MAC2C;AAC3C,MAAI,SAAS,OAAW;AACxB,QAAM,SAAS,mBAAmB,IAAI;AACtC,MAAI,CAAC,UAAU,CAAC,yBAAyB,SAAS,OAAO,WAAW,GAAG;AACrE,UAAM,IAAI;AAAA,MACR,SAAS,IAAI,gCAAgC,KAAK,sGAExB,yBAAyB,KAAK,IAAI,CAAC;AAAA,IAAA;AAAA,EAEjE;AACA,MACE,OAAO,eAAe,UACtB,CAAC,uBAAuB,SAAS,OAAO,UAAU,GAClD;AACA,UAAM,IAAI;AAAA,MACR,eAAe,OAAO,UAAU,gCAAgC,KAAK,6BACzC,uBAAuB,KAAK,IAAI,CAAC;AAAA,IAAA;AAAA,EAEjE;AACF;AAsBO,MAAM,uBAIT;AAAA,EACF,sBAAsB;AAAA,IACpB,MAAM;AAAA,IACN,KAAK;AAAA,IACL,KAAK;AAAA,IACL,MAAM;AAAA,IACN,MAAM;AAAA,EAAA;AAAA,EAER,0BAA0B;AAAA,IACxB,MAAM;AAAA,IACN,KAAK;AAAA,IACL,KAAK;AAAA,IACL,MAAM;AAAA,IACN,MAAM;AAAA,EAAA;AAEV;AAOO,SAAS,4BACd,OACuD;AACvD,SAAO,qBAAqB,KAAK;AACnC;AAmEA,MAAM,qDAA0D,IAAI;AAAA,EAClE;AACF,CAAC;AAQM,SAAS,wBAAwB,OAAwB;AAC9D,SAAO,+BAA+B,IAAI,KAAK;AACjD;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/ai-grok",
-  "version": "0.12.4",
+  "version": "0.14.0",
   "description": "xAI Grok adapter for TanStack AI chat, image generation, realtime, and structured outputs.",
   "author": "Tanner Linsley",
   "license": "MIT",
@@ -56,12 +56,12 @@
   "devDependencies": {
     "@vitest/coverage-v8": "4.0.14",
     "vite": "^7.3.3",
-    "@tanstack/ai": "0.34.0",
-    "@tanstack/ai-client": "0.18.2"
+    "@tanstack/ai": "0.34.1",
+    "@tanstack/ai-client": "0.18.3"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@tanstack/ai": "^0.34.0"
+    "@tanstack/ai": "^0.34.1"
   },
   "scripts": {
     "build": "vite build",

package/src/adapters/summarize.ts

@@ -17,14 +17,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 function createGrokSummarize<TModel extends GrokSummarizeModel>(
@@ -50,7 +50,7 @@ export function createGrokSummarize<TModel extends GrokSummarizeModel>(
  * - `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
@@ -58,7 +58,7 @@ export function createGrokSummarize<TModel extends GrokSummarizeModel>(
  * @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/src/adapters/text.ts

@@ -1,16 +1,17 @@
 import OpenAI from 'openai'
-import { OpenAIBaseChatCompletionsTextAdapter } from '@tanstack/openai-base'
+import { OpenAIBaseResponsesTextAdapter } from '@tanstack/openai-base'
 import { getGrokApiKeyFromEnv, withGrokDefaults } from '../utils/client'
-import { GROK_COMBINED_TOOLS_AND_SCHEMA_MODELS } from '../model-meta'
+import { convertToolsToProviderFormat } from '../tools'
 import type {
   GROK_CHAT_MODELS,
   GrokChatModelToolCapabilitiesByName,
   ResolveInputModalities,
   ResolveProviderOptions,
 } from '../model-meta'
-import type { Modality } from '@tanstack/ai'
+import type { Modality, TextOptions } from '@tanstack/ai'
 import type { GrokMessageMetadataByModality } from '../message-types'
 import type { GrokClientConfig } from '../utils'
+import type { ResponseCreateParams } from 'openai/resources/responses/responses'
 
 /**
  * Resolve tool capabilities for a specific Grok model.
@@ -34,20 +35,21 @@ 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 class GrokTextAdapter<
   TModel extends (typeof GROK_CHAT_MODELS)[number],
-  TProviderOptions extends Record<string, any> = ResolveProviderOptions<TModel>,
+  TProviderOptions extends Record<string, unknown> =
+    ResolveProviderOptions<TModel>,
   TInputModalities extends ReadonlyArray<Modality> =
     ResolveInputModalities<TModel>,
   TToolCapabilities extends ReadonlyArray<string> =
     ResolveToolCapabilities<TModel>,
-> extends OpenAIBaseChatCompletionsTextAdapter<
+> extends OpenAIBaseResponsesTextAdapter<
   TModel,
   TProviderOptions,
   TInputModalities,
@@ -61,36 +63,34 @@ export class GrokTextAdapter<
     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`.
-   */
-  protected override extractReasoning(
-    chunk: OpenAI.Chat.Completions.ChatCompletionChunk,
-  ): { text: string } | undefined {
-    const delta = chunk.choices[0]?.delta as
-      | { reasoning?: unknown; reasoning_content?: unknown }
-      | undefined
-    const raw = delta?.reasoning_content ?? delta?.reasoning
-    if (typeof raw === 'string' && raw.length > 0) {
-      return { text: raw }
+  protected override mapOptionsToRequest(
+    options: TextOptions<TProviderOptions>,
+  ): Omit<ResponseCreateParams, 'stream'> {
+    const { tools: _baseTools, ...request } = super.mapOptionsToRequest({
+      ...options,
+      tools: undefined,
+    })
+    void _baseTools
+
+    if (this.model === 'grok-build-0.1' && request.reasoning !== undefined) {
+      throw new Error(
+        'grok-build-0.1 does not support reasoning modelOptions; omit reasoning for this model.',
+      )
     }
-    return 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.
-   */
-  override supportsCombinedToolsAndSchema(): boolean {
-    return GROK_COMBINED_TOOLS_AND_SCHEMA_MODELS.has(this.model)
+    const tools = options.tools
+      ? convertToolsToProviderFormat(options.tools)
+      : undefined
+
+    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: tools as ResponseCreateParams['tools'] }),
+    }
   }
 }
 
@@ -98,15 +98,15 @@ export class GrokTextAdapter<
  * 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 function createGrokText<
@@ -127,7 +127,7 @@ export function createGrokText<
  * - `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
@@ -135,7 +135,7 @@ export function createGrokText<
  * @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,