@framers/agentos-ext-google-cloud-stt 0.2.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2025 Framers
+
+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/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: google-cloud-stt
+description: Batch speech-to-text via Google Cloud Speech-to-Text API
+category: voice
+---
+
+# Google Cloud STT
+
+Batch speech-to-text recognition using Google Cloud Speech-to-Text V1 API.
+
+## Setup
+
+Provide credentials via the `GOOGLE_CLOUD_STT_CREDENTIALS` secret. Accepts either:
+- An absolute path to a service-account JSON key file (contains `/` or `\`)
+- A raw JSON string with the service-account credentials
+
+## Features
+
+- LINEAR16 PCM audio transcription
+- Configurable language code (BCP-47)
+- Confidence scores and word-level alternatives
+- Maps to standard `SpeechTranscriptionResult` shape
+
+## Configuration
+
+In `agent.config.json`:
+
+```json
+{
+  "voice": {
+    "stt": "google-cloud-stt"
+  }
+}
+```
+
+Provider-specific options via `providerOptions`:
+
+```json
+{
+  "voice": {
+    "stt": "google-cloud-stt",
+    "providerOptions": {
+      "language": "fr-FR"
+    }
+  }
+}
+```

package/dist/GoogleCloudSTTProvider.d.ts

@@ -0,0 +1,84 @@
+/**
+ * @file GoogleCloudSTTProvider.ts
+ * @description Batch speech-to-text provider backed by Google Cloud Speech-to-Text V1 API.
+ *
+ * Credentials are resolved from the constructor argument:
+ * - If the string contains `/` or `\`, it is treated as a path to a service-account JSON key file
+ *   and passed to the client as `keyFilename`.
+ * - Otherwise the string is parsed as a JSON object and passed as `credentials`.
+ *
+ * @module google-cloud-stt
+ */
+/**
+ * A single recognised audio segment returned by the provider.
+ *
+ * Mirrors the generic `SpeechTranscriptionResult` shape used across the
+ * AgentOS voice pipeline.
+ */
+export interface SpeechTranscriptionResult {
+    /** The recognised text. */
+    transcript: string;
+    /** Confidence score in [0, 1]. */
+    confidence: number;
+    /** Whether this is a final (non-speculative) result. Always `true` for batch. */
+    isFinal: boolean;
+}
+/**
+ * Per-call transcription options forwarded to the Google Cloud API.
+ */
+export interface GoogleCloudSTTOptions {
+    /** BCP-47 language code (e.g. `'en-US'`, `'fr-FR'`). @defaultValue `'en-US'` */
+    language?: string;
+}
+/**
+ * Audio frame passed to {@link GoogleCloudSTTProvider.transcribe}.
+ */
+export interface AudioData {
+    /** Raw PCM bytes (LINEAR16). */
+    data: Buffer;
+    /** Sample rate in Hz. @defaultValue `16000` */
+    sampleRate?: number;
+}
+/**
+ * Google Cloud Speech-to-Text batch provider.
+ *
+ * Implements the `SpeechToTextProvider` contract expected by the AgentOS
+ * voice pipeline without taking a hard runtime dependency on the interface
+ * types (to avoid circular imports when loaded as an extension pack).
+ */
+export declare class GoogleCloudSTTProvider {
+    /** Stable provider identifier used by the AgentOS extension registry. */
+    readonly id = "google-cloud-stt";
+    /** Lazily initialised Speech client. */
+    private _client;
+    /** Resolved client constructor options (set in constructor, used in {@link _getClient}). */
+    private readonly _clientOptions;
+    /**
+     * Create a new {@link GoogleCloudSTTProvider}.
+     *
+     * @param credentials - Either an absolute path to a service-account JSON key
+     *   file (any string that contains `/` or `\`) or a JSON string containing
+     *   the service-account credentials object.
+     */
+    constructor(credentials: string);
+    /**
+     * Return (and lazily create) the Google Cloud {@link SpeechClient}.
+     *
+     * Using a lazy initialisation pattern keeps the constructor synchronous and
+     * allows unit tests to inject the mock before the first `transcribe()` call.
+     */
+    private _getClient;
+    /**
+     * Transcribe a batch audio buffer using Google Cloud Speech-to-Text.
+     *
+     * The audio must be encoded as LINEAR16 (raw PCM, 16-bit little-endian).
+     * The method returns all recognised alternatives from the first result, each
+     * mapped to a {@link SpeechTranscriptionResult}.
+     *
+     * @param audio   - Audio frame containing the raw PCM bytes and sample rate.
+     * @param options - Optional per-call parameters (language code).
+     * @returns Array of transcription results ordered by confidence (descending).
+     */
+    transcribe(audio: AudioData, options?: GoogleCloudSTTOptions): Promise<SpeechTranscriptionResult[]>;
+}
+//# sourceMappingURL=GoogleCloudSTTProvider.d.ts.map

package/dist/GoogleCloudSTTProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GoogleCloudSTTProvider.d.ts","sourceRoot":"","sources":["../src/GoogleCloudSTTProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH;;;;;GAKG;AACH,MAAM,WAAW,yBAAyB;IACxC,2BAA2B;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,gFAAgF;IAChF,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,qBAAa,sBAAsB;IACjC,yEAAyE;IACzE,QAAQ,CAAC,EAAE,sBAAsB;IAEjC,wCAAwC;IACxC,OAAO,CAAC,OAAO,CAA6B;IAE5C,4FAA4F;IAC5F,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0B;IAEzD;;;;;;OAMG;gBACS,WAAW,EAAE,MAAM;IAc/B;;;;;OAKG;YACW,UAAU;IAaxB;;;;;;;;;;OAUG;IACG,UAAU,CACd,KAAK,EAAE,SAAS,EAChB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,yBAAyB,EAAE,CAAC;CA2BxC"}

package/dist/GoogleCloudSTTProvider.js

@@ -0,0 +1,98 @@
+/**
+ * @file GoogleCloudSTTProvider.ts
+ * @description Batch speech-to-text provider backed by Google Cloud Speech-to-Text V1 API.
+ *
+ * Credentials are resolved from the constructor argument:
+ * - If the string contains `/` or `\`, it is treated as a path to a service-account JSON key file
+ *   and passed to the client as `keyFilename`.
+ * - Otherwise the string is parsed as a JSON object and passed as `credentials`.
+ *
+ * @module google-cloud-stt
+ */
+/**
+ * Google Cloud Speech-to-Text batch provider.
+ *
+ * Implements the `SpeechToTextProvider` contract expected by the AgentOS
+ * voice pipeline without taking a hard runtime dependency on the interface
+ * types (to avoid circular imports when loaded as an extension pack).
+ */
+export class GoogleCloudSTTProvider {
+    /** Stable provider identifier used by the AgentOS extension registry. */
+    id = 'google-cloud-stt';
+    /** Lazily initialised Speech client. */
+    _client = null;
+    /** Resolved client constructor options (set in constructor, used in {@link _getClient}). */
+    _clientOptions;
+    /**
+     * Create a new {@link GoogleCloudSTTProvider}.
+     *
+     * @param credentials - Either an absolute path to a service-account JSON key
+     *   file (any string that contains `/` or `\`) or a JSON string containing
+     *   the service-account credentials object.
+     */
+    constructor(credentials) {
+        if (credentials.includes('/') || credentials.includes('\\')) {
+            // Treat as a file path.
+            this._clientOptions = { keyFilename: credentials };
+        }
+        else {
+            // Treat as an inline JSON credentials object.
+            this._clientOptions = { credentials: JSON.parse(credentials) };
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Return (and lazily create) the Google Cloud {@link SpeechClient}.
+     *
+     * Using a lazy initialisation pattern keeps the constructor synchronous and
+     * allows unit tests to inject the mock before the first `transcribe()` call.
+     */
+    async _getClient() {
+        if (!this._client) {
+            // Dynamic import keeps the peer dep truly optional at module-load time.
+            const { SpeechClient } = await import('@google-cloud/speech');
+            this._client = new SpeechClient(this._clientOptions);
+        }
+        return this._client;
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /**
+     * Transcribe a batch audio buffer using Google Cloud Speech-to-Text.
+     *
+     * The audio must be encoded as LINEAR16 (raw PCM, 16-bit little-endian).
+     * The method returns all recognised alternatives from the first result, each
+     * mapped to a {@link SpeechTranscriptionResult}.
+     *
+     * @param audio   - Audio frame containing the raw PCM bytes and sample rate.
+     * @param options - Optional per-call parameters (language code).
+     * @returns Array of transcription results ordered by confidence (descending).
+     */
+    async transcribe(audio, options) {
+        const client = await this._getClient();
+        const response = await client.recognize({
+            audio: { content: audio.data.toString('base64') },
+            config: {
+                encoding: 'LINEAR16',
+                sampleRateHertz: audio.sampleRate ?? 16000,
+                languageCode: options?.language ?? 'en-US',
+            },
+        });
+        const results = [];
+        for (const result of response[0]?.results ?? []) {
+            const alt = result?.alternatives?.[0];
+            if (alt) {
+                results.push({
+                    transcript: alt.transcript ?? '',
+                    confidence: alt.confidence ?? 0,
+                    isFinal: true,
+                });
+            }
+        }
+        return results;
+    }
+}
+//# sourceMappingURL=GoogleCloudSTTProvider.js.map

package/dist/GoogleCloudSTTProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GoogleCloudSTTProvider.js","sourceRoot":"","sources":["../src/GoogleCloudSTTProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAwCH;;;;;;GAMG;AACH,MAAM,OAAO,sBAAsB;IACjC,yEAAyE;IAChE,EAAE,GAAG,kBAAkB,CAAC;IAEjC,wCAAwC;IAChC,OAAO,GAAwB,IAAI,CAAC;IAE5C,4FAA4F;IAC3E,cAAc,CAA0B;IAEzD;;;;;;OAMG;IACH,YAAY,WAAmB;QAC7B,IAAI,WAAW,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC5D,wBAAwB;YACxB,IAAI,CAAC,cAAc,GAAG,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC;QACrD,CAAC;aAAM,CAAC;YACN,8CAA8C;YAC9C,IAAI,CAAC,cAAc,GAAG,EAAE,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,CAA4B,EAAE,CAAC;QAC5F,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,kBAAkB;IAClB,8EAA8E;IAE9E;;;;;OAKG;IACK,KAAK,CAAC,UAAU;QACtB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YAClB,wEAAwE;YACxE,MAAM,EAAE,YAAY,EAAE,GAAG,MAAM,MAAM,CAAC,sBAAsB,CAAC,CAAC;YAC9D,IAAI,CAAC,OAAO,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QACvD,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,8EAA8E;IAC9E,aAAa;IACb,8EAA8E;IAE9E;;;;;;;;;;OAUG;IACH,KAAK,CAAC,UAAU,CACd,KAAgB,EAChB,OAA+B;QAE/B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,EAAE,CAAC;QAEvC,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC;YACtC,KAAK,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE;YACjD,MAAM,EAAE;gBACN,QAAQ,EAAE,UAAU;gBACpB,eAAe,EAAE,KAAK,CAAC,UAAU,IAAI,KAAK;gBAC1C,YAAY,EAAE,OAAO,EAAE,QAAQ,IAAI,OAAO;aAC3C;SACF,CAAC,CAAC;QAEH,MAAM,OAAO,GAAgC,EAAE,CAAC;QAEhD,KAAK,MAAM,MAAM,IAAI,QAAQ,CAAC,CAAC,CAAC,EAAE,OAAO,IAAI,EAAE,EAAE,CAAC;YAChD,MAAM,GAAG,GAAG,MAAM,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,CAAC;YACtC,IAAI,GAAG,EAAE,CAAC;gBACR,OAAO,CAAC,IAAI,CAAC;oBACX,UAAU,EAAE,GAAG,CAAC,UAAU,IAAI,EAAE;oBAChC,UAAU,EAAE,GAAG,CAAC,UAAU,IAAI,CAAC;oBAC/B,OAAO,EAAE,IAAI;iBACd,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,66 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the Google Cloud STT extension pack.
+ *
+ * Exports the main {@link createGoogleCloudSTT} factory function and the
+ * {@link createExtensionPack} bridge function that conforms to the AgentOS
+ * manifest factory convention.
+ *
+ * ### Usage (direct)
+ * ```ts
+ * import { createGoogleCloudSTT } from '@framers/agentos-ext-google-cloud-stt';
+ *
+ * const stt = createGoogleCloudSTT('/path/to/service-account.json');
+ * const results = await stt.transcribe({ data: pcmBuffer, sampleRate: 16000 });
+ * ```
+ *
+ * ### Usage (manifest-driven)
+ * ```json
+ * { "packs": [{ "module": "@framers/agentos-ext-google-cloud-stt" }] }
+ * ```
+ *
+ * @module google-cloud-stt
+ */
+import { GoogleCloudSTTProvider } from './GoogleCloudSTTProvider.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 GoogleCloudSTTProvider} instance.
+ *
+ * Use this when composing the provider programmatically outside of the
+ * AgentOS extension system.
+ *
+ * @param credentials - Path to service-account JSON file or inline JSON string.
+ * @returns Configured {@link GoogleCloudSTTProvider}.
+ */
+export declare function createGoogleCloudSTT(credentials: string): GoogleCloudSTTProvider;
+/**
+ * AgentOS manifest factory function.
+ *
+ * Reads the `GOOGLE_CLOUD_STT_CREDENTIALS` secret from the context and
+ * returns an {@link ExtensionPack} containing a single `stt-provider`
+ * descriptor backed by {@link GoogleCloudSTTProvider}.
+ *
+ * @param context - Pack context supplied by the extension manager.
+ * @returns A fully configured {@link ExtensionPack}.
+ */
+export declare function createExtensionPack(context: ExtensionPackContext): ExtensionPack;
+export { GoogleCloudSTTProvider } from './GoogleCloudSTTProvider.js';
+export type { SpeechTranscriptionResult, GoogleCloudSTTOptions, AudioData, } from './GoogleCloudSTTProvider.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,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAMrE,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,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,sBAAsB,CAEhF;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAgBhF;AAMD,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,YAAY,EACV,yBAAyB,EACzB,qBAAqB,EACrB,SAAS,GACV,MAAM,6BAA6B,CAAC"}

package/dist/index.js

@@ -0,0 +1,72 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the Google Cloud STT extension pack.
+ *
+ * Exports the main {@link createGoogleCloudSTT} factory function and the
+ * {@link createExtensionPack} bridge function that conforms to the AgentOS
+ * manifest factory convention.
+ *
+ * ### Usage (direct)
+ * ```ts
+ * import { createGoogleCloudSTT } from '@framers/agentos-ext-google-cloud-stt';
+ *
+ * const stt = createGoogleCloudSTT('/path/to/service-account.json');
+ * const results = await stt.transcribe({ data: pcmBuffer, sampleRate: 16000 });
+ * ```
+ *
+ * ### Usage (manifest-driven)
+ * ```json
+ * { "packs": [{ "module": "@framers/agentos-ext-google-cloud-stt" }] }
+ * ```
+ *
+ * @module google-cloud-stt
+ */
+import { GoogleCloudSTTProvider } from './GoogleCloudSTTProvider.js';
+/** Kind constant matching packages/agentos/src/extensions/types.ts. */
+const EXTENSION_KIND_STT = 'stt-provider';
+// ---------------------------------------------------------------------------
+// Factories
+// ---------------------------------------------------------------------------
+/**
+ * Create a standalone {@link GoogleCloudSTTProvider} instance.
+ *
+ * Use this when composing the provider programmatically outside of the
+ * AgentOS extension system.
+ *
+ * @param credentials - Path to service-account JSON file or inline JSON string.
+ * @returns Configured {@link GoogleCloudSTTProvider}.
+ */
+export function createGoogleCloudSTT(credentials) {
+    return new GoogleCloudSTTProvider(credentials);
+}
+/**
+ * AgentOS manifest factory function.
+ *
+ * Reads the `GOOGLE_CLOUD_STT_CREDENTIALS` secret from the context and
+ * returns an {@link ExtensionPack} containing a single `stt-provider`
+ * descriptor backed by {@link GoogleCloudSTTProvider}.
+ *
+ * @param context - Pack context supplied by the extension manager.
+ * @returns A fully configured {@link ExtensionPack}.
+ */
+export function createExtensionPack(context) {
+    const credentials = context.getSecret?.('GOOGLE_CLOUD_STT_CREDENTIALS') ?? '';
+    const provider = new GoogleCloudSTTProvider(credentials);
+    return {
+        id: 'google-cloud-stt',
+        descriptors: [
+            {
+                id: 'google-cloud-stt',
+                kind: EXTENSION_KIND_STT,
+                payload: provider,
+                enableByDefault: true,
+                metadata: { providerId: 'google-cloud-stt' },
+            },
+        ],
+    };
+}
+// ---------------------------------------------------------------------------
+// Re-exports
+// ---------------------------------------------------------------------------
+export { GoogleCloudSTTProvider } from './GoogleCloudSTTProvider.js';
+//# sourceMappingURL=index.js.map

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,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AA2BrE,uEAAuE;AACvE,MAAM,kBAAkB,GAAG,cAAc,CAAC;AAE1C,8EAA8E;AAC9E,YAAY;AACZ,8EAA8E;AAE9E;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,WAAmB;IACtD,OAAO,IAAI,sBAAsB,CAAC,WAAW,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAA6B;IAC/D,MAAM,WAAW,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,8BAA8B,CAAC,IAAI,EAAE,CAAC;IAC9E,MAAM,QAAQ,GAAG,IAAI,sBAAsB,CAAC,WAAW,CAAC,CAAC;IAEzD,OAAO;QACL,EAAE,EAAE,kBAAkB;QACtB,WAAW,EAAE;YACX;gBACE,EAAE,EAAE,kBAAkB;gBACtB,IAAI,EAAE,kBAAkB;gBACxB,OAAO,EAAE,QAAQ;gBACjB,eAAe,EAAE,IAAI;gBACrB,QAAQ,EAAE,EAAE,UAAU,EAAE,kBAAkB,EAAE;aAC7C;SACF;KACF,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC"}

package/manifest.json

@@ -0,0 +1,8 @@
+{
+  "name": "@framers/agentos-ext-google-cloud-stt",
+  "version": "0.1.0",
+  "description": "Batch speech-to-text via Google Cloud Speech-to-Text API",
+  "kind": "stt-provider",
+  "extensionId": "google-cloud-stt",
+  "entryPoint": "./dist/index.js"
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@framers/agentos-ext-google-cloud-stt",
+  "version": "0.2.0",
+  "description": "Batch speech-to-text via Google Cloud Speech-to-Text 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",
+    "@google-cloud/speech": "^6.0.0"
+  },
+  "devDependencies": {
+    "@google-cloud/speech": "^6.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^1.6.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/google-cloud-stt"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run"
+  }
+}

package/src/GoogleCloudSTTProvider.ts

@@ -0,0 +1,149 @@
+/**
+ * @file GoogleCloudSTTProvider.ts
+ * @description Batch speech-to-text provider backed by Google Cloud Speech-to-Text V1 API.
+ *
+ * Credentials are resolved from the constructor argument:
+ * - If the string contains `/` or `\`, it is treated as a path to a service-account JSON key file
+ *   and passed to the client as `keyFilename`.
+ * - Otherwise the string is parsed as a JSON object and passed as `credentials`.
+ *
+ * @module google-cloud-stt
+ */
+
+// Dynamic import is used so the SDK is only loaded at runtime, allowing the
+// module to load without throwing when the peer dep is absent.
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type SpeechClient = any;
+
+/**
+ * A single recognised audio segment returned by the provider.
+ *
+ * Mirrors the generic `SpeechTranscriptionResult` shape used across the
+ * AgentOS voice pipeline.
+ */
+export interface SpeechTranscriptionResult {
+  /** The recognised text. */
+  transcript: string;
+  /** Confidence score in [0, 1]. */
+  confidence: number;
+  /** Whether this is a final (non-speculative) result. Always `true` for batch. */
+  isFinal: boolean;
+}
+
+/**
+ * Per-call transcription options forwarded to the Google Cloud API.
+ */
+export interface GoogleCloudSTTOptions {
+  /** BCP-47 language code (e.g. `'en-US'`, `'fr-FR'`). @defaultValue `'en-US'` */
+  language?: string;
+}
+
+/**
+ * Audio frame passed to {@link GoogleCloudSTTProvider.transcribe}.
+ */
+export interface AudioData {
+  /** Raw PCM bytes (LINEAR16). */
+  data: Buffer;
+  /** Sample rate in Hz. @defaultValue `16000` */
+  sampleRate?: number;
+}
+
+/**
+ * Google Cloud Speech-to-Text batch provider.
+ *
+ * Implements the `SpeechToTextProvider` contract expected by the AgentOS
+ * voice pipeline without taking a hard runtime dependency on the interface
+ * types (to avoid circular imports when loaded as an extension pack).
+ */
+export class GoogleCloudSTTProvider {
+  /** Stable provider identifier used by the AgentOS extension registry. */
+  readonly id = 'google-cloud-stt';
+
+  /** Lazily initialised Speech client. */
+  private _client: SpeechClient | null = null;
+
+  /** Resolved client constructor options (set in constructor, used in {@link _getClient}). */
+  private readonly _clientOptions: Record<string, unknown>;
+
+  /**
+   * Create a new {@link GoogleCloudSTTProvider}.
+   *
+   * @param credentials - Either an absolute path to a service-account JSON key
+   *   file (any string that contains `/` or `\`) or a JSON string containing
+   *   the service-account credentials object.
+   */
+  constructor(credentials: string) {
+    if (credentials.includes('/') || credentials.includes('\\')) {
+      // Treat as a file path.
+      this._clientOptions = { keyFilename: credentials };
+    } else {
+      // Treat as an inline JSON credentials object.
+      this._clientOptions = { credentials: JSON.parse(credentials) as Record<string, unknown> };
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Return (and lazily create) the Google Cloud {@link SpeechClient}.
+   *
+   * Using a lazy initialisation pattern keeps the constructor synchronous and
+   * allows unit tests to inject the mock before the first `transcribe()` call.
+   */
+  private async _getClient(): Promise<SpeechClient> {
+    if (!this._client) {
+      // Dynamic import keeps the peer dep truly optional at module-load time.
+      const { SpeechClient } = await import('@google-cloud/speech');
+      this._client = new SpeechClient(this._clientOptions);
+    }
+    return this._client;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Public API
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Transcribe a batch audio buffer using Google Cloud Speech-to-Text.
+   *
+   * The audio must be encoded as LINEAR16 (raw PCM, 16-bit little-endian).
+   * The method returns all recognised alternatives from the first result, each
+   * mapped to a {@link SpeechTranscriptionResult}.
+   *
+   * @param audio   - Audio frame containing the raw PCM bytes and sample rate.
+   * @param options - Optional per-call parameters (language code).
+   * @returns Array of transcription results ordered by confidence (descending).
+   */
+  async transcribe(
+    audio: AudioData,
+    options?: GoogleCloudSTTOptions,
+  ): Promise<SpeechTranscriptionResult[]> {
+    const client = await this._getClient();
+
+    const response = await client.recognize({
+      audio: { content: audio.data.toString('base64') },
+      config: {
+        encoding: 'LINEAR16',
+        sampleRateHertz: audio.sampleRate ?? 16000,
+        languageCode: options?.language ?? 'en-US',
+      },
+    });
+
+    const results: SpeechTranscriptionResult[] = [];
+
+    for (const result of response[0]?.results ?? []) {
+      const alt = result?.alternatives?.[0];
+      if (alt) {
+        results.push({
+          transcript: alt.transcript ?? '',
+          confidence: alt.confidence ?? 0,
+          isFinal: true,
+        });
+      }
+    }
+
+    return results;
+  }
+}

package/src/index.ts

@@ -0,0 +1,109 @@
+/**
+ * @file index.ts
+ * @description Pack factory for the Google Cloud STT extension pack.
+ *
+ * Exports the main {@link createGoogleCloudSTT} factory function and the
+ * {@link createExtensionPack} bridge function that conforms to the AgentOS
+ * manifest factory convention.
+ *
+ * ### Usage (direct)
+ * ```ts
+ * import { createGoogleCloudSTT } from '@framers/agentos-ext-google-cloud-stt';
+ *
+ * const stt = createGoogleCloudSTT('/path/to/service-account.json');
+ * const results = await stt.transcribe({ data: pcmBuffer, sampleRate: 16000 });
+ * ```
+ *
+ * ### Usage (manifest-driven)
+ * ```json
+ * { "packs": [{ "module": "@framers/agentos-ext-google-cloud-stt" }] }
+ * ```
+ *
+ * @module google-cloud-stt
+ */
+
+import { GoogleCloudSTTProvider } from './GoogleCloudSTTProvider.js';
+
+// ---------------------------------------------------------------------------
+// Local interface mirrors — avoids a hard runtime dep on @framers/agentos
+// ---------------------------------------------------------------------------
+
+/** 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>;
+}
+
+/** Kind constant matching packages/agentos/src/extensions/types.ts. */
+const EXTENSION_KIND_STT = 'stt-provider';
+
+// ---------------------------------------------------------------------------
+// Factories
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a standalone {@link GoogleCloudSTTProvider} instance.
+ *
+ * Use this when composing the provider programmatically outside of the
+ * AgentOS extension system.
+ *
+ * @param credentials - Path to service-account JSON file or inline JSON string.
+ * @returns Configured {@link GoogleCloudSTTProvider}.
+ */
+export function createGoogleCloudSTT(credentials: string): GoogleCloudSTTProvider {
+  return new GoogleCloudSTTProvider(credentials);
+}
+
+/**
+ * AgentOS manifest factory function.
+ *
+ * Reads the `GOOGLE_CLOUD_STT_CREDENTIALS` secret from the context and
+ * returns an {@link ExtensionPack} containing a single `stt-provider`
+ * descriptor backed by {@link GoogleCloudSTTProvider}.
+ *
+ * @param context - Pack context supplied by the extension manager.
+ * @returns A fully configured {@link ExtensionPack}.
+ */
+export function createExtensionPack(context: ExtensionPackContext): ExtensionPack {
+  const credentials = context.getSecret?.('GOOGLE_CLOUD_STT_CREDENTIALS') ?? '';
+  const provider = new GoogleCloudSTTProvider(credentials);
+
+  return {
+    id: 'google-cloud-stt',
+    descriptors: [
+      {
+        id: 'google-cloud-stt',
+        kind: EXTENSION_KIND_STT,
+        payload: provider,
+        enableByDefault: true,
+        metadata: { providerId: 'google-cloud-stt' },
+      },
+    ],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Re-exports
+// ---------------------------------------------------------------------------
+
+export { GoogleCloudSTTProvider } from './GoogleCloudSTTProvider.js';
+export type {
+  SpeechTranscriptionResult,
+  GoogleCloudSTTOptions,
+  AudioData,
+} from './GoogleCloudSTTProvider.js';