@acpfx/stt-deepgram 0.2.0 → 0.2.3

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2024-2026 acpfx contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,45 @@
+# @acpfx/stt-deepgram
+
+Speech-to-text via Deepgram streaming API. Streams partial transcriptions in real time with configurable VAD and endpointing.
+
+## Usage
+
+This package is a pipeline node for [@acpfx/cli](../orchestrator/README.md). See the CLI package for installation and usage.
+
+Requires a `DEEPGRAM_API_KEY` environment variable.
+
+## Manifest
+
+- **Consumes:** `audio.chunk`
+- **Emits:** `speech.partial`, `speech.final`, `speech.pause`, `lifecycle.ready`, `lifecycle.done`, `control.error`
+
+## Settings
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `language` | string | `en` | Language code |
+| `model` | string | `nova-3` | Deepgram model name |
+| `utteranceEndMs` | number | `1000` | Silence ms before utterance end |
+| `endpointing` | number | `300` | VAD endpointing threshold in ms |
+| `apiKey` | string | | Overrides `DEEPGRAM_API_KEY` env var |
+
+## Pipeline Example
+
+```yaml
+nodes:
+  stt:
+    use: "@acpfx/stt-deepgram"
+    settings: { language: en, model: nova-3 }
+    outputs: [bridge]
+env:
+  DEEPGRAM_API_KEY: ${DEEPGRAM_API_KEY}
+```
+
+## External Links
+
+- [Deepgram](https://deepgram.com) -- Speech AI platform
+- [Deepgram Developer Docs](https://developers.deepgram.com) -- API reference and guides
+
+## License
+
+ISC

package/dist/index.js

@@ -0,0 +1,287 @@
+// ../node-sdk/src/index.ts
+import { createInterface } from "node:readline";
+
+// ../core/src/config.ts
+import { parse as parseYaml } from "yaml";
+
+// ../core/src/manifest.ts
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { z as z2 } from "zod";
+
+// ../core/src/acpfx-flags.ts
+import { z } from "zod";
+var SetupCheckResponseSchema = z.object({
+  needed: z.boolean(),
+  description: z.string().optional()
+});
+var SetupProgressSchema = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("progress"),
+    message: z.string(),
+    pct: z.number().optional()
+  }),
+  z.object({ type: z.literal("complete"), message: z.string() }),
+  z.object({ type: z.literal("error"), message: z.string() })
+]);
+var UnsupportedFlagResponseSchema = z.object({
+  unsupported: z.boolean(),
+  flag: z.string()
+});
+
+// ../core/src/manifest.ts
+var ArgumentTypeSchema = z2.enum(["string", "number", "boolean"]);
+var ManifestArgumentSchema = z2.object({
+  type: ArgumentTypeSchema,
+  default: z2.unknown().optional(),
+  description: z2.string().optional(),
+  required: z2.boolean().optional(),
+  enum: z2.array(z2.unknown()).optional()
+});
+var ManifestEnvFieldSchema = z2.object({
+  required: z2.boolean().optional(),
+  description: z2.string().optional()
+});
+var NodeManifestSchema = z2.object({
+  name: z2.string(),
+  description: z2.string().optional(),
+  consumes: z2.array(z2.string()),
+  emits: z2.array(z2.string()),
+  arguments: z2.record(z2.string(), ManifestArgumentSchema).optional(),
+  additional_arguments: z2.boolean().optional(),
+  env: z2.record(z2.string(), ManifestEnvFieldSchema).optional()
+});
+function handleAcpfxFlags(manifestPath) {
+  const acpfxFlag = process.argv.find((a) => a.startsWith("--acpfx-"));
+  const legacyManifest = process.argv.includes("--manifest");
+  if (!acpfxFlag && !legacyManifest) return;
+  const flag = acpfxFlag ?? "--acpfx-manifest";
+  switch (flag) {
+    case "--acpfx-manifest":
+      printManifest(manifestPath);
+      break;
+    case "--acpfx-setup-check":
+      process.stdout.write(JSON.stringify({ needed: false }) + "\n");
+      process.exit(0);
+      break;
+    default:
+      process.stdout.write(
+        JSON.stringify({ unsupported: true, flag }) + "\n"
+      );
+      process.exit(0);
+  }
+}
+function handleManifestFlag(manifestPath) {
+  handleAcpfxFlags(manifestPath);
+}
+function printManifest(manifestPath) {
+  if (!manifestPath) {
+    const script = process.argv[1];
+    const scriptDir = dirname(script);
+    const scriptBase = script.replace(/\.[^.]+$/, "");
+    const colocated = `${scriptBase}.manifest.json`;
+    try {
+      readFileSync(colocated);
+      manifestPath = colocated;
+    } catch {
+      manifestPath = join(scriptDir, "manifest.json");
+    }
+  }
+  try {
+    const content = readFileSync(manifestPath, "utf8");
+    process.stdout.write(content.trim() + "\n");
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`Failed to read manifest: ${err}
+`);
+    process.exit(1);
+  }
+}
+
+// ../node-sdk/src/index.ts
+var NODE_NAME = process.env.ACPFX_NODE_NAME ?? "unknown";
+function emit(event) {
+  process.stdout.write(JSON.stringify(event) + "\n");
+}
+function log(level, message) {
+  emit({ type: "log", level, component: NODE_NAME, message });
+}
+log.info = (message) => log("info", message);
+log.warn = (message) => log("warn", message);
+log.error = (message) => log("error", message);
+log.debug = (message) => log("debug", message);
+function onEvent(handler) {
+  const rl = createInterface({ input: process.stdin });
+  rl.on("line", (line) => {
+    if (!line.trim()) return;
+    try {
+      const event = JSON.parse(line);
+      handler(event);
+    } catch {
+    }
+  });
+  return rl;
+}
+
+// src/index.ts
+handleManifestFlag();
+var WS_URL = "wss://api.deepgram.com/v1/listen";
+var settings = JSON.parse(process.env.ACPFX_SETTINGS || "{}");
+var API_KEY = settings.apiKey ?? process.env.DEEPGRAM_API_KEY ?? "";
+var LANGUAGE = settings.language ?? "en";
+var MODEL = settings.model ?? "nova-3";
+var UTTERANCE_END_MS = settings.utteranceEndMs ?? 1e3;
+var ENDPOINTING = settings.endpointing ?? 300;
+var TRACK_ID = "stt";
+if (!API_KEY) {
+  log.error("No API key. Set DEEPGRAM_API_KEY or settings.apiKey");
+  process.exit(1);
+}
+var ws = null;
+var connected = false;
+var lastFinalText = "";
+var pendingText = "";
+async function connectWebSocket() {
+  const url = `${WS_URL}?model=${MODEL}&language=${encodeURIComponent(LANGUAGE)}&encoding=linear16&sample_rate=16000&channels=1&interim_results=true&punctuate=true&smart_format=true&utterance_end_ms=${UTTERANCE_END_MS}&endpointing=${ENDPOINTING}&vad_events=true`;
+  ws = new WebSocket(url, ["token", API_KEY]);
+  await new Promise((resolve, reject) => {
+    ws.addEventListener(
+      "open",
+      () => {
+        connected = true;
+        log.info("Connected to Deepgram STT");
+        resolve();
+      },
+      { once: true }
+    );
+    ws.addEventListener(
+      "error",
+      () => {
+        reject(new Error("WebSocket connection failed"));
+      },
+      { once: true }
+    );
+  });
+  ws.addEventListener("message", (event) => {
+    try {
+      const data = typeof event.data === "string" ? event.data : Buffer.from(event.data).toString("utf-8");
+      const msg = JSON.parse(data);
+      handleServerMessage(msg);
+    } catch {
+    }
+  });
+  ws.addEventListener("error", (event) => {
+    log.error(`WebSocket error: ${event.message ?? "unknown"}`);
+    emit({
+      type: "control.error",
+      component: "stt-deepgram",
+      message: "STT WebSocket error",
+      fatal: false
+    });
+  });
+  ws.addEventListener("close", (event) => {
+    log.info(`WebSocket closed (code=${event.code})`);
+    connected = false;
+  });
+}
+function handleServerMessage(msg) {
+  const type = msg.type;
+  if (type === "UtteranceEnd") {
+    if (pendingText) {
+      emit({
+        type: "speech.pause",
+        trackId: TRACK_ID,
+        pendingText,
+        silenceMs: UTTERANCE_END_MS
+      });
+      pendingText = "";
+    }
+    return;
+  }
+  if (type === "SpeechStarted") {
+    return;
+  }
+  if (type === "Results") {
+    const channel = msg.channel;
+    const alternatives = channel?.alternatives ?? [];
+    if (alternatives.length === 0) return;
+    const transcript = alternatives[0].transcript ?? "";
+    const isFinal = msg.is_final === true;
+    const speechFinal = msg.speech_final === true;
+    if (!transcript) return;
+    if (isFinal) {
+      lastFinalText = transcript;
+      pendingText = pendingText ? pendingText + " " + transcript : transcript;
+      emit({
+        type: "speech.final",
+        trackId: TRACK_ID,
+        text: transcript,
+        confidence: alternatives[0].confidence ?? void 0
+      });
+      if (speechFinal) {
+        emit({
+          type: "speech.pause",
+          trackId: TRACK_ID,
+          pendingText,
+          silenceMs: ENDPOINTING
+        });
+        pendingText = "";
+      }
+    } else {
+      emit({
+        type: "speech.partial",
+        trackId: TRACK_ID,
+        text: transcript
+      });
+    }
+  }
+}
+function sendAudio(base64Pcm) {
+  if (!ws || !connected) return;
+  const pcm = Buffer.from(base64Pcm, "base64");
+  try {
+    ws.send(pcm);
+  } catch {
+  }
+}
+function closeWebSocket() {
+  connected = false;
+  if (ws) {
+    try {
+      ws.send(JSON.stringify({ type: "CloseStream" }));
+      ws.close();
+    } catch {
+    }
+    ws = null;
+  }
+}
+async function main() {
+  await connectWebSocket();
+  emit({ type: "lifecycle.ready", component: "stt-deepgram" });
+  const rl = onEvent((event) => {
+    if (event.type === "audio.chunk") {
+      if (!connected) {
+        connectWebSocket().then(() => {
+          sendAudio(event.data);
+        }).catch(() => {
+        });
+      } else {
+        sendAudio(event.data);
+      }
+    } else if (event.type === "control.interrupt") {
+    }
+  });
+  rl.on("close", () => {
+    closeWebSocket();
+    emit({ type: "lifecycle.done", component: "stt-deepgram" });
+    process.exit(0);
+  });
+  process.on("SIGTERM", () => {
+    closeWebSocket();
+    process.exit(0);
+  });
+}
+main().catch((err) => {
+  log.error(`Fatal: ${err.message}`);
+  process.exit(1);
+});

