@tanstack/ai-groq 0.1.0

package/src/model-meta.ts

@@ -0,0 +1,370 @@
+import type { GroqTextProviderOptions } from './text/text-provider-options'
+
+/**
+ * Internal metadata structure describing a Groq model's capabilities and pricing.
+ */
+interface ModelMeta<TProviderOptions = unknown> {
+  name: string
+  context_window?: number
+  max_completion_tokens?: number
+  pricing: {
+    input?: { normal: number; cached?: number }
+    output?: { normal: number }
+  }
+  supports: {
+    input: Array<'text' | 'image' | 'audio'>
+    output: Array<'text' | 'audio'>
+    endpoints: Array<'chat' | 'tts' | 'transcription' | 'batch'>
+
+    features: Array<
+      | 'streaming'
+      | 'tools'
+      | 'json_object'
+      | 'browser_search'
+      | 'code_execution'
+      | 'reasoning'
+      | 'content_moderation'
+      | 'json_schema'
+      | 'vision'
+    >
+  }
+  /**
+   * Type-level description of which provider options this model supports.
+   */
+  providerOptions?: TProviderOptions
+}
+
+const LLAMA_3_3_70B_VERSATILE = {
+  name: 'llama-3.3-70b-versatile',
+  context_window: 131_072,
+  max_completion_tokens: 32_768,
+  pricing: {
+    input: {
+      normal: 0.59,
+    },
+    output: {
+      normal: 0.79,
+    },
+  },
+  supports: {
+    input: ['text'],
+    output: ['text'],
+    endpoints: ['chat'],
+    features: ['streaming', 'tools', 'json_object'],
+  },
+} as const satisfies ModelMeta<GroqTextProviderOptions>
+
+const LLAMA_4_MAVERICK_17B_128E_INSTRUCT = {
+  name: 'meta-llama/llama-4-maverick-17b-128e-instruct',
+  context_window: 131_072,
+  max_completion_tokens: 8_192,
+  pricing: {
+    input: {
+      normal: 0.2,
+    },
+    output: {
+      normal: 0.6,
+    },
+  },
+  supports: {
+    input: ['text', 'image'],
+    output: ['text'],
+    endpoints: ['chat'],
+    features: ['streaming', 'tools', 'json_object', 'json_schema', 'vision'],
+  },
+} as const satisfies ModelMeta<GroqTextProviderOptions>
+
+const LLAMA_4_SCOUT_17B_16E_INSTRUCT = {
+  name: 'meta-llama/llama-4-scout-17b-16e-instruct',
+  context_window: 131_072,
+  max_completion_tokens: 8_192,
+  pricing: {
+    input: {
+      normal: 0.05,
+    },
+    output: {
+      normal: 0.08,
+    },
+  },
+  supports: {
+    input: ['text', 'image'],
+    output: ['text'],
+    endpoints: ['chat'],
+    features: ['streaming', 'tools', 'json_object'],
+  },
+} as const satisfies ModelMeta<GroqTextProviderOptions>
+
+const LLAMA_GUARD_4_12B = {
+  name: 'meta-llama/llama-guard-4-12b',
+  context_window: 131_072,
+  max_completion_tokens: 1024,
+  pricing: {
+    input: {
+      normal: 0.2,
+    },
+    output: {
+      normal: 0.2,
+    },
+  },
+  supports: {
+    input: ['text', 'image'],
+    output: ['text'],
+    endpoints: ['chat'],
+    features: ['streaming', 'json_object', 'content_moderation', 'vision'],
+  },
+} as const satisfies ModelMeta<GroqTextProviderOptions>
+
+const LLAMA_PROMPT_GUARD_2_86M = {
+  name: 'meta-llama/llama-prompt-guard-2-86m',
+  context_window: 512,
+  max_completion_tokens: 512,
+  pricing: {
+    input: {
+      normal: 0.04,
+    },
+    output: {
+      normal: 0.04,
+    },
+  },
+  supports: {
+    input: ['text'],
+    output: ['text'],
+    endpoints: ['chat'],
+    features: ['streaming', 'content_moderation', 'json_object'],
+  },
+} as const satisfies ModelMeta<GroqTextProviderOptions>
+
+const LLAMA_3_1_8B_INSTANT = {
+  name: 'llama-3.1-8b-instant',
+  context_window: 131_072,
+  max_completion_tokens: 131_072,
+  pricing: {
+    input: {
+      normal: 0.05,
+    },
+    output: {
+      normal: 0.08,
+    },
+  },
+  supports: {
+    input: ['text'],
+    output: ['text'],
+    endpoints: ['chat'],
+    features: ['streaming', 'json_object', 'tools'],
+  },
+} as const satisfies ModelMeta<GroqTextProviderOptions>
+
+const LLAMA_PROMPT_GUARD_2_22M = {
+  name: 'meta-llama/llama-prompt-guard-2-22m',
+  context_window: 512,
+  max_completion_tokens: 512,
+  pricing: {
+    input: {
+      normal: 0.03,
+    },
+    output: {
+      normal: 0.03,
+    },
+  },
+  supports: {
+    input: ['text'],
+    output: ['text'],
+    endpoints: ['chat'],
+    features: ['streaming', 'content_moderation'],
+  },
+} as const satisfies ModelMeta<GroqTextProviderOptions>
+
+const GPT_OSS_120B = {
+  name: 'openai/gpt-oss-120b',
+  context_window: 131_072,
+  max_completion_tokens: 65_536,
+  pricing: {
+    input: {
+      normal: 0.15,
+      cached: 0.075,
+    },
+    output: {
+      normal: 0.6,
+    },
+  },
+  supports: {
+    input: ['text'],
+    output: ['text'],
+    endpoints: ['chat'],
+    features: [
+      'streaming',
+      'json_object',
+      'json_schema',
+      'tools',
+      'browser_search',
+      'code_execution',
+      'reasoning',
+    ],
+  },
+} as const satisfies ModelMeta<GroqTextProviderOptions>
+
+const GPT_OSS_SAFEGUARD_20B = {
+  name: 'openai/gpt-oss-safeguard-20b',
+  context_window: 131_072,
+  max_completion_tokens: 65_536,
+  pricing: {
+    input: {
+      normal: 0.075,
+      cached: 0.037,
+    },
+    output: {
+      normal: 0.3,
+    },
+  },
+  supports: {
+    input: ['text'],
+    output: ['text'],
+    endpoints: ['chat'],
+    features: [
+      'streaming',
+      'tools',
+      'browser_search',
+      'code_execution',
+      'json_object',
+      'json_schema',
+      'reasoning',
+      'content_moderation',
+    ],
+  },
+} as const satisfies ModelMeta<GroqTextProviderOptions>
+
+const GPT_OSS_20B = {
+  name: 'openai/gpt-oss-20b',
+  context_window: 131_072,
+  max_completion_tokens: 65_536,
+  pricing: {
+    input: {
+      normal: 0.075,
+      cached: 0.037,
+    },
+    output: {
+      normal: 0.3,
+    },
+  },
+  supports: {
+    input: ['text'],
+    output: ['text'],
+    endpoints: ['chat'],
+    features: [
+      'streaming',
+      'browser_search',
+      'code_execution',
+      'json_object',
+      'json_schema',
+      'reasoning',
+      'tools',
+    ],
+  },
+} as const satisfies ModelMeta<GroqTextProviderOptions>
+
+const KIMI_K2_INSTRUCT_0905 = {
+  name: 'moonshotai/kimi-k2-instruct-0905',
+  context_window: 262_144,
+  max_completion_tokens: 16_384,
+  pricing: {
+    input: {
+      normal: 1,
+      cached: 0.5,
+    },
+    output: {
+      normal: 3,
+    },
+  },
+  supports: {
+    input: ['text'],
+    output: ['text'],
+    endpoints: ['chat'],
+    features: ['streaming', 'tools', 'json_object', 'json_schema'],
+  },
+} as const satisfies ModelMeta<GroqTextProviderOptions>
+
+const QWEN3_32B = {
+  name: 'qwen/qwen3-32b',
+  context_window: 131_072,
+  max_completion_tokens: 40_960,
+  pricing: {
+    input: {
+      normal: 0.29,
+    },
+    output: {
+      normal: 0.59,
+    },
+  },
+  supports: {
+    input: ['text'],
+    output: ['text'],
+    endpoints: ['chat'],
+    features: ['streaming', 'json_object', 'tools', 'reasoning'],
+  },
+} as const satisfies ModelMeta<GroqTextProviderOptions>
+
+/**
+ * All supported Groq chat model identifiers.
+ */
+export const GROQ_CHAT_MODELS = [
+  LLAMA_3_1_8B_INSTANT.name,
+  LLAMA_3_3_70B_VERSATILE.name,
+  LLAMA_4_MAVERICK_17B_128E_INSTRUCT.name,
+  LLAMA_4_SCOUT_17B_16E_INSTRUCT.name,
+  LLAMA_GUARD_4_12B.name,
+  LLAMA_PROMPT_GUARD_2_86M.name,
+  LLAMA_PROMPT_GUARD_2_22M.name,
+  GPT_OSS_20B.name,
+  GPT_OSS_120B.name,
+  GPT_OSS_SAFEGUARD_20B.name,
+  KIMI_K2_INSTRUCT_0905.name,
+  QWEN3_32B.name,
+] as const
+
+/**
+ * Union type of all supported Groq chat model names.
+ */
+export type GroqChatModels = (typeof GROQ_CHAT_MODELS)[number]
+
+/**
+ * Type-only map from Groq chat model name to its supported input modalities.
+ */
+export type GroqModelInputModalitiesByName = {
+  [LLAMA_3_1_8B_INSTANT.name]: typeof LLAMA_3_1_8B_INSTANT.supports.input
+  [LLAMA_3_3_70B_VERSATILE.name]: typeof LLAMA_3_3_70B_VERSATILE.supports.input
+  [LLAMA_4_MAVERICK_17B_128E_INSTRUCT.name]: typeof LLAMA_4_MAVERICK_17B_128E_INSTRUCT.supports.input
+  [LLAMA_4_SCOUT_17B_16E_INSTRUCT.name]: typeof LLAMA_4_SCOUT_17B_16E_INSTRUCT.supports.input
+  [LLAMA_GUARD_4_12B.name]: typeof LLAMA_GUARD_4_12B.supports.input
+  [LLAMA_PROMPT_GUARD_2_86M.name]: typeof LLAMA_PROMPT_GUARD_2_86M.supports.input
+  [LLAMA_PROMPT_GUARD_2_22M.name]: typeof LLAMA_PROMPT_GUARD_2_22M.supports.input
+  [GPT_OSS_20B.name]: typeof GPT_OSS_20B.supports.input
+  [GPT_OSS_120B.name]: typeof GPT_OSS_120B.supports.input
+  [GPT_OSS_SAFEGUARD_20B.name]: typeof GPT_OSS_SAFEGUARD_20B.supports.input
+  [KIMI_K2_INSTRUCT_0905.name]: typeof KIMI_K2_INSTRUCT_0905.supports.input
+  [QWEN3_32B.name]: typeof QWEN3_32B.supports.input
+}
+
+/**
+ * Type-only map from Groq chat model name to its provider options type.
+ */
+export type GroqChatModelProviderOptionsByName = {
+  [K in (typeof GROQ_CHAT_MODELS)[number]]: GroqTextProviderOptions
+}
+
+/**
+ * Resolves the provider options type for a specific Groq model.
+ * Falls back to generic GroqTextProviderOptions for unknown models.
+ */
+export type ResolveProviderOptions<TModel extends string> =
+  TModel extends keyof GroqChatModelProviderOptionsByName
+    ? GroqChatModelProviderOptionsByName[TModel]
+    : GroqTextProviderOptions
+
+/**
+ * Resolve input modalities for a specific model.
+ * If the model has explicit modalities in the map, use those; otherwise use text only.
+ */
+export type ResolveInputModalities<TModel extends string> =
+  TModel extends keyof GroqModelInputModalitiesByName
+    ? GroqModelInputModalitiesByName[TModel]
+    : readonly ['text']

