@framers/agentos 0.1.110 → 0.1.112

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

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

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

@@ -1,20 +1,179 @@
 import type { AdaptiveVADConfig } from '../../core/audio/AdaptiveVAD.js';
 import type { CalibrationConfig } from '../../core/audio/EnvironmentalCalibrator.js';
 import type { SpeechVadDecision, SpeechVadProvider } from '../types.js';
+/**
+ * Configuration for the {@link BuiltInAdaptiveVadProvider}.
+ *
+ * All fields are optional — sensible defaults are applied for 16kHz mono
+ * audio with 20ms frames (the standard voice pipeline configuration).
+ *
+ * @see {@link BuiltInAdaptiveVadProvider} for usage examples
+ * @see {@link AdaptiveVADConfig} for detailed VAD tuning parameters
+ * @see {@link CalibrationConfig} for environmental calibration settings
+ */
 export interface BuiltInAdaptiveVadProviderConfig {
+    /**
+     * Audio sample rate in Hz. Must match the actual audio stream.
+     * @default 16_000 (16 kHz, standard for voice processing)
+     */
     sampleRate?: number;
+    /**
+     * Duration of each audio frame in milliseconds. Determines the number
+     * of samples expected in each `processFrame()` call.
+     * At 16kHz with 20ms frames, each frame is 320 samples.
+     * @default 20
+     */
     frameDurationMs?: number;
+    /**
+     * Environmental calibration settings. Controls how the noise floor and
+     * spectral profile are estimated from ambient audio.
+     *
+     * @see {@link CalibrationConfig} for available options
+     */
     calibration?: CalibrationConfig;
+    /**
+     * VAD algorithm configuration. Controls speech detection thresholds,
+     * minimum speech duration, hangover period, etc.
+     *
+     * @see {@link AdaptiveVADConfig} for available options
+     */
     vad?: AdaptiveVADConfig;
 }
