@tanstack/ai-grok 0.12.4 → 0.14.0

package/src/tools/index.ts

@@ -1,5 +1,212 @@
-export {
-  type ChatCompletionFunctionTool as FunctionTool,
-  convertFunctionToolToChatCompletionsFormat as convertFunctionToolToAdapterFormat,
-  convertToolsToChatCompletionsFormat as convertToolsToProviderFormat,
-} from '@tanstack/openai-base'
+import { brandProviderTool } from '@tanstack/ai'
+import { convertFunctionToolToResponsesFormat } from '@tanstack/openai-base'
+import type { ProviderTool, Tool } from '@tanstack/ai'
+import type { ResponsesFunctionTool } from '@tanstack/openai-base'
+import type { GrokProviderToolKind } from '../model-meta'
+
+export type FunctionTool = ResponsesFunctionTool
+
+export { convertFunctionToolToResponsesFormat as convertFunctionToolToAdapterFormat }
+
+export type GrokProviderTool<TKind extends GrokProviderToolKind> = ProviderTool<
+  'grok',
+  TKind
+>
+
+type GrokToolKindMarker<TKind extends GrokProviderToolKind> = `grok.${TKind}`
+
+export interface GrokWebSearchToolConfig {
+  type: 'web_search'
+  filters?: {
+    allowed_domains?: Array<string>
+    excluded_domains?: Array<string>
+  }
+  enable_image_understanding?: boolean
+  enable_image_search?: boolean
+}
+
+export interface GrokXSearchToolConfig {
+  type: 'x_search'
+  allowed_x_handles?: Array<string>
+  excluded_x_handles?: Array<string>
+  from_date?: string
+  to_date?: string
+  enable_image_understanding?: boolean
+  enable_video_understanding?: boolean
+}
+
+export interface GrokFileSearchToolConfig {
+  type: 'file_search'
+  vector_store_ids: Array<string>
+  max_num_results?: number
+}
+
+export interface GrokMCPToolConfig {
+  type: 'mcp'
+  server_label: string
+  server_url: string
+  allowed_tools?: Array<string>
+  server_description?: string
+  authorization?: string
+  headers?: Record<string, string>
+}
+
+export type GrokServerTool =
+  | GrokWebSearchToolConfig
+  | GrokXSearchToolConfig
+  | GrokFileSearchToolConfig
+  | GrokMCPToolConfig
+
+type GrokProviderToolMetadata<TKind extends GrokProviderToolKind> = Extract<
+  GrokServerTool,
+  { type: TKind }
+> & {
+  __kind: GrokToolKindMarker<TKind>
+}
+
+export type GrokResponsesTool = GrokServerTool | ResponsesFunctionTool
+
+function providerTool<TKind extends GrokProviderToolKind>(
+  kind: TKind,
+  description: string,
+  metadata: Extract<GrokServerTool, { type: TKind }>,
+): GrokProviderTool<TKind> {
+  return brandProviderTool<GrokProviderTool<TKind>>({
+    name: kind,
+    description,
+    metadata: {
+      __kind: `grok.${kind}`,
+      ...metadata,
+    },
+  })
+}
+
+export function grokWebSearchTool(
+  config: Omit<GrokWebSearchToolConfig, 'type'> = {},
+): GrokProviderTool<'web_search'> {
+  if (
+    config.filters?.allowed_domains !== undefined &&
+    config.filters.excluded_domains !== undefined
+  ) {
+    throw new Error(
+      'allowed_domains and excluded_domains cannot both be provided.',
+    )
+  }
+  if (
+    config.filters?.allowed_domains !== undefined &&
+    config.filters.allowed_domains.length > 5
+  ) {
+    throw new Error('allowed_domains supports at most 5 domains.')
+  }
+  if (
+    config.filters?.excluded_domains !== undefined &&
+    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,
+  })
+}
+
+export function grokXSearchTool(
+  config: Omit<GrokXSearchToolConfig, 'type'> = {},
+): GrokProviderTool<'x_search'> {
+  if (
+    config.allowed_x_handles !== undefined &&
+    config.excluded_x_handles !== undefined
+  ) {
+    throw new Error(
+      'allowed_x_handles and excluded_x_handles cannot both be provided.',
+    )
+  }
+  if (
+    config.allowed_x_handles !== undefined &&
+    config.allowed_x_handles.length > 20
+  ) {
+    throw new Error('allowed_x_handles supports at most 20 handles.')
+  }
+  if (
+    config.excluded_x_handles !== undefined &&
+    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,
+  })
+}
+
+export function grokFileSearchTool(
+  config: Omit<GrokFileSearchToolConfig, 'type'>,
+): GrokProviderTool<'file_search'> {
+  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 !== undefined) {
+    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,
+  })
+}
+
+export function grokMCPTool(
+  config: Omit<GrokMCPToolConfig, 'type'>,
+): GrokProviderTool<'mcp'> {
+  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: Tool): GrokProviderToolKind | undefined {
+  const kind = (tool.metadata as { __kind?: unknown } | undefined)?.__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 undefined
+  }
+}
+
+function convertGrokProviderToolToAdapterFormat(
+  tool: Tool,
+  kind: GrokProviderToolKind,
+): GrokServerTool {
+  const metadata = tool.metadata as GrokProviderToolMetadata<typeof kind>
+  if (metadata.type !== kind) {
+    throw new Error(
+      `convertGrokProviderToolToAdapterFormat: tool "${tool.name}" has mismatched Grok tool metadata.`,
+    )
+  }
+  const { __kind: _kind, ...toolConfig } = metadata
+  void _kind
+  return toolConfig
+}
+
+export function convertToolsToProviderFormat(
+  tools: Array<Tool>,
+): Array<GrokResponsesTool> {
+  return tools.map((tool) => {
+    const grokProviderToolKind = getGrokProviderToolKind(tool)
+    if (grokProviderToolKind) {
+      return convertGrokProviderToolToAdapterFormat(tool, grokProviderToolKind)
+    }
+    return convertFunctionToolToResponsesFormat(tool)
+  })
+}

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