package/src/text/text-provider-options.ts

@@ -0,0 +1,225 @@
+import type {
+  ChatCompletionMessageParam,
+  ChatCompletionTool,
+  ChatCompletionToolChoiceOption,
+  CompoundCustom,
+  Document,
+  ResponseFormatJsonObject,
+  ResponseFormatJsonSchema,
+  ResponseFormatText,
+  SearchSettings,
+} from '../message-types'
+
+/**
+ * Groq-specific provider options for text/chat models.
+ *
+ * These options extend the standard Chat Completions API parameters
+ * with Groq-specific features like compound models and search settings.
+ *
+ * @see https://console.groq.com/docs/api-reference#chat
+ */
+export interface GroqTextProviderOptions {
+  /**
+   * Whether to enable citations in the response. When enabled, the model will
+   * include citations for information retrieved from provided documents or web
+   * searches.
+   */
+  citation_options?: 'enabled' | 'disabled' | null
+
+  /** Custom configuration of models and tools for Compound. */
+  compound_custom?: CompoundCustom | null
+
+  /**
+   * If set to true, groq will return called tools without validating that the tool
+   * is present in request.tools. tool_choice=required/none will still be enforced,
+   * but the request cannot require a specific tool be used.
+   */
+  disable_tool_validation?: boolean
+
+  /**
+   * A list of documents to provide context for the conversation. Each document
+   * contains text that can be referenced by the model.
+   */
+  documents?: Array<Document> | null
+
+  /**
+   * Number between -2.0 and 2.0. Positive values penalize new tokens based on their
+   * existing frequency in the text so far, decreasing the model's likelihood to
+   * repeat the same line verbatim.
+   */
+  frequency_penalty?: number | null
+
+  /**
+   * Whether to include reasoning in the response. This field is mutually exclusive
+   * with `reasoning_format`.
+   */
+  include_reasoning?: boolean | null
+
+  /** Modify the likelihood of specified tokens appearing in the completion. */
+  logit_bias?: { [key: string]: number } | null
+
+  /**
+   * Whether to return log probabilities of the output tokens or not. If true,
+   * returns the log probabilities of each output token returned in the `content`
+   * of `message`.
+   */
+  logprobs?: boolean | null
+
+  /**
+   * The maximum number of tokens that can be generated in the chat completion. The
+   * total length of input tokens and generated tokens is limited by the model's
+   * context length.
+   */
+  max_completion_tokens?: number | null
+
+  /** Request metadata. */
+  metadata?: { [key: string]: string } | null
+
+  /**
+   * How many chat completion choices to generate for each input message.
+   * Currently only n=1 is supported.
+   */
+  n?: number | null
+
+  /** Whether to enable parallel function calling during tool use. */
+  parallel_tool_calls?: boolean | null
+
+  /**
+   * Number between -2.0 and 2.0. Positive values penalize new tokens based on
+   * whether they appear in the text so far, increasing the model's likelihood to
+   * talk about new topics.
+   */
+  presence_penalty?: number | null
+
+  /**
+   * Controls reasoning effort for supported models.
+   *
+   * - qwen3 models: `'none'` to disable, `'default'` or null to enable
+   * - openai/gpt-oss models: `'low'`, `'medium'` (default), or `'high'`
+   */
+  reasoning_effort?: 'none' | 'default' | 'low' | 'medium' | 'high' | null
+
+  /**
+   * Specifies how to output reasoning tokens.
+   * This field is mutually exclusive with `include_reasoning`.
+   */
+  reasoning_format?: 'hidden' | 'raw' | 'parsed' | null
+
+  /**
+   * An object specifying the format that the model must output.
+   *
+   * - `json_schema` — enables Structured Outputs (preferred)
+   * - `json_object` — enables the older JSON mode
+   * - `text` — plain text output (default)
+   *
+   * @see https://console.groq.com/docs/structured-outputs
+   */
+  response_format?:
+    | ResponseFormatText
+    | ResponseFormatJsonSchema
+    | ResponseFormatJsonObject
+    | null
+
+  /** Settings for web search functionality when the model uses a web search tool. */
+  search_settings?: SearchSettings | null
+
+  /**
+   * If specified, our system will make a best effort to sample deterministically,
+   * such that repeated requests with the same `seed` and parameters should return
+   * the same result.
+   */
+  seed?: number | null
+
+  /**
+   * The service tier to use for the request.
+   *
+   * - `auto` — automatically select the highest tier available
+   * - `flex` — uses the flex tier, which will succeed or fail quickly
+   */
+  service_tier?: 'auto' | 'on_demand' | 'flex' | 'performance' | null
+
+  /**
+   * Up to 4 sequences where the API will stop generating further tokens.
+   * The returned text will not contain the stop sequence.
+   */
+  stop?: string | null | Array<string>
+
+  /** Whether to store the request for future use. */
+  store?: boolean | null
+
+  /**
+   * Sampling temperature between 0 and 2. Higher values like 0.8 will make the
+   * output more random, while lower values like 0.2 will make it more focused
+   * and deterministic. We generally recommend altering this or top_p but not both.
+   */
+  temperature?: number | null
+
+  /**
+   * Controls which (if any) tool is called by the model.
+   *
+   * - `none` — never call tools
+   * - `auto` — model decides (default when tools are present)
+   * - `required` — model must call tools
+   * - Named choice — forces a specific tool
+   */
+  tool_choice?: ChatCompletionToolChoiceOption | null
+
+  /**
+   * An integer between 0 and 20 specifying the number of most likely tokens to
+   * return at each token position. `logprobs` must be set to `true` if this
+   * parameter is used.
+   */
+  top_logprobs?: number | null
+
+  /**
+   * An alternative to sampling with temperature, called nucleus sampling, where the
+   * model considers the results of the tokens with top_p probability mass. So 0.1
+   * means only the tokens comprising the top 10% probability mass are considered.
+   */
+  top_p?: number | null
+
+  /**
+   * A unique identifier representing your end-user, which can help monitor and
+   * detect abuse.
+   */
+  user?: string | null
+}
+
+/**
+ * Internal options interface used for validation within the adapter.
+ * Extends provider options with required fields for API requests.
+ */
+export interface InternalTextProviderOptions extends GroqTextProviderOptions {
+  /** An array of messages comprising the conversation. */
+  messages: Array<ChatCompletionMessageParam>
+
+  /**
+   * The model name (e.g. "llama-3.3-70b-versatile", "openai/gpt-oss-120b").
+   * @see https://console.groq.com/docs/models
+   */
+  model: string
+
+  /** Whether to stream partial message deltas as server-sent events. */
+  stream?: boolean | null
+
+  /**
+   * Tools the model may call (functions, code_interpreter, etc).
+   * @see https://console.groq.com/docs/tool-use
+   */
+  tools?: Array<ChatCompletionTool>
+}
+
+/**
+ * External provider options (what users pass in)
+ */
+export type ExternalTextProviderOptions = GroqTextProviderOptions
+
+/**
+ * Validates text provider options.
+ * Basic validation stub — Groq API handles detailed validation.
+ */
+export function validateTextProviderOptions(
+  _options: InternalTextProviderOptions,
+): void {
+  // Groq API handles detailed validation
+}

