heyhank 0.1.0 → 0.2.0

package/server/vector-store.ts

@@ -0,0 +1,210 @@
+// ─── Vector Store ───────────────────────────────────────────────────────────
+// Wraps vectra LocalIndex for local semantic vector storage + migration from old Notes.
+
+import { LocalIndex } from "vectra";
+import { join } from "node:path";
+import { existsSync, writeFileSync, readFileSync, mkdirSync } from "node:fs";
+import { HEYHANK_HOME } from "./paths.js";
+
+const INDEX_PATH = join(HEYHANK_HOME, "memory", "vector-index");
+const MIGRATED_MARKER = join(HEYHANK_HOME, "memory", ".migrated");
+
+let index: LocalIndex | null = null;
+
+export interface VectorItem {
+  id: string;
+  content: string;
+  metadata: Record<string, unknown>;
+}
+
+async function ensureIndex(): Promise<LocalIndex> {
+  if (index) return index;
+
+  mkdirSync(INDEX_PATH, { recursive: true });
+  const idx = new LocalIndex(INDEX_PATH);
+
+  if (!await idx.isIndexCreated()) {
+    await idx.createIndex();
+  }
+
+  index = idx;
+
+  // Run migration from old notes if needed
+  await migrateFromNotes();
+
+  return index;
+}
+
+async function migrateFromNotes(): Promise<void> {
+  if (existsSync(MIGRATED_MARKER)) return;
+
+  const notesPath = join(HEYHANK_HOME, "assistant", "notes.json");
+  if (!existsSync(notesPath)) {
+    // No notes to migrate, mark as done
+    mkdirSync(join(HEYHANK_HOME, "memory"), { recursive: true });
+    writeFileSync(MIGRATED_MARKER, new Date().toISOString(), "utf-8");
+    return;
+  }
+
+  try {
+    const notes = JSON.parse(readFileSync(notesPath, "utf-8")) as Array<{
+      id: string;
+      title: string;
+      content: string;
+      tags: string[];
+      createdAt: string;
+    }>;
+
+    const memoryNotes = notes.filter(
+      (n) => n.tags?.includes("memory") || n.tags?.includes("hank-memory")
+    );
+
+    if (memoryNotes.length > 0) {
+      console.log(`[vector-store] Migrating ${memoryNotes.length} memory notes to vector index...`);
+
+      // Import embedding lazily to avoid circular deps
+      const { getEmbedding } = await import("./embedding-service.js");
+
+      for (const note of memoryNotes) {
+        try {
+          const embedding = await getEmbedding(note.content, "passage: ");
+          await index!.insertItem({
+            vector: embedding,
+            metadata: {
+              id: note.id,
+              content: note.content,
+              createdAt: note.createdAt,
+            },
+          });
+        } catch {
+          // If embedding fails, store with zero vector
+          const zeroVector = new Array(384).fill(0);
+          await index!.insertItem({
+            vector: zeroVector,
+            metadata: {
+              id: note.id,
+              content: note.content,
+              createdAt: note.createdAt,
+            },
+          });
+        }
+      }
+      console.log(`[vector-store] Migration complete.`);
+    }
+  } catch (err) {
+    console.error("[vector-store] Migration error:", err);
+  }
+
+  writeFileSync(MIGRATED_MARKER, new Date().toISOString(), "utf-8");
+}
+
+export async function addItem(
+  id: string,
+  content: string,
+  embedding: number[],
+  metadata: Record<string, unknown> = {}
+): Promise<void> {
+  const idx = await ensureIndex();
+  await idx.insertItem({
+    vector: embedding,
+    metadata: { id, content, ...metadata },
+  });
+}
+
+export async function searchByVector(embedding: number[], topK = 5): Promise<VectorItem[]> {
+  const idx = await ensureIndex();
+  const results = await idx.queryItems(embedding, "", topK);
+  return results.map((r) => ({
+    id: (r.item.metadata as Record<string, unknown>).id as string,
+    content: (r.item.metadata as Record<string, unknown>).content as string,
+    metadata: r.item.metadata as Record<string, unknown>,
+  }));
+}
+
+export async function keywordSearch(query: string, limit = 5): Promise<VectorItem[]> {
+  const idx = await ensureIndex();
+  const allItems = await idx.listItems();
+  const q = query.toLowerCase();
+  const matches: VectorItem[] = [];
+
+  for (const item of allItems) {
+    const meta = item.metadata as Record<string, unknown>;
+    const content = (meta.content as string) || "";
+    if (content.toLowerCase().includes(q)) {
+      matches.push({
+        id: meta.id as string,
+        content,
+        metadata: meta,
+      });
+      if (matches.length >= limit) break;
+    }
+  }
+
+  return matches;
+}
+
+export async function listAll(): Promise<VectorItem[]> {
+  const idx = await ensureIndex();
+  const allItems = await idx.listItems();
+  return allItems.map((item) => {
+    const meta = item.metadata as Record<string, unknown>;
+    return {
+      id: meta.id as string,
+      content: (meta.content as string) || "",
+      metadata: meta,
+    };
+  });
+}
+
+export async function deleteItem(id: string): Promise<boolean> {
+  const idx = await ensureIndex();
+  const allItems = await idx.listItems();
+  for (const item of allItems) {
+    const meta = item.metadata as Record<string, unknown>;
+    if (meta.id === id) {
+      await idx.deleteItem(item.id);
+      return true;
+    }
+  }
+  return false;
+}
+
+export async function rebuildFromVault(vaultMemoryDir: string): Promise<void> {
+  const { readdirSync, readFileSync } = await import("node:fs");
+  const { join } = await import("node:path");
+  const { parseFrontmatter } = await import("./vault-markdown.js");
+  const { getEmbedding } = await import("./embedding-service.js");
+
+  const files = readdirSync(vaultMemoryDir).filter(f => f.startsWith("memory-") && f.endsWith(".md"));
+  if (files.length === 0) return;
+
+  // Get existing indexed IDs to skip
+  const existingItems = await listAll();
+  const existingIds = new Set(existingItems.map(i => i.id));
+
+  let indexed = 0;
+  for (const file of files) {
+    const id = file.replace(/^memory-/, "").replace(/\.md$/, "");
+    if (existingIds.has(id)) continue;
+
+    const content = readFileSync(join(vaultMemoryDir, file), "utf-8");
+    const { frontmatter, body } = parseFrontmatter(content);
+
+    let embedding: number[];
+    try {
+      embedding = await getEmbedding(body, "passage: ");
+    } catch {
+      embedding = new Array(384).fill(0);
+    }
+
+    const metadata: Record<string, unknown> = {};
+    if (frontmatter.createdAt) metadata.createdAt = frontmatter.createdAt;
+    if (frontmatter.category) metadata.category = frontmatter.category;
+    if (frontmatter.source) metadata.source = frontmatter.source;
+
+    await addItem(id, body, embedding, metadata);
+    indexed++;
+  }
+
+  if (indexed > 0) console.log(`[vector-store] Indexed ${indexed} new memories from vault`);
+}

