@livekit/agents 1.0.47 → 1.1.0-dev.0

package/src/inference/interruption/types.ts

@@ -0,0 +1,84 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import type { Span } from '@opentelemetry/api';
+
+export interface OverlappingSpeechEvent {
+  type: 'user_overlapping_speech';
+  timestamp: number;
+  isInterruption: boolean;
+  totalDurationInS: number;
+  predictionDurationInS: number;
+  detectionDelayInS: number;
+  overlapStartedAt?: number;
+  speechInput?: Int16Array;
+  probabilities?: number[];
+  probability: number;
+  numRequests: number;
+}
+
+/**
+ * Configuration options for interruption detection.
+ */
+export interface InterruptionOptions {
+  sampleRate: number;
+  threshold: number;
+  minFrames: number;
+  maxAudioDurationInS: number;
+  audioPrefixDurationInS: number;
+  detectionIntervalInS: number;
+  inferenceTimeout: number;
+  minInterruptionDurationInS: number;
+  baseUrl: string;
+  apiKey: string;
+  apiSecret: string;
+  useProxy: boolean;
+}
+
+/**
+ * API connection options for transport layers.
+ */
+export interface ApiConnectOptions {
+  maxRetries: number;
+  retryInterval: number;
+  timeout: number;
+}
+
+// Sentinel types for stream control signals
+
+export interface AgentSpeechStarted {
+  type: 'agent-speech-started';
+}
+
+export interface AgentSpeechEnded {
+  type: 'agent-speech-ended';
+}
+
+export interface OverlapSpeechStarted {
+  type: 'overlap-speech-started';
+  /** Duration of the speech segment in milliseconds (matches VADEvent.speechDuration units). */
+  speechDuration: number;
+  /** Absolute timestamp (ms) when overlap speech started, computed at call-site. */
+  startedAt: number;
+  userSpeakingSpan?: Span;
+}
+
+export interface OverlapSpeechEnded {
+  type: 'overlap-speech-ended';
+  /** Absolute timestamp (ms) when overlap speech ended, used as the non-interruption event timestamp. */
+  endedAt: number;
+}
+
+export interface Flush {
+  type: 'flush';
+}
+
+/**
+ * Union type for all stream control signals.
+ */
+export type InterruptionSentinel =
+  | AgentSpeechStarted
+  | AgentSpeechEnded
+  | OverlapSpeechStarted
+  | OverlapSpeechEnded
+  | Flush;

package/src/inference/interruption/utils.test.ts

