@kuralle-syrinx/google 2.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Kuralle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@kuralle-syrinx/google",
+  "version": "2.1.0",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "dependencies": {
+    "ws": "^8.18.0",
+    "@kuralle-syrinx/core": "2.1.0",
+    "@kuralle-syrinx/ws": "2.1.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,273 @@
+// SPDX-License-Identifier: MIT
+
+import { afterEach, describe, expect, it } from "vitest";
+import { WebSocketServer, type WebSocket } from "ws";
+import {
+  PipelineBusImpl,
+  Route,
+  type SttErrorPacket,
+  type SttInterimPacket,
+  type SttResultPacket,
+  type EndOfSpeechPacket,
+} from "@kuralle-syrinx/core";
+import { GoogleSTTPlugin } from "./index.js";
+
+let servers: WebSocketServer[] = [];
+
+afterEach(async () => {
+  await Promise.all(
+    servers.splice(0).map(
+      (server) =>
+        new Promise<void>((resolve) => {
+          for (const client of server.clients) client.terminate();
+          server.close(() => resolve());
+        }),
+    ),
+  );
+});
+
+async function createLocalServer(onConnection: (socket: WebSocket) => void): Promise<string> {
+  const server = await new Promise<WebSocketServer>((resolve) => {
+    let nextServer: WebSocketServer;
+    nextServer = new WebSocketServer({ port: 0 }, () => {
+      resolve(nextServer);
+    });
+  });
+  servers.push(server);
+  server.on("connection", onConnection);
+  const address = server.address();
+  if (!address || typeof address === "string") throw new Error("Expected TCP server address");
+  return `ws://127.0.0.1:${address.port}`;
+}
+
+function startBus(bus: PipelineBusImpl): Promise<void> {
+  const started = bus.start();
+  return started;
+}
+
+describe("GoogleSTTPlugin", () => {
+  it("pushes interim and final packets from Google streaming responses", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.once("message", () => {
+        socket.send(JSON.stringify({
+          results: [{
+            isFinal: false,
+            alternatives: [{ transcript: "hello", confidence: 0.7 }],
+          }],
+        }));
+        socket.send(JSON.stringify({
+          results: [{
+            isFinal: true,
+            alternatives: [{ transcript: "hello world", confidence: 0.95 }],
+          }],
+        }));
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new GoogleSTTPlugin();
+    const interims: SttInterimPacket[] = [];
+    const finals: SttResultPacket[] = [];
+    bus.on("stt.interim", (pkt) => {
+      interims.push(pkt as SttInterimPacket);
+    });
+    bus.on("stt.result", (pkt) => {
+      finals.push(pkt as SttResultPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      project_id: "test-project",
+      endpoint_url: endpointUrl,
+    });
+    bus.push(Route.Main, {
+      kind: "stt.audio",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      audio: new Uint8Array([1, 2, 3, 4]),
+    });
+    await new Promise((resolve) => setTimeout(resolve, 30));
+
+    expect(interims).toEqual([
+      expect.objectContaining({ kind: "stt.interim", contextId: "turn-1", text: "hello" }),
+    ]);
+    expect(finals).toEqual([
+      expect.objectContaining({
+        kind: "stt.result",
+        contextId: "turn-1",
+        text: "hello world",
+        confidence: 0.95,
+        language: "en-US",
+      }),
+    ]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("reconnects after a recoverable socket close before sending later audio", async () => {
+    let connections = 0;
+    const receivedFrames: Array<{ connection: number; kind: "config" | "audio"; payload: unknown }> = [];
+    const endpointUrl = await createLocalServer((socket) => {
+      connections++;
+      const connection = connections;
+      if (connections === 1) {
+        socket.close();
+        return;
+      }
+      socket.on("message", (data, isBinary) => {
+        if (isBinary) {
+          receivedFrames.push({ connection, kind: "audio", payload: Buffer.from(data as Buffer) });
+        } else {
+          receivedFrames.push({ connection, kind: "config", payload: JSON.parse(data.toString()) });
+        }
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new GoogleSTTPlugin();
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      project_id: "test-project",
+      endpoint_url: endpointUrl,
+      retry_base_delay_ms: 1,
+      retry_max_delay_ms: 1,
+    });
+    await new Promise((resolve) => setTimeout(resolve, 30));
+    bus.push(Route.Main, {
+      kind: "stt.audio",
+      contextId: "turn-1",
+      timestampMs: Date.now(),
+      audio: new Uint8Array([9, 8, 7, 6]),
+    });
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    expect(connections).toBeGreaterThanOrEqual(2);
+    expect(receivedFrames).toEqual([
+      expect.objectContaining({ connection: 2, kind: "config" }),
+      expect.objectContaining({ connection: 2, kind: "audio", payload: Buffer.from([9, 8, 7, 6]) }),
+    ]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("uses configured sample_rate in the audio contract and Google decoding config", async () => {
+    const configs: any[] = [];
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data, isBinary) => {
+        if (!isBinary) configs.push(JSON.parse(data.toString()));
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new GoogleSTTPlugin();
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      project_id: "test-project",
+      endpoint_url: endpointUrl,
+      sample_rate: 8000,
+    });
+    await new Promise((resolve) => setTimeout(resolve, 20));
+
+    expect(configs[0]?.streamingConfig?.config?.explicitDecodingConfig?.sampleRateHertz).toBe(8000);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("suppresses EOS when Smart Turn ownership disables provider finalization", async () => {
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.once("message", () => {
+        socket.send(JSON.stringify({
+          results: [{
+            isFinal: true,
+            alternatives: [{ transcript: "hello world", confidence: 0.95 }],
+          }],
+        }));
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new GoogleSTTPlugin();
+    const finals: SttResultPacket[] = [];
+    const eos: EndOfSpeechPacket[] = [];
+    bus.on("stt.result", (pkt) => {
+      finals.push(pkt as SttResultPacket);
+    });
+    bus.on("eos.turn_complete", (pkt) => {
+      eos.push(pkt as EndOfSpeechPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      project_id: "test-project",
+      endpoint_url: endpointUrl,
+      emit_eos_on_final: false,
+    });
+    bus.push(Route.Main, {
+      kind: "stt.audio",
+      contextId: "turn-no-eos",
+      timestampMs: Date.now(),
+      audio: new Uint8Array([1, 2, 3, 4]),
+    });
+    await new Promise((resolve) => setTimeout(resolve, 30));
+
+    expect(finals).toHaveLength(1);
+    expect(eos).toEqual([]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+
+  it("emits stt.error for odd-length PCM16 without throwing into the bus pump", async () => {
+    const receivedAudio: Buffer[] = [];
+    const endpointUrl = await createLocalServer((socket) => {
+      socket.on("message", (data, isBinary) => {
+        if (isBinary) receivedAudio.push(data as Buffer);
+      });
+    });
+    const bus = new PipelineBusImpl();
+    const started = startBus(bus);
+    const plugin = new GoogleSTTPlugin();
+    const errors: SttErrorPacket[] = [];
+    bus.on("stt.error", (pkt) => {
+      errors.push(pkt as SttErrorPacket);
+    });
+
+    await plugin.initialize(bus, {
+      api_key: "test",
+      project_id: "test-project",
+      endpoint_url: endpointUrl,
+    });
+    bus.push(Route.Main, {
+      kind: "stt.audio",
+      contextId: "turn-bad",
+      timestampMs: Date.now(),
+      audio: new Uint8Array([1, 2, 3]),
+    });
+    await new Promise((resolve) => setTimeout(resolve, 30));
+
+    expect(errors).toEqual([
+      expect.objectContaining({
+        kind: "stt.error",
+        contextId: "turn-bad",
+        component: "stt",
+        cause: expect.objectContaining({
+          message: expect.stringMatching(/even number of bytes/i),
+        }),
+      }),
+    ]);
+    expect(receivedAudio).toEqual([]);
+
+    await plugin.close();
+    bus.stop();
+    await started;
+  });
+});

package/src/index.ts

@@ -0,0 +1,249 @@
+// SPDX-License-Identifier: MIT
+//
+// Syrinx Kernel v2 — Google Cloud Speech-to-Text Plugin
+//
+// Uses Google Cloud Speech-to-Text v2 REST API for streaming recognition.
+// Sends audio chunks, receives interim and final transcripts.
+// Pushes SttInterimPacket, SttResultPacket, and SttErrorPacket into the bus.
+//
+// Reference: Rapida transformer/google/stt.go (GCP Speech-to-Text v2 API)
+// Reference: https://cloud.google.com/speech-to-text/v2/docs/streaming-recognize
+//
+// Unlike Deepgram which uses simple API keys, GCP requires:
+//   - API key (for public API) OR
+//   - Service account key (for private/project-scoped API)
+//   - Project ID (required for recognizer path)
+
+import type { PipelineBus } from "@kuralle-syrinx/core";
+import {
+  Route,
+  type AudioFormat,
+  type VoicePlugin,
+  type PluginConfig,
+  type SttErrorPacket,
+  assertAudioFormat,
+  assertAudioPayload,
+  requireStringConfig,
+  optionalStringConfig,
+  categorizeSttError,
+  isRecoverable,
+  readProviderRetryConfig,
+} from "@kuralle-syrinx/core";
+import { WebSocketConnection, type SocketData, type SocketFactory } from "@kuralle-syrinx/ws";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+interface GCPConfig {
+  recognizer: string;
+  encoding: string;
+  sampleRateHertz: number;
+  languageCodes: string[];
+  model: string;
+  enableAutomaticPunctuation: boolean;
+  interimResults: boolean;
+}
+
+// =============================================================================
+// Plugin
+// =============================================================================
+
+export class GoogleSTTPlugin implements VoicePlugin {
+  readonly endpointingCapability = {
+    owner: "provider_stt" as const,
+    disableConfig: {
+      emit_eos_on_final: false,
+    },
+  };
+
+  constructor(private readonly socketFactory?: SocketFactory) {}
+
+  private bus: PipelineBus | null = null;
+  private conn: WebSocketConnection | null = null;
+  private apiKey: string = "";
+  private projectId: string = "";
+  private languageCode: string = "en-US";
+  private model: string = "latest_long";
+  private endpointUrl: string | undefined;
+  private currentContextId = "";
+  private disposers: Array<() => void> = [];
+  private recognizerPath = "";
+  private sampleRate = 16000;
+  private confidenceThreshold = 0;
+  private emitEosOnFinal = true;
+  private audioFormat: AudioFormat = { encoding: "pcm_s16le", sampleRateHz: 16000, channels: 1 };
+
+  async initialize(bus: PipelineBus, config: PluginConfig): Promise<void> {
+    this.bus = bus;
+    this.apiKey = requireStringConfig(config, "api_key");
+    this.projectId = requireStringConfig(config, "project_id");
+    this.languageCode = optionalStringConfig(config, "language") ?? "en-US";
+    this.model = optionalStringConfig(config, "model") ?? "latest_long";
+    this.endpointUrl = optionalStringConfig(config, "endpoint_url");
+    this.sampleRate = (config["sample_rate"] as number) ?? 16000;
+    this.confidenceThreshold = (config["confidence_threshold"] as number) ?? 0;
+    this.emitEosOnFinal = (config["emit_eos_on_final"] as boolean) ?? true;
+
+    this.recognizerPath = `projects/${this.projectId}/locations/global/recognizers/_`;
+    this.audioFormat = { encoding: "pcm_s16le", sampleRateHz: this.sampleRate, channels: 1 };
+    assertAudioFormat(this.audioFormat);
+    this.conn = new WebSocketConnection({
+      url: () => {
+        return this.endpointUrl ??
+          `wss://speech.googleapis.com/v2/${this.recognizerPath}:streamingRecognize?key=${this.apiKey}`;
+      },
+      socketFactory: this.socketFactory ?? await defaultSocketFactory(),
+      retry: readProviderRetryConfig(config),
+      replayBufferSize: (config["replay_buffer_size"] as number) ?? 64,
+      onReplay: (event, count) => {
+        this.pushMetric(this.currentContextId, `stt.google.reconnect_replay_${event}`, String(count));
+      },
+      onReadyBeforeReplay: () => this.sendConfig(),
+      onMessage: (data) => this.handleMessage(data),
+      onConnectionLost: (err) => {
+        this.emitError(err);
+      },
+      onUnrecoverable: (err) => {
+        this.emitError(err);
+      },
+    });
+    await this.conn.connect();
+
+    this.disposers.push(
+      bus.on("stt.audio", async (pkt: unknown) => {
+        const audioPkt = pkt as { audio: Uint8Array; contextId?: string };
+        this.currentContextId = audioPkt.contextId ?? this.currentContextId;
+        await this.sendAudio(audioPkt.audio);
+      }),
+      bus.on("turn.change", (pkt: unknown) => {
+        this.currentContextId = (pkt as { contextId: string }).contextId;
+      }),
+    );
+  }
+
+  async sendAudio(audio: Uint8Array): Promise<void> {
+    if (audio.byteLength === 0) return;
+    try {
+      assertAudioPayload(this.audioFormat, audio);
+      if (!this.conn) throw new Error("Google STT is not connected");
+      await this.conn.ensureReady();
+      this.conn.send(audio);
+    } catch (err) {
+      this.emitError(err instanceof Error ? err : new Error(String(err)));
+    }
+  }
+
+  async close(): Promise<void> {
+    for (const dispose of this.disposers.splice(0)) dispose();
+    await this.conn?.close();
+    this.conn = null;
+    this.bus = null;
+  }
+
+  private sendConfig(): void {
+    const configMsg = {
+      recognizer: this.recognizerPath,
+      streamingConfig: {
+        config: {
+          explicitDecodingConfig: {
+            encoding: "LINEAR16",
+            sampleRateHertz: this.sampleRate,
+            audioChannelCount: 1,
+          },
+          languageCodes: [this.languageCode],
+          model: this.model,
+          features: {
+            enableAutomaticPunctuation: true,
+            enableWordConfidence: true,
+          },
+        },
+        streamingFeatures: {
+          interimResults: true,
+        },
+      },
+    };
+    this.conn?.send(JSON.stringify(configMsg));
+  }
+
+  private handleMessage(data: SocketData): void {
+    if (typeof data !== "string") return;
+    try {
+      const msg = JSON.parse(data);
+      const results = msg.results;
+      if (!Array.isArray(results) || results.length === 0) return;
+
+      for (const result of results) {
+        const alt = result.alternatives?.[0];
+        if (!alt?.transcript) continue;
+
+        const text = String(alt.transcript).trim();
+        if (!text) continue;
+        const confidence = alt.confidence ?? 0;
+
+        if (this.confidenceThreshold > 0 && confidence < this.confidenceThreshold) {
+          this.pushMetric(this.currentContextId, "stt_low_confidence", String(confidence));
+          continue;
+        }
+
+        if (result.isFinal === true) {
+          this.bus?.push(Route.Main, {
+            kind: "stt.result",
+            contextId: this.currentContextId,
+            timestampMs: Date.now(),
+            text,
+            confidence,
+            language: this.languageCode,
+            provider: { name: "google", model: this.model, region: "global" },
+          });
+          if (this.emitEosOnFinal) {
+            this.bus?.push(Route.Main, {
+              kind: "eos.turn_complete",
+              contextId: this.currentContextId,
+              timestampMs: Date.now(),
+              text,
+              transcripts: [],
+            });
+          }
+        } else {
+          this.bus?.push(Route.Main, {
+            kind: "stt.interim",
+            contextId: this.currentContextId,
+            timestampMs: Date.now(),
+            text,
+          });
+        }
+      }
+    } catch {
+      // Provider keepalives or malformed transient messages are ignored.
+    }
+  }
+
+  private emitError(error: Error, category = categorizeSttError(error)): void {
+    const packet: SttErrorPacket = {
+      kind: "stt.error",
+      contextId: this.currentContextId,
+      timestampMs: Date.now(),
+      component: "stt" as const,
+      category,
+      cause: error,
+      isRecoverable: isRecoverable(category),
+    };
+    this.bus?.push(Route.Critical, packet);
+  }
+
+  private pushMetric(contextId: string, name: string, value: string): void {
+    this.bus?.push(Route.Background, {
+      kind: "metric.conversation",
+      contextId,
+      timestampMs: Date.now(),
+      name,
+      value,
+    });
+  }
+}
+
+async function defaultSocketFactory(): Promise<SocketFactory> {
+  const mod = await import("@kuralle-syrinx/ws/node");
+  return mod.createNodeWsSocket;
+}

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitReturns": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}