@ai-sdk/deepgram 2.0.8 → 2.0.10

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.8",
+  "version": "2.0.10",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -8,9 +8,14 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist/**/*",
+    "docs/**/*",
+    "src",
     "CHANGELOG.md",
     "README.md"
   ],
+  "directories": {
+    "doc": "./docs"
+  },
   "exports": {
     "./package.json": "./package.json",
     ".": {
@@ -28,7 +33,7 @@
     "tsup": "^8",
     "typescript": "5.6.3",
     "zod": "3.25.76",
-    "@ai-sdk/test-server": "1.0.1",
+    "@ai-sdk/test-server": "1.0.2",
     "@vercel/ai-tsconfig": "0.0.0"
   },
   "peerDependencies": {
@@ -54,7 +59,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-api-types.ts

@@ -0,0 +1,36 @@
+export type DeepgramTranscriptionAPITypes = {
+  // Base parameters
+  language?: string;
+  detect_language?: boolean;
+  model?: string;
+
+  // Formatting options
+  smart_format?: boolean;
+  punctuate?: boolean;
+  paragraphs?: boolean;
+
+  // Summarization and analysis
+  summarize?: 'v2' | false;
+  topics?: boolean;
+  intents?: boolean;
+  sentiment?: boolean;
+
+  // Entity detection
+  detect_entities?: boolean;
+
+  // Redaction options
+  redact?: string | string[];
+  replace?: string;
+
+  // Search and keywords
+  search?: string;
+  keyterm?: string;
+
+  // Speaker-related features
+  diarize?: boolean;
+  utterances?: boolean;
+  utt_split?: number;
+
+  // Miscellaneous
+  filler_words?: boolean;
+};

package/src/deepgram-config.ts

@@ -0,0 +1,9 @@
+import { FetchFunction } from '@ai-sdk/provider-utils';
+
+export type DeepgramConfig = {
+  provider: string;
+  url: (options: { modelId: string; path: string }) => string;
+  headers: () => Record<string, string | undefined>;
+  fetch?: FetchFunction;
+  generateId?: () => string;
+};

package/src/deepgram-error.test.ts

@@ -0,0 +1,34 @@
+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-error.ts

@@ -0,0 +1,16 @@
+import { z } from 'zod/v4';
+import { createJsonErrorResponseHandler } from '@ai-sdk/provider-utils';
+
+export const deepgramErrorDataSchema = z.object({
+  error: z.object({
+    message: z.string(),
+    code: z.number(),
+  }),
+});
+
+export type DeepgramErrorData = z.infer<typeof deepgramErrorDataSchema>;
+
+export const deepgramFailedResponseHandler = createJsonErrorResponseHandler({
+  errorSchema: deepgramErrorDataSchema,
+  errorToMessage: data => data.error.message,
+});

package/src/deepgram-provider.ts

@@ -0,0 +1,139 @@
+import {
+  TranscriptionModelV3,
+  SpeechModelV3,
+  ProviderV3,
+  NoSuchModelError,
+} from '@ai-sdk/provider';
+import {
+  FetchFunction,
+  loadApiKey,
+  withUserAgentSuffix,
+} from '@ai-sdk/provider-utils';
+import { DeepgramTranscriptionModel } from './deepgram-transcription-model';
+import { DeepgramTranscriptionModelId } from './deepgram-transcription-options';
+import { DeepgramSpeechModel } from './deepgram-speech-model';
+import { DeepgramSpeechModelId } from './deepgram-speech-options';
+import { VERSION } from './version';
+
+export interface DeepgramProvider extends ProviderV3 {
+  (
+    modelId: 'nova-3',
+    settings?: {},
+  ): {
+    transcription: DeepgramTranscriptionModel;
+  };
+
+  /**
+Creates a model for transcription.
+   */
+  transcription(modelId: DeepgramTranscriptionModelId): TranscriptionModelV3;
+
+  /**
+Creates a model for speech generation.
+   */
+  speech(modelId: DeepgramSpeechModelId): SpeechModelV3;
+
+  /**
+   * @deprecated Use `embeddingModel` instead.
+   */
+  textEmbeddingModel(modelId: string): never;
+}
+
+export interface DeepgramProviderSettings {
+  /**
+API key for authenticating requests.
+     */
+  apiKey?: string;
+
+  /**
+Custom headers to include in the requests.
+     */
+  headers?: Record<string, string>;
+
+  /**
+Custom fetch implementation. You can use it as a middleware to intercept requests,
+or to provide a custom fetch implementation for e.g. testing.
+    */
+  fetch?: FetchFunction;
+}
+
+/**
+Create an Deepgram provider instance.
+ */
+export function createDeepgram(
+  options: DeepgramProviderSettings = {},
+): DeepgramProvider {
+  const getHeaders = () =>
+    withUserAgentSuffix(
+      {
+        authorization: `Token ${loadApiKey({
+          apiKey: options.apiKey,
+          environmentVariableName: 'DEEPGRAM_API_KEY',
+          description: 'Deepgram',
+        })}`,
+        ...options.headers,
+      },
+      `ai-sdk/deepgram/${VERSION}`,
+    );
+
+  const createTranscriptionModel = (modelId: DeepgramTranscriptionModelId) =>
+    new DeepgramTranscriptionModel(modelId, {
+      provider: `deepgram.transcription`,
+      url: ({ path }) => `https://api.deepgram.com${path}`,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
+
+  const createSpeechModel = (modelId: DeepgramSpeechModelId) =>
+    new DeepgramSpeechModel(modelId, {
+      provider: `deepgram.speech`,
+      url: ({ path }) => `https://api.deepgram.com${path}`,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
+
+  const provider = function (modelId: DeepgramTranscriptionModelId) {
+    return {
+      transcription: createTranscriptionModel(modelId),
+    };
+  };
+
+  provider.specificationVersion = 'v3' as const;
+  provider.transcription = createTranscriptionModel;
+  provider.transcriptionModel = createTranscriptionModel;
+  provider.speech = createSpeechModel;
+  provider.speechModel = createSpeechModel;
+
+  // Required ProviderV3 methods that are not supported
+  provider.languageModel = (modelId: string) => {
+    throw new NoSuchModelError({
+      modelId,
+      modelType: 'languageModel',
+      message: 'Deepgram does not provide language models',
+    });
+  };
+
+  provider.embeddingModel = (modelId: string) => {
+    throw new NoSuchModelError({
+      modelId,
+      modelType: 'embeddingModel',
+      message: 'Deepgram does not provide text embedding models',
+    });
+  };
+  provider.textEmbeddingModel = provider.embeddingModel;
+
+  provider.imageModel = (modelId: string) => {
+    throw new NoSuchModelError({
+      modelId,
+      modelType: 'imageModel',
+      message: 'Deepgram does not provide image models',
+    });
+  };
+
+  return provider as DeepgramProvider;
+}
+
+/**
+Default Deepgram provider instance.
+ */
+export const deepgram = createDeepgram();

package/src/deepgram-speech-api-types.ts

@@ -0,0 +1,15 @@
+export type DeepgramSpeechAPITypes = {
+  // Request body
+  text: string;
+
+  // Query parameters (these are set via query params, not body)
+  model?: string;
+  encoding?: string;
+  sample_rate?: number;
+  bit_rate?: number | string;
+  container?: string;
+  callback?: string;
+  callback_method?: 'POST' | 'PUT';
+  mip_opt_out?: boolean;
+  tag?: string | string[];
+};