Agent skill
groq-upgrade-migration
Upgrade groq-sdk versions and handle Groq model deprecations. Use when upgrading SDK versions, detecting deprecated models, or migrating to new Groq model IDs. Trigger with phrases like "upgrade groq", "groq migration", "groq breaking changes", "update groq SDK", "groq deprecated model".
Install this agent skill to your Project
npx add-skill https://github.com/jeremylongshore/claude-code-plugins-plus-skills/tree/main/plugins/saas-packs/groq-pack/skills/groq-upgrade-migration
SKILL.md
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. Groq regularly deprecates older models in favor of newer, faster alternatives.
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 at: GET https://api.groq.com/openai/v1/models
Instructions
Step 1: Check Current Version and Models
set -euo pipefail
# SDK version
npm list groq-sdk 2>/dev/null
npm view groq-sdk version # latest on npm
# Find all model references in your code
grep -rn "model.*['\"]" src/ --include="*.ts" --include="*.js" | grep -i "groq\|llama\|mixtral\|gemma\|whisper"
Step 2: Upgrade SDK
set -euo pipefail
# Create upgrade branch
git checkout -b chore/upgrade-groq-sdk
# Update to latest
npm install groq-sdk@latest
# Check for breaking changes
npm ls groq-sdk
Step 3: Find and Replace Deprecated Models
// Find-and-replace map for deprecated model IDs
const MODEL_MIGRATIONS: Record<string, string> = {
"mixtral-8x7b-32768": "llama-3.3-70b-versatile",
"gemma2-9b-it": "llama-3.1-8b-instant",
"llama-3.1-70b-versatile": "llama-3.3-70b-versatile",
"llama-3.1-70b-specdec": "llama-3.3-70b-specdec",
"llama3-70b-8192": "llama-3.3-70b-versatile",
"llama3-8b-8192": "llama-3.1-8b-instant",
"distil-whisper-large-v3-en": "whisper-large-v3-turbo",
};
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;
}
Step 4: Run Migration Scanner
set -euo pipefail
# Automated scan for deprecated patterns
echo "=== Deprecated Model IDs ==="
grep -rn "mixtral-8x7b\|gemma2-9b\|llama-3.1-70b-versatile\|llama3-70b\|llama3-8b\|distil-whisper" \
src/ --include="*.ts" --include="*.js" --include="*.py" || echo "None found"
echo ""
echo "=== Old Import Patterns ==="
grep -rn "from '@groq/sdk'\|from \"@groq/sdk\"\|require('@groq/sdk')" \
src/ --include="*.ts" --include="*.js" || echo "None found (correct import is 'groq-sdk')"
echo ""
echo "=== Deprecated Method Calls ==="
grep -rn "\.ping()\|\.healthCheck()\|GroqClient\|GroqError" \
src/ --include="*.ts" --include="*.js" || echo "None found"
Step 5: Validate and Test
set -euo pipefail
# Run tests
npm test
# Verify models are current
curl -s https://api.groq.com/openai/v1/models \
-H "Authorization: Bearer $GROQ_API_KEY" | \
jq -r '.data[].id' | sort
# Integration test
node -e "
const Groq = require('groq-sdk').default;
const g = new Groq();
g.chat.completions.create({
model: 'llama-3.1-8b-instant',
messages: [{role: 'user', content: 'ping'}],
max_tokens: 5
}).then(r => console.log('OK:', r.choices[0].message.content));
"
Step 6: Rollback If Needed
set -euo pipefail
# Pin to previous version
npm install groq-sdk@0.11.0 --save-exact
npm test
SDK Changelog Highlights
The groq-sdk package mirrors the OpenAI SDK structure. Key changes to watch:
- New model IDs added to type definitions
- Response type changes (e.g., new
usagefields) - Constructor options changes
- New endpoint support (vision, audio, TTS)
Always check the GitHub releases.
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 |
| New required fields | 400 on previously working requests |
Check API docs for parameter changes |
Resources
Next Steps
For CI integration during upgrades, see groq-ci-integration.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
dockerfile-generator
Dockerfile Generator - Auto-activating skill for DevOps Basics. Triggers on: dockerfile generator, dockerfile generator Part of the DevOps Basics skill category.
branch-naming-helper
Branch Naming Helper - Auto-activating skill for DevOps Basics. Triggers on: branch naming helper, branch naming helper Part of the DevOps Basics skill category.
readme-generator
Readme Generator - Auto-activating skill for DevOps Basics. Triggers on: readme generator, readme generator Part of the DevOps Basics skill category.
makefile-generator
Makefile Generator - Auto-activating skill for DevOps Basics. Triggers on: makefile generator, makefile generator Part of the DevOps Basics skill category.
gitignore-generator
Gitignore Generator - Auto-activating skill for DevOps Basics. Triggers on: gitignore generator, gitignore generator Part of the DevOps Basics skill category.
pre-commit-hook-setup
Pre Commit Hook Setup - Auto-activating skill for DevOps Basics. Triggers on: pre commit hook setup, pre commit hook setup Part of the DevOps Basics skill category.
Didn't find tool you were looking for?