--- name: groq-upgrade-migration-149a18784430 description: '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". ' allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(git:*) version: 1.11.0 license: MIT author: Jeremy Longshore tags: - saas - groq - api - migration compatibility: Designed for Claude Code --- # 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 . See the Authentication section of [references/implementation.md](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](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): ```typescript const MODEL_MIGRATIONS: Record = { "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](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)](references/implementation.md) - [Worked examples](references/examples.md) - [Groq Model Deprecations](https://console.groq.com/docs/deprecations) - [Groq Changelog](https://console.groq.com/docs/changelog) - [groq-sdk GitHub Releases](https://github.com/groq/groq-typescript/releases) - [Groq Current Models](https://console.groq.com/docs/models) For CI integration during upgrades, see the `groq-ci-integration` skill. --- Source attribution: jeremylongshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/groq-pack/skills/groq-upgrade-migration/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice MIT License Copyright (c) 2025 Jeremy Longshore Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Mega AI Hub resource metadata Creator / publisher: jeremylongshore Original project: https://github.com/jeremylongshore/claude-code-plugins-plus-skills/blob/ab85a061f7bcc039dac13ee193de7a4cd4388571/plugins/saas-packs/groq-pack/skills/groq-upgrade-migration/SKILL.md Attribution basis: Source repository record Fields of work: Development & Engineering, Product Management Roles: Backend Developer, DevOps / SRE, Technical Product Manager Specialties: API, Backend, Design, Frontend, Git, Testing Tools: Tool not specified Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 5528f60c5d15fdb0c8f6e6ff5ccea2746572e3139be9729f662e29f46b7c431b