daemora 1.0.1 → 1.0.3

package/src/utils/Embeddings.js

@@ -0,0 +1,79 @@
+/**
+ * Provider-agnostic embedding generation.
+ *
+ * Auto-detects the best available embedding provider (priority order):
+ *   1. OPENAI_API_KEY      → text-embedding-3-small  (512 dims)
+ *   2. GOOGLE_AI_API_KEY   → text-embedding-004       (768 dims)
+ *   3. OLLAMA_HOST         → nomic-embed-text         (768 dims, local/free)
+ *   4. None                → returns null (callers fall back to keyword search)
+ *
+ * Override with: EMBEDDING_PROVIDER=openai|google|ollama
+ * Override Ollama model with: OLLAMA_EMBED_MODEL=nomic-embed-text
+ *
+ * Note: vectors from different providers are NOT interchangeable.
+ * Callers (SkillLoader, memory.js) tag stored vectors with the provider name
+ * and skip vectors that don't match the current provider.
+ */
+
+import { embed } from "ai";
+
+/**
+ * Returns the currently active embedding provider name, or null if none available.
+ */
+export function getEmbeddingProvider() {
+  const override = process.env.EMBEDDING_PROVIDER?.toLowerCase();
+
+  if (override) {
+    if (override === "openai"  && process.env.OPENAI_API_KEY)    return "openai";
+    if (override === "google"  && process.env.GOOGLE_AI_API_KEY) return "google";
+    if (override === "ollama")                                    return "ollama";
+    return null;  // Override set but required key missing
+  }
+
+  // Auto-detect in priority order
+  if (process.env.OPENAI_API_KEY)    return "openai";
+  if (process.env.GOOGLE_AI_API_KEY) return "google";
+  if (process.env.OLLAMA_HOST)       return "ollama";
+  return null;
+}
+
+/**
+ * Generate a vector embedding for the given text using the best available provider.
+ * Returns null if no provider is configured - callers must fall back to keyword search.
+ *
+ * @param {string} text
+ * @returns {Promise<number[]|null>}
+ */
+export async function generateEmbedding(text) {
+  const provider = getEmbeddingProvider();
+  if (!provider) return null;
+
+  try {
+    let model;
+
+    if (provider === "openai") {
+      const { createOpenAI } = await import("@ai-sdk/openai");
+      const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
+      // 512 dims = 3x smaller than default 1536, minimal quality loss for recall tasks
+      model = openai.embedding("text-embedding-3-small", { dimensions: 512 });
+
+    } else if (provider === "google") {
+      const { createGoogleGenerativeAI } = await import("@ai-sdk/google");
+      const google = createGoogleGenerativeAI({ apiKey: process.env.GOOGLE_AI_API_KEY });
+      model = google.textEmbeddingModel("text-embedding-004");  // 768 dims
+
+    } else if (provider === "ollama") {
+      const { ollama } = await import("ollama-ai-provider");
+      const modelName = process.env.OLLAMA_EMBED_MODEL || "nomic-embed-text";
+      model = ollama.embedding(modelName);  // typically 768 dims
+    }
+
+    if (!model) return null;
+
+    const { embedding } = await embed({ model, value: text.slice(0, 8000) });
+    return embedding;
+
+  } catch {
+    return null;
+  }
+}

package/src/voice/VoiceSessionManager.js

