@tanstack/ai-groq 0.1.11 → 0.2.1

package/src/adapters/text.ts

@@ -1,72 +1,44 @@
-import { BaseTextAdapter } from '@tanstack/ai/adapters'
-import { validateTextProviderOptions } from '../text/text-provider-options'
-import { convertToolsToProviderFormat } from '../tools'
-import {
-  createGroqClient,
-  generateId,
-  getGroqApiKeyFromEnv,
-  makeGroqStructuredOutputCompatible,
-  transformNullsToUndefined,
-} from '../utils'
+import OpenAI from 'openai'
+import { OpenAIBaseChatCompletionsTextAdapter } from '@tanstack/openai-base'
+import { getGroqApiKeyFromEnv, withGroqDefaults } from '../utils/client'
+import { makeGroqStructuredOutputCompatible } from '../utils/schema-converter'
+import type { Modality, TextOptions } from '@tanstack/ai'
 import type {
   GROQ_CHAT_MODELS,
   GroqChatModelToolCapabilitiesByName,
   ResolveInputModalities,
   ResolveProviderOptions,
 } from '../model-meta'
-import type {
-  StructuredOutputOptions,
-  StructuredOutputResult,
-} from '@tanstack/ai/adapters'
-import type { InternalLogger } from '@tanstack/ai/adapter-internals'
-import type GROQ_SDK from 'groq-sdk'
-import type { ChatCompletionCreateParamsStreaming } from 'groq-sdk/resources/chat/completions'
-import type {
-  ContentPart,
-  Modality,
-  ModelMessage,
-  StreamChunk,
-  TextOptions,
-} from '@tanstack/ai'
-import type {
-  ExternalTextProviderOptions,
-  InternalTextProviderOptions,
-} from '../text/text-provider-options'
-import type {
-  ChatCompletionContentPart,
-  ChatCompletionMessageParam,
-  GroqImageMetadata,
-  GroqMessageMetadataByModality,
-} from '../message-types'
+import type { GroqMessageMetadataByModality } from '../message-types'
 import type { GroqClientConfig } from '../utils'
 
-type GroqTextProviderOptions = ExternalTextProviderOptions
-
 type ResolveToolCapabilities<TModel extends string> =
   TModel extends keyof GroqChatModelToolCapabilitiesByName
     ? NonNullable<GroqChatModelToolCapabilitiesByName[TModel]>
     : readonly []
 
-/** Cast an event object to StreamChunk. Adapters construct events with string
- *  literal types which are structurally compatible with the EventType enum. */
-const asChunk = (chunk: Record<string, unknown>) =>
-  chunk as unknown as StreamChunk
-
 /**
  * Configuration for Groq text adapter
  */
 export interface GroqTextConfig extends GroqClientConfig {}
 
 /**
- * Alias for TextProviderOptions for external use
+ * Re-export of the public provider options type
  */
 export type { ExternalTextProviderOptions as GroqTextProviderOptions } from '../text/text-provider-options'
 
 /**
  * Groq Text (Chat) Adapter
  *
- * Tree-shakeable adapter for Groq chat/text completion functionality.
- * Uses the Groq SDK which provides an OpenAI-compatible Chat Completions API.
+ * Tree-shakeable adapter for Groq chat/text completion. Groq exposes an
+ * OpenAI-compatible Chat Completions endpoint at `/openai/v1`, so we drive
+ * it with the OpenAI SDK via a `baseURL` override (the same pattern as
+ * `ai-grok`).
+ *
+ * Quirk: when usage is present on a stream, Groq historically delivered it
+ * under `chunk.x_groq.usage` rather than `chunk.usage`. The override below
+ * promotes it to the standard location so the base's RUN_FINISHED usage
+ * accounting works unchanged.
  */
 export class GroqTextAdapter<
   TModel extends (typeof GROQ_CHAT_MODELS)[number],
@@ -75,7 +47,7 @@ export class GroqTextAdapter<
     ResolveInputModalities<TModel>,
   TToolCapabilities extends ReadonlyArray<string> =
     ResolveToolCapabilities<TModel>,
-> extends BaseTextAdapter<
+> extends OpenAIBaseChatCompletionsTextAdapter<
   TModel,
   TProviderOptions,
   TInputModalities,
@@ -85,526 +57,81 @@ export class GroqTextAdapter<
   readonly kind = 'text' as const
   readonly name = 'groq' as const
 