@@ -0,0 +1,241 @@
+/**
+ * Grok Video Generation Provider Options (xAI Imagine API)
+ *
+ * Based on https://docs.x.ai/docs/guides/video-generations
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+
+import type { DurationOptions } from '@tanstack/ai/adapters'
+import type { GrokVideoModel } from '../model-meta'
+
+/**
+ * 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}`
+
+const GROK_VIDEO_ASPECT_RATIOS: ReadonlyArray<string> = [
+  '1:1',
+  '16:9',
+  '9:16',
+  '4:3',
+  '3:4',
+  '3:2',
+  '2:3',
+]
+
+const GROK_VIDEO_RESOLUTIONS: ReadonlyArray<string> = ['480p', '720p', '1080p']
+
+/**
+ * Video duration limits enforced by the Imagine API (seconds).
+ */
+export const GROK_VIDEO_MIN_DURATION = 1
+export 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 function parseGrokVideoSize(
+  size: string,
+): { aspectRatio: string; resolution?: string } | undefined {
+  const match = size.match(/^([\d.]+:[\d.]+)(?:_(.+))?$/)
+  const [, aspectRatio, resolution] = match ?? []
+  if (aspectRatio === undefined) return undefined
+  return { aspectRatio, ...(resolution !== undefined && { resolution }) }
+}
+
+/**
+ * Validate the `size` template for a given grok video model.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export function validateVideoSize(
+  model: string,
+  size?: string,
+): asserts size is GrokVideoSize | undefined {
+  if (size === undefined) 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 !== undefined &&
+    !GROK_VIDEO_RESOLUTIONS.includes(parsed.resolution)
+  ) {
+    throw new Error(
+      `Resolution "${parsed.resolution}" is not supported by model "${model}". ` +
+        `Supported resolutions: ${GROK_VIDEO_RESOLUTIONS.join(', ')}`,
+    )
+  }
+}
+
+/**
+ * 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 const GROK_VIDEO_DURATIONS: {
+  readonly [TModel in GrokVideoModel]: DurationOptions<
+    GrokVideoModelDurationByName[TModel]
+  >
+} = {
+  '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',
+  },
+}
+
+/**
+ * Look up the duration options for a grok video model.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export function getGrokVideoDurationOptions<TModel extends GrokVideoModel>(
+  model: TModel,
+): DurationOptions<GrokVideoModelDurationByName[TModel]> {
+  return GROK_VIDEO_DURATIONS[model]
+}
+
+/**
+ * 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']
+}
+
+/**
+ * Models that only support image-to-video — a starting-frame image is
+ * required and text-to-video is rejected by the Imagine API. Used by the
+ * adapter to fail fast with a clear message instead of surfacing the raw
+ * "Text-to-video is not supported for this model" 400.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+const GROK_VIDEO_IMAGE_TO_VIDEO_ONLY: ReadonlySet<string> = new Set([
+  'grok-imagine-video-1.5',
+])
+
+/**
+ * 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 function isImageToVideoOnlyModel(model: string): boolean {
+  return GROK_VIDEO_IMAGE_TO_VIDEO_ONLY.has(model)
+}