@@ -0,0 +1,170 @@
+/**
+ * VoiceSessionManager — in-memory state for active interactive voice calls.
+ *
+ * Each session bridges two async tracks:
+ *   - The agent loop (calls listen/speak/end as tool calls)
+ *   - Twilio webhooks (hits /voice/input when caller speaks, /voice/wait to fetch agent reply)
+ *
+ * Promise-based signalling lets the agent's `listen` call block cleanly until
+ * the caller speaks, without polling.
+ */
+
+import { randomBytes } from "node:crypto";
+
+const SESSION_TTL_MS = 2 * 60 * 60 * 1000; // prune sessions older than 2 hours
+
+class VoiceSession {
+  constructor({ sessionId, callSid, greeting }) {
+    this.id = sessionId;
+    this.callSid = callSid;
+    this.status = "ringing";       // ringing | in-progress | ended
+    this.greeting = greeting || null;
+    this.transcript = [];          // [{ role: "caller"|"agent", text, timestamp }]
+    this.createdAt = Date.now();
+    this.endedAt = null;
+
+    // Pending response the agent queued (text | "__HANGUP__" | null)
+    this._pendingResponse = null;
+
+    // Resolvers for agent's `listen` wait
+    this._callerInputResolve = null;
+    this._callerInputReject = null;
+
+    // Resolve for the webhook's `wait` poll (so it knows a response is ready)
+    this._responseReadyResolve = null;
+  }
+
+  /** Called by /voice/answer once Twilio dials and connects */
+  markConnected() {
+    this.status = "in-progress";
+  }
+
+  /** Called by /voice/input when Twilio STT delivers caller speech */
+  receiveCallerInput(text) {
+    const entry = { role: "caller", text, timestamp: new Date().toISOString() };
+    this.transcript.push(entry);
+    console.log(`[VoiceSession:${this.id}] Caller said: "${text}"`);
+
+    if (this._callerInputResolve) {
+      this._callerInputResolve(text);
+      this._callerInputResolve = null;
+      this._callerInputReject = null;
+    }
+  }
+
+  /** Called by the agent's speak/end tool action */
+  setAgentResponse(textOrSignal) {
+    this._pendingResponse = textOrSignal;
+
+    if (textOrSignal !== "__HANGUP__") {
+      this.transcript.push({ role: "agent", text: textOrSignal, timestamp: new Date().toISOString() });
+    }
+
+    // Wake up the /voice/wait poll immediately
+    if (this._responseReadyResolve) {
+      this._responseReadyResolve();
+      this._responseReadyResolve = null;
+    }
+
+    console.log(`[VoiceSession:${this.id}] Agent queued: "${textOrSignal}"`);
+  }
+
+  /**
+   * Agent tool `listen` calls this — blocks until caller speaks or timeout.
+   * @returns {Promise<string>} caller's spoken text
+   */
+  waitForCallerInput(timeoutMs = 120_000) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._callerInputResolve = null;
+        this._callerInputReject = null;
+        reject(new Error("Timed out waiting for caller input (caller may have hung up)"));
+      }, timeoutMs);
+
+      this._callerInputResolve = (text) => { clearTimeout(timer); resolve(text); };
+      this._callerInputReject = (err) => { clearTimeout(timer); reject(err); };
+    });
+  }
+
+  /**
+   * /voice/wait calls this to block until the agent queues a reply.
+   * Twilio expects a response quickly so we use a short timeout (8s) and fall
+   * back to a <Pause>+<Redirect> loop when the agent hasn't responded yet.
+   */
+  waitForAgentResponse(timeoutMs = 8_000) {
+    if (this._pendingResponse !== null) {
+      return Promise.resolve(); // already ready
+    }
+    return new Promise((resolve) => {
+      const timer = setTimeout(resolve, timeoutMs); // resolve (don't reject) on timeout
+      this._responseReadyResolve = () => { clearTimeout(timer); resolve(); };
+    });
+  }
+
+  /** Consume and return the pending response, clearing it */
+  consumeResponse() {
+    const r = this._pendingResponse;
+    this._pendingResponse = null;
+    return r;
+  }
+
+  /** Mark session as ended */
+  end() {
+    this.status = "ended";
+    this.endedAt = Date.now();
+    // Reject any waiting agent listen call so it doesn't hang forever
+    if (this._callerInputReject) {
+      this._callerInputReject(new Error("Call ended"));
+      this._callerInputResolve = null;
+      this._callerInputReject = null;
+    }
+  }
+}
+
+// ─── Manager (singleton) ───────────────────────────────────────────────────────
+
+class VoiceSessionManager {
+  constructor() {
+    this.sessions = new Map(); // sessionId → VoiceSession
+    // Prune dead sessions every 30 minutes
+    setInterval(() => this._prune(), 30 * 60 * 1000);
+  }
+
+  create({ callSid, greeting } = {}) {
+    const sessionId = "vc_" + randomBytes(6).toString("hex");
+    const session = new VoiceSession({ sessionId, callSid, greeting });
+    this.sessions.set(sessionId, session);
+    console.log(`[VoiceSessionManager] Created session ${sessionId} for call ${callSid}`);
+    return session;
+  }
+
+  get(sessionId) {
+    return this.sessions.get(sessionId) || null;
+  }
+
+  /** Look up session by Twilio call SID (used by status callbacks) */
+  getBySid(callSid) {
+    for (const session of this.sessions.values()) {
+      if (session.callSid === callSid) return session;
+    }
+    return null;
+  }
+
+  delete(sessionId) {
+    this.sessions.delete(sessionId);
+  }
+
+  _prune() {
+    const now = Date.now();
+    for (const [id, session] of this.sessions) {
+      if (now - session.createdAt > SESSION_TTL_MS) {
+        console.log(`[VoiceSessionManager] Pruning expired session ${id}`);
+        session.end();
+        this.sessions.delete(id);
+      }
+    }
+  }
+}
+
+const voiceSessionManager = new VoiceSessionManager();
+export default voiceSessionManager;

