@llmrtc/llmrtc-core 1.0.0

package/dist/metrics.js

@@ -0,0 +1,241 @@
+/**
+ * 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
+ * }
+ * ```
+ */
+// =============================================================================
+// Metric Names
+// =============================================================================
+/**
+ * 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 const MetricNames = {
+    // STT metrics
+    /** Duration of STT transcription in milliseconds */
+    STT_DURATION: 'llmrtc.stt.duration_ms',
+    // LLM metrics
+    /** Time to first LLM token in milliseconds */
+    LLM_TTFT: 'llmrtc.llm.ttft_ms',
+    /** Total LLM inference duration in milliseconds */
+    LLM_DURATION: 'llmrtc.llm.duration_ms',
+    /** Number of tokens generated (when available from provider) */
+    LLM_TOKENS: 'llmrtc.llm.tokens',
+    // TTS metrics
+    /** Duration of TTS synthesis in milliseconds */
+    TTS_DURATION: 'llmrtc.tts.duration_ms',
+    // Turn metrics
+    /** Total turn duration (STT + LLM + TTS) in milliseconds */
+    TURN_DURATION: 'llmrtc.turn.duration_ms',
+    // Session metrics
+    /** Session duration in milliseconds */
+    SESSION_DURATION: 'llmrtc.session.duration_ms',
+    /** Number of active sessions (gauge) */
+    ACTIVE_SESSIONS: 'llmrtc.sessions.active',
+    /** Total turns per session */
+    SESSION_TURNS: 'llmrtc.session.turns',
+    // Error metrics
+    /** Error counter by type/component */
+    ERRORS: 'llmrtc.errors',
+    // Connection metrics
+    /** Number of active WebSocket connections */
+    CONNECTIONS: 'llmrtc.connections.active',
+    /** Reconnection attempts */
+    RECONNECTIONS: 'llmrtc.reconnections',
+    // Tool metrics
+    /** Tool execution duration in milliseconds */
+    TOOL_DURATION: 'llmrtc.tool.duration_ms',
+    /** Number of tool calls */
+    TOOL_CALLS: 'llmrtc.tool.calls',
+    /** Tool call errors */
+    TOOL_ERRORS: 'llmrtc.tool.errors',
+    // Playbook metrics
+    /** Stage duration in milliseconds */
+    STAGE_DURATION: 'llmrtc.playbook.stage.duration_ms',
+    /** Number of stage transitions */
+    STAGE_TRANSITIONS: 'llmrtc.playbook.transitions',
+    /** Turns per stage */
+    STAGE_TURNS: 'llmrtc.playbook.stage.turns',
+    /** Current playbook stage (gauge) */
+    CURRENT_STAGE: 'llmrtc.playbook.stage.current',
+    /** Playbook completion counter */
+    PLAYBOOK_COMPLETIONS: 'llmrtc.playbook.completions'
+};
+// =============================================================================
+// Built-in Implementations
+// =============================================================================
+/**
+ * No-op metrics adapter (default)
+ *
+ * Use this when metrics collection is disabled or not needed.
+ * All methods are no-ops with minimal overhead.
+ */
+export class NoopMetrics {
+    increment() {
+        // No-op
+    }
+    timing() {
+        // No-op
+    }
+    gauge() {
+        // No-op
+    }
+}
+/**
+ * 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 class ConsoleMetrics {
+    constructor(options) {
+        Object.defineProperty(this, "prefix", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.prefix = options?.prefix ? `${options.prefix}.` : '';
+    }
+    increment(name, value = 1, tags) {
+        const tagStr = tags ? ` ${JSON.stringify(tags)}` : '';
+        console.log(`[metric] ${this.prefix}${name} +${value}${tagStr}`);
+    }
+    timing(name, durationMs, tags) {
+        const tagStr = tags ? ` ${JSON.stringify(tags)}` : '';
+        console.log(`[metric] ${this.prefix}${name} ${durationMs}ms${tagStr}`);
+    }
+    gauge(name, value, tags) {
+        const tagStr = tags ? ` ${JSON.stringify(tags)}` : '';
+        console.log(`[metric] ${this.prefix}${name} = ${value}${tagStr}`);
+    }
+}
+/**
+ * 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 class InMemoryMetrics {
+    constructor() {
+        Object.defineProperty(this, "counters", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "timings", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "gauges", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+    }
+    increment(name, value = 1, tags) {
+        this.counters.push({ name, value, tags, timestamp: Date.now() });
+    }
+    timing(name, durationMs, tags) {
+        this.timings.push({ name, durationMs, tags, timestamp: Date.now() });
+    }
+    gauge(name, value, tags) {
+        this.gauges.push({ name, value, tags, timestamp: Date.now() });
+    }
+    /**
+     * Get the latest counter entry for a metric name
+     */
+    getLatestCounter(name) {
+        return this.counters.filter(c => c.name === name).pop();
+    }
+    /**
+     * Get the latest timing entry for a metric name
+     */
+    getLatestTiming(name) {
+        return this.timings.filter(t => t.name === name).pop();
+    }
+    /**
+     * Get the latest gauge entry for a metric name
+     */
+    getLatestGauge(name) {
+        return this.gauges.filter(g => g.name === name).pop();
+    }
+    /**
+     * Get sum of all counter increments for a metric name
+     */
+    getCounterSum(name) {
+        return this.counters
+            .filter(c => c.name === name)
+            .reduce((sum, c) => sum + c.value, 0);
+    }
+    /**
+     * Clear all stored metrics
+     */
+    clear() {
+        this.counters.length = 0;
+        this.timings.length = 0;
+        this.gauges.length = 0;
+    }
+}
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

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