@@ -0,0 +1,132 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { describe, expect, it, vi } from 'vitest';
+import { BoundedCache } from './utils.js';
+
+class Entry {
+  createdAt: number;
+  totalDurationInS: number | undefined = undefined;
+  predictionDurationInS: number | undefined = undefined;
+  note: string | undefined = undefined;
+
+  constructor(createdAt: number, note?: string) {
+    this.createdAt = createdAt;
+    this.note = note;
+  }
+}
+
+describe('BoundedCache', () => {
+  it('evicts oldest entry when maxLen is exceeded', () => {
+    const cache = new BoundedCache<number, Entry>(2);
+    cache.set(1, new Entry(1));
+    cache.set(2, new Entry(2));
+    cache.set(3, new Entry(3));
+
+    expect(cache.size).toBe(2);
+    expect([...cache.keys()]).toEqual([2, 3]);
+    expect(cache.get(1)).toBeUndefined();
+    expect(cache.get(2)!.createdAt).toBe(2);
+    expect(cache.get(3)!.createdAt).toBe(3);
+  });
+
+  it('setOrUpdate creates a value via factory when key is missing', () => {
+    const cache = new BoundedCache<number, Entry>(10);
+    const factory = vi.fn(() => new Entry(100));
+
+    const value = cache.setOrUpdate(1, factory, { predictionDurationInS: 0.42 });
+
+    expect(factory).toHaveBeenCalledTimes(1);
+    expect(value.createdAt).toBe(100);
+    expect(value.predictionDurationInS).toBe(0.42);
+    expect(cache.get(1)?.predictionDurationInS).toBe(0.42);
+  });
+
+  it('setOrUpdate updates existing value and does not call factory', () => {
+    const cache = new BoundedCache<number, Entry>(10);
+    cache.set(1, new Entry(1, 'before'));
+    const factory = vi.fn(() => new Entry(999));
+
+    const value = cache.setOrUpdate(1, factory, { note: 'after', totalDurationInS: 1.5 });
+
+    expect(factory).not.toHaveBeenCalled();
+    expect(value.createdAt).toBe(1);
+    expect(value.note).toBe('after');
+    expect(value.totalDurationInS).toBe(1.5);
+  });
+
+  it('updateValue returns undefined for missing key', () => {
+    const cache = new BoundedCache<number, Entry>(10);
+    const result = cache.updateValue(404, { note: 'missing' });
+
+    expect(result).toBeUndefined();
+  });
+
+  it('updateValue ignores undefined fields', () => {
+    const cache = new BoundedCache<number, Entry>(10);
+    cache.set(1, new Entry(1, 'keep'));
+
+    const result = cache.updateValue(1, {
+      note: undefined,
+      predictionDurationInS: 0.1,
+    });
+
+    expect(result?.createdAt).toBe(1);
+    expect(result?.note).toBe('keep');
+    expect(result?.predictionDurationInS).toBe(0.1);
+  });
+
+  it('pop without predicate removes the oldest entry (python parity)', () => {
+    const cache = new BoundedCache<number, Entry>(10);
+    cache.set(1, new Entry(1));
+    cache.set(2, new Entry(2));
+    cache.set(3, new Entry(3));
+
+    const popped = cache.pop();
+
+    expect(popped?.createdAt).toBe(1);
+    expect([...cache.keys()]).toEqual([2, 3]);
+  });
+
+  it('pop with predicate removes the most recent matching entry', () => {
+    const cache = new BoundedCache<number, Entry>(10);
+    const e1 = new Entry(1);
+    e1.totalDurationInS = 0;
+    const e2 = new Entry(2);
+    e2.totalDurationInS = 1;
+    const e3 = new Entry(3);
+    e3.totalDurationInS = 2;
+    cache.set(1, e1);
+    cache.set(2, e2);
+    cache.set(3, e3);
+
+    const popped = cache.pop((entry) => (entry.totalDurationInS ?? 0) > 0);
+
+    expect(popped?.createdAt).toBe(3);
+    expect(popped?.totalDurationInS).toBe(2);
+    expect([...cache.keys()]).toEqual([1, 2]);
+  });
+
+  it('pop with predicate returns undefined when no match exists', () => {
+    const cache = new BoundedCache<number, Entry>(10);
+    const e1 = new Entry(1);
+    e1.totalDurationInS = 0;
+    cache.set(1, e1);
+
+    const popped = cache.pop((entry) => (entry.totalDurationInS ?? 0) > 10);
+
+    expect(popped).toBeUndefined();
+    expect(cache.size).toBe(1);
+  });
+
+  it('clear removes all entries', () => {
+    const cache = new BoundedCache<number, Entry>(10);
+    cache.set(1, new Entry(1));
+    cache.set(2, new Entry(2));
+
+    cache.clear();
+
+    expect(cache.size).toBe(0);
+    expect([...cache.keys()]).toEqual([]);
+  });
+});

package/src/inference/interruption/utils.ts

