modular-voice-agent-sdk 1.0.0

package/dist/server/handler.js

@@ -0,0 +1,224 @@
+/**
+ * Pipeline Handler
+ *
+ * Framework-agnostic session handler for voice pipeline servers.
+ * Supports capability negotiation - skips STT/TTS when client handles them.
+ * Each session has its own conversation history and conversation ID.
+ */
+import { float32ToBase64Node, base64ToFloat32Node, concatFloat32Arrays } from './encoding';
+/**
+ * Generate a unique conversation ID
+ */
+function generateConversationId() {
+    return `conv-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+}
+/**
+ * A session represents a single client connection.
+ * Each session has its own conversation history and ID.
+ */
+export class PipelineSession {
+    pipeline;
+    audioChunks = [];
+    destroyed = false;
+    capabilities = {
+        hasSTT: false,
+        hasTTS: false,
+    };
+    /** Session's conversation history */
+    history = [];
+    /** Unique conversation ID for this session */
+    conversationId;
+    constructor(pipeline) {
+        this.pipeline = pipeline;
+        this.conversationId = generateConversationId();
+        // Initialize history with system prompt
+        this.history = [{ role: 'system', content: this.pipeline.getSystemPrompt() }];
+    }
+    /**
+     * Get the conversation context for this session
+     */
+    getContext() {
+        return {
+            conversationId: this.conversationId,
+            history: this.history,
+        };
+    }
+    /**
+     * Handle an incoming message and yield response messages
+     */
+    async *handle(message) {
+        if (this.destroyed)
+            return;
+        switch (message.type) {
+            case 'capabilities':
+                // Client is telling us what it handles locally
+                this.capabilities = {
+                    hasSTT: message.hasSTT,
+                    hasTTS: message.hasTTS,
+                };
+                break;
+            case 'audio':
+                this.audioChunks.push(base64ToFloat32Node(message.data));
+                break;
+            case 'end_audio':
+                yield* this.processAudio();
+                break;
+            case 'text':
+                // Client did STT locally - process text directly
+                yield* this.processText(message.text);
+                break;
+            case 'clear_history':
+                // Reset session history and get a new conversation ID
+                this.conversationId = generateConversationId();
+                this.history = [{ role: 'system', content: this.pipeline.getSystemPrompt() }];
+                break;
+        }
+    }
+    /**
+     * Get client capabilities
+     */
+    getCapabilities() {
+        return { ...this.capabilities };
+    }
+    /**
+     * Process accumulated audio through the pipeline (STT → LLM → TTS)
+     */
+    async *processAudio() {
+        if (this.audioChunks.length === 0)
+            return;
+        if (!this.pipeline.hasSTT()) {
+            yield { type: 'error', message: 'No STT backend configured on server. Client should use local STT and send text.' };
+            return;
+        }
+        const audio = concatFloat32Arrays(this.audioChunks);
+        this.audioChunks = [];
+        yield* this.runPipeline((callbacks) => this.pipeline.processAudio(audio, this.getContext(), callbacks));
+    }
+    /**
+     * Process text through the pipeline (LLM → TTS)
+     */
+    async *processText(text) {
+        // Emit the transcript so client knows what was received
+        // (useful for debugging, client can ignore if it already has transcript)
+        yield { type: 'transcript', text };
+        yield* this.runPipeline((callbacks) => this.pipeline.processText(text, this.getContext(), callbacks));
+    }
+    /**
+     * Run the pipeline and yield messages as they arrive
+     */
+    async *runPipeline(run) {
+        const messageQueue = [];
+        let resolveWaiting = null;
+        let isComplete = false;
+        const enqueue = (msg) => {
+            messageQueue.push(msg);
+            if (resolveWaiting) {
+                resolveWaiting();
+                resolveWaiting = null;
+            }
+        };
+        // Determine what to skip based on client capabilities
+        const skipTTS = this.capabilities.hasTTS || !this.pipeline.hasTTS();
+        // Start pipeline processing
+        const pipelinePromise = run({
+            onTranscript: (text) => enqueue({ type: 'transcript', text }),
+            onResponseChunk: (text) => enqueue({ type: 'response_chunk', text }),
+            onAudio: (playable) => {
+                // Skip audio if client handles TTS locally
+                if (skipTTS)
+                    return;
+                const raw = playable.getRawAudio();
+                if (!raw) {
+                    // TTS backend doesn't provide raw audio (e.g., WebSpeechTTS)
+                    // This is a config error - server TTS must produce raw audio
+                    enqueue({
+                        type: 'error',
+                        message: 'Server TTS backend does not provide raw audio. Use a TTS backend that produces raw audio (TransformersTTS, NativeTTS), or configure client with localTTS.',
+                    });
+                    isComplete = true;
+                    return;
+                }
+                enqueue({
+                    type: 'audio',
+                    data: float32ToBase64Node(raw.audio),
+                    sampleRate: raw.sampleRate,
+                });
+            },
+            onToolCall: (toolCall) => {
+                enqueue({
+                    type: 'tool_call',
+                    toolCallId: toolCall.id,
+                    name: toolCall.name,
+                    arguments: toolCall.arguments,
+                });
+            },
+            onToolResult: (toolCallId, result) => {
+                enqueue({
+                    type: 'tool_result',
+                    toolCallId,
+                    result,
+                });
+            },
+            onComplete: () => {
+                enqueue({ type: 'complete' });
+                isComplete = true;
+            },
+            onError: (err) => {
+                enqueue({ type: 'error', message: err.message });
+                isComplete = true;
+            },
+        });
+        // Yield messages as they arrive
+        while (!isComplete || messageQueue.length > 0) {
+            if (messageQueue.length > 0) {
+                yield messageQueue.shift();
+            }
+            else if (!isComplete) {
+                await new Promise((resolve) => {
+                    resolveWaiting = resolve;
+                });
+            }
+        }
+        await pipelinePromise;
+    }
+    /**
+     * Clean up session resources
+     */
+    destroy() {
+        this.destroyed = true;
+        this.audioChunks = [];
+    }
+}
+/**
+ * Pipeline handler factory
+ */
+export class PipelineHandler {
+    pipeline;
+    constructor(pipeline, _config = {}) {
+        this.pipeline = pipeline;
+        // Config reserved for future options
+    }
+    /**
+     * Create a new session for a client connection.
+     * Each session has its own conversation history.
+     */
+    createSession() {
+        return new PipelineSession(this.pipeline);
+    }
+    /**
+     * Get info about what the pipeline handles
+     */
+    getPipelineInfo() {
+        return {
+            hasSTT: this.pipeline.hasSTT(),
+            hasTTS: this.pipeline.hasTTS(),
+        };
+    }
+}
+/**
+ * Create a pipeline handler
+ */
+export function createPipelineHandler(pipeline, config) {
+    return new PipelineHandler(pipeline, config);
+}
+//# sourceMappingURL=handler.js.map

package/dist/server/handler.js.map

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

package/dist/server/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Modular Voice Agent SDK - Server Utilities
+ *
+ * Framework-agnostic handlers for building voice assistant servers.
+ * Works with any WebSocket library (ws, Socket.io, Bun, Deno, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { VoicePipeline } from 'modular-voice-agent-sdk';
+ * import { createPipelineHandler } from 'modular-voice-agent-sdk/server';
+ * import { WebSocketServer } from 'ws';
+ *
+ * const pipeline = new VoicePipeline({ stt, llm, tts, systemPrompt });
+ * const handler = createPipelineHandler(pipeline);
+ *
+ * wss.on('connection', (ws) => {
+ *   const session = handler.createSession();
+ *   ws.on('message', async (data) => {
+ *     for await (const msg of session.handle(JSON.parse(data))) {
+ *       ws.send(JSON.stringify(msg));
+ *     }
+ *   });
+ *   ws.on('close', () => session.destroy());
+ * });
+ * ```
+ */
+export { createPipelineHandler, PipelineHandler, PipelineSession } from './handler';
+export type { PipelineHandlerConfig } from './handler';
+export { float32ToBase64, base64ToFloat32, type ClientMessage, type ServerMessage, type AudioMessage, type EndAudioMessage, type ClearHistoryMessage, type TranscriptMessage, type ResponseChunkMessage, type AudioResponseMessage, type CompleteMessage, type ErrorMessage, } from '../client/protocol';
+export { float32ToBase64Node, base64ToFloat32Node } from './encoding';
+//# sourceMappingURL=index.d.ts.map

package/dist/server/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AACpF,YAAY,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAGvD,OAAO,EACL,eAAe,EACf,eAAe,EACf,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,YAAY,GAClB,MAAM,oBAAoB,CAAC;AAG5B,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}

