@tanstack/ai-groq 0.1.0

package/dist/esm/text/text-provider-options.d.ts

@@ -0,0 +1,179 @@
+import { ChatCompletionMessageParam, ChatCompletionTool, ChatCompletionToolChoiceOption, CompoundCustom, Document, ResponseFormatJsonObject, ResponseFormatJsonSchema, ResponseFormatText, SearchSettings } from '../message-types.js';
+/**
+ * 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 declare function validateTextProviderOptions(_options: InternalTextProviderOptions): void;

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

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

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

@@ -0,0 +1 @@
+{"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;"}

package/dist/esm/tools/function-tool.d.ts

@@ -0,0 +1,13 @@
+import { Tool } from '@tanstack/ai';
+import { ChatCompletionTool } from '../message-types.js';
+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 declare function convertFunctionToolToAdapterFormat(tool: Tool): FunctionTool;

package/dist/esm/tools/function-tool.js

@@ -0,0 +1,29 @@
+import { makeGroqStructuredOutputCompatible } from "../utils/schema-converter.js";
+function convertFunctionToolToAdapterFormat(tool) {
+  const inputSchema = tool.inputSchema ?? {
+    type: "object",
+    properties: {},
+    required: []
+  };
+  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
+    }
+  };
+}
+export {
+  convertFunctionToolToAdapterFormat
+};
+//# sourceMappingURL=function-tool.js.map

package/dist/esm/tools/function-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-tool.js","sources":["../../../src/tools/function-tool.ts"],"sourcesContent":["import { makeGroqStructuredOutputCompatible } from '../utils/schema-converter'\nimport type { JSONSchema, Tool } from '@tanstack/ai'\nimport type { ChatCompletionTool } from '../message-types'\n\nexport type FunctionTool = ChatCompletionTool\n\n/**\n * Converts a standard Tool to Groq ChatCompletionTool format.\n *\n * Tool schemas are already converted to JSON Schema in the ai layer.\n * We apply Groq-specific transformations for strict mode:\n * - All properties in required array\n * - Optional fields made nullable\n * - additionalProperties: false\n */\nexport function convertFunctionToolToAdapterFormat(tool: Tool): FunctionTool {\n  const inputSchema = (tool.inputSchema ?? {\n    type: 'object',\n    properties: {},\n    required: [],\n  }) as JSONSchema\n\n  // Ensure object schemas always have properties (e.g. z.object({}) may produce { type: 'object' } without properties)\n  if (inputSchema.type === 'object' && !inputSchema.properties) {\n    inputSchema.properties = {}\n  }\n\n  const jsonSchema = makeGroqStructuredOutputCompatible(\n    inputSchema,\n    inputSchema.required || [],\n  )\n\n  jsonSchema.additionalProperties = false\n\n  return {\n    type: 'function',\n    function: {\n      name: tool.name,\n      description: tool.description,\n      parameters: jsonSchema,\n      strict: true,\n    },\n  } satisfies FunctionTool\n}\n"],"names":[],"mappings":";AAeO,SAAS,mCAAmC,MAA0B;AAC3E,QAAM,cAAe,KAAK,eAAe;AAAA,IACvC,MAAM;AAAA,IACN,YAAY,CAAA;AAAA,IACZ,UAAU,CAAA;AAAA,EAAC;AAIb,MAAI,YAAY,SAAS,YAAY,CAAC,YAAY,YAAY;AAC5D,gBAAY,aAAa,CAAA;AAAA,EAC3B;AAEA,QAAM,aAAa;AAAA,IACjB;AAAA,IACA,YAAY,YAAY,CAAA;AAAA,EAAC;AAG3B,aAAW,uBAAuB;AAElC,SAAO;AAAA,IACL,MAAM;AAAA,IACN,UAAU;AAAA,MACR,MAAM,KAAK;AAAA,MACX,aAAa,KAAK;AAAA,MAClB,YAAY;AAAA,MACZ,QAAQ;AAAA,IAAA;AAAA,EACV;AAEJ;"}

package/dist/esm/tools/index.d.ts

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

package/dist/esm/tools/tool-converter.d.ts

@@ -0,0 +1,7 @@
+import { FunctionTool } from './function-tool.js';
+import { 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 declare function convertToolsToProviderFormat(tools: Array<Tool>): Array<FunctionTool>;

package/dist/esm/tools/tool-converter.js

@@ -0,0 +1,10 @@
+import { convertFunctionToolToAdapterFormat } from "./function-tool.js";
+function convertToolsToProviderFormat(tools) {
+  return tools.map((tool) => {
+    return convertFunctionToolToAdapterFormat(tool);
+  });
+}
+export {
+  convertToolsToProviderFormat
+};
+//# sourceMappingURL=tool-converter.js.map

package/dist/esm/tools/tool-converter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-converter.js","sources":["../../../src/tools/tool-converter.ts"],"sourcesContent":["import { convertFunctionToolToAdapterFormat } from './function-tool'\nimport type { FunctionTool } from './function-tool'\nimport type { Tool } from '@tanstack/ai'\n\n/**\n * Converts an array of standard Tools to Groq-specific format.\n * Groq uses an OpenAI-compatible API, so we primarily support function tools.\n */\nexport function convertToolsToProviderFormat(\n  tools: Array<Tool>,\n): Array<FunctionTool> {\n  return tools.map((tool) => {\n    return convertFunctionToolToAdapterFormat(tool)\n  })\n}\n"],"names":[],"mappings":";AAQO,SAAS,6BACd,OACqB;AACrB,SAAO,MAAM,IAAI,CAAC,SAAS;AACzB,WAAO,mCAAmC,IAAI;AAAA,EAChD,CAAC;AACH;"}

package/dist/esm/utils/client.d.ts

@@ -0,0 +1,17 @@
+import { default as Groq_SDK, ClientOptions } from 'groq-sdk';
+export interface GroqClientConfig extends ClientOptions {
+    apiKey: string;
+}
+/**
+ * Creates a Groq SDK client instance
+ */
+export declare function createGroqClient(config: GroqClientConfig): Groq_SDK;
+/**
+ * Gets Groq API key from environment variables
+ * @throws Error if GROQ_API_KEY is not found
+ */
+export declare function getGroqApiKeyFromEnv(): string;
+/**
+ * Generates a unique ID with a prefix
+ */
+export declare function generateId(prefix: string): string;

package/dist/esm/utils/client.js

@@ -0,0 +1,23 @@
+import Groq_SDK from "groq-sdk";
+function createGroqClient(config) {
+  return new Groq_SDK(config);
+}
+function getGroqApiKeyFromEnv() {
+  const env = typeof globalThis !== "undefined" && globalThis.window?.env ? globalThis.window.env : typeof process !== "undefined" ? process.env : void 0;
+  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;
+}
+function generateId(prefix) {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+}
+export {
+  createGroqClient,
+  generateId,
+  getGroqApiKeyFromEnv
+};
+//# sourceMappingURL=client.js.map

package/dist/esm/utils/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sources":["../../../src/utils/client.ts"],"sourcesContent":["import Groq_SDK from 'groq-sdk'\nimport type { ClientOptions } from 'groq-sdk'\n\nexport interface GroqClientConfig extends ClientOptions {\n  apiKey: string\n}\n\n/**\n * Creates a Groq SDK client instance\n */\nexport function createGroqClient(config: GroqClientConfig): Groq_SDK {\n  return new Groq_SDK(config)\n}\n\n/**\n * Gets Groq API key from environment variables\n * @throws Error if GROQ_API_KEY is not found\n */\nexport function getGroqApiKeyFromEnv(): string {\n  const env =\n    typeof globalThis !== 'undefined' && (globalThis as any).window?.env\n      ? (globalThis as any).window.env\n      : typeof process !== 'undefined'\n        ? process.env\n        : undefined\n  const key = env?.GROQ_API_KEY\n\n  if (!key) {\n    throw new Error(\n      'GROQ_API_KEY is required. Please set it in your environment variables or use the factory function with an explicit API key.',\n    )\n  }\n\n  return key\n}\n\n/**\n * Generates a unique ID with a prefix\n */\nexport function generateId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n}\n"],"names":[],"mappings":";AAUO,SAAS,iBAAiB,QAAoC;AACnE,SAAO,IAAI,SAAS,MAAM;AAC5B;AAMO,SAAS,uBAA+B;AAC7C,QAAM,MACJ,OAAO,eAAe,eAAgB,WAAmB,QAAQ,MAC5D,WAAmB,OAAO,MAC3B,OAAO,YAAY,cACjB,QAAQ,MACR;AACR,QAAM,MAAM,KAAK;AAEjB,MAAI,CAAC,KAAK;AACR,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAEJ;AAEA,SAAO;AACT;AAKO,SAAS,WAAW,QAAwB;AACjD,SAAO,GAAG,MAAM,IAAI,KAAK,KAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,UAAU,CAAC,CAAC;AAC3E;"}

package/dist/esm/utils/index.d.ts

@@ -0,0 +1,2 @@
+export { createGroqClient, getGroqApiKeyFromEnv, generateId, type GroqClientConfig, } from './client.js';
+export { makeGroqStructuredOutputCompatible, transformNullsToUndefined, } from './schema-converter.js';

package/dist/esm/utils/schema-converter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Recursively transform null values to undefined in an object.
+ *
+ * This is needed because Groq's structured output requires all fields to be
+ * in the `required` array, with optional fields made nullable (type: ["string", "null"]).
+ * When Groq returns null for optional fields, we need to convert them back to
+ * undefined to match the original Zod schema expectations.
+ *
+ * @param obj - Object to transform
+ * @returns Object with nulls converted to undefined
+ */
+export declare function transformNullsToUndefined<T>(obj: T): T;
+/**
+ * Transform a JSON schema to be compatible with Groq's structured output requirements.
+ *
+ * Groq requires:
+ * - All properties must be in the `required` array
+ * - Optional fields should have null added to their type union
+ * - additionalProperties must be false for objects
+ *
+ * @param schema - JSON schema to transform
+ * @param originalRequired - Original required array (to know which fields were optional)
+ * @returns Transformed schema compatible with Groq structured output
+ */
+export declare function makeGroqStructuredOutputCompatible(schema: Record<string, any>, originalRequired?: Array<string>): Record<string, any>;

package/dist/esm/utils/schema-converter.js

@@ -0,0 +1,78 @@
+function transformNullsToUndefined(obj) {
+  if (obj === null) {
+    return void 0;
+  }
+  if (Array.isArray(obj)) {
+    return obj.map((item) => transformNullsToUndefined(item));
+  }
+  if (typeof obj === "object") {
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+      const transformed = transformNullsToUndefined(value);
+      if (transformed !== void 0) {
+        result[key] = transformed;
+      }
+    }
+    return result;
+  }
+  return obj;
+}
+function makeGroqStructuredOutputCompatible(schema, originalRequired = []) {
+  const result = { ...schema };
+  if (result.type === "object") {
+    if (!result.properties) {
+      result.properties = {};
+    }
+    const properties = { ...result.properties };
+    const allPropertyNames = Object.keys(properties);
+    for (const propName of allPropertyNames) {
+      const prop = properties[propName];
+      const wasOptional = !originalRequired.includes(propName);
+      if (prop.type === "object" && prop.properties) {
+        properties[propName] = makeGroqStructuredOutputCompatible(
+          prop,
+          prop.required || []
+        );
+      } else if (prop.type === "array" && prop.items) {
+        properties[propName] = {
+          ...prop,
+          items: makeGroqStructuredOutputCompatible(
+            prop.items,
+            prop.items.required || []
+          )
+        };
+      } else if (wasOptional) {
+        if (prop.type && !Array.isArray(prop.type)) {
+          properties[propName] = {
+            ...prop,
+            type: [prop.type, "null"]
+          };
+        } else if (Array.isArray(prop.type) && !prop.type.includes("null")) {
+          properties[propName] = {
+            ...prop,
+            type: [...prop.type, "null"]
+          };
+        }
+      }
+    }
+    result.properties = properties;
+    if (allPropertyNames.length > 0) {
+      result.required = allPropertyNames;
+    } else {
+      delete result.required;
+    }
+    result.additionalProperties = false;
+  }
+  if (result.type === "array" && result.items) {
+    result.items = makeGroqStructuredOutputCompatible(
+      result.items,
+      result.items.required || []
+    );
+  }
+  return result;
+}
+export {
+  makeGroqStructuredOutputCompatible,
+  transformNullsToUndefined
+};
+//# sourceMappingURL=schema-converter.js.map

