ava-engine 0.0.0-stage → 0.2.0

package/lib/kokoro-model.mjs

@@ -0,0 +1,51 @@
+// The offline Kokoro voice model: where it's cached, whether it's there, and
+// loading it with download progress. Shared by the server and the setup wizard.
+//
+// It's cached under the models folder (~/.ava-engine/models/kokoro for the CLI),
+// not inside node_modules, so it survives `npx` updates instead of downloading
+// again after every new version.
+
+import { existsSync, readdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const KOKORO_MODEL = process.env.KOKORO_MODEL || "onnx-community/Kokoro-82M-v1.0-ONNX";
+export const KOKORO_DTYPE = process.env.KOKORO_DTYPE || "q8";
+export const KOKORO_SIZE = "~90 MB";
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+export function kokoroCacheDir() {
+  return process.env.KOKORO_CACHE_DIR || join(process.env.AVA_MODELS_DIR || join(ROOT, "models"), "kokoro");
+}
+
+/** True once the model's weights are on disk (no network needed to start). */
+export function kokoroInstalled(dir = kokoroCacheDir()) {
+  const onnx = join(dir, ...KOKORO_MODEL.split("/"), "onnx");
+  try { return existsSync(onnx) && readdirSync(onnx).some((f) => f.endsWith(".onnx")); } catch { return false; }
+}
+
+/**
+ * Load Kokoro, downloading it first if needed.
+ * onProgress({ loaded, total, pct }) reports the overall download.
+ */
+export async function loadKokoro({ onProgress } = {}) {
+  const { env } = await import("@huggingface/transformers");
+  env.cacheDir = kokoroCacheDir();
+  const { KokoroTTS } = await import("kokoro-js");
+  const files = new Map(); // file → { loaded, total }
+  // Count only the large files (the weights). The small config/tokenizer files
+  // finish first and would make the bar jump to 100% and back.
+  const progress_callback = (e) => {
+    if (!onProgress || e.status !== "progress" || !(e.total > 1_000_000)) return;
+    files.set(e.file, { loaded: e.loaded, total: e.total });
+    let loaded = 0, total = 0;
+    for (const f of files.values()) { loaded += f.loaded; total += f.total; }
+    onProgress({ loaded, total, pct: Math.min(100, Math.floor((loaded / total) * 100)) });
+  };
+  // transformers.js warns about a missing content-length on every download; it's
+  // harmless and would break the setup wizard's progress bar, so hide just that line.
+  const warn = console.warn;
+  console.warn = (...args) => { if (!String(args[0]).includes("content-length")) warn(...args); };
+  try { return await KokoroTTS.from_pretrained(KOKORO_MODEL, { dtype: KOKORO_DTYPE, device: "cpu", progress_callback }); }
+  finally { console.warn = warn; }
+}

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 };
+}