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

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AA4BjE,iFAAiF;AACjF,MAAM,4BAA4B,GAAG,wBAAwB,CAAC;AAE9D,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CAAC,MAAc;IACvD,OAAO,IAAI,oBAAoB,CAAC,MAAM,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAA6B;IAC/D,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,kBAAkB,CAAC,IAAI,EAAE,CAAC;IAC7D,MAAM,GAAG,GAAG,IAAI,oBAAoB,CAAC,MAAM,CAAC,CAAC;IAE7C,OAAO;QACL,EAAE,EAAE,wBAAwB;QAC5B,WAAW,EAAE;YACX;gBACE,EAAE,EAAE,wBAAwB;gBAC5B,IAAI,EAAE,4BAA4B;gBAClC,OAAO,EAAE,GAAG;gBACZ,eAAe,EAAE,IAAI;gBACrB,QAAQ,EAAE,EAAE,UAAU,EAAE,oBAAoB,EAAE;aAC/C;SACF;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E,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"}

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @file types.ts
+ * @description Deepgram-specific configuration types for the streaming STT extension pack.
+ *
+ * These types augment the generic {@link StreamingSTTConfig} with Deepgram WebSocket
+ * API options that have no counterpart in the core voice pipeline interface.
+ *
+ * @module streaming-stt-deepgram/types
+ */
+/**
+ * Deepgram-specific configuration for the streaming STT session.
+ *
+ * All fields are optional — sensible defaults are applied when omitted.
+ * The `apiKey` field is required and must be a valid Deepgram API key.
+ */
+export interface DeepgramStreamingConfig {
+    /**
+     * Deepgram API key.  Must be set to a non-empty string; the pack reads this
+     * from the `DEEPGRAM_API_KEY` secret when constructed via {@link createExtensionPack}.
+     */
+    apiKey: string;
+    /**
+     * Deepgram model name.
+     * @defaultValue 'nova-2'
+     * @see {@link https://developers.deepgram.com/docs/models}
+     */
+    model?: string;
+    /**
+     * BCP-47 language code for recognition (e.g. `'en-US'`, `'fr-FR'`).
+     * @defaultValue 'en-US'
+     */
+    language?: string;
+    /**
+     * Whether to insert punctuation into the transcript.
+     * @defaultValue true
+     */
+    punctuate?: boolean;
+    /**
+     * Whether to emit interim (non-final) transcript events.
+     * @defaultValue true
+     */
+    interimResults?: boolean;
+    /**
+     * Whether to enable speaker diarization (speaker turn segmentation).
+     * When `true`, each {@link TranscriptWord} in the result carries a `speaker`
+     * label populated by {@link extractSpeakerFromWords}.
+     * @defaultValue false
+     */
+    diarize?: boolean;
+    /**
+     * Custom keyword boosting list.  Deepgram will upweight these terms during
+     * recognition.  Format: `['keyword:boost']` where boost is an optional float.
+     * @see {@link https://developers.deepgram.com/docs/keywords}
+     */
+    keywords?: string[];
+    /**
+     * Deepgram native endpointing duration in milliseconds.
+     * Set to `false` to disable provider-side endpointing (the voice pipeline's
+     * {@link IEndpointDetector} is then solely responsible for utterance segmentation).
+     * @defaultValue false
+     */
+    endpointing?: number | false;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IAEzB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IAEpB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;CAC9B"}

package/dist/types.js

@@ -0,0 +1,11 @@
+/**
+ * @file types.ts
+ * @description Deepgram-specific configuration types for the streaming STT extension pack.
+ *
+ * These types augment the generic {@link StreamingSTTConfig} with Deepgram WebSocket
+ * API options that have no counterpart in the core voice pipeline interface.
+ *
+ * @module streaming-stt-deepgram/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/manifest.json

@@ -0,0 +1,8 @@
+{
+  "name": "@framers/agentos-ext-streaming-stt-deepgram",
+  "version": "0.1.0",
+  "description": "Real-time streaming STT via Deepgram WebSocket API",
+  "kind": "streaming-stt-provider",
+  "extensionId": "streaming-stt-deepgram",
+  "entryPoint": "./dist/index.js"
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@framers/agentos-ext-streaming-stt-deepgram",
+  "version": "0.2.0",
+  "description": "Real-time streaming STT via Deepgram WebSocket API for AgentOS voice pipeline",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "SKILL.md",
+    "manifest.json"
+  ],
+  "peerDependencies": {
+    "@framers/agentos": "^0.1.0"
+  },
+  "dependencies": {
+    "ws": "^8.17.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0",
+    "vitest": "^1.6.0",
+    "@types/ws": "^8.5.0",
+    "@framers/agentos": "0.1.94"
+  },
+  "license": "MIT",
+  "author": "Frame.dev",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/framersai/agentos-extensions.git",
+    "directory": "registry/curated/voice/streaming-stt-deepgram"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}

package/src/DeepgramDiarizationAdapter.ts

@@ -0,0 +1,113 @@
+/**
+ * @file DeepgramDiarizationAdapter.ts
+ * @description Utilities for extracting speaker labels from Deepgram word-level
+ * diarization results.
+ *
+ * Deepgram's `diarize: true` option annotates each word in the transcript with
+ * a zero-indexed integer `speaker` field.  This module converts that raw
+ * numeric label into the string format expected by {@link TranscriptWord.speaker}
+ * (`'Speaker_0'`, `'Speaker_1'`, …) and determines the majority speaker for
+ * an utterance.
+ *
+ * @module streaming-stt-deepgram/DeepgramDiarizationAdapter
+ */
+
+/**
+ * A single Deepgram word object as returned by the WebSocket API when
+ * `diarize: true` is passed in the connection query string.
+ *
+ * Only the fields used by this adapter are declared; the raw JSON may contain
+ * additional fields that are ignored.
+ */
+export interface DeepgramWord {
+  /** Recognised word token. */
+  word: string;
+  /** Start time relative to the stream start in seconds. */
+  start: number;
+  /** End time relative to the stream start in seconds. */
+  end: number;
+  /** Recognition confidence in [0, 1]. */
+  confidence: number;
+  /**
+   * Zero-indexed speaker index assigned by Deepgram's diarization model.
+   * Present only when the session was opened with `diarize=true`.
+   */
+  speaker?: number;
+  /** Punctuated variant of {@link word} when `punctuate=true`. */
+  punctuated_word?: string;
+}
+
+/**
+ * Extract the majority speaker label from an array of Deepgram word objects.
+ *
+ * The function tallies votes by `speaker` index and returns the label for the
+ * speaker with the most words.  Ties are broken by lowest index (i.e. the
+ * earliest-assigned speaker wins).
+ *
+ * Returns `undefined` when the array is empty or no word carries a `speaker`
+ * field (i.e. diarization was not requested for this session).
+ *
+ * @param words - Raw Deepgram word objects from `channel.alternatives[0].words`.
+ * @returns A string label such as `'Speaker_0'`, or `undefined`.
+ *
+ * @example
+ * ```ts
+ * const words = [
+ *   { word: 'Hello', speaker: 0, start: 0, end: 0.3, confidence: 0.99 },
+ *   { word: 'world', speaker: 1, start: 0.4, end: 0.7, confidence: 0.97 },
+ *   { word: 'today', speaker: 0, start: 0.8, end: 1.1, confidence: 0.95 },
+ * ];
+ * extractSpeakerFromWords(words); // → 'Speaker_0'
+ * ```
+ */
+export function extractSpeakerFromWords(words: DeepgramWord[]): string | undefined {
+  if (words.length === 0) return undefined;
+
+  /** Vote counts keyed by speaker index. */
+  const votes = new Map<number, number>();
+
+  for (const w of words) {
+    if (w.speaker === undefined) continue;
+    votes.set(w.speaker, (votes.get(w.speaker) ?? 0) + 1);
+  }
+
+  if (votes.size === 0) return undefined;
+
+  // Find the speaker index with the highest vote count; ties broken by lowest index.
+  let majorityIndex = -1;
+  let majorityCount = -1;
+
+  for (const [index, count] of votes) {
+    if (count > majorityCount || (count === majorityCount && index < majorityIndex)) {
+      majorityCount = count;
+      majorityIndex = index;
+    }
+  }
+
+  return majorityIndex >= 0 ? `Speaker_${majorityIndex}` : undefined;
+}
+
+/**
+ * Map a Deepgram word object to the canonical `TranscriptWord`-compatible shape.
+ *
+ * Seconds are converted to milliseconds to match the voice pipeline convention.
+ * The `word` field prefers the punctuated variant when available.
+ *
+ * @param dw - Raw Deepgram word object.
+ * @returns A plain object matching the {@link TranscriptWord} interface.
+ */
+export function mapDeepgramWord(dw: DeepgramWord): {
+  word: string;
+  start: number;
+  end: number;
+  confidence: number;
+  speaker?: string;
+} {
+  return {
+    word: dw.punctuated_word ?? dw.word,
+    start: Math.round(dw.start * 1000),
+    end: Math.round(dw.end * 1000),
+    confidence: dw.confidence,
+    speaker: dw.speaker !== undefined ? `Speaker_${dw.speaker}` : undefined,
+  };
+}