| name | groq-sdk-patterns |
| description | Apply production-ready Groq SDK patterns for TypeScript and Python.
Use when implementing Groq integrations, refactoring SDK usage,
or establishing team coding standards for Groq.
Trigger with phrases like "groq SDK patterns", "groq best practices",
"groq code patterns", "idiomatic groq".
|
| allowed-tools | Read, Write, Edit |
| version | 1.11.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| tags | ["saas","groq","python","typescript"] |
| compatibility | Designed for Claude Code, also compatible with Codex and OpenClaw |
Groq SDK Patterns
Overview
Production patterns for the groq-sdk package. The Groq SDK mirrors the OpenAI SDK interface (chat.completions.create), so patterns feel familiar but must account for Groq-specific behavior: extreme speed (500+ tok/s), aggressive rate limits on free tier, and unique response metadata like queue_time and completion_time.
The full, copy-paste-ready implementations live in references/ so this file stays a fast map of the workflow. Read the summary here, then drill into the language file you need.
Prerequisites
groq-sdk (TypeScript) or groq (Python) installedGROQ_API_KEY set in the environment- Understanding of async/await and error handling
- Familiarity with OpenAI SDK patterns (Groq is API-compatible)
Instructions
Build the integration in layers. Each step below is a one-line summary; the full typed implementation is in references/typescript-patterns.md (steps 1–5, 7) and references/python-patterns.md (step 6).
- Typed client singleton — one shared
Groq client with maxRetries and timeout, so the whole app reuses one connection pool and config.
- Type-safe completion wrapper — return a typed result that surfaces Groq's unique timing fields (
queue_time, completion_time, total_time) and a computed tokensPerSec.
- Streaming with typed events — an
AsyncGenerator<string> that yields delta.content tokens.
- Error handling with Groq error types — branch on
Groq.APIError (429, 401, other) and Groq.APIConnectionError; rethrow the unknown.
- Retry with exponential backoff — honor the
retry-after header on 429s, else jittered backoff.
- Python patterns — sync
Groq(), AsyncGroq(), and streaming (see the Python reference).
- Multi-tenant client factory — cache one client per tenant so API keys stay isolated.
The essential skeleton — a shared singleton every other pattern builds on:
