feat(realtime): gate realtime pipeline voice models behind voice recognition

[localai-bot]

What

Adds an optional speaker-verification gate to realtime pipeline voice models (VAD → STT → LLM → TTS). When a model's YAML declares a pipeline.voice_recognition block, every committed utterance is verified against authorized speakers, and unauthorized utterances are dropped before they reach the LLM (no LLM call, no tool execution, no TTS). The realtime session stays open.

This connects the existing realtime API (WebRTC + WebSocket) with the existing voice-recognition subsystem (/v1/voice/*, VoiceRegistry, SpeechBrain/ONNX speaker-recognition backend). No new infrastructure.

Configuration

pipeline:
  vad: silero-vad
  transcription: whisper
  llm: qwen
  tts: kokoro
  voice_recognition:
    model: speaker-recognition   # speaker-recognition backend model
    mode: identify               # "identify" (registry) or "verify" (references)
    threshold: 0.25              # cosine distance; <= passes
    when: every                  # "every" (default) or "first"
    on_reject: drop_event        # "drop_event" (default) or "drop_silent"
    anti_spoofing: false         # optional liveness check (verify mode)
    allow:                       # identify mode: authorized identities (multiple persons)
      names: ["alice", "bob"]
      labels: ["family"]
    references:                  # verify mode: reference speakers (multiple persons)
      - { name: alice, audio: /models/voices/alice.wav }
      - { name: bob,   audio: /models/voices/bob.wav }

• identify (1:N): match against speakers registered via /v1/voice/register; allow.names/allow.labels filter who counts (empty = any registered speaker).
• verify (1:few): match against reference audios, embedded once at model load.
• Both modes support multiple authorized persons.

Design

• Dedicated voiceGate component (realtime_voicegate.go) with a single Authorize entry point and testability seams (embedFn/verifyFn + the Registry interface), so all decision paths are unit-tested without a live backend.
• Parallel-with-STT + hard barrier: verification runs concurrently with transcription as a latency optimization, but there is a hard join before generateResponse. An unauthorized utterance can never reach the LLM/tools/TTS regardless of how fast STT finishes.
• Fail-closed everywhere: a backend/verification error denies the turn; an incomplete voice_recognition block (e.g. missing model) refuses the session rather than running unprotected.
• when: first trusts the session after one successful match (guarded by a mutex); when: every re-checks each utterance.

Testing

• Unit tests for config schema (Normalize/Validate/VoiceGateEnabled), cosineDistance, identify mode (allow by name/label/empty, threshold, unknown speaker, no-speech, embed-fail, identify-fail), verify mode (match/no-match/no-speech/embed-fail, anti-spoofing + its error path), the decide policy matrix, and newVoiceGate fail-fast.
• go vet clean, go test -race clean on the realtime package, golangci-lint --new-from-merge-base reports 0 issues.

Notes

• identify mode uses the existing in-memory VoiceRegistry (lost on restart); persistence is future work.
• Built with subagent-driven development; each task was spec- and quality-reviewed.

Assisted-by: Claude:opus-4.8 [Claude Code]