package/dist/manifest.json

@@ -0,0 +1 @@
+{"name":"stt-deepgram","description":"Speech-to-text via Deepgram streaming API","consumes":["audio.chunk"],"emits":["speech.partial","speech.final","speech.pause","lifecycle.ready","lifecycle.done","control.error"],"arguments":{"language":{"type":"string","default":"en","description":"Language code for transcription"},"model":{"type":"string","default":"nova-3","description":"Deepgram model name"},"utteranceEndMs":{"type":"number","default":1000,"description":"Milliseconds of silence before utterance end"},"endpointing":{"type":"number","default":300,"description":"VAD endpointing threshold in ms"},"apiKey":{"type":"string","description":"Deepgram API key (overrides DEEPGRAM_API_KEY env var)"}},"env":{"DEEPGRAM_API_KEY":{"required":true,"description":"Deepgram API key for STT"}}}

package/manifest.yaml

@@ -9,3 +9,27 @@ emits:
   - lifecycle.ready
   - lifecycle.done
   - control.error
+arguments:
+  language:
+    type: string
+    default: "en"
+    description: "Language code for transcription"
+  model:
+    type: string
+    default: "nova-3"
+    description: "Deepgram model name"
+  utteranceEndMs:
+    type: number
+    default: 1000
+    description: "Milliseconds of silence before utterance end"
+  endpointing:
+    type: number
+    default: 300
+    description: "VAD endpointing threshold in ms"
+  apiKey:
+    type: string
+    description: "Deepgram API key (overrides DEEPGRAM_API_KEY env var)"
+env:
+  DEEPGRAM_API_KEY:
+    required: true
+    description: "Deepgram API key for STT"

