@voice-kit/core 0.1.1 → 0.1.3

package/dist/observability.js

@@ -1,222 +0,0 @@
-import { LRUCache } from 'lru-cache';
-import pino from 'pino';
-import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
-import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http';
-import { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
-import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions';
-import { trace, SpanStatusCode } from '@opentelemetry/api';
-import { resourceFromAttributes } from '@opentelemetry/resources';
-
-// src/observability/metric/index.ts
-var logger = pino({ name: "@voice-kit/core:metrics" });
-var TOKEN_COSTS_PER_M = {
-  "gpt-4o": { input: 5, output: 15 },
-  "gpt-4o-mini": { input: 0.15, output: 0.6 },
-  "claude-3-5-sonnet": { input: 3, output: 15 },
-  "llama-3.3-70b": { input: 0.59, output: 0.79 }
-};
-function p95(values) {
-  if (values.length === 0) return 0;
-  const sorted = [...values].sort((a, b) => a - b);
-  const idx = Math.floor(sorted.length * 0.95);
-  return sorted[Math.min(idx, sorted.length - 1)] ?? 0;
-}
-function avg(values) {
-  if (values.length === 0) return 0;
-  return values.reduce((a, b) => a + b, 0) / values.length;
-}
-var CallMetrics = class {
-  store;
-  constructor() {
-    this.store = new LRUCache({
-      max: 1e4,
-      ttl: 2 * 60 * 60 * 1e3
-      // 2 hours
-    });
-  }
-  getOrCreate(callId) {
-    const existing = this.store.get(callId);
-    if (existing) return existing;
-    const data = {
-      sttFirstByteMs: [],
-      ttsFirstByteMs: [],
-      llmFirstTokenMs: [],
-      turnLatencyMs: [],
-      interruptionCount: 0,
-      interruptionPositions: [],
-      tokenCost: []
-    };
-    this.store.set(callId, data);
-    return data;
-  }
-  /** Record time from audio start to first STT partial result. */
-  recordSTTFirstByte(callId, ms) {
-    this.getOrCreate(callId).sttFirstByteMs.push(ms);
-    logger.debug({ callId, ms }, "Metric: STT TTFB");
-  }
-  /** Record time from TTS request to first audio chunk. */
-  recordTTSFirstByte(callId, ms) {
-    this.getOrCreate(callId).ttsFirstByteMs.push(ms);
-    logger.debug({ callId, ms }, "Metric: TTS TTFB");
-  }
-  /** Record time from LLM request to first token. */
-  recordLLMFirstToken(callId, ms) {
-    this.getOrCreate(callId).llmFirstTokenMs.push(ms);
-    logger.debug({ callId, ms }, "Metric: LLM first token");
-  }
-  /**
-   * Record end-to-end turn latency: speech_end → first TTS audio byte.
-   * This is the primary latency metric for voice agent quality.
-   */
-  recordTurnLatency(callId, ms) {
-    this.getOrCreate(callId).turnLatencyMs.push(ms);
-    logger.debug({ callId, ms }, "Metric: turn latency");
-  }
-  /**
-   * Record an interruption event.
-   *
-   * @param callId       Call identifier
-   * @param positionPct  0–1, how far through the TTS stream the interruption occurred
-   */
-  recordInterruption(callId, positionPct) {
-    const data = this.getOrCreate(callId);
-    data.interruptionCount++;
-    data.interruptionPositions.push(positionPct);
-    logger.debug({ callId, positionPct }, "Metric: interruption");
-  }
-  /** Record token usage and estimated cost for a model call. */
-  recordTokenCost(callId, model, inputTokens, outputTokens) {
-    const costs = TOKEN_COSTS_PER_M[model] ?? { input: 0, output: 0 };
-    const estimatedUsdCost = inputTokens / 1e6 * costs.input + outputTokens / 1e6 * costs.output;
-    this.getOrCreate(callId).tokenCost.push({
-      model,
-      inputTokens,
-      outputTokens,
-      estimatedUsdCost
-    });
-    logger.debug({ callId, model, inputTokens, outputTokens, estimatedUsdCost }, "Metric: token cost");
-  }
-  /**
-   * Get a full summary of metrics for a call.
-   *
-   * @param callId  The call identifier
-   * @returns       Aggregated metrics summary
-   */
-  getCallSummary(callId) {
-    const data = this.getOrCreate(callId);
-    return {
-      callId,
-      sttFirstByteMs: [...data.sttFirstByteMs],
-      ttsFirstByteMs: [...data.ttsFirstByteMs],
-      llmFirstTokenMs: [...data.llmFirstTokenMs],
-      turnLatencyMs: [...data.turnLatencyMs],
-      interruptionCount: data.interruptionCount,
-      interruptionPositions: [...data.interruptionPositions],
-      tokenCost: [...data.tokenCost],
-      avgTurnLatencyMs: Math.round(avg(data.turnLatencyMs)),
-      p95TurnLatencyMs: Math.round(p95(data.turnLatencyMs))
-    };
-  }
-  /** Remove metrics for a call. Call on call.ended to free memory. */
-  clearCall(callId) {
-    this.store.delete(callId);
-  }
-};
-var logger2 = pino({ name: "@voice-kit/core:observability" });
-var _provider = null;
-function getOrInitProvider() {
-  if (_provider) return _provider;
-  const endpoint = process.env["OTEL_EXPORTER_OTLP_ENDPOINT"];
-  _provider = new NodeTracerProvider({
-    resource: resourceFromAttributes({
-      [ATTR_SERVICE_NAME]: "voice-kit"
-    }),
-    // Pass span processors directly in constructor — addSpanProcessor doesn't exist in this version
-    spanProcessors: endpoint ? [new SimpleSpanProcessor(new OTLPTraceExporter({ url: endpoint }))] : []
-  });
-  if (endpoint) {
-    logger2.info({ endpoint }, "OTel OTLP exporter configured");
-  }
-  _provider.register();
-  return _provider;
-}
-var VoiceSDKTracer = class {
-  tracer;
-  constructor() {
-    getOrInitProvider();
-    this.tracer = trace.getTracer("@voice-kit/core", "0.1.0");
-  }
-  /**
-   * Trace an STT operation with provider + language attributes.
-   */
-  async traceSTT(fn, attrs) {
-    return this.withSpan(`stt.${attrs.provider}`, fn, {
-      "stt.provider": attrs.provider,
-      "stt.language": attrs.language,
-      ...attrs.callId && { "call.id": attrs.callId }
-    });
-  }
-  /**
-   * Trace a TTS synthesis operation.
-   */
-  async traceTTS(fn, attrs) {
-    return this.withSpan(`tts.${attrs.provider}`, fn, {
-      "tts.provider": attrs.provider,
-      "tts.voice_id": attrs.voice,
-      "tts.char_count": attrs.chars,
-      ...attrs.callId && { "call.id": attrs.callId }
-    });
-  }
-  /**
-   * Trace an LLM generation call.
-   */
-  async traceLLM(fn, attrs) {
-    return this.withSpan(`llm.${attrs.model}`, fn, {
-      "llm.model": attrs.model,
-      "llm.input_tokens": attrs.inputTokens,
-      ...attrs.callId && { "call.id": attrs.callId }
-    });
-  }
-  /**
-   * Trace a full call lifecycle.
-   */
-  async traceCall(fn, attrs) {
-    return this.withSpan("call", fn, {
-      "call.id": attrs.callId,
-      "call.direction": attrs.direction
-    });
-  }
-  /**
-   * Trace a single conversation turn.
-   */
-  async traceTurn(fn, attrs) {
-    return this.withSpan("turn", fn, {
-      "turn.index": attrs.turnIndex,
-      "call.id": attrs.callId
-    });
-  }
-  /** Generic span wrapper. @internal */
-  async withSpan(name, fn, attributes) {
-    const span = this.tracer.startSpan(name, { attributes });
-    const startMs = Date.now();
-    try {
-      const result = await fn();
-      span.setStatus({ code: SpanStatusCode.OK });
-      span.setAttribute("duration_ms", Date.now() - startMs);
-      return result;
-    } catch (err) {
-      span.setStatus({
-        code: SpanStatusCode.ERROR,
-        message: err instanceof Error ? err.message : String(err)
-      });
-      span.recordException(err instanceof Error ? err : new Error(String(err)));
-      throw err;
-    } finally {
-      span.end();
-    }
-  }
-};
-
-export { CallMetrics, VoiceSDKTracer };
-//# sourceMappingURL=observability.js.map
-//# sourceMappingURL=observability.js.map

package/dist/observability.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/observability/metric/index.ts","../src/observability/tracer/index.ts"],"names":["logger","pino","Resource"],"mappings":"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","file":"observability.js","sourcesContent":["/**\r\n * @voice-kit/core — CallMetrics\r\n *\r\n * Records per-call performance metrics: TTFB, turn latency, token cost, interruption rate.\r\n * In-process LRU storage — exported via getCallSummary().\r\n */\r\n\r\nimport { LRUCache } from 'lru-cache'\r\nimport type { CallMetricsSummary } from '../../types'\r\nimport pino from 'pino'\r\n\r\nconst logger = pino({ name: '@voice-kit/core:metrics' })\r\n\r\n/** USD cost per 1M tokens by model. Approximate — update as pricing changes. */\r\nconst TOKEN_COSTS_PER_M: Record<string, { input: number; output: number }> = {\r\n    'gpt-4o': { input: 5.0, output: 15.0 },\r\n    'gpt-4o-mini': { input: 0.15, output: 0.6 },\r\n    'claude-3-5-sonnet': { input: 3.0, output: 15.0 },\r\n    'llama-3.3-70b': { input: 0.59, output: 0.79 },\r\n}\r\n\r\ninterface CallData {\r\n    sttFirstByteMs: number[]\r\n    ttsFirstByteMs: number[]\r\n    llmFirstTokenMs: number[]\r\n    turnLatencyMs: number[]\r\n    interruptionCount: number\r\n    interruptionPositions: number[]\r\n    tokenCost: Array<{\r\n        model: string\r\n        inputTokens: number\r\n        outputTokens: number\r\n        estimatedUsdCost: number\r\n    }>\r\n}\r\n\r\nfunction p95(values: number[]): number {\r\n    if (values.length === 0) return 0\r\n    const sorted = [...values].sort((a, b) => a - b)\r\n    const idx = Math.floor(sorted.length * 0.95)\r\n    return sorted[Math.min(idx, sorted.length - 1)] ?? 0\r\n}\r\n\r\nfunction avg(values: number[]): number {\r\n    if (values.length === 0) return 0\r\n    return values.reduce((a, b) => a + b, 0) / values.length\r\n}\r\n\r\n/**\r\n * Per-call performance metrics recorder.\r\n *\r\n * @example\r\n * ```ts\r\n * const metrics = new CallMetrics()\r\n * metrics.recordSTTFirstByte(callId, 180)\r\n * metrics.recordTurnLatency(callId, 340)\r\n * const summary = metrics.getCallSummary(callId)\r\n * console.log(summary.avgTurnLatencyMs) // 340\r\n * ```\r\n */\r\nexport class CallMetrics {\r\n    private readonly store: LRUCache<string, CallData>\r\n\r\n    constructor() {\r\n        this.store = new LRUCache<string, CallData>({\r\n            max: 10_000,\r\n            ttl: 2 * 60 * 60 * 1_000, // 2 hours\r\n        })\r\n    }\r\n\r\n    private getOrCreate(callId: string): CallData {\r\n        const existing = this.store.get(callId)\r\n        if (existing) return existing\r\n\r\n        const data: CallData = {\r\n            sttFirstByteMs: [],\r\n            ttsFirstByteMs: [],\r\n            llmFirstTokenMs: [],\r\n            turnLatencyMs: [],\r\n            interruptionCount: 0,\r\n            interruptionPositions: [],\r\n            tokenCost: [],\r\n        }\r\n        this.store.set(callId, data)\r\n        return data\r\n    }\r\n\r\n    /** Record time from audio start to first STT partial result. */\r\n    recordSTTFirstByte(callId: string, ms: number): void {\r\n        this.getOrCreate(callId).sttFirstByteMs.push(ms)\r\n        logger.debug({ callId, ms }, 'Metric: STT TTFB')\r\n    }\r\n\r\n    /** Record time from TTS request to first audio chunk. */\r\n    recordTTSFirstByte(callId: string, ms: number): void {\r\n        this.getOrCreate(callId).ttsFirstByteMs.push(ms)\r\n        logger.debug({ callId, ms }, 'Metric: TTS TTFB')\r\n    }\r\n\r\n    /** Record time from LLM request to first token. */\r\n    recordLLMFirstToken(callId: string, ms: number): void {\r\n        this.getOrCreate(callId).llmFirstTokenMs.push(ms)\r\n        logger.debug({ callId, ms }, 'Metric: LLM first token')\r\n    }\r\n\r\n    /**\r\n     * Record end-to-end turn latency: speech_end → first TTS audio byte.\r\n     * This is the primary latency metric for voice agent quality.\r\n     */\r\n    recordTurnLatency(callId: string, ms: number): void {\r\n        this.getOrCreate(callId).turnLatencyMs.push(ms)\r\n        logger.debug({ callId, ms }, 'Metric: turn latency')\r\n    }\r\n\r\n    /**\r\n     * Record an interruption event.\r\n     *\r\n     * @param callId       Call identifier\r\n     * @param positionPct  0–1, how far through the TTS stream the interruption occurred\r\n     */\r\n    recordInterruption(callId: string, positionPct: number): void {\r\n        const data = this.getOrCreate(callId)\r\n        data.interruptionCount++\r\n        data.interruptionPositions.push(positionPct)\r\n        logger.debug({ callId, positionPct }, 'Metric: interruption')\r\n    }\r\n\r\n    /** Record token usage and estimated cost for a model call. */\r\n    recordTokenCost(\r\n        callId: string,\r\n        model: string,\r\n        inputTokens: number,\r\n        outputTokens: number\r\n    ): void {\r\n        const costs = TOKEN_COSTS_PER_M[model] ?? { input: 0, output: 0 }\r\n        const estimatedUsdCost =\r\n            (inputTokens / 1_000_000) * costs.input +\r\n            (outputTokens / 1_000_000) * costs.output\r\n\r\n        this.getOrCreate(callId).tokenCost.push({\r\n            model,\r\n            inputTokens,\r\n            outputTokens,\r\n            estimatedUsdCost,\r\n        })\r\n\r\n        logger.debug({ callId, model, inputTokens, outputTokens, estimatedUsdCost }, 'Metric: token cost')\r\n    }\r\n\r\n    /**\r\n     * Get a full summary of metrics for a call.\r\n     *\r\n     * @param callId  The call identifier\r\n     * @returns       Aggregated metrics summary\r\n     */\r\n    getCallSummary(callId: string): CallMetricsSummary {\r\n        const data = this.getOrCreate(callId)\r\n\r\n        return {\r\n            callId,\r\n            sttFirstByteMs: [...data.sttFirstByteMs],\r\n            ttsFirstByteMs: [...data.ttsFirstByteMs],\r\n            llmFirstTokenMs: [...data.llmFirstTokenMs],\r\n            turnLatencyMs: [...data.turnLatencyMs],\r\n            interruptionCount: data.interruptionCount,\r\n            interruptionPositions: [...data.interruptionPositions],\r\n            tokenCost: [...data.tokenCost],\r\n            avgTurnLatencyMs: Math.round(avg(data.turnLatencyMs)),\r\n            p95TurnLatencyMs: Math.round(p95(data.turnLatencyMs)),\r\n        }\r\n    }\r\n\r\n    /** Remove metrics for a call. Call on call.ended to free memory. */\r\n    clearCall(callId: string): void {\r\n        this.store.delete(callId)\r\n    }\r\n}","/**\r\n * @voice-kit/core — OpenTelemetry tracing\r\n *\r\n * VoiceSDKTracer: wraps every external provider call with OTel spans.\r\n * Auto-exports to OTLP endpoint if OTEL_EXPORTER_OTLP_ENDPOINT is set.\r\n */\r\n\r\nimport { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'\r\nimport { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'\r\nimport { SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base'\r\nimport { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions'\r\nimport { trace, SpanStatusCode, type Tracer, type Span } from '@opentelemetry/api'\r\nimport { resourceFromAttributes as Resource } from '@opentelemetry/resources'\r\nimport pino from 'pino'\r\n\r\nconst logger = pino({ name: '@voice-kit/core:observability' })\r\n\r\nlet _provider: NodeTracerProvider | null = null\r\n\r\n/**\r\n * Initialize the global OTel trace provider.\r\n * Called once at SDK startup if OTEL_EXPORTER_OTLP_ENDPOINT is set.\r\n *\r\n * @internal\r\n */\r\nfunction getOrInitProvider(): NodeTracerProvider {\r\n    if (_provider) return _provider\r\n\r\n    const endpoint = process.env['OTEL_EXPORTER_OTLP_ENDPOINT']\r\n\r\n    _provider = new NodeTracerProvider({\r\n        resource: Resource({\r\n            [ATTR_SERVICE_NAME]: 'voice-kit',\r\n        }),\r\n        // Pass span processors directly in constructor — addSpanProcessor doesn't exist in this version\r\n        spanProcessors: endpoint\r\n            ? [new SimpleSpanProcessor(new OTLPTraceExporter({ url: endpoint }))]\r\n            : [],\r\n    })\r\n\r\n    if (endpoint) {\r\n        logger.info({ endpoint }, 'OTel OTLP exporter configured')\r\n    }\r\n\r\n    _provider.register()\r\n    return _provider\r\n}\r\n\r\n/**\r\n * OpenTelemetry tracer for VoiceKit. Wraps every external I/O with spans.\r\n *\r\n * @example\r\n * ```ts\r\n * const tracer = new VoiceSDKTracer()\r\n * const result = await tracer.traceSTT(\r\n *   () => stt.transcribeBatch(audio),\r\n *   { provider: 'deepgram', language: 'en-IN' }\r\n * )\r\n * ```\r\n */\r\nexport class VoiceSDKTracer {\r\n    private readonly tracer: Tracer\r\n\r\n    constructor() {\r\n        getOrInitProvider()\r\n        this.tracer = trace.getTracer('@voice-kit/core', '0.1.0')\r\n    }\r\n\r\n    /**\r\n     * Trace an STT operation with provider + language attributes.\r\n     */\r\n    async traceSTT<T>(\r\n        fn: () => Promise<T>,\r\n        attrs: { provider: string; language: string; callId?: string }\r\n    ): Promise<T> {\r\n        return this.withSpan(`stt.${attrs.provider}`, fn, {\r\n            'stt.provider': attrs.provider,\r\n            'stt.language': attrs.language,\r\n            ...(attrs.callId && { 'call.id': attrs.callId }),\r\n        })\r\n    }\r\n\r\n    /**\r\n     * Trace a TTS synthesis operation.\r\n     */\r\n    async traceTTS<T>(\r\n        fn: () => Promise<T>,\r\n        attrs: { provider: string; voice: string; chars: number; callId?: string }\r\n    ): Promise<T> {\r\n        return this.withSpan(`tts.${attrs.provider}`, fn, {\r\n            'tts.provider': attrs.provider,\r\n            'tts.voice_id': attrs.voice,\r\n            'tts.char_count': attrs.chars,\r\n            ...(attrs.callId && { 'call.id': attrs.callId }),\r\n        })\r\n    }\r\n\r\n    /**\r\n     * Trace an LLM generation call.\r\n     */\r\n    async traceLLM<T>(\r\n        fn: () => Promise<T>,\r\n        attrs: { model: string; inputTokens: number; callId?: string }\r\n    ): Promise<T> {\r\n        return this.withSpan(`llm.${attrs.model}`, fn, {\r\n            'llm.model': attrs.model,\r\n            'llm.input_tokens': attrs.inputTokens,\r\n            ...(attrs.callId && { 'call.id': attrs.callId }),\r\n        })\r\n    }\r\n\r\n    /**\r\n     * Trace a full call lifecycle.\r\n     */\r\n    async traceCall<T>(\r\n        fn: () => Promise<T>,\r\n        attrs: { callId: string; direction: 'inbound' | 'outbound' }\r\n    ): Promise<T> {\r\n        return this.withSpan('call', fn, {\r\n            'call.id': attrs.callId,\r\n            'call.direction': attrs.direction,\r\n        })\r\n    }\r\n\r\n    /**\r\n     * Trace a single conversation turn.\r\n     */\r\n    async traceTurn<T>(\r\n        fn: () => Promise<T>,\r\n        attrs: { turnIndex: number; callId: string }\r\n    ): Promise<T> {\r\n        return this.withSpan('turn', fn, {\r\n            'turn.index': attrs.turnIndex,\r\n            'call.id': attrs.callId,\r\n        })\r\n    }\r\n\r\n    /** Generic span wrapper. @internal */\r\n    private async withSpan<T>(\r\n        name: string,\r\n        fn: () => Promise<T>,\r\n        attributes: Record<string, string | number | boolean>\r\n    ): Promise<T> {\r\n        const span: Span = this.tracer.startSpan(name, { attributes })\r\n        const startMs = Date.now()\r\n\r\n        try {\r\n            const result = await fn()\r\n            span.setStatus({ code: SpanStatusCode.OK })\r\n            span.setAttribute('duration_ms', Date.now() - startMs)\r\n            return result\r\n        } catch (err) {\r\n            span.setStatus({\r\n                code: SpanStatusCode.ERROR,\r\n                message: err instanceof Error ? err.message : String(err),\r\n            })\r\n            span.recordException(err instanceof Error ? err : new Error(String(err)))\r\n            throw err\r\n        } finally {\r\n            span.end()\r\n        }\r\n    }\r\n}"]}