+/**
+ * Built-in voice activity detection (VAD) provider backed by the
+ * {@link AdaptiveVAD} engine and {@link EnvironmentalCalibrator}.
+ *
+ * This is the default VAD provider in AgentOS and requires no external
+ * dependencies or API keys. It operates entirely locally on raw audio frames.
+ *
+ * ## How It Works
+ *
+ * 1. The {@link EnvironmentalCalibrator} continuously estimates the ambient
+ *    noise floor and spectral profile from incoming audio frames.
+ * 2. The {@link AdaptiveVAD} uses the calibrator's noise profile to set
+ *    dynamic thresholds for speech detection — louder environments get
+ *    higher thresholds to avoid false positives.
+ * 3. Each `processFrame()` call returns a {@link SpeechVadDecision} with
+ *    `isSpeech`, `confidence`, the raw VAD result, and the current noise profile.
+ *
+ * ## Configuration Defaults
+ *
+ * - Sample rate: 16 kHz (standard for voice pipelines)
+ * - Frame duration: 20ms (320 samples per frame)
+ * - VAD and calibration: Use sensible defaults from the underlying engines
+ *
+ * @see {@link BuiltInAdaptiveVadProviderConfig} for configuration options
+ * @see {@link AdaptiveVAD} for the underlying VAD algorithm
+ * @see {@link EnvironmentalCalibrator} for the noise profiling engine
+ *
+ * @example
+ * ```ts
+ * const vad = new BuiltInAdaptiveVadProvider({
+ *   sampleRate: 16_000,
+ *   frameDurationMs: 20,
+ *   vad: { minSpeechDurationMs: 100 },
+ * });
+ *
+ * const frame = new Float32Array(320); // 20ms at 16kHz
+ * // ... fill frame with audio samples ...
+ * const decision = vad.processFrame(frame);
+ * if (decision.isSpeech) {
+ *   console.log(`Speech detected (confidence: ${decision.confidence})`);
+ * }
+ * ```
+ */
 export declare class BuiltInAdaptiveVadProvider implements SpeechVadProvider {
+    /** Unique provider identifier used for registration and resolution. */
     readonly id = "agentos-adaptive-vad";
+    /** Human-readable display name for UI and logging. */
     readonly displayName = "AgentOS Adaptive VAD";
+    /**
+     * Environmental calibrator that estimates the ambient noise profile.
+     * Shared with the VAD engine for dynamic threshold adaptation.
+     */
     private readonly calibrator;
+    /**
+     * Adaptive VAD engine that performs frame-by-frame speech detection
+     * using the calibrator's noise profile for dynamic thresholding.
+     */
     private readonly vad;
+    /**
+     * Creates a new BuiltInAdaptiveVadProvider.
+     *
+     * Initializes both the environmental calibrator and the adaptive VAD
+     * engine with the provided or default configuration.
+     *
+     * @param config - Optional VAD configuration. All fields default to
+     *   standard values suitable for 16kHz mono voice audio.
+     *
+     * @example
+     * ```ts
+     * // Default configuration (16kHz, 20ms frames)
+     * const vad = new BuiltInAdaptiveVadProvider();
+     *
+     * // Custom configuration
+     * const vad = new BuiltInAdaptiveVadProvider({
+     *   sampleRate: 48_000,
+     *   frameDurationMs: 10,
+     *   vad: { minSpeechDurationMs: 200 },
+     * });
+     * ```
+     */
     constructor(config?: BuiltInAdaptiveVadProviderConfig);
+    /**
+     * Process a single audio frame and return a speech/non-speech decision.
+     *
+     * This method must be called sequentially with consecutive audio frames.
+     * The VAD maintains internal state (speech onset tracking, hangover counters)
+     * that depends on temporal continuity between frames.
+     *
+     * @param frame - A Float32Array of audio samples for one frame. The expected
+     *   length is `sampleRate * frameDurationMs / 1000` (e.g. 320 for 16kHz/20ms).
+     *   Samples should be normalized to the range [-1.0, 1.0].
+     * @returns A decision object with `isSpeech`, `confidence`, the raw VAD result,
+     *   and the current environmental noise profile.
+     *
+     * @example
+     * ```ts
+     * const frame = new Float32Array(320);
+     * // ... fill with audio samples ...
+     * const decision = vad.processFrame(frame);
+     * console.log(decision.isSpeech, decision.confidence);
+     * ```
+     */
     processFrame(frame: Float32Array): SpeechVadDecision;
+    /**
+     * Reset the VAD state for a new audio session.
+     *
+     * Clears internal counters (speech onset tracking, hangover timers) so the
+     * VAD starts fresh. Should be called when starting a new conversation turn
+     * or after a significant audio gap. Does NOT reset the environmental
+     * calibrator — the noise profile persists across resets.
+     *
+     * @example
+     * ```ts
+     * // Start a new conversation turn
+     * vad.reset();
+     * ```
+     */
     reset(): void;
+    /**
+     * Returns the current environmental noise profile estimated by the calibrator.
+     *
+     * The noise profile includes the estimated noise floor RMS, spectral shape,
+     * and confidence metrics. Returns `null` if insufficient audio has been
+     * processed for a reliable estimate.
+     *
+     * @returns The current noise profile, or `null` if not yet calibrated.
+     *
+     * @example
+     * ```ts
+     * const profile = vad.getNoiseProfile();
+     * if (profile) {
+     *   console.log(`Noise floor: ${profile.noiseFloorRms}`);
+     * }
+     * ```
+     */
     getNoiseProfile(): import("../../core/index.js").NoiseProfile | null;
 }
 //# sourceMappingURL=BuiltInAdaptiveVadProvider.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"BuiltInAdaptiveVadProvider.d.ts","sourceRoot":"","sources":["../../../src/speech/providers/BuiltInAdaptiveVadProvider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,iBAAiB,EAClB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AACrF,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAExE,MAAM,WAAW,gCAAgC;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAChC,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED,qBAAa,0BAA2B,YAAW,iBAAiB;IAClE,SAAgB,EAAE,0BAA0B;IAC5C,SAAgB,WAAW,0BAA0B;IACrD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA0B;IACrD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;gBAEtB,MAAM,GAAE,gCAAqC;IAYzD,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,iBAAiB;IAUpD,KAAK,IAAI,IAAI;IAIb,eAAe;CAGhB"}