@@ -0,0 +1,137 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { FRAME_DURATION_IN_S, MIN_INTERRUPTION_DURATION_IN_S } from './defaults.js';
+
+/**
+ * A bounded cache that automatically evicts the oldest entries when the cache exceeds max size.
+ * Uses FIFO eviction strategy.
+ */
+export class BoundedCache<K, V extends object> {
+  private cache: Map<K, V> = new Map();
+  private readonly maxLen: number;
+
+  constructor(maxLen: number = 10) {
+    this.maxLen = maxLen;
+  }
+
+  set(key: K, value: V): void {
+    this.cache.set(key, value);
+    if (this.cache.size > this.maxLen) {
+      // Remove the oldest entry (first inserted)
+      const firstKey = this.cache.keys().next().value as K;
+      this.cache.delete(firstKey);
+    }
+  }
+
+  /**
+   * Update existing value fields if present and defined.
+   * Mirrors python BoundedDict.update_value behavior.
+   */
+  updateValue(key: K, fields: Partial<V>): V | undefined {
+    const value = this.cache.get(key);
+    if (!value) return value;
+
+    for (const [fieldName, fieldValue] of Object.entries(fields) as [keyof V, V[keyof V]][]) {
+      if (fieldValue === undefined) continue;
+      // Runtime field update parity with python's hasattr + setattr.
+      if (fieldName in (value as object)) {
+        (value as Record<string, unknown>)[String(fieldName)] = fieldValue;
+      }
+    }
+    return value;
+  }
+
+  /**
+   * Set a new value with factory when missing; otherwise update in place.
+   * Mirrors python BoundedDict.set_or_update behavior.
+   */
+  setOrUpdate(key: K, factory: () => V, fields: Partial<V>): V {
+    if (!this.cache.has(key)) {
+      this.set(key, factory());
+    }
+    const result = this.updateValue(key, fields);
+    if (!result) {
+      throw new Error('setOrUpdate invariant failed: entry should exist after set');
+    }
+    return result;
+  }
+
+  get(key: K): V | undefined {
+    return this.cache.get(key);
+  }
+
+  has(key: K): boolean {
+    return this.cache.has(key);
+  }
+
+  delete(key: K): boolean {
+    return this.cache.delete(key);
+  }
+
+  /**
+   * Pop an entry if it satisfies the predicate.
+   * - No predicate: pop oldest (FIFO)
+   * - With predicate: search in reverse order and pop first match
+   */
+  pop(predicate?: (value: V) => boolean): V | undefined {
+    if (predicate === undefined) {
+      const first = this.cache.entries().next().value as [K, V] | undefined;
+      if (!first) return undefined;
+      const [key, value] = first;
+      this.cache.delete(key);
+      return value;
+    }
+
+    const keys = Array.from(this.cache.keys());
+    for (let i = keys.length - 1; i >= 0; i--) {
+      const key = keys[i]!;
+      const value = this.cache.get(key)!;
+      if (predicate(value)) {
+        this.cache.delete(key);
+        return value;
+      }
+    }
+    return undefined;
+  }
+
+  clear(): void {
+    this.cache.clear();
+  }
+
+  get size(): number {
+    return this.cache.size;
+  }
+
+  values(): IterableIterator<V> {
+    return this.cache.values();
+  }
+
+  keys(): IterableIterator<K> {
+    return this.cache.keys();
+  }
+
+  entries(): IterableIterator<[K, V]> {
+    return this.cache.entries();
+  }
+}
+
+/**
+ * Estimate probability by finding the n-th maximum value in the probabilities array.
+ * The n-th position is determined by the window size (25ms per frame).
+ * Returns 0 if there are insufficient probabilities.
+ */
+export function estimateProbability(
+  probabilities: number[],
+  windowSizeInS: number = MIN_INTERRUPTION_DURATION_IN_S,
+): number {
+  const nTh = Math.ceil(windowSizeInS / FRAME_DURATION_IN_S);
+  if (probabilities.length < nTh) {
+    return 0;
+  }
+
+  // Find the n-th maximum value by sorting in descending order
+  // Create a copy to avoid mutating the original array
+  const sorted = [...probabilities].sort((a, b) => b - a);
+  return sorted[nTh - 1]!;
+}