fix comments

Author: toubatbrian

agents/src/metrics/usage_collector.ts

@@ -4,14 +4,9 @@
 import { log } from '../log.js';
 import type { AgentMetrics } from './base.js';
 
-// Ref: python livekit-agents/livekit/agents/metrics/usage_collector.py - lines 10-14 (diff)
-// NOTE: Python uses warnings.warn() for deprecation at runtime.
-// TypeScript uses JSDoc @deprecated which shows in IDE.
-// We also add optional console.warn() in constructor for runtime parity.
 /**
- * @deprecated Use LLMModelUsage, TTSModelUsage, or STTModelUsage from './model_usage.js' instead.
+ * @deprecated Use LLMModelUsage, TTSModelUsage, or STTModelUsage instead.
  * These new types provide per-model/provider usage aggregation for more detailed tracking.
- * Ref: python livekit-agents/livekit/agents/metrics/usage_collector.py - lines 10-14 (diff)
  */
 export interface UsageSummary {
   llmPromptTokens: number;
@@ -22,7 +17,7 @@ export interface UsageSummary {
 }
 
 /**
- * @deprecated Use ModelUsageCollector from './model_usage.js' instead.
+ * @deprecated Use ModelUsageCollector instead.
  * ModelUsageCollector provides per-model/provider usage aggregation for more detailed tracking.
  */
 export class UsageCollector {

agents/src/telemetry/trace_types.ts

@@ -30,10 +30,9 @@ export const ATTR_FUNCTION_TOOLS = 'lk.function_tools';
 export const ATTR_RESPONSE_TEXT = 'lk.response.text';
 export const ATTR_RESPONSE_FUNCTION_CALLS = 'lk.response.function_calls';
 
-// Ref: python livekit-agents/livekit/agents/telemetry/trace_types.py - lines 5-6 (diff)
 // New latency attributes for response timing
 /** Time to first token in seconds. */
-export const ATTR_RESPONSE_TTFT = 'lk.response.ttft'; // Ref: line 5 (ATTR_RESPONSE_TTFT)
+export const ATTR_RESPONSE_TTFT = 'lk.response.ttft';
 
 // function tool
 export const ATTR_FUNCTION_TOOL_NAME = 'lk.function_tool.name';
@@ -46,9 +45,8 @@ export const ATTR_TTS_INPUT_TEXT = 'lk.input_text';
 export const ATTR_TTS_STREAMING = 'lk.tts.streaming';
 export const ATTR_TTS_LABEL = 'lk.tts.label';
 
-// Ref: python livekit-agents/livekit/agents/telemetry/trace_types.py - lines 10-11 (diff)
 /** Time to first byte in seconds. */
-export const ATTR_RESPONSE_TTFB = 'lk.response.ttfb'; // Ref: line 10 (ATTR_RESPONSE_TTFB)
+export const ATTR_RESPONSE_TTFB = 'lk.response.ttfb';
 
 // eou detection
 export const ATTR_EOU_PROBABILITY = 'lk.eou.probability';
@@ -72,18 +70,15 @@ export const ATTR_LLM_METRICS = 'lk.llm_metrics';
 export const ATTR_TTS_METRICS = 'lk.tts_metrics';
 export const ATTR_REALTIME_MODEL_METRICS = 'lk.realtime_model_metrics';
 
-// Ref: python livekit-agents/livekit/agents/telemetry/trace_types.py - lines 16-17 (diff)
-// latency span attributes
 /** End-to-end latency in seconds. */
-export const ATTR_E2E_LATENCY = 'lk.e2e_latency'; // Ref: line 17 (ATTR_E2E_LATENCY)
+export const ATTR_E2E_LATENCY = 'lk.e2e_latency';
 
 // OpenTelemetry GenAI attributes
 // OpenTelemetry specification: https://opentelemetry.io/docs/specs/semconv/registry/attributes/gen-ai/
 export const ATTR_GEN_AI_OPERATION_NAME = 'gen_ai.operation.name';
 export const ATTR_GEN_AI_REQUEST_MODEL = 'gen_ai.request.model';
-// Ref: python livekit-agents/livekit/agents/telemetry/trace_types.py - lines 22-23 (diff)
 /** The provider name (e.g., 'openai', 'anthropic'). */
-export const ATTR_GEN_AI_PROVIDER_NAME = 'gen_ai.provider.name'; // Ref: line 23
+export const ATTR_GEN_AI_PROVIDER_NAME = 'gen_ai.provider.name';
 export const ATTR_GEN_AI_USAGE_INPUT_TOKENS = 'gen_ai.usage.input_tokens';
 export const ATTR_GEN_AI_USAGE_OUTPUT_TOKENS = 'gen_ai.usage.output_tokens';
 

agents/src/voice/agent_session.ts

@@ -17,7 +17,6 @@ import {
 } from '../inference/index.js';
 import type { InterruptionEvent } from '../inference/interruption/types.js';
 import { type JobContext, getJobContext } from '../job.js';
-// Ref: python livekit-agents/livekit/agents/voice/agent_session.py - lines 5-6 (diff)
 import type { FunctionCall, FunctionCallOutput } from '../llm/chat_context.js';
 import { AgentHandoffItem, ChatContext, ChatMessage } from '../llm/chat_context.js';
 import type { LLM, RealtimeModel, RealtimeModelError, ToolChoice } from '../llm/index.js';
@@ -72,15 +71,9 @@ import type {
 } from './turn_config/turn_handling.js';
 import { migrateLegacyOptions } from './turn_config/utils.js';
 
-// Ref: python livekit-agents/livekit/agents/voice/agent_session.py - lines 17-19 (diff)
-// NOTE: Python uses @dataclass. TypeScript uses interface.
-/**
- * Usage summary for an AgentSession, aggregated per model/provider combination.
- * Ref: python livekit-agents/livekit/agents/voice/agent_session.py - lines 17-19 (diff)
- */
 export interface AgentSessionUsage {
   /** List of usage summaries, one per model/provider combination. */
-  modelUsage: ModelUsage[]; // Ref: line 18 (model_usage: list[ModelUsage])
+  modelUsage: ModelUsage[];
 }
 
 export interface SessionOptions {
@@ -206,8 +199,6 @@ export class AgentSession<
 
   private _interruptionDetection?: InterruptionConfig['mode'];
 
-  // Ref: python livekit-agents/livekit/agents/voice/agent_session.py - line 34 (diff)
-  // Collects and aggregates usage metrics per model/provider combination
   private _usageCollector: ModelUsageCollector = new ModelUsageCollector();
 
   /** @internal */
@@ -290,9 +281,6 @@ export class AgentSession<
   ): boolean {
     const eventData = args[0] as AgentEvent;
     this._recordedEvents.push(eventData);
-    // Ref: python livekit-agents/livekit/agents/voice/agent_session.py - lines 39-40 (diff)
-    // if isinstance(arg, MetricsCollectedEvent):
-    //     self._usage_collector.collect(arg.metrics)
     if (event === AgentSessionEventTypes.MetricsCollected) {
       this._usageCollector.collect((eventData as MetricsCollectedEvent).metrics);
     }
@@ -328,10 +316,8 @@ export class AgentSession<
     return this._interruptionDetection;
   }
 
-  // Ref: python livekit-agents/livekit/agents/voice/agent_session.py - lines 45-48 (diff)
   /**
    * Returns usage summaries for this session, one per model/provider combination.
-   * Ref: python livekit-agents/livekit/agents/voice/agent_session.py - lines 45-48 (diff)
    */
   get usage(): AgentSessionUsage {
     return { modelUsage: this._usageCollector.flatten() };
@@ -959,8 +945,6 @@ export class AgentSession<
     this.rootSpanContext = undefined;
     this.llmErrorCounts = 0;
     this.ttsErrorCounts = 0;
-    // Ref: python livekit-agents/livekit/agents/voice/agent_session.py - lines 53-54 (diff)
-    // Reset collector on session reset
     this._usageCollector = new ModelUsageCollector();
 
     this.logger.info({ reason, error }, 'AgentSession closed');

agents/src/voice/generation.ts

@@ -36,7 +36,6 @@ export class _LLMGenerationData {
   generatedText: string = '';
   generatedToolCalls: FunctionCall[];
   id: string;
-  // Time to first token in seconds (for TTFT span attribute)
   ttft?: number;
 
   constructor(
@@ -382,16 +381,14 @@ export function updateInstructions(options: {
   }
 }
 
-// Ref: python livekit-agents/livekit/agents/voice/generation.py - lines 3-7 (diff)
-// Added model and provider parameters to generation functions
 export function performLLMInference(
   node: LLMNode,
   chatCtx: ChatContext,
   toolCtx: ToolContext,
   modelSettings: ModelSettings,
   controller: AbortController,
-  model?: string, // Ref: line 5 (model: str | None = None)
-  provider?: string, // Ref: line 6 (provider: str | None = None)
+  model?: string,
+  provider?: string,
 ): [Task<void>, _LLMGenerationData] {
   const textStream = new IdentityTransform<string>();
   const toolCallStream = new IdentityTransform<FunctionCall>();
@@ -407,20 +404,15 @@ export function performLLMInference(
     );
     span.setAttribute(traceTypes.ATTR_FUNCTION_TOOLS, JSON.stringify(Object.keys(toolCtx)));
 
-    // Ref: python livekit-agents/livekit/agents/voice/generation.py - lines 36-48 (diff)
-    // Set model/provider attributes on the span
     if (model) {
-      // Ref: lines 44-45
       span.setAttribute(traceTypes.ATTR_GEN_AI_REQUEST_MODEL, model);
     }
     if (provider) {
-      // Ref: lines 46-47
       span.setAttribute(traceTypes.ATTR_GEN_AI_PROVIDER_NAME, provider);
     }
 
     let llmStreamReader: ReadableStreamDefaultReader<string | ChatChunk> | null = null;
     let llmStream: ReadableStream<string | ChatChunk> | null = null;
-    // Track start time for TTFT calculation
     const startTime = performance.now() / 1000; // Convert to seconds
     let firstTokenReceived = false;
 
@@ -445,7 +437,6 @@ export function performLLMInference(
         const { done, value: chunk } = result;
         if (done) break;
 
-        // Track time to first token
         if (!firstTokenReceived) {
           firstTokenReceived = true;
           data.ttft = performance.now() / 1000 - startTime;
@@ -521,35 +512,28 @@ export function performLLMInference(
   ];
 }
 
-// Ref: python livekit-agents/livekit/agents/voice/generation.py - lines 77-82 (diff)
-// Added model and provider parameters for TTS generation
 export function performTTSInference(
   node: TTSNode,
   text: ReadableStream<string>,
   modelSettings: ModelSettings,
   controller: AbortController,
-  model?: string, // Ref: line 79 (model: str | None = None)
-  provider?: string, // Ref: line 80 (provider: str | None = None)
+  model?: string,
+  provider?: string,
 ): [Task<void>, ReadableStream<AudioFrame>] {
   const audioStream = new IdentityTransform<AudioFrame>();
   const outputWriter = audioStream.writable.getWriter();
   const audioOutputStream = audioStream.readable;
 
   const _performTTSInferenceImpl = async (signal: AbortSignal, span: Span) => {
-    // Ref: python livekit-agents/livekit/agents/voice/generation.py - lines 77-82 (diff)
-    // Set model/provider attributes on the span
     if (model) {
-      // Ref: lines 79-80
       span.setAttribute(traceTypes.ATTR_GEN_AI_REQUEST_MODEL, model);
     }
     if (provider) {
-      // Ref: lines 81-82
       span.setAttribute(traceTypes.ATTR_GEN_AI_PROVIDER_NAME, provider);
     }
 
     let ttsStreamReader: ReadableStreamDefaultReader<AudioFrame> | null = null;
     let ttsStream: ReadableStream<AudioFrame> | null = null;
-    // Track start time for TTFB calculation
     const startTime = performance.now() / 1000; // Convert to seconds
     let firstByteReceived = false;
 
@@ -570,7 +554,6 @@ export function performTTSInference(
           break;
         }
 
-        // Track time to first byte and set span attribute
         if (!firstByteReceived) {
           firstByteReceived = true;
           const ttfb = performance.now() / 1000 - startTime;
@@ -663,7 +646,6 @@ export function performTextForwarding(
 
 export interface _AudioOut {
   audio: Array<AudioFrame>;
-  /** Future that will be set with the timestamp of the first frame's capture */
   firstFrameFut: Future<number>;
 }
 
@@ -751,7 +733,6 @@ export function performAudioForwarding(
   ];
 }
 
-// function_tool span is already implemented in tracableToolExecution below (line ~796)
 export function performToolExecutions({
   session,
   speechHandle,