package/dist/esm/utils/schema-converter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-converter.js","sources":["../../../src/utils/schema-converter.ts"],"sourcesContent":["/**\n * Recursively transform null values to undefined in an object.\n *\n * This is needed because Groq's structured output requires all fields to be\n * in the `required` array, with optional fields made nullable (type: [\"string\", \"null\"]).\n * When Groq returns null for optional fields, we need to convert them back to\n * undefined to match the original Zod schema expectations.\n *\n * @param obj - Object to transform\n * @returns Object with nulls converted to undefined\n */\nexport function transformNullsToUndefined<T>(obj: T): T {\n  if (obj === null) {\n    return undefined as unknown as T\n  }\n\n  if (Array.isArray(obj)) {\n    return obj.map((item) => transformNullsToUndefined(item)) as unknown as T\n  }\n\n  if (typeof obj === 'object') {\n    const result: Record<string, unknown> = {}\n    for (const [key, value] of Object.entries(obj as Record<string, unknown>)) {\n      const transformed = transformNullsToUndefined(value)\n      if (transformed !== undefined) {\n        result[key] = transformed\n      }\n    }\n    return result as T\n  }\n\n  return obj\n}\n\n/**\n * Transform a JSON schema to be compatible with Groq's structured output requirements.\n *\n * Groq requires:\n * - All properties must be in the `required` array\n * - Optional fields should have null added to their type union\n * - additionalProperties must be false for objects\n *\n * @param schema - JSON schema to transform\n * @param originalRequired - Original required array (to know which fields were optional)\n * @returns Transformed schema compatible with Groq structured output\n */\nexport function makeGroqStructuredOutputCompatible(\n  schema: Record<string, any>,\n  originalRequired: Array<string> = [],\n): Record<string, any> {\n  const result = { ...schema }\n\n  if (result.type === 'object') {\n    if (!result.properties) {\n      result.properties = {}\n    }\n    const properties = { ...result.properties }\n    const allPropertyNames = Object.keys(properties)\n\n    for (const propName of allPropertyNames) {\n      const prop = properties[propName]\n      const wasOptional = !originalRequired.includes(propName)\n\n      if (prop.type === 'object' && prop.properties) {\n        properties[propName] = makeGroqStructuredOutputCompatible(\n          prop,\n          prop.required || [],\n        )\n      } else if (prop.type === 'array' && prop.items) {\n        properties[propName] = {\n          ...prop,\n          items: makeGroqStructuredOutputCompatible(\n            prop.items,\n            prop.items.required || [],\n          ),\n        }\n      } else if (wasOptional) {\n        if (prop.type && !Array.isArray(prop.type)) {\n          properties[propName] = {\n            ...prop,\n            type: [prop.type, 'null'],\n          }\n        } else if (Array.isArray(prop.type) && !prop.type.includes('null')) {\n          properties[propName] = {\n            ...prop,\n            type: [...prop.type, 'null'],\n          }\n        }\n      }\n    }\n\n    result.properties = properties\n    // Groq rejects `required` when there are no properties, even if it's an empty array\n    if (allPropertyNames.length > 0) {\n      result.required = allPropertyNames\n    } else {\n      delete result.required\n    }\n    result.additionalProperties = false\n  }\n\n  if (result.type === 'array' && result.items) {\n    result.items = makeGroqStructuredOutputCompatible(\n      result.items,\n      result.items.required || [],\n    )\n  }\n\n  return result\n}\n"],"names":[],"mappings":"AAWO,SAAS,0BAA6B,KAAW;AACtD,MAAI,QAAQ,MAAM;AAChB,WAAO;AAAA,EACT;AAEA,MAAI,MAAM,QAAQ,GAAG,GAAG;AACtB,WAAO,IAAI,IAAI,CAAC,SAAS,0BAA0B,IAAI,CAAC;AAAA,EAC1D;AAEA,MAAI,OAAO,QAAQ,UAAU;AAC3B,UAAM,SAAkC,CAAA;AACxC,eAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,GAA8B,GAAG;AACzE,YAAM,cAAc,0BAA0B,KAAK;AACnD,UAAI,gBAAgB,QAAW;AAC7B,eAAO,GAAG,IAAI;AAAA,MAChB;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAEA,SAAO;AACT;AAcO,SAAS,mCACd,QACA,mBAAkC,IACb;AACrB,QAAM,SAAS,EAAE,GAAG,OAAA;AAEpB,MAAI,OAAO,SAAS,UAAU;AAC5B,QAAI,CAAC,OAAO,YAAY;AACtB,aAAO,aAAa,CAAA;AAAA,IACtB;AACA,UAAM,aAAa,EAAE,GAAG,OAAO,WAAA;AAC/B,UAAM,mBAAmB,OAAO,KAAK,UAAU;AAE/C,eAAW,YAAY,kBAAkB;AACvC,YAAM,OAAO,WAAW,QAAQ;AAChC,YAAM,cAAc,CAAC,iBAAiB,SAAS,QAAQ;AAEvD,UAAI,KAAK,SAAS,YAAY,KAAK,YAAY;AAC7C,mBAAW,QAAQ,IAAI;AAAA,UACrB;AAAA,UACA,KAAK,YAAY,CAAA;AAAA,QAAC;AAAA,MAEtB,WAAW,KAAK,SAAS,WAAW,KAAK,OAAO;AAC9C,mBAAW,QAAQ,IAAI;AAAA,UACrB,GAAG;AAAA,UACH,OAAO;AAAA,YACL,KAAK;AAAA,YACL,KAAK,MAAM,YAAY,CAAA;AAAA,UAAC;AAAA,QAC1B;AAAA,MAEJ,WAAW,aAAa;AACtB,YAAI,KAAK,QAAQ,CAAC,MAAM,QAAQ,KAAK,IAAI,GAAG;AAC1C,qBAAW,QAAQ,IAAI;AAAA,YACrB,GAAG;AAAA,YACH,MAAM,CAAC,KAAK,MAAM,MAAM;AAAA,UAAA;AAAA,QAE5B,WAAW,MAAM,QAAQ,KAAK,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,MAAM,GAAG;AAClE,qBAAW,QAAQ,IAAI;AAAA,YACrB,GAAG;AAAA,YACH,MAAM,CAAC,GAAG,KAAK,MAAM,MAAM;AAAA,UAAA;AAAA,QAE/B;AAAA,MACF;AAAA,IACF;AAEA,WAAO,aAAa;AAEpB,QAAI,iBAAiB,SAAS,GAAG;AAC/B,aAAO,WAAW;AAAA,IACpB,OAAO;AACL,aAAO,OAAO;AAAA,IAChB;AACA,WAAO,uBAAuB;AAAA,EAChC;AAEA,MAAI,OAAO,SAAS,WAAW,OAAO,OAAO;AAC3C,WAAO,QAAQ;AAAA,MACb,OAAO;AAAA,MACP,OAAO,MAAM,YAAY,CAAA;AAAA,IAAC;AAAA,EAE9B;AAEA,SAAO;AACT;"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@tanstack/ai-groq",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Groq adapter for TanStack AI",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/typescript/ai-groq"
+  },
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "eslint ./src --fix",
+    "test:build": "publint --strict",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest run",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  },
+  "keywords": [
+    "ai",
+    "groq",
+    "tanstack",
+    "adapter"
+  ],
+  "devDependencies": {
+    "@vitest/coverage-v8": "4.0.14",
+    "vite": "^7.2.7"
+  },
+  "peerDependencies": {
+    "@tanstack/ai": "^0.6.3",
+    "zod": "^4.0.0"
+  },
+  "dependencies": {
+    "groq-sdk": "^0.37.0"
+  }
+}