modular-voice-agent-sdk 1.0.0

package/dist/services/llm-logger.js

@@ -0,0 +1,275 @@
+/**
+ * LLM Logger Service
+ *
+ * Provides structured, backend-agnostic logging for LLM interactions.
+ * Backends emit structured events, the logger handles all formatting.
+ */
+// ============================================================================
+// Logger Implementation
+// ============================================================================
+/**
+ * Formats and displays structured LLM log events
+ * All formatting (colors, icons, layout) is centralized here
+ */
+export class LLMLogger {
+    static COLORS = {
+        reset: '\x1b[0m',
+        dim: '\x1b[2m',
+        cyan: '\x1b[36m',
+        yellow: '\x1b[33m',
+        green: '\x1b[32m',
+        magenta: '\x1b[35m',
+        blue: '\x1b[34m',
+        red: '\x1b[31m',
+    };
+    static ICONS = {
+        system: '⚙',
+        user: '👤',
+        toolCall: '🔧',
+        toolResult: '✓',
+        response: '💬',
+        error: '✗',
+        arrow: '→',
+    };
+    enabled;
+    constructor(options = {}) {
+        this.enabled = options.enabled ?? true;
+    }
+    /**
+     * Log a structured event
+     */
+    log(event) {
+        if (!this.enabled)
+            return;
+        const { COLORS: C, ICONS } = LLMLogger;
+        switch (event.type) {
+            case 'new_conversation':
+                console.log(`\n${C.cyan}━━━━━━━━━━━━━━ NEW CONVERSATION ━━━━━━━━━━━━━━${C.reset}`);
+                break;
+            case 'llm_call_start':
+                console.log(`\n${C.dim}┌───────────────────────────────────────────────${C.reset}`);
+                if (event.isFirstCall) {
+                    console.log(`${C.dim}│${C.reset} ${C.cyan}LLM${C.reset}`);
+                }
+                else {
+                    console.log(`${C.dim}│${C.reset} ${C.cyan}LLM${C.reset} ${C.dim}(continued)${C.reset}`);
+                }
+                console.log(`${C.dim}├───────────────────────────────────────────────${C.reset}`);
+                break;
+            case 'llm_call_output':
+                console.log(`${C.dim}├─────────────────── ${C.reset}${C.cyan}output${C.reset} ${C.dim}─────────────────${C.reset}`);
+                break;
+            case 'llm_call_end':
+                console.log(`${C.dim}└───────────────────────────────────────────────${C.reset}\n`);
+                break;
+            case 'system': {
+                const lines = event.content.split('\n');
+                console.log(`${C.dim}│${C.reset} ${ICONS.system} ${C.magenta}SYSTEM${C.reset}`);
+                for (const line of lines) {
+                    console.log(`${C.dim}│${C.reset}   ${C.dim}${line}${C.reset}`);
+                }
+                break;
+            }
+            case 'user':
+                console.log(`${C.dim}│${C.reset} ${ICONS.user} ${C.yellow}USER${C.reset}: ${event.content}`);
+                break;
+            case 'tool_call': {
+                const argsStr = this.formatArgs(event.args);
+                console.log(`${C.dim}│${C.reset} ${ICONS.arrow} ${ICONS.toolCall} ${C.blue}${event.name}${C.reset}(${C.dim}${argsStr}${C.reset})`);
+                break;
+            }
+            case 'tool_result':
+                console.log(`${C.dim}│${C.reset} ${ICONS.toolResult} ${C.green}RESULT${C.reset}: ${C.dim}${event.content}${C.reset}`);
+                break;
+            case 'assistant':
+                console.log(`${C.dim}│${C.reset} ${ICONS.response} ${C.green}ASSISTANT${C.reset}: ${event.content}`);
+                break;
+            case 'response':
+                console.log(`${C.dim}│${C.reset} ${ICONS.arrow} ${ICONS.response} ${event.content}`);
+                break;
+            case 'error':
+                console.log(`${C.dim}│${C.reset} ${ICONS.error} ${C.red}ERROR${C.reset}: ${event.message}`);
+                break;
+        }
+    }
+    /**
+     * Format tool arguments for display
+     */
+    formatArgs(args) {
+        const entries = Object.entries(args);
+        if (entries.length === 0)
+            return '';
+        return entries.map(([k, v]) => `${k}=${JSON.stringify(v)}`).join(', ');
+    }
+    /**
+     * Enable or disable logging
+     */
+    setEnabled(enabled) {
+        this.enabled = enabled;
+    }
+}
+/**
+ * Tracks conversation state and emits structured events for new messages.
+ * Works with Message[] arrays directly - used by all backends.
+ * Supports multiple simultaneous conversations via conversation IDs.
+ */
+export class LLMConversationTracker {
+    conversations = new Map();
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /**
+     * Get or create state for a conversation
+     */
+    getState(conversationId) {
+        let state = this.conversations.get(conversationId);
+        if (!state) {
+            // New conversation!
+            state = { loggedMessages: [], callCount: 0 };
+            this.conversations.set(conversationId, state);
+            this.logger.log({ type: 'new_conversation' });
+        }
+        return state;
+    }
+    /**
+     * Process messages array and emit events for new messages
+     */
+    logInput(conversationId, messages) {
+        const state = this.getState(conversationId);
+        // Find which messages are new
+        const newMessages = [];
+        for (let i = 0; i < messages.length; i++) {
+            const msgKey = this.messageKey(messages[i]);
+            if (i >= state.loggedMessages.length || state.loggedMessages[i] !== msgKey) {
+                newMessages.push(messages[i]);
+                state.loggedMessages[i] = msgKey;
+            }
+        }
+        state.loggedMessages.length = messages.length;
+        const isFirstCall = state.callCount === 0;
+        state.callCount++;
+        // Emit events
+        this.logger.log({ type: 'llm_call_start', isFirstCall });
+        for (const msg of newMessages) {
+            this.emitMessageEvent(msg);
+        }
+    }
+    /**
+     * Log an LLM response (text content and/or tool calls)
+     */
+    logOutput(conversationId, content, toolCalls) {
+        // Ensure conversation exists (in case logOutput is called without logInput)
+        this.getState(conversationId);
+        this.logger.log({ type: 'llm_call_output' });
+        if (toolCalls && toolCalls.length > 0) {
+            for (const tc of toolCalls) {
+                this.logger.log({ type: 'tool_call', name: tc.name, args: tc.arguments });
+            }
+        }
+        else if (content) {
+            this.logger.log({ type: 'response', content });
+        }
+        this.logger.log({ type: 'llm_call_end' });
+    }
+    /**
+     * Log a raw response string (for backends that return tool calls as formatted strings)
+     * Parses <tool_call> tags and handles accordingly
+     */
+    logRawOutput(conversationId, response) {
+        const toolCall = this.parseToolCall(response);
+        if (toolCall) {
+            this.logOutput(conversationId, '', [toolCall]);
+        }
+        else {
+            this.logOutput(conversationId, response);
+        }
+    }
+    /**
+     * Remove a conversation's tracking state (called when session ends)
+     */
+    removeConversation(conversationId) {
+        this.conversations.delete(conversationId);
+    }
+    /**
+     * Reset tracker state for a specific conversation
+     */
+    resetConversation(conversationId) {
+        this.conversations.delete(conversationId);
+    }
+    /**
+     * Reset all tracker state (e.g., for testing)
+     */
+    reset() {
+        this.conversations.clear();
+    }
+    /**
+     * Generate a unique key for a message (for deduplication)
+     */
+    messageKey(msg) {
+        if (msg.toolCalls && msg.toolCalls.length > 0) {
+            return `${msg.role}:toolcalls:${JSON.stringify(msg.toolCalls)}`;
+        }
+        return `${msg.role}:${msg.content}`;
+    }
+    /**
+     * Emit the appropriate log event for a message
+     */
+    emitMessageEvent(msg) {
+        switch (msg.role) {
+            case 'system':
+                this.logger.log({ type: 'system', content: msg.content });
+                break;
+            case 'user':
+                this.logger.log({ type: 'user', content: msg.content });
+                break;
+            case 'assistant':
+                // Skip assistant messages in input - they're our previous outputs
+                // We don't need to show them again
+                break;
+            case 'tool':
+                this.logger.log({ type: 'tool_result', content: msg.content });
+                break;
+        }
+    }
+    /**
+     * Parse tool call from SmolLM2/HuggingFace format: <tool_call>[...]</tool_call>
+     */
+    parseToolCall(content) {
+        const match = content.match(/<tool_call>\s*([\s\S]*?)\s*<\/tool_call>/);
+        if (!match)
+            return null;
+        try {
+            const parsed = JSON.parse(match[1].trim());
+            const call = Array.isArray(parsed) ? parsed[0] : parsed;
+            return { name: call.name, arguments: call.arguments || {} };
+        }
+        catch {
+            return null;
+        }
+    }
+}
+// ============================================================================
+// Singleton instance for convenience
+// ============================================================================
+let defaultLogger = null;
+let defaultTracker = null;
+/**
+ * Get the default logger instance (creates one if needed)
+ */
+export function getDefaultLogger() {
+    if (!defaultLogger) {
+        defaultLogger = new LLMLogger();
+    }
+    return defaultLogger;
+}
+/**
+ * Get the default tracker instance (creates one if needed)
+ */
+export function getDefaultTracker() {
+    if (!defaultTracker) {
+        defaultTracker = new LLMConversationTracker(getDefaultLogger());
+    }
+    return defaultTracker;
+}
+//# sourceMappingURL=llm-logger.js.map

