groq-upgrade-migration

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:

Current Model IDs (Use These)

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 [email protected] --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

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.