groq-upgrade-migration

Current State

!npm list groq-sdk 2>/dev/null | grep groq-sdk || echo 'groq-sdk not installed' !pip show groq 2>/dev/null | grep -E "Name|Version" || echo 'groq not installed (python)'

Overview

Guide for upgrading the groq-sdk package and migrating away from deprecated model IDs. It walks a safe upgrade path — branch, bump, scan for deprecated model references, rewrite them, and verify against the live models endpoint before merging.

Prerequisites

• A Node project that depends on groq-sdk (or the Python groq package).
• npm, git, curl, and jq available on PATH.
• Authentication: GROQ_API_KEY exported in your shell (or CI secret store). The SDK constructor new Groq() reads it automatically; the live model check passes it as Authorization: Bearer $GROQ_API_KEY. Get a key at https://console.groq.com/keys. See the Authentication section of references/implementation.md.

Model Deprecation Timeline

Groq announces deprecations with advance notice. These models have been deprecated:

| Deprecated Model | Deprecation Date | Replacement | |-----------------|-----------------|-------------| | mixtral-8x7b-32768 | 2025-03-05 | llama-3.3-70b-versatile or llama-3.1-8b-instant | | gemma2-9b-it | 2025-08-08 | llama-3.1-8b-instant | | llama-3.1-70b-versatile | 2024-12-06 | llama-3.3-70b-versatile | | llama-3.1-70b-specdec | 2024-12-06 | llama-3.3-70b-specdec | | playai-tts | 2025-12-23 | Orpheus TTS models | | playai-tts-arabic | 2025-12-23 | Orpheus TTS models | | distil-whisper-large-v3-en | — | whisper-large-v3-turbo |

Current Model IDs (Use These)

| Model ID | Type | Context | Speed | |----------|------|---------|-------| | llama-3.1-8b-instant | Text | 128K | ~560 tok/s | | llama-3.3-70b-versatile | Text | 128K | ~280 tok/s | | llama-3.3-70b-specdec | Text | 128K | Faster | | meta-llama/llama-4-scout-17b-16e-instruct | Vision+Text | 128K | ~460 tok/s | | meta-llama/llama-4-maverick-17b-128e-instruct | Vision+Text | 128K | — | | whisper-large-v3 | Audio STT | — | 164x RT | | whisper-large-v3-turbo | Audio STT | — | 216x RT |

Always verify against the live endpoint: GET https://api.groq.com/openai/v1/models.

Instructions

Work through these six steps. Each has a copy-paste command block in references/implementation.md; the summary here is enough to drive the workflow, then drill in for the exact commands.

1. Check current version and models — read the installed groq-sdk version, compare to npm view groq-sdk version, and grep your src/ for every model string reference.
2. Upgrade the SDK — git checkout -b chore/upgrade-groq-sdk, then npm install groq-sdk@latest.
3. Find and replace deprecated models — use Read/Edit to fold the MODEL_MIGRATIONS resolver map (below) into your Groq client module, or Write a new groq-migrations.ts helper, so deprecated IDs are rewritten at runtime.
4. Run the migration scanner — the grep sweep in the reference flags deprecated model IDs, old @groq/sdk imports, and removed method calls.
5. Validate and test — npm test, then confirm current IDs against the live /v1/models endpoint and run the SDK integration smoke test.
6. Roll back if needed — pin the previous version with npm install groq-sdk@0.11.0 --save-exact and re-run tests.

The essential resolver skeleton (full version in the reference):

const MODEL_MIGRATIONS: Record<string, string> = {
  "mixtral-8x7b-32768": "llama-3.3-70b-versatile",
  "gemma2-9b-it": "llama-3.1-8b-instant",
  "distil-whisper-large-v3-en": "whisper-large-v3-turbo",
  // ...full map in references/implementation.md
};

function resolveModel(model: string): string {
  if (model in MODEL_MIGRATIONS) {
    console.warn(`Model ${model} is deprecated. Using ${MODEL_MIGRATIONS[model]} instead.`);
    return MODEL_MIGRATIONS[model];
  }
  return model;
}

Output

Running this workflow produces:

• A chore/upgrade-groq-sdk branch with groq-sdk bumped in package.json and the lockfile.
• A scanner report listing any remaining deprecated model IDs, stale @groq/sdk imports, or removed method calls — empty under every heading means the code is clean.
• Updated call sites (or a resolveModel wrapper) pointing at current model IDs.
• A green npm test run plus a live /v1/models listing confirming every model your code uses is still served.

Error Handling

| Issue | Symptom | Solution | |-------|---------|----------| | Deprecated model | 400 model_not_found or 400 model_decommissioned | Replace with current model ID | | Type errors after upgrade | TypeScript compilation fails | Check SDK changelog for type changes | | Auth format change | 401 after upgrade | Verify constructor uses apiKey, not key, and GROQ_API_KEY is set | | New required fields | 400 on previously working requests | Check API docs for parameter changes |

Examples

Worked before/after migrations — replacing a decommissioned chat model, routing every call through resolveModel, migrating a transcription model, and reading a clean scanner run — are in references/examples.md. Quick example: a call still using mixtral-8x7b-32768 swaps to llama-3.3-70b-versatile per the migration map, clearing the 400 model_decommissioned error.

Resources

• Full walkthrough (all commands)
• Worked examples
• Groq Model Deprecations
• Groq Changelog
• groq-sdk GitHub Releases
• Groq Current Models

For CI integration during upgrades, see the groq-ci-integration skill.