@xynogen/pix-9router 0.1.0

package/src/transcribe.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect } from "bun:test";
+import { extname } from "node:path";
+
+// ── Re-export internal helpers for testing via module augmentation ────────────
+// transcribe.ts exports only the default fn; we test the pure logic
+// inline here to avoid coupling tests to private internals.
+
+// ── mimeType (copied from transcribe.ts) ─────────────────────────────────────
+
+function mimeType(filePath: string): string {
+	const ext = extname(filePath).toLowerCase();
+	const types: Record<string, string> = {
+		".mp3": "audio/mpeg",
+		".wav": "audio/wav",
+		".flac": "audio/flac",
+		".ogg": "audio/ogg",
+		".m4a": "audio/mp4",
+		".webm": "audio/webm",
+		".mp4": "audio/mp4",
+		".mpga": "audio/mpeg",
+	};
+	return types[ext] ?? "application/octet-stream";
+}
+
+// ── parseTranscriptionResponse (extracted logic from execute) ─────────────────
+
+function parseTranscriptionResponse(raw: string): string {
+	try {
+		const parsed = JSON.parse(raw) as { text?: string };
+		return parsed.text ?? raw;
+	} catch {
+		return raw;
+	}
+}
+
+// ── mimeType ─────────────────────────────────────────────────────────────────
+
+describe("mimeType", () => {
+	it("returns audio/mpeg for .mp3", () => {
+		expect(mimeType("recording.mp3")).toBe("audio/mpeg");
+	});
+
+	it("returns audio/mpeg for .mpga", () => {
+		expect(mimeType("recording.mpga")).toBe("audio/mpeg");
+	});
+
+	it("returns audio/wav for .wav", () => {
+		expect(mimeType("recording.wav")).toBe("audio/wav");
+	});
+
+	it("returns audio/flac for .flac", () => {
+		expect(mimeType("music.flac")).toBe("audio/flac");
+	});
+
+	it("returns audio/ogg for .ogg", () => {
+		expect(mimeType("voice.ogg")).toBe("audio/ogg");
+	});
+
+	it("returns audio/mp4 for .m4a", () => {
+		expect(mimeType("podcast.m4a")).toBe("audio/mp4");
+	});
+
+	it("returns audio/webm for .webm", () => {
+		expect(mimeType("clip.webm")).toBe("audio/webm");
+	});
+
+	it("returns audio/mp4 for .mp4", () => {
+		expect(mimeType("video.mp4")).toBe("audio/mp4");
+	});
+
+	it("is case-insensitive on extension", () => {
+		expect(mimeType("LOUD.MP3")).toBe("audio/mpeg");
+		expect(mimeType("file.WAV")).toBe("audio/wav");
+		expect(mimeType("track.Flac")).toBe("audio/flac");
+	});
+
+	it("returns application/octet-stream for unknown extension", () => {
+		expect(mimeType("archive.zip")).toBe("application/octet-stream");
+	});
+
+	it("returns application/octet-stream for no extension", () => {
+		expect(mimeType("noext")).toBe("application/octet-stream");
+	});
+
+	it("handles paths with directories", () => {
+		expect(mimeType("/home/user/audio/meeting.mp3")).toBe("audio/mpeg");
+		expect(mimeType("./recordings/call.wav")).toBe("audio/wav");
+	});
+
+	it("handles dotfiles with audio extensions", () => {
+		expect(mimeType(".hidden.mp3")).toBe("audio/mpeg");
+	});
+});
+
+// ── parseTranscriptionResponse ───────────────────────────────────────────────
+
+describe("parseTranscriptionResponse", () => {
+	it("extracts text from JSON response", () => {
+		const raw = JSON.stringify({ text: "Hello, world!" });
+		expect(parseTranscriptionResponse(raw)).toBe("Hello, world!");
+	});
+
+	it("extracts text from JSON with extra fields", () => {
+		const raw = JSON.stringify({
+			text: "Transcribed content",
+			duration: 5.2,
+			language: "en",
+		});
+		expect(parseTranscriptionResponse(raw)).toBe("Transcribed content");
+	});
+
+	it("returns raw JSON string when text field is missing", () => {
+		const raw = JSON.stringify({ result: "no text field" });
+		expect(parseTranscriptionResponse(raw)).toBe(raw);
+	});
+
+	it("returns plain text as-is when not JSON", () => {
+		expect(parseTranscriptionResponse("Just plain text")).toBe(
+			"Just plain text",
+		);
+	});
+
+	it("returns empty string from JSON with empty text", () => {
+		const raw = JSON.stringify({ text: "" });
+		// ?? only triggers on null/undefined, not empty string — so "" is returned
+		expect(parseTranscriptionResponse(raw)).toBe("");
+	});
+
+	it("returns raw when text is null", () => {
+		const raw = JSON.stringify({ text: null });
+		// null ?? raw → raw
+		expect(parseTranscriptionResponse(raw)).toBe(raw);
+	});
+
+	it("returns raw when text is undefined (absent from parsed object)", () => {
+		const raw = JSON.stringify({ other: "stuff" });
+		// parsed.text is undefined → undefined ?? raw → raw
+		expect(parseTranscriptionResponse(raw)).toBe(raw);
+	});
+
+	it("handles multiline transcription", () => {
+		const text = "Line one.\nLine two.\nLine three.";
+		const raw = JSON.stringify({ text });
+		expect(parseTranscriptionResponse(raw)).toBe(text);
+	});
+
+	it("handles unicode in transcription", () => {
+		const text = "日本語のテスト 🎙️";
+		const raw = JSON.stringify({ text });
+		expect(parseTranscriptionResponse(raw)).toBe(text);
+	});
+
+	it("handles broken JSON gracefully", () => {
+		expect(parseTranscriptionResponse("{broken")).toBe("{broken");
+	});
+
+	it("handles empty string input", () => {
+		expect(parseTranscriptionResponse("")).toBe("");
+	});
+});