package/dist/services/llm-logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-logger.js","sourceRoot":"","sources":["../../src/services/llm-logger.ts"],"names":[],"mappings":"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"}

package/dist/services/text-normalizer.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Text Normalizer
+ * Converts text to TTS-friendly format
+ */
+export declare class TextNormalizer {
+    normalize(text: string): string;
+    private normalizeTimes;
+    private normalizeDecimalNumbers;
+    private normalizeOrdinals;
+    private normalizeCurrency;
+    private normalizePercentages;
+    private normalizeYears;
+    private normalizeStandaloneNumbers;
+    private normalizeSymbols;
+    private normalizePunctuation;
+}
+//# sourceMappingURL=text-normalizer.d.ts.map

package/dist/services/text-normalizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-normalizer.d.ts","sourceRoot":"","sources":["../../src/services/text-normalizer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,qBAAa,cAAc;IACzB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;IAe/B,OAAO,CAAC,cAAc;IActB,OAAO,CAAC,uBAAuB;IAQ/B,OAAO,CAAC,iBAAiB;IAIzB,OAAO,CAAC,iBAAiB;IAczB,OAAO,CAAC,oBAAoB;IAI5B,OAAO,CAAC,cAAc;IAkBtB,OAAO,CAAC,0BAA0B;IAIlC,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,oBAAoB;CAU7B"}

