@pipedog/core 0.0.0 → 0.1.0

package/dist/utils/tracing/service_attributes.js

@@ -0,0 +1,434 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/tracing/service_attributes.py
+/** Python `isinstance(value, (str, int, float, bool))`. */
+function isPrimitive(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+/** Convert a camelCase name back to upstream's snake_case (`voiceId` → `voice_id`). */
+export function _camelToSnake(name) {
+    return name.replace(/[A-Z]/g, (c) => `_${c.toLowerCase()}`);
+}
+/** Set every primitive extra keyword argument (keys not in `known`) as an attribute. */
+function setExtraAttributes(span, options, known) {
+    for (const [key, value] of Object.entries(options)) {
+        if (known.has(key))
+            continue;
+        if (isPrimitive(value)) {
+            span.setAttribute(key, value);
+        }
+    }
+}
+/** Set the primitive given fields of `settings` as `settings.<key>` attributes. */
+function setSettingsAttributes(span, settings) {
+    // Use givenFields() defensively in case a service doesn't initialize all settings.
+    if (settings) {
+        for (const [key, value] of Object.entries(settings.givenFields())) {
+            if (isPrimitive(value)) {
+                span.setAttribute(`settings.${_camelToSnake(key)}`, value);
+            }
+        }
+    }
+}
+/**
+ * Extract the standardized gen_ai.provider.name value from a service class name.
+ *
+ * Source:
+ * https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/registry/attributes/gen-ai.md
+ *
+ * Uses standard OTel names where possible, with special case mappings for
+ * service names that don't follow the pattern.
+ *
+ * @param serviceName The service class name to extract provider name from.
+ * @returns The standardized gen_ai.provider.name value.
+ */
+export function _getProviderNameFromServiceName(serviceName) {
+    const SPECIAL_CASE_MAPPINGS = {
+        // AWS
+        AWSBedrockLLMService: "aws.bedrock",
+        // Azure
+        AzureLLMService: "azure.ai.openai",
+        // Google
+        GoogleLLMService: "gcp.gemini",
+        GoogleVertexLLMService: "gcp.vertex_ai",
+        // Others
+        GrokLLMService: "x_ai",
+        MistralLLMService: "mistral_ai",
+    };
+    if (Object.hasOwn(SPECIAL_CASE_MAPPINGS, serviceName)) {
+        return SPECIAL_CASE_MAPPINGS[serviceName];
+    }
+    let provider;
+    if (serviceName.endsWith("LLMService")) {
+        provider = serviceName.slice(0, -10).toLowerCase();
+    }
+    else {
+        provider = serviceName.toLowerCase();
+    }
+    return provider;
+}
+const TTS_KNOWN = new Set([
+    "serviceName",
+    "model",
+    "voiceId",
+    "text",
+    "settings",
+    "characterCount",
+    "operationName",
+    "ttfb",
+]);
+/**
+ * Add TTS-specific attributes to a span.
+ *
+ * @param span The span to add attributes to.
+ * @param options The TTS attributes; any other key is added as an attribute.
+ */
+export function addTtsSpanAttributes(span, options) {
+    const operationName = options.operationName ?? "tts";
+    // Add standard attributes
+    span.setAttribute("gen_ai.provider.name", options.serviceName.replaceAll("TTSService", "").toLowerCase());
+    span.setAttribute("gen_ai.request.model", options.model);
+    span.setAttribute("gen_ai.operation.name", operationName);
+    span.setAttribute("gen_ai.output.type", "speech");
+    span.setAttribute("voice_id", options.voiceId);
+    // Add optional attributes
+    if (options.text) {
+        span.setAttribute("text", options.text);
+    }
+    if (options.characterCount !== null && options.characterCount !== undefined) {
+        span.setAttribute("metrics.character_count", options.characterCount);
+    }
+    if (options.ttfb !== null && options.ttfb !== undefined) {
+        span.setAttribute("metrics.ttfb", options.ttfb);
+    }
+    setSettingsAttributes(span, options.settings);
+    // Add any additional keyword arguments as attributes
+    setExtraAttributes(span, options, TTS_KNOWN);
+}
+const STT_KNOWN = new Set([
+    "serviceName",
+    "model",
+    "operationName",
+    "transcript",
+    "isFinal",
+    "language",
+    "userId",
+    "settings",
+    "vadEnabled",
+    "ttfb",
+]);
+/**
+ * Add STT-specific attributes to a span.
+ *
+ * @param span The span to add attributes to.
+ * @param options The STT attributes; any other key is added as an attribute.
+ */
+export function addSttSpanAttributes(span, options) {
+    const operationName = options.operationName ?? "stt";
+    // Add standard attributes
+    span.setAttribute("gen_ai.provider.name", options.serviceName.replaceAll("STTService", "").toLowerCase());
+    span.setAttribute("gen_ai.request.model", options.model);
+    span.setAttribute("gen_ai.operation.name", operationName);
+    span.setAttribute("vad_enabled", options.vadEnabled ?? false);
+    // Add optional attributes
+    if (options.transcript) {
+        span.setAttribute("transcript", options.transcript);
+    }
+    if (options.isFinal !== null && options.isFinal !== undefined) {
+        span.setAttribute("is_final", options.isFinal);
+    }
+    if (options.language) {
+        span.setAttribute("language", options.language);
+    }
+    if (options.userId) {
+        span.setAttribute("user_id", options.userId);
+    }
+    if (options.ttfb !== null && options.ttfb !== undefined) {
+        span.setAttribute("metrics.ttfb", options.ttfb);
+    }
+    setSettingsAttributes(span, options.settings);
+    // Add any additional keyword arguments as attributes
+    setExtraAttributes(span, options, STT_KNOWN);
+}
+const LLM_KNOWN = new Set([
+    "serviceName",
+    "model",
+    "stream",
+    "messages",
+    "output",
+    "tools",
+    "toolCount",
+    "toolChoice",
+    "systemInstructions",
+    "parameters",
+    "extraParameters",
+    "ttfb",
+]);
+const GEN_AI_REQUEST_PARAMETERS = new Set([
+    "temperature",
+    "max_tokens",
+    "max_completion_tokens",
+    "top_p",
+    "top_k",
+    "frequency_penalty",
+    "presence_penalty",
+    "seed",
+]);
+/**
+ * Add LLM-specific attributes to a span.
+ *
+ * @param span The span to add attributes to.
+ * @param options The LLM attributes; any other key is added as an attribute.
+ *   Keys of `parameters` may be camelCase settings names; they are converted
+ *   to snake_case attribute names.
+ */
+export function addLlmSpanAttributes(span, options) {
+    // Add standard attributes
+    span.setAttribute("gen_ai.provider.name", _getProviderNameFromServiceName(options.serviceName));
+    span.setAttribute("gen_ai.request.model", options.model);
+    span.setAttribute("gen_ai.operation.name", "chat");
+    span.setAttribute("gen_ai.output.type", "text");
+    span.setAttribute("stream", options.stream ?? true);
+    // Add optional attributes
+    if (options.messages) {
+        span.setAttribute("input", options.messages);
+    }
+    if (options.output) {
+        span.setAttribute("output", options.output);
+    }
+    if (options.tools) {
+        span.setAttribute("tools", options.tools);
+    }
+    if (options.toolCount !== null && options.toolCount !== undefined) {
+        span.setAttribute("tool_count", options.toolCount);
+    }
+    if (options.toolChoice) {
+        span.setAttribute("tool_choice", options.toolChoice);
+    }
+    if (options.systemInstructions) {
+        span.setAttribute("gen_ai.system_instructions", options.systemInstructions);
+    }
+    if (options.ttfb !== null && options.ttfb !== undefined) {
+        span.setAttribute("metrics.ttfb", options.ttfb);
+    }
+    // Add parameters if provided
+    if (options.parameters) {
+        for (const [rawKey, value] of Object.entries(options.parameters)) {
+            if (isPrimitive(value)) {
+                const key = _camelToSnake(rawKey);
+                if (GEN_AI_REQUEST_PARAMETERS.has(key)) {
+                    span.setAttribute(`gen_ai.request.${key}`, value);
+                }
+                else {
+                    span.setAttribute(`param.${key}`, value);
+                }
+            }
+        }
+    }
+    // Add extra parameters if provided
+    if (options.extraParameters) {
+        for (const [key, value] of Object.entries(options.extraParameters)) {
+            if (isPrimitive(value)) {
+                span.setAttribute(`extra.${key}`, value);
+            }
+        }
+    }
+    // Add any additional keyword arguments as attributes
+    setExtraAttributes(span, options, LLM_KNOWN);
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+const GEMINI_KNOWN = new Set([
+    "serviceName",
+    "model",
+    "operationName",
+    "voiceId",
+    "language",
+    "modalities",
+    "settings",
+    "tools",
+    "toolsSerialized",
+    "transcript",
+    "isInput",
+    "textOutput",
+    "audioDataSize",
+]);
+/** An enum member upstream (`.value`); a plain string in TS. */
+function enumValue(value) {
+    return isObject(value) && "value" in value ? value.value : value;
+}
+/**
+ * Add Gemini Live specific attributes to a span.
+ *
+ * @param span The span to add attributes to.
+ * @param options The Gemini Live attributes; any other key is added as an attribute.
+ */
+export function addGeminiLiveSpanAttributes(span, options) {
+    // Add standard attributes
+    span.setAttribute("gen_ai.provider.name", "gcp.gemini");
+    span.setAttribute("gen_ai.request.model", options.model);
+    span.setAttribute("gen_ai.operation.name", options.operationName);
+    span.setAttribute("service.operation", options.operationName);
+    // Add optional attributes
+    if (options.voiceId) {
+        span.setAttribute("voice_id", options.voiceId);
+    }
+    if (options.language) {
+        span.setAttribute("language", options.language);
+    }
+    if (options.modalities) {
+        span.setAttribute("modalities", options.modalities);
+    }
+    if (options.transcript) {
+        span.setAttribute("transcript", options.transcript);
+        if (options.isInput !== null && options.isInput !== undefined) {
+            span.setAttribute("transcript.is_input", options.isInput);
+        }
+    }
+    if (options.textOutput) {
+        span.setAttribute("text_output", options.textOutput);
+    }
+    if (options.audioDataSize !== null && options.audioDataSize !== undefined) {
+        span.setAttribute("audio.data_size_bytes", options.audioDataSize);
+    }
+    const tools = options.tools;
+    if (tools && tools.length > 0) {
+        span.setAttribute("tools.count", tools.length);
+        span.setAttribute("tools.available", true);
+        // Add individual tool names for easier filtering
+        const toolNames = [];
+        for (const tool of tools) {
+            if (isObject(tool) && "name" in tool) {
+                const toolName = tool.name;
+                if (toolName !== null && toolName !== undefined) {
+                    toolNames.push(String(toolName));
+                }
+            }
+        }
+        if (toolNames.length > 0) {
+            span.setAttribute("tools.names", toolNames.join(","));
+        }
+    }
+    if (options.toolsSerialized) {
+        span.setAttribute("tools.definitions", options.toolsSerialized);
+    }
+    // Use givenFields() defensively in case a service doesn't initialize all settings.
+    if (options.settings) {
+        for (const [key, value] of Object.entries(options.settings.givenFields())) {
+            if (isPrimitive(value)) {
+                span.setAttribute(`settings.${_camelToSnake(key)}`, value);
+            }
+            else if (key === "vad" && value) {
+                // Handle VAD settings specially
+                if (isObject(value)) {
+                    if ("disabled" in value && value.disabled !== null && value.disabled !== undefined) {
+                        span.setAttribute("settings.vad.disabled", value.disabled);
+                    }
+                    if ("startSensitivity" in value && value.startSensitivity) {
+                        span.setAttribute("settings.vad.start_sensitivity", String(enumValue(value.startSensitivity)));
+                    }
+                    if ("endSensitivity" in value && value.endSensitivity) {
+                        span.setAttribute("settings.vad.end_sensitivity", String(enumValue(value.endSensitivity)));
+                    }
+                }
+            }
+        }
+    }
+    // Add any additional keyword arguments as attributes
+    setExtraAttributes(span, options, GEMINI_KNOWN);
+}
+const OPENAI_REALTIME_KNOWN = new Set([
+    "serviceName",
+    "model",
+    "operationName",
+    "sessionProperties",
+    "transcript",
+    "isInput",
+    "contextMessages",
+    "functionCalls",
+    "tools",
+    "toolsSerialized",
+    "audioDataSize",
+]);
+/**
+ * Add OpenAI Realtime specific attributes to a span.
+ *
+ * @param span The span to add attributes to.
+ * @param options The OpenAI Realtime attributes; any other key is added as an attribute.
+ */
+export function addOpenaiRealtimeSpanAttributes(span, options) {
+    // Add standard attributes
+    span.setAttribute("gen_ai.provider.name", "openai");
+    span.setAttribute("gen_ai.request.model", options.model);
+    span.setAttribute("gen_ai.operation.name", options.operationName);
+    span.setAttribute("service.operation", options.operationName);
+    // Add optional attributes
+    if (options.transcript) {
+        span.setAttribute("transcript", options.transcript);
+        if (options.isInput !== null && options.isInput !== undefined) {
+            span.setAttribute("transcript.is_input", options.isInput);
+        }
+    }
+    if (options.contextMessages) {
+        span.setAttribute("input", options.contextMessages);
+    }
+    if (options.audioDataSize !== null && options.audioDataSize !== undefined) {
+        span.setAttribute("audio.data_size_bytes", options.audioDataSize);
+    }
+    const tools = options.tools;
+    if (tools && tools.length > 0) {
+        span.setAttribute("tools.count", tools.length);
+        span.setAttribute("tools.available", true);
+        // Add individual tool names for easier filtering
+        const toolNames = [];
+        for (const tool of tools) {
+            if (isObject(tool) && "name" in tool) {
+                toolNames.push(String(tool.name));
+            }
+            else if (isObject(tool) && isObject(tool.function) && "name" in tool.function) {
+                toolNames.push(String(tool.function.name));
+            }
+        }
+        if (toolNames.length > 0) {
+            span.setAttribute("tools.names", toolNames.join(","));
+        }
+    }
+    if (options.toolsSerialized) {
+        span.setAttribute("tools.definitions", options.toolsSerialized);
+    }
+    const functionCalls = options.functionCalls;
+    if (functionCalls && functionCalls.length > 0) {
+        span.setAttribute("function_calls.count", functionCalls.length);
+        const call = functionCalls[0];
+        if (isObject(call) && "name" in call) {
+            span.setAttribute("function_calls.first_name", String(call.name));
+        }
+    }
+    // Add session properties if provided
+    if (options.sessionProperties) {
+        for (const [key, value] of Object.entries(options.sessionProperties)) {
+            if (isPrimitive(value)) {
+                span.setAttribute(`session.${key}`, value);
+            }
+            else if (key === "turn_detection" && value !== null && value !== undefined) {
+                if (typeof value === "boolean") {
+                    span.setAttribute("session.turn_detection.enabled", value);
+                }
+                else if (isObject(value)) {
+                    span.setAttribute("session.turn_detection.enabled", true);
+                    for (const [tdKey, tdValue] of Object.entries(value)) {
+                        if (isPrimitive(tdValue)) {
+                            span.setAttribute(`session.turn_detection.${tdKey}`, tdValue);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    // Add any additional keyword arguments as attributes
+    setExtraAttributes(span, options, OPENAI_REALTIME_KNOWN);
+}
+//# sourceMappingURL=service_attributes.js.map

package/dist/utils/tracing/service_decorators.d.ts

@@ -0,0 +1,214 @@
+import { type OtelContext, type OtelSpan } from "./setup.ts";
+type Service = any;
+/** A decorator returned by the `traced*` functions. */
+export type TracedMethodDecorator = (value: any, context?: any, descriptor?: PropertyDescriptor) => any;
+/**
+ * Get the model name from a service instance.
+ *
+ * This is a bit of a mess — there were multiple places a model name could live.
+ * Soon, `this._settings` should be the only source of truth about model name.
+ * In fact...it might already be the case, but juuuuust to be safe, we'll
+ * check all the places we used to store it.
+ */
+export declare function _getModelName(service: Service): string;
+/**
+ * Get the current turn's tracing context if available.
+ *
+ * @param service The service instance.
+ * @returns The turn context, or null if unavailable.
+ */
+export declare function _getTurnContext(service: Service): OtelContext | null;
+/**
+ * Get the parent service span context (internal use only).
+ *
+ * This looks for the service span that was created when the service was initialized,
+ * or falls back to the conversation context if available.
+ *
+ * @param service The service instance.
+ * @returns The parent service context, or null if unavailable.
+ */
+export declare function _getParentServiceContext(service: Service): OtelContext | null;
+/**
+ * Resolve the effective system instruction for tracing (internal use only).
+ *
+ * System instructions can live on the LLM service (`settings.systemInstruction`,
+ * the norm — and the composed source of truth, see
+ * `LLMService._composeSystemInstruction`) or be supplied as an initial
+ * system message in the context. The service setting takes priority,
+ * matching service behavior.
+ *
+ * @param service The LLM service instance.
+ * @param context The universal `LLMContext`, or null.
+ * @returns The system instruction text, or null if none is present.
+ */
+export declare function _getSystemInstruction(service: Service, context: Service): string | null;
+/**
+ * Add token usage metrics to a span (internal use only).
+ *
+ * @param span The span to add token metrics to.
+ * @param tokenUsage A dict (snake_case keys) or `LLMTokenUsage` object
+ *   containing token usage information.
+ */
+export declare function _addTokenUsageToSpan(span: OtelSpan, tokenUsage: unknown): void;
+/**
+ * Add STT usage metrics to a span (internal use only).
+ *
+ * @param span The span to add usage metrics to.
+ * @param usage `STTUsage` object with audio seconds.
+ */
+export declare function _addSttUsageToSpan(span: OtelSpan, usage: Service): void;
+export interface TracedOptions {
+    /** Custom span name. */
+    name?: string | null;
+}
+/**
+ * Trace TTS service methods with TTS-specific attributes.
+ *
+ * Automatically captures and records:
+ *
+ * - Service name and model information
+ * - Voice ID and settings
+ * - Character count and text content
+ * - Performance metrics like TTFB
+ *
+ * The span is scoped to the full synthesis operation, from
+ * `createAudioContext` until `TTSStoppedFrame` (or `removeAudioContext` as a
+ * safety net), so TTFB and any other runtime-computed metrics land on the
+ * correct span even when audio chunks are delivered after `runTts` returns
+ * (e.g. WebSocket streaming TTS services).
+ *
+ * Works with both async functions and generators.
+ *
+ * @example
+ * class MyTTSService extends TTSService {
+ *   @tracedTts
+ *   async *runTts(text: string, contextId: string) { ... }
+ * }
+ *
+ * @param func The TTS method to trace (when used as `@tracedTts`).
+ * @param options.name Custom span name. Defaults to service type and class name.
+ * @returns Wrapped method with TTS-specific tracing, or a decorator when
+ *   called with options.
+ */
+export declare function tracedTts(options?: TracedOptions): TracedMethodDecorator;
+export declare function tracedTts(func: any, context?: any, descriptor?: PropertyDescriptor): any;
+/**
+ * Apply `tracedTts` to `owner[attrName]` without decorator syntax.
+ *
+ * Equivalent to upstream's class-definition-time `__set_name__` hook: wraps
+ * `owner.setup` so the audio-context patches install on every instance, and
+ * replaces the method with its traced wrapper.
+ *
+ * @example
+ * class MyTTSService extends TTSService {
+ *   async *runTts(text: string, contextId: string) { ... }
+ *   static {
+ *     installTracedTts(this.prototype, "runTts");
+ *   }
+ * }
+ */
+export declare function installTracedTts(owner: object, attrName: string, _options?: TracedOptions): void;
+/**
+ * Trace STT service methods with transcription attributes.
+ *
+ * Automatically captures and records:
+ *
+ * - Service name and model information
+ * - Transcription text and final status
+ * - Language information
+ * - Performance metrics like TTFB
+ * - Usage metrics (audio seconds) when the service reports them via
+ *   `startSttUsageMetrics`
+ *
+ * The span is scoped to one STT segment, from `VADUserStartedSpeakingFrame`
+ * (or the first `TranscriptionFrame` when VAD did not fire, e.g. whispered
+ * speech) until a finalized `TranscriptionFrame`. Multiple finalized
+ * transcripts in a single user turn produce multiple sequential spans, each
+ * anchored at the point speech for that segment began. `metrics.ttfb` is read
+ * after the base `pushFrame` runs `stopTtfbMetrics` for the finalized frame,
+ * so the value is correct for the closing span.
+ *
+ * @param func The STT method to trace (when used as `@tracedStt`).
+ * @param options.name Custom span name. Defaults to function name.
+ * @returns The original method unchanged. The decorator's class-level work is
+ *   to install a `pushFrame` wrapper on the owning class (or, as a TC39
+ *   decorator, on each instance) that owns the span lifetime.
+ */
+export declare function tracedStt(options?: TracedOptions): TracedMethodDecorator;
+export declare function tracedStt(func: any, context?: any, descriptor?: PropertyDescriptor): any;
+/**
+ * Apply `tracedStt` to `owner` without decorator syntax.
+ *
+ * Equivalent to upstream's class-definition-time `__set_name__` hook: wraps
+ * `pushFrame`, `stopTtfbMetrics` and `startSttUsageMetrics` so VAD,
+ * transcription, and finalization events drive the span lifecycle. The
+ * decorated method itself runs unchanged.
+ *
+ * @example
+ * class MySTTService extends STTService {
+ *   static {
+ *     installTracedStt(this.prototype, "_handleTranscription");
+ *   }
+ * }
+ */
+export declare function installTracedStt(owner: object, _attrName?: string, _options?: TracedOptions): void;
+/**
+ * Trace LLM service methods with LLM-specific attributes.
+ *
+ * Automatically captures and records:
+ *
+ * - Service name and model information
+ * - Context content and messages
+ * - Tool configurations
+ * - Token usage metrics
+ * - Performance metrics like TTFB
+ * - Aggregated output text
+ *
+ * @param func The LLM method to trace (when used as `@tracedLlm`).
+ * @param options.name Custom span name. Defaults to service type and class name.
+ * @returns Wrapped method with LLM-specific tracing, or a decorator when
+ *   called with options.
+ */
+export declare function tracedLlm(options?: TracedOptions): TracedMethodDecorator;
+export declare function tracedLlm(func: any, context?: any, descriptor?: PropertyDescriptor): any;
+/**
+ * Get the AUDIO token count from a Gemini modality breakdown, if reported.
+ *
+ * Duck-typed (`entry.modality` / `entry.tokenCount`) so this module doesn't
+ * depend on Google types. Gemini omits modalities with no tokens (and omits
+ * the list entirely when there is no breakdown), so absence means "not
+ * reported" rather than zero.
+ *
+ * @param details A modality breakdown from usage metadata, e.g. `promptTokensDetails`.
+ * @returns The AUDIO token count, or null if not reported.
+ */
+export declare function _geminiAudioModalityTokens(details: unknown): number | null;
+/**
+ * Trace Gemini Live service methods with operation-specific attributes.
+ *
+ * This decorator automatically captures relevant information based on the operation type:
+ *
+ * - llm_setup: Configuration, tools definitions, and system instructions
+ * - llm_tool_call: Function call information
+ * - llm_tool_result: Function execution results
+ * - llm_response: Complete LLM response with usage and output
+ *
+ * @param operation The operation name (matches the event type being handled).
+ * @returns A decorator that wraps the method with Gemini Live specific tracing.
+ */
+export declare function tracedGeminiLive(operation: string): TracedMethodDecorator;
+/**
+ * Trace OpenAI Realtime service methods with operation-specific attributes.
+ *
+ * This decorator automatically captures relevant information based on the operation type:
+ *
+ * - llm_setup: Session configuration and tools
+ * - llm_request: Context and input messages
+ * - llm_response: Usage metadata, output, and function calls
+ *
+ * @param operation The operation name (matches the event type being handled).
+ * @returns A decorator that wraps the method with OpenAI Realtime specific tracing.
+ */
+export declare function tracedOpenaiRealtime(operation: string): TracedMethodDecorator;
+export {};
+//# sourceMappingURL=service_decorators.d.ts.map