@ai-sdk/deepgram 2.0.8 → 2.0.9

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

@@ -0,0 +1,249 @@
+import { createTestServer } from '@ai-sdk/test-server/with-vitest';
+import { DeepgramTranscriptionModel } from './deepgram-transcription-model';
+import { createDeepgram } from './deepgram-provider';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { describe, it, expect, vi } from 'vitest';
+
+vi.mock('./version', () => ({
+  VERSION: '0.0.0-test',
+}));
+
+const audioData = await readFile(path.join(__dirname, 'transcript-test.mp3'));
+const provider = createDeepgram({ apiKey: 'test-api-key' });
+const model = provider.transcription('nova-3');
+
+const server = createTestServer({
+  'https://api.deepgram.com/v1/listen': {},
+});
+
+describe('doGenerate', () => {
+  function prepareJsonResponse({
+    headers,
+    detectedLanguage,
+  }: {
+    headers?: Record<string, string>;
+    detectedLanguage?: string;
+  } = {}) {
+    server.urls['https://api.deepgram.com/v1/listen'].response = {
+      type: 'json-value',
+      headers,
+      body: {
+        metadata: {
+          transaction_key: 'deprecated',
+          request_id: '2479c8c8-8185-40ac-9ac6-f0874419f793',
+          sha256:
+            '154e291ecfa8be6ab8343560bcc109008fa7853eb5372533e8efdefc9b504c33',
+          created: '2024-02-06T19:56:16.180Z',
+          duration: 25.933313,
+          channels: 1,
+          models: ['30089e05-99d1-4376-b32e-c263170674af'],
+          model_info: {
+            '30089e05-99d1-4376-b32e-c263170674af': {
+              name: '2-general-nova',
+              version: '2024-01-09.29447',
+              arch: 'nova-3',
+            },
+          },
+        },
+        results: {
+          channels: [
+            {
+              detected_language: detectedLanguage,
+              alternatives: [
+                {
+                  transcript: 'Hello world!',
+                  confidence: 0.99902344,
+                  words: [
+                    {
+                      word: 'hello',
+                      start: 0.08,
+                      end: 0.32,
+                      confidence: 0.9975586,
+                      punctuated_word: 'Hello.',
+                    },
+                    {
+                      word: 'world',
+                      start: 0.32,
+                      end: 0.79999995,
+                      confidence: 0.9921875,
+                      punctuated_word: 'World',
+                    },
+                  ],
+                  paragraphs: {
+                    transcript: 'Hello world!',
+                    paragraphs: [
+                      {
+                        sentences: [
+                          {
+                            text: 'Hello world!',
+                            start: 0.08,
+                            end: 0.32,
+                          },
+                        ],
+                        num_words: 2,
+                        start: 0.08,
+                        end: 0.79999995,
+                      },
+                    ],
+                  },
+                },
+              ],
+            },
+          ],
+        },
+      },
+    };
+  }
+
+  it('should pass the model', async () => {
+    prepareJsonResponse();
+
+    await model.doGenerate({
+      audio: audioData,
+      mediaType: 'audio/wav',
+    });
+
+    expect(await server.calls[0].requestBodyMultipart).toMatchObject({});
+  });
+
+  it('should pass headers', async () => {
+    prepareJsonResponse();
+
+    const provider = createDeepgram({
+      apiKey: 'test-api-key',
+      headers: {
+        'Custom-Provider-Header': 'provider-header-value',
+      },
+    });
+
+    await provider.transcription('nova-3').doGenerate({
+      audio: audioData,
+      mediaType: 'audio/wav',
+      headers: {
+        'Custom-Request-Header': 'request-header-value',
+      },
+    });
+
+    expect(server.calls[0].requestHeaders).toMatchObject({
+      authorization: 'Token test-api-key',
+      'content-type': 'audio/wav',
+      '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 extract the transcription text', async () => {
+    prepareJsonResponse();
+
+    const result = await model.doGenerate({
+      audio: audioData,
+      mediaType: 'audio/wav',
+    });
+
+    expect(result.text).toBe('Hello world!');
+  });
+
+  it('should include response data with timestamp, modelId and headers', async () => {
+    prepareJsonResponse({
+      headers: {
+        'x-request-id': 'test-request-id',
+        'x-ratelimit-remaining': '123',
+      },
+    });
+
+    const testDate = new Date(0);
+    const customModel = new DeepgramTranscriptionModel('nova-3', {
+      provider: 'test-provider',
+      url: () => 'https://api.deepgram.com/v1/listen',
+      headers: () => ({}),
+      _internal: {
+        currentDate: () => testDate,
+      },
+    });
+
+    const result = await customModel.doGenerate({
+      audio: audioData,
+      mediaType: 'audio/wav',
+    });
+
+    expect(result.response).toMatchObject({
+      timestamp: testDate,
+      modelId: 'nova-3',
+      headers: {
+        'content-type': 'application/json',
+        'x-request-id': 'test-request-id',
+        'x-ratelimit-remaining': '123',
+      },
+    });
+  });
+
+  it('should use real date when no custom date provider is specified', async () => {
+    prepareJsonResponse();
+
+    const testDate = new Date(0);
+    const customModel = new DeepgramTranscriptionModel('nova-3', {
+      provider: 'test-provider',
+      url: () => 'https://api.deepgram.com/v1/listen',
+      headers: () => ({}),
+      _internal: {
+        currentDate: () => testDate,
+      },
+    });
+
+    const result = await customModel.doGenerate({
+      audio: audioData,
+      mediaType: 'audio/wav',
+    });
+
+    expect(result.response.timestamp.getTime()).toEqual(testDate.getTime());
+    expect(result.response.modelId).toBe('nova-3');
+  });
+
+  it('should pass detectLanguage as detect_language query parameter', async () => {
+    prepareJsonResponse();
+
+    await model.doGenerate({
+      audio: audioData,
+      mediaType: 'audio/wav',
+      providerOptions: {
+        deepgram: {
+          detectLanguage: true,
+        },
+      },
+    });
+
+    const requestUrl = server.calls[0].requestUrl;
+    expect(requestUrl).toContain('detect_language=true');
+  });
+
+  it('should return detected language from response', async () => {
+    prepareJsonResponse({ detectedLanguage: 'sv' });
+
+    const result = await model.doGenerate({
+      audio: audioData,
+      mediaType: 'audio/wav',
+      providerOptions: {
+        deepgram: {
+          detectLanguage: true,
+        },
+      },
+    });
+
+    expect(result.language).toBe('sv');
+  });
+
+  it('should return undefined language when not detected', async () => {
+    prepareJsonResponse();
+
+    const result = await model.doGenerate({
+      audio: audioData,
+      mediaType: 'audio/wav',
+    });
+
+    expect(result.language).toBeUndefined();
+  });
+});

package/src/deepgram-transcription-model.ts

@@ -0,0 +1,211 @@
+import { SharedV3Warning, TranscriptionModelV3 } from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  createJsonResponseHandler,
+  parseProviderOptions,
+  postToApi,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import { DeepgramTranscriptionAPITypes } from './deepgram-api-types';
+import { DeepgramConfig } from './deepgram-config';
+import { deepgramFailedResponseHandler } from './deepgram-error';
+import { DeepgramTranscriptionModelId } from './deepgram-transcription-options';
+
+// https://developers.deepgram.com/docs/pre-recorded-audio#results
+const deepgramProviderOptionsSchema = z.object({
+  /** Language to use for transcription. If not specified, Deepgram defaults to English. Use `detectLanguage: true` to enable automatic language detection. */
+  language: z.string().nullish(),
+  /** Whether to enable automatic language detection. When true, Deepgram will detect the language of the audio. */
+  detectLanguage: z.boolean().nullish(),
+  /** Whether to use smart formatting, which formats written-out numbers, dates, times, etc. */
+  smartFormat: z.boolean().nullish(),
+  /** Whether to add punctuation to the transcript. */
+  punctuate: z.boolean().nullish(),
+  /** Whether to format the transcript into paragraphs. */
+  paragraphs: z.boolean().nullish(),
+  /** Whether to generate a summary of the transcript. Use 'v2' for the latest version or false to disable. */
+  summarize: z.union([z.literal('v2'), z.literal(false)]).nullish(),
+  /** Whether to identify topics in the transcript. */
+  topics: z.boolean().nullish(),
+  /** Whether to identify intents in the transcript. */
+  intents: z.boolean().nullish(),
+  /** Whether to analyze sentiment in the transcript. */
+  sentiment: z.boolean().nullish(),
+  /** Whether to detect and tag named entities in the transcript. */
+  detectEntities: z.boolean().nullish(),
+  /** Specify terms or patterns to redact from the transcript. Can be a string or array of strings. */
+  redact: z.union([z.string(), z.array(z.string())]).nullish(),
+  /** String to replace redacted content with. */
+  replace: z.string().nullish(),
+  /** Term or phrase to search for in the transcript. */
+  search: z.string().nullish(),
+  /** Key term to identify in the transcript. */
+  keyterm: z.string().nullish(),
+  /** Whether to identify different speakers in the audio. */
+  diarize: z.boolean().nullish(),
+  /** Whether to segment the transcript into utterances. */
+  utterances: z.boolean().nullish(),
+  /** Minimum duration of silence (in seconds) to trigger a new utterance. */
+  uttSplit: z.number().nullish(),
+  /** Whether to include filler words (um, uh, etc.) in the transcript. */
+  fillerWords: z.boolean().nullish(),
+});
+
+export type DeepgramTranscriptionCallOptions = z.infer<
+  typeof deepgramProviderOptionsSchema
+>;
+
+interface DeepgramTranscriptionModelConfig extends DeepgramConfig {
+  _internal?: {
+    currentDate?: () => Date;
+  };
+}
+
+export class DeepgramTranscriptionModel implements TranscriptionModelV3 {
+  readonly specificationVersion = 'v3';
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  constructor(
+    readonly modelId: DeepgramTranscriptionModelId,
+    private readonly config: DeepgramTranscriptionModelConfig,
+  ) {}
+
+  private async getArgs({
+    providerOptions,
+  }: Parameters<TranscriptionModelV3['doGenerate']>[0]) {
+    const warnings: SharedV3Warning[] = [];
+
+    // Parse provider options
+    const deepgramOptions = await parseProviderOptions({
+      provider: 'deepgram',
+      providerOptions,
+      schema: deepgramProviderOptionsSchema,
+    });
+
+    const body: DeepgramTranscriptionAPITypes = {
+      model: this.modelId,
+      diarize: true,
+    };
+
+    // Add provider-specific options
+    if (deepgramOptions) {
+      body.detect_entities = deepgramOptions.detectEntities ?? undefined;
+      body.detect_language = deepgramOptions.detectLanguage ?? undefined;
+      body.filler_words = deepgramOptions.fillerWords ?? undefined;
+      body.language = deepgramOptions.language ?? undefined;
+      body.punctuate = deepgramOptions.punctuate ?? undefined;
+      body.redact = deepgramOptions.redact ?? undefined;
+      body.search = deepgramOptions.search ?? undefined;
+      body.smart_format = deepgramOptions.smartFormat ?? undefined;
+      body.summarize = deepgramOptions.summarize ?? undefined;
+      body.topics = deepgramOptions.topics ?? undefined;
+      body.utterances = deepgramOptions.utterances ?? undefined;
+      body.utt_split = deepgramOptions.uttSplit ?? undefined;
+
+      if (typeof deepgramOptions.diarize === 'boolean') {
+        body.diarize = deepgramOptions.diarize;
+      }
+    }
+
+    // Convert body to URL query parameters
+    const queryParams = new URLSearchParams();
+    for (const [key, value] of Object.entries(body)) {
+      if (value !== undefined) {
+        queryParams.append(key, String(value));
+      }
+    }
+
+    return {
+      queryParams,
+      warnings,
+    };
+  }
+
+  async doGenerate(
+    options: Parameters<TranscriptionModelV3['doGenerate']>[0],
+  ): Promise<Awaited<ReturnType<TranscriptionModelV3['doGenerate']>>> {
+    const currentDate = this.config._internal?.currentDate?.() ?? new Date();
+    const { queryParams, warnings } = await this.getArgs(options);
+
+    const {
+      value: response,
+      responseHeaders,
+      rawValue: rawResponse,
+    } = await postToApi({
+      url:
+        this.config.url({
+          path: '/v1/listen',
+          modelId: this.modelId,
+        }) +
+        '?' +
+        queryParams.toString(),
+      headers: {
+        ...combineHeaders(this.config.headers(), options.headers),
+        'Content-Type': options.mediaType,
+      },
+      body: {
+        content: options.audio,
+        values: options.audio,
+      },
+      failedResponseHandler: deepgramFailedResponseHandler,
+      successfulResponseHandler: createJsonResponseHandler(
+        deepgramTranscriptionResponseSchema,
+      ),
+      abortSignal: options.abortSignal,
+      fetch: this.config.fetch,
+    });
+
+    return {
+      text:
+        response.results?.channels.at(0)?.alternatives.at(0)?.transcript ?? '',
+      segments:
+        response.results?.channels[0].alternatives[0].words?.map(word => ({
+          text: word.word,
+          startSecond: word.start,
+          endSecond: word.end,
+        })) ?? [],
+      language:
+        response.results?.channels.at(0)?.detected_language ?? undefined,
+      durationInSeconds: response.metadata?.duration ?? undefined,
+      warnings,
+      response: {
+        timestamp: currentDate,
+        modelId: this.modelId,
+        headers: responseHeaders,
+        body: rawResponse,
+      },
+    };
+  }
+}
+
+const deepgramTranscriptionResponseSchema = z.object({
+  metadata: z
+    .object({
+      duration: z.number(),
+    })
+    .nullish(),
+  results: z
+    .object({
+      channels: z.array(
+        z.object({
+          detected_language: z.string().nullish(),
+          alternatives: z.array(
+            z.object({
+              transcript: z.string(),
+              words: z.array(
+                z.object({
+                  word: z.string(),
+                  start: z.number(),
+                  end: z.number(),
+                }),
+              ),
+            }),
+          ),
+        }),
+      ),
+    })
+    .nullish(),
+});

package/src/deepgram-transcription-options.ts

@@ -0,0 +1,34 @@
+export type DeepgramTranscriptionModelId =
+  | 'base'
+  | 'base-general'
+  | 'base-meeting'
+  | 'base-phonecall'
+  | 'base-finance'
+  | 'base-conversationalai'
+  | 'base-voicemail'
+  | 'base-video'
+  | 'enhanced'
+  | 'enhanced-general'
+  | 'enhanced-meeting'
+  | 'enhanced-phonecall'
+  | 'enhanced-finance'
+  | 'nova'
+  | 'nova-general'
+  | 'nova-phonecall'
+  | 'nova-medical'
+  | 'nova-2'
+  | 'nova-2-general'
+  | 'nova-2-meeting'
+  | 'nova-2-phonecall'
+  | 'nova-2-finance'
+  | 'nova-2-conversationalai'
+  | 'nova-2-voicemail'
+  | 'nova-2-video'
+  | 'nova-2-medical'
+  | 'nova-2-drivethru'
+  | 'nova-2-automotive'
+  | 'nova-2-atc'
+  | 'nova-3'
+  | 'nova-3-general'
+  | 'nova-3-medical'
+  | (string & {});

package/src/index.ts

@@ -0,0 +1,9 @@
+export { createDeepgram, deepgram } from './deepgram-provider';
+export type {
+  DeepgramProvider,
+  DeepgramProviderSettings,
+} from './deepgram-provider';
+export { DeepgramSpeechModel } from './deepgram-speech-model';
+export type { DeepgramSpeechCallOptions } from './deepgram-speech-model';
+export type { DeepgramSpeechModelId } from './deepgram-speech-options';
+export { VERSION } from './version';

package/src/version.ts

@@ -0,0 +1,6 @@
+// Version string of this package injected at build time.
+declare const __PACKAGE_VERSION__: string | undefined;
+export const VERSION: string =
+  typeof __PACKAGE_VERSION__ !== 'undefined'
+    ? __PACKAGE_VERSION__
+    : '0.0.0-test';