@ai-sdk/groq 0.0.0-64aae7dd-20260114144918 → 0.0.0-98261322-20260122142521

package/src/groq-chat-options.test.ts

@@ -0,0 +1,110 @@
+import { describe, it, expect } from 'vitest';
+import { groqProviderOptions, GroqProviderOptions } from './groq-chat-options';
+
+describe('groqProviderOptions', () => {
+  describe('reasoningEffort', () => {
+    it('accepts valid reasoningEffort values', () => {
+      const validValues = ['none', 'default', 'low', 'medium', 'high'] as const;
+
+      validValues.forEach(value => {
+        const result = groqProviderOptions.safeParse({
+          reasoningEffort: value,
+        });
+        expect(result.success).toBe(true);
+        expect(result.data?.reasoningEffort).toBe(value);
+      });
+    });
+
+    it('rejects invalid reasoningEffort values', () => {
+      const invalidValues = [
+        'invalid',
+        'high-effort',
+        'minimal',
+        'maximum',
+        '',
+      ];
+
+      invalidValues.forEach(value => {
+        const result = groqProviderOptions.safeParse({
+          reasoningEffort: value,
+        });
+        expect(result.success).toBe(false);
+      });
+    });
+
+    it('allows reasoningEffort to be undefined', () => {
+      const result = groqProviderOptions.safeParse({});
+      expect(result.success).toBe(true);
+      expect(result.data?.reasoningEffort).toBeUndefined();
+    });
+
+    it('allows reasoningEffort to be omitted explicitly', () => {
+      const result = groqProviderOptions.safeParse({
+        reasoningEffort: undefined,
+      });
+      expect(result.success).toBe(true);
+      expect(result.data?.reasoningEffort).toBeUndefined();
+    });
+  });
+
+  describe('combined options with reasoningEffort', () => {
+    it('accepts reasoningEffort with other valid options', () => {
+      const result = groqProviderOptions.safeParse({
+        reasoningEffort: 'high',
+        parallelToolCalls: true,
+        user: 'test-user',
+        structuredOutputs: false,
+        serviceTier: 'flex',
+      });
+
+      expect(result.success).toBe(true);
+      expect(result.data?.reasoningEffort).toBe('high');
+      expect(result.data?.parallelToolCalls).toBe(true);
+      expect(result.data?.user).toBe('test-user');
+    });
+
+    it('rejects when reasoningEffort is invalid among valid options', () => {
+      const result = groqProviderOptions.safeParse({
+        reasoningEffort: 'ultra-high',
+        parallelToolCalls: true,
+        user: 'test-user',
+      });
+
+      expect(result.success).toBe(false);
+    });
+  });
+
+  describe('all reasoningEffort enum variants', () => {
+    it('validates all reasoningEffort variants individually', () => {
+      const variants: Array<'none' | 'default' | 'low' | 'medium' | 'high'> = [
+        'none',
+        'default',
+        'low',
+        'medium',
+        'high',
+      ];
+
+      variants.forEach(variant => {
+        const result = groqProviderOptions.safeParse({
+          reasoningEffort: variant,
+        });
+        expect(result.success).toBe(true);
+        if (result.success) {
+          expect(result.data.reasoningEffort).toBe(variant);
+        }
+      });
+    });
+  });
+
+  describe('type inference', () => {
+    it('infers GroqProviderOptions type correctly', () => {
+      const options: GroqProviderOptions = {
+        reasoningEffort: 'medium',
+        parallelToolCalls: false,
+      };
+
+      expect(options.reasoningEffort).toBe('medium');
+      expect(options.parallelToolCalls).toBe(false);
+    });
+  });
+});

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.test.ts

