@livekit/agents 1.1.0 → 1.2.0

package/src/llm/zod-utils.ts

@@ -0,0 +1,153 @@
+// SPDX-FileCopyrightText: 2025 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import type { JSONSchema7 } from 'json-schema';
+import { toStrictJsonSchema } from 'openai/lib/transform';
+import { zodToJsonSchema as zodToJsonSchemaV3 } from 'zod-to-json-schema';
+import type * as z3 from 'zod/v3';
+import * as z4 from 'zod/v4';
+
+/**
+ * Result type from Zod schema parsing.
+ */
+export type ZodParseResult<T = unknown> =
+  | { success: true; data: T }
+  | { success: false; error: unknown };
+
+/**
+ * Type definition for Zod schemas that works with both v3 and v4.
+ * Uses a union type of both Zod v3 and v4 schema types.
+ *
+ * Adapted from Vercel AI SDK's zodSchema function signature.
+ * Source: https://github.com/vercel/ai/blob/main/packages/provider-utils/src/schema.ts#L278-L281
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ZodSchema = z4.core.$ZodType<any, any> | z3.Schema<any, z3.ZodTypeDef, any>;
+
+/**
+ * Detects if a schema is a Zod v4 schema.
+ * Zod v4 schemas have a `_zod` property that v3 schemas don't have.
+ *
+ * @param schema - The schema to check
+ * @returns True if the schema is a Zod v4 schema
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- Required to match Zod v4's type signature
+export function isZod4Schema(schema: ZodSchema): schema is z4.core.$ZodType<any, any> {
+  // https://zod.dev/library-authors?id=how-to-support-zod-3-and-zod-4-simultaneously
+  return '_zod' in schema;
+}
+
+/**
+ * Checks if a value is a Zod schema (either v3 or v4).
+ *
+ * @param value - The value to check
+ * @returns True if the value is a Zod schema
+ */
+export function isZodSchema(value: unknown): value is ZodSchema {
+  if (typeof value !== 'object' || value === null) {
+    return false;
+  }
+
+  // Check for v4 schema (_zod property)
+  if ('_zod' in value) {
+    return true;
+  }
+
+  // Check for v3 schema (_def property with typeName)
+  if ('_def' in value && typeof value._def === 'object' && value._def !== null) {
+    const def = value._def as Record<string, unknown>;
+    if ('typeName' in def) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Checks if a Zod schema is an object schema.
+ *
+ * @param schema - The schema to check
+ * @returns True if the schema is an object schema
+ */
+export function isZodObjectSchema(schema: ZodSchema): boolean {
+  // Need to access internal Zod properties to check schema type
+  const schemaWithInternals = schema as {
+    _def?: { type?: string; typeName?: string };
+    _zod?: { traits?: Set<string> };
+  };
+
+  // Check for v4 schema first
+  if (isZod4Schema(schema)) {
+    // v4 uses _def.type and _zod.traits
+    return (
+      schemaWithInternals._def?.type === 'object' ||
+      schemaWithInternals._zod?.traits?.has('ZodObject') ||
+      false
+    );
+  }
+
+  // v3 uses _def.typeName
+  return schemaWithInternals._def?.typeName === 'ZodObject';
+}
+
+/**
+ * Converts a Zod schema to JSON Schema format.
+ * Handles both Zod v3 and v4 schemas automatically.
+ *
+ * Adapted from Vercel AI SDK's zod3Schema and zod4Schema functions.
+ * Source: https://github.com/vercel/ai/blob/main/packages/provider-utils/src/schema.ts#L237-L269
+ *
+ * @param schema - The Zod schema to convert
+ * @param isOpenai - Whether to use OpenAI-specific formatting (default: true)
+ * @returns A JSON Schema representation of the Zod schema
+ */
+export function zodSchemaToJsonSchema(
+  schema: ZodSchema,
+  isOpenai: boolean = true,
+  strict: boolean = false,
+): JSONSchema7 {
+  let result: JSONSchema7;
+
+  if (isZod4Schema(schema)) {
+    // Zod v4 has native toJSONSchema support
+    // Configuration adapted from Vercel AI SDK to support OpenAPI conversion for Google
+    // Source: https://github.com/vercel/ai/blob/main/packages/provider-utils/src/schema.ts#L255-L258
+    result = z4.toJSONSchema(schema, {
+      target: 'draft-7',
+      io: 'output',
+      reused: 'inline', // Don't use references by default (to support openapi conversion for google)
+    }) as JSONSchema7;
+  } else {
+    // Zod v3 requires the zod-to-json-schema library
+    // Configuration adapted from Vercel AI SDK
+    // $refStrategy: 'none' is equivalent to v4's reused: 'inline'
+    result = zodToJsonSchemaV3(schema, {
+      target: isOpenai ? 'openAi' : 'jsonSchema7',
+      $refStrategy: 'none', // Don't use references by default (to support openapi conversion for google)
+    }) as JSONSchema7;
+  }
+
+  return strict ? (toStrictJsonSchema(result) as JSONSchema7) : result;
+}
+
+/**
+ * Parses a value against a Zod schema.
+ * Handles both Zod v3 and v4 parse APIs automatically.
+ *
+ * @param schema - The Zod schema to parse against
+ * @param value - The value to parse
+ * @returns A promise that resolves to the parse result
+ */
+export async function parseZodSchema<T = unknown>(
+  schema: ZodSchema,
+  value: unknown,
+): Promise<ZodParseResult<T>> {
+  if (isZod4Schema(schema)) {
+    const result = await z4.safeParseAsync(schema, value);
+    return result as ZodParseResult<T>;
+  } else {
+    const result = await schema.safeParseAsync(value);
+    return result as ZodParseResult<T>;
+  }
+}

package/src/log.ts

@@ -1,8 +1,11 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-import type { Logger } from 'pino';
-import { pino } from 'pino';
+import { Writable } from 'node:stream';
+import type { DestinationStream, Logger } from 'pino';
+import { multistream, pino } from 'pino';
+import { build as pinoPretty } from 'pino-pretty';
+import { type PinoLogObject, emitToOtel } from './telemetry/pino_otel_transport.js';
 
 /** @internal */
 export type LoggerOptions = {
@@ -10,14 +13,27 @@ export type LoggerOptions = {
   level?: string;
 };
 
-/** @internal */
-export let loggerOptions: LoggerOptions;
+// Use Symbol.for() + globalThis to create process-wide singletons.
+// This avoids the "dual package hazard". Symbol.for() returns the same Symbol
+// across all module instances, and globalThis is shared process-wide.
+const LOGGER_KEY = Symbol.for('@livekit/agents:logger');
+const LOGGER_OPTIONS_KEY = Symbol.for('@livekit/agents:loggerOptions');
+const OTEL_ENABLED_KEY = Symbol.for('@livekit/agents:otelEnabled');
+
+type GlobalState = {
+  [LOGGER_KEY]?: Logger;
+  [LOGGER_OPTIONS_KEY]?: LoggerOptions;
+  [OTEL_ENABLED_KEY]?: boolean;
+};
+
+const globals = globalThis as typeof globalThis & GlobalState;
 
 /** @internal */
-let logger: Logger | undefined = undefined;
+export const loggerOptions = (): LoggerOptions | undefined => globals[LOGGER_OPTIONS_KEY];
 
 /** @internal */
 export const log = () => {
+  const logger = globals[LOGGER_KEY];
   if (!logger) {
     throw new TypeError('logger not initialized. did you forget to run initializeLogger()?');
   }
@@ -26,20 +42,56 @@ export const log = () => {
 
 /** @internal */
 export const initializeLogger = ({ pretty, level }: LoggerOptions) => {
-  loggerOptions = { pretty, level };
-  logger = pino(
-    pretty
-      ? {
-          transport: {
-            target: 'pino-pretty',
-            options: {
-              colorize: true,
-            },
-          },
-        }
-      : {},
+  globals[LOGGER_OPTIONS_KEY] = { pretty, level };
+  globals[LOGGER_KEY] = pino(
+    { level: level || 'info', serializers: { error: pino.stdSerializers.err } },
+    pretty ? pinoPretty({ colorize: true }) : process.stdout,
   );
-  if (level) {
-    logger.level = level;
+};
+
+/**
+ * Custom Pino destination that parses JSON logs and emits to OTEL.
+ * This receives the FULL serialized log including msg, level, time, etc.
+ */
+class OtelDestination extends Writable {
+  _write(chunk: Buffer, _encoding: string, callback: (error?: Error | null) => void): void {
+    try {
+      const line = chunk.toString().trim();
+      if (line) {
+        const logObj = JSON.parse(line) as PinoLogObject;
+        emitToOtel(logObj);
+      }
+    } catch {
+      // Ignore parse errors (e.g., non-JSON lines)
+    }
+    callback();
   }
+}
+
+/**
+ * Enable OTEL logging by reconfiguring the logger with multistream.
+ * Uses a custom destination that receives full JSON logs (with msg, level, time).
+ *
+ * @internal
+ */
+export const enableOtelLogging = () => {
+  if (globals[OTEL_ENABLED_KEY] || !globals[LOGGER_KEY]) {
+    console.warn('OTEL logging already enabled or logger not initialized');
+    return;
+  }
+  globals[OTEL_ENABLED_KEY] = true;
+
+  const opts = globals[LOGGER_OPTIONS_KEY]!;
+  const { pretty, level } = opts;
+
+  const logLevel = level || 'info';
+  const streams: { stream: DestinationStream; level: string }[] = [
+    { stream: pretty ? pinoPretty({ colorize: true }) : process.stdout, level: logLevel },
+    { stream: new OtelDestination(), level: 'debug' },
+  ];
+
+  globals[LOGGER_KEY] = pino(
+    { level: logLevel, serializers: { error: pino.stdSerializers.err } },
+    multistream(streams),
+  );
 };

package/src/metrics/base.ts

@@ -2,21 +2,31 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 
+export type MetricsMetadata = {
+  /** The provider name (e.g., 'openai', 'anthropic'). */
+  modelProvider?: string;
+  /** The model name (e.g., 'gpt-4o', 'claude-3-5-sonnet'). */
+  modelName?: string;
+};
+
 export type AgentMetrics =
   | STTMetrics
   | LLMMetrics
   | TTSMetrics
   | VADMetrics
   | EOUMetrics
-  | RealtimeModelMetrics;
+  | RealtimeModelMetrics
+  | InterruptionMetrics;
 
 export type LLMMetrics = {
   type: 'llm_metrics';
   label: string;
   requestId: string;
   timestamp: number;
-  duration: number;
-  ttft: number;
+  /** Duration of the request in milliseconds. */
+  durationMs: number;
+  /** Time to first token in milliseconds. */
+  ttftMs: number;
   cancelled: boolean;
   completionTokens: number;
   promptTokens: number;
@@ -24,6 +34,8 @@ export type LLMMetrics = {
   totalTokens: number;
   tokensPerSecond: number;
   speechId?: string;
+  /** Metadata for model provider and name tracking. */
+  metadata?: MetricsMetadata;
 };
 
 export type STTMetrics = {
@@ -32,17 +44,23 @@ export type STTMetrics = {
   requestId: string;
   timestamp: number;
   /**
-   * The request duration in seconds, 0.0 if the STT is streaming.
+   * The request duration in milliseconds, 0.0 if the STT is streaming.
    */
-  duration: number;
+  durationMs: number;
   /**
-   * The duration of the pushed audio in seconds.
+   * The duration of the pushed audio in milliseconds.
    */
-  audioDuration: number;
+  audioDurationMs: number;
+  /** Input audio tokens (for token-based billing). */
+  inputTokens?: number;
+  /** Output text tokens (for token-based billing). */
+  outputTokens?: number;
   /**
    * Whether the STT is streaming (e.g using websocket).
    */
   streamed: boolean;
+  /** Metadata for model provider and name tracking. */
+  metadata?: MetricsMetadata;
 };
 
 export type TTSMetrics = {
@@ -50,22 +68,32 @@ export type TTSMetrics = {
   label: string;
   requestId: string;
   timestamp: number;
-  ttfb: number;
-  duration: number;
-  audioDuration: number;
+  /** Time to first byte in milliseconds. */
+  ttfbMs: number;
+  /** Total synthesis duration in milliseconds. */
+  durationMs: number;
+  /** Generated audio duration in milliseconds. */
+  audioDurationMs: number;
   cancelled: boolean;
+  /** Number of characters synthesized (for character-based billing). */
   charactersCount: number;
+  /** Input text tokens (for token-based billing, e.g., OpenAI TTS). */
+  inputTokens?: number;
+  /** Output audio tokens (for token-based billing, e.g., OpenAI TTS). */
+  outputTokens?: number;
   streamed: boolean;
   segmentId?: string;
   speechId?: string;
+  /** Metadata for model provider and name tracking. */
+  metadata?: MetricsMetadata;
 };
 
 export type VADMetrics = {
   type: 'vad_metrics';
   label: string;
   timestamp: number;
-  idleTime: number;
-  inferenceDurationTotal: number;
+  idleTimeMs: number;
+  inferenceDurationTotalMs: number;
   inferenceCount: number;
 };
 
@@ -76,16 +104,23 @@ export type EOUMetrics = {
    * Amount of time between the end of speech from VAD and the decision to end the user's turn.
    * Set to 0.0 if the end of speech was not detected.
    */
-  endOfUtteranceDelay: number;
+  endOfUtteranceDelayMs: number;
   /**
    * Time taken to obtain the transcript after the end of the user's speech.
    * Set to 0.0 if the end of speech was not detected.
    */
-  transcriptionDelay: number;
+  transcriptionDelayMs: number;
   /**
    * Time taken to invoke the user's `Agent.onUserTurnCompleted` callback.
    */
-  onUserTurnCompletedDelay: number;
+  onUserTurnCompletedDelayMs: number;
+  /**
+   * The time the user stopped speaking.
+   */
+  lastSpeakingTimeMs: number;
+  /**
+   * The ID of the speech handle.
+   */
   speechId?: string;
 };
 
@@ -118,13 +153,17 @@ export type RealtimeModelMetrics = {
    */
   timestamp: number;
   /**
-   * The duration of the response from created to done in seconds.
+   * The duration of the response from created to done in milliseconds.
    */
-  duration: number;
+  durationMs: number;
   /**
-   * Time to first audio token in seconds. -1 if no audio token was sent.
+   * The duration of the session connection in milliseconds (for session-based billing like xAI).
    */
-  ttft: number;
+  sessionDurationMs?: number;
+  /**
+   * Time to first audio token in milliseconds. -1 if no audio token was sent.
+   */
+  ttftMs: number;
   /**
    * Whether the request was cancelled.
    */
@@ -153,4 +192,24 @@ export type RealtimeModelMetrics = {
    * Details about the output tokens used in the Response.
    */
   outputTokenDetails: RealtimeModelMetricsOutputTokenDetails;
+  /** Metadata for model provider and name tracking. */
+  metadata?: MetricsMetadata;
+};
+
+export type InterruptionMetrics = {
+  type: 'interruption_metrics';
+  timestamp: number;
+  /** Latest RTT time taken to perform inference, in milliseconds. */
+  totalDuration: number;
+  /** Latest time taken by the model side, in milliseconds. */
+  predictionDuration: number;
+  /** Latest total time from onset of speech to final prediction, in milliseconds. */
+  detectionDelay: number;
+  /** Number of interruptions detected (incremental). */
+  numInterruptions: number;
+  /** Number of backchannels detected (incremental). */
+  numBackchannels: number;
+  /** Number of requests sent to the model (incremental). */
+  numRequests: number;
+  metadata?: MetricsMetadata;
 };

package/src/metrics/index.ts

@@ -4,11 +4,23 @@
 
 export type {
   AgentMetrics,
+  EOUMetrics,
+  InterruptionMetrics,
   LLMMetrics,
+  MetricsMetadata,
   RealtimeModelMetrics,
   STTMetrics,
   TTSMetrics,
   VADMetrics,
 } from './base.js';
+export {
+  filterZeroValues,
+  ModelUsageCollector,
+  type InterruptionModelUsage,
+  type LLMModelUsage,
+  type ModelUsage,
+  type STTModelUsage,
+  type TTSModelUsage,
+} from './model_usage.js';
 export { UsageCollector, type UsageSummary } from './usage_collector.js';
 export { logMetrics } from './utils.js';