Deepgram Local Dev LoopSAFE

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-local-dev-loop
description: 'Configure Deepgram local development workflow with testing and mocks.

  Use when setting up development environment, configuring test fixtures,

  or establishing rapid iteration patterns for Deepgram integration.

  Trigger: "deepgram local dev", "deepgram development setup",

  "deepgram test environment", "deepgram dev workflow", "deepgram mock".

  '
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(pip:*), Grep
version: 1.13.0
license: MIT
author: Jeremy Longshore <[email protected]>
tags:
- saas
- deepgram
- testing
- workflow
- development
compatibility: Designed for Claude Code
---
# Deepgram Local Dev Loop

## Examples

Use a local or development workspace with a short licensed fixture, make one SDK/config change, run the focused unit test and a bounded integration test, then inspect redacted metrics. Commit only the reviewed change; never copy production recordings, transcripts, or API keys into a local test loop.

## Overview

Set up a fast local development workflow for Deepgram: test fixtures with sample audio, mock responses for offline unit tests, Vitest integration tests against the real API, and a watch-mode transcription dev server.

## Prerequisites

- `@deepgram/sdk` installed, `DEEPGRAM_API_KEY` configured
- `npm install -D vitest tsx dotenv` for testing and dev server
- Optional: `curl` for downloading test fixtures

## Instructions

### Step 1: Project Structure

```bash
mkdir -p src tests/mocks fixtures
touch src/transcribe.ts tests/transcribe.test.ts tests/mocks/deepgram-responses.ts
```

### Step 2: Download Test Fixtures

```bash
# Deepgram provides free sample audio files
curl -o fixtures/nasa-podcast.wav \
  https://static.deepgram.com/examples/nasa-podcast.wav

curl -o fixtures/bueller.wav \
  https://static.deepgram.com/examples/Bueller-Life-moves-702702706.wav
```

### Step 3: Environment Config

```bash
# .env.development
DEEPGRAM_API_KEY=your-dev-key
DEEPGRAM_MODEL=nova-3

# .env.test (use a separate test key with low limits)
DEEPGRAM_API_KEY=your-test-key
DEEPGRAM_MODEL=base
```

```json
{
  "scripts": {
    "dev": "tsx watch src/transcribe.ts",
    "test": "vitest",
    "test:watch": "vitest --watch",
    "test:integration": "vitest run tests/integration/"
  }
}
```

### Step 4: Mock Deepgram Responses

```typescript
// tests/mocks/deepgram-responses.ts
export const mockPrerecordedResult = {
  metadata: {
    request_id: 'mock-request-id-001',
    created: '2026-01-01T00:00:00.000Z',
    duration: 12.5,
    channels: 1,
    models: ['nova-3'],
    model_info: { 'nova-3': { name: 'nova-3', version: '2026-01-01' } },
  },
  results: {
    channels: [{
      alternatives: [{
        transcript: 'Life moves pretty fast. If you don\'t stop and look around once in a while, you could miss it.',
        confidence: 0.98,
        words: [
          { word: 'life', start: 0.08, end: 0.32, confidence: 0.99, punctuated_word: 'Life' },
          { word: 'moves', start: 0.32, end: 0.56, confidence: 0.98, punctuated_word: 'moves' },
          { word: 'pretty', start: 0.56, end: 0.88, confidence: 0.97, punctuated_word: 'pretty' },
          { word: 'fast', start: 0.88, end: 1.12, confidence: 0.99, punctuated_word: 'fast.' },
        ],
      }],
    }],
    utterances: [{
      speaker: 0,
      transcript: 'Life moves pretty fast. If you don\'t stop and look around once in a while, you could miss it.',
      start: 0.08,
      end: 5.44,
      confidence: 0.98,
    }],
  },
};

export const mockLiveTranscript = {
  type: 'Results',
  channel_index: [0, 1],
  duration: 1.5,
  start: 0.0,
  is_final: true,
  speech_final: true,
  channel: {
    alternatives: [{
      transcript: 'Hello, how are you today?',
      confidence: 0.95,
      words: [
        { word: 'hello', start: 0.0, end: 0.3, confidence: 0.98, punctuated_word: 'Hello,' },
        { word: 'how', start: 0.35, end: 0.5, confidence: 0.96, punctuated_word: 'how' },
      ],
    }],
  },
};

export const mockTtsResponse = {
  content_type: 'audio/wav',
  request_id: 'mock-tts-001',
  model_name: 'aura-2-thalia-en',
  characters: { count: 42, limit: 100000 },
};
```

### Step 5: Unit Tests with Mocks

```typescript
// tests/transcribe.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { mockPrerecordedResult } from './mocks/deepgram-responses';

// Mock the SDK
vi.mock('@deepgram/sdk', () => ({
  createClient: () => ({
    listen: {
      prerecorded: {
        transcribeUrl: vi.fn().mockResolvedValue({
          result: mockPrerecordedResult,
          error: null,
        }),
        transcribeFile: vi.fn().mockResolvedValue({
          result: mockPrerecordedResult,
          error: null,
        }),
      },
    },
    speak: {
      request: vi.fn().mockResolvedValue({
        getStream: () => Promise.resolve(null),
      }),
    },
  }),
}));

describe('DeepgramTranscriber', () => {
  it('transcribes URL and returns transcript text', async () => {
    const { createClient } = await import('@deepgram/sdk');
    const client = createClient('mock-key');

    const { result } = await client.listen.prerecorded.transcribeUrl(
      { url: 'https://example.com/audio.wav' },
      { model: 'nova-3', smart_format: true }
    );

    expect(result.results.channels[0].alternatives[0].transcript).toContain('Life moves');
    expect(result.metadata.duration).toBe(12.5);
    expect(result.metadata.request_id).toBe('mock-request-id-001');
  });

  it('returns word-level timing data', async () => {
    const { createClient } = await import('@deepgram/sdk');
    const client = createClient('mock-key');

    const { result } = await client.listen.prerecorded.transcribeUrl(
      { url: 'https://example.com/audio.wav' },
      { model: 'nova-3' }
    );

    const words = result.results.channels[0].alternatives[0].words;
    expect(words[0].word).toBe('life');
    expect(words[0].start).toBe(0.08);
    expect(words[0].confidence).toBeGrea

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 (1)

config(); // Load .env

Gates applied: no_behavioural_pass.