@ai-sdk/hume 2.0.7 → 2.0.9

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @ai-sdk/hume
 
+## 2.0.9
+
+### Patch Changes
+
+- 8dc54db: chore: add src folders to package bundle
+
+## 2.0.8
+
+### Patch Changes
+
+- Updated dependencies [5c090e7]
+  - @ai-sdk/provider@3.0.4
+  - @ai-sdk/provider-utils@4.0.8
+
 ## 2.0.7
 
 ### Patch Changes

package/dist/index.js

@@ -236,7 +236,7 @@ var HumeSpeechModel = class {
 };
 
 // src/version.ts
-var VERSION = true ? "2.0.7" : "0.0.0-test";
+var VERSION = true ? "2.0.9" : "0.0.0-test";
 
 // src/hume-provider.ts
 function createHume(options = {}) {

package/dist/index.mjs

@@ -216,7 +216,7 @@ var HumeSpeechModel = class {
 };
 
 // src/version.ts
-var VERSION = true ? "2.0.7" : "0.0.0-test";
+var VERSION = true ? "2.0.9" : "0.0.0-test";
 
 // src/hume-provider.ts
 function createHume(options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/hume",
-  "version": "2.0.7",
+  "version": "2.0.9",
   "license": "Apache-2.0",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -8,6 +8,7 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist/**/*",
+    "src",
     "CHANGELOG.md",
     "README.md"
   ],
@@ -20,15 +21,15 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/provider": "3.0.3",
-    "@ai-sdk/provider-utils": "4.0.7"
+    "@ai-sdk/provider": "3.0.4",
+    "@ai-sdk/provider-utils": "4.0.8"
   },
   "devDependencies": {
     "@types/node": "20.17.24",
     "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": {

package/src/hume-api-types.ts

@@ -0,0 +1,29 @@
+type HumeSpeechAPIUtterances = Array<{
+  text: string;
+  description?: string;
+  speed?: number;
+  trailing_silence?: number;
+  voice?:
+    | {
+        id: string;
+        provider?: 'HUME_AI' | 'CUSTOM_VOICE';
+      }
+    | {
+        name: string;
+        provider?: 'HUME_AI' | 'CUSTOM_VOICE';
+      };
+}>;
+
+export type HumeSpeechAPITypes = {
+  utterances: HumeSpeechAPIUtterances;
+  context?:
+    | {
+        generation_id: string;
+      }
+    | {
+        utterances: HumeSpeechAPIUtterances;
+      };
+  format: {
+    type: 'mp3' | 'pcm' | 'wav';
+  };
+};

package/src/hume-config.ts

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

package/src/hume-error.test.ts

@@ -0,0 +1,34 @@
+import { safeParseJSON } from '@ai-sdk/provider-utils';
+import { humeErrorDataSchema } from './hume-error';
+import { describe, it, expect } from 'vitest';
+
+describe('humeErrorDataSchema', () => {
+  it('should parse Hume 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: humeErrorDataSchema,
+    });
+
+    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/hume-error.ts

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

package/src/hume-provider.ts

@@ -0,0 +1,79 @@
+import { SpeechModelV3, ProviderV3 } from '@ai-sdk/provider';
+import {
+  FetchFunction,
+  loadApiKey,
+  withUserAgentSuffix,
+} from '@ai-sdk/provider-utils';
+import { HumeSpeechModel } from './hume-speech-model';
+import { VERSION } from './version';
+
+export interface HumeProvider extends Pick<ProviderV3, 'speechModel'> {
+  (settings?: {}): {
+    speech: HumeSpeechModel;
+  };
+
+  /**
+Creates a model for speech synthesis.
+   */
+  speech(): SpeechModelV3;
+}
+
+export interface HumeProviderSettings {
+  /**
+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 Hume provider instance.
+ */
+export function createHume(options: HumeProviderSettings = {}): HumeProvider {
+  const getHeaders = () =>
+    withUserAgentSuffix(
+      {
+        'X-Hume-Api-Key': loadApiKey({
+          apiKey: options.apiKey,
+          environmentVariableName: 'HUME_API_KEY',
+          description: 'Hume',
+        }),
+        ...options.headers,
+      },
+      `ai-sdk/hume/${VERSION}`,
+    );
+
+  const createSpeechModel = () =>
+    new HumeSpeechModel('', {
+      provider: `hume.speech`,
+      url: ({ path }) => `https://api.hume.ai${path}`,
+      headers: getHeaders,
+      fetch: options.fetch,
+    });
+
+  const provider = function () {
+    return {
+      speech: createSpeechModel(),
+    };
+  };
+
+  provider.speech = createSpeechModel;
+  provider.speechModel = createSpeechModel;
+
+  return provider satisfies HumeProvider;
+}
+
+/**
+Default Hume provider instance.
+ */
+export const hume = createHume();

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

@@ -0,0 +1,214 @@
+import { createTestServer } from '@ai-sdk/test-server/with-vitest';
+import { HumeSpeechModel } from './hume-speech-model';
+import { createHume } from './hume-provider';
+import { describe, it, expect, vi } from 'vitest';
+
+vi.mock('./version', () => ({
+  VERSION: '0.0.0-test',
+}));
+
+const provider = createHume({ apiKey: 'test-api-key' });
+const model = provider.speech();
+
+const server = createTestServer({
+  'https://api.hume.ai/v0/tts/file': {},
+});
+
+describe('doGenerate', () => {
+  function prepareAudioResponse({
+    headers,
+    format = 'mp3',
+  }: {
+    headers?: Record<string, string>;
+    format?: 'mp3' | 'pcm' | 'wav';
+  } = {}) {
+    const audioBuffer = new Uint8Array(100); // Mock audio data
+    server.urls['https://api.hume.ai/v0/tts/file'].response = {
+      type: 'binary',
+      headers: {
+        'content-type': `audio/${format}`,
+        ...headers,
+      },
+      body: Buffer.from(audioBuffer),
+    };
+    return audioBuffer;
+  }
+
+  it('should pass the model and text', async () => {
+    prepareAudioResponse();
+
+    await model.doGenerate({
+      text: 'Hello from the AI SDK!',
+    });
+
+    expect(await server.calls[0].requestBodyJson).toMatchObject({
+      utterances: [
+        {
+          text: 'Hello from the AI SDK!',
+          voice: {
+            id: 'd8ab67c6-953d-4bd8-9370-8fa53a0f1453',
+            provider: 'HUME_AI',
+          },
+        },
+      ],
+      format: {
+        type: 'mp3',
+      },
+    });
+  });
+
+  it('should pass headers', async () => {
+    prepareAudioResponse();
+
+    const provider = createHume({
+      apiKey: 'test-api-key',
+      headers: {
+        'Custom-Provider-Header': 'provider-header-value',
+      },
+    });
+
+    await provider.speech().doGenerate({
+      text: 'Hello from the AI SDK!',
+      headers: {
+        'Custom-Request-Header': 'request-header-value',
+      },
+    });
+
+    expect(server.calls[0].requestHeaders).toMatchObject({
+      'x-hume-api-key': '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/hume/0.0.0-test`,
+    );
+  });
+
+  it('should pass options', async () => {
+    prepareAudioResponse();
+
+    await model.doGenerate({
+      text: 'Hello from the AI SDK!',
+      voice: 'test-voice',
+      outputFormat: 'mp3',
+      speed: 1.5,
+    });
+
+    expect(await server.calls[0].requestBodyJson).toMatchObject({
+      utterances: [
+        {
+          text: 'Hello from the AI SDK!',
+          voice: {
+            id: 'test-voice',
+            provider: 'HUME_AI',
+          },
+          speed: 1.5,
+        },
+      ],
+      format: {
+        type: 'mp3',
+      },
+    });
+  });
+
+  it('should return audio data with correct content type', async () => {
+    const audio = new Uint8Array(100); // Mock audio data
+    prepareAudioResponse({
+      format: 'mp3',
+      headers: {
+        'x-request-id': 'test-request-id',
+        'x-ratelimit-remaining': '123',
+      },
+    });
+
+    const result = await model.doGenerate({
+      text: 'Hello from the AI SDK!',
+      outputFormat: 'mp3',
+    });
+
+    expect(result.audio).toStrictEqual(audio);
+  });
+
+  it('should include response data with timestamp, modelId and headers', async () => {
+    prepareAudioResponse({
+      headers: {
+        'x-request-id': 'test-request-id',
+        'x-ratelimit-remaining': '123',
+      },
+    });
+
+    const testDate = new Date(0);
+    const customModel = new HumeSpeechModel('', {
+      provider: 'test-provider',
+      url: () => 'https://api.hume.ai/v0/tts/file',
+      headers: () => ({}),
+      _internal: {
+        currentDate: () => testDate,
+      },
+    });
+
+    const result = await customModel.doGenerate({
+      text: 'Hello from the AI SDK!',
+    });
+
+    expect(result.response).toMatchObject({
+      timestamp: testDate,
+      headers: {
+        'content-type': 'audio/mp3',
+        'x-request-id': 'test-request-id',
+        'x-ratelimit-remaining': '123',
+      },
+    });
+  });
+
+  it('should use real date when no custom date provider is specified', async () => {
+    prepareAudioResponse();
+
+    const testDate = new Date(0);
+    const customModel = new HumeSpeechModel('', {
+      provider: 'test-provider',
+      url: () => 'https://api.hume.ai/v0/tts/file',
+      headers: () => ({}),
+      _internal: {
+        currentDate: () => testDate,
+      },
+    });
+
+    const result = await customModel.doGenerate({
+      text: 'Hello from the AI SDK!',
+    });
+
+    expect(result.response.timestamp.getTime()).toEqual(testDate.getTime());
+    expect(result.response.modelId).toBe('');
+  });
+
+  it('should handle different audio formats', async () => {
+    const formats = ['mp3', 'pcm', 'wav'] as const;
+
+    for (const format of formats) {
+      const audio = prepareAudioResponse({ format });
+
+      const result = await model.doGenerate({
+        text: 'Hello from the AI SDK!',
+        providerOptions: {
+          lmnt: {
+            format,
+          },
+        },
+      });
+
+      expect(result.audio).toStrictEqual(audio);
+    }
+  });
+
+  it('should include warnings if any are generated', async () => {
+    prepareAudioResponse();
+
+    const result = await model.doGenerate({
+      text: 'Hello from the AI SDK!',
+    });
+
+    expect(result.warnings).toEqual([]);
+  });
+});

package/src/hume-speech-model.ts

@@ -0,0 +1,238 @@
+import { SpeechModelV3, SharedV3Warning } from '@ai-sdk/provider';
+import {
+  combineHeaders,
+  createBinaryResponseHandler,
+  parseProviderOptions,
+  postJsonToApi,
+} from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import { HumeConfig } from './hume-config';
+import { humeFailedResponseHandler } from './hume-error';
+import { HumeSpeechAPITypes } from './hume-api-types';
+
+// https://dev.hume.ai/reference/text-to-speech-tts/synthesize-file
+const humeSpeechCallOptionsSchema = z.object({
+  /**
+   * Context for the speech synthesis request.
+   * Can be either a generationId for retrieving a previous generation,
+   * or a list of utterances to synthesize.
+   */
+  context: z
+    .object({
+      /**
+       * ID of a previously generated speech synthesis to retrieve.
+       */
+      generationId: z.string(),
+    })
+    .or(
+      z.object({
+        /**
+         * List of utterances to synthesize into speech.
+         */
+        utterances: z.array(
+          z.object({
+            /**
+             * The text content to convert to speech.
+             */
+            text: z.string(),
+            /**
+             * Optional description or instructions for how the text should be spoken.
+             */
+            description: z.string().optional(),
+            /**
+             * Optional speech rate multiplier.
+             */
+            speed: z.number().optional(),
+            /**
+             * Optional duration of silence to add after the utterance in seconds.
+             */
+            trailingSilence: z.number().optional(),
+            /**
+             * Voice configuration for the utterance.
+             * Can be specified by ID or name.
+             */
+            voice: z
+              .object({
+                /**
+                 * ID of the voice to use.
+                 */
+                id: z.string(),
+                /**
+                 * Provider of the voice, either Hume's built-in voices or a custom voice.
+                 */
+                provider: z.enum(['HUME_AI', 'CUSTOM_VOICE']).optional(),
+              })
+              .or(
+                z.object({
+                  /**
+                   * Name of the voice to use.
+                   */
+                  name: z.string(),
+                  /**
+                   * Provider of the voice, either Hume's built-in voices or a custom voice.
+                   */
+                  provider: z.enum(['HUME_AI', 'CUSTOM_VOICE']).optional(),
+                }),
+              )
+              .optional(),
+          }),
+        ),
+      }),
+    )
+    .nullish(),
+});
+
+export type HumeSpeechCallOptions = z.infer<typeof humeSpeechCallOptionsSchema>;
+
+interface HumeSpeechModelConfig extends HumeConfig {
+  _internal?: {
+    currentDate?: () => Date;
+  };
+}
+
+export class HumeSpeechModel implements SpeechModelV3 {
+  readonly specificationVersion = 'v3';
+
+  get provider(): string {
+    return this.config.provider;
+  }
+
+  constructor(
+    readonly modelId: '',
+    private readonly config: HumeSpeechModelConfig,
+  ) {}
+
+  private async getArgs({
+    text,
+    voice = 'd8ab67c6-953d-4bd8-9370-8fa53a0f1453',
+    outputFormat = 'mp3',
+    speed,
+    instructions,
+    language,
+    providerOptions,
+  }: Parameters<SpeechModelV3['doGenerate']>[0]) {
+    const warnings: SharedV3Warning[] = [];
+
+    // Parse provider options
+    const humeOptions = await parseProviderOptions({
+      provider: 'hume',
+      providerOptions,
+      schema: humeSpeechCallOptionsSchema,
+    });
+
+    // Create request body
+    const requestBody: HumeSpeechAPITypes = {
+      utterances: [
+        {
+          text,
+          speed,
+          description: instructions,
+          voice: {
+            id: voice,
+            provider: 'HUME_AI',
+          },
+        },
+      ],
+      format: { type: 'mp3' },
+    };
+
+    if (outputFormat) {
+      if (['mp3', 'pcm', 'wav'].includes(outputFormat)) {
+        requestBody.format = { type: outputFormat as 'mp3' | 'pcm' | 'wav' };
+      } else {
+        warnings.push({
+          type: 'unsupported',
+          feature: 'outputFormat',
+          details: `Unsupported output format: ${outputFormat}. Using mp3 instead.`,
+        });
+      }
+    }
+
+    // Add provider-specific options
+    if (humeOptions) {
+      const speechModelOptions: Omit<
+        HumeSpeechAPITypes,
+        'utterances' | 'format'
+      > = {};
+
+      if (humeOptions.context) {
+        if ('generationId' in humeOptions.context) {
+          speechModelOptions.context = {
+            generation_id: humeOptions.context.generationId,
+          };
+        } else {
+          speechModelOptions.context = {
+            utterances: humeOptions.context.utterances.map(utterance => ({
+              text: utterance.text,
+              description: utterance.description,
+              speed: utterance.speed,
+              trailing_silence: utterance.trailingSilence,
+              voice: utterance.voice,
+            })),
+          };
+        }
+      }
+
+      for (const key in speechModelOptions) {
+        const value =
+          speechModelOptions[
+            key as keyof Omit<HumeSpeechAPITypes, 'utterances' | 'format'>
+          ];
+        if (value !== undefined) {
+          (requestBody as Record<string, unknown>)[key] = value;
+        }
+      }
+    }
+
+    if (language) {
+      warnings.push({
+        type: 'unsupported',
+        feature: 'language',
+        details: `Hume speech models do not support language selection. Language parameter "${language}" was ignored.`,
+      });
+    }
+
+    return {
+      requestBody,
+      warnings,
+    };
+  }
+
+  async doGenerate(
+    options: Parameters<SpeechModelV3['doGenerate']>[0],
+  ): Promise<Awaited<ReturnType<SpeechModelV3['doGenerate']>>> {
+    const currentDate = this.config._internal?.currentDate?.() ?? new Date();
+    const { requestBody, warnings } = await this.getArgs(options);
+
+    const {
+      value: audio,
+      responseHeaders,
+      rawValue: rawResponse,
+    } = await postJsonToApi({
+      url: this.config.url({
+        path: '/v0/tts/file',
+        modelId: this.modelId,
+      }),
+      headers: combineHeaders(this.config.headers(), options.headers),
+      body: requestBody,
+      failedResponseHandler: humeFailedResponseHandler,
+      successfulResponseHandler: createBinaryResponseHandler(),
+      abortSignal: options.abortSignal,
+      fetch: this.config.fetch,
+    });
+
+    return {
+      audio,
+      warnings,
+      request: {
+        body: JSON.stringify(requestBody),
+      },
+      response: {
+        timestamp: currentDate,
+        modelId: this.modelId,
+        headers: responseHeaders,
+        body: rawResponse,
+      },
+    };
+  }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+export { createHume, hume } from './hume-provider';
+export type { HumeProvider, HumeProviderSettings } from './hume-provider';
+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';