package/src/tools/function-tool.ts

@@ -0,0 +1,44 @@
+import { makeGroqStructuredOutputCompatible } from '../utils/schema-converter'
+import type { JSONSchema, Tool } from '@tanstack/ai'
+import type { ChatCompletionTool } from '../message-types'
+
+export type FunctionTool = ChatCompletionTool
+
+/**
+ * Converts a standard Tool to Groq ChatCompletionTool format.
+ *
+ * Tool schemas are already converted to JSON Schema in the ai layer.
+ * We apply Groq-specific transformations for strict mode:
+ * - All properties in required array
+ * - Optional fields made nullable
+ * - additionalProperties: false
+ */
+export function convertFunctionToolToAdapterFormat(tool: Tool): FunctionTool {
+  const inputSchema = (tool.inputSchema ?? {
+    type: 'object',
+    properties: {},
+    required: [],
+  }) as JSONSchema
+
+  // Ensure object schemas always have properties (e.g. z.object({}) may produce { type: 'object' } without properties)
+  if (inputSchema.type === 'object' && !inputSchema.properties) {
+    inputSchema.properties = {}
+  }
+
+  const jsonSchema = makeGroqStructuredOutputCompatible(
+    inputSchema,
+    inputSchema.required || [],
+  )
+
+  jsonSchema.additionalProperties = false
+
+  return {
+    type: 'function',
+    function: {
+      name: tool.name,
+      description: tool.description,
+      parameters: jsonSchema,
+      strict: true,
+    },
+  } satisfies FunctionTool
+}

