@framers/agentos-ext-streaming-stt-deepgram 0.2.0

package/dist/DeepgramStreamSession.js

@@ -0,0 +1,351 @@
+/**
+ * @file DeepgramStreamSession.ts
+ * @description Active streaming STT session backed by the Deepgram WebSocket API.
+ *
+ * {@link DeepgramStreamSession} implements the {@link StreamingSTTSession} interface
+ * (which extends `EventEmitter`) and adds Deepgram-specific convenience events:
+ *
+ * | Event                 | Payload              | Description                                           |
+ * |-----------------------|----------------------|-------------------------------------------------------|
+ * | `'transcript'`        | `TranscriptEvent`    | Every hypothesis (interim + final, per base interface)|
+ * | `'interim_transcript'`| `TranscriptEvent`    | Non-final hypothesis only                             |
+ * | `'final_transcript'`  | `TranscriptEvent`    | Final (stable) hypothesis                             |
+ * | `'speech_start'`      | —                    | First non-empty word received in this utterance       |
+ * | `'speech_end'`        | —                    | Deepgram `speech_final` flag fired                    |
+ * | `'error'`             | `Error`              | Unrecoverable provider error                          |
+ * | `'close'`             | —                    | Session fully terminated                              |
+ *
+ * ### Auto-reconnect
+ * On an unexpected WebSocket close (code ≠ 1000/1001), the session buffers
+ * incoming audio frames (up to 5 s worth at 16 kHz / 512 samples per frame)
+ * and reattempts the connection with exponential back-off starting at 100 ms,
+ * doubling each attempt up to a cap of 5 000 ms.
+ *
+ * @module streaming-stt-deepgram/DeepgramStreamSession
+ */
+import { EventEmitter } from 'node:events';
+import WebSocket from 'ws';
+import { extractSpeakerFromWords, mapDeepgramWord } from './DeepgramDiarizationAdapter.js';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+/** Deepgram WebSocket entry point for streaming recognition. */
+const DEEPGRAM_WS_BASE = 'wss://api.deepgram.com/v1/listen';
+/** Maximum number of audio frames to buffer during reconnect (~5 s at 16 kHz/512). */
+const MAX_BUFFER_FRAMES = 500;
+/** Initial reconnect back-off delay in milliseconds. */
+const BACKOFF_INITIAL_MS = 100;
+/** Maximum reconnect back-off delay in milliseconds. */
+const BACKOFF_MAX_MS = 5_000;
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Convert a Float32Array of normalised PCM samples to a 16-bit signed integer
+ * PCM Buffer (little-endian), as required by the Deepgram `linear16` encoding.
+ *
+ * Samples are clamped to [-1, 1] before scaling to prevent wrap-around on
+ * values outside the normalised range.
+ *
+ * @param samples - Float32 PCM input, each sample in [-1, 1].
+ * @returns Node.js `Buffer` of Int16 samples (2 bytes each, little-endian).
+ */
+function float32ToInt16Buffer(samples) {
+    const buf = Buffer.allocUnsafe(samples.length * 2);
+    for (let i = 0; i < samples.length; i++) {
+        // Clamp to [-1, 1] then scale to the Int16 range.
+        const clamped = Math.max(-1, Math.min(1, samples[i]));
+        buf.writeInt16LE(Math.round(clamped * 0x7fff), i * 2);
+    }
+    return buf;
+}
+/**
+ * Build the Deepgram WebSocket URL from the resolved configuration.
+ *
+ * @param cfg - Resolved Deepgram streaming configuration.
+ * @returns Full `wss://` URL with query parameters.
+ */
+function buildWsUrl(cfg) {
+    const params = new URLSearchParams({
+        model: cfg.model,
+        language: cfg.language,
+        punctuate: String(cfg.punctuate),
+        interim_results: String(cfg.interimResults),
+        diarize: String(cfg.diarize),
+        encoding: 'linear16',
+        sample_rate: '16000',
+        channels: '1',
+    });
+    if (cfg.keywords && cfg.keywords.length > 0) {
+        for (const kw of cfg.keywords) {
+            params.append('keywords', kw);
+        }
+    }
+    if (cfg.endpointing !== false && cfg.endpointing !== undefined) {
+        params.set('endpointing', String(cfg.endpointing));
+    }
+    return `${DEEPGRAM_WS_BASE}?${params.toString()}`;
+}
+// ---------------------------------------------------------------------------
+// Main class
+// ---------------------------------------------------------------------------
+/**
+ * Active streaming STT session backed by a Deepgram WebSocket connection.
+ *
+ * Construct via {@link DeepgramStreamingSTT.startSession} rather than directly.
+ *
+ * @example
+ * ```ts
+ * const session = new DeepgramStreamSession({ apiKey: process.env.DEEPGRAM_API_KEY! });
+ *
+ * session.on('interim_transcript', (evt) => process.stdout.write(`\r${evt.text}`));
+ * session.on('final_transcript',   (evt) => console.log(`FINAL: ${evt.text}`));
+ * session.on('speech_end',         ()    => console.log('utterance ended'));
+ *
+ * // Push audio frames from a microphone source:
+ * microphone.on('frame', (frame) => session.pushAudio(frame));
+ *
+ * // Signal end of utterance:
+ * await session.flush();
+ * session.close();
+ * ```
+ */
+export class DeepgramStreamSession extends EventEmitter {
+    // -------------------------------------------------------------------------
+    // Private state
+    // -------------------------------------------------------------------------
+    /** Resolved configuration with all defaults applied. */
+    cfg;
+    /** Current WebSocket connection (replaced on reconnect). */
+    ws = null;
+    /** `true` once the first non-empty transcript arrives in this utterance. */
+    speechStarted = false;
+    /** `true` after {@link close} is called — prevents reconnect attempts. */
+    closed = false;
+    /**
+     * Ring buffer of audio frames accumulated while the WebSocket is
+     * reconnecting.  Capped at {@link MAX_BUFFER_FRAMES} to bound memory.
+     */
+    reconnectBuffer = [];
+    /** Current reconnect back-off delay in milliseconds. */
+    backoffMs = BACKOFF_INITIAL_MS;
+    /** Active reconnect timer handle. */
+    reconnectTimer = null;
+    /** `true` while the WebSocket is open and ready to accept binary data. */
+    wsReady = false;
+    // -------------------------------------------------------------------------
+    // Constructor
+    // -------------------------------------------------------------------------
+    /**
+     * @param config - Deepgram streaming configuration.  `apiKey` is required;
+     *                 all other fields have sensible defaults.
+     */
+    constructor(config) {
+        super();
+        // Apply defaults.
+        this.cfg = {
+            model: 'nova-2',
+            language: 'en-US',
+            punctuate: true,
+            interimResults: true,
+            diarize: false,
+            ...config,
+        };
+        this.connect();
+    }
+    // -------------------------------------------------------------------------
+    // StreamingSTTSession interface
+    // -------------------------------------------------------------------------
+    /**
+     * Push a raw PCM audio frame into the recognition stream.
+     *
+     * Converts Float32 samples to Int16 linear PCM and transmits them as binary
+     * over the WebSocket.  Frames received while the socket is reconnecting are
+     * queued in {@link reconnectBuffer} (up to {@link MAX_BUFFER_FRAMES}).
+     *
+     * @param frame - Audio frame with normalised Float32 samples at any sample rate.
+     *                Frames are sent as-is; resample to 16 kHz before calling if
+     *                the source differs from the Deepgram session's `sample_rate`.
+     */
+    pushAudio(frame) {
+        if (this.closed)
+            return;
+        const pcmBuffer = float32ToInt16Buffer(frame.samples);
+        if (this.wsReady && this.ws) {
+            this.ws.send(pcmBuffer);
+        }
+        else {
+            // Buffer frames during reconnect — drop the oldest when full.
+            if (this.reconnectBuffer.length >= MAX_BUFFER_FRAMES) {
+                this.reconnectBuffer.shift();
+            }
+            this.reconnectBuffer.push(frame);
+        }
+    }
+    /**
+     * Signal end-of-utterance to Deepgram.
+     *
+     * Sends the JSON `{"type":"CloseStream"}` control message, instructing
+     * Deepgram to flush any buffered audio and emit a final transcript before
+     * closing the connection from their side.
+     *
+     * @returns A promise that resolves immediately after the message is enqueued.
+     */
+    async flush() {
+        if (this.ws && this.wsReady) {
+            this.ws.send(JSON.stringify({ type: 'CloseStream' }));
+        }
+    }
+    /**
+     * Immediately terminate the session without waiting for a final result.
+     *
+     * Cancels any pending reconnect timer, marks the session as closed, and
+     * terminates the underlying WebSocket.  After `close()` no further events
+     * are emitted.
+     */
+    close() {
+        this.closed = true;
+        if (this.reconnectTimer !== null) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.terminate();
+            this.ws = null;
+        }
+        this.wsReady = false;
+        this.emit('close');
+    }
+    // -------------------------------------------------------------------------
+    // Internal — WebSocket lifecycle
+    // -------------------------------------------------------------------------
+    /**
+     * Open (or reopen) the Deepgram WebSocket connection.
+     *
+     * Attaches `open`, `message`, `error`, and `close` handlers.  On successful
+     * open the reconnect buffer is drained in order.
+     */
+    connect() {
+        if (this.closed)
+            return;
+        const url = buildWsUrl(this.cfg);
+        const socket = new WebSocket(url, {
+            headers: {
+                Authorization: `Token ${this.cfg.apiKey}`,
+            },
+        });
+        this.ws = socket;
+        socket.on('open', () => {
+            this.wsReady = true;
+            this.backoffMs = BACKOFF_INITIAL_MS; // reset on successful connect
+            // Drain buffered frames accumulated during the reconnect window.
+            const buffered = this.reconnectBuffer.splice(0);
+            for (const frame of buffered) {
+                const pcm = float32ToInt16Buffer(frame.samples);
+                socket.send(pcm);
+            }
+        });
+        socket.on('message', (data) => {
+            try {
+                const msg = JSON.parse(data.toString());
+                this.handleMessage(msg);
+            }
+            catch {
+                // Ignore malformed frames — Deepgram occasionally sends keep-alive
+                // empty strings or non-JSON control bytes.
+            }
+        });
+        socket.on('error', (err) => {
+            this.emit('error', err);
+        });
+        socket.on('close', (code) => {
+            this.wsReady = false;
+            this.ws = null;
+            // Normal closure (1000 = Normal, 1001 = Going Away) or explicit close().
+            const isNormal = code === 1000 || code === 1001;
+            if (isNormal || this.closed) {
+                if (!this.closed) {
+                    // Deepgram closed normally after a CloseStream — emit session close.
+                    this.emit('close');
+                }
+                return;
+            }
+            // Unexpected drop — schedule reconnect with exponential back-off.
+            this.scheduleReconnect();
+        });
+    }
+    /**
+     * Schedule a reconnect attempt after the current {@link backoffMs} delay,
+     * then double the delay for the next attempt (capped at {@link BACKOFF_MAX_MS}).
+     */
+    scheduleReconnect() {
+        if (this.closed)
+            return;
+        const delay = this.backoffMs;
+        this.backoffMs = Math.min(this.backoffMs * 2, BACKOFF_MAX_MS);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, delay);
+    }
+    // -------------------------------------------------------------------------
+    // Internal — message parsing
+    // -------------------------------------------------------------------------
+    /**
+     * Process a parsed Deepgram WebSocket message and emit the appropriate events.
+     *
+     * Deepgram sends two primary result types:
+     * - `Results` — transcript hypotheses with `is_final` and `speech_final` flags.
+     * - `Metadata` — session-level metadata (ignored here).
+     *
+     * @param msg - Parsed Deepgram JSON message.
+     */
+    handleMessage(msg) {
+        if (msg.type !== 'Results')
+            return;
+        const alt = msg.channel?.alternatives?.[0];
+        if (!alt)
+            return;
+        const text = alt.transcript ?? '';
+        const confidence = alt.confidence ?? 0;
+        const rawWords = alt.words ?? [];
+        const words = rawWords.map(mapDeepgramWord);
+        // Determine majority speaker when diarization is enabled.
+        const majoritySpeaker = this.cfg.diarize
+            ? extractSpeakerFromWords(rawWords)
+            : undefined;
+        // Suppress empty interim frames — Deepgram emits these as silence padding.
+        if (text.trim() === '' && !msg.is_final)
+            return;
+        // Emit 'speech_start' on the first non-empty transcript in this utterance.
+        if (!this.speechStarted && text.trim() !== '') {
+            this.speechStarted = true;
+            this.emit('speech_start');
+        }
+        const event = {
+            text,
+            confidence,
+            words,
+            isFinal: msg.is_final ?? false,
+            durationMs: msg.duration !== undefined ? Math.round(msg.duration * 1000) : undefined,
+        };
+        // Attach majority speaker to the event as a convenience property.
+        if (majoritySpeaker) {
+            event.speaker = majoritySpeaker;
+        }
+        // Base interface event — always emitted for both interim and final results.
+        this.emit('transcript', event);
+        if (msg.is_final) {
+            this.emit('final_transcript', event);
+            // Reset speech-started tracker for the next utterance.
+            this.speechStarted = false;
+            if (msg.speech_final) {
+                this.emit('speech_end');
+            }
+        }
+        else {
+            this.emit('interim_transcript', event);
+        }
+    }
+}
+//# sourceMappingURL=DeepgramStreamSession.js.map