package/dist/server/index.js

@@ -0,0 +1,32 @@
+/**
+ * Modular Voice Agent SDK - Server Utilities
+ *
+ * Framework-agnostic handlers for building voice assistant servers.
+ * Works with any WebSocket library (ws, Socket.io, Bun, Deno, etc.)
+ *
+ * @example
+ * ```typescript
+ * import { VoicePipeline } from 'modular-voice-agent-sdk';
+ * import { createPipelineHandler } from 'modular-voice-agent-sdk/server';
+ * import { WebSocketServer } from 'ws';
+ *
+ * const pipeline = new VoicePipeline({ stt, llm, tts, systemPrompt });
+ * const handler = createPipelineHandler(pipeline);
+ *
+ * wss.on('connection', (ws) => {
+ *   const session = handler.createSession();
+ *   ws.on('message', async (data) => {
+ *     for await (const msg of session.handle(JSON.parse(data))) {
+ *       ws.send(JSON.stringify(msg));
+ *     }
+ *   });
+ *   ws.on('close', () => session.destroy());
+ * });
+ * ```
+ */
+export { createPipelineHandler, PipelineHandler, PipelineSession } from './handler';
+// Re-export protocol types for server use
+export { float32ToBase64, base64ToFloat32, } from '../client/protocol';
+// Server-side encoding utilities (use Buffer for efficiency in Node.js)
+export { float32ToBase64Node, base64ToFloat32Node } from './encoding';
+//# sourceMappingURL=index.js.map

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAGpF,0CAA0C;AAC1C,OAAO,EACL,eAAe,EACf,eAAe,GAWhB,MAAM,oBAAoB,CAAC;AAE5B,wEAAwE;AACxE,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}