package/package.json

@@ -1,16 +1,20 @@
 {
   "name": "@acpfx/stt-deepgram",
-  "version": "0.2.0",
+  "version": "0.2.3",
   "type": "module",
   "bin": {
     "acpfx-stt-deepgram": "./dist/index.js"
   },
   "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "manifest.yaml"
+  ],
   "dependencies": {
-    "@acpfx/core": "0.2.0",
-    "@acpfx/node-sdk": "0.2.0"
+    "@acpfx/core": "0.4.0",
+    "@acpfx/node-sdk": "0.3.0"
   },
   "scripts": {
-    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --packages=external"
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/index.js --packages=external && node ../../scripts/copy-manifest.js"
   }
 }

package/CHANGELOG.md

@@ -1,21 +0,0 @@
-# @acpfx/stt-deepgram
-
-## 0.2.0
-
-### Minor Changes
-
-- d757640: Initial release: type-safe contracts, Rust orchestrator, manifest-driven event filtering
-
-  - Rust schema crate as canonical event type source of truth with codegen to TypeScript + Zod
-  - Node manifests (manifest.yaml) declaring consumes/emits contracts
-  - Orchestrator event filtering: nodes only receive declared events
-  - Rust orchestrator with ratatui TUI (--ui flag)
-  - node-sdk with structured logging helpers
-  - CI/CD with GitHub Actions and changesets
-  - Platform-specific npm packages for Rust binaries (esbuild-style distribution)
-
-### Patch Changes
-
-- Updated dependencies [d757640]
-  - @acpfx/core@0.2.0
-  - @acpfx/node-sdk@0.2.0