package/dist/DeepgramStreamSession.js.map

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

package/dist/DeepgramStreamingSTT.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @file DeepgramStreamingSTT.ts
+ * @description {@link IStreamingSTT} factory implementation backed by Deepgram.
+ *
+ * {@link DeepgramStreamingSTT} is a thin factory that creates
+ * {@link DeepgramStreamSession} instances on demand.  It holds no persistent
+ * state other than the API key and a reference count used to implement
+ * {@link isStreaming}.
+ *
+ * @module streaming-stt-deepgram/DeepgramStreamingSTT
+ */
+import { DeepgramStreamSession } from './DeepgramStreamSession.js';
+/** Minimal re-export of the StreamingSTTConfig shape used by this adapter. */
+export interface StreamingSTTConfig {
+    language?: string;
+    interimResults?: boolean;
+    punctuate?: boolean;
+    profanityFilter?: boolean;
+    providerOptions?: Record<string, unknown>;
+}
+/**
+ * {@link IStreamingSTT}-compatible factory for Deepgram streaming sessions.
+ *
+ * Instantiate once per agent and reuse for the lifetime of the voice pipeline.
+ * Each call to {@link startSession} opens an independent WebSocket connection
+ * to Deepgram so that multiple concurrent sessions are supported.
+ *
+ * @example
+ * ```ts
+ * const stt = new DeepgramStreamingSTT(process.env.DEEPGRAM_API_KEY!);
+ * const session = await stt.startSession({ language: 'fr-FR' });
+ *
+ * session.on('final_transcript', (evt) => console.log(evt.text));
+ * microphone.on('frame', (f) => session.pushAudio(f));
+ * ```
+ */
+export declare class DeepgramStreamingSTT {
+    private readonly apiKey;
+    /**
+     * Stable provider identifier used by the voice pipeline to select between
+     * registered STT implementations.
+     */
+    readonly providerId = "deepgram-streaming";
+    /** `true` while at least one session has been created and not yet closed. */
+    get isStreaming(): boolean;
+    /** Count of sessions opened but not yet closed. */
+    private _activeSessions;
+    /**
+     * @param apiKey - Deepgram API key.  Passed through to every session.
+     */
+    constructor(apiKey: string);
+    /**
+     * Open a new streaming recognition session.
+     *
+     * Provider-specific options can be forwarded via `config.providerOptions`
+     * under the following keys:
+     * - `model` — Deepgram model name (default `'nova-2'`).
+     * - `diarize` — Enable speaker diarization (default `false`).
+     * - `keywords` — Custom keyword list (default `[]`).
+     * - `endpointing` — Native endpointing duration ms, or `false`.
+     *
+     * @param config - Generic session config merged with Deepgram defaults.
+     * @returns A ready-to-use {@link DeepgramStreamSession}.
+     */
+    startSession(config?: StreamingSTTConfig): Promise<DeepgramStreamSession>;
+}
+//# sourceMappingURL=DeepgramStreamingSTT.d.ts.map

