@agfpd/voicetalk-runtime 0.1.0 → 0.2.0

package/src/wake.ts

@@ -0,0 +1,279 @@
+// wake.ts — «кому из флота адресована реплика».
+//
+// HYBRID wake model (design intent agreed with Arthur, 22.07): the passport carries a
+// small CURATED map «wake word → target peer» plus a default target. A wake word that is
+// a peer's name addresses that peer directly («Борис, привет» → boris); a neutral wake
+// word addresses the default agent, who dispatches onward. A word per each of 30+ peers
+// was explicitly REJECTED — it couples the spoken vocabulary to the roster and multiplies
+// false triggers — so nothing here ever sweeps the fleet registry for addressable names.
+// The registry is consulted only for peers the operator ALREADY named in the map, to
+// enrich them with their own human name («наталья» → «наталья вячеславовна») and their
+// voice.
+//
+// Why the address is matched on the TRANSCRIPT rather than by an acoustic wake-word model
+// (openWakeWord et al.): an acoustic detector needs a trained model per phrase, and Фаза 3
+// is proving the pipeline end to end — transcript matching gives the same routing with
+// zero training and no per-name asset to maintain. Privacy is preserved by the property
+// that made an on-device detector attractive in the first place: the recognizer is the
+// LOCAL floor of voice-connect (mlx-whisper on this host), so no audio leaves the machine
+// to decide whether a name was spoken. The cost is running the recognizer on every voiced
+// segment; endpointing keeps that to actual speech, and an acoustic pre-gate (openWakeWord
+// on the curated map — cheap in parallel, one shared feature backbone) is the natural
+// Фаза-4 latency upgrade behind this same interface.
+
+import { readFileSync } from 'fs'
+import { homedir } from 'os'
+import { join } from 'path'
+
+export type FleetPeer = {
+  personality: string
+  intelligence?: string
+  description?: string
+  /** Per-peer TTS voice from `interfaces.voice` — so each agent answers in its own voice. */
+  voice?: Record<string, string>
+}
+
+export type Address = {
+  personality: string
+  /** Every spoken form that addresses this peer, normalized. */
+  aliases: string[]
+}
+
+const FILLERS = new Set(['эй', 'окей', 'ок', 'слушай', 'hey', 'ok', 'okay', 'привет'])
+
+/** Normalize a spoken/written form for matching: lowercase, ё→е, punctuation dropped. */
+export function normalizeSpoken(text: string): string {
+  return text
+    .toLowerCase()
+    .replace(/ё/g, 'е')
+    .replace(/[^\p{L}\p{N}\s-]/gu, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+function levenshtein(a: string, b: string): number {
+  if (a === b) return 0
+  const m = a.length
+  const n = b.length
+  if (m === 0 || n === 0) return Math.max(m, n)
+  let prev = Array.from({ length: n + 1 }, (_, i) => i)
+  for (let i = 1; i <= m; i++) {
+    const cur = [i]
+    for (let j = 1; j <= n; j++) {
+      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1))
+    }
+    prev = cur
+  }
+  return prev[n]
+}
+
+/** Speech recognition mangles the tail of a name («Борис» → «борись»); allow one edit on
+ *  a name long enough that a single-edit collision is implausible. */
+function tokenMatches(spoken: string, alias: string): boolean {
+  if (spoken === alias) return true
+  if (alias.length >= 5 && Math.abs(spoken.length - alias.length) <= 1) return levenshtein(spoken, alias) <= 1
+  return false
+}
+
+/** Derive the spoken forms of a peer: its personality plus the human name that opens its
+ *  description («Борис — PM и архитектор…» → «борис»). This makes the fleet's own
+ *  registry the single source of truth for names; no separate alias file to drift. */
+export function peerAliases(peer: FleetPeer): string[] {
+  const out = new Set<string>()
+  const personality = normalizeSpoken(peer.personality)
+  if (personality) out.add(personality)
+  const head = normalizeSpoken((peer.description ?? '').split(/\s+[—–-]\s+/)[0] ?? '')
+  if (head && head.length <= 40) {
+    out.add(head)
+    const first = head.split(' ')[0]
+    // «mr booker» → also «booker»; «наталья вячеславовна» → also «наталья».
+    if (first && first.length >= 3 && !['mr', 'mrs', 'ms', 'dr'].includes(first)) out.add(first)
+    const words = head.split(' ')
+    if (words.length > 1 && ['mr', 'mrs', 'ms', 'dr'].includes(words[0])) out.add(words.slice(1).join(' '))
+  }
+  return [...out].filter(Boolean)
+}
+
+function iapeerRoot(): string {
+  const override = process.env.IAPEER_ROOT?.trim()
+  return override || join(homedir(), '.iapeer')
+}
+
+export function readFleetPeers(path = join(iapeerRoot(), 'peers-profiles.json')): FleetPeer[] {
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8')) as { peers?: unknown }
+    if (!Array.isArray(raw.peers)) return []
+    return raw.peers
+      .filter((p): p is Record<string, unknown> => !!p && typeof p === 'object')
+      .map(p => ({
+        personality: String(p.personality ?? ''),
+        intelligence: typeof p.intelligence === 'string' ? p.intelligence : undefined,
+        description: typeof p.description === 'string' ? p.description : undefined,
+        voice:
+          p.interfaces && typeof p.interfaces === 'object' && (p.interfaces as any).voice
+            ? ((p.interfaces as any).voice as Record<string, string>)
+            : undefined,
+      }))
+      .filter(p => p.personality)
+  } catch {
+    return []
+  }
+}
+
+/** The voicetalk peer binding — the hybrid wake map. `wake_words` may be written as a
+ *  map (word → peer) or as a bare list of words, in which case each word is resolved to
+ *  the peer it names, falling back to `default_target`. `wake_word` is the legacy
+ *  single-word form and is folded into the same map. */
+export type VoicetalkBinding = {
+  wake_word?: string
+  wake_words?: Record<string, string> | string[]
+  default_target?: string
+  device?: string
+}
+
+export type AddressBookOptions = {
+  /** The speaker — never addressable by their own voice. */
+  owner: string
+  binding: VoicetalkBinding
+  peers?: FleetPeer[]
+}
+
+/** Normalize the two accepted spellings of the wake map into word → target|undefined. */
+export function wakeEntries(binding: VoicetalkBinding): Array<[string, string | undefined]> {
+  const out: Array<[string, string | undefined]> = []
+  const push = (word: unknown, target?: unknown) => {
+    const w = normalizeSpoken(String(word ?? ''))
+    if (!w) return
+    const t = typeof target === 'string' && target.trim() ? target.trim() : undefined
+    out.push([w, t])
+  }
+  const map = binding.wake_words
+  if (Array.isArray(map)) for (const word of map) push(word)
+  else if (map && typeof map === 'object') for (const [word, target] of Object.entries(map)) push(word, target)
+  if (binding.wake_word) push(binding.wake_word)
+  return out
+}
+
+/** Build the address book from the CURATED wake map. Every entry resolves to a target:
+ *  the explicit one, else the peer whose name the wake word is, else the default target.
+ *  A wake word with no resolvable target is dropped (and `doctor` reports it) — routing
+ *  speech to a guessed peer is worse than not routing it. */
+export function buildAddressBook(opts: AddressBookOptions): Address[] {
+  const owner = normalizeSpoken(opts.owner)
+  const peers = opts.peers ?? readFleetPeers()
+  const byName = (word: string): string | undefined =>
+    peers.find(p => normalizeSpoken(p.personality) === word)?.personality ??
+    peers.find(p => peerAliases(p).includes(word))?.personality
+  const book = new Map<string, Set<string>>()
+  const add = (personality: string, aliases: string[]) => {
+    const key = personality.trim()
+    if (!key || normalizeSpoken(key) === owner) return
+    const set = book.get(key) ?? new Set<string>()
+    for (const a of aliases) if (a) set.add(a)
+    book.set(key, set)
+  }
+  const entries = wakeEntries(opts.binding)
+  if (entries.length === 0 && opts.binding.default_target) {
+    // Out-of-the-box default (22.07): the DEFAULT AGENT'S NAME is the activation word —
+    // no separate neutral wake word is introduced. A passport carrying only
+    // `default_target: "darwin"` is therefore already usable: «Дарвин, …».
+    const target = opts.binding.default_target
+    const known = peers.find(p => p.personality === target)
+    entries.push(...[normalizeSpoken(target), ...(known ? peerAliases(known) : [])].map(w => [w, target] as [string, string]))
+  }
+  for (const [word, explicit] of entries) {
+    const target = explicit ?? byName(word) ?? opts.binding.default_target
+    if (!target) continue
+    // The target is addressable by: the configured word, its own personality, and — for a
+    // peer the registry knows — its human name. Bounded to CONFIGURED targets only.
+    const known = peers.find(p => p.personality === target)
+    add(target, [word, normalizeSpoken(target), ...(known ? peerAliases(known) : [])])
+  }
+  return [...book.entries()].map(([personality, aliases]) => ({ personality, aliases: [...aliases] }))
+}
+
+/** Wake words the operator configured that resolve to nothing — surfaced by `doctor`. */
+export function unresolvedWakeWords(binding: VoicetalkBinding, peers?: FleetPeer[]): string[] {
+  const roster = peers ?? readFleetPeers()
+  const out: string[] = []
+  for (const [word, explicit] of wakeEntries(binding)) {
+    const target =
+      explicit ??
+      roster.find(p => normalizeSpoken(p.personality) === word)?.personality ??
+      roster.find(p => peerAliases(p).includes(word))?.personality ??
+      binding.default_target
+    if (!target) out.push(word)
+  }
+  return out
+}
+
+export type WakeMatch = {
+  target: string
+  /** The utterance with the address (and any leading filler) stripped. */
+  body: string
+  alias: string
+}
+
+/** Does this transcript open by addressing a fleet peer? Longest alias wins, so
+ *  «наталья вячеславовна» is preferred over «наталья». */
+export function matchWake(transcript: string, book: Address[]): WakeMatch | null {
+  const normalized = normalizeSpoken(transcript)
+  if (!normalized) return null
+  let tokens = normalized.split(' ')
+  const rawTokens = transcript.trim().split(/\s+/)
+  let offset = 0
+  // Skip a leading filler («эй, Борис…», «окей, Борис…») — one only.
+  if (tokens.length > 1 && FILLERS.has(tokens[0])) {
+    tokens = tokens.slice(1)
+    offset = 1
+  }
+  const candidates: Array<{ target: string; alias: string; words: string[] }> = []
+  for (const entry of book) {
+    for (const alias of entry.aliases) candidates.push({ target: entry.personality, alias, words: alias.split(' ') })
+  }
+  candidates.sort((a, b) => b.words.length - a.words.length || b.alias.length - a.alias.length)
+  for (const cand of candidates) {
+    if (tokens.length < cand.words.length) continue
+    const ok = cand.words.every((w, i) => tokenMatches(tokens[i], w))
+    if (!ok) continue
+    // Rebuild the body from the ORIGINAL transcript so punctuation and casing of the
+    // message survive — only the address is stripped.
+    const body = rawTokens
+      .slice(offset + cand.words.length)
+      .join(' ')
+      .replace(/^[\s,.!:;—–-]+/, '')
+      .trim()
+    return { target: cand.target, alias: cand.alias, body }
+  }
+  return null
+}
+
+/** Whisper-family recognizers emit stock phrases on near-silence («Продолжение
+ *  следует…», «Субтитры сделал…»). They are not speech; drop them before matching so a
+ *  quiet room cannot fabricate an utterance. */
+const HALLUCINATIONS = [
+  'продолжение следует',
+  'субтитры',
+  'редактор субтитров',
+  'корректор',
+  'спасибо за просмотр',
+  'подписывайтесь на канал',
+  'thanks for watching',
+  'subtitles by',
+  'thank you',
+  'you',
+]
+
+export function isLikelyHallucination(transcript: string): boolean {
+  const n = normalizeSpoken(transcript)
+  if (!n) return true
+  if (n.length <= 2) return true
+  return HALLUCINATIONS.some(h => n === h || n.startsWith(h))
+}
+
+/** Names spoken to the recognizer as a decoder prompt — biases spelling toward the
+ *  fleet's own vocabulary so the matcher sees «Борис», not «Барис». */
+export function sttPrompt(book: Address[]): string {
+  const names = book.flatMap(a => a.aliases).slice(0, 40)
+  return names.length ? `Обращение к ассистенту по имени: ${names.join(', ')}.` : ''
+}