package/server/voice-pipeline/gemini-live-adapter.ts

@@ -0,0 +1,97 @@
+// ─── Gemini Live Adapter ─────────────────────────────────────────────────────
+// Wraps the existing AudioBridge (Gemini Live) so it conforms to the
+// VoiceEngineSession interface. Lets call-manager use both engines uniformly.
+
+import type { ServerWebSocket } from "bun";
+import { AudioBridge, base64ToBuffer, downsampleTo8k } from "../telephony/audio-bridge.js";
+import type { TelephonyContact, TranscriptEntry, CallState, TelephonySettings } from "../telephony/call-types.js";
+import type { VoiceEngineSession } from "./manager.js";
+
+interface GeminiLiveAdapterParams {
+  callId: string;
+  voice: string;
+  systemPrompt: string;
+  geminiKey: string;
+  telSettings: TelephonySettings;
+  tools: unknown[];
+  isInbound: boolean;
+  onTranscript: (entry: TranscriptEntry) => void;
+  onStatusChange: (status: CallState["status"]) => void;
+  onToolCall: (calls: Array<{ id: string; name: string; args: Record<string, unknown> }>) => Promise<Array<{ id: string; name: string; response: unknown }>>;
+  /** For listen-mode: receives raw 24kHz base64 PCM from Gemini before downsampling */
+  onRawGeminiAudio?: (base64Pcm: string) => void;
+}
+
+export function createGeminiLiveEngine(params: GeminiLiveAdapterParams): VoiceEngineSession & { bridge: AudioBridge } {
+  const { callId, voice, systemPrompt, geminiKey, telSettings, tools, isInbound, onTranscript, onStatusChange, onToolCall, onRawGeminiAudio } = params;
+
+  const bridge = new AudioBridge(callId, {
+    geminiApiKey: geminiKey,
+    voice,
+    systemPrompt,
+    vertexAI: telSettings.geminiBackend === "vertexai" ? {
+      enabled: true,
+      projectId: telSettings.gcpProjectId,
+      location: telSettings.gcpLocation,
+      serviceAccountKey: telSettings.gcpServiceAccountKey,
+    } : undefined,
+    tools,
+    onTranscript,
+    onStatusChange,
+    onToolCall,
+  });
+
+  let onAudioCb: (pcm8k: Uint8Array) => void = () => {};
+  let onTurnCompleteCb: (() => void) | undefined;
+
+  // Gemini emits base64 24kHz PCM → downsample to 8kHz for FreeSWITCH
+  bridge.onGeminiAudio = (base64Pcm: string) => {
+    onRawGeminiAudio?.(base64Pcm);
+    const pcm = base64ToBuffer(base64Pcm);
+    const downsampled = downsampleTo8k(pcm, 24000);
+    onAudioCb(downsampled);
+  };
+
+  bridge.onTurnComplete = () => {
+    onTurnCompleteCb?.();
+  };
+
+  const engine: VoiceEngineSession & { bridge: AudioBridge } = {
+    bridge,
+    engineLabel: telSettings.geminiBackend === "vertexai" ? "Gemini Live (Vertex AI)" : "Gemini Live (AI Studio)",
+    onAudio: () => {},
+    async connect() {
+      await bridge.connect();
+    },
+    sendCallerAudio(pcm) {
+      bridge.sendCallerAudio(pcm);
+    },
+    playGreetingIfReady() {
+      // Gemini Live needs a text trigger to start speaking (no pre-rendered greeting)
+      bridge.sendTrigger(isInbound
+        ? "A caller is now on the line. Start speaking NOW — greet them warmly and ask how you can help."
+        : "The callee just picked up the phone. Start speaking NOW — greet them immediately according to your instructions.");
+    },
+    disconnect() {
+      bridge.disconnect();
+    },
+    get isReady() {
+      return bridge.isReady;
+    },
+  };
+
+  // Wire the audio callback so call-manager can patch it
+  Object.defineProperty(engine, "onAudio", {
+    get() { return onAudioCb; },
+    set(fn: (pcm8k: Uint8Array) => void) { onAudioCb = fn; },
+  });
+  Object.defineProperty(engine, "onTurnComplete", {
+    get() { return onTurnCompleteCb; },
+    set(fn: () => void) { onTurnCompleteCb = fn; },
+  });
+
+  return engine;
+}
+
+// Re-export for convenience
+export type { ServerWebSocket };

