@ai-sdk/groq 0.0.0-70e0935a-20260114150030 → 0.0.0-98261322-20260122142521

package/src/groq-provider.ts

@@ -0,0 +1,143 @@
+import {
+  LanguageModelV3,
+  NoSuchModelError,
+  ProviderV3,
+  TranscriptionModelV3,
+} from '@ai-sdk/provider';
+import {
+  FetchFunction,
+  loadApiKey,
+  withoutTrailingSlash,
+  withUserAgentSuffix,
+} from '@ai-sdk/provider-utils';
+import { GroqChatLanguageModel } from './groq-chat-language-model';
+import { GroqChatModelId } from './groq-chat-options';
+import { GroqTranscriptionModelId } from './groq-transcription-options';
+import { GroqTranscriptionModel } from './groq-transcription-model';
+
+import { groqTools } from './groq-tools';
+import { VERSION } from './version';
+export interface GroqProvider extends ProviderV3 {
+  /**
+Creates a model for text generation.
+*/
+  (modelId: GroqChatModelId): LanguageModelV3;
+
+  /**
+Creates an Groq chat model for text generation.
+   */
+  languageModel(modelId: GroqChatModelId): LanguageModelV3;
+
+  /**
+Creates a model for transcription.
+   */
+  transcription(modelId: GroqTranscriptionModelId): TranscriptionModelV3;
+
+  /**
+   * Tools provided by Groq.
+   */
+  tools: typeof groqTools;
+
+  /**
+   * @deprecated Use `embeddingModel` instead.
+   */
+  textEmbeddingModel(modelId: string): never;
+}
+
+export interface GroqProviderSettings {
+  /**
+Base URL for the Groq API calls.
+     */
+  baseURL?: string;
+
+  /**
+API key for authenticating requests.
+     */
+  apiKey?: string;
+
+  /**
+Custom headers to include in the requests.
+     */
+  headers?: Record<string, string>;
+
+  /**
+Custom fetch implementation. You can use it as a middleware to intercept requests,
+or to provide a custom fetch implementation for e.g. testing.
+    */
+  fetch?: FetchFunction;
+}
+
+/**
+Create an Groq provider instance.
+ */
+export function createGroq(options: GroqProviderSettings = {}): GroqProvider {
+  const baseURL =
+    withoutTrailingSlash(options.baseURL) ?? 'https://api.groq.com/openai/v1';
+
+  const getHeaders = () =>
+    withUserAgentSuffix(
+      {
+        Authorization: `Bearer ${loadApiKey({
+          apiKey: options.apiKey,
+          environmentVariableName: 'GROQ_API_KEY',
+          description: 'Groq',
+        })}`,
+        ...options.headers,
+      },
+      `ai-sdk/groq/${VERSION}`,
+    );
+
+  const createChatModel = (modelId: GroqChatModelId) =>
+    new GroqChatLanguageModel(modelId, {
+      provider: 'groq.chat',
+      url: ({ path }) => `${baseURL}${path}`,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
+
+  const createLanguageModel = (modelId: GroqChatModelId) => {
+    if (new.target) {
+      throw new Error(
+        'The Groq model function cannot be called with the new keyword.',
+      );
+    }
+
+    return createChatModel(modelId);
+  };
+
+  const createTranscriptionModel = (modelId: GroqTranscriptionModelId) => {
+    return new GroqTranscriptionModel(modelId, {
+      provider: 'groq.transcription',
+      url: ({ path }) => `${baseURL}${path}`,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
+  };
+
+  const provider = function (modelId: GroqChatModelId) {
+    return createLanguageModel(modelId);
+  };
+
+  provider.specificationVersion = 'v3' as const;
+  provider.languageModel = createLanguageModel;
+  provider.chat = createChatModel;
+
+  provider.embeddingModel = (modelId: string) => {
+    throw new NoSuchModelError({ modelId, modelType: 'embeddingModel' });
+  };
+  provider.textEmbeddingModel = provider.embeddingModel;
+  provider.imageModel = (modelId: string) => {
+    throw new NoSuchModelError({ modelId, modelType: 'imageModel' });
+  };
+  provider.transcription = createTranscriptionModel;
+  provider.transcriptionModel = createTranscriptionModel;
+
+  provider.tools = groqTools;
+
+  return provider;
+}
+
+/**
+Default Groq provider instance.
+ */
+export const groq = createGroq();

package/src/groq-tools.ts

@@ -0,0 +1,5 @@
+import { browserSearch } from './tool/browser-search';
+
+export const groqTools = {
+  browserSearch,
+};

package/src/groq-transcription-model.test.ts

@@ -0,0 +1,185 @@
+import { createTestServer } from '@ai-sdk/test-server/with-vitest';
+import { GroqTranscriptionModel } from './groq-transcription-model';
+import { createGroq } from './groq-provider';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { describe, it, expect, vi } from 'vitest';
+
+vi.mock('./version', () => ({
+  VERSION: '0.0.0-test',
+}));
+
+const audioData = await readFile(path.join(__dirname, 'transcript-test.mp3'));
+const provider = createGroq({ apiKey: 'test-api-key' });
+const model = provider.transcription('whisper-large-v3-turbo');
+
+const server = createTestServer({
+  'https://api.groq.com/openai/v1/audio/transcriptions': {},
+});
+
+describe('doGenerate', () => {
+  function prepareJsonResponse({
+    headers,
+  }: {
+    headers?: Record<string, string>;
+  } = {}) {
+    server.urls[
+      'https://api.groq.com/openai/v1/audio/transcriptions'
+    ].response = {
+      type: 'json-value',
+      headers,
+      body: {
+        task: 'transcribe',
+        language: 'English',
+        duration: 2.5,
+        text: 'Hello world!',
+        segments: [
+          {
+            id: 0,
+            seek: 0,
+            start: 0,
+            end: 2.48,
+            text: 'Hello world!',
+            tokens: [50365, 2425, 490, 264],
+            temperature: 0,
+            avg_logprob: -0.29010406,
+            compression_ratio: 0.7777778,
+            no_speech_prob: 0.032802984,
+          },
+        ],
+        x_groq: { id: 'req_01jrh9nn61f24rydqq1r4b3yg5' },
+      },
+    };
+  }
+
+  it('should pass the model', async () => {
+    prepareJsonResponse();
+
+    await model.doGenerate({
+      audio: audioData,
+      mediaType: 'audio/wav',
+    });
+
+    expect(await server.calls[0].requestBodyMultipart).toMatchObject({
+      model: 'whisper-large-v3-turbo',
+    });
+  });
+
+  it('should pass headers', async () => {
+    prepareJsonResponse();
+
+    const provider = createGroq({
+      apiKey: 'test-api-key',
+      headers: {
+        'Custom-Provider-Header': 'provider-header-value',
+      },
+    });
+
+    await provider.transcription('whisper-large-v3-turbo').doGenerate({
+      audio: audioData,
+      mediaType: 'audio/wav',
+      headers: {
+        'Custom-Request-Header': 'request-header-value',
+      },
+    });
+
+    expect(server.calls[0].requestHeaders).toMatchObject({
+      authorization: 'Bearer test-api-key',
+      'content-type': expect.stringMatching(
+        /^multipart\/form-data; boundary=----formdata-undici-\d+$/,
+      ),
+      'custom-provider-header': 'provider-header-value',
+      'custom-request-header': 'request-header-value',
+    });
+    expect(server.calls[0].requestUserAgent).toContain(
+      `ai-sdk/groq/0.0.0-test`,
+    );
+  });
+
+  it('should extract the transcription text', async () => {
+    prepareJsonResponse();
+
+    const result = await model.doGenerate({
+      audio: audioData,
+      mediaType: 'audio/wav',
+    });
+
+    expect(result.text).toBe('Hello world!');
+  });
+
+  it('should include response data with timestamp, modelId and headers', async () => {
+    prepareJsonResponse({
+      headers: {
+        'x-request-id': 'test-request-id',
+        'x-ratelimit-remaining': '123',
+      },
+    });
+
+    const testDate = new Date(0);
+    const customModel = new GroqTranscriptionModel('whisper-large-v3-turbo', {
+      provider: 'test-provider',
+      url: () => 'https://api.groq.com/openai/v1/audio/transcriptions',
+      headers: () => ({}),
+      _internal: {
+        currentDate: () => testDate,
+      },
+    });
+
+    const result = await customModel.doGenerate({
+      audio: audioData,
+      mediaType: 'audio/wav',
+    });
+
+    expect(result.response).toMatchObject({
+      timestamp: testDate,
+      modelId: 'whisper-large-v3-turbo',
+      headers: {
+        'content-type': 'application/json',
+        'x-request-id': 'test-request-id',
+        'x-ratelimit-remaining': '123',
+      },
+    });
+  });
+
+  it('should use real date when no custom date provider is specified', async () => {
+    prepareJsonResponse();
+
+    const testDate = new Date(0);
+    const customModel = new GroqTranscriptionModel('whisper-large-v3-turbo', {
+      provider: 'test-provider',
+      url: () => 'https://api.groq.com/openai/v1/audio/transcriptions',
+      headers: () => ({}),
+      _internal: {
+        currentDate: () => testDate,
+      },
+    });
+
+    const result = await customModel.doGenerate({
+      audio: audioData,
+      mediaType: 'audio/wav',
+    });
+
+    expect(result.response.timestamp.getTime()).toEqual(testDate.getTime());
+    expect(result.response.modelId).toBe('whisper-large-v3-turbo');
+  });
+
+  it('should correctly pass provider options when they are an array', async () => {
+    prepareJsonResponse();
+
+    await model.doGenerate({
+      audio: audioData,
+      mediaType: 'audio/wav',
+      providerOptions: {
+        groq: {
+          timestampGranularities: ['segment'],
+          responseFormat: 'verbose_json',
+        },
+      },
+    });
+
+    expect(await server.calls[0].requestBodyMultipart).toMatchObject({
+      'timestamp_granularities[]': 'segment',
+      response_format: 'verbose_json',
+    });
+  });
+});

package/src/groq-transcription-model.ts

@@ -0,0 +1,184 @@
+import { TranscriptionModelV3, SharedV3Warning } from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  convertBase64ToUint8Array,
+  createJsonResponseHandler,
+  mediaTypeToExtension,
+  parseProviderOptions,
+  postFormDataToApi,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import { GroqConfig } from './groq-config';
+import { groqFailedResponseHandler } from './groq-error';
+import { GroqTranscriptionModelId } from './groq-transcription-options';
+import { GroqTranscriptionAPITypes } from './groq-api-types';
+
+// https://console.groq.com/docs/speech-to-text
+const groqProviderOptionsSchema = z.object({
+  language: z.string().nullish(),
+  prompt: z.string().nullish(),
+  responseFormat: z.string().nullish(),
+  temperature: z.number().min(0).max(1).nullish(),
+  timestampGranularities: z.array(z.string()).nullish(),
+});
+
+export type GroqTranscriptionCallOptions = z.infer<
+  typeof groqProviderOptionsSchema
+>;
+
+interface GroqTranscriptionModelConfig extends GroqConfig {
+  _internal?: {
+    currentDate?: () => Date;
+  };
+}
+
+export class GroqTranscriptionModel implements TranscriptionModelV3 {
+  readonly specificationVersion = 'v3';
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  constructor(
+    readonly modelId: GroqTranscriptionModelId,
+    private readonly config: GroqTranscriptionModelConfig,
+  ) {}
+
+  private async getArgs({
+    audio,
+    mediaType,
+    providerOptions,
+  }: Parameters<TranscriptionModelV3['doGenerate']>[0]) {
+    const warnings: SharedV3Warning[] = [];
+
+    // Parse provider options
+    const groqOptions = await parseProviderOptions({
+      provider: 'groq',
+      providerOptions,
+      schema: groqProviderOptionsSchema,
+    });
+
+    // Create form data with base fields
+    const formData = new FormData();
+    const blob =
+      audio instanceof Uint8Array
+        ? new Blob([audio])
+        : new Blob([convertBase64ToUint8Array(audio)]);
+
+    formData.append('model', this.modelId);
+    const fileExtension = mediaTypeToExtension(mediaType);
+    formData.append(
+      'file',
+      new File([blob], 'audio', { type: mediaType }),
+      `audio.${fileExtension}`,
+    );
+
+    // Add provider-specific options
+    if (groqOptions) {
+      const transcriptionModelOptions: Omit<
+        GroqTranscriptionAPITypes,
+        'model'
+      > = {
+        language: groqOptions.language ?? undefined,
+        prompt: groqOptions.prompt ?? undefined,
+        response_format: groqOptions.responseFormat ?? undefined,
+        temperature: groqOptions.temperature ?? undefined,
+        timestamp_granularities:
+          groqOptions.timestampGranularities ?? undefined,
+      };
+
+      for (const key in transcriptionModelOptions) {
+        const value =
+          transcriptionModelOptions[
+            key as keyof Omit<GroqTranscriptionAPITypes, 'model'>
+          ];
+        if (value !== undefined) {
+          if (Array.isArray(value)) {
+            for (const item of value) {
+              formData.append(`${key}[]`, String(item));
+            }
+          } else {
+            formData.append(key, String(value));
+          }
+        }
+      }
+    }
+
+    return {
+      formData,
+      warnings,
+    };
+  }
+
+  async doGenerate(
+    options: Parameters<TranscriptionModelV3['doGenerate']>[0],
+  ): Promise<Awaited<ReturnType<TranscriptionModelV3['doGenerate']>>> {
+    const currentDate = this.config._internal?.currentDate?.() ?? new Date();
+    const { formData, warnings } = await this.getArgs(options);
+
+    const {
+      value: response,
+      responseHeaders,
+      rawValue: rawResponse,
+    } = await postFormDataToApi({
+      url: this.config.url({
+        path: '/audio/transcriptions',
+        modelId: this.modelId,
+      }),
+      headers: combineHeaders(this.config.headers(), options.headers),
+      formData,
+      failedResponseHandler: groqFailedResponseHandler,
+      successfulResponseHandler: createJsonResponseHandler(
+        groqTranscriptionResponseSchema,
+      ),
+      abortSignal: options.abortSignal,
+      fetch: this.config.fetch,
+    });
+
+    return {
+      text: response.text,
+      segments:
+        response.segments?.map(segment => ({
+          text: segment.text,
+          startSecond: segment.start,
+          endSecond: segment.end,
+        })) ?? [],
+      language: response.language ?? undefined,
+      durationInSeconds: response.duration ?? undefined,
+      warnings,
+      response: {
+        timestamp: currentDate,
+        modelId: this.modelId,
+        headers: responseHeaders,
+        body: rawResponse,
+      },
+    };
+  }
+}
+
+const groqTranscriptionResponseSchema = z.object({
+  text: z.string(),
+  x_groq: z.object({
+    id: z.string(),
+  }),
+  // additional properties are returned when `response_format: 'verbose_json'` is
+  task: z.string().nullish(),
+  language: z.string().nullish(),
+  duration: z.number().nullish(),
+  segments: z
+    .array(
+      z.object({
+        id: z.number(),
+        seek: z.number(),
+        start: z.number(),
+        end: z.number(),
+        text: z.string(),
+        tokens: z.array(z.number()),
+        temperature: z.number(),
+        avg_logprob: z.number(),
+        compression_ratio: z.number(),
+        no_speech_prob: z.number(),
+      }),
+    )
+    .nullish(),
+});

package/src/groq-transcription-options.ts

@@ -0,0 +1,4 @@
+export type GroqTranscriptionModelId =
+  | 'whisper-large-v3-turbo'
+  | 'whisper-large-v3'
+  | (string & {});

package/src/index.ts

@@ -0,0 +1,5 @@
+export { createGroq, groq } from './groq-provider';
+export type { GroqProvider, GroqProviderSettings } from './groq-provider';
+export type { GroqProviderOptions } from './groq-chat-options';
+export { browserSearch } from './tool/browser-search';
+export { VERSION } from './version';

package/src/map-groq-finish-reason.ts

@@ -0,0 +1,19 @@
+import { LanguageModelV3FinishReason } from '@ai-sdk/provider';
+
+export function mapGroqFinishReason(
+  finishReason: string | null | undefined,
+): LanguageModelV3FinishReason['unified'] {
+  switch (finishReason) {
+    case 'stop':
+      return 'stop';
+    case 'length':
+      return 'length';
+    case 'content_filter':
+      return 'content-filter';
+    case 'function_call':
+    case 'tool_calls':
+      return 'tool-calls';
+    default:
+      return 'other';
+  }
+}

package/src/tool/browser-search.ts

@@ -0,0 +1,28 @@
+import { createProviderToolFactory } from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+
+/**
+ * Browser search tool for Groq models.
+ *
+ * Provides interactive browser search capabilities that go beyond traditional web search
+ * by navigating websites interactively and providing more detailed results.
+ *
+ * Currently supported on:
+ * - openai/gpt-oss-20b
+ * - openai/gpt-oss-120b
+ *
+ * @see https://console.groq.com/docs/browser-search
+ */
+export const browserSearch = createProviderToolFactory<
+  {
+    // Browser search doesn't take input parameters - it's controlled by the prompt
+    // The tool is activated automatically when included in the tools array
+  },
+  {
+    // No configuration options needed - the tool works automatically
+    // when included in the tools array for supported models
+  }
+>({
+  id: 'groq.browser_search',
+  inputSchema: z.object({}),
+});

package/src/version.ts

@@ -0,0 +1,6 @@
+// Version string of this package injected at build time.
+declare const __PACKAGE_VERSION__: string | undefined;
+export const VERSION: string =
+  typeof __PACKAGE_VERSION__ !== 'undefined'
+    ? __PACKAGE_VERSION__
+    : '0.0.0-test';