package/src/transcribe.ts

@@ -0,0 +1,240 @@
+/**
+ * transcribe.ts — speech-to-text tool via 9Router audio transcription API, with curl fallback.
+ *
+ * Uses the OpenAI-compatible /audio/transcriptions endpoint through the router.
+ * Accepts a file path to an audio file and returns the transcribed text.
+ *
+ * Default model: dg/nova-3 (Deepgram Nova 3)
+ *
+ * Environment:
+ *   ROUTER_API_BASE  — router API base URL (default: https://9r.xynogen.xyz/v1)
+ *   ROUTER_API_KEY   — bearer token for the router
+ */
+
+import { readFile } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { basename, extname } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { routerBaseUrl } from "./data.js";
+
+const REQUEST_TIMEOUT_MS = 120_000; // audio transcription can take longer
+const DEFAULT_MODEL = "dg/nova-3";
+
+function auth(): string | undefined {
+	return process.env.ROUTER_API_KEY;
+}
+
+/** Map file extension to MIME type for common audio formats. */
+function mimeType(filePath: string): string {
+	const ext = extname(filePath).toLowerCase();
+	const types: Record<string, string> = {
+		".mp3": "audio/mpeg",
+		".wav": "audio/wav",
+		".flac": "audio/flac",
+		".ogg": "audio/ogg",
+		".m4a": "audio/mp4",
+		".webm": "audio/webm",
+		".mp4": "audio/mp4",
+		".mpga": "audio/mpeg",
+	};
+	return types[ext] ?? "application/octet-stream";
+}
+
+async function apiMultipart(
+	path: string,
+	filePath: string,
+	model: string,
+	language: string | undefined,
+	signal?: AbortSignal,
+): Promise<string> {
+	const url = `${routerBaseUrl()}${path}`;
+	const key = auth();
+	const controller = new AbortController();
+	const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+	const s = signal
+		? AbortSignal.any([signal, controller.signal])
+		: controller.signal;
+
+	try {
+		const fileData = await readFile(filePath);
+		const blob = new Blob([fileData], { type: mimeType(filePath) });
+
+		const form = new FormData();
+		form.append("file", blob, basename(filePath));
+		form.append("model", model);
+		if (language) form.append("language", language);
+
+		const res = await fetch(url, {
+			method: "POST",
+			headers: {
+				...(key ? { Authorization: `Bearer ${key}` } : {}),
+			},
+			body: form,
+			signal: s,
+		});
+		if (!res.ok) {
+			const errText = await res.text().catch(() => "");
+			throw new Error(`API ${res.status}: ${errText.slice(0, 500)}`);
+		}
+		return await res.text();
+	} finally {
+		clearTimeout(timeout);
+	}
+}
+
+function curl(args: string[]): Promise<string> {
+	return new Promise((resolve, reject) => {
+		execFile(
+			"curl",
+			["-sS", "--connect-timeout", "10", "--max-time", "120", ...args],
+			{ maxBuffer: 10 * 1024 * 1024, timeout: REQUEST_TIMEOUT_MS },
+			(err, stdout, stderr) => {
+				if (err) {
+					const msg = (err as NodeJS.ErrnoException).killed
+						? "curl timed out"
+						: `curl exit ${(err as NodeJS.ErrnoException).code ?? "??"}: ${stderr.slice(0, 300)}`;
+					reject(new Error(msg));
+					return;
+				}
+				resolve(stdout);
+			},
+		);
+	});
+}
+
+export default function registerTranscribe(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: "transcribe",
+		label: "Transcribe",
+		description:
+			"Convert speech to text. Transcribes an audio file using the 9Router audio transcription API (Deepgram Nova 3).",
+		promptSnippet:
+			"transcribe(file, model?, language?) — Transcribe an audio file to text. Supports mp3, wav, flac, ogg, m4a, webm. Default model: dg/nova-3.",
+		promptGuidelines: [
+			"Use transcribe when you need to convert speech/audio to text.",
+			"The file parameter should be an absolute or relative path to an audio file on disk.",
+			"Supports common audio formats: mp3, wav, flac, ogg, m4a, webm, mp4.",
+			"Default model is dg/nova-3 (Deepgram Nova 3). Override with model parameter if needed.",
+			"Optionally specify language as ISO 639-1 code (e.g. 'en', 'es', 'fr') for better accuracy.",
+		],
+		parameters: Type.Object({
+			file: Type.String({
+				description: "Path to the audio file to transcribe",
+			}),
+			model: Type.Optional(
+				Type.String({
+					description: "Transcription model to use (default: dg/nova-3)",
+					default: DEFAULT_MODEL,
+				}),
+			),
+			language: Type.Optional(
+				Type.String({
+					description:
+						"ISO 639-1 language code (e.g. 'en', 'es', 'fr') for better accuracy",
+				}),
+			),
+		}),
+
+		async execute(_toolCallId, params, signal, onUpdate) {
+			const model = params.model ?? DEFAULT_MODEL;
+			const filePath = params.file;
+			let apiMsg = "";
+
+			try {
+				onUpdate?.({
+					content: [
+						{
+							type: "text",
+							text: `Transcribing: ${filePath} (model: ${model})...`,
+						},
+					],
+				});
+
+				const raw = await apiMultipart(
+					"/audio/transcriptions",
+					filePath,
+					model,
+					params.language,
+					signal,
+				);
+
+				// The API may return JSON {"text": "..."} or plain text
+				let text: string;
+				try {
+					const parsed = JSON.parse(raw) as { text?: string };
+					text = parsed.text ?? raw;
+				} catch {
+					text = raw;
+				}
+
+				return {
+					content: [{ type: "text", text: text.slice(0, 50_000) }],
+					details: {
+						source: "api",
+						model,
+						chars: text.length,
+					},
+				};
+			} catch (apiErr: unknown) {
+				apiMsg = apiErr instanceof Error ? apiErr.message : String(apiErr);
+				onUpdate?.({
+					content: [
+						{
+							type: "text",
+							text: `API failed: ${apiMsg}\nFalling back to curl...`,
+						},
+					],
+				});
+			}
+
+			// curl fallback — uses multipart form upload
+			try {
+				const curlArgs = [
+					"-X",
+					"POST",
+					...(auth() ? ["-H", `Authorization: Bearer ${auth()}`] : []),
+					"-F",
+					`file=@${filePath}`,
+					"-F",
+					`model=${model}`,
+					...(params.language ? ["-F", `language=${params.language}`] : []),
+					`${routerBaseUrl()}/audio/transcriptions`,
+				];
+
+				const raw = await curl(curlArgs);
+
+				let text: string;
+				try {
+					const parsed = JSON.parse(raw) as { text?: string };
+					text = parsed.text ?? raw;
+				} catch {
+					text = raw;
+				}
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: `[FALLBACK — curl] API called via curl instead of fetch.\n\n${text.slice(0, 49_500)}`,
+						},
+					],
+					details: { source: "curl-fallback", model },
+				};
+			} catch (curlErr: unknown) {
+				const curlMsg =
+					curlErr instanceof Error ? curlErr.message : String(curlErr);
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Transcription failed (both API and curl).\nAPI: ${apiMsg}\nCurl: ${curlMsg}`,
+						},
+					],
+					details: { source: "failed" },
+					isError: true,
+				};
+			}
+		},
+	});
+}