package/dist/services/function-service.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Function Service
+ * Registry and executor for LLM tool/function calls
+ */
+import type { ToolDefinition, FunctionCall, FunctionResult } from '../types';
+export declare class FunctionService {
+    private tools;
+    constructor(tools?: ToolDefinition[]);
+    register(tool: ToolDefinition): void;
+    has(name: string): boolean;
+    getDefinitions(): ToolDefinition[];
+    execute(call: FunctionCall): Promise<FunctionResult>;
+    formatForSystemPrompt(): string;
+}
+export declare function containsFunctionCall(text: string): boolean;
+export declare function parseFunctionCall(text: string): FunctionCall;
+//# sourceMappingURL=function-service.d.ts.map

package/dist/services/function-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"function-service.d.ts","sourceRoot":"","sources":["../../src/services/function-service.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE7E,qBAAa,eAAe;IAC1B,OAAO,CAAC,KAAK,CAAqC;gBAEtC,KAAK,GAAE,cAAc,EAAO;IAMxC,QAAQ,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAIpC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,cAAc,IAAI,cAAc,EAAE;IAI5B,OAAO,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC;IAe1D,qBAAqB,IAAI,MAAM;CAmChC;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE1D;AAED,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,CAc5D"}

package/dist/services/function-service.js

@@ -0,0 +1,82 @@
+/**
+ * Function Service
+ * Registry and executor for LLM tool/function calls
+ */
+export class FunctionService {
+    tools = new Map();
+    constructor(tools = []) {
+        for (const tool of tools) {
+            this.register(tool);
+        }
+    }
+    register(tool) {
+        this.tools.set(tool.name, tool);
+    }
+    has(name) {
+        return this.tools.has(name);
+    }
+    getDefinitions() {
+        return Array.from(this.tools.values());
+    }
+    async execute(call) {
+        const tool = this.tools.get(call.name);
+        if (!tool) {
+            return { name: call.name, result: `Unknown tool: "${call.name}"` };
+        }
+        try {
+            const result = await tool.handler(call.arguments);
+            return { name: call.name, result };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { name: call.name, result: `Error: ${message}` };
+        }
+    }
+    formatForSystemPrompt() {
+        const defs = this.getDefinitions();
+        if (defs.length === 0)
+            return '';
+        const tools = defs.map((def) => ({
+            type: 'function',
+            function: {
+                name: def.name,
+                description: def.description,
+                parameters: {
+                    type: 'object',
+                    properties: def.parameters
+                        ? Object.fromEntries(Object.entries(def.parameters).map(([k, v]) => [
+                            k,
+                            { type: v.type, description: v.description },
+                        ]))
+                        : {},
+                    required: def.parameters
+                        ? Object.entries(def.parameters)
+                            .filter(([, v]) => v.required)
+                            .map(([k]) => k)
+                        : [],
+                },
+            },
+        }));
+        let prompt = '\n\nYou have access to these tools:\n';
+        prompt += JSON.stringify(tools, null, 2);
+        prompt += '\n\nWhen you need to use a tool, respond with ONLY:\n';
+        prompt += '<tool_call>[{"name": "function_name", "arguments": {}}]</tool_call>';
+        return prompt;
+    }
+}
+export function containsFunctionCall(text) {
+    return /<tool_call>/.test(text);
+}
+export function parseFunctionCall(text) {
+    const match = text.match(/<tool_call>([\s\S]*?)<\/tool_call>/);
+    if (!match) {
+        throw new Error('No <tool_call> tag found');
+    }
+    const parsed = JSON.parse(match[1].trim());
+    if (Array.isArray(parsed)) {
+        const call = parsed[0];
+        return { name: call.name ?? call.function, arguments: call.arguments ?? {} };
+    }
+    return { name: parsed.name ?? parsed.function, arguments: parsed.arguments ?? {} };
+}
+//# sourceMappingURL=function-service.js.map

