Deepgram Migration Deep DiveSAFE

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-migration-deep-dive
description: 'Deep dive into migrating to Deepgram from other transcription providers.

  Use when migrating from AWS Transcribe, Google Cloud STT, Azure Speech,

  OpenAI Whisper, AssemblyAI, or Rev.ai to Deepgram.

  Trigger: "deepgram migration", "switch to deepgram", "migrate transcription",

  "deepgram from AWS", "deepgram from Google", "replace whisper with deepgram".

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

## Prerequisites

- An inventory of existing audio/transcript flows, data retention/consent obligations, evaluation fixtures, and rollback owner.
- A staging environment with separate credentials and a compatibility/quality acceptance threshold.

## Examples

Run the old and new transcription flow against approved non-sensitive fixtures, compare aggregate accuracy/latency/error metrics, and route a small reversible staging canary only after acceptance passes. Roll back immediately on quality, consent, or operational regression; do not bulk-migrate or reprocess customer recordings before the observation window closes.

## Current State

!`npm list @deepgram/sdk 2>/dev/null | grep deepgram || echo 'Not installed'`
!`npm list @aws-sdk/client-transcribe 2>/dev/null | grep transcribe || echo 'AWS Transcribe SDK not found'`
!`pip show google-cloud-speech 2>/dev/null | grep Version || echo 'Google STT not found'`

## Overview

Migrate to Deepgram from AWS Transcribe, Google Cloud Speech-to-Text, Azure Cognitive Services, or OpenAI Whisper. Uses an adapter pattern with a unified interface, parallel running for quality validation, percentage-based traffic shifting, and automated rollback.

## Feature Mapping

### AWS Transcribe -> Deepgram

| AWS Transcribe | Deepgram | Notes |
|----------------|----------|-------|
| `LanguageCode: 'en-US'` | `language: 'en'` | ISO 639-1 (2-letter) |
| `ShowSpeakerLabels: true` | `diarize: true` | Same feature, different param |
| `VocabularyName: 'custom'` | `keywords: ['term:1.5']` | Inline boosting, no pre-upload |
| `ContentRedactionType: 'PII'` | `redact: ['pci', 'ssn']` | Granular PII categories |
| `OutputBucketName` | `callback: 'https://...'` | Callback URL, not S3 |
| Job polling model | Sync response or callback | No polling needed |

### Google Cloud STT -> Deepgram

| Google STT | Deepgram | Notes |
|------------|----------|-------|
| `RecognitionConfig.encoding` | Auto-detected | Deepgram auto-detects format |
| `RecognitionConfig.sampleRateHertz` | `sample_rate` (live only) | REST auto-detects |
| `RecognitionConfig.model: 'latest_long'` | `model: 'nova-3'` | Direct mapping |
| `SpeakerDiarizationConfig` | `diarize: true` | Simpler configuration |
| `StreamingRecognize` | `listen.live()` | WebSocket vs gRPC |

### OpenAI Whisper -> Deepgram

| Whisper | Deepgram | Notes |
|---------|----------|-------|
| Local GPU processing | API call | No GPU needed |
| `whisper.transcribe(audio)` | `listen.prerecorded.transcribeFile()` | Similar interface |
| `model='large-v3'` | `model: 'nova-3'` | 10-100x faster |
| `language='en'` | `language: 'en'` | Same format |
| No diarization | `diarize: true` | Deepgram advantage |
| No streaming | `listen.live()` | Deepgram advantage |

## Instructions

### Step 1: Adapter Pattern

```typescript
interface TranscriptionResult {
  transcript: string;
  confidence: number;
  words: Array<{ word: string; start: number; end: number; speaker?: number }>;
  duration: number;
  provider: string;
}

interface TranscriptionAdapter {
  transcribeUrl(url: string, options: any): Promise<TranscriptionResult>;
  transcribeFile(path: string, options: any): Promise<TranscriptionResult>;
  name: string;
}
```

### Step 2: Deepgram Adapter

```typescript
import { createClient } from '@deepgram/sdk';
import { readFileSync } from 'fs';

class DeepgramAdapter implements TranscriptionAdapter {
  name = 'deepgram';
  private client: ReturnType<typeof createClient>;

  constructor(apiKey: string) {
    this.client = createClient(apiKey);
  }

  async transcribeUrl(url: string, options: any = {}): Promise<TranscriptionResult> {
    const { result, error } = await this.client.listen.prerecorded.transcribeUrl(
      { url },
      {
        model: options.model ?? 'nova-3',
        smart_format: true,
        diarize: options.diarize ?? false,
        language: options.language ?? 'en',
        keywords: options.keywords,
        redact: options.redact,
      }
    );
    if (error) throw new Error(`Deepgram: ${error.message}`);
    return this.normalize(result);
  }

  async transcribeFile(path: string, options: any = {}): Promise<TranscriptionResult> {
    const audio = readFileSync(path);
    const { result, error } = await this.client.listen.prerecorded.transcribeFile(
      audio,
      {
        model: options.model ?? 'nova-3',
        smart_format: true,
        diarize: options.diarize ?? false,
      }
    );
    if (error) throw new Error(`Deepgram: ${error.message}`);
    return this.normalize(result);
  }

  private normalize(result: any): TranscriptionResult {
    const alt = result.results.channels[0].alternatives[0];
    return {
      transcript: alt.transcript,
      confidence: alt.confidence,
      words: (alt.words ?? []).map((w: any) => ({
        word: w.punctuated_word ?? w.word,
        start: w.start,
        end: w.end,
        speaker: w.speaker,
      })),
      duration: result.metadata.duration,
      provider: 'deepgram',
    };
  }
}
```

### Step 3: AWS Transcribe Adapter (Legacy)

```typescript
// Legacy adapter — wraps existing AWS Transcribe code for parallel running
import { TranscribeClient, StartTranscriptionJobCommand, GetTranscriptionJobCommand }
  from '@aws-sdk/client-transcribe';

class AWSTranscribeAdapter implements Trans

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.