groq-migration-deep-dive

name	groq-migration-deep-dive
description	Use when you are moving a codebase off OpenAI, Anthropic, or another LLM provider onto Groq (or between Groq model generations) and want a zero-downtime, feature-flagged cutover with a benchmark and rollback plan. Trigger with phrases like "migrate to groq", "switch to groq", "groq migration", "openai to groq", "groq replatform".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(node:*), Bash(kubectl:*)
version	1.11.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","groq","migration"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

Groq Migration Deep Dive

Current State

!npm list groq-sdk openai @anthropic-ai/sdk 2>/dev/null | grep -E "groq|openai|anthropic" || echo 'No LLM SDKs found'

Overview

Migrate to Groq from OpenAI, Anthropic, or other LLM providers. Groq's OpenAI-compatible API makes migration straightforward — the primary changes are a different SDK import, different model IDs, and different response metadata. The reward is 10-50x faster inference.

The safe path is a provider-abstraction layer plus feature-flagged traffic shifting: route a small canary to Groq, benchmark quality and speed, ramp to 100%, and keep a one-flag rollback the whole way.

Migration Complexity

Source	Complexity	Key Changes
OpenAI	Low	Import, model IDs, base URL — API shape is identical
Anthropic	Medium	Different API shape, message format, streaming protocol
Local LLMs	Medium	Remove infra, add API calls
Other cloud (Bedrock, Vertex)	Medium	Remove cloud SDK, add groq-sdk

Prerequisites

• A Groq API key (GROQ_API_KEY) from console.groq.com.
• groq-sdk installed: npm install groq-sdk.
• A feature-flag mechanism (LaunchDarkly, env var, config service) exposing a groq_migration_pct value for gradual traffic shifting.
• The existing provider's key still available (OPENAI_API_KEY or equivalent) so you can run both providers side-by-side during the cutover.
• Node >=18 if you use the performance.now() benchmark helper.

Instructions

Steps 1-2 below are the essential skeleton — the two changes every migration needs. Steps 3-7 (the provider abstraction, traffic shifting, scanner, benchmark, and full compatibility matrix) are moved verbatim into the reference files linked under Examples so this file stays scannable.

Step 1: OpenAI to Groq Migration

The minimal change: swap the SDK import, client, and model ID. The response shape is identical, so downstream code (result.choices[0].message.content) is untouched.

// BEFORE: OpenAI
   ;
 openai =  ({ : process.. });
 result =  openai...({
  : ,
  : [{ : , :  }],
});


   ;
 groq =  ({ : process.. });
 result =  groq...({
  : ,  
  : [{ : , :  }],
});