ava-engine 0.0.0-stage → 0.1.0

package/lib/fetch-models.mjs

@@ -0,0 +1,104 @@
+// Offline speech-to-text model downloads (sherpa-onnx). Dependency-free so the
+// Dockerfile and the CLI can both use it:
+//
+//   node lib/fetch-models.mjs [english-small|english|multilingual|all] [--dir <path>]
+//
+// Archives are extracted with the system `tar` (macOS, Linux and Windows 10+).
+
+import { createWriteStream, existsSync, mkdirSync, renameSync, rmSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { spawn } from "node:child_process";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { fileURLToPath } from "node:url";
+
+const BASE = "https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models";
+
+/** What the CLI offers. `files` are fetched in order; `dir` marks a pack as installed. */
+export const MODEL_PACKS = {
+  "english-small": {
+    label: "English, fast", size: "122 MB",
+    hint: "Streaming English with live captions. A good default.",
+    files: [{ name: "sherpa-onnx-streaming-zipformer-en-20M-2023-02-17.tar.bz2", dir: "sherpa-onnx-streaming-zipformer-en-20M-2023-02-17" }],
+  },
+  english: {
+    label: "English, most accurate", size: "296 MB",
+    hint: "The larger streaming English model. Used instead of the small one when both are installed.",
+    files: [{ name: "sherpa-onnx-streaming-zipformer-en-2023-06-26.tar.bz2", dir: "sherpa-onnx-streaming-zipformer-en-2023-06-26" }],
+  },
+  multilingual: {
+    label: "Multilingual (zh/en/ja/ko/yue)", size: "1 GB",
+    hint: "SenseVoice with voice activity detection. Captions appear when the speaker pauses.",
+    files: [
+      { name: "sherpa-onnx-sense-voice-zh-en-ja-ko-yue-2024-07-17.tar.bz2", dir: "sherpa-onnx-sense-voice-zh-en-ja-ko-yue-2024-07-17" },
+      { name: "silero_vad.onnx", file: "silero_vad.onnx" },
+    ],
+  },
+};
+
+export function packInstalled(pack, dir) {
+  return MODEL_PACKS[pack].files.every((f) => existsSync(join(dir, f.dir || f.file)));
+}
+
+export function installedPacks(dir) {
+  return Object.keys(MODEL_PACKS).filter((p) => packInstalled(p, dir));
+}
+
+function untar(archive, cwd) {
+  return new Promise((res, rej) => {
+    const p = spawn("tar", ["xjf", archive], { cwd, stdio: ["ignore", "ignore", "pipe"] });
+    let err = "";
+    p.stderr.on("data", (d) => { err += d; });
+    p.on("error", (e) => rej(new Error(`couldn't run tar: ${e.message}`)));
+    p.on("close", (code) => (code === 0 ? res() : rej(new Error(`tar failed (${code}): ${err.trim()}`))));
+  });
+}
+
+async function download(url, dest, onProgress) {
+  const res = await fetch(url, { redirect: "follow" });
+  if (!res.ok || !res.body) throw new Error(`download failed: HTTP ${res.status} for ${url}`);
+  const total = Number(res.headers.get("content-length")) || 0;
+  let done = 0;
+  const body = Readable.fromWeb(res.body);
+  body.on("data", (c) => { done += c.length; onProgress?.(done, total); });
+  const tmp = dest + ".part";
+  await pipeline(body, createWriteStream(tmp));
+  renameSync(tmp, dest); // only a complete download gets the real name
+}
+
+/**
+ * Download and unpack one model pack into `dir`. Skips files already present.
+ * onProgress({ file, done, total, phase: "download" | "extract" | "skip" })
+ */
+export async function fetchPack(pack, dir, onProgress) {
+  const spec = MODEL_PACKS[pack];
+  if (!spec) throw new Error(`unknown model pack "${pack}" (choose: ${Object.keys(MODEL_PACKS).join(", ")})`);
+  mkdirSync(dir, { recursive: true });
+  for (const f of spec.files) {
+    const target = join(dir, f.dir || f.file);
+    if (existsSync(target)) { onProgress?.({ file: f.name, phase: "skip" }); continue; }
+    const dest = join(dir, f.name);
+    await download(`${BASE}/${f.name}`, dest, (done, total) => onProgress?.({ file: f.name, phase: "download", done, total }));
+    if (f.dir) {
+      onProgress?.({ file: f.name, phase: "extract" });
+      try { await untar(f.name, dir); } finally { rmSync(dest, { force: true }); }
+    }
+  }
+}
+
+// ── command line ──
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const args = process.argv.slice(2);
+  const di = args.indexOf("--dir");
+  const dir = resolve(di >= 0 ? args.splice(di, 2)[1] : join(dirname(fileURLToPath(import.meta.url)), "..", "models"));
+  const wanted = args[0] === "all" ? ["english", "multilingual"] : args.length ? args : ["english-small"];
+  for (const pack of wanted) {
+    let last = -1;
+    await fetchPack(pack, dir, (p) => {
+      if (p.phase === "skip") console.log(`✓ ${p.file} (already present)`);
+      else if (p.phase === "extract") console.log(`  unpacking ${p.file}…`);
+      else if (p.total) { const pct = Math.floor((p.done / p.total) * 100); if (pct !== last && pct % 10 === 0) { last = pct; console.log(`↓ ${p.file} ${pct}%`); } }
+    });
+  }
+  console.log(`Models are in ${dir}`);
+}