package/src/voice/VoiceWebhook.js

@@ -0,0 +1,188 @@
+/**
+ * VoiceWebhook — Express router for Twilio voice call webhooks.
+ *
+ * Twilio calls these endpoints during the lifecycle of an active call:
+ *
+ *   POST /voice/answer/:sessionId    — call connected, return opening TwiML
+ *   POST /voice/input/:sessionId     — caller finished speaking (SpeechResult)
+ *   POST /voice/wait/:sessionId      — poll for agent's next reply
+ *   POST /voice/status/:sessionId    — call status change (completed/failed/busy)
+ *
+ * The agent talks to the call via VoiceSessionManager (not via these routes).
+ * These routes are only for Twilio ↔ Daemora signalling.
+ */
+
+import { Router } from "express";
+import voiceSessionManager from "./VoiceSessionManager.js";
+
+const router = Router();
+
+// Twilio sends form-encoded bodies — parse them for voice routes
+import { urlencoded } from "express";
+router.use(urlencoded({ extended: false }));
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+// ── Voice quality + latency config ────────────────────────────────────────────
+// Polly.Joanna = Amazon Polly neural voice via Twilio — high quality, low latency.
+// Use "alice" as fallback (built-in Twilio TTS, slightly lower quality but zero extra cost).
+const VOICE    = process.env.VOICE_TTS_VOICE    || "Polly.Joanna";
+const LANGUAGE = process.env.VOICE_TTS_LANGUAGE || "en-US";
+
+// How long Twilio waits for the caller to start speaking (seconds).
+// 4s is fast enough to feel responsive; increase if callers complain of being cut off.
+const SPEECH_TIMEOUT_START = process.env.VOICE_SPEECH_TIMEOUT || "4";
+
+// How long Twilio waits after caller stops speaking before finalising (seconds).
+// "auto" = Twilio's ML-based end-of-speech detector — fastest + most accurate option.
+const SPEECH_TIMEOUT_END   = "auto";
+
+// How often we poll for the agent's reply while the caller is on hold (ms).
+// Lower = snappier response, but more HTTP round-trips. 500ms is a good balance.
+const POLL_PAUSE_MS = parseInt(process.env.VOICE_POLL_INTERVAL_MS || "500", 10);
+const POLL_PAUSE_S  = Math.max(1, Math.round(POLL_PAUSE_MS / 1000)); // TwiML needs whole seconds
+// ──────────────────────────────────────────────────────────────────────────────
+
+function twiml(content) {
+  return `<?xml version="1.0" encoding="UTF-8"?><Response>${content}</Response>`;
+}
+
+function escapeXml(str) {
+  return (str || "")
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function sayAndListen(sessionId, message) {
+  // <Gather> wraps <Say> so caller can barge-in (interrupt the agent mid-sentence).
+  // speechTimeout="auto" uses Twilio's ML end-of-speech — much faster than a fixed delay.
+  // bargeIn="true" lets the caller speak while agent is still talking (reduces turn latency).
+  return twiml(
+    `<Gather input="speech" timeout="${SPEECH_TIMEOUT_START}" speechTimeout="${SPEECH_TIMEOUT_END}" ` +
+    `bargeIn="true" action="/voice/input/${sessionId}" method="POST">` +
+    `<Say voice="${VOICE}" language="${LANGUAGE}">${escapeXml(message)}</Say>` +
+    `</Gather>` +
+    // Fallback if no speech detected — re-poll the agent (in case it has a follow-up)
+    `<Redirect method="POST">/voice/wait/${sessionId}</Redirect>`
+  );
+}
+
+function waitAndPoll(sessionId) {
+  // Hold music is better UX than silence but adds latency — skip it.
+  // Use the shortest TwiML pause Twilio supports (1s) and redirect.
+  // The actual responsiveness is determined by how fast the agent queues its reply
+  // (session.waitForAgentResponse uses 8s internal timeout, which is polled at 500ms).
+  return twiml(
+    `<Pause length="${POLL_PAUSE_S}"/>` +
+    `<Redirect method="POST">/voice/wait/${sessionId}</Redirect>`
+  );
+}
+
+// ─── Routes ───────────────────────────────────────────────────────────────────
+
+/**
+ * POST /voice/answer/:sessionId
+ * Twilio hits this immediately when the outbound call is answered.
+ * We mark the session connected and speak the greeting (if any).
+ */
+router.post("/answer/:sessionId", (req, res) => {
+  const session = voiceSessionManager.get(req.params.sessionId);
+  if (!session) {
+    // Unknown session — hang up gracefully
+    res.type("text/xml").send(twiml("<Hangup/>"));
+    return;
+  }
+
+  session.markConnected();
+  console.log(`[VoiceWebhook] Call answered for session ${session.id}`);
+
+  const greeting = session.greeting || "Hello, this is your AI assistant. How can I help you?";
+  res.type("text/xml").send(sayAndListen(session.id, greeting));
+});
+
+/**
+ * POST /voice/input/:sessionId
+ * Twilio posts the caller's transcribed speech here (SpeechResult field).
+ * We store it in the session and redirect to /voice/wait while the agent thinks.
+ */
+router.post("/input/:sessionId", (req, res) => {
+  const session = voiceSessionManager.get(req.params.sessionId);
+  if (!session || session.status === "ended") {
+    res.type("text/xml").send(twiml("<Hangup/>"));
+    return;
+  }
+
+  const speechResult = req.body?.SpeechResult || "";
+  const confidence   = req.body?.Confidence   || "?";
+
+  if (speechResult.trim()) {
+    console.log(`[VoiceWebhook] Caller spoke (confidence ${confidence}): "${speechResult}"`);
+    session.receiveCallerInput(speechResult.trim());
+  } else {
+    console.log(`[VoiceWebhook] No speech detected — re-polling`);
+  }
+
+  // Park the call while the agent processes the input
+  res.type("text/xml").send(waitAndPoll(session.id));
+});
+
+/**
+ * POST /voice/wait/:sessionId
+ * Polling endpoint. Agent queues its reply via session.setAgentResponse().
+ * We wait up to 8s for a reply; if none, return pause+redirect (1-second loop).
+ */
+router.post("/wait/:sessionId", async (req, res) => {
+  const session = voiceSessionManager.get(req.params.sessionId);
+  if (!session || session.status === "ended") {
+    res.type("text/xml").send(twiml("<Hangup/>"));
+    return;
+  }
+
+  // Wait up to 8s for the agent to queue a reply
+  await session.waitForAgentResponse(8_000);
+
+  const response = session.consumeResponse();
+
+  if (response === null) {
+    // Agent still thinking — keep the caller on hold
+    res.type("text/xml").send(waitAndPoll(session.id));
+    return;
+  }
+
+  if (response === "__HANGUP__") {
+    session.end();
+    voiceSessionManager.delete(session.id);
+    console.log(`[VoiceWebhook] Session ${session.id} ended by agent`);
+    res.type("text/xml").send(twiml("<Say>Goodbye.</Say><Hangup/>"));
+    return;
+  }
+
+  // Agent reply — speak it and listen for caller's next utterance
+  res.type("text/xml").send(sayAndListen(session.id, response));
+});
+
+/**
+ * POST /voice/status/:sessionId
+ * Twilio status callback — tracks call lifecycle (ringing → in-progress → completed).
+ * If call ends unexpectedly (caller hangs up), we clean up the session.
+ */
+router.post("/status/:sessionId", (req, res) => {
+  const { CallStatus, CallSid } = req.body || {};
+  const session = voiceSessionManager.get(req.params.sessionId);
+
+  console.log(`[VoiceWebhook] Status callback: ${CallSid} → ${CallStatus}`);
+
+  if (session && (CallStatus === "completed" || CallStatus === "failed" || CallStatus === "busy" || CallStatus === "no-answer")) {
+    if (session.status !== "ended") {
+      session.end();
+      voiceSessionManager.delete(session.id);
+      console.log(`[VoiceWebhook] Session ${session.id} closed via status callback (${CallStatus})`);
+    }
+  }
+
+  res.status(204).end();
+});
+
+export default router;