package/dist/DeepgramStreamingSTT.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeepgramStreamingSTT.d.ts","sourceRoot":"","sources":["../src/DeepgramStreamingSTT.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAGnE,8EAA8E;AAC9E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;GAeG;AACH,qBAAa,oBAAoB;IAkBnB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAjBnC;;;OAGG;IACH,QAAQ,CAAC,UAAU,wBAAwB;IAE3C,6EAA6E;IAC7E,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,mDAAmD;IACnD,OAAO,CAAC,eAAe,CAAK;IAE5B;;OAEG;gBAC0B,MAAM,EAAE,MAAM;IAE3C;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,MAAM,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,qBAAqB,CAAC;CAuBhF"}

package/dist/DeepgramStreamingSTT.js

@@ -0,0 +1,81 @@
+/**
+ * @file DeepgramStreamingSTT.ts
+ * @description {@link IStreamingSTT} factory implementation backed by Deepgram.
+ *
+ * {@link DeepgramStreamingSTT} is a thin factory that creates
+ * {@link DeepgramStreamSession} instances on demand.  It holds no persistent
+ * state other than the API key and a reference count used to implement
+ * {@link isStreaming}.
+ *
+ * @module streaming-stt-deepgram/DeepgramStreamingSTT
+ */
+import { DeepgramStreamSession } from './DeepgramStreamSession.js';
+/**
+ * {@link IStreamingSTT}-compatible factory for Deepgram streaming sessions.
+ *
+ * Instantiate once per agent and reuse for the lifetime of the voice pipeline.
+ * Each call to {@link startSession} opens an independent WebSocket connection
+ * to Deepgram so that multiple concurrent sessions are supported.
+ *
+ * @example
+ * ```ts
+ * const stt = new DeepgramStreamingSTT(process.env.DEEPGRAM_API_KEY!);
+ * const session = await stt.startSession({ language: 'fr-FR' });
+ *
+ * session.on('final_transcript', (evt) => console.log(evt.text));
+ * microphone.on('frame', (f) => session.pushAudio(f));
+ * ```
+ */
+export class DeepgramStreamingSTT {
+    apiKey;
+    /**
+     * Stable provider identifier used by the voice pipeline to select between
+     * registered STT implementations.
+     */
+    providerId = 'deepgram-streaming';
+    /** `true` while at least one session has been created and not yet closed. */
+    get isStreaming() {
+        return this._activeSessions > 0;
+    }
+    /** Count of sessions opened but not yet closed. */
+    _activeSessions = 0;
+    /**
+     * @param apiKey - Deepgram API key.  Passed through to every session.
+     */
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    /**
+     * Open a new streaming recognition session.
+     *
+     * Provider-specific options can be forwarded via `config.providerOptions`
+     * under the following keys:
+     * - `model` — Deepgram model name (default `'nova-2'`).
+     * - `diarize` — Enable speaker diarization (default `false`).
+     * - `keywords` — Custom keyword list (default `[]`).
+     * - `endpointing` — Native endpointing duration ms, or `false`.
+     *
+     * @param config - Generic session config merged with Deepgram defaults.
+     * @returns A ready-to-use {@link DeepgramStreamSession}.
+     */
+    async startSession(config) {
+        const provOpts = (config?.providerOptions ?? {});
+        const sessionConfig = {
+            apiKey: this.apiKey,
+            language: config?.language ?? provOpts.language,
+            punctuate: config?.punctuate ?? provOpts.punctuate,
+            interimResults: config?.interimResults ?? provOpts.interimResults,
+            model: provOpts.model,
+            diarize: provOpts.diarize,
+            keywords: provOpts.keywords,
+            endpointing: provOpts.endpointing,
+        };
+        const session = new DeepgramStreamSession(sessionConfig);
+        this._activeSessions++;
+        session.once('close', () => {
+            this._activeSessions = Math.max(0, this._activeSessions - 1);
+        });
+        return session;
+    }
+}
+//# sourceMappingURL=DeepgramStreamingSTT.js.map

