@livekit/agents 1.1.0 → 1.2.1

package/src/telemetry/utils.ts

@@ -0,0 +1,61 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { type Span, SpanStatusCode, context as otelContext, trace } from '@opentelemetry/api';
+import type { RealtimeModelMetrics } from '../metrics/base.js';
+import * as traceTypes from './trace_types.js';
+import { tracer } from './traces.js';
+
+export function recordException(span: Span, error: Error): void {
+  span.recordException(error);
+  span.setStatus({
+    code: SpanStatusCode.ERROR,
+    message: error.message,
+  });
+
+  // Set exception attributes for better visibility
+  // (in case the exception event is not rendered by the backend)
+  span.setAttributes({
+    [traceTypes.ATTR_EXCEPTION_TYPE]: error.constructor.name,
+    [traceTypes.ATTR_EXCEPTION_MESSAGE]: error.message,
+    [traceTypes.ATTR_EXCEPTION_TRACE]: error.stack || '',
+  });
+}
+
+export function recordRealtimeMetrics(span: Span, metrics: RealtimeModelMetrics): void {
+  const attrs: Record<string, string | number> = {
+    [traceTypes.ATTR_GEN_AI_REQUEST_MODEL]: metrics.label || 'unknown',
+    [traceTypes.ATTR_REALTIME_MODEL_METRICS]: JSON.stringify(metrics),
+    [traceTypes.ATTR_GEN_AI_USAGE_INPUT_TOKENS]: metrics.inputTokens,
+    [traceTypes.ATTR_GEN_AI_USAGE_OUTPUT_TOKENS]: metrics.outputTokens,
+    [traceTypes.ATTR_GEN_AI_USAGE_INPUT_TEXT_TOKENS]: metrics.inputTokenDetails.textTokens,
+    [traceTypes.ATTR_GEN_AI_USAGE_INPUT_AUDIO_TOKENS]: metrics.inputTokenDetails.audioTokens,
+    [traceTypes.ATTR_GEN_AI_USAGE_INPUT_CACHED_TOKENS]: metrics.inputTokenDetails.cachedTokens,
+    [traceTypes.ATTR_GEN_AI_USAGE_OUTPUT_TEXT_TOKENS]: metrics.outputTokenDetails.textTokens,
+    [traceTypes.ATTR_GEN_AI_USAGE_OUTPUT_AUDIO_TOKENS]: metrics.outputTokenDetails.audioTokens,
+  };
+
+  // Add LangFuse-specific completion start time if TTFT is available
+  if (metrics.ttftMs !== undefined && metrics.ttftMs !== -1) {
+    const completionStartTime = metrics.timestamp + metrics.ttftMs;
+    // Convert to UTC ISO string for LangFuse compatibility
+    const completionStartTimeUtc = new Date(completionStartTime).toISOString();
+    attrs[traceTypes.ATTR_LANGFUSE_COMPLETION_START_TIME] = completionStartTimeUtc;
+  }
+
+  if (span.isRecording()) {
+    span.setAttributes(attrs);
+  } else {
+    const currentContext = otelContext.active();
+    const spanContext = trace.setSpan(currentContext, span);
+
+    // Create a dedicated child span for orphaned metrics
+    tracer.getTracer().startActiveSpan('realtime_metrics', {}, spanContext, (child) => {
+      try {
+        child.setAttributes(attrs);
+      } finally {
+        child.end();
+      }
+    });
+  }
+}

package/src/tokenize/basic/sentence.ts

@@ -16,7 +16,7 @@ export const splitSentences = (
   const starters =
     /(Mr|Mrs|Ms|Dr|Prof|Capt|Cpt|Lt|He\s|She\s|It\s|They\s|Their\s|Our\s|We\s|But\s|However\s|That\s|This\s|Wherever)/g;
   const acronyms = /([A-Z][.][A-Z][.](?:[A-Z][.])?)/g;
-  const websites = /[.](com|net|org|io|gov|edu|me)/g;
+  const websites = /(\w+\.)+(com|net|org|io|gov|edu|me)/g;
   const digits = /([0-9])/g;
   const dots = /\.{2,}/g;
 
@@ -27,7 +27,7 @@ export const splitSentences = (
   }
 
   text = text.replaceAll(prefixes, '$1<prd>');
-  text = text.replaceAll(websites, '<prd>$2');
+  text = text.replace(websites, (match) => match.replaceAll('.', '<prd>'));
   text = text.replaceAll(new RegExp(`${digits.source}[.]${digits.source}`, 'g'), '$1<prd>$2');
   text = text.replaceAll(dots, (match) => '<prd>'.repeat(match.length));
   text = text.replaceAll('Ph.D.', 'Ph<prd>D<prd>');
@@ -51,7 +51,7 @@ export const splitSentences = (
   text = text.replaceAll('."', '".');
   text = text.replaceAll('!"', '"!');
   text = text.replaceAll('?"', '"?');
-  text = text.replaceAll('.', '.<stop>');
+  text = text.replace(/\.(?=\s|$)/g, '.<stop>');
   text = text.replaceAll('?', '?<stop>');
   text = text.replaceAll('!', '!<stop>');
   text = text.replaceAll('<prd>', '.');

package/src/tokenize/tokenizer.test.ts

@@ -13,6 +13,8 @@ const TEXT =
   'This is a test. Another test. ' +
   'A short sentence. ' +
   'A longer sentence that is longer than the previous sentence. ' +
+  'Find additional resources on livekit.com. ' +
+  'Find additional resources on docs.livekit.com. ' +
   'f(x) = x * 2.54 + 42. ' +
   'Hey! Hi! Hello! ';
 
@@ -22,6 +24,8 @@ const EXPECTED_MIN_20 = [
   'Mr. Theo is testing the sentence tokenizer.',
   'This is a test. Another test.',
   'A short sentence. A longer sentence that is longer than the previous sentence.',
+  'Find additional resources on livekit.com.',
+  'Find additional resources on docs.livekit.com.',
   'f(x) = x * 2.54 + 42.',
   'Hey! Hi! Hello!',
 ];

package/src/transcription.ts

@@ -13,11 +13,17 @@ import { AsyncIterableQueue, Future, shortuuid } from './utils.js';
 const STANDARD_SPEECH_RATE = 3830;
 
 export interface TextSyncOptions {
+  /** Language code for transcription. */
   language: string;
+  /** Speech speed multiplier. */
   speed: number;
+  /** Delay between sentences in milliseconds. */
   newSentenceDelay: number;
+  /** Tokenizer for splitting text into sentences. */
   sentenceTokenizer: SentenceTokenizer;
+  /** Function to hyphenate words. */
   hyphenateWord: (word: string) => string[];
+  /** Function to split text into words with positions. */
   splitWords: (words: string) => [string, number, number][];
 }