@llmrtc/llmrtc-core 1.0.0

package/dist/logging-hooks.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Pre-built logging hooks for structured logging
+ *
+ * This module provides ready-to-use hooks that log all orchestrator and server
+ * events with structured timing information.
+ *
+ * @example
+ * ```typescript
+ * import { LLMRTCServer, createLoggingHooks } from '@llmrtc/llmrtc-backend';
+ *
+ * const server = new LLMRTCServer({
+ *   providers: { llm, stt, tts },
+ *   hooks: createLoggingHooks({ level: 'info' })
+ * });
+ *
+ * // Output:
+ * // [llmrtc] Connection established: session=abc123
+ * // [llmrtc] Turn started: turn=xyz789 session=abc123
+ * // [llmrtc] STT completed: turn=xyz789 duration=142ms text="Hello there"
+ * // [llmrtc] LLM started: turn=xyz789
+ * // [llmrtc] LLM completed: turn=xyz789 duration=312ms
+ * // [llmrtc] TTS completed: turn=xyz789 duration=89ms
+ * // [llmrtc] Turn completed: turn=xyz789 duration=543ms
+ * ```
+ */
+import type { OrchestratorHooks, ServerHooks } from './hooks.js';
+/**
+ * Log levels in order of verbosity
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+/**
+ * Logger interface compatible with console
+ */
+export interface LoggerLike {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    log: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+/**
+ * Configuration for createLoggingHooks
+ */
+export interface LoggingHooksConfig {
+    /**
+     * Custom logger instance (default: console)
+     * Must implement debug, info, log, warn, error methods
+     */
+    logger?: LoggerLike;
+    /**
+     * Minimum log level (default: 'info')
+     * - 'debug': Log everything including chunk details
+     * - 'info': Log turn lifecycle and timing
+     * - 'warn': Log warnings and errors only
+     * - 'error': Log errors only
+     */
+    level?: LogLevel;
+    /**
+     * Include payloads in logs (default: false)
+     * When true, includes STT text, LLM request/response content, etc.
+     * Warning: May log sensitive data
+     */
+    includePayloads?: boolean;
+    /**
+     * Log prefix (default: '[llmrtc]')
+     */
+    prefix?: string;
+    /**
+     * Include timestamps in logs (default: true)
+     */
+    includeTimestamp?: boolean;
+}
+/**
+ * Create a set of logging hooks for structured logging
+ *
+ * @param config - Configuration options
+ * @returns Combined OrchestratorHooks and ServerHooks
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with console logging
+ * const hooks = createLoggingHooks();
+ *
+ * // Custom logger and level
+ * const hooks = createLoggingHooks({
+ *   logger: pino(),
+ *   level: 'debug',
+ *   includePayloads: true
+ * });
+ *
+ * // Use with LLMRTCServer
+ * const server = new LLMRTCServer({
+ *   providers: { llm, stt, tts },
+ *   hooks: {
+ *     ...createLoggingHooks({ level: 'info' }),
+ *     // Add custom hook
+ *     onLLMEnd(ctx, result) {
+ *       // Custom guardrail
+ *       if (result.fullText.includes('forbidden')) {
+ *         throw new Error('Content policy violation');
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export declare function createLoggingHooks(config?: LoggingHooksConfig): OrchestratorHooks & ServerHooks;
+/**
+ * Create a minimal logging hook that only logs errors
+ */
+export declare function createErrorOnlyHooks(config?: Omit<LoggingHooksConfig, 'level'>): OrchestratorHooks & ServerHooks;
+/**
+ * Create a verbose logging hook that logs everything including chunks
+ */
+export declare function createVerboseHooks(config?: Omit<LoggingHooksConfig, 'level' | 'includePayloads'>): OrchestratorHooks & ServerHooks;
+/**
+ * Create timing-only hooks that just emit timing metrics without logging
+ * Useful when you want metrics without log noise
+ */
+export declare function createTimingHooks(): Pick<OrchestratorHooks, 'onSTTEnd' | 'onLLMEnd' | 'onTTSEnd' | 'onTurnEnd'>;

package/dist/logging-hooks.js

@@ -0,0 +1,280 @@
+/**
+ * Pre-built logging hooks for structured logging
+ *
+ * This module provides ready-to-use hooks that log all orchestrator and server
+ * events with structured timing information.
+ *
+ * @example
+ * ```typescript
+ * import { LLMRTCServer, createLoggingHooks } from '@llmrtc/llmrtc-backend';
+ *
+ * const server = new LLMRTCServer({
+ *   providers: { llm, stt, tts },
+ *   hooks: createLoggingHooks({ level: 'info' })
+ * });
+ *
+ * // Output:
+ * // [llmrtc] Connection established: session=abc123
+ * // [llmrtc] Turn started: turn=xyz789 session=abc123
+ * // [llmrtc] STT completed: turn=xyz789 duration=142ms text="Hello there"
+ * // [llmrtc] LLM started: turn=xyz789
+ * // [llmrtc] LLM completed: turn=xyz789 duration=312ms
+ * // [llmrtc] TTS completed: turn=xyz789 duration=89ms
+ * // [llmrtc] Turn completed: turn=xyz789 duration=543ms
+ * ```
+ */
+// =============================================================================
+// Log Level Utilities
+// =============================================================================
+const LOG_LEVEL_ORDER = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3
+};
+function shouldLog(configLevel, messageLevel) {
+    return LOG_LEVEL_ORDER[messageLevel] >= LOG_LEVEL_ORDER[configLevel];
+}
+// =============================================================================
+// Factory Function
+// =============================================================================
+/**
+ * Create a set of logging hooks for structured logging
+ *
+ * @param config - Configuration options
+ * @returns Combined OrchestratorHooks and ServerHooks
+ *
+ * @example
+ * ```typescript
+ * // Basic usage with console logging
+ * const hooks = createLoggingHooks();
+ *
+ * // Custom logger and level
+ * const hooks = createLoggingHooks({
+ *   logger: pino(),
+ *   level: 'debug',
+ *   includePayloads: true
+ * });
+ *
+ * // Use with LLMRTCServer
+ * const server = new LLMRTCServer({
+ *   providers: { llm, stt, tts },
+ *   hooks: {
+ *     ...createLoggingHooks({ level: 'info' }),
+ *     // Add custom hook
+ *     onLLMEnd(ctx, result) {
+ *       // Custom guardrail
+ *       if (result.fullText.includes('forbidden')) {
+ *         throw new Error('Content policy violation');
+ *       }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export function createLoggingHooks(config = {}) {
+    const { logger = console, level = 'info', includePayloads = false, prefix = '[llmrtc]', includeTimestamp = true } = config;
+    const formatLog = (message, data) => {
+        const timestamp = includeTimestamp ? new Date().toISOString() + ' ' : '';
+        const dataStr = data ? ' ' + Object.entries(data)
+            .map(([k, v]) => `${k}=${typeof v === 'string' ? v : JSON.stringify(v)}`)
+            .join(' ') : '';
+        return `${timestamp}${prefix} ${message}${dataStr}`;
+    };
+    const log = (messageLevel, message, data) => {
+        if (!shouldLog(level, messageLevel))
+            return;
+        const formatted = formatLog(message, data);
+        switch (messageLevel) {
+            case 'debug':
+                logger.debug(formatted);
+                break;
+            case 'info':
+                logger.info ? logger.info(formatted) : logger.log(formatted);
+                break;
+            case 'warn':
+                logger.warn(formatted);
+                break;
+            case 'error':
+                logger.error(formatted);
+                break;
+        }
+    };
+    return {
+        // =========================================================================
+        // Server Hooks
+        // =========================================================================
+        onConnection(sessionId, connectionId) {
+            log('info', 'Connection established', { session: sessionId, connection: connectionId });
+        },
+        onDisconnect(sessionId, timing) {
+            log('info', 'Connection closed', {
+                session: sessionId,
+                duration: `${timing.durationMs}ms`
+            });
+        },
+        onSpeechStart(sessionId, timestamp) {
+            log('debug', 'Speech started', { session: sessionId, timestamp });
+        },
+        onSpeechEnd(sessionId, timestamp, audioDurationMs) {
+            log('debug', 'Speech ended', {
+                session: sessionId,
+                audioDuration: `${audioDurationMs}ms`
+            });
+        },
+        onError(error, context) {
+            log('error', `Error in ${context.component}`, {
+                code: context.code,
+                message: error.message,
+                session: context.sessionId,
+                turn: context.turnId
+            });
+        },
+        // =========================================================================
+        // Turn Lifecycle Hooks
+        // =========================================================================
+        onTurnStart(ctx, audio) {
+            log('info', 'Turn started', {
+                turn: ctx.turnId,
+                session: ctx.sessionId,
+                audioSize: `${audio.length}b`
+            });
+        },
+        onTurnEnd(ctx, timing) {
+            log('info', 'Turn completed', {
+                turn: ctx.turnId,
+                duration: `${timing.durationMs}ms`
+            });
+        },
+        // =========================================================================
+        // STT Hooks
+        // =========================================================================
+        onSTTStart(ctx, audio) {
+            log('debug', 'STT started', {
+                turn: ctx.turnId,
+                audioSize: `${audio.length}b`
+            });
+        },
+        onSTTEnd(ctx, result, timing) {
+            const data = {
+                turn: ctx.turnId,
+                duration: `${timing.durationMs}ms`
+            };
+            if (includePayloads) {
+                data.text = result.text;
+            }
+            log('info', 'STT completed', data);
+        },
+        onSTTError(ctx, error) {
+            log('error', 'STT failed', {
+                turn: ctx.turnId,
+                error: error.message
+            });
+        },
+        // =========================================================================
+        // LLM Hooks
+        // =========================================================================
+        onLLMStart(ctx, request) {
+            const data = {
+                turn: ctx.turnId,
+                messages: request.messages.length
+            };
+            if (includePayloads && request.messages.length > 0) {
+                const lastMsg = request.messages[request.messages.length - 1];
+                data.lastMessage = lastMsg.content.slice(0, 100);
+            }
+            log('debug', 'LLM started', data);
+        },
+        onLLMChunk(ctx, chunk, chunkIndex) {
+            if (chunkIndex === 0) {
+                log('debug', 'LLM first chunk received', { turn: ctx.turnId });
+            }
+        },
+        onLLMEnd(ctx, result, timing) {
+            const data = {
+                turn: ctx.turnId,
+                duration: `${timing.durationMs}ms`,
+                chars: result.fullText.length
+            };
+            if (includePayloads) {
+                data.response = result.fullText.slice(0, 200);
+            }
+            log('info', 'LLM completed', data);
+        },
+        onLLMError(ctx, error) {
+            log('error', 'LLM failed', {
+                turn: ctx.turnId,
+                error: error.message
+            });
+        },
+        // =========================================================================
+        // TTS Hooks
+        // =========================================================================
+        onTTSStart(ctx, text) {
+            const data = {
+                turn: ctx.turnId,
+                textLength: text.length
+            };
+            if (includePayloads) {
+                data.text = text.slice(0, 100);
+            }
+            log('debug', 'TTS started', data);
+        },
+        onTTSChunk(ctx, chunk, chunkIndex) {
+            log('debug', 'TTS chunk', {
+                turn: ctx.turnId,
+                chunk: chunkIndex,
+                size: `${chunk.audio.length}b`
+            });
+        },
+        onTTSEnd(ctx, timing) {
+            log('info', 'TTS completed', {
+                turn: ctx.turnId,
+                duration: `${timing.durationMs}ms`
+            });
+        },
+        onTTSError(ctx, error) {
+            log('error', 'TTS failed', {
+                turn: ctx.turnId,
+                error: error.message
+            });
+        }
+    };
+}
+// =============================================================================
+// Specialized Loggers
+// =============================================================================
+/**
+ * Create a minimal logging hook that only logs errors
+ */
+export function createErrorOnlyHooks(config = {}) {
+    return createLoggingHooks({ ...config, level: 'error' });
+}
+/**
+ * Create a verbose logging hook that logs everything including chunks
+ */
+export function createVerboseHooks(config = {}) {
+    return createLoggingHooks({ ...config, level: 'debug', includePayloads: true });
+}
+/**
+ * Create timing-only hooks that just emit timing metrics without logging
+ * Useful when you want metrics without log noise
+ */
+export function createTimingHooks() {
+    return {
+        onSTTEnd(_ctx, _result, timing) {
+            // Just track timing, no logging
+            void timing;
+        },
+        onLLMEnd(_ctx, _result, timing) {
+            void timing;
+        },
+        onTTSEnd(_ctx, timing) {
+            void timing;
+        },
+        onTurnEnd(_ctx, timing) {
+            void timing;
+        }
+    };
+}
+//# sourceMappingURL=logging-hooks.js.map