package/lib/guard.mjs

@@ -0,0 +1,92 @@
+// Abuse protection for a publicly reachable server. Every /api call can spend
+// the operator's model/voice credit, so a deploy should never be wide open.
+//
+//   ACCESS_PASSWORD  optional. When set, the app, specialist console, /api/* and
+//                    the WebSockets require it (HTTP Basic auth, then a cookie so
+//                    WebSocket upgrades are covered too). The landing page and
+//                    static assets stay public.
+//   TRUST_PROXY=1    take the client IP from Fly-Client-IP / X-Forwarded-For
+//                    (only behind a proxy you control — the header is spoofable).
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+const PASSWORD = process.env.ACCESS_PASSWORD || "";
+const TRUST_PROXY = process.env.TRUST_PROXY === "1";
+export const AUTH_ENABLED = !!PASSWORD;
+
+const COOKIE = "ava_auth";
+const cookieValue = PASSWORD ? createHmac("sha256", PASSWORD).update("ava-access-v1").digest("hex") : "";
+
+function safeEqual(a, b) {
+  const x = Buffer.from(String(a)), y = Buffer.from(String(b));
+  return x.length === y.length && timingSafeEqual(x, y);
+}
+
+function readCookie(req, name) {
+  for (const part of String(req.headers.cookie || "").split(";")) {
+    const i = part.indexOf("=");
+    if (i > 0 && part.slice(0, i).trim() === name) return part.slice(i + 1).trim();
+  }
+  return null;
+}
+
+/** True if the request carries a valid password (Basic auth) or auth cookie. */
+export function isAuthorized(req) {
+  if (!AUTH_ENABLED) return true;
+  const c = readCookie(req, COOKIE);
+  if (c && safeEqual(c, cookieValue)) return true;
+  const h = String(req.headers.authorization || "");
+  if (h.startsWith("Basic ")) {
+    const pass = Buffer.from(h.slice(6), "base64").toString("utf8").split(":").slice(1).join(":");
+    return safeEqual(pass, PASSWORD);
+  }
+  return false;
+}
+
+/** Headers that ask the browser for the password. */
+export function challengeHeaders() {
+  return { "WWW-Authenticate": 'Basic realm="Ava", charset="UTF-8"' };
+}
+
+/** Set-Cookie header that remembers a successful login (so WebSockets pass). */
+export function authCookieHeader(req) {
+  if (!AUTH_ENABLED || readCookie(req, COOKIE) === cookieValue) return {};
+  const secure = TRUST_PROXY || req.socket.encrypted ? "; Secure" : "";
+  return { "Set-Cookie": `${COOKIE}=${cookieValue}; Path=/; HttpOnly; SameSite=Strict; Max-Age=43200${secure}` };
+}
+
+export function clientIp(req) {
+  if (TRUST_PROXY) {
+    const fly = req.headers["fly-client-ip"];
+    if (fly) return String(fly);
+    const xff = req.headers["x-forwarded-for"];
+    if (xff) return String(xff).split(",")[0].trim();
+  }
+  return req.socket.remoteAddress || "?";
+}
+
+/** Reject cross-site WebSocket upgrades (browsers always send Origin). */
+export function sameOrigin(req) {
+  const origin = req.headers.origin;
+  if (!origin) return true; // non-browser client; still subject to auth
+  try { return new URL(origin).host === req.headers.host; } catch { return false; }
+}
+
+/**
+ * Fixed-window rate limiter: limiter("turn", 120, 60_000)(ip) → true if allowed.
+ * Buckets are swept as they expire, so memory stays bounded by active clients.
+ */
+export function limiter(name, max, windowMs) {
+  const hits = new Map();
+  setInterval(() => { const now = Date.now(); for (const [k, v] of hits) if (now >= v.reset) hits.delete(k); }, windowMs).unref();
+  const allow = (key) => {
+    const now = Date.now();
+    let b = hits.get(key);
+    if (!b || now >= b.reset) { b = { n: 0, reset: now + windowMs }; hits.set(key, b); }
+    b.n += 1;
+    return b.n <= max;
+  };
+  /** True while `key` is over the limit, without counting a new hit. */
+  allow.blocked = (key) => { const b = hits.get(key); return !!b && Date.now() < b.reset && b.n >= max; };
+  return allow;
+}

