@tanstack/ai-grok 0.6.7 → 0.7.0

package/src/adapters/image.ts

@@ -49,29 +49,42 @@ export class GrokImageAdapter<
   private client: OpenAI_SDK
 
   constructor(config: GrokImageConfig, model: TModel) {
-    super({}, model)
+    super(model, {})
     this.client = createGrokClient(config)
   }
 
   async generateImages(
     options: ImageGenerationOptions<GrokImageProviderOptions>,
   ): Promise<ImageGenerationResult> {
-    const { model, prompt, numberOfImages, size } = options
+    const { model, prompt, numberOfImages, size, logger } = options
 
-    // Validate inputs
-    validatePrompt({ prompt, model })
-    validateImageSize(model, size)
-    validateNumberOfImages(model, numberOfImages)
+    logger.request(`activity=generateImage provider=grok model=${this.model}`, {
+      provider: 'grok',
+      model: this.model,
+    })
 
-    // Build request based on model type
-    const request = this.buildRequest(options)
+    try {
+      // Validate inputs
+      validatePrompt({ prompt, model })
+      validateImageSize(model, size)
+      validateNumberOfImages(model, numberOfImages)
 
-    const response = await this.client.images.generate({
-      ...request,
-      stream: false,
-    })
+      // Build request based on model type
+      const request = this.buildRequest(options)
+
+      const response = await this.client.images.generate({
+        ...request,
+        stream: false,
+      })
 
-    return this.transformResponse(model, response)
+      return this.transformResponse(model, response)
+    } catch (error) {
+      logger.errors('grok.generateImage fatal', {
+        error,
+        source: 'grok.generateImage',
+      })
+      throw error
+    }
   }
 
   private buildRequest(
@@ -79,12 +92,14 @@ export class GrokImageAdapter<
   ): OpenAI_SDK.Images.ImageGenerateParams {
     const { model, prompt, numberOfImages, size, modelOptions } = options
 
+    // Spread modelOptions FIRST so explicit args (model, prompt, n, size) win
+    // and user-supplied modelOptions cannot silently override them.
     return {
+      ...modelOptions,
       model,
       prompt,
       n: numberOfImages ?? 1,
       size: size as OpenAI_SDK.Images.ImageGenerateParams['size'],
-      ...modelOptions,
     }
   }
 
