deepgram-upgrade-migration

name	deepgram-upgrade-migration
description	Plan and execute Deepgram SDK upgrades and migrations. Use when upgrading SDK versions, migrating to new API versions, or transitioning between Deepgram models. Trigger with phrases like "upgrade deepgram", "deepgram migration", "update deepgram SDK", "deepgram version upgrade", "migrate deepgram".
allowed-tools	Read, Grep, Bash(curl:*)
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>

Deepgram Upgrade Migration

Overview

Guide for planning and executing Deepgram SDK upgrades and API migrations safely.

Prerequisites

• Current SDK version documented
• Test environment available
• Rollback plan prepared
• Changelog reviewed

Migration Types

1. SDK Version Upgrade

Upgrading the Deepgram SDK package (e.g., v2.x to v3.x)

2. Model Migration

Transitioning between transcription models (e.g., Nova to Nova-2)

3. API Version Migration

Moving between API versions (v1 to v2)

Instructions

Step 1: Assess Current State

Document current versions, configurations, and usage patterns.

Step 2: Review Breaking Changes

Check changelogs and migration guides for breaking changes.

Step 3: Plan Migration

Create detailed migration plan with rollback procedures.

Step 4: Test Thoroughly

Test in staging environment before production rollout.

Step 5: Execute Migration

Perform migration with monitoring and validation.

SDK Upgrade Guide

Check Current Version

# Node.js
npm list @deepgram/sdk

# Python
pip show deepgram-sdk

Review Changelog

# View npm package changelog
npm view @deepgram/sdk versions --json

# Or check GitHub releases
curl -s https://api.github.com/repos/deepgram/deepgram-js-sdk/releases/latest

TypeScript SDK v2 to v3 Migration

// v2 (old)
import Deepgram from '@deepgram/sdk';
const deepgram = new Deepgram(apiKey);
const response = await deepgram.transcription.preRecorded(
  { url: audioUrl },
  { punctuate: true }
);

// v3 (new)
import { createClient } from '@deepgram/sdk';
const deepgram = createClient(apiKey);
const { result, error } = await deepgram.listen.prerecorded.transcribeUrl(
  { url: audioUrl },
  { punctuate: true }
);

Breaking Changes Checklist

// lib/migration-check.ts
interface MigrationCheck {
  name: string;
  check: () => boolean;
  fix: string;
}

const v3MigrationChecks: MigrationCheck[] = [
  {
    name: 'Import statement',
    check: () => {
      // Check if old import style is used
      return true;
    },
    fix: 'Change: import Deepgram from "@deepgram/sdk" to import { createClient } from "@deepgram/sdk"',
  },
  {
    name: 'Client initialization',
    check: () => true,
    fix: 'Change: new Deepgram(key) to createClient(key)',
  },
  {
    name: 'Transcription method',
    check: () => true,
    fix: 'Change: deepgram.transcription.preRecorded() to deepgram.listen.prerecorded.transcribeUrl()',
  },
  {
    name: 'Response handling',
    check: () => true,
    fix: 'Change: const response = await ... to const { result, error } = await ...',
  },
  {
    name: 'Error handling',
    check: () => true,
    : ,
  },
];

  () {
  .();
   ( check  v3MigrationChecks) {
    .();
    .();
  }
}

Model Migration Guide

Nova to Nova-2 Migration

// Model comparison
const modelComparison = {
  'nova': {
    accuracy: 'Good',
    speed: 'Fast',
    languages: 36,
    deprecated: false,
  },
  'nova-2': {
    accuracy: 'Best',
    speed: 'Fast',
    languages: 47,
    deprecated: false,
  },
};

// Migration is simple - just change the model parameter
const { result, error } = await deepgram.listen.prerecorded.transcribeUrl(
  { url: audioUrl },
  {
    model: 'nova-2',  // Changed from 'nova'
    // All other options remain the same
    smart_format: true,
    punctuate: true,
    diarize: true,
  }
);

A/B Testing Models

// lib/model-ab-test.ts
interface ModelTestResult {
  model: string;
  transcript: string;
  confidence: number;
  processingTime: number;
}

