vocal-stack 1.0.0

package/dist/flow/index.d.cts

@@ -0,0 +1,337 @@
+/**
+ * Configuration for flow control
+ */
+interface FlowConfig {
+    /**
+     * Stall threshold in milliseconds
+     * @default 700
+     */
+    readonly stallThresholdMs?: number;
+    /**
+     * Filler phrases to inject
+     * @default ['um', 'let me think', 'hmm']
+     */
+    readonly fillerPhrases?: readonly string[];
+    /**
+     * Whether to enable filler injection
+     * @default true
+     */
+    readonly enableFillers?: boolean;
+    /**
+     * Maximum number of fillers to inject per response
+     * @default 3
+     */
+    readonly maxFillersPerResponse?: number;
+    /**
+     * Callback when filler is injected
+     */
+    readonly onFillerInjected?: (filler: string) => void;
+    /**
+     * Callback when stall is detected
+     */
+    readonly onStallDetected?: (durationMs: number) => void;
+    /**
+     * Callback when first chunk is emitted
+     */
+    readonly onFirstChunk?: () => void;
+}
+/**
+ * Conversation states
+ */
+declare enum ConversationState {
+    IDLE = "idle",
+    WAITING = "waiting",
+    SPEAKING = "speaking",
+    INTERRUPTED = "interrupted"
+}
+/**
+ * Statistics tracked by flow controller
+ */
+interface FlowStats {
+    readonly fillersInjected: number;
+    readonly stallsDetected: number;
+    readonly chunksProcessed: number;
+    readonly firstChunkTime: number | null;
+    readonly totalDurationMs: number;
+}
+/**
+ * Flow events for low-level API
+ */
+type FlowEvent = {
+    type: 'stall-detected';
+    durationMs: number;
+} | {
+    type: 'filler-injected';
+    filler: string;
+} | {
+    type: 'first-chunk';
+    chunk: string;
+} | {
+    type: 'state-change';
+    from: ConversationState;
+    to: ConversationState;
+} | {
+    type: 'interrupted';
+} | {
+    type: 'chunk-processed';
+    chunk: string;
+} | {
+    type: 'completed';
+    stats: FlowStats;
+};
+/**
+ * Event listener for flow events
+ */
+type FlowEventListener = (event: FlowEvent) => void;
+/**
+ * Configuration for low-level FlowManager
+ */
+interface FlowManagerConfig {
+    /**
+     * Stall threshold in milliseconds
+     * @default 700
+     */
+    readonly stallThresholdMs?: number;
+    /**
+     * Filler phrases to inject
+     * @default ['um', 'let me think', 'hmm']
+     */
+    readonly fillerPhrases?: readonly string[];
+    /**
+     * Whether to enable filler injection
+     * @default true
+     */
+    readonly enableFillers?: boolean;
+    /**
+     * Maximum number of fillers to inject per response
+     * @default 3
+     */
+    readonly maxFillersPerResponse?: number;
+    /**
+     * Buffer size for barge-in scenarios
+     * @default 10
+     */
+    readonly bufferSize?: number;
+}
+
+/**
+ * High-level stream wrapper for flow control
+ */
+declare class FlowController {
+    private readonly config;
+    private readonly stateMachine;
+    private readonly stallDetector;
+    private readonly fillerInjector;
+    private readonly bufferManager;
+    private firstChunkEmitted;
+    private stats;
+    private startTime;
+    constructor(config?: FlowConfig);
+    /**
+     * Wrap an async iterable with flow control
+     */
+    wrap(input: AsyncIterable<string>): AsyncIterable<string>;
+    /**
+     * Interrupt the current flow (for barge-in)
+     */
+    interrupt(): void;
+    /**
+     * Get current conversation state
+     */
+    getState(): ConversationState;
+    /**
+     * Get flow statistics
+     */
+    getStats(): FlowStats;
+    /**
+     * Get buffered chunks (for advanced barge-in scenarios)
+     */
+    getBufferedChunks(): readonly string[];
+    private handleStall;
+    private reset;
+}
+/**
+ * Convenience function to create and use flow controller
+ */
+declare function withFlowControl(input: AsyncIterable<string>, config?: FlowConfig): AsyncIterable<string>;
+
+/**
+ * Low-level event-based flow manager
+ */
+declare class FlowManager {
+    private readonly config;
+    private readonly stateMachine;
+    private readonly stallDetector;
+    private readonly fillerInjector;
+    private readonly bufferManager;
+    private readonly listeners;
+    private firstChunkEmitted;
+    private stats;
+    private startTime;
+    private stateChangeUnsubscribe;
+    constructor(config?: FlowManagerConfig);
+    /**
+     * Add event listener
+     */
+    on(listener: FlowEventListener): () => void;
+    /**
+     * Start flow tracking
+     */
+    start(): void;
+    /**
+     * Process a chunk from the stream
+     */
+    processChunk(chunk: string): void;
+    /**
+     * Complete the flow
+     */
+    complete(): void;
+    /**
+     * Interrupt the flow (for barge-in)
+     */
+    interrupt(): void;
+    /**
+     * Get current conversation state
+     */
+    getState(): ConversationState;
+    /**
+     * Get flow statistics
+     */
+    getStats(): FlowStats;
+    /**
+     * Get buffered chunks
+     */
+    getBufferedChunks(): readonly string[];
+    private handleStall;
+    private emit;
+    private reset;
+}
+
+/**
+ * Conversation state machine
+ */
+declare class ConversationStateMachine {
+    private currentState;
+    private readonly listeners;
+    /**
+     * Get current state
+     */
+    getState(): ConversationState;
+    /**
+     * Attempt to transition to new state
+     */
+    transition(to: ConversationState): boolean;
+    /**
+     * Add state change listener
+     */
+    onStateChange(listener: (from: ConversationState, to: ConversationState) => void): () => void;
+    /**
+     * Reset to IDLE
+     */
+    reset(): void;
+}
+
+/**
+ * Default stall threshold in milliseconds
+ * Based on human perception of silence: 500-1000ms feels like a pause
+ * Most LLM APIs stream chunks every 50-200ms when active
+ */
+declare const DEFAULT_STALL_THRESHOLD_MS = 700;
+/**
+ * Default filler phrases to inject during stalls
+ */
+declare const DEFAULT_FILLER_PHRASES: string[];
+/**
+ * Default maximum fillers per response
+ * Prevents over-use of filler words
+ */
+declare const DEFAULT_MAX_FILLERS_PER_RESPONSE = 3;
+
+/**
+ * Detects stream stalls based on timing
+ */
+declare class StallDetector {
+    private lastChunkTime;
+    private stallTimer;
+    private readonly thresholdMs;
+    private readonly onStall;
+    constructor(thresholdMs: number, onStall: (durationMs: number) => void);
+    /**
+     * Notify detector that a chunk was received
+     */
+    notifyChunk(): void;
+    /**
+     * Start monitoring for stalls
+     */
+    start(): void;
+    /**
+     * Stop monitoring
+     */
+    stop(): void;
+    private scheduleStallCheck;
+    private clearTimer;
+}
+
+/**
+ * Manages filler phrase injection
+ */
+declare class FillerInjector {
+    private readonly phrases;
+    private readonly maxFillers;
+    private fillersUsed;
+    private lastFillerIndex;
+    constructor(phrases: readonly string[], maxFillers: number);
+    /**
+     * Get next filler phrase (returns null if limit reached)
+     */
+    getFiller(): string | null;
+    /**
+     * Reset filler state
+     */
+    reset(): void;
+    /**
+     * Check if more fillers can be injected
+     */
+    canInjectMore(): boolean;
+    /**
+     * Get count of fillers used
+     */
+    getUsedCount(): number;
+}
+
+/**
+ * Buffer manager for barge-in scenarios
+ */
+declare class BufferManager {
+    private buffer;
+    private readonly maxSize;
+    private head;
+    private size;
+    constructor(maxSize?: number);
+    /**
+     * Add chunk to buffer
+     */
+    add(chunk: string): void;
+    /**
+     * Get all buffered chunks in order
+     */
+    getAll(): readonly string[];
+    /**
+     * Clear all buffered chunks
+     */
+    clear(): void;
+    /**
+     * Get current buffer size
+     */
+    getSize(): number;
+    /**
+     * Check if buffer is empty
+     */
+    isEmpty(): boolean;
+    /**
+     * Check if buffer is full
+     */
+    isFull(): boolean;
+}
+
+export { BufferManager, ConversationState, ConversationStateMachine, DEFAULT_FILLER_PHRASES, DEFAULT_MAX_FILLERS_PER_RESPONSE, DEFAULT_STALL_THRESHOLD_MS, FillerInjector, type FlowConfig, FlowController, type FlowEvent, type FlowEventListener, FlowManager, type FlowManagerConfig, type FlowStats, StallDetector, withFlowControl };