package/server/voice-pipeline/greeting-cache.ts

@@ -0,0 +1,200 @@
+// ─── Greeting Cache ─────────────────────────────────────────────────────────
+// Pre-renders greeting MP3s/PCM for instant playback at call answer.
+// Cache key: contactId + direction + voice + text-hash.
+// Auto-invalidates when contact name/script changes.
+
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { TelephonyContact } from "../telephony/call-types.js";
+import type { TTSConfig, VoicePipelineSettings } from "./types.js";
+import { getTTSProvider } from "./providers/index.js";
+import { normalizePhoneE164 } from "../telephony/phone-utils.js";
+
+const CACHE_DIR = join(homedir(), ".heyhank", "telephony", "greetings");
+
+function ensureDir(): void {
+  if (!existsSync(CACHE_DIR)) mkdirSync(CACHE_DIR, { recursive: true });
+}
+
+function hashText(text: string): string {
+  return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+
+/** Build cache file path */
+function cachePath(key: string, format: "pcm" | "mp3"): string {
+  return join(CACHE_DIR, `${key}.${format}`);
+}
+
+/** Options to customize the greeting text without changing every call site. */
+export interface GreetingTextOptions {
+  /** Operator name to mention (e.g. "Markus Stöger"). Empty → no operator clause. */
+  operatorName?: string;
+  /** Append AI + recording disclosure (EU AI Act Art. 50 + DSGVO Art. 13). Default: true. */
+  legalDisclosure?: boolean;
+}
+
+/** Build the greeting text from contact + direction. */
+export function buildGreetingText(
+  direction: "inbound" | "outbound",
+  contact: TelephonyContact | null,
+  options: GreetingTextOptions = {},
+): string {
+  const operator = options.operatorName?.trim();
+  const disclose = options.legalDisclosure !== false;
+  const ofOperator = operator ? ` von ${operator}` : "";
+  const aiLabel = disclose ? "der KI-Assistent" : "der Assistent";
+  const recordingClause = disclose
+    ? " Dieses Gespräch wird aufgezeichnet und mit künstlicher Intelligenz verarbeitet."
+    : "";
+
+  if (direction === "outbound") {
+    if (contact) {
+      return `Servus ${contact.name}! Hier ist Hank, ${aiLabel}${ofOperator}.${recordingClause} Hast du kurz Zeit?`;
+    }
+    return `Hallo, hier ist Hank, ${aiLabel}${ofOperator}.${recordingClause}`;
+  }
+  // inbound
+  if (contact) {
+    return `Servus ${contact.name}! Hier ist Hank, ${aiLabel}${ofOperator}.${recordingClause} Was kann ich für dich tun?`;
+  }
+  // unknown caller
+  return `Hallo, hier ist Hank, ${aiLabel}${ofOperator}.${recordingClause} Wie kann ich dir helfen?`;
+}
+
+/** Build a cache key for the given parameters */
+function buildKey(params: {
+  direction: "inbound" | "outbound";
+  contactId: string | null;
+  voice: string;
+  text: string;
+}): string {
+  const contactPart = params.contactId || "unknown";
+  return `${params.direction}-${contactPart}-${params.voice}-${hashText(params.text)}`;
+}
+
+/** Get or render a greeting → returns PCM 8kHz bytes for FreeSWITCH */
+export async function getOrRenderGreeting(params: {
+  direction: "inbound" | "outbound";
+  contact: TelephonyContact | null;
+  settings: VoicePipelineSettings;
+  /** Optional override text (else built from contact + direction) */
+  overrideText?: string;
+}): Promise<{ pcm: Uint8Array; text: string; cached: boolean }> {
+  ensureDir();
+  const text = params.overrideText || buildGreetingText(params.direction, params.contact, {
+    operatorName: params.settings.operatorName,
+    legalDisclosure: params.settings.legalDisclosureInGreeting,
+  });
+  const voice = params.settings.tts.voice;
+  const key = buildKey({
+    direction: params.direction,
+    contactId: params.contact?.id ?? null,
+    voice,
+    text,
+  });
+
+  const pcmPath = cachePath(key, "pcm");
+  if (existsSync(pcmPath)) {
+    return { pcm: readFileSync(pcmPath), text, cached: true };
+  }
+
+  // Render via TTS
+  const ttsProvider = getTTSProvider(params.settings.tts.provider);
+  const config: TTSConfig = {
+    voice,
+    language: params.settings.stt.language,
+    format: "PCM_8000",
+    speakingRate: params.settings.tts.speakingRate,
+  };
+  // Phonetic fix: German TTS says "Hank" with a long A ("Haank").
+  // Spelling it "Henk" yields the English short-A pronunciation.
+  const ttsText = text.replace(/\bHank\b/g, "Henk");
+  const result = await ttsProvider.synthesize(ttsText, config);
+
+  // Save to cache
+  writeFileSync(pcmPath, Buffer.from(result.audio));
+
+  return { pcm: result.audio, text, cached: false };
+}
+
+/**
+ * Pre-render greetings for ALL contacts (background task).
+ * Called on contact create/update or settings change.
+ * Renders both inbound + outbound personalized greetings + the unknown-caller default.
+ */
+export async function preRenderAllGreetings(
+  contacts: TelephonyContact[],
+  settings: VoicePipelineSettings,
+): Promise<{ rendered: number; cached: number; errors: number }> {
+  if (!settings.preRenderGreetings) {
+    return { rendered: 0, cached: 0, errors: 0 };
+  }
+
+  let rendered = 0;
+  let cached = 0;
+  let errors = 0;
+
+  // Default unknown-caller inbound greeting
+  try {
+    const r = await getOrRenderGreeting({ direction: "inbound", contact: null, settings });
+    if (r.cached) cached++; else rendered++;
+  } catch {
+    errors++;
+  }
+
+  // Per-contact greetings (both directions)
+  for (const c of contacts) {
+    for (const dir of ["inbound", "outbound"] as const) {
+      try {
+        const r = await getOrRenderGreeting({ direction: dir, contact: c, settings });
+        if (r.cached) cached++; else rendered++;
+      } catch {
+        errors++;
+      }
+    }
+  }
+
+  return { rendered, cached, errors };
+}
+
+/**
+ * Find contact by phone number. Normalizes to E.164 first, so a caller-ID
+ * arriving as "06508920611" (national format) still matches a contact stored
+ * as "+436508920611". Pass the trunk's country-code digits (no `+`) as
+ * `defaultCountryCode` to enable national→E.164 conversion.
+ */
+export function findContactByPhone(
+  contacts: TelephonyContact[],
+  phone: string,
+  defaultCountryCode: string = "",
+): TelephonyContact | null {
+  if (!phone) return null;
+  const target = normalizePhoneE164(phone, defaultCountryCode);
+  return contacts.find((c) => normalizePhoneE164(c.phone, defaultCountryCode) === target) || null;
+}
+
+/**
+ * Wipe stale cache entries — call when settings change (different voice).
+ * Deletes all PCM files; they'll be re-rendered on demand.
+ */
+export function clearCache(): { deleted: number } {
+  ensureDir();
+  let deleted = 0;
+  try {
+    for (const file of readdirSync(CACHE_DIR)) {
+      if (file.endsWith(".pcm") || file.endsWith(".mp3")) {
+        try {
+          unlinkSync(join(CACHE_DIR, file));
+          deleted++;
+        } catch {
+          // ignore
+        }
+      }
+    }
+  } catch {
+    // ignore
+  }
+  return { deleted };
+}