export async function compareModels(
  audioUrl: string,
  models: string[] = ['nova', 'nova-2']
): Promise<ModelTestResult[]> {
  const client = createClient(process.env.DEEPGRAM_API_KEY!);
  const results: ModelTestResult[] = [];

  for (const model of models) {
    const startTime = Date.now();

    const { result, error } = await client.listen.prerecorded.transcribeUrl(
      { url: audioUrl },
      { model, smart_format: true }
    );

    if (error) {
      console.error(`Error with model ${model}:`, error);
      continue;
    }

     alternative = result..[].[];

    results.({
      model,
      : alternative.,
      : alternative.,
      : .() - startTime,
    });
  }

   results;
}


 () {
  .();

   ( result  results) {
    .();
    .();
    .();
    .();
    .();
  }

  
   best = results.(
    a. > b. ? a : b
  );
  .();
}

Rollback Plan

Prepare Rollback

// lib/rollback.ts
interface DeploymentVersion {
  sdkVersion: string;
  model: string;
  config: Record<string, unknown>;
  deployedAt: Date;
}

class RollbackManager {
  private versions: DeploymentVersion[] = [];
  private maxVersions = 5;

  recordDeployment(version: Omit<DeploymentVersion, 'deployedAt'>) {
    this.versions.unshift({
      ...version,
      deployedAt: new Date(),
    });

    // Keep only last N versions
    this.versions = this.versions.slice(0, this.maxVersions);
  }

  getLastStableVersion(): DeploymentVersion | null {
    return this.versions[1] || null; // Skip current version
  }

  getRollbackInstructions(: ): [] {
     [
      ,
      ,
      ,
      ,
      ,
      ,
    ];
  }
}

Emergency Rollback Script

#!/bin/bash
# scripts/emergency-rollback.sh

set -e

echo "=== Emergency Rollback ==="

# Store current version
CURRENT_VERSION=$(npm list @deepgram/sdk --json | jq -r '.dependencies["@deepgram/sdk"].version')
echo "Current version: $CURRENT_VERSION"

# Get previous version from git
git show HEAD~1:package-lock.json > /tmp/prev-lock.json
PREV_VERSION=$(cat /tmp/prev-lock.json | jq -r '.packages["node_modules/@deepgram/sdk"].version')
echo "Rolling back to: $PREV_VERSION"

# Confirm
read -p "Proceed with rollback? (y/n) " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
  exit 1
fi

# Rollback
npm install @deepgram/sdk@$PREV_VERSION --save-exact

# Verify
npm test

echo "Rollback complete. Deploy when ready."

Migration Validation

Validation Script

// scripts/validate-migration.ts
import { createClient } from '@deepgram/sdk';

interface ValidationResult {
  test: string;
  passed: boolean;
  details?: string;
}

async function validateMigration(): Promise<ValidationResult[]> {
  const results: ValidationResult[] = [];
  const client = createClient(process.env.DEEPGRAM_API_KEY!);

  // Test 1: API connectivity
  try {
    const { error } = await client.manage.getProjects();
    results.push({
      test: 'API Connectivity',
      passed: !error,
      details: error?.message,
    });
  } catch (err) {
    results.push({
      test: 'API Connectivity',
      passed: false,
      details: err instanceof Error ? err.message : 'Unknown error',
    });
  }

  // Test 2: Pre-recorded transcription
  try {
     { result, error } =  client...(
      { :  },
      { : , :  }
    );

    results.({
      : ,
      : !error && !!result?.?.?.[]?.?.[]?.,
      : error?.,
    });
  }  (err) {
    results.({
      : ,
      : ,
      : err   ? err. : ,
    });
  }

  
   {
     connection = client..({ :  });

      <>( {
      connection.(,  {
        connection.();
        ();
      });
      connection.(, reject);
      ( ( ()), );
    });

    results.({
      : ,
      : ,
    });
  }  (err) {
    results.({
      : ,
      : ,
      : err   ? err. : ,
    });
  }

   results;
}


().( {
  .();

   ( result  results) {
     status = result. ?  : ;
    .();
     (result.) {
      .();
    }
  }

   allPassed = results.( r.);
  process.(allPassed ?  : );
});

Resources

• Deepgram SDK Changelog
• Deepgram Python SDK Changelog
• Model Migration Guide
• API Deprecation Schedule

Next Steps

Proceed to deepgram-ci-integration for CI/CD integration.