-  private client: GROQ_SDK
-
   constructor(config: GroqTextConfig, model: TModel) {
-    super({}, model)
-    this.client = createGroqClient(config)
-  }
-
-  async *chatStream(
-    options: TextOptions<GroqTextProviderOptions>,
-  ): AsyncIterable<StreamChunk> {
-    const requestParams = this.mapTextOptionsToGroq(options)
-    const timestamp = Date.now()
-    const { logger } = options
-
-    const aguiState = {
-      runId: options.runId ?? generateId(this.name),
-      threadId: options.threadId ?? generateId(this.name),
-      messageId: generateId(this.name),
-      timestamp,
-      hasEmittedRunStarted: false,
-    }
-
-    try {
-      logger.request(
-        `activity=chat provider=groq model=${this.model} messages=${options.messages.length} tools=${options.tools?.length ?? 0} stream=true`,
-        { provider: 'groq', model: this.model },
-      )
-      const stream = await this.client.chat.completions.create({
-        ...requestParams,
-        stream: true,
-      })
-
-      yield* this.processGroqStreamChunks(stream, options, aguiState, logger)
-    } catch (error: unknown) {
-      const err = error as Error & { code?: string }
-
-      if (!aguiState.hasEmittedRunStarted) {
-        aguiState.hasEmittedRunStarted = true
-        yield asChunk({
-          type: 'RUN_STARTED',
-          runId: aguiState.runId,
-          threadId: aguiState.threadId,
-          model: options.model,
-          timestamp,
-        })
-      }
-
-      yield asChunk({
-        type: 'RUN_ERROR',
-        runId: aguiState.runId,
-        model: options.model,
-        timestamp,
-        message: err.message || 'Unknown error',
-        code: err.code,
-        error: {
-          message: err.message || 'Unknown error',
-          code: err.code,
-        },
-      })
-
-      logger.errors('groq.chatStream fatal', {
-        error,
-        source: 'groq.chatStream',
-      })
-    }
+    super(model, 'groq', new OpenAI(withGroqDefaults(config)))
   }
 