package/src/index.ts

@@ -1,244 +0,0 @@
-/**
- * stt-deepgram node — Deepgram Nova-3 Realtime STT with UtteranceEnd detection.
- *
- * Reads audio.chunk events from stdin, streams to Deepgram WebSocket,
- * emits speech.partial, speech.final, and speech.pause events.
- *
- * Uses UtteranceEnd for end-of-turn detection — analyzes word timing gaps,
- * ignores non-speech audio (won't false-trigger on SFX sounds).
- *
- * Settings (via ACPFX_SETTINGS):
- *   language?: string           — language code (default: "en")
- *   apiKey?: string             — Deepgram API key (falls back to DEEPGRAM_API_KEY env)
- *   model?: string              — STT model (default: "nova-3")
- *   utteranceEndMs?: number     — ms gap for utterance end (default: 1000)
- *   endpointing?: number        — VAD endpointing ms (default: 300)
- */
-
-import { emit, log, onEvent, handleManifestFlag } from "@acpfx/node-sdk";
-
-handleManifestFlag();
-
-const WS_URL = "wss://api.deepgram.com/v1/listen";
-
-type Settings = {
-  language?: string;
-  apiKey?: string;
-  model?: string;
-  utteranceEndMs?: number;
-  endpointing?: number;
-};
-
-const settings: Settings = JSON.parse(process.env.ACPFX_SETTINGS || "{}");
-const API_KEY = settings.apiKey ?? process.env.DEEPGRAM_API_KEY ?? "";
-const LANGUAGE = settings.language ?? "en";
-const MODEL = settings.model ?? "nova-3";
-const UTTERANCE_END_MS = settings.utteranceEndMs ?? 1000;
-const ENDPOINTING = settings.endpointing ?? 300;
-const TRACK_ID = "stt";
-
-if (!API_KEY) {
-  log.error("No API key. Set DEEPGRAM_API_KEY or settings.apiKey");
-  process.exit(1);
-}
-
-let ws: WebSocket | null = null;
-let connected = false;
-let lastFinalText = "";
-let pendingText = "";
-
-
-async function connectWebSocket(): Promise<void> {
-  const url =
-    `${WS_URL}?model=${MODEL}` +
-    `&language=${encodeURIComponent(LANGUAGE)}` +
-    `&encoding=linear16` +
-    `&sample_rate=16000` +
-    `&channels=1` +
-    `&interim_results=true` +
-    `&punctuate=true` +
-    `&smart_format=true` +
-    `&utterance_end_ms=${UTTERANCE_END_MS}` +
-    `&endpointing=${ENDPOINTING}` +
-    `&vad_events=true`;
-
-  ws = new WebSocket(url, ["token", API_KEY]);
-
-  await new Promise<void>((resolve, reject) => {
-    ws!.addEventListener(
-      "open",
-      () => {
-        connected = true;
-        log.info("Connected to Deepgram STT");
-        resolve();
-      },
-      { once: true },
-    );
-
-    ws!.addEventListener(
-      "error",
-      () => {
-        reject(new Error("WebSocket connection failed"));
-      },
-      { once: true },
-    );
-  });
-
-  ws.addEventListener("message", (event: MessageEvent) => {
-    try {
-      const data =
-        typeof event.data === "string"
-          ? event.data
-          : Buffer.from(event.data as ArrayBuffer).toString("utf-8");
-      const msg = JSON.parse(data);
-      handleServerMessage(msg);
-    } catch {
-      // ignore parse errors
-    }
-  });
-
-  ws.addEventListener("error", (event: Event) => {
-    log.error(`WebSocket error: ${(event as ErrorEvent).message ?? "unknown"}`);
-    emit({
-      type: "control.error",
-      component: "stt-deepgram",
-      message: "STT WebSocket error",
-      fatal: false,
-    });
-  });
-
-  ws.addEventListener("close", (event: CloseEvent) => {
-    log.info(`WebSocket closed (code=${event.code})`);
-    connected = false;
-  });
-}
-
-function handleServerMessage(msg: Record<string, unknown>): void {
-  const type = msg.type as string | undefined;
-
-  // UtteranceEnd — speaker finished their turn (word-timing based, ignores noise)
-  if (type === "UtteranceEnd") {
-    if (pendingText) {
-      emit({
-        type: "speech.pause",
-        trackId: TRACK_ID,
-        pendingText,
-        silenceMs: UTTERANCE_END_MS,
-      });
-      pendingText = "";
-    }
-    return;
-  }
-
-  // SpeechStarted — VAD detected speech beginning
-  if (type === "SpeechStarted") {
-    return;
-  }
-
-  // Transcription result
-  if (type === "Results") {
-    const channel = msg.channel as Record<string, unknown> | undefined;
-    const alternatives = (channel?.alternatives as Array<Record<string, unknown>>) ?? [];
-    if (alternatives.length === 0) return;
-
-    const transcript = (alternatives[0].transcript as string) ?? "";
-    const isFinal = msg.is_final === true;
-    const speechFinal = msg.speech_final === true;
-
-    if (!transcript) return;
-
-    if (isFinal) {
-      // Clear stale partial timer — proper final arrived
-      // Final transcript for this segment
-      lastFinalText = transcript;
-      pendingText = transcript;
-
-      emit({
-        type: "speech.final",
-        trackId: TRACK_ID,
-        text: transcript,
-        confidence: (alternatives[0].confidence as number) ?? undefined,
-      });
-
-      // If speech_final (endpointing detected silence), also emit pause
-      if (speechFinal) {
-        emit({
-          type: "speech.pause",
-          trackId: TRACK_ID,
-          pendingText: transcript,
-          silenceMs: ENDPOINTING,
-        });
-        pendingText = "";
-      }
-    } else {
-      // Interim result — partial transcript
-      emit({
-        type: "speech.partial",
-        trackId: TRACK_ID,
-        text: transcript,
-      });
-    }
-  }
-}
-
-function sendAudio(base64Pcm: string): void {
-  if (!ws || !connected) return;
-  const pcm = Buffer.from(base64Pcm, "base64");
-  try {
-    ws.send(pcm);
-  } catch {
-    // WebSocket may have closed
-  }
-}
-
-function closeWebSocket(): void {
-  connected = false;
-  if (ws) {
-    try {
-      // Send close message per Deepgram protocol
-      ws.send(JSON.stringify({ type: "CloseStream" }));
-      ws.close();
-    } catch {
-      // ignore
-    }
-    ws = null;
-  }
-}
-
-// --- Main ---
-
-async function main(): Promise<void> {
-  await connectWebSocket();
-
-  emit({ type: "lifecycle.ready", component: "stt-deepgram" });
-
-  const rl = onEvent((event) => {
-    if (event.type === "audio.chunk") {
-      if (!connected) {
-        connectWebSocket().then(() => {
-          sendAudio(event.data as string);
-        }).catch(() => {});
-      } else {
-        sendAudio(event.data as string);
-      }
-    } else if (event.type === "control.interrupt") {
-      // Don't close WebSocket — STT should keep listening for barge-in.
-    }
-  });
-
-  rl.on("close", () => {
-    closeWebSocket();
-    emit({ type: "lifecycle.done", component: "stt-deepgram" });
-    process.exit(0);
-  });
-
-  process.on("SIGTERM", () => {
-    closeWebSocket();
-    process.exit(0);
-  });
-}
-
-main().catch((err) => {
-  log.error(`Fatal: ${err.message}`);
-  process.exit(1);
-});