@ai-sdk/deepgram 2.0.9 → 2.0.11

package/docs/110-deepgram.mdx

@@ -0,0 +1,190 @@
+---
+title: Deepgram
+description: Learn how to use the Deepgram provider for the AI SDK.
+---
+
+# Deepgram Provider
+
+The [Deepgram](https://deepgram.com/) provider contains language model support for the Deepgram transcription API.
+
+## Setup
+
+The Deepgram provider is available in the `@ai-sdk/deepgram` module. You can install it with
+
+<Tabs items={['pnpm', 'npm', 'yarn', 'bun']}>
+  <Tab>
+    <Snippet text="pnpm add @ai-sdk/deepgram" dark />
+  </Tab>
+  <Tab>
+    <Snippet text="npm install @ai-sdk/deepgram" dark />
+  </Tab>
+  <Tab>
+    <Snippet text="yarn add @ai-sdk/deepgram" dark />
+  </Tab>
+
+  <Tab>
+    <Snippet text="bun add @ai-sdk/deepgram" dark />
+  </Tab>
+</Tabs>
+
+## Provider Instance
+
+You can import the default provider instance `deepgram` from `@ai-sdk/deepgram`:
+
+```ts
+import { deepgram } from '@ai-sdk/deepgram';
+```
+
+If you need a customized setup, you can import `createDeepgram` from `@ai-sdk/deepgram` and create a provider instance with your settings:
+
+```ts
+import { createDeepgram } from '@ai-sdk/deepgram';
+
+const deepgram = createDeepgram({
+  // custom settings, e.g.
+  fetch: customFetch,
+});
+```
+
+You can use the following optional settings to customize the Deepgram provider instance:
+
+- **apiKey** _string_
+
+  API key that is being sent using the `Authorization` header.
+  It defaults to the `DEEPGRAM_API_KEY` environment variable.
+
+- **headers** _Record&lt;string,string&gt;_
+
+  Custom headers to include in the requests.
+
+- **fetch** _(input: RequestInfo, init?: RequestInit) => Promise&lt;Response&gt;_
+
+  Custom [fetch](https://developer.mozilla.org/en-US/docs/Web/API/fetch) implementation.
+  Defaults to the global `fetch` function.
+  You can use it as a middleware to intercept requests,
+  or to provide a custom fetch implementation for e.g. testing.
+
+## Transcription Models
+
+You can create models that call the [Deepgram transcription API](https://developers.deepgram.com/docs/pre-recorded-audio)
+using the `.transcription()` factory method.
+
+The first argument is the model id e.g. `nova-3`.
+
+```ts
+const model = deepgram.transcription('nova-3');
+```
+
+You can also pass additional provider-specific options using the `providerOptions` argument. For example, supplying the `summarize` option will enable summaries for sections of content.
+
+```ts highlight="6"
+import { experimental_transcribe as transcribe } from 'ai';
+import { deepgram } from '@ai-sdk/deepgram';
+import { readFile } from 'fs/promises';
+
+const result = await transcribe({
+  model: deepgram.transcription('nova-3'),
+  audio: await readFile('audio.mp3'),
+  providerOptions: { deepgram: { summarize: true } },
+});
+```
+
+The following provider options are available:
+
+- **language** _string_
+
+  Language code for the audio.
+  Supports numerous ISO-639-1 and ISO-639-3 language codes.
+  Optional.
+
+- **smartFormat** _boolean_
+
+  Whether to apply smart formatting to the transcription.
+  Optional.
+
+- **punctuate** _boolean_
+
+  Whether to add punctuation to the transcription.
+  Optional.
+
+- **paragraphs** _boolean_
+
+  Whether to format the transcription into paragraphs.
+  Optional.
+
+- **summarize** _enum | boolean_
+
+  Whether to generate a summary of the transcription.
+  Allowed values: `'v2'`, `false`.
+  Optional.
+
+- **topics** _boolean_
+
+  Whether to detect topics in the transcription.
+  Optional.
+
+- **intents** _boolean_
+
+  Whether to detect intents in the transcription.
+  Optional.
+
+- **sentiment** _boolean_
+
+  Whether to perform sentiment analysis on the transcription.
+  Optional.
+
+- **detectEntities** _boolean_
+
+  Whether to detect entities in the transcription.
+  Optional.
+
+- **redact** _string | array of strings_
+
+  Specifies what content to redact from the transcription.
+  Optional.
+
+- **replace** _string_
+
+  Replacement string for redacted content.
+  Optional.
+
+- **search** _string_
+
+  Search term to find in the transcription.
+  Optional.
+
+- **keyterm** _string_
+
+  Key terms to identify in the transcription.
+  Optional.
+
+- **diarize** _boolean_
+
+  Whether to identify different speakers in the transcription.
+  Defaults to `true`.
+  Optional.
+
+- **utterances** _boolean_
+
+  Whether to segment the transcription into utterances.
+  Optional.
+
+- **uttSplit** _number_
+
+  Threshold for splitting utterances.
+  Optional.
+
+- **fillerWords** _boolean_
+
+  Whether to include filler words (um, uh, etc.) in the transcription.
+  Optional.
+
+### Model Capabilities
+
+| Model                                                                                              | Transcription       | Duration            | Segments            | Language            |
+| -------------------------------------------------------------------------------------------------- | ------------------- | ------------------- | ------------------- | ------------------- |
+| `nova-3` (+ [variants](https://developers.deepgram.com/docs/models-languages-overview#nova-3))     | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
+| `nova-2` (+ [variants](https://developers.deepgram.com/docs/models-languages-overview#nova-2))     | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
+| `nova` (+ [variants](https://developers.deepgram.com/docs/models-languages-overview#nova))         | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
+| `enhanced` (+ [variants](https://developers.deepgram.com/docs/models-languages-overview#enhanced)) | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |
+| `base` (+ [variants](https://developers.deepgram.com/docs/models-languages-overview#base))         | <Check size={18} /> | <Check size={18} /> | <Check size={18} /> | <Cross size={18} /> |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/deepgram",
-  "version": "2.0.9",
+  "version": "2.0.11",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -8,10 +8,18 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist/**/*",
+    "docs/**/*",
     "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test-d.ts",
+    "!src/**/__snapshots__",
+    "!src/**/__fixtures__",
     "CHANGELOG.md",
     "README.md"
   ],
+  "directories": {
+    "doc": "./docs"
+  },
   "exports": {
     "./package.json": "./package.json",
     ".": {
@@ -21,15 +29,15 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "3.0.4",
-    "@ai-sdk/provider-utils": "4.0.8"
+    "@ai-sdk/provider": "3.0.5",
+    "@ai-sdk/provider-utils": "4.0.9"
   },
   "devDependencies": {
     "@types/node": "20.17.24",
     "tsup": "^8",
     "typescript": "5.6.3",
     "zod": "3.25.76",
-    "@ai-sdk/test-server": "1.0.2",
+    "@ai-sdk/test-server": "1.0.3",
     "@vercel/ai-tsconfig": "0.0.0"
   },
   "peerDependencies": {
@@ -55,7 +63,7 @@
   "scripts": {
     "build": "tsup --tsconfig tsconfig.build.json",
     "build:watch": "tsup --tsconfig tsconfig.build.json --watch",
-    "clean": "del-cli dist",
+    "clean": "del-cli dist docs",
     "lint": "eslint \"./**/*.ts*\"",
     "type-check": "tsc --noEmit",
     "prettier-check": "prettier --check \"./**/*.ts*\"",

package/src/deepgram-error.test.ts

@@ -1,34 +0,0 @@
-import { safeParseJSON } from '@ai-sdk/provider-utils';
-import { deepgramErrorDataSchema } from './deepgram-error';
-import { describe, expect, it } from 'vitest';
-
-describe('deepgramErrorDataSchema', () => {
-  it('should parse Deepgram resource exhausted error', async () => {
-    const error = `
-{"error":{"message":"{\\n  \\"error\\": {\\n    \\"code\\": 429,\\n    \\"message\\": \\"Resource has been exhausted (e.g. check quota).\\",\\n    \\"status\\": \\"RESOURCE_EXHAUSTED\\"\\n  }\\n}\\n","code":429}}
-`;
-
-    const result = await safeParseJSON({
-      text: error,
-      schema: deepgramErrorDataSchema,
-    });
-
-    expect(result).toStrictEqual({
-      success: true,
-      value: {
-        error: {
-          message:
-            '{\n  "error": {\n    "code": 429,\n    "message": "Resource has been exhausted (e.g. check quota).",\n    "status": "RESOURCE_EXHAUSTED"\n  }\n}\n',
-          code: 429,
-        },
-      },
-      rawValue: {
-        error: {
-          message:
-            '{\n  "error": {\n    "code": 429,\n    "message": "Resource has been exhausted (e.g. check quota).",\n    "status": "RESOURCE_EXHAUSTED"\n  }\n}\n',
-          code: 429,
-        },
-      },
-    });
-  });
-});

package/src/deepgram-speech-model.test.ts

@@ -1,355 +0,0 @@
-import { createTestServer } from '@ai-sdk/test-server/with-vitest';
-import { createDeepgram } from './deepgram-provider';
-import { DeepgramSpeechModel } from './deepgram-speech-model';
-import { describe, it, expect, vi } from 'vitest';
-
-vi.mock('./version', () => ({
-  VERSION: '0.0.0-test',
-}));
-
-const provider = createDeepgram({ apiKey: 'test-api-key' });
-const model = provider.speech('aura-2-helena-en');
-
-const server = createTestServer({
-  'https://api.deepgram.com/v1/speak': {},
-});
-
-describe('doGenerate', () => {
-  function prepareAudioResponse({
-    headers,
-  }: {
-    headers?: Record<string, string>;
-  } = {}) {
-    const audioBuffer = new Uint8Array(100); // Mock audio data
-    server.urls['https://api.deepgram.com/v1/speak'].response = {
-      type: 'binary',
-      headers: {
-        'content-type': 'audio/mp3',
-        ...headers,
-      },
-      body: Buffer.from(audioBuffer),
-    };
-    return audioBuffer;
-  }
-
-  it('should pass the model and text', async () => {
-    prepareAudioResponse();
-
-    await model.doGenerate({
-      text: 'Hello, welcome to Deepgram!',
-    });
-
-    expect(await server.calls[0].requestBodyJson).toMatchObject({
-      text: 'Hello, welcome to Deepgram!',
-    });
-
-    const url = new URL(server.calls[0].requestUrl);
-    expect(url.searchParams.get('model')).toBe('aura-2-helena-en');
-  });
-
-  it('should pass headers', async () => {
-    prepareAudioResponse();
-
-    const provider = createDeepgram({
-      apiKey: 'test-api-key',
-      headers: {
-        'Custom-Provider-Header': 'provider-header-value',
-      },
-    });
-
-    await provider.speech('aura-2-helena-en').doGenerate({
-      text: 'Hello, welcome to Deepgram!',
-      headers: {
-        'Custom-Request-Header': 'request-header-value',
-      },
-    });
-
-    expect(server.calls[0].requestHeaders).toMatchObject({
-      authorization: 'Token test-api-key',
-      'content-type': 'application/json',
-      'custom-provider-header': 'provider-header-value',
-      'custom-request-header': 'request-header-value',
-    });
-
-    expect(server.calls[0].requestUserAgent).toContain(
-      `ai-sdk/deepgram/0.0.0-test`,
-    );
-  });
-
-  it('should pass query parameters for model', async () => {
-    prepareAudioResponse();
-
-    await model.doGenerate({
-      text: 'Hello, welcome to Deepgram!',
-    });
-
-    const url = new URL(server.calls[0].requestUrl);
-    expect(url.searchParams.get('model')).toBe('aura-2-helena-en');
-  });
-
-  it('should map outputFormat to encoding/container', async () => {
-    prepareAudioResponse();
-
-    await model.doGenerate({
-      text: 'Hello, welcome to Deepgram!',
-      outputFormat: 'wav',
-    });
-
-    const url = new URL(server.calls[0].requestUrl);
-    expect(url.searchParams.get('container')).toBe('wav');
-    expect(url.searchParams.get('encoding')).toBe('linear16');
-  });
-
-  it('should pass provider options', async () => {
-    prepareAudioResponse();
-
-    await model.doGenerate({
-      text: 'Hello, welcome to Deepgram!',
-      providerOptions: {
-        deepgram: {
-          encoding: 'mp3',
-          bitRate: 48000,
-          container: 'wav',
-          callback: 'https://example.com/callback',
-          callbackMethod: 'POST',
-          mipOptOut: true,
-          tag: 'test-tag',
-        },
-      },
-    });
-
-    const url = new URL(server.calls[0].requestUrl);
-    expect(url.searchParams.get('encoding')).toBe('mp3');
-    expect(url.searchParams.get('bit_rate')).toBe('48000');
-    // mp3 doesn't support container, so it should be removed
-    expect(url.searchParams.get('container')).toBeNull();
-    expect(url.searchParams.get('callback')).toBe(
-      'https://example.com/callback',
-    );
-    expect(url.searchParams.get('callback_method')).toBe('POST');
-    expect(url.searchParams.get('mip_opt_out')).toBe('true');
-    expect(url.searchParams.get('tag')).toBe('test-tag');
-  });
-
-  it('should handle array tag', async () => {
-    prepareAudioResponse();
-
-    await model.doGenerate({
-      text: 'Hello, welcome to Deepgram!',
-      providerOptions: {
-        deepgram: {
-          tag: ['tag1', 'tag2'],
-        },
-      },
-    });
-
-    const url = new URL(server.calls[0].requestUrl);
-    expect(url.searchParams.get('tag')).toBe('tag1,tag2');
-  });
-
-  it('should return audio data', async () => {
-    const audio = new Uint8Array(100); // Mock audio data
-    prepareAudioResponse({
-      headers: {
-        'x-request-id': 'test-request-id',
-      },
-    });
-
-    const result = await model.doGenerate({
-      text: 'Hello, welcome to Deepgram!',
-    });
-
-    expect(result.audio).toStrictEqual(audio);
-  });
-
-  it('should include response data with timestamp, modelId and headers', async () => {
-    prepareAudioResponse({
-      headers: {
-        'x-request-id': 'test-request-id',
-      },
-    });
-
-    const testDate = new Date(0);
-    const customModel = new DeepgramSpeechModel('aura-2-helena-en', {
-      provider: 'test-provider',
-      url: () => 'https://api.deepgram.com/v1/speak',
-      headers: () => ({}),
-      _internal: {
-        currentDate: () => testDate,
-      },
-    });
-
-    const result = await customModel.doGenerate({
-      text: 'Hello, welcome to Deepgram!',
-    });
-
-    expect(result.response).toMatchObject({
-      timestamp: testDate,
-      modelId: 'aura-2-helena-en',
-      headers: {
-        'content-type': 'audio/mp3',
-        'x-request-id': 'test-request-id',
-      },
-    });
-  });
-
-  it('should warn about unsupported voice parameter', async () => {
-    prepareAudioResponse();
-
-    const result = await model.doGenerate({
-      text: 'Hello, welcome to Deepgram!',
-      voice: 'different-voice',
-    });
-
-    expect(result.warnings).toMatchInlineSnapshot(`
-      [
-        {
-          "details": "Deepgram TTS models embed the voice in the model ID. The voice parameter "different-voice" was ignored. Use the model ID to select a voice (e.g., "aura-2-helena-en").",
-          "feature": "voice",
-          "type": "unsupported",
-        },
-      ]
-    `);
-  });
-
-  it('should warn about unsupported speed parameter', async () => {
-    prepareAudioResponse();
-
-    const result = await model.doGenerate({
-      text: 'Hello, welcome to Deepgram!',
-      speed: 1.5,
-    });
-
-    expect(result.warnings).toMatchInlineSnapshot(`
-      [
-        {
-          "details": "Deepgram TTS REST API does not support speed adjustment. Speed parameter was ignored.",
-          "feature": "speed",
-          "type": "unsupported",
-        },
-      ]
-    `);
-  });
-
-  it('should warn about unsupported language parameter', async () => {
-    prepareAudioResponse();
-
-    const result = await model.doGenerate({
-      text: 'Hello, welcome to Deepgram!',
-      language: 'en',
-    });
-
-    expect(result.warnings).toMatchInlineSnapshot(`
-      [
-        {
-          "details": "Deepgram TTS models are language-specific via the model ID. Language parameter "en" was ignored. Select a model with the appropriate language suffix (e.g., "-en" for English).",
-          "feature": "language",
-          "type": "unsupported",
-        },
-      ]
-    `);
-  });
-
-  it('should warn about unsupported instructions parameter', async () => {
-    prepareAudioResponse();
-
-    const result = await model.doGenerate({
-      text: 'Hello, welcome to Deepgram!',
-      instructions: 'Speak slowly',
-    });
-
-    expect(result.warnings).toMatchInlineSnapshot(`
-      [
-        {
-          "details": "Deepgram TTS REST API does not support instructions. Instructions parameter was ignored.",
-          "feature": "instructions",
-          "type": "unsupported",
-        },
-      ]
-    `);
-  });
-
-  it('should include request body in response', async () => {
-    prepareAudioResponse();
-
-    const result = await model.doGenerate({
-      text: 'Hello, welcome to Deepgram!',
-    });
-
-    expect(result.request?.body).toBe(
-      JSON.stringify({ text: 'Hello, welcome to Deepgram!' }),
-    );
-  });
-
-  it('should clean up incompatible parameters when encoding changes via providerOptions', async () => {
-    prepareAudioResponse();
-
-    // Test case 1: outputFormat sets sample_rate, encoding changed to mp3 (fixed sample rate)
-    await model.doGenerate({
-      text: 'Hello, welcome to Deepgram!',
-      outputFormat: 'linear16_16000', // Sets: encoding=linear16, sample_rate=16000
-      providerOptions: {
-        deepgram: {
-          encoding: 'mp3', // Changes encoding to mp3
-        },
-      },
-    });
-
-    const url1 = new URL(server.calls[0].requestUrl);
-    expect(url1.searchParams.get('encoding')).toBe('mp3');
-    expect(url1.searchParams.get('sample_rate')).toBeNull(); // Should be removed
-
-    // Test case 2: outputFormat sets container for linear16, encoding changed to opus
-    await model.doGenerate({
-      text: 'Hello, welcome to Deepgram!',
-      outputFormat: 'linear16_16000', // Sets: encoding=linear16, container=wav
-      providerOptions: {
-        deepgram: {
-          encoding: 'opus', // Changes encoding to opus
-        },
-      },
-    });
-
-    const url2 = new URL(server.calls[1].requestUrl);
-    expect(url2.searchParams.get('encoding')).toBe('opus');
-    expect(url2.searchParams.get('container')).toBe('ogg'); // Should be ogg, not wav
-    expect(url2.searchParams.get('sample_rate')).toBeNull(); // Should be removed
-
-    // Test case 3: outputFormat sets bit_rate, encoding changed to linear16 (no bitrate support)
-    await model.doGenerate({
-      text: 'Hello, welcome to Deepgram!',
-      outputFormat: 'mp3', // Sets: encoding=mp3
-      providerOptions: {
-        deepgram: {
-          encoding: 'linear16', // Changes encoding to linear16
-          bitRate: 48000, // Try to set bitrate
-        },
-      },
-    });
-
-    const url3 = new URL(server.calls[2].requestUrl);
-    expect(url3.searchParams.get('encoding')).toBe('linear16');
-    expect(url3.searchParams.get('bit_rate')).toBeNull(); // Should be removed
-  });
-
-  it('should clean up incompatible parameters when container changes encoding implicitly', async () => {
-    prepareAudioResponse();
-
-    // Test case: outputFormat sets sample_rate, container changes encoding to opus
-    await model.doGenerate({
-      text: 'Hello, welcome to Deepgram!',
-      outputFormat: 'linear16_16000', // Sets: encoding=linear16, sample_rate=16000
-      providerOptions: {
-        deepgram: {
-          container: 'ogg', // Changes encoding to opus implicitly
-        },
-      },
-    });
-
-    const callIndex = server.calls.length - 1;
-    const url = new URL(server.calls[callIndex].requestUrl);
-    expect(url.searchParams.get('encoding')).toBe('opus');
-    expect(url.searchParams.get('container')).toBe('ogg');
-    expect(url.searchParams.get('sample_rate')).toBeNull(); // Should be removed (opus has fixed sample rate)
-  });
-});