@openvole/paw-stt 0.1.0

package/README.md

@@ -0,0 +1,45 @@
+# @openvole/paw-stt
+
+[![npm version](https://img.shields.io/npm/v/@openvole/paw-stt.svg)](https://www.npmjs.com/package/@openvole/paw-stt)
+
+Speech-to-text tool Paw for OpenVole. Transcribe audio files using the OpenAI Whisper API.
+
+## Install
+
+```bash
+npm install @openvole/paw-stt
+```
+
+## Configuration
+
+Add to your Vole config:
+
+```json
+{
+  "paws": ["@openvole/paw-stt"]
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `OPENAI_API_KEY` | Yes | — | OpenAI API key for Whisper access |
+| `OPENAI_STT_MODEL` | No | `whisper-1` | Whisper model to use |
+
+## Tool
+
+### `stt_transcribe`
+
+Transcribe an audio file to text using OpenAI Whisper.
+
+**Parameters:**
+
+- `file_path` (string, required) — Absolute path to the audio file.
+- `language` (string, optional) — ISO-639-1 language code (e.g. `"en"`, `"fr"`). Whisper auto-detects if omitted.
+
+**Supported formats:** mp3, wav, m4a, webm, mp4, mpeg, mpga, oga, ogg, flac.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import * as _openvole_paw_sdk from '@openvole/paw-sdk';
+
+declare const _default: _openvole_paw_sdk.PawDefinition;
+
+export { _default as default };

package/dist/index.js

@@ -0,0 +1,144 @@
+// src/index.ts
+import { definePaw } from "@openvole/paw-sdk";
+
+// src/paw.ts
+import { z } from "@openvole/paw-sdk";
+
+// src/whisper.ts
+import { readFile, access } from "fs/promises";
+import { basename, extname } from "path";
+var SUPPORTED_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".mp3",
+  ".wav",
+  ".m4a",
+  ".webm",
+  ".mp4",
+  ".mpeg",
+  ".mpga",
+  ".oga",
+  ".ogg",
+  ".flac"
+]);
+var MIME_TYPES = {
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+  ".m4a": "audio/mp4",
+  ".webm": "audio/webm",
+  ".mp4": "audio/mp4",
+  ".mpeg": "audio/mpeg",
+  ".mpga": "audio/mpeg",
+  ".oga": "audio/ogg",
+  ".ogg": "audio/ogg",
+  ".flac": "audio/flac"
+};
+var WhisperClient = class {
+  apiKey;
+  model;
+  constructor(apiKey, model = "whisper-1") {
+    this.apiKey = apiKey;
+    this.model = model;
+  }
+  async transcribe(filePath, language) {
+    try {
+      await access(filePath);
+    } catch {
+      throw new Error(`File not found: ${filePath}`);
+    }
+    const ext = extname(filePath).toLowerCase();
+    if (!SUPPORTED_EXTENSIONS.has(ext)) {
+      throw new Error(
+        `Unsupported audio format "${ext}". Supported formats: ${[...SUPPORTED_EXTENSIONS].map((e) => e.slice(1)).join(", ")}`
+      );
+    }
+    const fileBuffer = await readFile(filePath);
+    const mimeType = MIME_TYPES[ext] ?? "application/octet-stream";
+    const fileName = basename(filePath);
+    const formData = new FormData();
+    formData.append("file", new Blob([fileBuffer], { type: mimeType }), fileName);
+    formData.append("model", this.model);
+    if (language) {
+      formData.append("language", language);
+    }
+    const response = await fetch(
+      "https://api.openai.com/v1/audio/transcriptions",
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`
+        },
+        body: formData
+      }
+    );
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(
+        `Whisper API error (${response.status}): ${body}`
+      );
+    }
+    const json = await response.json();
+    return json.text;
+  }
+};
+
+// src/paw.ts
+var whisper;
+function getWhisper() {
+  if (!whisper) {
+    throw new Error("WhisperClient not initialized \u2014 onLoad has not been called");
+  }
+  return whisper;
+}
+var paw = {
+  name: "@openvole/paw-stt",
+  version: "0.1.0",
+  description: "Speech-to-text tool using OpenAI Whisper",
+  brain: false,
+  tools: [
+    {
+      name: "stt_transcribe",
+      description: "Transcribe an audio file to text using OpenAI Whisper",
+      parameters: z.object({
+        file_path: z.string().describe("Absolute path to the audio file to transcribe"),
+        language: z.string().optional().describe('ISO-639-1 language code (e.g. "en", "fr", "de"). Optional \u2014 Whisper auto-detects if omitted')
+      }),
+      async execute(params) {
+        const { file_path, language } = params;
+        try {
+          const text = await getWhisper().transcribe(file_path, language);
+          return { text, file_path, language: language ?? null };
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          if (message.startsWith("File not found")) {
+            throw new Error(`File not found: ${file_path}`);
+          }
+          if (message.startsWith("Unsupported audio format")) {
+            throw new Error(message);
+          }
+          throw new Error(`Whisper transcription failed: ${message}`);
+        }
+      }
+    }
+  ],
+  async onLoad() {
+    const apiKey = process.env.OPENAI_API_KEY;
+    if (!apiKey) {
+      throw new Error(
+        "[paw-stt] OPENAI_API_KEY environment variable is required"
+      );
+    }
+    const model = process.env.OPENAI_STT_MODEL ?? "whisper-1";
+    whisper = new WhisperClient(apiKey, model);
+    console.log(`[paw-stt] loaded \u2014 model: ${model}`);
+  },
+  async onUnload() {
+    whisper = void 0;
+    console.log("[paw-stt] unloaded");
+  }
+};
+
+// src/index.ts
+var index_default = definePaw(paw);
+export {
+  index_default as default
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/paw.ts","../src/whisper.ts"],"sourcesContent":["import { definePaw } from '@openvole/paw-sdk'\nimport { paw } from './paw.js'\n\nexport default definePaw(paw)\n","import { z, type PawDefinition } from '@openvole/paw-sdk'\nimport { WhisperClient } from './whisper.js'\n\nlet whisper: WhisperClient | undefined\n\nfunction getWhisper(): WhisperClient {\n\tif (!whisper) {\n\t\tthrow new Error('WhisperClient not initialized — onLoad has not been called')\n\t}\n\treturn whisper\n}\n\nexport const paw: PawDefinition = {\n\tname: '@openvole/paw-stt',\n\tversion: '0.1.0',\n\tdescription: 'Speech-to-text tool using OpenAI Whisper',\n\tbrain: false,\n\n\ttools: [\n\t\t{\n\t\t\tname: 'stt_transcribe',\n\t\t\tdescription: 'Transcribe an audio file to text using OpenAI Whisper',\n\t\t\tparameters: z.object({\n\t\t\t\tfile_path: z.string().describe('Absolute path to the audio file to transcribe'),\n\t\t\t\tlanguage: z\n\t\t\t\t\t.string()\n\t\t\t\t\t.optional()\n\t\t\t\t\t.describe('ISO-639-1 language code (e.g. \"en\", \"fr\", \"de\"). Optional — Whisper auto-detects if omitted'),\n\t\t\t}),\n\t\t\tasync execute(params: unknown) {\n\t\t\t\tconst { file_path, language } = params as {\n\t\t\t\t\tfile_path: string\n\t\t\t\t\tlanguage?: string\n\t\t\t\t}\n\n\t\t\t\ttry {\n\t\t\t\t\tconst text = await getWhisper().transcribe(file_path, language)\n\t\t\t\t\treturn { text, file_path, language: language ?? null }\n\t\t\t\t} catch (err) {\n\t\t\t\t\tconst message =\n\t\t\t\t\t\terr instanceof Error ? err.message : String(err)\n\n\t\t\t\t\tif (message.startsWith('File not found')) {\n\t\t\t\t\t\tthrow new Error(`File not found: ${file_path}`)\n\t\t\t\t\t}\n\t\t\t\t\tif (message.startsWith('Unsupported audio format')) {\n\t\t\t\t\t\tthrow new Error(message)\n\t\t\t\t\t}\n\t\t\t\t\tthrow new Error(`Whisper transcription failed: ${message}`)\n\t\t\t\t}\n\t\t\t},\n\t\t},\n\t],\n\n\tasync onLoad() {\n\t\tconst apiKey = process.env.OPENAI_API_KEY\n\t\tif (!apiKey) {\n\t\t\tthrow new Error(\n\t\t\t\t'[paw-stt] OPENAI_API_KEY environment variable is required',\n\t\t\t)\n\t\t}\n\n\t\tconst model = process.env.OPENAI_STT_MODEL ?? 'whisper-1'\n\t\twhisper = new WhisperClient(apiKey, model)\n\t\tconsole.log(`[paw-stt] loaded — model: ${model}`)\n\t},\n\n\tasync onUnload() {\n\t\twhisper = undefined\n\t\tconsole.log('[paw-stt] unloaded')\n\t},\n}\n","import { readFile, access } from 'node:fs/promises'\nimport { basename, extname } from 'node:path'\n\nconst SUPPORTED_EXTENSIONS = new Set([\n\t'.mp3',\n\t'.wav',\n\t'.m4a',\n\t'.webm',\n\t'.mp4',\n\t'.mpeg',\n\t'.mpga',\n\t'.oga',\n\t'.ogg',\n\t'.flac',\n])\n\nconst MIME_TYPES: Record<string, string> = {\n\t'.mp3': 'audio/mpeg',\n\t'.wav': 'audio/wav',\n\t'.m4a': 'audio/mp4',\n\t'.webm': 'audio/webm',\n\t'.mp4': 'audio/mp4',\n\t'.mpeg': 'audio/mpeg',\n\t'.mpga': 'audio/mpeg',\n\t'.oga': 'audio/ogg',\n\t'.ogg': 'audio/ogg',\n\t'.flac': 'audio/flac',\n}\n\nexport class WhisperClient {\n\tprivate apiKey: string\n\tprivate model: string\n\n\tconstructor(apiKey: string, model = 'whisper-1') {\n\t\tthis.apiKey = apiKey\n\t\tthis.model = model\n\t}\n\n\tasync transcribe(filePath: string, language?: string): Promise<string> {\n\t\t// Validate file exists\n\t\ttry {\n\t\t\tawait access(filePath)\n\t\t} catch {\n\t\t\tthrow new Error(`File not found: ${filePath}`)\n\t\t}\n\n\t\t// Validate file extension\n\t\tconst ext = extname(filePath).toLowerCase()\n\t\tif (!SUPPORTED_EXTENSIONS.has(ext)) {\n\t\t\tthrow new Error(\n\t\t\t\t`Unsupported audio format \"${ext}\". Supported formats: ${[...SUPPORTED_EXTENSIONS].map((e) => e.slice(1)).join(', ')}`,\n\t\t\t)\n\t\t}\n\n\t\tconst fileBuffer = await readFile(filePath)\n\t\tconst mimeType = MIME_TYPES[ext] ?? 'application/octet-stream'\n\t\tconst fileName = basename(filePath)\n\n\t\tconst formData = new FormData()\n\t\tformData.append('file', new Blob([fileBuffer], { type: mimeType }), fileName)\n\t\tformData.append('model', this.model)\n\t\tif (language) {\n\t\t\tformData.append('language', language)\n\t\t}\n\n\t\tconst response = await fetch(\n\t\t\t'https://api.openai.com/v1/audio/transcriptions',\n\t\t\t{\n\t\t\t\tmethod: 'POST',\n\t\t\t\theaders: {\n\t\t\t\t\tAuthorization: `Bearer ${this.apiKey}`,\n\t\t\t\t},\n\t\t\t\tbody: formData,\n\t\t\t},\n\t\t)\n\n\t\tif (!response.ok) {\n\t\t\tconst body = await response.text()\n\t\t\tthrow new Error(\n\t\t\t\t`Whisper API error (${response.status}): ${body}`,\n\t\t\t)\n\t\t}\n\n\t\tconst json = (await response.json()) as { text: string }\n\t\treturn json.text\n\t}\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@openvole/paw-stt",
+  "version": "0.1.0",
+  "description": "Speech-to-text tool Paw for OpenVole — transcribe audio with OpenAI Whisper",
+  "type": "module",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.0",
+    "@openvole/paw-sdk": "^0.3.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "files": [
+    "dist",
+    "vole-paw.json",
+    "README.md"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@openvole/paw-sdk": "^0.3.0"
+  }
+}

package/vole-paw.json

@@ -0,0 +1,18 @@
+{
+  "name": "@openvole/paw-stt",
+  "version": "0.1.0",
+  "description": "Speech-to-text tool Paw using OpenAI Whisper",
+  "entry": "./dist/index.js",
+  "brain": false,
+  "inProcess": false,
+  "transport": "ipc",
+  "tools": [
+    { "name": "stt_transcribe", "description": "Transcribe an audio file to text using OpenAI Whisper" }
+  ],
+  "permissions": {
+    "network": ["api.openai.com"],
+    "listen": [],
+    "filesystem": [],
+    "env": ["OPENAI_API_KEY", "OPENAI_STT_MODEL"]
+  }
+}