package/dist/logging-hooks.js.map

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

package/dist/metrics.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Metrics adapter interface for pluggable metrics reporting
+ *
+ * This module provides a simple interface for emitting metrics that can be
+ * implemented by various backends (Prometheus, StatsD, CloudWatch, etc.)
+ *
+ * @example
+ * ```typescript
+ * // Using console metrics for debugging
+ * const server = new LLMRTCServer({
+ *   providers: { llm, stt, tts },
+ *   metrics: new ConsoleMetrics()
+ * });
+ *
+ * // Using a custom Prometheus adapter
+ * class PrometheusMetrics implements MetricsAdapter {
+ *   private histogram = new promClient.Histogram({
+ *     name: 'llmrtc_duration_ms',
+ *     help: 'Operation duration in milliseconds',
+ *     labelNames: ['operation']
+ *   });
+ *
+ *   timing(name: string, durationMs: number, tags?: Record<string, string>) {
+ *     this.histogram.observe({ operation: name, ...tags }, durationMs);
+ *   }
+ *   // ... other methods
+ * }
+ * ```
+ */
+/**
+ * Standard metric names used by the SDK
+ *
+ * Integrators can use these constants when building dashboards or alerts:
+ *
+ * ```typescript
+ * // Example Prometheus query
+ * // histogram_quantile(0.95, rate(llmrtc_stt_duration_ms_bucket[5m]))
+ * ```
+ */
+export declare const MetricNames: {
+    /** Duration of STT transcription in milliseconds */
+    readonly STT_DURATION: "llmrtc.stt.duration_ms";
+    /** Time to first LLM token in milliseconds */
+    readonly LLM_TTFT: "llmrtc.llm.ttft_ms";
+    /** Total LLM inference duration in milliseconds */
+    readonly LLM_DURATION: "llmrtc.llm.duration_ms";
+    /** Number of tokens generated (when available from provider) */
+    readonly LLM_TOKENS: "llmrtc.llm.tokens";
+    /** Duration of TTS synthesis in milliseconds */
+    readonly TTS_DURATION: "llmrtc.tts.duration_ms";
+    /** Total turn duration (STT + LLM + TTS) in milliseconds */
+    readonly TURN_DURATION: "llmrtc.turn.duration_ms";
+    /** Session duration in milliseconds */
+    readonly SESSION_DURATION: "llmrtc.session.duration_ms";
+    /** Number of active sessions (gauge) */
+    readonly ACTIVE_SESSIONS: "llmrtc.sessions.active";
+    /** Total turns per session */
+    readonly SESSION_TURNS: "llmrtc.session.turns";
+    /** Error counter by type/component */
+    readonly ERRORS: "llmrtc.errors";
+    /** Number of active WebSocket connections */
+    readonly CONNECTIONS: "llmrtc.connections.active";
+    /** Reconnection attempts */
+    readonly RECONNECTIONS: "llmrtc.reconnections";
+    /** Tool execution duration in milliseconds */
+    readonly TOOL_DURATION: "llmrtc.tool.duration_ms";
+    /** Number of tool calls */
+    readonly TOOL_CALLS: "llmrtc.tool.calls";
+    /** Tool call errors */
+    readonly TOOL_ERRORS: "llmrtc.tool.errors";
+    /** Stage duration in milliseconds */
+    readonly STAGE_DURATION: "llmrtc.playbook.stage.duration_ms";
+    /** Number of stage transitions */
+    readonly STAGE_TRANSITIONS: "llmrtc.playbook.transitions";
+    /** Turns per stage */
+    readonly STAGE_TURNS: "llmrtc.playbook.stage.turns";
+    /** Current playbook stage (gauge) */
+    readonly CURRENT_STAGE: "llmrtc.playbook.stage.current";
+    /** Playbook completion counter */
+    readonly PLAYBOOK_COMPLETIONS: "llmrtc.playbook.completions";
+};
+export type MetricName = typeof MetricNames[keyof typeof MetricNames];
+/**
+ * Interface for metrics adapters
+ *
+ * Implement this interface to integrate with your preferred metrics backend.
+ * All methods should be non-blocking and fail silently.
+ */
+export interface MetricsAdapter {
+    /**
+     * Increment a counter metric
+     * @param name - Metric name (use MetricNames constants)
+     * @param value - Value to increment by (default: 1)
+     * @param tags - Optional key-value tags for dimensions
+     *
+     * @example
+     * ```typescript
+     * metrics.increment(MetricNames.ERRORS, 1, { component: 'stt', code: 'STT_ERROR' });
+     * ```
+     */
+    increment(name: string, value?: number, tags?: Record<string, string>): void;
+    /**
+     * Record a timing/histogram metric
+     * @param name - Metric name (use MetricNames constants)
+     * @param durationMs - Duration in milliseconds
+     * @param tags - Optional key-value tags for dimensions
+     *
+     * @example
+     * ```typescript
+     * metrics.timing(MetricNames.STT_DURATION, 150, { provider: 'whisper' });
+     * ```
+     */
+    timing(name: string, durationMs: number, tags?: Record<string, string>): void;
+    /**
+     * Set a gauge metric (current value)
+     * @param name - Metric name (use MetricNames constants)
+     * @param value - Current value
+     * @param tags - Optional key-value tags for dimensions
+     *
+     * @example
+     * ```typescript
+     * metrics.gauge(MetricNames.ACTIVE_SESSIONS, sessionCount);
+     * ```
+     */
+    gauge(name: string, value: number, tags?: Record<string, string>): void;
+}
+/**
+ * No-op metrics adapter (default)
+ *
+ * Use this when metrics collection is disabled or not needed.
+ * All methods are no-ops with minimal overhead.
+ */
+export declare class NoopMetrics implements MetricsAdapter {
+    increment(): void;
+    timing(): void;
+    gauge(): void;
+}
+/**
+ * Console metrics adapter for debugging
+ *
+ * Logs all metrics to the console with timestamps.
+ * Useful during development to verify metrics are being emitted correctly.
+ *
+ * @example
+ * ```typescript
+ * const server = new LLMRTCServer({
+ *   providers: { llm, stt, tts },
+ *   metrics: new ConsoleMetrics({ prefix: 'myapp' })
+ * });
+ *
+ * // Output:
+ * // [metric] myapp.llmrtc.stt.duration_ms 150ms { provider: 'whisper' }
+ * // [metric] myapp.llmrtc.llm.duration_ms 320ms { model: 'gpt-4' }
+ * ```
+ */
+export declare class ConsoleMetrics implements MetricsAdapter {
+    private prefix;
+    constructor(options?: {
+        prefix?: string;
+    });
+    increment(name: string, value?: number, tags?: Record<string, string>): void;
+    timing(name: string, durationMs: number, tags?: Record<string, string>): void;
+    gauge(name: string, value: number, tags?: Record<string, string>): void;
+}
+/**
+ * In-memory metrics collector for testing
+ *
+ * Stores all metrics in arrays for later inspection.
+ * Useful in unit tests to verify metrics are emitted correctly.
+ *
+ * @example
+ * ```typescript
+ * const metrics = new InMemoryMetrics();
+ * const orchestrator = new ConversationOrchestrator({
+ *   providers: { llm, stt, tts },
+ *   metrics
+ * });
+ *
+ * // Run orchestrator...
+ *
+ * // Verify metrics
+ * expect(metrics.timings.find(t => t.name === MetricNames.STT_DURATION)).toBeDefined();
+ * expect(metrics.getLatestTiming(MetricNames.STT_DURATION)?.durationMs).toBeLessThan(200);
+ * ```
+ */
+export declare class InMemoryMetrics implements MetricsAdapter {
+    readonly counters: Array<{
+        name: string;
+        value: number;
+        tags?: Record<string, string>;
+        timestamp: number;
+    }>;
+    readonly timings: Array<{
+        name: string;
+        durationMs: number;
+        tags?: Record<string, string>;
+        timestamp: number;
+    }>;
+    readonly gauges: Array<{
+        name: string;
+        value: number;
+        tags?: Record<string, string>;
+        timestamp: number;
+    }>;
+    increment(name: string, value?: number, tags?: Record<string, string>): void;
+    timing(name: string, durationMs: number, tags?: Record<string, string>): void;
+    gauge(name: string, value: number, tags?: Record<string, string>): void;
+    /**
+     * Get the latest counter entry for a metric name
+     */
+    getLatestCounter(name: string): {
+        name: string;
+        value: number;
+        tags?: Record<string, string>;
+        timestamp: number;
+    } | undefined;
+    /**
+     * Get the latest timing entry for a metric name
+     */
+    getLatestTiming(name: string): {
+        name: string;
+        durationMs: number;
+        tags?: Record<string, string>;
+        timestamp: number;
+    } | undefined;
+    /**
+     * Get the latest gauge entry for a metric name
+     */
+    getLatestGauge(name: string): {
+        name: string;
+        value: number;
+        tags?: Record<string, string>;
+        timestamp: number;
+    } | undefined;
+    /**
+     * Get sum of all counter increments for a metric name
+     */
+    getCounterSum(name: string): number;
+    /**
+     * Clear all stored metrics
+     */
+    clear(): void;
+}