@framers/agentos 0.1.109 → 0.1.111

package/dist/speech/providers/OpenAITextToSpeechProvider.d.ts

@@ -1,20 +1,145 @@
 import type { SpeechSynthesisOptions, SpeechSynthesisResult, SpeechVoice, TextToSpeechProvider } from '../types.js';
+/**
+ * Configuration for the {@link OpenAITextToSpeechProvider}.
+ *
+ * @see {@link OpenAITextToSpeechProvider} for usage examples
+ * @see https://platform.openai.com/docs/api-reference/audio/createSpeech
+ */
 export interface OpenAITextToSpeechProviderConfig {
+    /**
+     * OpenAI API key used for authentication.
+     * Sent as `Authorization: Bearer <apiKey>`.
+     */
     apiKey: string;
+    /**
+     * Base URL for the OpenAI API. Override for proxies, Azure OpenAI, or
+     * compatible third-party endpoints.
+     * @default 'https://api.openai.com/v1'
+     */
     baseUrl?: string;
+    /**
+     * Default TTS model. `tts-1` is optimized for real-time, `tts-1-hd` for quality.
+     * @default 'tts-1'
+     */
     model?: string;
+    /**
+     * Default voice identifier. See {@link OPENAI_VOICES} for available options.
+     * @default 'nova'
+     */
     voice?: string;
+    /**
+     * Custom fetch implementation for dependency injection in tests.
+     * @default globalThis.fetch
+     */
     fetchImpl?: typeof fetch;
 }
+/**
+ * Text-to-speech provider that uses the OpenAI TTS API.
+ *
+ * ## API Contract
+ *
+ * - **Endpoint:** `POST {baseUrl}/audio/speech`
+ * - **Authentication:** `Authorization: Bearer <apiKey>`
+ * - **Content-Type:** `application/json`
+ * - **Request body:** `{ model, voice, input, response_format, speed }`
+ * - **Response:** Raw audio bytes in the requested format
+ *
+ * ## Models
+ *
+ * - `tts-1` — Optimized for real-time, lower latency, slightly lower quality
+ * - `tts-1-hd` — Higher quality at the cost of additional latency
+ *
+ * ## Voice Listing
+ *
+ * OpenAI's voice catalog is static (6 voices), so {@link listAvailableVoices}
+ * returns a hardcoded list from {@link OPENAI_VOICES} without making an API call.
+ *
+ * @see {@link OpenAITextToSpeechProviderConfig} for configuration options
+ * @see {@link OpenAIWhisperSpeechToTextProvider} for the corresponding STT provider
+ *
+ * @example
+ * ```ts
+ * const provider = new OpenAITextToSpeechProvider({
+ *   apiKey: process.env.OPENAI_API_KEY!,
+ *   model: 'tts-1',
+ *   voice: 'nova',
+ * });
+ * const result = await provider.synthesize('Hello!', { speed: 1.1 });
+ * ```
+ */
 export declare class OpenAITextToSpeechProvider implements TextToSpeechProvider {
     private readonly config;
+    /** Unique provider identifier used for registration and resolution. */
     readonly id = "openai-tts";
+    /** Human-readable display name for UI and logging. */
     readonly displayName = "OpenAI TTS";
+    /**
+     * Streaming is supported — the OpenAI API streams audio bytes as they
+     * are generated, enabling low-latency playback pipelines.
+     */
     readonly supportsStreaming = true;
+    /** Fetch implementation — injected for testability, defaults to global fetch. */
     private readonly fetchImpl;
+    /**
+     * Creates a new OpenAITextToSpeechProvider.
+     *
+     * @param config - Provider configuration including API key and optional defaults.
+     *
+     * @example
+     * ```ts
+     * const provider = new OpenAITextToSpeechProvider({
+     *   apiKey: 'sk-xxxx',
+     *   voice: 'shimmer',
+     * });
+     * ```
+     */
     constructor(config: OpenAITextToSpeechProviderConfig);
+    /**
+     * Returns the human-readable provider name.
+     *
+     * @returns The display name string `'OpenAI TTS'`.
+     *
+     * @example
+     * ```ts
+     * provider.getProviderName(); // 'OpenAI TTS'
+     * ```
+     */
     getProviderName(): string;
+    /**
+     * Synthesizes speech from text using the OpenAI TTS API.
+     *
+     * @param text - The text to convert to audio. Maximum 4096 characters.
+     * @param options - Optional synthesis settings including voice, model,
+     *   output format, and speed (0.25–4.0 range).
+     * @returns A promise resolving to the audio buffer and metadata.
+     * @throws {Error} When the OpenAI API returns a non-2xx status code.
+     *   Common causes: invalid API key (401), rate limit (429), text too long (400).
+     *
+     * @example
+     * ```ts
+     * const result = await provider.synthesize('Hello world', {
+     *   voice: 'alloy',
+     *   speed: 1.2,
+     *   outputFormat: 'opus',
+     * });
+     * ```
+     */
     synthesize(text: string, options?: SpeechSynthesisOptions): Promise<SpeechSynthesisResult>;
+    /**
+     * Returns the static list of available OpenAI TTS voices.
+     *
+     * Unlike other providers (ElevenLabs, Azure) that require an API call to
+     * list voices, OpenAI's voice catalog is fixed and hardcoded. This method
+     * returns a shallow copy to prevent external mutation.
+     *
+     * @returns A promise resolving to the 6 built-in OpenAI voice options.
+     *
+     * @example
+     * ```ts
+     * const voices = await provider.listAvailableVoices();
+     * const defaultVoice = voices.find(v => v.isDefault); // 'nova'
+     * ```
+     */
     listAvailableVoices(): Promise<SpeechVoice[]>;
 }
 //# sourceMappingURL=OpenAITextToSpeechProvider.d.ts.map