package/lib/models.mjs

@@ -0,0 +1,47 @@
+// Central model config. Override any of these via env (see .env.example).
+// Slugs are OpenRouter model ids. Change freely — the UI shows whatever is set.
+
+export const MODELS = {
+  talker:     process.env.MODEL_TALKER     || "meta-llama/llama-3.3-70b-instruct", // the SPOKEN reply — latency-critical; on Groq ~0.2s TTFT (vs ~0.7s on gemini-flash-lite)
+  perception: process.env.MODEL_PERCEPTION || "google/gemini-2.5-flash",
+  planner:    process.env.MODEL_PLANNER    || "anthropic/claude-sonnet-4.5",
+  intent:     process.env.MODEL_INTENT     || "google/gemini-2.5-flash-lite",
+};
+
+// Per-role provider routing (OpenRouter). Only the talker is latency-critical —
+// it's the reply the user actually hears — so we prefer Groq's very low
+// time-to-first-token. allow_fallbacks keeps replies working (just slower) if
+// Groq is briefly unavailable. Set TALKER_PROVIDER=auto to let OpenRouter pick.
+export const PROVIDER = {
+  talker: process.env.TALKER_PROVIDER === "auto" ? undefined
+    : { order: [process.env.TALKER_PROVIDER || "groq"], allow_fallbacks: true },
+  // Perception (vision) is on the turn's hot path when the screen changed, so it
+  // wants a fast provider too. Only pinned when PERCEPTION_PROVIDER is set (the
+  // default vision model may not be served by that provider).
+  perception: process.env.PERCEPTION_PROVIDER && process.env.PERCEPTION_PROVIDER !== "auto"
+    ? { order: [process.env.PERCEPTION_PROVIDER], allow_fallbacks: true } : undefined,
+};
+
+// Fallback price table ($ per 1M tokens) used only if OpenRouter doesn't
+// return a usage.cost for a call. Approximate; edit to taste. [in, out]
+export const PRICES = {
+  "google/gemini-2.5-flash":       [0.30, 2.50],
+  "google/gemini-2.5-flash-lite":  [0.10, 0.40],
+  "anthropic/claude-sonnet-4.5":   [3.00, 15.00],
+  "google/gemini-2.5-pro":         [1.25, 10.00],
+  "openai/gpt-4o-mini":            [0.15, 0.60],
+};
+
+export function estimateCost(model, promptTokens, completionTokens) {
+  const p = PRICES[model];
+  if (!p) return 0;
+  return (promptTokens / 1e6) * p[0] + (completionTokens / 1e6) * p[1];
+}
+
+// Friendly display label per role.
+export const ROLE_LABEL = {
+  talker: "Talker",
+  perception: "Perception",
+  planner: "Planner",
+  intent: "Intent",
+};

