@inceptionstack/roundhouse 0.2.2 → 0.3.0

package/src/voice/providers/whisper.ts

@@ -0,0 +1,339 @@
+/**
+ * voice/providers/whisper.ts — Local Whisper STT provider
+ *
+ * Runs the whisper CLI via child_process. Auto-detects language.
+ * Can auto-install whisper via pip3 and warm the model on first use.
+ */
+
+import { execFile } from "node:child_process";
+import { access, constants, rm, readFile, readdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { mkdirSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import type { SttProvider, SttInput, TranscriptionResult, SttProviderConfig } from "../types";
+
+// ── Binary discovery ─────────────────────────────────
+
+const WHISPER_PATHS = [
+  join(homedir(), ".local", "bin", "whisper"),
+  "/usr/local/bin/whisper",
+  "/usr/bin/whisper",
+];
+
+let cachedBinaryPath: string | null | undefined; // undefined = not checked yet
+
+async function findWhisperBinary(): Promise<string | null> {
+  if (cachedBinaryPath !== undefined) return cachedBinaryPath;
+
+  for (const p of WHISPER_PATHS) {
+    try {
+      await access(p, constants.X_OK);
+      cachedBinaryPath = p;
+      return p;
+    } catch {}
+  }
+  cachedBinaryPath = null;
+  return null;
+}
+
+/** Reset cached path so next findWhisperBinary() re-scans */
+function invalidateCache(): void {
+  cachedBinaryPath = undefined;
+}
+
+// ── Auto-install ─────────────────────────────────────
+
+let pipAvailable: boolean | undefined;
+
+async function checkPip(): Promise<boolean> {
+  if (pipAvailable !== undefined) return pipAvailable;
+  return new Promise<boolean>((resolve) => {
+    execFile("pip3", ["--version"], { timeout: 5000 }, (err) => {
+      pipAvailable = !err;
+      resolve(pipAvailable);
+    });
+  });
+}
+
+/**
+ * Install whisper via pip3 --user. Returns the binary path or null on failure.
+ */
+async function installWhisperWithPip(): Promise<string | null> {
+  if (!(await checkPip())) {
+    console.warn("[stt/whisper] pip3 not available — cannot auto-install whisper");
+    return null;
+  }
+
+  console.log("[stt/whisper] installing openai-whisper via pip3...");
+  return new Promise<string | null>((resolve) => {
+    execFile(
+      "pip3",
+      ["install", "--user", "openai-whisper"],
+      {
+        timeout: 300_000, // 5 min for install
+        maxBuffer: 10 * 1024 * 1024, // 10MB for pip output
+        env: { ...process.env },
+      },
+      async (err, stdout, stderr) => {
+        if (err) {
+          console.error("[stt/whisper] pip3 install failed:", err.message);
+          if (stderr) console.error("[stt/whisper] stderr:", stderr.slice(0, 500));
+          resolve(null);
+          return;
+        }
+        console.log("[stt/whisper] pip3 install succeeded");
+
+        // Re-discover binary
+        invalidateCache();
+        const binary = await findWhisperBinary();
+        if (!binary) {
+          console.error("[stt/whisper] installed but binary not found in expected paths");
+          resolve(null);
+          return;
+        }
+
+        // Validate with --help
+        execFile(binary, ["--help"], { timeout: 10_000 }, (helpErr) => {
+          if (helpErr) {
+            console.error("[stt/whisper] binary found but --help failed:", helpErr.message);
+            resolve(null);
+          } else {
+            console.log(`[stt/whisper] validated binary at ${binary}`);
+            resolve(binary);
+          }
+        });
+      },
+    );
+  });
+}
+
+/**
+ * Warm the whisper model by running a tiny transcription.
+ * This forces the model download (~461MB for small).
+ */
+async function warmWhisperModel(binary: string, model: string): Promise<boolean> {
+  const warmupDir = join(homedir(), ".roundhouse", "whisper-warmup", randomBytes(4).toString("hex"));
+  mkdirSync(warmupDir, { recursive: true });
+
+  // Generate a tiny silent WAV file (1 second, 16kHz, mono, 16-bit)
+  const sampleRate = 16000;
+  const numSamples = sampleRate; // 1 second
+  const dataSize = numSamples * 2; // 16-bit = 2 bytes per sample
+  const buf = Buffer.alloc(44 + dataSize);
+  // WAV header
+  buf.write("RIFF", 0);
+  buf.writeUInt32LE(36 + dataSize, 4);
+  buf.write("WAVE", 8);
+  buf.write("fmt ", 12);
+  buf.writeUInt32LE(16, 16); // PCM format chunk size
+  buf.writeUInt16LE(1, 20);  // PCM format
+  buf.writeUInt16LE(1, 22);  // mono
+  buf.writeUInt32LE(sampleRate, 24);
+  buf.writeUInt32LE(sampleRate * 2, 28); // byte rate
+  buf.writeUInt16LE(2, 32);  // block align
+  buf.writeUInt16LE(16, 34); // bits per sample
+  buf.write("data", 36);
+  buf.writeUInt32LE(dataSize, 40);
+  // Data is all zeros (silence)
+
+  const wavPath = join(warmupDir, "silence.wav");
+  await writeFile(wavPath, buf);
+
+  console.log(`[stt/whisper] warming model '${model}' (may download ~461MB)...`);
+
+  return new Promise<boolean>((resolve) => {
+    execFile(
+      binary,
+      [wavPath, "--model", model, "--output_format", "json", "--output_dir", warmupDir],
+      {
+        timeout: 600_000, // 10 min for model download + first run
+        env: {
+          ...process.env,
+          PATH: `${join(homedir(), ".local", "bin")}:${process.env.PATH}`,
+        },
+      },
+      async (err) => {
+        // Clean up warmup files
+        try { await rm(warmupDir, { recursive: true }); } catch {}
+
+        if (err) {
+          console.warn(`[stt/whisper] model warmup failed: ${err.message}`);
+          resolve(false);
+        } else {
+          console.log(`[stt/whisper] model '${model}' ready`);
+          resolve(true);
+        }
+      },
+    );
+  });
+}
+
+// ── Provider ─────────────────────────────────────────
+
+/** Extended provider with install capability */
+export interface InstallableWhisperProvider extends SttProvider {
+  ensureInstalled(): Promise<boolean>;
+}
+
+// Singleton promises to prevent concurrent installs
+let installPromise: Promise<string | null> | null = null;
+let installFailed = false; // sticky failure to prevent retry spam
+
+export function createWhisperProvider(config: SttProviderConfig): InstallableWhisperProvider {
+  const model = (config.model as string) ?? "small";
+  const timeoutMs = config.timeoutMs ?? 30000;
+  const autoInstall = config.autoInstall === true; // explicit opt-in only
+  let modelWarmed = false;
+  let warmFailed = false; // sticky failure to prevent warmup retry spam
+  let warmPromise: Promise<boolean> | null = null;
+
+  const WHISPER_LANGS = new Set(["af","am","ar","as","az","ba","be","bg","bn","bo","br","bs","ca","cs","cy","da","de","el","en","es","et","eu","fa","fi","fo","fr","gl","gu","ha","haw","he","hi","hr","ht","hu","hy","id","is","it","ja","jw","ka","kk","km","kn","ko","la","lb","ln","lo","lt","lv","mg","mi","mk","ml","mn","mr","ms","mt","my","ne","nl","nn","no","oc","pa","pl","ps","pt","ro","ru","sa","sd","si","sk","sl","sn","so","sq","sr","su","sv","sw","ta","te","tg","th","tk","tl","tr","tt","uk","ur","uz","vi","yi","yo","yue","zh"]);
+
+  async function getBinary(): Promise<string | null> {
+    // Check if already available
+    const existing = await findWhisperBinary();
+    if (existing) return existing;
+
+    // Try auto-install
+    if (!autoInstall) return null;
+    if (installFailed) return null; // sticky failure — don't retry every message
+
+    // Singleton: join existing install or start new one
+    if (!installPromise) {
+      installPromise = installWhisperWithPip().then((result) => {
+        if (!result) installFailed = true;
+        return result;
+      }).finally(() => {
+        installPromise = null;
+      });
+    }
+    return installPromise;
+  }
+
+  return {
+    name: `whisper-${model}`,
+
+    canTranscribe(input: SttInput): boolean {
+      return input.mime.startsWith("audio/");
+    },
+
+    async ensureInstalled(): Promise<boolean> {
+      const binary = await getBinary();
+      if (!binary) return false;
+
+      // Warm model with singleton promise
+      if (!modelWarmed && !warmFailed) {
+        if (!warmPromise) {
+          warmPromise = (async () => {
+            // Check if model already cached
+            const modelDir = join(homedir(), ".cache", "whisper");
+            try {
+              const files = await readdir(modelDir);
+              if (files.some((f) => f.startsWith(model) && f.includes("."))) {
+                modelWarmed = true;
+                return true;
+              }
+            } catch {}
+
+            // Run warmup — catch everything so it never rejects
+            try {
+              const ok = await warmWhisperModel(binary, model);
+              if (!ok) warmFailed = true;
+              modelWarmed = ok;
+              return ok;
+            } catch (err) {
+              console.warn(`[stt/whisper] warmup error: ${(err as Error).message}`);
+              warmFailed = true;
+              modelWarmed = false;
+              return false;
+            }
+          })().finally(() => { warmPromise = null; });
+        }
+        await warmPromise;
+      }
+      return modelWarmed;
+    },
+
+    async transcribe(input: SttInput): Promise<TranscriptionResult> {
+      const binary = await getBinary();
+      if (!binary) {
+        throw new Error("whisper not available and auto-install failed");
+      }
+
+      const outputDir = join(homedir(), ".roundhouse", "whisper-tmp", randomBytes(6).toString("hex"));
+      mkdirSync(outputDir, { recursive: true });
+
+      const audioPath = input.localPath.startsWith("-") ? `./${input.localPath}` : input.localPath;
+
+      const args = [
+        audioPath,
+        "--model", model,
+        "--output_format", "json",
+        "--output_dir", outputDir,
+      ];
+
+      if (input.hint?.language && WHISPER_LANGS.has(input.hint.language)) {
+        args.push("--language", input.hint.language);
+      }
+
+      return new Promise<TranscriptionResult>((resolve, reject) => {
+        execFile(
+          binary,
+          args,
+          {
+            timeout: timeoutMs,
+            env: {
+              ...process.env,
+              PATH: `${join(homedir(), ".local", "bin")}:${process.env.PATH}`,
+            },
+          },
+          async (error, _stdout, stderr) => {
+            const cleanup = async () => {
+              try { await rm(outputDir, { recursive: true }); } catch {}
+            };
+
+            if (error) {
+              await cleanup();
+              reject(new Error(`whisper failed: ${error.message}`));
+              return;
+            }
+
+            try {
+              const files = await readdir(outputDir);
+              const jsonFile = files.find((f) => f.endsWith(".json"));
+              if (!jsonFile) {
+                await cleanup();
+                reject(new Error("whisper produced no JSON output"));
+                return;
+              }
+              const raw = await readFile(join(outputDir, jsonFile), "utf8");
+              const result = JSON.parse(raw);
+
+              await cleanup();
+
+              let language: string | undefined;
+              const langMatch = stderr.match(/Detected language:\s*(\w+)/);
+              if (langMatch) language = langMatch[1].toLowerCase();
+              if (result.language) language = result.language;
+
+              const text = (result.text ?? "").trim();
+              if (!text) {
+                reject(new Error("whisper returned empty transcript"));
+                return;
+              }
+
+              // Mark model as warmed after successful transcription
+              modelWarmed = true;
+
+              resolve({ text, language, approximate: true });
+            } catch (err) {
+              await cleanup();
+              reject(new Error(`whisper output parse failed: ${(err as Error).message}`));
+            }
+          },
+        );
+      });
+    },
+  };
+}

package/src/voice/stt-service.ts

@@ -0,0 +1,284 @@
+/**
+ * voice/stt-service.ts — Speech-to-text service
+ *
+ * Manages provider chain, timeouts, and graceful fallback.
+ * Never throws — returns null on all failures.
+ */
+
+import type { SttProvider, SttInput, SttConfig, AttachmentTranscript } from "./types";
+import type { MessageAttachment } from "../types";
+import { createWhisperProvider, type InstallableWhisperProvider } from "./providers/whisper";
+
+// Provider factory registry
+const PROVIDER_FACTORIES: Record<string, (config: any) => SttProvider> = {
+  whisper: createWhisperProvider,
+};
+
+export class SttService {
+  private providers: SttProvider[] = [];
+  private config: SttConfig;
+  private initPromise: Promise<void> | null = null;
+  private activeStt: Promise<void> = Promise.resolve(); // global concurrency: 1 at a time
+  private installNoticeSent = false;
+
+  constructor(config: SttConfig) {
+    this.config = config;
+  }
+
+  private async ensureInitialized(): Promise<void> {
+    if (!this.initPromise) {
+      this.initPromise = this.doInit().catch((err) => {
+        this.initPromise = null; // retry on next call
+        throw err;
+      });
+    }
+    await this.initPromise;
+  }
+
+  private async doInit(): Promise<void> {
+    for (const providerName of this.config.chain) {
+      const providerConfig = this.config.providers[providerName];
+      if (!providerConfig) {
+        console.warn(`[stt] provider "${providerName}" in chain but not configured, skipping`);
+        continue;
+      }
+
+      const type = providerConfig.type;
+      const factory = PROVIDER_FACTORIES[type];
+
+      if (!factory) {
+        console.warn(`[stt] unknown provider type "${type}", skipping`);
+        continue;
+      }
+
+      try {
+        // Pass autoInstall from service-level config into provider config
+        const mergedProviderConfig = {
+          ...providerConfig,
+          autoInstall: providerConfig.autoInstall ?? this.config.autoInstall ?? false,
+        };
+        this.providers.push(factory(mergedProviderConfig));
+        console.log(`[stt] loaded provider: ${providerName} (${type})`);
+      } catch (err) {
+        console.warn(`[stt] failed to create provider "${providerName}":`, (err as Error).message);
+      }
+    }
+
+    if (this.providers.length === 0) {
+      console.warn(`[stt] no providers available — transcription disabled`);
+    }
+  }
+
+  /**
+   * Prepare providers in background (install + warm model).
+   * Called from gateway.start() — non-blocking, never throws.
+   */
+  async prepareInBackground(): Promise<void> {
+    try {
+      await this.ensureInitialized();
+    } catch {
+      return;
+    }
+
+    for (const provider of this.providers) {
+      if ("ensureInstalled" in provider && typeof (provider as any).ensureInstalled === "function") {
+        try {
+          const installable = provider as InstallableWhisperProvider;
+          const ok = await installable.ensureInstalled();
+          if (ok) {
+            console.log(`[stt] ${provider.name} ready (installed + model warmed)`);
+          } else {
+            console.warn(`[stt] ${provider.name} not available after prepare`);
+          }
+        } catch (err) {
+          console.warn(`[stt] ${provider.name} prepare failed:`, (err as Error).message);
+        }
+      }
+    }
+  }
+
+  /** Should this attachment be auto-transcribed? */
+  shouldTranscribe(attachment: MessageAttachment): boolean {
+    if (!this.config.enabled || this.config.mode === "off") return false;
+
+    const auto = this.config.autoTranscribe ?? { voiceMessages: true, audioFiles: false, maxDurationSec: 120 };
+
+    // Only audio
+    if (attachment.mediaType !== "audio") return false;
+    if (!attachment.mime.startsWith("audio/")) return false;
+
+    // Voice messages (ogg/opus from Telegram) vs general audio files
+    const isVoiceMessage = attachment.mime === "audio/ogg" && attachment.name.endsWith(".ogg");
+    if (isVoiceMessage && auto.voiceMessages) return true;
+    if (!isVoiceMessage && auto.audioFiles) return true;
+
+    return false;
+  }
+
+  /**
+   * Try to transcribe an attachment using the provider chain.
+   * Returns null on all failures — never throws to callers.
+   */
+  async tryTranscribe(
+    attachment: MessageAttachment,
+    languageHint?: string,
+    notify?: (text: string) => Promise<void>,
+  ): Promise<AttachmentTranscript | null> {
+    try {
+      await this.ensureInitialized();
+    } catch (err) {
+      console.warn(`[stt] initialization failed:`, (err as Error).message);
+      return null;
+    }
+
+    if (this.providers.length === 0) return null;
+    if (!this.shouldTranscribe(attachment)) return null;
+
+    // Check duration limit using ffprobe
+    const maxDuration = this.config.autoTranscribe?.maxDurationSec ?? 120;
+    if (maxDuration > 0) {
+      try {
+        const duration = await getAudioDuration(attachment.localPath);
+        if (duration !== null && duration > maxDuration) {
+          console.log(`[stt] skipping ${attachment.name}: duration ${duration.toFixed(1)}s exceeds ${maxDuration}s limit`);
+          return null;
+        }
+      } catch {}
+    }
+
+    const input: SttInput = {
+      localPath: attachment.localPath,
+      mime: attachment.mime,
+      sizeBytes: attachment.sizeBytes,
+      hint: {
+        language: languageHint,
+        isVoiceMessage: attachment.mime === "audio/ogg",
+      },
+    };
+
+    const startTime = Date.now();
+
+    // Global concurrency limit: one transcription at a time to prevent CPU stampede
+    // Promise executor runs synchronously per spec, so release is always assigned before await
+    const prev = this.activeStt;
+    let release: () => void;
+    this.activeStt = new Promise<void>((r) => { release = r; });
+    await prev;
+
+    try {
+      for (const provider of this.providers) {
+        if (!provider.canTranscribe(input)) continue;
+
+        // Ensure provider is installed (with one-time user notification)
+        const installable = provider as InstallableWhisperProvider;
+        if (installable.ensureInstalled && typeof installable.ensureInstalled === "function") {
+          try {
+            const isReady = await installable.ensureInstalled();
+            if (!isReady) {
+              if (!this.installNoticeSent && notify) {
+                this.installNoticeSent = true;
+                try { await notify("🎤 Voice transcription not available. Whisper install or model download failed."); } catch {}
+              }
+              continue;
+            }
+          } catch {
+            continue;
+          }
+        }
+
+        try {
+          console.log(`[stt] trying ${provider.name} for ${attachment.name}...`);
+          const result = await provider.transcribe(input);
+          const durationMs = Date.now() - startTime;
+
+          console.log(`[stt] ${provider.name} succeeded in ${durationMs}ms: "${result.text.slice(0, 80)}"`);
+
+          return {
+            text: result.text,
+            provider: provider.name,
+            language: result.language,
+            confidence: result.confidence,
+            approximate: true,
+            status: "completed" as const,
+            durationMs,
+          };
+        } catch (err) {
+          console.warn(`[stt] ${provider.name} failed:`, (err as Error).message);
+          continue;
+        }
+      }
+
+      // All providers failed
+      return {
+        text: "",
+        provider: "none",
+        approximate: true,
+        status: "failed" as const,
+        error: "All STT providers failed",
+        durationMs: Date.now() - startTime,
+      };
+    } finally {
+      release!();
+    }
+  }
+}
+
+/**
+ * Enrich audio attachments with transcripts.
+ * Mutates the attachments array in-place.
+ */
+export async function enrichAttachmentsWithTranscripts(
+  attachments: MessageAttachment[],
+  sttService: SttService | null,
+  notify?: (text: string) => Promise<void>,
+): Promise<void> {
+  if (!sttService) return;
+
+  for (const att of attachments) {
+    try {
+      const transcript = await sttService.tryTranscribe(att, undefined, notify);
+      if (transcript) {
+        att.transcript = transcript;
+      }
+    } catch (err) {
+      console.error(`[stt] unexpected error transcribing ${att.name}:`, (err as Error).message);
+    }
+  }
+}
+
+/** Get audio duration using ffprobe. Returns null if ffprobe is unavailable. */
+async function getAudioDuration(filePath: string): Promise<number | null> {
+  const { execFile: exec } = await import("node:child_process");
+  return new Promise((resolve) => {
+    exec(
+      "ffprobe",
+      ["-i", filePath, "-show_entries", "format=duration", "-v", "quiet", "-of", "csv=p=0"],
+      { timeout: 5000 },
+      (error, stdout) => {
+        if (error) return resolve(null);
+        const dur = parseFloat(stdout.trim());
+        resolve(isNaN(dur) ? null : dur);
+      },
+    );
+  });
+}
+
+/** Default STT config */
+export const DEFAULT_STT_CONFIG: SttConfig = {
+  enabled: true,
+  mode: "on",
+  autoInstall: true,
+  chain: ["whisper"],
+  autoTranscribe: {
+    voiceMessages: true,
+    audioFiles: false,
+    maxDurationSec: 120,
+  },
+  providers: {
+    whisper: {
+      type: "whisper",
+      model: "small",
+      timeoutMs: 30000,
+    },
+  },
+};

package/src/voice/types.ts

@@ -0,0 +1,63 @@
+/**
+ * voice/types.ts — Shared types for voice STT/TTS
+ */
+
+// ── STT (Speech-to-Text) ────────────────────────────
+
+export interface SttProvider {
+  readonly name: string;
+  canTranscribe(input: SttInput): boolean;
+  transcribe(input: SttInput): Promise<TranscriptionResult>;
+}
+
+export interface SttInput {
+  localPath: string;
+  mime: string;
+  sizeBytes: number;
+  hint?: {
+    language?: string;
+    isVoiceMessage?: boolean;
+  };
+}
+
+export interface TranscriptionResult {
+  text: string;
+  language?: string;
+  confidence?: number;
+  approximate: true;
+}
+
+// ── Attachment transcript (stored on MessageAttachment) ──
+
+export interface AttachmentTranscript {
+  text: string;
+  provider: string;
+  language?: string;
+  confidence?: number;
+  approximate: true;
+  status: "completed" | "failed";
+  error?: string;
+  durationMs?: number;
+}
+
+// ── STT config ───────────────────────────────────────
+
+export interface SttProviderConfig {
+  type: string;
+  timeoutMs?: number;
+  autoInstall?: boolean;
+  [key: string]: unknown;
+}
+
+export interface SttConfig {
+  enabled: boolean;
+  mode: "on" | "off";
+  autoInstall?: boolean;
+  chain: string[];
+  autoTranscribe: {
+    voiceMessages: boolean;
+    audioFiles: boolean;
+    maxDurationSec: number;
+  };
+  providers: Record<string, SttProviderConfig>;
+}