@@ -0,0 +1,272 @@
+import { describe, it, expect } from 'vitest';
+import { prepareTools } from './groq-prepare-tools';
+
+describe('prepareTools', () => {
+  it('should return undefined tools and toolChoice when tools are null', () => {
+    const result = prepareTools({
+      tools: undefined,
+      modelId: 'gemma2-9b-it',
+    });
+
+    expect(result).toEqual({
+      tools: undefined,
+      toolChoice: undefined,
+      toolWarnings: [],
+    });
+  });
+
+  it('should return undefined tools and toolChoice when tools are empty', () => {
+    const result = prepareTools({
+      tools: [],
+      modelId: 'gemma2-9b-it',
+    });
+
+    expect(result).toEqual({
+      tools: undefined,
+      toolChoice: undefined,
+      toolWarnings: [],
+    });
+  });
+
+  it('should correctly prepare function tools', () => {
+    const result = prepareTools({
+      tools: [
+        {
+          type: 'function',
+          name: 'testFunction',
+          description: 'A test function',
+          inputSchema: { type: 'object', properties: {} },
+        },
+      ],
+      modelId: 'gemma2-9b-it',
+    });
+
+    expect(result.tools).toEqual([
+      {
+        type: 'function',
+        function: {
+          name: 'testFunction',
+          description: 'A test function',
+          parameters: { type: 'object', properties: {} },
+        },
+      },
+    ]);
+    expect(result.toolChoice).toBeUndefined();
+    expect(result.toolWarnings).toEqual([]);
+  });
+
+  it('should add warnings for unsupported provider-defined tools', () => {
+    const result = prepareTools({
+      tools: [
+        {
+          type: 'provider',
+          id: 'some.unsupported_tool',
+          name: 'unsupported_tool',
+          args: {},
+        },
+      ],
+      modelId: 'gemma2-9b-it',
+    });
+
+    expect(result.tools).toEqual([]);
+    expect(result.toolChoice).toBeUndefined();
+    expect(result.toolWarnings).toMatchInlineSnapshot(`
+      [
+        {
+          "feature": "provider-defined tool some.unsupported_tool",
+          "type": "unsupported",
+        },
+      ]
+    `);
+  });
+
+  it('should handle tool choice "auto"', () => {
+    const result = prepareTools({
+      tools: [
+        {
+          type: 'function',
+          name: 'testFunction',
+          description: 'Test',
+          inputSchema: {},
+        },
+      ],
+      toolChoice: { type: 'auto' },
+      modelId: 'gemma2-9b-it',
+    });
+    expect(result.toolChoice).toEqual('auto');
+  });
+
+  it('should handle tool choice "required"', () => {
+    const result = prepareTools({
+      tools: [
+        {
+          type: 'function',
+          name: 'testFunction',
+          description: 'Test',
+          inputSchema: {},
+        },
+      ],
+      toolChoice: { type: 'required' },
+      modelId: 'gemma2-9b-it',
+    });
+    expect(result.toolChoice).toEqual('required');
+  });
+
+  it('should handle tool choice "none"', () => {
+    const result = prepareTools({
+      tools: [
+        {
+          type: 'function',
+          name: 'testFunction',
+          description: 'Test',
+          inputSchema: {},
+        },
+      ],
+      toolChoice: { type: 'none' },
+      modelId: 'gemma2-9b-it',
+    });
+    expect(result.toolChoice).toEqual('none');
+  });
+
+  it('should handle tool choice "tool"', () => {
+    const result = prepareTools({
+      tools: [
+        {
+          type: 'function',
+          name: 'testFunction',
+          description: 'Test',
+          inputSchema: {},
+        },
+      ],
+      toolChoice: { type: 'tool', toolName: 'testFunction' },
+      modelId: 'gemma2-9b-it',
+    });
+    expect(result.toolChoice).toEqual({
+      type: 'function',
+      function: { name: 'testFunction' },
+    });
+  });
+
+  describe('browser search tool', () => {
+    it('should handle browser search tool with supported model', () => {
+      const result = prepareTools({
+        tools: [
+          {
+            type: 'provider',
+            id: 'groq.browser_search',
+            name: 'browser_search',
+            args: {},
+          },
+        ],
+        modelId: 'openai/gpt-oss-120b', // Supported model
+      });
+
+      expect(result.tools).toEqual([
+        {
+          type: 'browser_search',
+        },
+      ]);
+      expect(result.toolWarnings).toEqual([]);
+    });
+
+    it('should warn when browser search is used with unsupported model', () => {
+      const result = prepareTools({
+        tools: [
+          {
+            type: 'provider',
+            id: 'groq.browser_search',
+            name: 'browser_search',
+            args: {},
+          },
+        ],
+        modelId: 'gemma2-9b-it', // Unsupported model
+      });
+
+      expect(result.tools).toEqual([]);
+      expect(result.toolWarnings).toMatchInlineSnapshot(`
+        [
+          {
+            "details": "Browser search is only supported on the following models: openai/gpt-oss-20b, openai/gpt-oss-120b. Current model: gemma2-9b-it",
+            "feature": "provider-defined tool groq.browser_search",
+            "type": "unsupported",
+          },
+        ]
+      `);
+    });
+
+    it('should handle mixed tools with model validation', () => {
+      const result = prepareTools({
+        tools: [
+          {
+            type: 'function',
+            name: 'test-tool',
+            description: 'A test tool',
+            inputSchema: { type: 'object', properties: {} },
+          },
+          {
+            type: 'provider',
+            id: 'groq.browser_search',
+            name: 'browser_search',
+            args: {},
+          },
+        ],
+        modelId: 'openai/gpt-oss-20b', // Supported model
+      });
+
+      expect(result.tools).toEqual([
+        {
+          type: 'function',
+          function: {
+            name: 'test-tool',
+            description: 'A test tool',
+            parameters: { type: 'object', properties: {} },
+          },
+        },
+        {
+          type: 'browser_search',
+        },
+      ]);
+      expect(result.toolWarnings).toEqual([]);
+    });
+
+    it('should validate all browser search supported models', () => {
+      const supportedModels = ['openai/gpt-oss-20b', 'openai/gpt-oss-120b'];
+
+      supportedModels.forEach(modelId => {
+        const result = prepareTools({
+          tools: [
+            {
+              type: 'provider',
+              id: 'groq.browser_search',
+              name: 'browser_search',
+              args: {},
+            },
+          ],
+          modelId: modelId as any,
+        });
+
+        expect(result.tools).toEqual([{ type: 'browser_search' }]);
+        expect(result.toolWarnings).toEqual([]);
+      });
+    });
+
+    it('should handle browser search with tool choice', () => {
+      const result = prepareTools({
+        tools: [
+          {
+            type: 'provider',
+            id: 'groq.browser_search',
+            name: 'browser_search',
+            args: {},
+          },
+        ],
+        toolChoice: { type: 'required' },
+        modelId: 'openai/gpt-oss-120b',
+      });
+
+      expect(result.tools).toEqual([{ type: 'browser_search' }]);
+      expect(result.toolChoice).toEqual('required');
+      expect(result.toolWarnings).toEqual([]);
+    });
+  });
+});

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}`,
+      });
+    }
+  }
+}