package/dist/DeepgramStreamingSTT.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DeepgramStreamingSTT.js","sourceRoot":"","sources":["../src/DeepgramStreamingSTT.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAYnE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,oBAAoB;IAkBF;IAjB7B;;;OAGG;IACM,UAAU,GAAG,oBAAoB,CAAC;IAE3C,6EAA6E;IAC7E,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC;IAClC,CAAC;IAED,mDAAmD;IAC3C,eAAe,GAAG,CAAC,CAAC;IAE5B;;OAEG;IACH,YAA6B,MAAc;QAAd,WAAM,GAAN,MAAM,CAAQ;IAAG,CAAC;IAE/C;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,YAAY,CAAC,MAA2B;QAC5C,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE,eAAe,IAAI,EAAE,CAAqC,CAAC;QAErF,MAAM,aAAa,GAA4B;YAC7C,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,QAAQ,EAAE,MAAM,EAAE,QAAQ,IAAI,QAAQ,CAAC,QAAQ;YAC/C,SAAS,EAAE,MAAM,EAAE,SAAS,IAAI,QAAQ,CAAC,SAAS;YAClD,cAAc,EAAE,MAAM,EAAE,cAAc,IAAI,QAAQ,CAAC,cAAc;YACjE,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,OAAO,EAAE,QAAQ,CAAC,OAAO;YACzB,QAAQ,EAAE,QAAQ,CAAC,QAAQ;YAC3B,WAAW,EAAE,QAAQ,CAAC,WAAW;SAClC,CAAC;QAEF,MAAM,OAAO,GAAG,IAAI,qBAAqB,CAAC,aAAa,CAAC,CAAC;QAEzD,IAAI,CAAC,eAAe,EAAE,CAAC;QACvB,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,EAAE;YACzB,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,eAAe,GAAG,CAAC,CAAC,CAAC;QAC/D,CAAC,CAAC,CAAC;QAEH,OAAO,OAAO,CAAC;IACjB,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the Deepgram Streaming STT extension pack.
+ *
+ * This module exports the main {@link createDeepgramStreamingSTT} factory
+ * function and the {@link createExtensionPack} bridge function that conforms
+ * to the AgentOS manifest factory convention.
+ *
+ * ### Usage (direct)
+ * ```ts
+ * import { createDeepgramStreamingSTT } from '@framers/agentos-ext-streaming-stt-deepgram';
+ *
+ * const stt = createDeepgramStreamingSTT(process.env.DEEPGRAM_API_KEY!);
+ * const session = await stt.startSession({ language: 'en-US' });
+ * ```
+ *
+ * ### Usage (manifest-driven)
+ * ```json
+ * { "packs": [{ "module": "@framers/agentos-ext-streaming-stt-deepgram" }] }
+ * ```
+ *
+ * @module streaming-stt-deepgram
+ */
+import { DeepgramStreamingSTT } from './DeepgramStreamingSTT.js';
+/** Subset of ExtensionDescriptor required by this pack. */
+interface ExtensionDescriptor {
+    id: string;
+    kind: string;
+    payload: unknown;
+    enableByDefault?: boolean;
+    metadata?: Record<string, unknown>;
+}
+/** Subset of ExtensionPack required by this pack. */
+interface ExtensionPack {
+    id: string;
+    descriptors: ExtensionDescriptor[];
+}
+/** Subset of ExtensionPackContext required by this pack. */
+interface ExtensionPackContext {
+    getSecret?: (id: string) => string | undefined;
+    options?: Record<string, unknown>;
+}
+/**
+ * Create a standalone {@link DeepgramStreamingSTT} instance.
+ *
+ * Use this when composing the provider programmatically outside of the
+ * AgentOS extension system.
+ *
+ * @param apiKey - Deepgram API key.
+ * @returns Configured {@link DeepgramStreamingSTT}.
+ */
+export declare function createDeepgramStreamingSTT(apiKey: string): DeepgramStreamingSTT;
+/**
+ * AgentOS manifest factory function.
+ *
+ * Reads the `DEEPGRAM_API_KEY` secret from the context and returns an
+ * {@link ExtensionPack} containing a single `streaming-stt-provider`
+ * descriptor backed by {@link DeepgramStreamingSTT}.
+ *
+ * @param context - Pack context supplied by the extension manager.
+ * @returns A fully configured {@link ExtensionPack}.
+ */
+export declare function createExtensionPack(context: ExtensionPackContext): ExtensionPack;
+export * from './types.js';
+export { DeepgramStreamingSTT } from './DeepgramStreamingSTT.js';
+export { DeepgramStreamSession } from './DeepgramStreamSession.js';
+export { extractSpeakerFromWords, mapDeepgramWord, } from './DeepgramDiarizationAdapter.js';
+export type { DeepgramWord } from './DeepgramDiarizationAdapter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAOjE,2DAA2D;AAC3D,UAAU,mBAAmB;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,qDAAqD;AACrD,UAAU,aAAa;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,mBAAmB,EAAE,CAAC;CACpC;AAED,4DAA4D;AAC5D,UAAU,oBAAoB;IAC5B,SAAS,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AASD;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,GAAG,oBAAoB,CAE/E;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAgBhF;AAMD,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EACL,uBAAuB,EACvB,eAAe,GAChB,MAAM,iCAAiC,CAAC;AACzC,YAAY,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/index.js

