feat(ai-groq): Add Groq adapter package (TanStack#332)

* feat(ai-groq): Add Groq adapter package

Adds a new `@tanstack/ai-groq` package for Groq AI model integration.
This package provides a tree-shakeable text adapter, supporting
streaming chat completions, structured output, and tool usage.

* chore: fix issues with PR

* ci: apply automated fixes

---------

Co-authored-by: Alem Tuzlak <t.zlak@hotmail.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>

Author: 3 people

.changeset/free-impalas-doubt.md

@@ -0,0 +1,5 @@
+---
+'@tanstack/ai-groq': minor
+---
+
+Adds a new @tanstack/ai-groq package(minor release), a Groq AI adapter for TanStack AI.

examples/ts-react-chat/package.json

@@ -15,6 +15,7 @@
     "@tanstack/ai-client": "workspace:*",
     "@tanstack/ai-gemini": "workspace:*",
     "@tanstack/ai-grok": "workspace:*",
+    "@tanstack/ai-groq": "workspace:*",
     "@tanstack/ai-ollama": "workspace:*",
     "@tanstack/ai-openai": "workspace:*",
     "@tanstack/ai-openrouter": "workspace:*",

examples/ts-react-chat/src/lib/model-selection.ts

@@ -4,6 +4,7 @@ export type Provider =
   | 'gemini'
   | 'ollama'
   | 'grok'
+  | 'groq'
   | 'openrouter'
 
 export interface ModelOption {
@@ -91,6 +92,23 @@ export const MODEL_OPTIONS: Array<ModelOption> = [
     label: 'Ollama - SmolLM',
   },
 
+  // Groq
+  {
+    provider: 'groq',
+    model: 'llama-3.3-70b-versatile',
+    label: 'Groq - Llama 3.3 70B',
+  },
+  {
+    provider: 'groq',
+    model: 'meta-llama/llama-4-maverick-17b-128e-instruct',
+    label: 'Groq - Llama 4 Maverick',
+  },
+  {
+    provider: 'groq',
+    model: 'meta-llama/llama-4-scout-17b-16e-instruct',
+    label: 'Groq - Llama 4 Scout',
+  },
+
   // Grok
   {
     provider: 'grok',

examples/ts-react-chat/src/routes/api.tanchat.ts

@@ -11,6 +11,7 @@ import { anthropicText } from '@tanstack/ai-anthropic'
 import { geminiText } from '@tanstack/ai-gemini'
 import { openRouterText } from '@tanstack/ai-openrouter'
 import { grokText } from '@tanstack/ai-grok'
+import { groqText } from '@tanstack/ai-groq'
 import type { AnyTextAdapter } from '@tanstack/ai'
 import {
   addToCartToolDef,
@@ -26,6 +27,7 @@ type Provider =
   | 'gemini'
   | 'ollama'
   | 'grok'
+  | 'groq'
   | 'openrouter'
 
 const SYSTEM_PROMPT = `You are a helpful assistant for a guitar store.
@@ -131,6 +133,13 @@ export const Route = createFileRoute('/api/tanchat')({
               adapter: grokText((model || 'grok-3') as 'grok-3'),
               modelOptions: {},
             }),
+          groq: () =>
+            createChatOptions({
+              adapter: groqText(
+                (model ||
+                  'llama-3.3-70b-versatile') as 'llama-3.3-70b-versatile',
+              ),
+            }),
           ollama: () =>
             createChatOptions({
               adapter: ollamaText((model || 'gpt-oss:120b') as 'gpt-oss:120b'),

examples/ts-react-chat/src/routes/index.tsx

@@ -264,19 +264,25 @@ function ChatPage() {
     [selectedModel.provider, selectedModel.model],
   )
 
-  const { messages, sendMessage, isLoading, addToolApprovalResponse, stop } =
-    useChat({
-      connection: fetchServerSentEvents('/api/tanchat'),
-      tools,
-      body,
-      onCustomEvent: (eventType, data, context) => {
-        console.log(
-          `[CustomEvent] ${eventType}`,
-          data,
-          context.toolCallId ? `(tool call: ${context.toolCallId})` : '',
-        )
-      },
-    })
+  const {
+    messages,
+    sendMessage,
+    isLoading,
+    error,
+    addToolApprovalResponse,
+    stop,
+  } = useChat({
+    connection: fetchServerSentEvents('/api/tanchat'),
+    tools,
+    body,
+    onCustomEvent: (eventType, data, context) => {
+      console.log(
+        `[CustomEvent] ${eventType}`,
+        data,
+        context.toolCallId ? `(tool call: ${context.toolCallId})` : '',
+      )
+    },
+  })
   const [input, setInput] = useState('')
 
   /**
@@ -415,6 +421,12 @@ function ChatPage() {
           addToolApprovalResponse={addToolApprovalResponse}
         />
 
+        {error && (
+          <div className="mx-4 mt-2 p-3 bg-red-500/10 border border-red-500/30 rounded-lg text-red-400 text-sm">
+            {error.message}
+          </div>
+        )}
+
         <ChatInputArea>
           <div className="space-y-3">
             {isLoading && (

packages/typescript/ai-groq/README.md

@@ -0,0 +1,91 @@
+# @tanstack/ai-groq
+
+Groq adapter for TanStack AI
+
+## Installation
+
+```bash
+npm install @tanstack/ai-groq
+# or
+pnpm add @tanstack/ai-groq
+# or
+yarn add @tanstack/ai-groq
+```
+
+## Setup
+
+Get your API key from [Groq Console](https://console.groq.com) and set it as an environment variable:
+
+```bash
+export GROQ_API_KEY="gsk_..."
+```
+
+## Usage
+
+### Text/Chat Adapter
+
+```typescript
+import { groqText } from '@tanstack/ai-groq'
+import { generate } from '@tanstack/ai'
+
+const adapter = groqText('llama-3.3-70b-versatile')
+
+const result = await generate({
+  adapter,
+  model: 'llama-3.3-70b-versatile',
+  messages: [
+    { role: 'user', content: 'Explain quantum computing in simple terms' },
+  ],
+})
+
+console.log(result.text)
+```
+
+### With Explicit API Key
+
+```typescript
+import { createGroqText } from '@tanstack/ai-groq'
+
+const adapter = createGroqText('llama-3.3-70b-versatile', 'gsk_api_key')
+```
+
+## Supported Models
+
+### Chat Models
+
+- `llama-3.3-70b-versatile` - Meta Llama 3.3 70B (131k context)
+- `llama-3.1-8b-instant` - Meta Llama 3.1 8B (131k context)
+- `meta-llama/llama-4-maverick-17b-128e-instruct` - Meta Llama 4 Maverick (vision)
+- `meta-llama/llama-4-scout-17b-16e-instruct` - Meta Llama 4 Scout
+- `meta-llama/llama-guard-4-12b` - Meta Llama Guard 4 (content moderation, vision)
+- `meta-llama/llama-prompt-guard-2-86m` - Meta Llama Prompt Guard (content moderation)
+- `meta-llama/llama-prompt-guard-2-22m` - Meta Llama Prompt Guard (content moderation)
+- `openai/gpt-oss-120b` - GPT OSS 120B (reasoning, tools, search)
+- `openai/gpt-oss-20b` - GPT OSS 20B (reasoning, search)
+- `openai/gpt-oss-safeguard-20b` - GPT OSS Safeguard 20B (content moderation, reasoning)
+- `moonshotai/kimi-k2-instruct-0905` - Kimi K2 Instruct (262k context)
+- `qwen/qwen3-32b` - Qwen3 32B (reasoning, tools)
+
+## Features
+
+- ✅ Streaming chat completions
+- ✅ Structured output (JSON Schema)
+- ✅ Function/tool calling
+- ✅ Multimodal input (text + images for vision models)
+- ❌ Embeddings (not supported by Groq)
+- ❌ Image generation (not supported by Groq)
+
+## Tree-Shakeable Adapters
+
+This package uses tree-shakeable adapters, so you only import what you need:
+
+```typescript
+// Only imports text adapter
+import { groqText } from '@tanstack/ai-groq'
+```
+
+This keeps your bundle size small!
+
+## License
+
+MIT

packages/typescript/ai-groq/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@tanstack/ai-groq",
+  "version": "0.0.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": "workspace:^",
+    "zod": "^4.0.0"
+  },
+  "dependencies": {
+    "groq-sdk": "^0.37.0"
+  }
+}