package/dist/flow/index.d.ts

@@ -0,0 +1,337 @@
+/**
+ * Configuration for flow control
+ */
+interface FlowConfig {
+    /**
+     * Stall threshold in milliseconds
+     * @default 700
+     */
+    readonly stallThresholdMs?: number;
+    /**
+     * Filler phrases to inject
+     * @default ['um', 'let me think', 'hmm']
+     */
+    readonly fillerPhrases?: readonly string[];
+    /**
+     * Whether to enable filler injection
+     * @default true
+     */
+    readonly enableFillers?: boolean;
+    /**
+     * Maximum number of fillers to inject per response
+     * @default 3
+     */
+    readonly maxFillersPerResponse?: number;
+    /**
+     * Callback when filler is injected
+     */
+    readonly onFillerInjected?: (filler: string) => void;
+    /**
+     * Callback when stall is detected
+     */
+    readonly onStallDetected?: (durationMs: number) => void;
+    /**
+     * Callback when first chunk is emitted
+     */
+    readonly onFirstChunk?: () => void;
+}
+/**
+ * Conversation states
+ */
+declare enum ConversationState {
+    IDLE = "idle",
+    WAITING = "waiting",
+    SPEAKING = "speaking",
+    INTERRUPTED = "interrupted"
+}
+/**
+ * Statistics tracked by flow controller
+ */
+interface FlowStats {
+    readonly fillersInjected: number;
+    readonly stallsDetected: number;
+    readonly chunksProcessed: number;
+    readonly firstChunkTime: number | null;
+    readonly totalDurationMs: number;
+}
+/**
+ * Flow events for low-level API
+ */
+type FlowEvent = {
+    type: 'stall-detected';
+    durationMs: number;
+} | {
+    type: 'filler-injected';
+    filler: string;
+} | {
+    type: 'first-chunk';
+    chunk: string;
+} | {
+    type: 'state-change';
+    from: ConversationState;
+    to: ConversationState;
+} | {
+    type: 'interrupted';
+} | {
+    type: 'chunk-processed';
+    chunk: string;
+} | {
+    type: 'completed';
+    stats: FlowStats;
+};
+/**
+ * Event listener for flow events
+ */
+type FlowEventListener = (event: FlowEvent) => void;
+/**
+ * Configuration for low-level FlowManager
+ */
+interface FlowManagerConfig {
+    /**
+     * Stall threshold in milliseconds
+     * @default 700
+     */
+    readonly stallThresholdMs?: number;
+    /**
+     * Filler phrases to inject
+     * @default ['um', 'let me think', 'hmm']
+     */
+    readonly fillerPhrases?: readonly string[];
+    /**
+     * Whether to enable filler injection
+     * @default true
+     */
+    readonly enableFillers?: boolean;
+    /**
+     * Maximum number of fillers to inject per response
+     * @default 3
+     */
+    readonly maxFillersPerResponse?: number;
+    /**
+     * Buffer size for barge-in scenarios
+     * @default 10
+     */
+    readonly bufferSize?: number;
+}
+
+/**
+ * High-level stream wrapper for flow control
+ */
+declare class FlowController {
+    private readonly config;
+    private readonly stateMachine;
+    private readonly stallDetector;
+    private readonly fillerInjector;
+    private readonly bufferManager;
+    private firstChunkEmitted;
+    private stats;
+    private startTime;
+    constructor(config?: FlowConfig);
+    /**
+     * Wrap an async iterable with flow control
+     */
+    wrap(input: AsyncIterable<string>): AsyncIterable<string>;
+    /**
+     * Interrupt the current flow (for barge-in)
+     */
+    interrupt(): void;
+    /**
+     * Get current conversation state
+     */
+    getState(): ConversationState;
+    /**
+     * Get flow statistics
+     */
+    getStats(): FlowStats;
+    /**
+     * Get buffered chunks (for advanced barge-in scenarios)
+     */
+    getBufferedChunks(): readonly string[];
+    private handleStall;
+    private reset;
+}
+/**
+ * Convenience function to create and use flow controller
+ */
+declare function withFlowControl(input: AsyncIterable<string>, config?: FlowConfig): AsyncIterable<string>;
+
+/**
+ * Low-level event-based flow manager
+ */
+declare class FlowManager {
+    private readonly config;
+    private readonly stateMachine;
+    private readonly stallDetector;
+    private readonly fillerInjector;
+    private readonly bufferManager;
+    private readonly listeners;
+    private firstChunkEmitted;
+    private stats;
+    private startTime;
+    private stateChangeUnsubscribe;
+    constructor(config?: FlowManagerConfig);
+    /**
+     * Add event listener
+     */
+    on(listener: FlowEventListener): () => void;
+    /**
+     * Start flow tracking
+     */
+    start(): void;
+    /**
+     * Process a chunk from the stream
+     */
+    processChunk(chunk: string): void;
+    /**
+     * Complete the flow
+     */
+    complete(): void;
+    /**
+     * Interrupt the flow (for barge-in)
+     */
+    interrupt(): void;
+    /**
+     * Get current conversation state
+     */
+    getState(): ConversationState;
+    /**
+     * Get flow statistics
+     */
+    getStats(): FlowStats;
+    /**
+     * Get buffered chunks
+     */
+    getBufferedChunks(): readonly string[];
+    private handleStall;
+    private emit;
+    private reset;
+}
+
+/**
+ * Conversation state machine
+ */
+declare class ConversationStateMachine {
+    private currentState;
+    private readonly listeners;
+    /**
+     * Get current state
+     */
+    getState(): ConversationState;
+    /**
+     * Attempt to transition to new state
+     */
+    transition(to: ConversationState): boolean;
+    /**
+     * Add state change listener
+     */
+    onStateChange(listener: (from: ConversationState, to: ConversationState) => void): () => void;
+    /**
+     * Reset to IDLE
+     */
+    reset(): void;
+}
+
+/**
+ * Default stall threshold in milliseconds
+ * Based on human perception of silence: 500-1000ms feels like a pause
+ * Most LLM APIs stream chunks every 50-200ms when active
+ */
+declare const DEFAULT_STALL_THRESHOLD_MS = 700;
+/**
+ * Default filler phrases to inject during stalls
+ */
+declare const DEFAULT_FILLER_PHRASES: string[];
+/**
+ * Default maximum fillers per response
+ * Prevents over-use of filler words
+ */
+declare const DEFAULT_MAX_FILLERS_PER_RESPONSE = 3;
+
+/**
+ * Detects stream stalls based on timing
+ */
+declare class StallDetector {
+    private lastChunkTime;
+    private stallTimer;
+    private readonly thresholdMs;
+    private readonly onStall;
+    constructor(thresholdMs: number, onStall: (durationMs: number) => void);
+    /**
+     * Notify detector that a chunk was received
+     */
+    notifyChunk(): void;
+    /**
+     * Start monitoring for stalls
+     */
+    start(): void;
+    /**
+     * Stop monitoring
+     */
+    stop(): void;
+    private scheduleStallCheck;
+    private clearTimer;
+}
+
+/**
+ * Manages filler phrase injection
+ */
+declare class FillerInjector {
+    private readonly phrases;
+    private readonly maxFillers;
+    private fillersUsed;
+    private lastFillerIndex;
+    constructor(phrases: readonly string[], maxFillers: number);
+    /**
+     * Get next filler phrase (returns null if limit reached)
+     */
+    getFiller(): string | null;
+    /**
+     * Reset filler state
+     */
+    reset(): void;
+    /**
+     * Check if more fillers can be injected
+     */
+    canInjectMore(): boolean;
+    /**
+     * Get count of fillers used
+     */
+    getUsedCount(): number;
+}
+
+/**
+ * Buffer manager for barge-in scenarios
+ */
+declare class BufferManager {
+    private buffer;
+    private readonly maxSize;
+    private head;
+    private size;
+    constructor(maxSize?: number);
+    /**
+     * Add chunk to buffer
+     */
+    add(chunk: string): void;
+    /**
+     * Get all buffered chunks in order
+     */
+    getAll(): readonly string[];
+    /**
+     * Clear all buffered chunks
+     */
+    clear(): void;
+    /**
+     * Get current buffer size
+     */
+    getSize(): number;
+    /**
+     * Check if buffer is empty
+     */
+    isEmpty(): boolean;
+    /**
+     * Check if buffer is full
+     */
+    isFull(): boolean;
+}
+
+export { BufferManager, ConversationState, ConversationStateMachine, DEFAULT_FILLER_PHRASES, DEFAULT_MAX_FILLERS_PER_RESPONSE, DEFAULT_STALL_THRESHOLD_MS, FillerInjector, type FlowConfig, FlowController, type FlowEvent, type FlowEventListener, FlowManager, type FlowManagerConfig, type FlowStats, StallDetector, withFlowControl };