@tanstack/ai/skills/ai-core/adapter-configuration/references/groq-adapter.md

Type-safe TypeScript AI SDK for streaming chat, tool calling, agents, structured outputs, and multimodal generation.

# Groq Adapter Reference

## Package

```
@tanstack/ai-groq
```

## Adapter Factories

| Factory    | Type      | Description      |
| ---------- | --------- | ---------------- |
| `groqText` | Text/Chat | Chat completions |

Groq currently only has a text adapter (no image, TTS, etc.).

## Import

```typescript
import { groqText } from '@tanstack/ai-groq'
```

## Key Chat Models

| Model                 | Context Window | Notes                     |
| --------------------- | -------------- | ------------------------- |
| `openai/gpt-oss-120b` | 131K           | Reasoning, browser search |
| `openai/gpt-oss-20b`  | 131K           | Budget reasoning          |
| `qwen/qwen3.8-27b`    | 131K           | Reasoning, vision, tools  |

Guard models: `openai/gpt-oss-safeguard-20b`, `meta-llama/llama-prompt-guard-2-86m`,
`meta-llama/llama-prompt-guard-2-22m`

## Provider-Specific modelOptions

```typescript
import { chat } from '@tanstack/ai'
import { groqText } from '@tanstack/ai-groq'

const messages = [{ role: 'user' as const, content: 'Hello' }]

chat({
  adapter: groqText('openai/gpt-oss-120b'),
  messages,
  threadId: 'thread-1',
  modelOptions: {
    // Reasoning
    reasoning_format: 'parsed', // 'hidden' | 'raw' | 'parsed' (mutually exclusive with include_reasoning)
    include_reasoning: true, // mutually exclusive with reasoning_format
    // Response format
    response_format: {
      type: 'json_schema',
      json_schema: { name: 'answer', schema: {/* JSON Schema */} },
    },
    // Sampling
    temperature: 0.7,
    top_p: 0.9,
    frequency_penalty: 0.5,
    presence_penalty: 0.5,
    seed: 42,
    stop: ['\n\n'],
    // Token limits
    max_completion_tokens: 8192,
    // Tool calling
    tool_choice: 'auto',
    parallel_tool_calls: true,
    disable_tool_validation: false,
    // Citations
    citation_options: 'enabled',
    // Documents for context
    documents: [{ source: { type: 'text', text: '...' } }],
    // Search settings (for web search tool)
    search_settings: {/* SearchSettings */},
    // Service tier
    service_tier: 'auto', // 'auto' | 'on_demand' | 'flex' | 'performance'
    // Metadata
    metadata: { session: 'abc' },
    // Logging
    logprobs: true,
    top_logprobs: 5,
    // User tracking
    user: 'user-123',
  },
})
```

## Environment Variable

```
GROQ_API_KEY
```

## Gotchas

- `chat({ reasoning })` sends `reasoning_effort`. openai/gpt-oss and
  qwen/qwen3.8-27b models take `low`, `medium`, and `high`. qwen/qwen3.8-27b also
  takes `off` (sends `'none'`).
- `include_reasoning` and `reasoning_format` are mutually exclusive.
- Most models have `max_completion_tokens` of 8K-65K, not unlimited.
- Groq specializes in inference speed; model selection is more limited
  than other providers.
- Guard models (`gpt-oss-safeguard-20b`, `llama-prompt-guard-2-*`) are for
  content moderation, not general chat.