-  /**
-   * Generate structured output using Groq's JSON Schema response format.
-   * Uses stream: false to get the complete response in one call.
-   *
-   * Groq has strict requirements for structured output:
-   * - All properties must be in the `required` array
-   * - Optional fields should have null added to their type union
-   * - additionalProperties must be false for all objects
-   *
-   * The outputSchema is already JSON Schema (converted in the ai layer).
-   * We apply Groq-specific transformations for structured output compatibility.
-   */
-  async structuredOutput(
-    options: StructuredOutputOptions<GroqTextProviderOptions>,
-  ): Promise<StructuredOutputResult<unknown>> {
-    const { chatOptions, outputSchema } = options
-    const requestParams = this.mapTextOptionsToGroq(chatOptions)
-    const { logger } = chatOptions
-
-    const jsonSchema = makeGroqStructuredOutputCompatible(
-      outputSchema,
-      outputSchema.required || [],
-    )
-
-    try {
-      logger.request(
-        `activity=chat provider=groq model=${this.model} messages=${chatOptions.messages.length} tools=${chatOptions.tools?.length ?? 0} stream=false`,
-        { provider: 'groq', model: this.model },
-      )
-      const response = await this.client.chat.completions.create({
-        ...requestParams,
-        stream: false,
-        response_format: {
-          type: 'json_schema',
-          json_schema: {
-            name: 'structured_output',
-            schema: jsonSchema,
-            strict: true,
-          },
-        },
-      })
-
-      const rawText = response.choices[0]?.message.content || ''
-
-      let parsed: unknown
-      try {
-        parsed = JSON.parse(rawText)
-      } catch {
-        throw new Error(
-          `Failed to parse structured output as JSON. Content: ${rawText.slice(0, 200)}${rawText.length > 200 ? '...' : ''}`,
-        )
-      }
-
-      const transformed = transformNullsToUndefined(parsed)
-
-      return {
-        data: transformed,
-        rawText,
-      }
-    } catch (error: unknown) {
-      logger.errors('groq.structuredOutput fatal', {
-        error,
-        source: 'groq.structuredOutput',
-      })
-      throw error
-    }
+  protected override makeStructuredOutputCompatible(
+    schema: Record<string, any>,
+    originalRequired?: Array<string>,
+  ): Record<string, any> {
+    return makeGroqStructuredOutputCompatible(schema, originalRequired)
   }
 
-  /**
-   * Processes streaming chunks from the Groq API and yields AG-UI stream events.
-   * Handles text content deltas, tool call assembly, and lifecycle events.
-   */
-  private async *processGroqStreamChunks(
-    stream: AsyncIterable<GROQ_SDK.Chat.Completions.ChatCompletionChunk>,
+  protected override async *processStreamChunks(
+    stream: AsyncIterable<OpenAI.Chat.Completions.ChatCompletionChunk>,
     options: TextOptions,
     aguiState: {
       runId: string
       threadId: string
       messageId: string
-      timestamp: number
       hasEmittedRunStarted: boolean
     },
-    logger: InternalLogger,
-  ): AsyncIterable<StreamChunk> {
-    let accumulatedContent = ''
-    const timestamp = aguiState.timestamp
-    let hasEmittedTextMessageStart = false
-
-    const toolCallsInProgress = new Map<
-      number,
-      {
-        id: string
-        name: string
-        arguments: string
-        started: boolean
-      }
-    >()
-
-    try {
-      for await (const chunk of stream) {
-        logger.provider(`provider=groq`, { chunk })
-        const choice = chunk.choices[0]
-
-        if (!choice) continue
-
-        if (!aguiState.hasEmittedRunStarted) {
-          aguiState.hasEmittedRunStarted = true
-          yield asChunk({
-            type: 'RUN_STARTED',
-            runId: aguiState.runId,
-            threadId: aguiState.threadId,
-            model: chunk.model || options.model,
-            timestamp,
-          })
-        }
-
-        const delta = choice.delta
-        const deltaContent = delta.content
-        const deltaToolCalls = delta.tool_calls
-
-        if (deltaContent) {
-          if (!hasEmittedTextMessageStart) {
-            hasEmittedTextMessageStart = true
-            yield asChunk({
-              type: 'TEXT_MESSAGE_START',
-              messageId: aguiState.messageId,
-              model: chunk.model || options.model,
-              timestamp,
-              role: 'assistant',
-            })
-          }
-
-          accumulatedContent += deltaContent
-
-          yield asChunk({
-            type: 'TEXT_MESSAGE_CONTENT',
-            messageId: aguiState.messageId,
-            model: chunk.model || options.model,
-            timestamp,
-            delta: deltaContent,
-            content: accumulatedContent,
-          })
-        }
-
-        if (deltaToolCalls) {
-          for (const toolCallDelta of deltaToolCalls) {
-            const index = toolCallDelta.index
-
-            if (!toolCallsInProgress.has(index)) {
-              toolCallsInProgress.set(index, {
-                id: toolCallDelta.id || '',
-                name: toolCallDelta.function?.name || '',
-                arguments: '',
-                started: false,
-              })
-            }
-
-            const toolCall = toolCallsInProgress.get(index)!
-
-            if (toolCallDelta.id) {
-              toolCall.id = toolCallDelta.id
-            }
-            if (toolCallDelta.function?.name) {
-              toolCall.name = toolCallDelta.function.name
-            }
-            if (toolCallDelta.function?.arguments) {
-              toolCall.arguments += toolCallDelta.function.arguments
-            }
-
-            if (toolCall.id && toolCall.name && !toolCall.started) {
-              toolCall.started = true
-              yield asChunk({
-                type: 'TOOL_CALL_START',
-                toolCallId: toolCall.id,
-                toolCallName: toolCall.name,
-                toolName: toolCall.name,
-                model: chunk.model || options.model,
-                timestamp,
-                index,
-              })
-            }
-
-            if (toolCallDelta.function?.arguments && toolCall.started) {
-              yield asChunk({
-                type: 'TOOL_CALL_ARGS',
-                toolCallId: toolCall.id,
-                model: chunk.model || options.model,
-                timestamp,
-                delta: toolCallDelta.function.arguments,
-              })
-            }
-          }
-        }
-
-        if (choice.finish_reason) {
-          if (
-            choice.finish_reason === 'tool_calls' ||
-            toolCallsInProgress.size > 0
-          ) {
-            for (const [, toolCall] of toolCallsInProgress) {
-              if (!toolCall.started || !toolCall.id || !toolCall.name) {
-                continue
-              }
-
-              let parsedInput: unknown = {}
-              try {
-                parsedInput = toolCall.arguments
-                  ? JSON.parse(toolCall.arguments)
-                  : {}
-              } catch {
-                parsedInput = {}
-              }
-
-              yield asChunk({
-                type: 'TOOL_CALL_END',
-                toolCallId: toolCall.id,
-                toolCallName: toolCall.name,
-                toolName: toolCall.name,
-                model: chunk.model || options.model,
-                timestamp,
-                input: parsedInput,
-              })
-            }
-          }
-
-          const computedFinishReason =
-            choice.finish_reason === 'tool_calls' ||
-            toolCallsInProgress.size > 0
-              ? 'tool_calls'
-              : choice.finish_reason === 'length'
-                ? 'length'
-                : 'stop'
-
-          if (hasEmittedTextMessageStart) {
-            yield asChunk({
-              type: 'TEXT_MESSAGE_END',
-              messageId: aguiState.messageId,
-              model: chunk.model || options.model,
-              timestamp,
-            })
-          }
-
-          const groqUsage = chunk.x_groq?.usage
-
-          yield asChunk({
-            type: 'RUN_FINISHED',
-            runId: aguiState.runId,
-            threadId: aguiState.threadId,
-            model: chunk.model || options.model,
-            timestamp,
-            usage: groqUsage
-              ? {
-                  promptTokens: groqUsage.prompt_tokens || 0,
-                  completionTokens: groqUsage.completion_tokens || 0,
-                  totalTokens: groqUsage.total_tokens || 0,
-                }
-              : undefined,
-            finishReason: computedFinishReason,
-          })
-        }
-      }
-    } catch (error: unknown) {
-      const err = error as Error & { code?: string }
-      logger.errors('groq stream ended with error', {
-        error,
-        source: 'groq.processGroqStreamChunks',
-      })
-
-      yield asChunk({
-        type: 'RUN_ERROR',
-        runId: aguiState.runId,
-        model: options.model,
-        timestamp,
-        message: err.message || 'Unknown error occurred',
-        code: err.code,
-        error: {
-          message: err.message || 'Unknown error occurred',
-          code: err.code,
-        },
-      })
-    }
+  ) {
+    yield* super.processStreamChunks(
+      promoteGroqUsage(stream),
+      options,
+      aguiState,
+    )
   }
 
   /**
-   * Maps common TextOptions to Groq-specific Chat Completions request parameters.
+   * Surfaces Groq's reasoning deltas during streaming structured output.
+   * Groq emits `delta.reasoning` (or legacy `delta.reasoning_content`) on
+   * reasoning models when the caller sets `reasoning_format: 'parsed'` in
+   * modelOptions. The base's chatStream and structuredOutputStream both
+   * route reasoning through this hook.
    */
-  private mapTextOptionsToGroq(
-    options: TextOptions,
-  ): ChatCompletionCreateParamsStreaming {
-    const modelOptions = options.modelOptions as
-      | Omit<
-          InternalTextProviderOptions,
-          'max_tokens' | 'tools' | 'temperature' | 'input' | 'top_p'
-        >
+  protected override extractReasoning(
+    chunk: OpenAI.Chat.Completions.ChatCompletionChunk,
+  ): { text: string } | undefined {
+    const delta = chunk.choices[0]?.delta as
+      | { reasoning?: unknown; reasoning_content?: unknown }
       | undefined
-
-    if (modelOptions) {
-      validateTextProviderOptions({
-        ...modelOptions,
-        model: options.model,
-      })
-    }
-
-    const tools = options.tools
-      ? convertToolsToProviderFormat(options.tools)
-      : undefined
-
-    const messages: Array<ChatCompletionMessageParam> = []
-
-    if (options.systemPrompts && options.systemPrompts.length > 0) {
-      messages.push({
-        role: 'system',
-        content: options.systemPrompts.join('\n'),
-      })
-    }
-
-    for (const message of options.messages) {
-      messages.push(this.convertMessageToGroq(message))
-    }
-
-    return {
-      model: options.model,
-      messages,
-      temperature: options.temperature,
-      max_tokens: options.maxTokens,
-      top_p: options.topP,
-      tools,
-      stream: true,
-    }
-  }
-
-  /**
-   * Converts a TanStack AI ModelMessage to a Groq ChatCompletionMessageParam.
-   * Handles tool, assistant, and user messages including multimodal content.
-   */
-  private convertMessageToGroq(
-    message: ModelMessage,
-  ): ChatCompletionMessageParam {
-    if (message.role === 'tool') {
-      return {
-        role: 'tool',
-        tool_call_id: message.toolCallId || '',
-        content:
-          typeof message.content === 'string'
-            ? message.content
-            : JSON.stringify(message.content),
-      }
-    }
-
-    if (message.role === 'assistant') {
-      const toolCalls = message.toolCalls?.map((tc) => ({
-        id: tc.id,
-        type: 'function' as const,
-        function: {
-          name: tc.function.name,
-          arguments:
-            typeof tc.function.arguments === 'string'
-              ? tc.function.arguments
-              : JSON.stringify(tc.function.arguments),
-        },
-      }))
-
-      return {
-        role: 'assistant',
-        content: this.extractTextContent(message.content),
-        ...(toolCalls && toolCalls.length > 0 ? { tool_calls: toolCalls } : {}),
-      }
-    }
-
-    const contentParts = this.normalizeContent(message.content)
-
-    if (contentParts.length === 1 && contentParts[0]?.type === 'text') {
-      return {
-        role: 'user',
-        content: contentParts[0].content,
-      }
-    }
-
-    const parts: Array<ChatCompletionContentPart> = []
-    for (const part of contentParts) {
-      if (part.type === 'text') {
-        parts.push({ type: 'text', text: part.content })
-      } else if (part.type === 'image') {
-        const imageMetadata = part.metadata as GroqImageMetadata | undefined
-        const imageValue = part.source.value
-        const imageUrl =
-          part.source.type === 'data' && !imageValue.startsWith('data:')
-            ? `data:${part.source.mimeType};base64,${imageValue}`
-            : imageValue
-        parts.push({
-          type: 'image_url',
-          image_url: {
-            url: imageUrl,
-            detail: imageMetadata?.detail || 'auto',
-          },
-        })
-      }
-    }
-
-    return {
-      role: 'user',
-      content: parts.length > 0 ? parts : '',
-    }
-  }
-
-  /**
-   * Normalizes message content to an array of ContentPart.
-   * Handles backward compatibility with string content.
-   */
-  private normalizeContent(
-    content: string | null | Array<ContentPart>,
-  ): Array<ContentPart> {
-    if (content === null) {
-      return []
-    }
-    if (typeof content === 'string') {
-      return [{ type: 'text', content: content }]
+    const raw = delta?.reasoning ?? delta?.reasoning_content
+    if (typeof raw === 'string' && raw.length > 0) {
+      return { text: raw }
     }
-    return content
+    return undefined
   }
+}
 
-  /**
-   * Extracts text content from a content value that may be string, null, or ContentPart array.
-   */
-  private extractTextContent(
-    content: string | null | Array<ContentPart>,
-  ): string {
-    if (content === null) {
-      return ''
-    }
-    if (typeof content === 'string') {
-      return content
+/**
+ * Promotes Groq's non-standard `x_groq.usage` to the standard `chunk.usage`
+ * slot the base reads. Pass-through for chunks that already carry usage at
+ * the documented location.
+ */
+async function* promoteGroqUsage(
+  stream: AsyncIterable<OpenAI.Chat.Completions.ChatCompletionChunk>,
+): AsyncIterable<OpenAI.Chat.Completions.ChatCompletionChunk> {
+  for await (const chunk of stream) {
+    const groqChunk = chunk as typeof chunk & {
+      x_groq?: { usage?: OpenAI.Chat.Completions.ChatCompletionChunk['usage'] }
+    }
+    if (!chunk.usage && groqChunk.x_groq?.usage) {
+      yield { ...chunk, usage: groqChunk.x_groq.usage }
+    } else {
+      yield chunk
     }
-    return content
-      .filter((p) => p.type === 'text')
-      .map((p) => p.content)
-      .join('')
   }
 }
 
 /**
  * Creates a Groq text adapter with explicit API key.
- * Type resolution happens here at the call site.
- *
- * @param model - The model name (e.g., 'llama-3.3-70b-versatile', 'openai/gpt-oss-120b')
- * @param apiKey - Your Groq API key
- * @param config - Optional additional configuration
- * @returns Configured Groq text adapter instance with resolved types
  *
  * @example
  * ```typescript
  * const adapter = createGroqText('llama-3.3-70b-versatile', "gsk_...");
- * // adapter has type-safe providerOptions for llama-3.3-70b-versatile
  * ```
  */
 export function createGroqText<
@@ -618,27 +145,11 @@ export function createGroqText<
 }
 
 /**
- * Creates a Groq text adapter with automatic API key detection from environment variables.
- * Type resolution happens here at the call site.
- *
- * Looks for `GROQ_API_KEY` in:
- * - `process.env` (Node.js)
- * - `window.env` (Browser with injected env)
- *
- * @param model - The model name (e.g., 'llama-3.3-70b-versatile', 'openai/gpt-oss-120b')
- * @param config - Optional configuration (excluding apiKey which is auto-detected)
- * @returns Configured Groq text adapter instance with resolved types
- * @throws Error if GROQ_API_KEY is not found in environment
+ * Creates a Groq text adapter with API key from `GROQ_API_KEY`.
  *
  * @example
  * ```typescript
- * // Automatically uses GROQ_API_KEY from environment
  * const adapter = groqText('llama-3.3-70b-versatile');
- *
- * const stream = chat({
- *   adapter,
- *   messages: [{ role: "user", content: "Hello!" }]
- * });
  * ```
  */
 export function groqText<TModel extends (typeof GROQ_CHAT_MODELS)[number]>(