+{"version":3,"file":"BuiltInAdaptiveVadProvider.d.ts","sourceRoot":"","sources":["../../../src/speech/providers/BuiltInAdaptiveVadProvider.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,iBAAiB,EAClB,MAAM,iCAAiC,CAAC;AACzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AACrF,OAAO,KAAK,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAExE;;;;;;;;;GASG;AACH,MAAM,WAAW,gCAAgC;IAC/C;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,iBAAiB,CAAC;IAEhC;;;;;OAKG;IACH,GAAG,CAAC,EAAE,iBAAiB,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBAAa,0BAA2B,YAAW,iBAAiB;IAClE,uEAAuE;IACvE,SAAgB,EAAE,0BAA0B;IAE5C,sDAAsD;IACtD,SAAgB,WAAW,0BAA0B;IAErD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA0B;IAErD;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAc;IAElC;;;;;;;;;;;;;;;;;;;;;OAqBG;gBACS,MAAM,GAAE,gCAAqC;IAYzD;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,iBAAiB;IAUpD;;;;;;;;;;;;;OAaG;IACH,KAAK,IAAI,IAAI;IAIb;;;;;;;;;;;;;;;;OAgBG;IACH,eAAe;CAGhB"}

package/dist/speech/providers/BuiltInAdaptiveVadProvider.js

@@ -1,8 +1,75 @@
 import { AdaptiveVAD } from '../../core/audio/AdaptiveVAD.js';
 import { EnvironmentalCalibrator } from '../../core/audio/EnvironmentalCalibrator.js';
+/**
+ * Built-in voice activity detection (VAD) provider backed by the
+ * {@link AdaptiveVAD} engine and {@link EnvironmentalCalibrator}.
+ *
+ * This is the default VAD provider in AgentOS and requires no external
+ * dependencies or API keys. It operates entirely locally on raw audio frames.
+ *
+ * ## How It Works
+ *
+ * 1. The {@link EnvironmentalCalibrator} continuously estimates the ambient
+ *    noise floor and spectral profile from incoming audio frames.
+ * 2. The {@link AdaptiveVAD} uses the calibrator's noise profile to set
+ *    dynamic thresholds for speech detection — louder environments get
+ *    higher thresholds to avoid false positives.
+ * 3. Each `processFrame()` call returns a {@link SpeechVadDecision} with
+ *    `isSpeech`, `confidence`, the raw VAD result, and the current noise profile.
+ *
+ * ## Configuration Defaults
+ *
+ * - Sample rate: 16 kHz (standard for voice pipelines)
+ * - Frame duration: 20ms (320 samples per frame)
+ * - VAD and calibration: Use sensible defaults from the underlying engines
+ *
+ * @see {@link BuiltInAdaptiveVadProviderConfig} for configuration options
+ * @see {@link AdaptiveVAD} for the underlying VAD algorithm
+ * @see {@link EnvironmentalCalibrator} for the noise profiling engine
+ *
+ * @example
+ * ```ts
+ * const vad = new BuiltInAdaptiveVadProvider({
+ *   sampleRate: 16_000,
+ *   frameDurationMs: 20,
+ *   vad: { minSpeechDurationMs: 100 },
+ * });
+ *
+ * const frame = new Float32Array(320); // 20ms at 16kHz
+ * // ... fill frame with audio samples ...
+ * const decision = vad.processFrame(frame);
+ * if (decision.isSpeech) {
+ *   console.log(`Speech detected (confidence: ${decision.confidence})`);
+ * }
+ * ```
+ */
 export class BuiltInAdaptiveVadProvider {
+    /**
+     * Creates a new BuiltInAdaptiveVadProvider.
+     *
+     * Initializes both the environmental calibrator and the adaptive VAD
+     * engine with the provided or default configuration.
+     *
+     * @param config - Optional VAD configuration. All fields default to
+     *   standard values suitable for 16kHz mono voice audio.
+     *
+     * @example
+     * ```ts
+     * // Default configuration (16kHz, 20ms frames)
+     * const vad = new BuiltInAdaptiveVadProvider();
+     *
+     * // Custom configuration
+     * const vad = new BuiltInAdaptiveVadProvider({
+     *   sampleRate: 48_000,
+     *   frameDurationMs: 10,
+     *   vad: { minSpeechDurationMs: 200 },
+     * });
+     * ```
+     */
     constructor(config = {}) {
+        /** Unique provider identifier used for registration and resolution. */
         this.id = 'agentos-adaptive-vad';
+        /** Human-readable display name for UI and logging. */
         this.displayName = 'AgentOS Adaptive VAD';
         this.calibrator = new EnvironmentalCalibrator({
             sampleRate: config.sampleRate ?? 16000,
@@ -10,6 +77,27 @@ export class BuiltInAdaptiveVadProvider {
         });
         this.vad = new AdaptiveVAD(config.vad ?? {}, this.calibrator, config.frameDurationMs ?? 20);
     }
+    /**
+     * Process a single audio frame and return a speech/non-speech decision.
+     *
+     * This method must be called sequentially with consecutive audio frames.
+     * The VAD maintains internal state (speech onset tracking, hangover counters)
+     * that depends on temporal continuity between frames.
+     *
+     * @param frame - A Float32Array of audio samples for one frame. The expected
+     *   length is `sampleRate * frameDurationMs / 1000` (e.g. 320 for 16kHz/20ms).
+     *   Samples should be normalized to the range [-1.0, 1.0].
+     * @returns A decision object with `isSpeech`, `confidence`, the raw VAD result,
+     *   and the current environmental noise profile.
+     *
+     * @example
+     * ```ts
+     * const frame = new Float32Array(320);
+     * // ... fill with audio samples ...
+     * const decision = vad.processFrame(frame);
+     * console.log(decision.isSpeech, decision.confidence);
+     * ```
+     */
     processFrame(frame) {
         const result = this.vad.processFrame(frame);
         return {
@@ -19,9 +107,40 @@ export class BuiltInAdaptiveVadProvider {
             profile: this.calibrator.getCurrentProfile(),
         };
     }
+    /**
+     * Reset the VAD state for a new audio session.
+     *
+     * Clears internal counters (speech onset tracking, hangover timers) so the
+     * VAD starts fresh. Should be called when starting a new conversation turn
+     * or after a significant audio gap. Does NOT reset the environmental
+     * calibrator — the noise profile persists across resets.
+     *
+     * @example
+     * ```ts
+     * // Start a new conversation turn
+     * vad.reset();
+     * ```
+     */
     reset() {
         this.vad.resetState();
     }
+    /**
+     * Returns the current environmental noise profile estimated by the calibrator.
+     *
+     * The noise profile includes the estimated noise floor RMS, spectral shape,
+     * and confidence metrics. Returns `null` if insufficient audio has been
+     * processed for a reliable estimate.
+     *
+     * @returns The current noise profile, or `null` if not yet calibrated.
+     *
+     * @example
+     * ```ts
+     * const profile = vad.getNoiseProfile();
+     * if (profile) {
+     *   console.log(`Noise floor: ${profile.noiseFloorRms}`);
+     * }
+     * ```
+     */
     getNoiseProfile() {
         return this.calibrator.getCurrentProfile();
     }

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

@@ -1 +1 @@
-{"version":3,"file":"BuiltInAdaptiveVadProvider.js","sourceRoot":"","sources":["../../../src/speech/providers/BuiltInAdaptiveVadProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,6CAA6C,CAAC;AActF,MAAM,OAAO,0BAA0B;IAMrC,YAAY,SAA2C,EAAE;QALzC,OAAE,GAAG,sBAAsB,CAAC;QAC5B,gBAAW,GAAG,sBAAsB,CAAC;QAKnD,IAAI,CAAC,UAAU,GAAG,IAAI,uBAAuB,CAAC;YAC5C,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,KAAM;YACvC,GAAG,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC;SAC9B,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,GAAG,IAAI,WAAW,CACxB,MAAM,CAAC,GAAG,IAAI,EAAE,EAChB,IAAI,CAAC,UAAU,EACf,MAAM,CAAC,eAAe,IAAI,EAAE,CAC7B,CAAC;IACJ,CAAC;IAED,YAAY,CAAC,KAAmB;QAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAC5C,OAAO;YACL,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,MAAM;YACN,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC,iBAAiB,EAAE;SAC7C,CAAC;IACJ,CAAC;IAED,KAAK;QACH,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC;IACxB,CAAC;IAED,eAAe;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,iBAAiB,EAAE,CAAC;IAC7C,CAAC;CACF"}
+{"version":3,"file":"BuiltInAdaptiveVadProvider.js","sourceRoot":"","sources":["../../../src/speech/providers/BuiltInAdaptiveVadProvider.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAC9D,OAAO,EAAE,uBAAuB,EAAE,MAAM,6CAA6C,CAAC;AAiDtF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,OAAO,0BAA0B;IAmBrC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,YAAY,SAA2C,EAAE;QAxCzD,uEAAuE;QACvD,OAAE,GAAG,sBAAsB,CAAC;QAE5C,sDAAsD;QACtC,gBAAW,GAAG,sBAAsB,CAAC;QAqCnD,IAAI,CAAC,UAAU,GAAG,IAAI,uBAAuB,CAAC;YAC5C,UAAU,EAAE,MAAM,CAAC,UAAU,IAAI,KAAM;YACvC,GAAG,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC;SAC9B,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,GAAG,IAAI,WAAW,CACxB,MAAM,CAAC,GAAG,IAAI,EAAE,EAChB,IAAI,CAAC,UAAU,EACf,MAAM,CAAC,eAAe,IAAI,EAAE,CAC7B,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,CAAC,KAAmB;QAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QAC5C,OAAO;YACL,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,MAAM;YACN,OAAO,EAAE,IAAI,CAAC,UAAU,CAAC,iBAAiB,EAAE;SAC7C,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,KAAK;QACH,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,CAAC;IACxB,CAAC;IAED;;;;;;;;;;;;;;;;OAgBG;IACH,eAAe;QACb,OAAO,IAAI,CAAC,UAAU,CAAC,iBAAiB,EAAE,CAAC;IAC7C,CAAC;CACF"}

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

@@ -1,54 +1,140 @@
 import type { SpeechAudioInput, SpeechToTextProvider, SpeechTranscriptionOptions, SpeechTranscriptionResult } from '../types.js';
-/** Configuration for the DeepgramBatchSTTProvider. */
+/**
+ * Configuration for the {@link DeepgramBatchSTTProvider}.
+ *
+ * @see {@link DeepgramBatchSTTProvider} for usage examples
+ */
 export interface DeepgramBatchSTTProviderConfig {
-    /** Deepgram API key. */
+    /**
+     * Deepgram API key used for authentication.
+     * Sent as `Authorization: Token <apiKey>` in the request header.
+     */
     apiKey: string;
     /**
      * Deepgram model to use for transcription.
+     * See https://developers.deepgram.com/docs/models for available models.
      * @default 'nova-2'
      */
     model?: string;
     /**
-     * BCP-47 language code, e.g. `'en-US'`.
-     * When omitted Deepgram uses automatic language detection.
+     * BCP-47 language code, e.g. `'en-US'`, `'fr-FR'`, `'de-DE'`.
+     * When omitted, Deepgram applies automatic language detection.
+     * @default 'en-US' (set at transcribe-time if not configured here)
      */
     language?: string;
     /**
-     * Custom fetch implementation, useful for testing.
-     * Defaults to the global `fetch`.
+     * Custom fetch implementation for dependency injection in tests.
+     * When omitted, the global `fetch` is used. This allows tests to
+     * intercept HTTP calls without mocking globals.
+     * @default globalThis.fetch
      */
     fetchImpl?: typeof fetch;
 }
 /**
  * Speech-to-text provider that uses the Deepgram batch (pre-recorded) REST API.
  *
- * Sends audio as a raw binary body and returns a normalised
- * {@link SpeechTranscriptionResult}. Streaming is not supported — use a
- * Deepgram streaming adapter for real-time transcription.
+ * ## REST API Contract
+ *
+ * - **Endpoint:** `POST https://api.deepgram.com/v1/listen`
+ * - **Authentication:** `Authorization: Token <apiKey>` header
+ * - **Content-Type:** Set to the audio's MIME type (e.g. `audio/wav`)
+ * - **Body:** Raw audio bytes sent directly (no multipart form)
+ * - **Query parameters:** `model`, `punctuate`, `diarize`, `language`
+ * - **Response:** JSON containing `results.channels[].alternatives[]` with
+ *   transcript text, confidence scores, and optional word-level timing
+ *
+ * ## Word-Level Diarization Mapping
+ *
+ * When `enableSpeakerDiarization` is `true`, the `diarize=true` query parameter
+ * is set. Deepgram then includes a `speaker` field (zero-based integer index) on
+ * each word in the response. These speaker indices are preserved through the
+ * {@link wordsToSegments} mapping into the normalized result.
+ *
+ * ## Error Handling
+ *
+ * Non-2xx responses from Deepgram trigger an `Error` with the HTTP status code
+ * and response body text included in the message for debugging. Network-level
+ * errors (DNS failures, timeouts) propagate as-is from the fetch implementation.
+ *
+ * Streaming is NOT supported by this provider — use a Deepgram WebSocket adapter
+ * for real-time transcription.
+ *
+ * @see {@link DeepgramBatchSTTProviderConfig} for configuration options
+ * @see {@link wordsToSegments} for the word-to-segment mapping logic
  *
  * @example
  * ```ts
- * const provider = new DeepgramBatchSTTProvider({ apiKey: process.env.DEEPGRAM_API_KEY! });
- * const result = await provider.transcribe({ data: audioBuffer, mimeType: 'audio/wav' });
+ * const provider = new DeepgramBatchSTTProvider({
+ *   apiKey: process.env.DEEPGRAM_API_KEY!,
+ *   model: 'nova-2',
+ * });
+ * const result = await provider.transcribe(
+ *   { data: audioBuffer, mimeType: 'audio/wav' },
+ *   { enableSpeakerDiarization: true },
+ * );
  * console.log(result.text);
+ * console.log(result.segments?.map(s => `[Speaker ${s.speaker}] ${s.text}`));
  * ```
  */
 export declare class DeepgramBatchSTTProvider implements SpeechToTextProvider {
     private readonly config;
+    /** Unique provider identifier used for registration and resolution. */
     readonly id = "deepgram-batch";
+    /** Human-readable display name for UI and logging. */
     readonly displayName = "Deepgram (Batch)";
+    /** This provider uses synchronous HTTP requests, not WebSocket streaming. */
     readonly supportsStreaming = false;
+    /** Fetch implementation — injected for testability, defaults to global fetch. */
     private readonly fetchImpl;
+    /**
+     * Creates a new DeepgramBatchSTTProvider.
+     *
+     * @param config - Provider configuration including API key and optional defaults.
+     *
+     * @example
+     * ```ts
+     * const provider = new DeepgramBatchSTTProvider({
+     *   apiKey: 'dg-xxxx',
+     *   model: 'nova-2',
+     *   language: 'en-US',
+     * });
+     * ```
+     */
     constructor(config: DeepgramBatchSTTProviderConfig);
-    /** Returns the human-readable provider name. */
+    /**
+     * Returns the human-readable provider name.
+     *
+     * @returns The display name string `'Deepgram (Batch)'`.
+     *
+     * @example
+     * ```ts
+     * provider.getProviderName(); // 'Deepgram (Batch)'
+     * ```
+     */
     getProviderName(): string;
     /**
      * Transcribes an audio buffer using the Deepgram pre-recorded API.
      *
-     * @param audio - Raw audio data and associated metadata.
-     * @param options - Optional transcription settings (language, diarization…).
-     * @returns A promise resolving to the normalised transcription result.
-     * @throws When the Deepgram API returns a non-2xx status.
+     * Sends the raw audio bytes as the request body (not multipart form) with
+     * the appropriate Content-Type header. The response is parsed and normalized
+     * into a {@link SpeechTranscriptionResult}.
+     *
+     * @param audio - Raw audio data and associated metadata (buffer, MIME type,
+     *   duration). The `data` buffer is sent directly as the request body.
+     * @param options - Optional transcription settings. Supports `model`,
+     *   `language`, and `enableSpeakerDiarization` overrides.
+     * @returns A promise resolving to the normalized transcription result with
+     *   text, confidence, timing, and optional speaker-attributed segments.
+     * @throws {Error} When the Deepgram API returns a non-2xx status code.
+     *   The error message includes the HTTP status and response body for debugging.
+     *
+     * @example
+     * ```ts
+     * const result = await provider.transcribe(
+     *   { data: wavBuffer, mimeType: 'audio/wav', durationSeconds: 5.2 },
+     *   { language: 'fr-FR', enableSpeakerDiarization: true },
+     * );
+     * ```
      */
     transcribe(audio: SpeechAudioInput, options?: SpeechTranscriptionOptions): Promise<SpeechTranscriptionResult>;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"DeepgramBatchSTTProvider.d.ts","sourceRoot":"","sources":["../../../src/speech/providers/DeepgramBatchSTTProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EAE1B,MAAM,aAAa,CAAC;AAErB,sDAAsD;AACtD,MAAM,WAAW,8BAA8B;IAC7C,wBAAwB;IACxB,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAoDD;;;;;;;;;;;;;GAaG;AACH,qBAAa,wBAAyB,YAAW,oBAAoB;IAOvD,OAAO,CAAC,QAAQ,CAAC,MAAM;IANnC,SAAgB,EAAE,oBAAoB;IACtC,SAAgB,WAAW,sBAAsB;IACjD,SAAgB,iBAAiB,SAAS;IAE1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAEZ,MAAM,EAAE,8BAA8B;IAInE,gDAAgD;IAChD,eAAe,IAAI,MAAM;IAIzB;;;;;;;OAOG;IACG,UAAU,CACd,KAAK,EAAE,gBAAgB,EACvB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,yBAAyB,CAAC;CAmDtC"}
+{"version":3,"file":"DeepgramBatchSTTProvider.d.ts","sourceRoot":"","sources":["../../../src/speech/providers/DeepgramBatchSTTProvider.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,gBAAgB,EAChB,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EAE1B,MAAM,aAAa,CAAC;AAErB;;;;GAIG;AACH,MAAM,WAAW,8BAA8B;IAC7C;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AA4FD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,wBAAyB,YAAW,oBAAoB;IA2BvD,OAAO,CAAC,QAAQ,CAAC,MAAM;IA1BnC,uEAAuE;IACvE,SAAgB,EAAE,oBAAoB;IAEtC,sDAAsD;IACtD,SAAgB,WAAW,sBAAsB;IAEjD,6EAA6E;IAC7E,SAAgB,iBAAiB,SAAS;IAE1C,iFAAiF;IACjF,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IAEzC;;;;;;;;;;;;;OAaG;gBAC0B,MAAM,EAAE,8BAA8B;IAInE;;;;;;;;;OASG;IACH,eAAe,IAAI,MAAM;IAIzB;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,UAAU,CACd,KAAK,EAAE,gBAAgB,EACvB,OAAO,GAAE,0BAA+B,GACvC,OAAO,CAAC,yBAAyB,CAAC;CA8DtC"}