package/dist/orchestrator.d.ts

@@ -0,0 +1,73 @@
+import { ConversationOrchestratorConfig, LLMResult, OrchestratorYield, STTResult, TTSResult, VisionAttachment } from './types.js';
+import { OrchestratorHooks } from './hooks.js';
+import { MetricsAdapter } from './metrics.js';
+/**
+ * Extended orchestrator configuration with hooks and metrics
+ */
+export interface OrchestratorConfigWithHooks extends ConversationOrchestratorConfig {
+    /** Hooks for observability and extensibility */
+    hooks?: OrchestratorHooks;
+    /** Metrics adapter for emitting timing and counter metrics */
+    metrics?: MetricsAdapter;
+    /** Custom sentence boundary splitter for streaming TTS */
+    sentenceChunker?: (text: string) => string[];
+}
+export declare class ConversationOrchestrator {
+    private readonly config;
+    private readonly providers;
+    private readonly history;
+    private readonly systemPrompt?;
+    private readonly historyLimit;
+    private readonly logger;
+    private readonly streamingTTS;
+    private readonly sessionId?;
+    private readonly hooks;
+    private readonly metrics;
+    private readonly sentenceChunker?;
+    constructor(config: OrchestratorConfigWithHooks);
+    init(): Promise<void>;
+    /**
+     * Run a single voice+vision turn: audio -> STT -> LLM (+optional vision) -> TTS.
+     */
+    runTurn(audio: Buffer, attachments?: VisionAttachment[]): Promise<{
+        transcript: STTResult;
+        llm: LLMResult;
+        tts: TTSResult;
+    }>;
+    /**
+     * Streaming version: yields LLM chunks as they arrive.
+     *
+     * With streaming TTS enabled (when provider supports speakStream):
+     * - Detects sentence boundaries during LLM streaming
+     * - Starts TTS generation as soon as each sentence is complete
+     * - Yields TTSChunk events with PCM audio data
+     * - User hears audio while LLM is still generating
+     *
+     * Hooks and metrics are called throughout the turn lifecycle.
+     */
+    runTurnStream(audio: Buffer, attachments?: VisionAttachment[]): AsyncGenerator<OrchestratorYield, void, unknown>;
+    /**
+     * Split text into sentences using custom chunker or default regex
+     */
+    private splitIntoSentences;
+    /**
+     * Stream TTS chunks for a sentence using PCM format with hooks.
+     * Yields TTSChunk events as audio data arrives.
+     */
+    private streamTTSChunksWithHooks;
+    /**
+     * Non-streaming TTS with hooks: generates complete audio and yields as single TTSResult.
+     */
+    private generateTTSWithHooks;
+    /**
+     * @deprecated Use streamTTSChunksWithHooks instead
+     * Stream TTS chunks for a sentence using PCM format.
+     */
+    private streamTTSChunks;
+    /**
+     * @deprecated Use generateTTSWithHooks instead
+     * Non-streaming TTS: generates complete audio and yields as single TTSResult.
+     */
+    private generateTTS;
+    private pushHistory;
+}