package/dist/services/text-normalizer.js

@@ -0,0 +1,100 @@
+/**
+ * Text Normalizer
+ * Converts text to TTS-friendly format
+ */
+import numberToWords from 'number-to-words';
+const { toWords, toWordsOrdinal } = numberToWords;
+export class TextNormalizer {
+    normalize(text) {
+        let result = text;
+        result = this.normalizeTimes(result);
+        result = this.normalizeDecimalNumbers(result);
+        result = this.normalizeOrdinals(result);
+        result = this.normalizeCurrency(result);
+        result = this.normalizePercentages(result);
+        result = this.normalizeYears(result);
+        result = this.normalizeStandaloneNumbers(result);
+        result = this.normalizeSymbols(result);
+        result = this.normalizePunctuation(result);
+        result = result.replace(/\s+/g, ' ').trim();
+        return result;
+    }
+    normalizeTimes(text) {
+        return text.replace(/\b(\d{1,2}):(\d{2})\s*(AM|PM|am|pm)?\b/g, (_, hourStr, minuteStr, period) => {
+            const hour = parseInt(hourStr, 10);
+            const minute = parseInt(minuteStr, 10);
+            const hourWord = toWords(hour);
+            let minuteWord = minute === 0 ? '' : minute < 10 ? 'oh ' + toWords(minute) : toWords(minute);
+            const periodWord = period ? ' ' + period.toUpperCase().split('').join(' ') : '';
+            return (hourWord + ' ' + minuteWord + periodWord).trim();
+        });
+    }
+    normalizeDecimalNumbers(text) {
+        return text.replace(/(\d+)\.(\d+)/g, (_, whole, decimal) => {
+            const wholeWords = toWords(parseInt(whole, 10));
+            const decimalDigits = decimal.split('').map((d) => toWords(parseInt(d, 10))).join(' ');
+            return `${wholeWords} point ${decimalDigits}`;
+        });
+    }
+    normalizeOrdinals(text) {
+        return text.replace(/(\d+)(st|nd|rd|th)\b/gi, (_, num) => toWordsOrdinal(parseInt(num, 10)));
+    }
+    normalizeCurrency(text) {
+        let result = text.replace(/\$(\d+)\.(\d{2})\b/g, (_, dollars, cents) => {
+            const d = parseInt(dollars, 10);
+            const c = parseInt(cents, 10);
+            let phrase = toWords(d) + (d === 1 ? ' dollar' : ' dollars');
+            if (c > 0)
+                phrase += ' and ' + toWords(c) + (c === 1 ? ' cent' : ' cents');
+            return phrase;
+        });
+        return result.replace(/\$(\d+)\b/g, (_, dollars) => {
+            const d = parseInt(dollars, 10);
+            return toWords(d) + (d === 1 ? ' dollar' : ' dollars');
+        });
+    }
+    normalizePercentages(text) {
+        return text.replace(/(\d+)%/g, (_, num) => toWords(parseInt(num, 10)) + ' percent');
+    }
+    normalizeYears(text) {
+        return text.replace(/\b(1\d{3}|2\d{3})\b/g, (match) => {
+            const year = parseInt(match, 10);
+            if (year >= 2000 && year < 2010)
+                return 'two thousand ' + (year === 2000 ? '' : toWords(year - 2000));
+            if (year >= 2010 && year < 3000) {
+                const first = Math.floor(year / 100);
+                const last = year % 100;
+                return toWords(first) + ' ' + (last < 10 ? 'oh ' + toWords(last) : toWords(last));
+            }
+            if (year >= 1000 && year < 2000) {
+                const first = Math.floor(year / 100);
+                const last = year % 100;
+                return toWords(first) + ' ' + (last === 0 ? 'hundred' : last < 10 ? 'oh ' + toWords(last) : toWords(last));
+            }
+            return toWords(year);
+        });
+    }
+    normalizeStandaloneNumbers(text) {
+        return text.replace(/\b(\d+)\b/g, (match) => toWords(parseInt(match, 10)));
+    }
+    normalizeSymbols(text) {
+        return text
+            .replace(/&/g, ' and ')
+            .replace(/@/g, ' at ')
+            .replace(/\+/g, ' plus ')
+            .replace(/=/g, ' equals ')
+            .replace(/#(\w+)/g, 'hashtag $1')
+            .replace(/#/g, ' number ');
+    }
+    normalizePunctuation(text) {
+        return text
+            .replace(/\.\.\./g, ', ')
+            .replace(/[;:]/g, ', ')
+            .replace(/[()[\]{}]/g, ' ')
+            .replace(/[""«»]/g, '')
+            .replace(/(?<!\w)[''']|['''](?!\w)/g, '')
+            .replace(/[*_~`]/g, '')
+            .replace(/-/g, ' ');
+    }
+}
+//# sourceMappingURL=text-normalizer.js.map

package/dist/services/text-normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"text-normalizer.js","sourceRoot":"","sources":["../../src/services/text-normalizer.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,195 @@
+/**
+ * Voice Pipeline Library - Type Definitions
+ */
+/**
+ * JSON Schema for tool parameters
+ */
+export interface ToolParameterSchema {
+    type: 'object';
+    properties: Record<string, {
+        type: string;
+        description?: string;
+        enum?: string[];
+    }>;
+    required?: string[];
+}
+/**
+ * Tool definition - describes a callable function
+ */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters: ToolParameterSchema;
+}
+/**
+ * Registered tool with execute function
+ */
+export interface Tool extends ToolDefinition {
+    execute: (args: Record<string, unknown>) => Promise<unknown> | unknown;
+}
+/**
+ * Tool call request from LLM
+ */
+export interface ToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+/**
+ * Result of executing a tool
+ */
+export interface ToolResult {
+    toolCallId: string;
+    result: unknown;
+    error?: string;
+}
+export type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+export interface BaseMessage {
+    role: MessageRole;
+    content: string;
+}
+export interface ToolMessage extends BaseMessage {
+    role: 'tool';
+    toolCallId: string;
+}
+export interface AssistantMessage extends BaseMessage {
+    role: 'assistant';
+    toolCalls?: ToolCall[];
+}
+export type Message = BaseMessage | ToolMessage | AssistantMessage;
+export interface AudioResult {
+    audio: Float32Array;
+    sampleRate: number;
+}
+/**
+ * AudioPlayable - Uniform interface for TTS output
+ * Allows backends to either provide raw audio data OR direct playback
+ */
+export interface AudioPlayable {
+    /** Get raw audio data (null if backend doesn't support raw audio, e.g., Web Speech) */
+    getRawAudio(): AudioResult | null;
+    /** Play the audio - works uniformly across all backends */
+    play(): Promise<void>;
+    /** Stop playback */
+    stop(): void;
+}
+/**
+ * BufferedAudioPlayable - For backends that produce raw audio data
+ * Used by: Native TTS, Transformers TTS
+ */
+export declare class BufferedAudioPlayable implements AudioPlayable {
+    private audio;
+    private sampleRate;
+    private audioContext;
+    private sourceNode;
+    constructor(audio: Float32Array, sampleRate: number);
+    getRawAudio(): AudioResult;
+    play(): Promise<void>;
+    stop(): void;
+}
+export interface ProgressInfo {
+    status: 'initiate' | 'download' | 'progress' | 'done' | 'ready';
+    file?: string;
+    progress?: number;
+    loaded?: number;
+    total?: number;
+}
+export type ProgressCallback = (progress: ProgressInfo) => void;
+export interface STTPipeline {
+    initialize(onProgress?: ProgressCallback): Promise<void>;
+    transcribe(audio: Float32Array): Promise<string>;
+    isReady(): boolean;
+}
+/**
+ * LLM generation options
+ */
+export interface LLMGenerateOptions {
+    /** Tools available for the LLM to call */
+    tools?: ToolDefinition[];
+    /** Callback for streaming tokens */
+    onToken?: (token: string) => void;
+    /** Callback when tool calls are detected */
+    onToolCall?: (toolCall: ToolCall) => void;
+    /** Conversation ID for tracking/logging (supports multiple simultaneous conversations) */
+    conversationId?: string;
+}
+/**
+ * LLM generation result
+ */
+export interface LLMGenerateResult {
+    /** Text content of the response */
+    content: string;
+    /** Tool calls requested by the LLM (if any) */
+    toolCalls?: ToolCall[];
+    /** Whether the response is complete or waiting for tool results */
+    finishReason: 'stop' | 'tool_calls';
+}
+export interface LLMPipeline {
+    initialize(onProgress?: ProgressCallback): Promise<void>;
+    /**
+     * Generate a response from the LLM
+     * @param messages - Conversation history
+     * @param options - Generation options including tools and callbacks
+     * @returns Generation result with content and optional tool calls
+     */
+    generate(messages: Message[], options?: LLMGenerateOptions): Promise<LLMGenerateResult>;
+    /** @deprecated Use generate() with options.onToken instead */
+    generateLegacy?(messages: Message[], onToken: (token: string) => void): Promise<string>;
+    isReady(): boolean;
+    /** Whether this backend supports native tool calling */
+    supportsTools?(): boolean;
+}
+export interface TTSPipeline {
+    initialize(onProgress?: ProgressCallback): Promise<void>;
+    synthesize(text: string): Promise<AudioPlayable>;
+    isReady(): boolean;
+}
+export interface TransformersSTTConfig {
+    model: string;
+    dtype: string;
+    language?: string;
+    device?: 'webgpu' | 'cpu';
+}
+export interface TransformersLLMConfig {
+    model: string;
+    dtype: string;
+    maxNewTokens: number;
+    temperature: number;
+    device?: 'webgpu' | 'cpu';
+}
+export interface TransformersTTSConfig {
+    model: string;
+    dtype: string;
+    speakerEmbeddings: string;
+    device?: 'webgpu' | 'cpu';
+}
+export interface NativeSTTConfig {
+    binaryPath: string;
+    modelPath: string;
+    language: string;
+}
+export interface NativeLLMConfig {
+    binaryPath: string;
+    modelPath: string;
+    maxNewTokens: number;
+    temperature: number;
+    gpuLayers?: number;
+}
+export interface NativeTTSConfig {
+    binaryPath: string;
+    modelPath: string;
+}
+export interface SherpaOnnxTTSConfig {
+    binaryPath: string;
+    modelDir: string;
+    speakerId?: number;
+    speedScale?: number;
+}
+export interface CloudLLMConfig {
+    baseUrl: string;
+    apiKey?: string;
+    model: string;
+    maxTokens?: number;
+    temperature?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,48 @@
+/**
+ * Voice Pipeline Library - Type Definitions
+ */
+/**
+ * BufferedAudioPlayable - For backends that produce raw audio data
+ * Used by: Native TTS, Transformers TTS
+ */
+export class BufferedAudioPlayable {
+    audio;
+    sampleRate;
+    audioContext = null;
+    sourceNode = null;
+    constructor(audio, sampleRate) {
+        this.audio = audio;
+        this.sampleRate = sampleRate;
+    }
+    getRawAudio() {
+        return { audio: this.audio, sampleRate: this.sampleRate };
+    }
+    async play() {
+        if (this.audio.length === 0)
+            return;
+        // Create AudioContext on demand (handles browser autoplay policies)
+        if (!this.audioContext) {
+            this.audioContext = new AudioContext({ sampleRate: this.sampleRate });
+        }
+        // Resume if suspended (browser autoplay policy)
+        if (this.audioContext.state === 'suspended') {
+            await this.audioContext.resume();
+        }
+        const audioBuffer = this.audioContext.createBuffer(1, this.audio.length, this.sampleRate);
+        // Copy data to channel (create a standard Float32Array to satisfy TS)
+        const channelData = audioBuffer.getChannelData(0);
+        channelData.set(this.audio);
+        this.sourceNode = this.audioContext.createBufferSource();
+        this.sourceNode.buffer = audioBuffer;
+        this.sourceNode.connect(this.audioContext.destination);
+        return new Promise((resolve) => {
+            this.sourceNode.onended = () => resolve();
+            this.sourceNode.start();
+        });
+    }
+    stop() {
+        this.sourceNode?.stop();
+        this.sourceNode = null;
+    }
+}
+//# sourceMappingURL=types.js.map