package/dist/speech/providers/OpenAITextToSpeechProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OpenAITextToSpeechProvider.d.ts","sourceRoot":"","sources":["../../../src/speech/providers/OpenAITextToSpeechProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,qBAAqB,EACrB,WAAW,EACX,oBAAoB,EACrB,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,gCAAgC;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AA4BD,qBAAa,0BAA2B,YAAW,oBAAoB;IAMzD,OAAO,CAAC,QAAQ,CAAC,MAAM;IALnC,SAAgB,EAAE,gBAAgB;IAClC,SAAgB,WAAW,gBAAgB;IAC3C,SAAgB,iBAAiB,QAAQ;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAEZ,MAAM,EAAE,gCAAgC;IAIrE,eAAe,IAAI,MAAM;IAInB,UAAU,CACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,qBAAqB,CAAC;IAyC3B,mBAAmB,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;CAGpD"}
+{"version":3,"file":"OpenAITextToSpeechProvider.d.ts","sourceRoot":"","sources":["../../../src/speech/providers/OpenAITextToSpeechProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,qBAAqB,EACrB,WAAW,EACX,oBAAoB,EACrB,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAqDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAAa,0BAA2B,YAAW,oBAAoB;IA6BzD,OAAO,CAAC,QAAQ,CAAC,MAAM;IA5BnC,uEAAuE;IACvE,SAAgB,EAAE,gBAAgB;IAElC,sDAAsD;IACtD,SAAgB,WAAW,gBAAgB;IAE3C;;;OAGG;IACH,SAAgB,iBAAiB,QAAQ;IAEzC,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IAEzC;;;;;;;;;;;;OAYG;gBAC0B,MAAM,EAAE,gCAAgC;IAIrE;;;;;;;;;OASG;IACH,eAAe,IAAI,MAAM;IAIzB;;;;;;;;;;;;;;;;;;OAkBG;IACG,UAAU,CACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,qBAAqB,CAAC;IA2CjC;;;;;;;;;;;;;;OAcG;IACG,mBAAmB,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;CAIpD"}

package/dist/speech/providers/OpenAITextToSpeechProvider.js

@@ -1,3 +1,12 @@
+/**
+ * Static catalog of built-in OpenAI TTS voices.
+ *
+ * These voices are available for both `tts-1` and `tts-1-hd` models.
+ * `'nova'` is marked as default because it provides a good balance of
+ * naturalness and clarity across languages.
+ *
+ * @see https://platform.openai.com/docs/guides/text-to-speech/voice-options
+ */
 const OPENAI_VOICES = [
     { id: 'alloy', name: 'Alloy', provider: 'openai-tts', lang: 'various', isDefault: false },
     { id: 'echo', name: 'Echo', provider: 'openai-tts', lang: 'various', isDefault: false },
@@ -6,6 +15,22 @@ const OPENAI_VOICES = [
     { id: 'nova', name: 'Nova', provider: 'openai-tts', lang: 'various', isDefault: true },
     { id: 'shimmer', name: 'Shimmer', provider: 'openai-tts', lang: 'various', isDefault: false },
 ];
+/**
+ * Maps an OpenAI output format identifier to its corresponding MIME type.
+ *
+ * OpenAI TTS supports multiple output formats. The default is MP3, which
+ * provides good quality at reasonable file sizes. PCM returns raw 24kHz
+ * 16-bit little-endian audio (MIME type `audio/L16`).
+ *
+ * @param format - The OpenAI output format string (e.g. `'mp3'`, `'opus'`).
+ * @returns The corresponding MIME type string.
+ *
+ * @example
+ * ```ts
+ * mimeTypeForOutput('opus'); // 'audio/opus'
+ * mimeTypeForOutput(undefined); // 'audio/mpeg' (default)
+ * ```
+ */
 function mimeTypeForOutput(format) {
     switch (format) {
         case 'opus':
@@ -17,23 +42,106 @@ function mimeTypeForOutput(format) {
         case 'wav':
             return 'audio/wav';
         case 'pcm':
-            return 'audio/L16';
+            return 'audio/L16'; // Raw 24kHz 16-bit little-endian mono
         default:
-            return 'audio/mpeg';
+            return 'audio/mpeg'; // MP3 is the default format
     }
 }
+/**
+ * Text-to-speech provider that uses the OpenAI TTS API.
+ *
+ * ## API Contract
+ *
+ * - **Endpoint:** `POST {baseUrl}/audio/speech`
+ * - **Authentication:** `Authorization: Bearer <apiKey>`
+ * - **Content-Type:** `application/json`
+ * - **Request body:** `{ model, voice, input, response_format, speed }`
+ * - **Response:** Raw audio bytes in the requested format
+ *
+ * ## Models
+ *
+ * - `tts-1` — Optimized for real-time, lower latency, slightly lower quality
+ * - `tts-1-hd` — Higher quality at the cost of additional latency
+ *
+ * ## Voice Listing
+ *
+ * OpenAI's voice catalog is static (6 voices), so {@link listAvailableVoices}
+ * returns a hardcoded list from {@link OPENAI_VOICES} without making an API call.
+ *
+ * @see {@link OpenAITextToSpeechProviderConfig} for configuration options
+ * @see {@link OpenAIWhisperSpeechToTextProvider} for the corresponding STT provider
+ *
+ * @example
+ * ```ts
+ * const provider = new OpenAITextToSpeechProvider({
+ *   apiKey: process.env.OPENAI_API_KEY!,
+ *   model: 'tts-1',
+ *   voice: 'nova',
+ * });
+ * const result = await provider.synthesize('Hello!', { speed: 1.1 });
+ * ```
+ */
 export class OpenAITextToSpeechProvider {
+    /**
+     * Creates a new OpenAITextToSpeechProvider.
+     *
+     * @param config - Provider configuration including API key and optional defaults.
+     *
+     * @example
+     * ```ts
+     * const provider = new OpenAITextToSpeechProvider({
+     *   apiKey: 'sk-xxxx',
+     *   voice: 'shimmer',
+     * });
+     * ```
+     */
     constructor(config) {
         this.config = config;
+        /** Unique provider identifier used for registration and resolution. */
         this.id = 'openai-tts';
+        /** Human-readable display name for UI and logging. */
         this.displayName = 'OpenAI TTS';
+        /**
+         * Streaming is supported — the OpenAI API streams audio bytes as they
+         * are generated, enabling low-latency playback pipelines.
+         */
         this.supportsStreaming = true;
         this.fetchImpl = config.fetchImpl ?? fetch;
     }
+    /**
+     * Returns the human-readable provider name.
+     *
+     * @returns The display name string `'OpenAI TTS'`.
+     *
+     * @example
+     * ```ts
+     * provider.getProviderName(); // 'OpenAI TTS'
+     * ```
+     */
     getProviderName() {
         return this.displayName;
     }
+    /**
+     * Synthesizes speech from text using the OpenAI TTS API.
+     *
+     * @param text - The text to convert to audio. Maximum 4096 characters.
+     * @param options - Optional synthesis settings including voice, model,
+     *   output format, and speed (0.25–4.0 range).
+     * @returns A promise resolving to the audio buffer and metadata.
+     * @throws {Error} When the OpenAI API returns a non-2xx status code.
+     *   Common causes: invalid API key (401), rate limit (429), text too long (400).
+     *
+     * @example
+     * ```ts
+     * const result = await provider.synthesize('Hello world', {
+     *   voice: 'alloy',
+     *   speed: 1.2,
+     *   outputFormat: 'opus',
+     * });
+     * ```
+     */
     async synthesize(text, options = {}) {
+        // Resolve options with fallback chain: per-call options > config > defaults
         const model = options.model ?? this.config.model ?? 'tts-1';
         const voice = options.voice ?? this.config.voice ?? 'nova';
         const outputFormat = options.outputFormat ?? 'mp3';
@@ -48,7 +156,7 @@ export class OpenAITextToSpeechProvider {
                 voice,
                 input: text,
                 response_format: outputFormat,
-                speed: options.speed,
+                speed: options.speed, // undefined is omitted by JSON.stringify
             }),
         });
         if (!response.ok) {
@@ -59,7 +167,7 @@ export class OpenAITextToSpeechProvider {
         return {
             audioBuffer,
             mimeType: mimeTypeForOutput(outputFormat),
-            cost: 0,
+            cost: 0, // Cost tracking is handled at a higher layer
             voiceUsed: voice,
             providerName: this.displayName,
             usage: {
@@ -68,7 +176,23 @@ export class OpenAITextToSpeechProvider {
             },
         };
     }
+    /**
+     * Returns the static list of available OpenAI TTS voices.
+     *
+     * Unlike other providers (ElevenLabs, Azure) that require an API call to
+     * list voices, OpenAI's voice catalog is fixed and hardcoded. This method
+     * returns a shallow copy to prevent external mutation.
+     *
+     * @returns A promise resolving to the 6 built-in OpenAI voice options.
+     *
+     * @example
+     * ```ts
+     * const voices = await provider.listAvailableVoices();
+     * const defaultVoice = voices.find(v => v.isDefault); // 'nova'
+     * ```
+     */
     async listAvailableVoices() {
+        // Return a shallow copy to prevent external mutation of the static catalog
         return [...OPENAI_VOICES];
     }
 }

package/dist/speech/providers/OpenAITextToSpeechProvider.js.map

@@ -1 +1 @@
-{"version":3,"file":"OpenAITextToSpeechProvider.js","sourceRoot":"","sources":["../../../src/speech/providers/OpenAITextToSpeechProvider.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"OpenAITextToSpeechProvider.js","sourceRoot":"","sources":["../../../src/speech/providers/OpenAITextToSpeechProvider.ts"],"names":[],"mappings":"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"}

package/dist/speech/providers/OpenAIWhisperSpeechToTextProvider.d.ts

@@ -1,18 +1,128 @@
 import type { SpeechAudioInput, SpeechToTextProvider, SpeechTranscriptionOptions, SpeechTranscriptionResult } from '../types.js';
+/**
+ * Configuration for the {@link OpenAIWhisperSpeechToTextProvider}.
+ *
+ * @see {@link OpenAIWhisperSpeechToTextProvider} for usage examples
+ * @see https://platform.openai.com/docs/api-reference/audio/createTranscription
+ */
 export interface OpenAIWhisperSpeechToTextProviderConfig {
+    /**
+     * OpenAI API key used for authentication.
+     * Sent as `Authorization: Bearer <apiKey>` in the request header.
+     */
     apiKey: string;
+    /**
+     * Base URL for the OpenAI API. Override for proxies, Azure OpenAI, or
+     * compatible third-party endpoints.
+     * @default 'https://api.openai.com/v1'
+     */
     baseUrl?: string;
+    /**
+     * Default Whisper model to use for transcription.
+     * @default 'whisper-1'
+     */
     model?: string;
+    /**
+     * Custom fetch implementation for dependency injection in tests.
+     * @default globalThis.fetch
+     */
     fetchImpl?: typeof fetch;
 }
+/**
+ * Speech-to-text provider that uses the OpenAI Whisper transcription API.
+ *
+ * ## API Contract
+ *
+ * - **Endpoint:** `POST {baseUrl}/audio/transcriptions`
+ * - **Authentication:** `Authorization: Bearer <apiKey>`
+ * - **Content-Type:** `multipart/form-data` (FormData with file blob)
+ * - **Response format:** Controlled by the `response_format` field; defaults
+ *   to `verbose_json` which includes segments, language detection, and duration.
+ *
+ * ## Supported Response Formats
+ *
+ * - `verbose_json` — Full JSON with segments, duration, and language (default)
+ * - `json` — Minimal JSON with just the text
+ * - `text` — Plain text response (no JSON)
+ * - `srt` — SubRip subtitle format
+ * - `vtt` — WebVTT subtitle format
+ *
+ * When `text`, `srt`, or `vtt` format is used, the response is returned as
+ * plain text and segments are not available.
+ *
+ * @see {@link OpenAIWhisperSpeechToTextProviderConfig} for configuration options
+ * @see {@link normalizeSegments} for the segment normalization logic
+ *
+ * @example
+ * ```ts
+ * const provider = new OpenAIWhisperSpeechToTextProvider({
+ *   apiKey: process.env.OPENAI_API_KEY!,
+ *   model: 'whisper-1',
+ * });
+ * const result = await provider.transcribe(
+ *   { data: audioBuffer, mimeType: 'audio/wav', fileName: 'recording.wav' },
+ *   { language: 'en', responseFormat: 'verbose_json' },
+ * );
+ * ```
+ */
 export declare class OpenAIWhisperSpeechToTextProvider implements SpeechToTextProvider {
     private readonly config;
+    /** Unique provider identifier used for registration and resolution. */
     readonly id = "openai-whisper";
+    /** Human-readable display name for UI and logging. */
     readonly displayName = "OpenAI Whisper";
+    /** Whisper API is batch-only; streaming requires a WebSocket adapter. */
     readonly supportsStreaming = false;
+    /** Fetch implementation — injected for testability, defaults to global fetch. */
     private readonly fetchImpl;
+    /**
+     * Creates a new OpenAIWhisperSpeechToTextProvider.
+     *
+     * @param config - Provider configuration including API key and optional defaults.
+     *
+     * @example
+     * ```ts
+     * const provider = new OpenAIWhisperSpeechToTextProvider({
+     *   apiKey: 'sk-xxxx',
+     *   baseUrl: 'https://api.openai.com/v1', // default
+     *   model: 'whisper-1', // default
+     * });
+     * ```
+     */
     constructor(config: OpenAIWhisperSpeechToTextProviderConfig);
+    /**
+     * Returns the human-readable provider name.
+     *
+     * @returns The display name string `'OpenAI Whisper'`.
+     *
+     * @example
+     * ```ts
+     * provider.getProviderName(); // 'OpenAI Whisper'
+     * ```
+     */
     getProviderName(): string;
+    /**
+     * Transcribes an audio buffer using the OpenAI Whisper API.
+     *
+     * The audio is sent as a multipart form upload with the file, model, and
+     * optional parameters (language, prompt, temperature, response_format).
+     *
+     * @param audio - Raw audio data and metadata. The `data` buffer is wrapped
+     *   in a Blob and sent as a form file field. If `fileName` is not provided,
+     *   a default name is generated from the `format` field.
+     * @param options - Optional transcription settings including language hint,
+     *   context prompt, temperature for sampling, and response format.
+     * @returns A promise resolving to the normalized transcription result.
+     * @throws {Error} When the OpenAI API returns a non-2xx status code.
+     *
+     * @example
+     * ```ts
+     * const result = await provider.transcribe(
+     *   { data: mp3Buffer, mimeType: 'audio/mpeg', fileName: 'voice.mp3' },
+     *   { language: 'fr', prompt: 'Discussion about AI' },
+     * );
+     * ```
+     */
     transcribe(audio: SpeechAudioInput, options?: SpeechTranscriptionOptions): Promise<SpeechTranscriptionResult>;
 }
 //# sourceMappingURL=OpenAIWhisperSpeechToTextProvider.d.ts.map

package/dist/speech/providers/OpenAIWhisperSpeechToTextProvider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OpenAIWhisperSpeechToTextProvider.d.ts","sourceRoot":"","sources":["../../../src/speech/providers/OpenAIWhisperSpeechToTextProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAEhB,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EAE1B,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,uCAAuC;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AA8CD,qBAAa,iCAAkC,YAAW,oBAAoB;IAMhE,OAAO,CAAC,QAAQ,CAAC,MAAM;IALnC,SAAgB,EAAE,oBAAoB;IACtC,SAAgB,WAAW,oBAAoB;IAC/C,SAAgB,iBAAiB,SAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAEZ,MAAM,EAAE,uCAAuC;IAI5E,eAAe,IAAI,MAAM;IAInB,UAAU,CACd,KAAK,EAAE,gBAAgB,EACvB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,yBAAyB,CAAC;CAoEtC"}
+{"version":3,"file":"OpenAIWhisperSpeechToTextProvider.d.ts","sourceRoot":"","sources":["../../../src/speech/providers/OpenAIWhisperSpeechToTextProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAEhB,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EAE1B,MAAM,aAAa,CAAC;AAErB;;;;;GAKG;AACH,MAAM,WAAW,uCAAuC;IACtD;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAqED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,qBAAa,iCAAkC,YAAW,oBAAoB;IA2BhE,OAAO,CAAC,QAAQ,CAAC,MAAM;IA1BnC,uEAAuE;IACvE,SAAgB,EAAE,oBAAoB;IAEtC,sDAAsD;IACtD,SAAgB,WAAW,oBAAoB;IAE/C,yEAAyE;IACzE,SAAgB,iBAAiB,SAAS;IAE1C,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IAEzC;;;;;;;;;;;;;OAaG;gBAC0B,MAAM,EAAE,uCAAuC;IAI5E;;;;;;;;;OASG;IACH,eAAe,IAAI,MAAM;IAIzB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACG,UAAU,CACd,KAAK,EAAE,gBAAgB,EACvB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,yBAAyB,CAAC;CA2EtC"}

package/dist/speech/providers/OpenAIWhisperSpeechToTextProvider.js

@@ -1,9 +1,29 @@
+/**
+ * Normalizes raw segment data from the OpenAI Whisper `verbose_json` response
+ * into strongly-typed {@link SpeechTranscriptionSegment} objects.
+ *
+ * This function performs defensive runtime type checking on every field because
+ * the Whisper API response shape is only partially documented and may include
+ * additional or differently-typed fields depending on the model version.
+ *
+ * The segment fields handled include standard ones (text, start, end, confidence)
+ * as well as Whisper-specific fields (id, seek, tokens, temperature, avg_logprob,
+ * compression_ratio, no_speech_prob) that are preserved for advanced consumers.
+ *
+ * @param input - The raw `segments` array from the Whisper JSON response.
+ *   Expected to be an array of objects, but handles non-array gracefully.
+ * @returns An array of normalized segments, or `undefined` if the input
+ *   is not a valid array.
+ *
+ * @see {@link SpeechTranscriptionSegment} for the output shape
+ */
 function normalizeSegments(input) {
     if (!Array.isArray(input))
         return undefined;
     return input
         .filter((segment) => typeof segment === 'object' && segment !== null)
         .map((segment) => {
+        // Use Record<string, unknown> for safe property access on untyped API data
         const item = segment;
         return {
             text: typeof item.text === 'string' ? item.text : '',
@@ -13,6 +33,7 @@ function normalizeSegments(input) {
             speaker: typeof item.speaker === 'string' || typeof item.speaker === 'number'
                 ? item.speaker
                 : undefined,
+            // Normalize nested word-level data with the same defensive approach
             words: Array.isArray(item.words)
                 ? item.words
                     .filter((word) => typeof word === 'object' && word !== null)
@@ -26,6 +47,7 @@ function normalizeSegments(input) {
                     };
                 })
                 : undefined,
+            // Whisper-specific metadata fields — preserved for advanced consumers
             id: typeof item.id === 'number' ? item.id : undefined,
             seek: typeof item.seek === 'number' ? item.seek : undefined,
             tokens: Array.isArray(item.tokens)
@@ -38,25 +60,114 @@ function normalizeSegments(input) {
         };
     });
 }
+/**
+ * Speech-to-text provider that uses the OpenAI Whisper transcription API.
+ *
+ * ## API Contract
+ *
+ * - **Endpoint:** `POST {baseUrl}/audio/transcriptions`
+ * - **Authentication:** `Authorization: Bearer <apiKey>`
+ * - **Content-Type:** `multipart/form-data` (FormData with file blob)
+ * - **Response format:** Controlled by the `response_format` field; defaults
+ *   to `verbose_json` which includes segments, language detection, and duration.
+ *
+ * ## Supported Response Formats
+ *
+ * - `verbose_json` — Full JSON with segments, duration, and language (default)
+ * - `json` — Minimal JSON with just the text
+ * - `text` — Plain text response (no JSON)
+ * - `srt` — SubRip subtitle format
+ * - `vtt` — WebVTT subtitle format
+ *
+ * When `text`, `srt`, or `vtt` format is used, the response is returned as
+ * plain text and segments are not available.
+ *
+ * @see {@link OpenAIWhisperSpeechToTextProviderConfig} for configuration options
+ * @see {@link normalizeSegments} for the segment normalization logic
+ *
+ * @example
+ * ```ts
+ * const provider = new OpenAIWhisperSpeechToTextProvider({
+ *   apiKey: process.env.OPENAI_API_KEY!,
+ *   model: 'whisper-1',
+ * });
+ * const result = await provider.transcribe(
+ *   { data: audioBuffer, mimeType: 'audio/wav', fileName: 'recording.wav' },
+ *   { language: 'en', responseFormat: 'verbose_json' },
+ * );
+ * ```
+ */
 export class OpenAIWhisperSpeechToTextProvider {
+    /**
+     * Creates a new OpenAIWhisperSpeechToTextProvider.
+     *
+     * @param config - Provider configuration including API key and optional defaults.
+     *
+     * @example
+     * ```ts
+     * const provider = new OpenAIWhisperSpeechToTextProvider({
+     *   apiKey: 'sk-xxxx',
+     *   baseUrl: 'https://api.openai.com/v1', // default
+     *   model: 'whisper-1', // default
+     * });
+     * ```
+     */
     constructor(config) {
         this.config = config;
+        /** Unique provider identifier used for registration and resolution. */
         this.id = 'openai-whisper';
+        /** Human-readable display name for UI and logging. */
         this.displayName = 'OpenAI Whisper';
+        /** Whisper API is batch-only; streaming requires a WebSocket adapter. */
         this.supportsStreaming = false;
         this.fetchImpl = config.fetchImpl ?? fetch;
     }
+    /**
+     * Returns the human-readable provider name.
+     *
+     * @returns The display name string `'OpenAI Whisper'`.
+     *
+     * @example
+     * ```ts
+     * provider.getProviderName(); // 'OpenAI Whisper'
+     * ```
+     */
     getProviderName() {
         return this.displayName;
     }
+    /**
+     * Transcribes an audio buffer using the OpenAI Whisper API.
+     *
+     * The audio is sent as a multipart form upload with the file, model, and
+     * optional parameters (language, prompt, temperature, response_format).
+     *
+     * @param audio - Raw audio data and metadata. The `data` buffer is wrapped
+     *   in a Blob and sent as a form file field. If `fileName` is not provided,
+     *   a default name is generated from the `format` field.
+     * @param options - Optional transcription settings including language hint,
+     *   context prompt, temperature for sampling, and response format.
+     * @returns A promise resolving to the normalized transcription result.
+     * @throws {Error} When the OpenAI API returns a non-2xx status code.
+     *
+     * @example
+     * ```ts
+     * const result = await provider.transcribe(
+     *   { data: mp3Buffer, mimeType: 'audio/mpeg', fileName: 'voice.mp3' },
+     *   { language: 'fr', prompt: 'Discussion about AI' },
+     * );
+     * ```
+     */
     async transcribe(audio, options = {}) {
         const form = new FormData();
         const responseFormat = (options.responseFormat ?? 'verbose_json');
         const model = options.model ?? this.config.model ?? 'whisper-1';
+        // Generate a filename with the correct extension for Whisper's format detection
         const fileName = audio.fileName ?? `speech.${audio.format ?? 'wav'}`;
+        // Build the multipart form payload — Whisper requires a file upload
         form.append('file', new Blob([Uint8Array.from(audio.data)], { type: audio.mimeType ?? 'audio/wav' }), fileName);
         form.append('model', model);
         form.append('response_format', responseFormat);
+        // Optional fields — only include when explicitly set to avoid API warnings
         if (options.language)
             form.append('language', options.language);
         if (options.prompt)
@@ -68,6 +179,7 @@ export class OpenAIWhisperSpeechToTextProvider {
             method: 'POST',
             headers: {
                 Authorization: `Bearer ${this.config.apiKey}`,
+                // Content-Type is NOT set — FormData sets it automatically with boundary
             },
             body: form,
         });
@@ -75,6 +187,8 @@ export class OpenAIWhisperSpeechToTextProvider {
             const message = await response.text();
             throw new Error(`OpenAI Whisper transcription failed (${response.status}): ${message}`);
         }
+        // Plain text responses (format=text, or server returning text/plain)
+        // don't have structured data — return minimal result with just the text.
         if (responseFormat === 'text' || response.headers.get('content-type')?.includes('text/plain')) {
             const text = await response.text();
             return {
@@ -89,6 +203,7 @@ export class OpenAIWhisperSpeechToTextProvider {
                 },
             };
         }
+        // JSON responses (verbose_json or json) — parse and normalize
         const payload = (await response.json());
         const durationSeconds = typeof payload.duration === 'number' ? payload.duration : audio.durationSeconds;
         return {