Deepgram Upgrade MigrationSAFE

Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: deepgram-upgrade-migration
description: 'Plan and execute Deepgram SDK upgrades and model migrations.

  Use when upgrading SDK versions (v3 to v4 to v5), migrating models

  (Nova-2 to Nova-3), or planning API version transitions.

  Trigger: "upgrade deepgram", "deepgram migration", "update deepgram SDK",

  "deepgram version upgrade", "nova-3 migration".

  '
allowed-tools: Read, Write, Edit, Grep, Bash(npm:*), Bash(pip:*)
version: 1.13.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- deepgram
- api
- migration
- upgrade
compatibility: Designed for Claude Code
---
# Deepgram Upgrade Migration

## Prerequisites

- Current/target SDK or API versions, compatibility matrix, approved fixtures, quality/latency thresholds, and rollback owner.
- Separate staging credentials plus a data-retention and consent review for any migration/reprocessing action.

## Examples

Upgrade the SDK in staging, run mock/unit tests and a small licensed-fixture comparison against the prior version, and compare aggregate output/latency/error metrics. Promote through an approved canary only after acceptance passes; revert to the prior lockfile/configuration on regression and do not reprocess production recordings to validate the upgrade.

## Current State

!`npm list @deepgram/sdk 2>/dev/null | grep deepgram || echo 'SDK not installed'`

## Overview

Guide for Deepgram SDK version upgrades (v3 -> v4 -> v5) and model migrations (Nova-2 -> Nova-3). Includes breaking change maps, side-by-side API comparison, A/B testing scripts, automated validation, and rollback procedures.

## SDK Version History

| Version | Client Init | STT API | Live API | TTS API | Status |
|---------|------------|---------|----------|---------|--------|
| v3.x | `createClient(key)` | `listen.prerecorded.transcribeUrl()` | `listen.live()` | `speak.request()` | Stable |
| v4.x | `createClient(key)` | `listen.prerecorded.transcribeUrl()` | `listen.live()` | `speak.request()` | Stable |
| v5.x | `new DeepgramClient({apiKey})` | `listen.v1.media.transcribeUrl()` | `listen.v1.connect()` | `speak.v1.audio.generate()` | Beta |

## Instructions

### Step 1: Identify Current Version and Breaking Changes

```bash
# Check installed version
npm list @deepgram/sdk

# Check latest available
npm view @deepgram/sdk versions --json | tail -5
```

### Step 2: v3/v4 to v5 Migration Map

```typescript
// ============= CLIENT CREATION =============
// v3/v4:
import { createClient } from '@deepgram/sdk';
const dg = createClient(process.env.DEEPGRAM_API_KEY!);

// v5:
import { DeepgramClient } from '@deepgram/sdk';
const dg = new DeepgramClient({ apiKey: process.env.DEEPGRAM_API_KEY });

// ============= PRE-RECORDED STT =============
// v3/v4:
const { result, error } = await dg.listen.prerecorded.transcribeUrl(
  { url: audioUrl },
  { model: 'nova-3', smart_format: true }
);

// v5:
const response = await dg.listen.v1.media.transcribeUrl(
  { url: audioUrl },
  { model: 'nova-3', smart_format: true }
);
// v5 throws on error instead of returning { error }

// ============= FILE TRANSCRIPTION =============
// v3/v4:
const { result, error } = await dg.listen.prerecorded.transcribeFile(
  buffer,
  { model: 'nova-3', mimetype: 'audio/wav' }
);

// v5:
const response = await dg.listen.v1.media.transcribeFile(
  createReadStream('audio.wav'),
  { model: 'nova-3' }
);

// ============= LIVE STREAMING =============
// v3/v4:
const connection = dg.listen.live({ model: 'nova-3', encoding: 'linear16' });
connection.on(LiveTranscriptionEvents.Transcript, (data) => { ... });

// v5:
const connection = await dg.listen.v1.connect({ model: 'nova-3', encoding: 'linear16' });
// Note: v5 connect() is async

// ============= TEXT-TO-SPEECH =============
// v3/v4:
const response = await dg.speak.request(
  { text: 'Hello world' },
  { model: 'aura-2-thalia-en' }
);
const stream = await response.getStream();

// v5:
const response = await dg.speak.v1.audio.generate(
  { text: 'Hello world' },
  { model: 'aura-2-thalia-en' }
);

// ============= ERROR HANDLING =============
// v3/v4: Destructured { result, error }
const { result, error } = await dg.listen.prerecorded.transcribeUrl(src, opts);
if (error) handleError(error);

// v5: try/catch (throws on error)
try {
  const result = await dg.listen.v1.media.transcribeUrl(src, opts);
} catch (err) {
  handleError(err);
}
```

### Step 3: Model Migration (Nova-2 -> Nova-3)

```typescript
// Nova-3 is a drop-in replacement — same API, better accuracy
// Just change the model parameter:

// Before:
{ model: 'nova-2' }

// After:
{ model: 'nova-3' }

// Nova-3 improvements over Nova-2:
// - Higher accuracy across all languages
// - Better handling of accents and dialects
// - Improved punctuation and formatting
// - Same pricing tier
// - Same API parameters
```

### Step 4: A/B Test Models

```typescript
async function compareModels(audioUrl: string) {
  const client = createClient(process.env.DEEPGRAM_API_KEY!);

  const [nova2, nova3] = await Promise.all([
    client.listen.prerecorded.transcribeUrl(
      { url: audioUrl },
      { model: 'nova-2', smart_format: true }
    ),
    client.listen.prerecorded.transcribeUrl(
      { url: audioUrl },
      { model: 'nova-3', smart_format: true }
    ),
  ]);

  const t2 = nova2.result.results.channels[0].alternatives[0];
  const t3 = nova3.result.results.channels[0].alternatives[0];

  console.log('=== Nova-2 ===');
  console.log(`Confidence: ${t2.confidence}`);
  console.log(`Words: ${t2.words?.length}`);
  console.log(`Transcript: ${t2.transcript.substring(0, 200)}...`);

  console.log('\n=== Nova-3 ===');
  console.log(`Confidence: ${t3.confidence}`);
  console.log(`Words: ${t3.words?.length}`);
  console.log(`Transcript: ${t3.transcript.substring(0, 200)}...`);

  // Simple word-level similarity
  const words2 = new Set(t2.transcript.toLowerCase().split(/\s+/));
  const words3 = new Set(t3.transcript.toLowerCase().split(/\s+/));
  const intersect

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.