@ai-sdk/groq 0.0.0-013d7476-20250808163325 → 0.0.0-4115c213-20260122152721

package/src/groq-chat-options.ts

@@ -0,0 +1,78 @@
+import { z } from 'zod/v4';
+
+// https://console.groq.com/docs/models
+export type GroqChatModelId =
+  // production models
+  | 'gemma2-9b-it'
+  | 'llama-3.1-8b-instant'
+  | 'llama-3.3-70b-versatile'
+  | 'meta-llama/llama-guard-4-12b'
+  | 'openai/gpt-oss-120b'
+  | 'openai/gpt-oss-20b'
+  // preview models (selection)
+  | 'deepseek-r1-distill-llama-70b'
+  | 'meta-llama/llama-4-maverick-17b-128e-instruct'
+  | 'meta-llama/llama-4-scout-17b-16e-instruct'
+  | 'meta-llama/llama-prompt-guard-2-22m'
+  | 'meta-llama/llama-prompt-guard-2-86m'
+  | 'moonshotai/kimi-k2-instruct-0905'
+  | 'qwen/qwen3-32b'
+  | 'llama-guard-3-8b'
+  | 'llama3-70b-8192'
+  | 'llama3-8b-8192'
+  | 'mixtral-8x7b-32768'
+  | 'qwen-qwq-32b'
+  | 'qwen-2.5-32b'
+  | 'deepseek-r1-distill-qwen-32b'
+  | (string & {});
+
+export const groqProviderOptions = z.object({
+  reasoningFormat: z.enum(['parsed', 'raw', 'hidden']).optional(),
+
+  /**
+   * Specifies the reasoning effort level for model inference.
+   * @see https://console.groq.com/docs/reasoning#reasoning-effort
+   */
+  reasoningEffort: z
+    .enum(['none', 'default', 'low', 'medium', 'high'])
+    .optional(),
+
+  /**
+   * Whether to enable parallel function calling during tool use. Default to true.
+   */
+  parallelToolCalls: z.boolean().optional(),
+
+  /**
+   * A unique identifier representing your end-user, which can help OpenAI to
+   * monitor and detect abuse. Learn more.
+   */
+  user: z.string().optional(),
+
+  /**
+   * Whether to use structured outputs.
+   *
+   * @default true
+   */
+  structuredOutputs: z.boolean().optional(),
+
+  /**
+   * Whether to use strict JSON schema validation.
+   * When true, the model uses constrained decoding to guarantee schema compliance.
+   * Only used when structured outputs are enabled and a schema is provided.
+   *
+   * @default true
+   */
+  strictJsonSchema: z.boolean().optional(),
+
+  /**
+   * Service tier for the request.
+   * - 'on_demand': Default tier with consistent performance and fairness
+   * - 'flex': Higher throughput tier optimized for workloads that can handle occasional request failures
+   * - 'auto': Uses on_demand rate limits, then falls back to flex tier if exceeded
+   *
+   * @default 'on_demand'
+   */
+  serviceTier: z.enum(['on_demand', 'flex', 'auto']).optional(),
+});
+
+export type GroqProviderOptions = z.infer<typeof groqProviderOptions>;

package/src/groq-config.ts

@@ -0,0 +1,9 @@
+import { FetchFunction } from '@ai-sdk/provider-utils';
+
+export type GroqConfig = {
+  provider: string;
+  url: (options: { modelId: string; path: string }) => string;
+  headers: () => Record<string, string | undefined>;
+  fetch?: FetchFunction;
+  generateId?: () => string;
+};

package/src/groq-error.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod/v4';
+import { createJsonErrorResponseHandler } from '@ai-sdk/provider-utils';
+
+export const groqErrorDataSchema = z.object({
+  error: z.object({
+    message: z.string(),
+    type: z.string(),
+  }),
+});
+
+export type GroqErrorData = z.infer<typeof groqErrorDataSchema>;
+
+export const groqFailedResponseHandler = createJsonErrorResponseHandler({
+  errorSchema: groqErrorDataSchema,
+  errorToMessage: data => data.error.message,
+});

package/src/groq-prepare-tools.ts

@@ -0,0 +1,128 @@
+import {
+  LanguageModelV3CallOptions,
+  SharedV3Warning,
+  UnsupportedFunctionalityError,
+} from '@ai-sdk/provider';
+import {
+  getSupportedModelsString,
+  isBrowserSearchSupportedModel,
+} from './groq-browser-search-models';
+import { GroqChatModelId } from './groq-chat-options';
+
+export function prepareTools({
+  tools,
+  toolChoice,
+  modelId,
+}: {
+  tools: LanguageModelV3CallOptions['tools'];
+  toolChoice?: LanguageModelV3CallOptions['toolChoice'];
+  modelId: GroqChatModelId;
+}): {
+  tools:
+    | undefined
+    | Array<
+        | {
+            type: 'function';
+            function: {
+              name: string;
+              description: string | undefined;
+              parameters: unknown;
+            };
+          }
+        | {
+            type: 'browser_search';
+          }
+      >;
+  toolChoice:
+    | { type: 'function'; function: { name: string } }
+    | 'auto'
+    | 'none'
+    | 'required'
+    | undefined;
+  toolWarnings: SharedV3Warning[];
+} {
+  // when the tools array is empty, change it to undefined to prevent errors:
+  tools = tools?.length ? tools : undefined;
+
+  const toolWarnings: SharedV3Warning[] = [];
+
+  if (tools == null) {
+    return { tools: undefined, toolChoice: undefined, toolWarnings };
+  }
+
+  const groqTools: Array<
+    | {
+        type: 'function';
+        function: {
+          name: string;
+          description: string | undefined;
+          parameters: unknown;
+        };
+      }
+    | {
+        type: 'browser_search';
+      }
+  > = [];
+
+  for (const tool of tools) {
+    if (tool.type === 'provider') {
+      if (tool.id === 'groq.browser_search') {
+        if (!isBrowserSearchSupportedModel(modelId)) {
+          toolWarnings.push({
+            type: 'unsupported',
+            feature: `provider-defined tool ${tool.id}`,
+            details: `Browser search is only supported on the following models: ${getSupportedModelsString()}. Current model: ${modelId}`,
+          });
+        } else {
+          groqTools.push({
+            type: 'browser_search',
+          });
+        }
+      } else {
+        toolWarnings.push({
+          type: 'unsupported',
+          feature: `provider-defined tool ${tool.id}`,
+        });
+      }
+    } else {
+      groqTools.push({
+        type: 'function',
+        function: {
+          name: tool.name,
+          description: tool.description,
+          parameters: tool.inputSchema,
+        },
+      });
+    }
+  }
+
+  if (toolChoice == null) {
+    return { tools: groqTools, toolChoice: undefined, toolWarnings };
+  }
+
+  const type = toolChoice.type;
+
+  switch (type) {
+    case 'auto':
+    case 'none':
+    case 'required':
+      return { tools: groqTools, toolChoice: type, toolWarnings };
+    case 'tool':
+      return {
+        tools: groqTools,
+        toolChoice: {
+          type: 'function',
+          function: {
+            name: toolChoice.toolName,
+          },
+        },
+        toolWarnings,
+      };
+    default: {
+      const _exhaustiveCheck: never = type;
+      throw new UnsupportedFunctionalityError({
+        functionality: `tool choice type: ${_exhaustiveCheck}`,
+      });
+    }
+  }
+}

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.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';