package/lib/openrouter.mjs

@@ -0,0 +1,153 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { estimateCost } from "./models.mjs";
+
+// The HTTP request a model call belongs to. When that client disconnects mid-turn,
+// its in-flight calls are aborted instead of spending tokens nobody will read.
+export const requestScope = new AsyncLocalStorage();
+function callSignal(ms) {
+  const client = requestScope.getStore()?.signal;
+  return client ? AbortSignal.any([AbortSignal.timeout(ms), client]) : AbortSignal.timeout(ms);
+}
+
+const OR_URL = "https://openrouter.ai/api/v1/chat/completions";
+export const MOCK = !process.env.OPENROUTER_API_KEY;
+// Optional app attribution on openrouter.ai (https://openrouter.ai/docs/app-attribution).
+const ATTRIBUTION = {
+  ...(process.env.OPENROUTER_REFERER ? { "HTTP-Referer": process.env.OPENROUTER_REFERER } : {}),
+  "X-Title": process.env.OPENROUTER_TITLE || "Ava",
+};
+// Hard caps so one hung upstream call can never freeze the observe loop or a turn.
+const CHAT_TIMEOUT_MS = 30_000;
+const STREAM_TIMEOUT_MS = 60_000;
+
+// Rough token estimate for mock mode + for context-size display.
+export function estTokens(x) {
+  if (x == null) return 0;
+  if (typeof x === "string") return Math.ceil(x.length / 4);
+  // OpenAI-style content array: text parts by length, image parts flat ~258/tile.
+  if (Array.isArray(x)) {
+    let t = 0;
+    for (const p of x) {
+      if (p?.type === "text") t += Math.ceil((p.text || "").length / 4);
+      else if (p?.type === "image_url") t += 900; // ~one downscaled screen frame
+    }
+    return t;
+  }
+  return Math.ceil(JSON.stringify(x).length / 4);
+}
+
+function messagesTokens(messages) {
+  return messages.reduce((s, m) => s + estTokens(m.content) + 4, 0);
+}
+
+/**
+ * One chat completion. Returns:
+ *   { text, model, role, promptTokens, completionTokens, cost, latencyMs, cached }
+ * In MOCK mode returns a deterministic canned reply from `mock(messages)`.
+ */
+export async function chat({ model, role, messages, maxTokens = 350, temperature = 0.5, mock, provider }) {
+  const t0 = Date.now();
+
+  if (MOCK) {
+    const text = (mock ? mock(messages) : "[mock reply]");
+    const promptTokens = messagesTokens(messages);
+    const completionTokens = estTokens(text);
+    // Simulate realistic per-role latency so the UI feels real.
+    const base = role === "planner" ? 3200 : role === "perception" ? 520 : 620;
+    const latencyMs = base + Math.round((Math.random() - 0.5) * 220);
+    await new Promise((r) => setTimeout(r, Math.min(latencyMs, 900))); // don't actually wait the full planner time
+    return {
+      text, model, role, promptTokens, completionTokens,
+      cost: estimateCost(model, promptTokens, completionTokens),
+      latencyMs, mocked: true,
+    };
+  }
+
+  const body = {
+    model,
+    messages,
+    max_tokens: maxTokens,
+    temperature,
+    usage: { include: true },
+    ...(provider ? { provider } : {}),
+  };
+  const res = await fetch(OR_URL, {
+    method: "POST",
+    headers: {
+      "Authorization": `Bearer ${process.env.OPENROUTER_API_KEY}`,
+      "Content-Type": "application/json",
+      ...ATTRIBUTION,
+    },
+    body: JSON.stringify(body),
+    signal: callSignal(CHAT_TIMEOUT_MS),
+  });
+
+  const latencyMs = Date.now() - t0;
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    const err = new Error(`OpenRouter ${res.status}: ${detail.slice(0, 300)}`);
+    err.status = res.status;
+    throw err;
+  }
+  const data = await res.json();
+  const choice = data.choices?.[0];
+  const text = choice?.message?.content ?? "";
+  const u = data.usage || {};
+  const promptTokens = u.prompt_tokens ?? 0;
+  const completionTokens = u.completion_tokens ?? 0;
+  const cost = typeof u.cost === "number" ? u.cost : estimateCost(model, promptTokens, completionTokens);
+  return { text, model, role, promptTokens, completionTokens, cost, latencyMs, mocked: false };
+}
+
+/**
+ * Streaming chat completion. Calls onDelta(textChunk) as tokens arrive.
+ * Returns the same usage shape as chat() once complete.
+ */
+export async function chatStream({ model, role, messages, maxTokens = 220, temperature = 0.5, mock, onDelta, provider }) {
+  const t0 = Date.now();
+
+  if (MOCK) {
+    const text = mock ? mock(messages) : "[mock reply]";
+    for (const w of text.match(/\S+\s*/g) || [text]) { onDelta(w); await new Promise((r) => setTimeout(r, 28)); }
+    const promptTokens = messagesTokens(messages), completionTokens = estTokens(text);
+    return { text, model, role, promptTokens, completionTokens, cost: estimateCost(model, promptTokens, completionTokens), latencyMs: Date.now() - t0, mocked: true };
+  }
+
+  const res = await fetch(OR_URL, {
+    method: "POST",
+    headers: {
+      "Authorization": `Bearer ${process.env.OPENROUTER_API_KEY}`,
+      "Content-Type": "application/json",
+      ...ATTRIBUTION,
+    },
+    body: JSON.stringify({ model, messages, max_tokens: maxTokens, temperature, stream: true, usage: { include: true }, ...(provider ? { provider } : {}) }),
+    signal: callSignal(STREAM_TIMEOUT_MS),
+  });
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new Error(`OpenRouter ${res.status}: ${detail.slice(0, 300)}`);
+  }
+  const reader = res.body.getReader();
+  const dec = new TextDecoder();
+  let buf = "", text = "", usage = null;
+  for (;;) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buf += dec.decode(value, { stream: true });
+    let idx;
+    while ((idx = buf.indexOf("\n")) >= 0) {
+      const line = buf.slice(0, idx).trim(); buf = buf.slice(idx + 1);
+      if (!line.startsWith("data:")) continue;
+      const d = line.slice(5).trim();
+      if (d === "[DONE]") continue;
+      let j; try { j = JSON.parse(d); } catch { continue; }
+      const delta = j.choices?.[0]?.delta?.content;
+      if (delta) { text += delta; onDelta(delta); }
+      if (j.usage) usage = j.usage;
+    }
+  }
+  const promptTokens = usage?.prompt_tokens ?? 0;
+  const completionTokens = usage?.completion_tokens ?? 0;
+  const cost = typeof usage?.cost === "number" ? usage.cost : estimateCost(model, promptTokens, completionTokens);
+  return { text, model, role, promptTokens, completionTokens, cost, latencyMs: Date.now() - t0, mocked: false };
+}