@@ -0,0 +1,75 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the Deepgram Streaming STT extension pack.
+ *
+ * This module exports the main {@link createDeepgramStreamingSTT} factory
+ * function and the {@link createExtensionPack} bridge function that conforms
+ * to the AgentOS manifest factory convention.
+ *
+ * ### Usage (direct)
+ * ```ts
+ * import { createDeepgramStreamingSTT } from '@framers/agentos-ext-streaming-stt-deepgram';
+ *
+ * const stt = createDeepgramStreamingSTT(process.env.DEEPGRAM_API_KEY!);
+ * const session = await stt.startSession({ language: 'en-US' });
+ * ```
+ *
+ * ### Usage (manifest-driven)
+ * ```json
+ * { "packs": [{ "module": "@framers/agentos-ext-streaming-stt-deepgram" }] }
+ * ```
+ *
+ * @module streaming-stt-deepgram
+ */
+import { DeepgramStreamingSTT } from './DeepgramStreamingSTT.js';
+/** Kind constant matching packages/agentos/src/extensions/types.ts line ~410. */
+const EXTENSION_KIND_STREAMING_STT = 'streaming-stt-provider';
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a standalone {@link DeepgramStreamingSTT} instance.
+ *
+ * Use this when composing the provider programmatically outside of the
+ * AgentOS extension system.
+ *
+ * @param apiKey - Deepgram API key.
+ * @returns Configured {@link DeepgramStreamingSTT}.
+ */
+export function createDeepgramStreamingSTT(apiKey) {
+    return new DeepgramStreamingSTT(apiKey);
+}
+/**
+ * AgentOS manifest factory function.
+ *
+ * Reads the `DEEPGRAM_API_KEY` secret from the context and returns an
+ * {@link ExtensionPack} containing a single `streaming-stt-provider`
+ * descriptor backed by {@link DeepgramStreamingSTT}.
+ *
+ * @param context - Pack context supplied by the extension manager.
+ * @returns A fully configured {@link ExtensionPack}.
+ */
+export function createExtensionPack(context) {
+    const apiKey = context.getSecret?.('DEEPGRAM_API_KEY') ?? '';
+    const stt = new DeepgramStreamingSTT(apiKey);
+    return {
+        id: 'streaming-stt-deepgram',
+        descriptors: [
+            {
+                id: 'deepgram-streaming-stt',
+                kind: EXTENSION_KIND_STREAMING_STT,
+                payload: stt,
+                enableByDefault: true,
+                metadata: { providerId: 'deepgram-streaming' },
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// Re-exports
+// ---------------------------------------------------------------------------
+export * from './types.js';
+export { DeepgramStreamingSTT } from './DeepgramStreamingSTT.js';
+export { DeepgramStreamSession } from './DeepgramStreamSession.js';
+export { extractSpeakerFromWords, mapDeepgramWord, } from './DeepgramDiarizationAdapter.js';
+//# sourceMappingURL=index.js.map