@tanstack/ai-groq 0.1.11 → 0.2.1

package/src/message-types.ts

@@ -1,72 +1,22 @@
 /**
  * Groq-specific message types for the Chat Completions API.
  *
- * These type definitions mirror the Groq SDK types and are used internally
- * by the adapter to avoid tight coupling to the SDK's exported types.
+ * Groq's wire format is OpenAI Chat Completions plus a few Groq-specific
+ * extensions (compound tools, citation/service-tier provider options,
+ * etc.). These type definitions describe that wire shape directly — the
+ * Groq SDK was dropped in favour of pointing the OpenAI SDK at Groq's
+ * `/openai/v1` base URL, so this file is the source of truth for
+ * Groq-only fields rather than a mirror of an external SDK's types.
  *
  * @see https://console.groq.com/docs/api-reference#chat
  */
 
-export interface ChatCompletionContentPartText {
-  /** The text content. */
-  text: string
-
-  /** The type of the content part. */
-  type: 'text'
-}
-
-export interface ChatCompletionContentPartImage {
-  image_url: {
-    /** Either a URL of the image or the base64 encoded image data. */
-    url: string
-
-    /** Specifies the detail level of the image. */
-    detail?: 'auto' | 'low' | 'high'
-  }
-
-  /** The type of the content part. */
-  type: 'image_url'
-}
-
-export interface ChatCompletionMessageToolCall {
-  /** The ID of the tool call. */
-  id: string
-
-  /** The function that the model called. */
-  function: {
-    /**
-     * The arguments to call the function with, as generated by the model in JSON
-     * format. Note that the model does not always generate valid JSON, and may
-     * hallucinate parameters not defined by your function schema. Validate the
-     * arguments in your code before calling your function.
-     */
-    arguments: string
-
-    /** The name of the function to call. */
-    name: string
-  }
-
-  /** The type of the tool. Currently, only `function` is supported. */
-  type: 'function'
-}
-
-export interface ChatCompletionRequestMessageContentPartDocument {
-  document: {
-    /** The JSON document data. */
-    data: { [key: string]: unknown }
-
-    /** Optional unique identifier for the document. */
-    id?: string | null
-  }
-
-  /** The type of the content part. */
-  type: 'document'
-}
-
 export type FunctionParameters = { [key: string]: unknown }
 
 export interface ChatCompletionNamedToolChoice {
-  Function: {
+  /** Always `function` for a named tool choice. */
+  type: 'function'
+  function: {
     /** The name of the function to call. */
     name: string
   }
@@ -113,34 +63,6 @@ export type ChatCompletionToolChoiceOption =
   | 'required'
   | ChatCompletionNamedToolChoice
 
-export type ChatCompletionContentPart =
-  | ChatCompletionContentPartText
-  | ChatCompletionContentPartImage
-  | ChatCompletionRequestMessageContentPartDocument
-
-export interface ChatCompletionAssistantMessageParam {
-  /** The role of the messages author, in this case `assistant`. */
-  role: 'assistant'
-
-  /**
-   * The contents of the assistant message. Required unless `tool_calls` or
-   * `function_call` is specified.
-   */
-  content?: string | Array<ChatCompletionContentPartText> | null
-
-  /** An optional name for the participant. */
-  name?: string
-
-  /**
-   * The reasoning output by the assistant if reasoning_format was set to 'parsed'.
-   * This field is only useable with qwen3 models.
-   */
-  reasoning?: string | null
-
-  /** The tool calls generated by the model, such as function calls. */
-  tool_calls?: Array<ChatCompletionMessageToolCall>
-}
-
 export interface ChatCompletionTool {
   /**
    * The type of the tool. `function`, `browser_search`, and `code_interpreter` are
@@ -151,48 +73,6 @@ export interface ChatCompletionTool {
   function?: FunctionDefinition
 }
 
-export interface ChatCompletionToolMessageParam {
-  /** The contents of the tool message. */
-  content: string | Array<ChatCompletionContentPart>
-
-  /** The role of the messages author, in this case `tool`. */
-  role: 'tool'
-
-  /** Tool call that this message is responding to. */
-  tool_call_id: string
-}
-
-export interface ChatCompletionSystemMessageParam {
-  /** The contents of the system message. */
-  content: string | Array<ChatCompletionContentPartText>
-
-  /** The role of the messages author, in this case `system`. */
-  role: 'system' | 'developer'
-
-  /** An optional name for the participant. */
-  name?: string
-}
-
-export interface ChatCompletionUserMessageParam {
-  /** The contents of the user message. */
-  content: string | Array<ChatCompletionContentPart>
-
-  /** The role of the messages author, in this case `user`. */
-  role: 'user'
-
-  /** An optional name for the participant. */
-  name?: string
-}
-
-/**
- * Union of all supported chat completion message params.
- */
-export type ChatCompletionMessageParam =
-  | ChatCompletionSystemMessageParam
-  | ChatCompletionUserMessageParam
-  | ChatCompletionAssistantMessageParam
-  | ChatCompletionToolMessageParam
-
 export interface CompoundCustomModels {
   /** Custom model to use for answering. */
   answering_model?: string | null

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

@@ -1,6 +1,4 @@
 import type {
-  ChatCompletionMessageParam,
-  ChatCompletionTool,
   ChatCompletionToolChoiceOption,
   CompoundCustom,
   Document,
@@ -185,41 +183,7 @@ export interface GroqTextProviderOptions {
   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/utils/client.ts

@@ -1,29 +1,32 @@
-import { generateId as _generateId, getApiKeyFromEnv } from '@tanstack/ai-utils'
-import Groq_SDK from 'groq-sdk'
-import type { ClientOptions } from 'groq-sdk'
+import { getApiKeyFromEnv } from '@tanstack/ai-utils'
+import type { ClientOptions } from 'openai'
 
-export interface GroqClientConfig extends ClientOptions {
+export interface GroqClientConfig extends Omit<ClientOptions, 'apiKey'> {
   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 {
-  return getApiKeyFromEnv('GROQ_API_KEY')
+  try {
+    return getApiKeyFromEnv('GROQ_API_KEY')
+  } catch {
+    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.',
+    )
+  }
 }
 
 /**
- * Generates a unique ID with a prefix
+ * Returns a Groq client config with Groq's OpenAI-compatible base URL
+ * applied when not already set. The Groq endpoint accepts the OpenAI SDK
+ * verbatim, so the adapter drives it via the OpenAI SDK with this baseURL.
  */
-export function generateId(prefix: string): string {
-  return _generateId(prefix)
+export function withGroqDefaults(config: GroqClientConfig): GroqClientConfig {
+  return {
+    ...config,
+    baseURL: config.baseURL || 'https://api.groq.com/openai/v1',
+  }
 }

package/src/utils/index.ts

@@ -1,9 +1,9 @@
 export {
-  createGroqClient,
   getGroqApiKeyFromEnv,
-  generateId,
+  withGroqDefaults,
   type GroqClientConfig,
 } from './client'
+export { generateId } from '@tanstack/ai-utils'
 export {
   makeGroqStructuredOutputCompatible,
   transformNullsToUndefined,

package/src/utils/schema-converter.ts

@@ -62,7 +62,7 @@ function removeEmptyRequired(schema: Record<string, any>): Record<string, any> {
 /**
  * Recursively normalise object schemas so any `{ type: 'object' }` node
  * without `properties` gets an empty `properties: {}` object. The
- * openai-base transformer only descends into objects that already have
+ * ai-openai-base transformer only descends into objects that already have
  * `properties` set, so a Zod `z.object({})` nested inside `properties`,
  * `items`, `additionalProperties`, or a combinator branch would otherwise
  * skip the strict-mode rewrite and fail Groq validation.
@@ -140,7 +140,7 @@ export function makeGroqStructuredOutputCompatible(
   schema: Record<string, any>,
   originalRequired: Array<string> = [],
 ): Record<string, any> {
-  // Recursively patch every `{ type: 'object' }` node so the openai-base
+  // Recursively patch every `{ type: 'object' }` node so the ai-openai-base
   // transformer descends into nested empty objects too.
   const normalised = normalizeObjectSchemas(schema)
 

package/dist/esm/text/text-provider-options.js

@@ -1,6 +0,0 @@
-function validateTextProviderOptions(_options) {
-}
-export {
-  validateTextProviderOptions
-};
-//# sourceMappingURL=text-provider-options.js.map

package/dist/esm/text/text-provider-options.js.map

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