package/src/tools/index.ts

@@ -0,0 +1,5 @@
+export {
+  convertFunctionToolToAdapterFormat,
+  type FunctionTool,
+} from './function-tool'
+export { convertToolsToProviderFormat } from './tool-converter'

package/src/tools/tool-converter.ts

@@ -0,0 +1,15 @@
+import { convertFunctionToolToAdapterFormat } from './function-tool'
+import type { FunctionTool } from './function-tool'
+import type { Tool } from '@tanstack/ai'
+
+/**
+ * Converts an array of standard Tools to Groq-specific format.
+ * Groq uses an OpenAI-compatible API, so we primarily support function tools.
+ */
+export function convertToolsToProviderFormat(
+  tools: Array<Tool>,
+): Array<FunctionTool> {
+  return tools.map((tool) => {
+    return convertFunctionToolToAdapterFormat(tool)
+  })
+}

package/src/utils/client.ts

@@ -0,0 +1,42 @@
+import Groq_SDK from 'groq-sdk'
+import type { ClientOptions } from 'groq-sdk'
+
+export interface GroqClientConfig extends ClientOptions {
+  apiKey: string
+}
+
+/**
+ * Creates a Groq SDK client instance
+ */
+export function createGroqClient(config: GroqClientConfig): Groq_SDK {
+  return new Groq_SDK(config)
+}
+
+/**
+ * Gets Groq API key from environment variables
+ * @throws Error if GROQ_API_KEY is not found
+ */
+export function getGroqApiKeyFromEnv(): string {
+  const env =
+    typeof globalThis !== 'undefined' && (globalThis as any).window?.env
+      ? (globalThis as any).window.env
+      : typeof process !== 'undefined'
+        ? process.env
+        : undefined
+  const key = env?.GROQ_API_KEY
+
+  if (!key) {
+    throw new Error(
+      'GROQ_API_KEY is required. Please set it in your environment variables or use the factory function with an explicit API key.',
+    )
+  }
+
+  return key
+}
+
+/**
+ * Generates a unique ID with a prefix
+ */
+export function generateId(prefix: string): string {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(7)}`
+}