package/dist/services/function-service.js.map

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

package/dist/services/index.d.ts

@@ -0,0 +1,4 @@
+export { TextNormalizer } from './text-normalizer';
+export { LLMLogger, LLMConversationTracker, getDefaultLogger, getDefaultTracker } from './llm-logger';
+export type { LLMLogEvent, TrackerMessage } from './llm-logger';
+//# sourceMappingURL=index.d.ts.map

package/dist/services/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACtG,YAAY,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC"}

package/dist/services/index.js

@@ -0,0 +1,3 @@
+export { TextNormalizer } from './text-normalizer';
+export { LLMLogger, LLMConversationTracker, getDefaultLogger, getDefaultTracker } from './llm-logger';
+//# sourceMappingURL=index.js.map

package/dist/services/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC"}

package/dist/services/llm-logger.d.ts

@@ -0,0 +1,136 @@
+/**
+ * LLM Logger Service
+ *
+ * Provides structured, backend-agnostic logging for LLM interactions.
+ * Backends emit structured events, the logger handles all formatting.
+ */
+export type LLMLogEvent = {
+    type: 'new_conversation';
+} | {
+    type: 'llm_call_start';
+    isFirstCall: boolean;
+} | {
+    type: 'llm_call_output';
+} | {
+    type: 'llm_call_end';
+} | {
+    type: 'system';
+    content: string;
+} | {
+    type: 'user';
+    content: string;
+} | {
+    type: 'tool_call';
+    name: string;
+    args: Record<string, unknown>;
+} | {
+    type: 'tool_result';
+    content: string;
+} | {
+    type: 'assistant';
+    content: string;
+} | {
+    type: 'response';
+    content: string;
+} | {
+    type: 'error';
+    message: string;
+};
+/** Message interface for the tracker - mirrors the library's Message type */
+export interface TrackerMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    toolCalls?: Array<{
+        id: string;
+        name: string;
+        arguments: Record<string, unknown>;
+    }>;
+    toolCallId?: string;
+}
+/**
+ * Formats and displays structured LLM log events
+ * All formatting (colors, icons, layout) is centralized here
+ */
+export declare class LLMLogger {
+    private static readonly COLORS;
+    private static readonly ICONS;
+    private enabled;
+    constructor(options?: {
+        enabled?: boolean;
+    });
+    /**
+     * Log a structured event
+     */
+    log(event: LLMLogEvent): void;
+    /**
+     * Format tool arguments for display
+     */
+    private formatArgs;
+    /**
+     * Enable or disable logging
+     */
+    setEnabled(enabled: boolean): void;
+}
+/**
+ * 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 declare class LLMConversationTracker {
+    private conversations;
+    private logger;
+    constructor(logger: LLMLogger);
+    /**
+     * Get or create state for a conversation
+     */
+    private getState;
+    /**
+     * Process messages array and emit events for new messages
+     */
+    logInput(conversationId: string, messages: TrackerMessage[]): void;
+    /**
+     * Log an LLM response (text content and/or tool calls)
+     */
+    logOutput(conversationId: string, content: string, toolCalls?: Array<{
+        name: string;
+        arguments: Record<string, unknown>;
+    }>): void;
+    /**
+     * Log a raw response string (for backends that return tool calls as formatted strings)
+     * Parses <tool_call> tags and handles accordingly
+     */
+    logRawOutput(conversationId: string, response: string): void;
+    /**
+     * Remove a conversation's tracking state (called when session ends)
+     */
+    removeConversation(conversationId: string): void;
+    /**
+     * Reset tracker state for a specific conversation
+     */
+    resetConversation(conversationId: string): void;
+    /**
+     * Reset all tracker state (e.g., for testing)
+     */
+    reset(): void;
+    /**
+     * Generate a unique key for a message (for deduplication)
+     */
+    private messageKey;
+    /**
+     * Emit the appropriate log event for a message
+     */
+    private emitMessageEvent;
+    /**
+     * Parse tool call from SmolLM2/HuggingFace format: <tool_call>[...]</tool_call>
+     */
+    private parseToolCall;
+}
+/**
+ * Get the default logger instance (creates one if needed)
+ */
+export declare function getDefaultLogger(): LLMLogger;
+/**
+ * Get the default tracker instance (creates one if needed)
+ */
+export declare function getDefaultTracker(): LLMConversationTracker;
+//# sourceMappingURL=llm-logger.d.ts.map

package/dist/services/llm-logger.d.ts.map

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