@@ -92,11 +107,18 @@ export class GrokImageAdapter<
     model: string,
     response: OpenAI_SDK.Images.ImagesResponse,
   ): ImageGenerationResult {
-    const images: Array<GeneratedImage> = (response.data ?? []).map((item) => ({
-      b64Json: item.b64_json,
-      url: item.url,
-      revisedPrompt: item.revised_prompt,
-    }))
+    const images: Array<GeneratedImage> = (response.data ?? []).flatMap(
+      (item): Array<GeneratedImage> => {
+        const revisedPrompt = item.revised_prompt
+        if (item.b64_json) {
+          return [{ b64Json: item.b64_json, revisedPrompt }]
+        }
+        if (item.url) {
+          return [{ url: item.url, revisedPrompt }]
+        }
+        return []
+      },
+    )
 
     return {
       id: generateId(this.name),

package/src/adapters/summarize.ts

@@ -47,36 +47,51 @@ export class GrokSummarizeAdapter<
   }
 
   async summarize(options: SummarizationOptions): Promise<SummarizationResult> {
+    const { logger } = options
     const systemPrompt = this.buildSummarizationPrompt(options)
 
+    logger.request(`activity=summarize provider=grok`, {
+      provider: 'grok',
+      model: options.model,
+    })
+
     // Use the text adapter's streaming and collect the result
     let summary = ''
     const id = ''
     let model = options.model
     let usage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 }
 
-    for await (const chunk of this.textAdapter.chatStream({
-      model: options.model,
-      messages: [{ role: 'user', content: options.text }],
-      systemPrompts: [systemPrompt],
-      maxTokens: options.maxLength,
-      temperature: 0.3,
-    })) {
-      // AG-UI TEXT_MESSAGE_CONTENT event
-      if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
-        if (chunk.content) {
-          summary = chunk.content
-        } else {
-          summary += chunk.delta
+    try {
+      for await (const chunk of this.textAdapter.chatStream({
+        model: options.model,
+        messages: [{ role: 'user', content: options.text }],
+        systemPrompts: [systemPrompt],
+        maxTokens: options.maxLength,
+        temperature: 0.3,
+        logger,
+      })) {
+        // AG-UI TEXT_MESSAGE_CONTENT event
+        if (chunk.type === 'TEXT_MESSAGE_CONTENT') {
+          if (chunk.content) {
+            summary = chunk.content
+          } else {
+            summary += chunk.delta
+          }
+          model = chunk.model || model
         }
-        model = chunk.model || model
-      }
-      // AG-UI RUN_FINISHED event
-      if (chunk.type === 'RUN_FINISHED') {
-        if (chunk.usage) {
-          usage = chunk.usage
+        // AG-UI RUN_FINISHED event
+        if (chunk.type === 'RUN_FINISHED') {
+          if (chunk.usage) {
+            usage = chunk.usage
+          }
         }
       }
+    } catch (error) {
+      logger.errors('grok.summarize fatal', {
+        error,
+        source: 'grok.summarize',
+      })
+      throw error
     }
 
     return { id, model, summary, usage }
@@ -85,16 +100,32 @@ export class GrokSummarizeAdapter<
   async *summarizeStream(
     options: SummarizationOptions,
   ): AsyncIterable<StreamChunk> {
+    const { logger } = options
     const systemPrompt = this.buildSummarizationPrompt(options)
 
-    // Delegate directly to the text adapter's streaming
-    yield* this.textAdapter.chatStream({
+    logger.request(`activity=summarize provider=grok`, {
+      provider: 'grok',
       model: options.model,
-      messages: [{ role: 'user', content: options.text }],
-      systemPrompts: [systemPrompt],
-      maxTokens: options.maxLength,
-      temperature: 0.3,
+      stream: true,
     })
+
+    try {
+      // Delegate directly to the text adapter's streaming
+      yield* this.textAdapter.chatStream({
+        model: options.model,
+        messages: [{ role: 'user', content: options.text }],
+        systemPrompts: [systemPrompt],
+        maxTokens: options.maxLength,
+        temperature: 0.3,
+        logger,
+      })
+    } catch (error) {
+      logger.errors('grok.summarize fatal', {
+        error,
+        source: 'grok.summarize',
+      })
+      throw error
+    }
   }
 
   private buildSummarizationPrompt(options: SummarizationOptions): string {

package/src/adapters/text.ts

@@ -18,6 +18,7 @@ import type {
   StructuredOutputOptions,
   StructuredOutputResult,
 } from '@tanstack/ai/adapters'
+import type { InternalLogger } from '@tanstack/ai/adapter-internals'
 import type OpenAI_SDK from 'openai'
 import type {
   ContentPart,
@@ -91,6 +92,7 @@ export class GrokTextAdapter<
   ): AsyncIterable<StreamChunk> {
     const requestParams = this.mapTextOptionsToGrok(options)
     const timestamp = Date.now()
+    const { logger } = options
 
     // AG-UI lifecycle tracking (mutable state object for ESLint compatibility)
     const aguiState = {
@@ -102,12 +104,16 @@ export class GrokTextAdapter<
     }
 
     try {
+      logger.request(
+        `activity=chat provider=grok model=${this.model} messages=${options.messages.length} tools=${options.tools?.length ?? 0} stream=true`,
+        { provider: 'grok', model: this.model },
+      )
       const stream = await this.client.chat.completions.create({
         ...requestParams,
         stream: true,
       })
 
-      yield* this.processGrokStreamChunks(stream, options, aguiState)
+      yield* this.processGrokStreamChunks(stream, options, aguiState, logger)
     } catch (error: unknown) {
       const err = error as Error & { code?: string }
 
@@ -137,10 +143,10 @@ export class GrokTextAdapter<
         },
       })
 
-      console.error('>>> chatStream: Fatal error during response creation <<<')
-      console.error('>>> Error message:', err.message)
-      console.error('>>> Error stack:', err.stack)
-      console.error('>>> Full error:', err)
+      logger.errors('grok.chatStream fatal', {
+        error,
+        source: 'grok.chatStream',
+      })
     }
   }
 
@@ -161,6 +167,7 @@ export class GrokTextAdapter<
   ): Promise<StructuredOutputResult<unknown>> {
     const { chatOptions, outputSchema } = options
     const requestParams = this.mapTextOptionsToGrok(chatOptions)
+    const { logger } = chatOptions
 
     // Apply Grok-specific transformations for structured output compatibility
     const jsonSchema = makeGrokStructuredOutputCompatible(
@@ -169,6 +176,10 @@ export class GrokTextAdapter<
     )
 
     try {
+      logger.request(
+        `activity=chat provider=grok model=${this.model} messages=${chatOptions.messages.length} tools=${chatOptions.tools?.length ?? 0} stream=false`,
+        { provider: 'grok', model: this.model },
+      )
       const response = await this.client.chat.completions.create({
         ...requestParams,
         stream: false,
@@ -204,9 +215,10 @@ export class GrokTextAdapter<
         rawText,
       }
     } catch (error: unknown) {
-      const err = error as Error
-      console.error('>>> structuredOutput: Error during response creation <<<')
-      console.error('>>> Error message:', err.message)
+      logger.errors('grok.structuredOutput fatal', {
+        error,
+        source: 'grok.structuredOutput',
+      })
       throw error
     }
   }
@@ -221,6 +233,7 @@ export class GrokTextAdapter<
       timestamp: number
       hasEmittedRunStarted: boolean
     },
+    logger: InternalLogger,
   ): AsyncIterable<StreamChunk> {
     let accumulatedContent = ''
     const timestamp = aguiState.timestamp
@@ -239,6 +252,7 @@ export class GrokTextAdapter<
 
     try {
       for await (const chunk of stream) {
+        logger.provider(`provider=grok`, { chunk })
         const choice = chunk.choices[0]
 
         if (!choice) continue
@@ -408,7 +422,10 @@ export class GrokTextAdapter<
       }
     } catch (error: unknown) {
       const err = error as Error & { code?: string }
-      console.log('[Grok Adapter] Stream ended with error:', err.message)
+      logger.errors('grok stream ended with error', {
+        error,
+        source: 'grok.processGrokStreamChunks',
+      })
 
       // Emit AG-UI RUN_ERROR
       yield asChunk({

package/src/adapters/transcription.ts

@@ -0,0 +1,233 @@
+import { BaseTranscriptionAdapter } from '@tanstack/ai/adapters'
+import { generateId, getGrokApiKeyFromEnv, toAudioFile } from '../utils'
+import type {
+  TranscriptionOptions,
+  TranscriptionResult,
+  TranscriptionWord,
+} from '@tanstack/ai'
+import type { GrokTranscriptionModel } from '../model-meta'
+import type { GrokTranscriptionProviderOptions } from '../audio/transcription-provider-options'
+
+/**
+ * Grok-specific extension of `TranscriptionWord` that surfaces the extra
+ * fields xAI returns when diarization / confidence are enabled. The base
+ * cross-provider `TranscriptionWord` contract doesn't include these, so
+ * callers who know they're using Grok can narrow with:
+ *
+ * ```ts
+ * const words = result.words as Array<GrokTranscriptionWord> | undefined
+ * ```
+ */
+export interface GrokTranscriptionWord extends TranscriptionWord {
+  /** Model confidence for the word, when xAI returns one. */
+  confidence?: number
+  /** Speaker index, populated when `modelOptions.diarize === true`. */
+  speaker?: number
+}
+
+const DEFAULT_GROK_BASE_URL = 'https://api.x.ai/v1'
+
+/**
+ * Configuration for the Grok transcription adapter.
+ *
+ * Uses direct `fetch` rather than the OpenAI SDK because xAI's `/v1/stt`
+ * endpoint is not OpenAI-compatible.
+ */
+export interface GrokTranscriptionConfig {
+  apiKey: string
+  baseURL?: string
+  /** Additional headers to merge into every request (e.g., test IDs). */
+  defaultHeaders?: Record<string, string>
+}
+
+/**
+ * xAI STT response shape from `POST /v1/stt`.
+ * Grok returns word-level timestamps only; no segment array.
+ */
+interface GrokSTTWord {
+  text: string
+  start: number
+  end: number
+  confidence?: number
+  speaker?: number
+}
+
+interface GrokSTTResponse {
+  text: string
+  language?: string
+  duration?: number
+  words?: Array<GrokSTTWord>
+  channels?: Array<unknown>
+}
+
+/**
+ * Grok Speech-to-Text Adapter.
+ *
+ * Talks to `POST {baseURL}/stt` per
+ * https://docs.x.ai/developers/rest-api-reference/inference/voice
+ */
+export class GrokTranscriptionAdapter<
+  TModel extends GrokTranscriptionModel,
+> extends BaseTranscriptionAdapter<TModel, GrokTranscriptionProviderOptions> {
+  readonly name = 'grok' as const
+
+  private readonly apiKey: string
+  private readonly baseURL: string
+  private readonly defaultHeaders: Record<string, string>
+
+  constructor(config: GrokTranscriptionConfig, model: TModel) {
+    super(model, config)
+    this.apiKey = config.apiKey
+    this.baseURL = (config.baseURL ?? DEFAULT_GROK_BASE_URL).replace(/\/+$/, '')
+    this.defaultHeaders = config.defaultHeaders ?? {}
+  }
+
+  async transcribe(
+    options: TranscriptionOptions<GrokTranscriptionProviderOptions>,
+  ): Promise<TranscriptionResult> {
+    const { logger } = options
+    const { model, audio, language, modelOptions } = options
+
+    logger.request(
+      `activity=generateTranscription provider=grok model=${model}`,
+      { provider: 'grok', model },
+    )
+
+    const file = toAudioFile(audio, modelOptions?.audio_format)
+    const form = buildTranscriptionFormData({ file, language, modelOptions })
+
+    try {
+      const response = await fetch(`${this.baseURL}/stt`, {
+        method: 'POST',
+        headers: {
+          // `defaultHeaders` first so Authorization always wins.
+          ...this.defaultHeaders,
+          Authorization: `Bearer ${this.apiKey}`,
+        },
+        body: form,
+      })
+
+      if (!response.ok) {
+        const errorText = await response.text()
+        throw new Error(
+          `Grok transcription request failed: ${response.status} ${errorText}`,
+        )
+      }
+
+      const data = (await response.json()) as GrokSTTResponse
+
+      const words: Array<TranscriptionWord> | undefined = data.words?.map(
+        (w) => {
+          // Construct a GrokTranscriptionWord so that `confidence` and
+          // `speaker` (when xAI returns them under `diarize` / confidence
+          // mode) are preserved on the result. The returned array is typed
+          // as `Array<TranscriptionWord>` per the cross-provider contract;
+          // callers who want the extras narrow via `as Array<GrokTranscriptionWord>`.
+          const tw: GrokTranscriptionWord = {
+            word: w.text,
+            start: w.start,
+            end: w.end,
+          }
+          if (w.confidence !== undefined) tw.confidence = w.confidence
+          if (w.speaker !== undefined) tw.speaker = w.speaker
+          return tw
+        },
+      )
+
+      return {
+        id: generateId(this.name),
+        model,
+        text: data.text,
+        language: data.language ?? language,
+        duration: data.duration,
+        words,
+      }
+    } catch (error) {
+      logger.errors('grok.transcribe fatal', {
+        error,
+        source: 'grok.transcribe',
+      })
+      throw error
+    }
+  }
+}
+
+/**
+ * Build the multipart/form-data body for `POST /v1/stt`, coercing SDK-level
+ * model options into xAI's wire format (booleans as `'true'`/`'false'`
+ * strings, numeric fields stringified, etc.).
+ *
+ * Wire-field mapping:
+ *   - `modelOptions.inverse_text_normalization` → `format` (xAI's chosen
+ *     wire-field name for the ITN boolean; the SDK surfaces it under the
+ *     clearer `inverse_text_normalization` key).
+ *   - `modelOptions.audio_format`, `sample_rate`, `multichannel`, `channels`,
+ *     `diarize` map to same-named form fields.
+ */
+export function buildTranscriptionFormData(options: {
+  file: File
+  language: string | undefined
+  modelOptions: GrokTranscriptionProviderOptions | undefined
+}): FormData {
+  const { file, language, modelOptions } = options
+  const form = new FormData()
+  form.set('file', file)
+  if (language) form.set('language', language)
+  if (modelOptions?.audio_format !== undefined) {
+    form.set('audio_format', modelOptions.audio_format)
+  }
+  if (modelOptions?.sample_rate !== undefined) {
+    form.set('sample_rate', String(modelOptions.sample_rate))
+  }
+  if (modelOptions?.inverse_text_normalization !== undefined) {
+    form.set(
+      'format',
+      modelOptions.inverse_text_normalization ? 'true' : 'false',
+    )
+  }
+  if (modelOptions?.multichannel !== undefined) {
+    form.set('multichannel', modelOptions.multichannel ? 'true' : 'false')
+  }
+  if (modelOptions?.channels !== undefined) {
+    form.set('channels', String(modelOptions.channels))
+  }
+  if (modelOptions?.diarize !== undefined) {
+    form.set('diarize', modelOptions.diarize ? 'true' : 'false')
+  }
+  return form
+}
+
+/**
+ * Creates a Grok transcription adapter with an explicit API key.
+ *
+ * @example
+ * ```typescript
+ * const adapter = createGrokTranscription('grok-stt', 'xai-...')
+ * const result = await generateTranscription({
+ *   adapter,
+ *   audio: audioFile,
+ *   language: 'en',
+ * })
+ * ```
+ */
+export function createGrokTranscription<TModel extends GrokTranscriptionModel>(
+  model: TModel,
+  apiKey: string,
+  config?: Omit<GrokTranscriptionConfig, 'apiKey'>,
+): GrokTranscriptionAdapter<TModel> {
+  return new GrokTranscriptionAdapter({ apiKey, ...config }, model)
+}
+
+/**
+ * Creates a Grok transcription adapter, reading the API key from
+ * `XAI_API_KEY` in the environment.
+ *
+ * @throws Error if `XAI_API_KEY` is not set.
+ */
+export function grokTranscription<TModel extends GrokTranscriptionModel>(
+  model: TModel,
+  config?: Omit<GrokTranscriptionConfig, 'apiKey'>,
+): GrokTranscriptionAdapter<TModel> {
+  const apiKey = getGrokApiKeyFromEnv()
+  return createGrokTranscription(model, apiKey, config)
+}