@pipedog/core 0.0.0 → 0.2.0

package/dist/utils/text/transforms/voice_formatter.js

@@ -0,0 +1,98 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/text/transforms/voice_formatter.py
+import { normalizeAcronyms } from "./acronyms.js";
+import { expandCurrency } from "./currency.js";
+import { normalizeDates } from "./dates.js";
+import { emailToSpeech } from "./email.js";
+import { expandNumbers } from "./numbers.js";
+import { expandPercentages } from "./percentages.js";
+import { expandPhoneNumbers } from "./phone.js";
+import { replaceText } from "./replacements.js";
+import { stripMarkdown } from "./strip_markdown.js";
+import { expandUnits } from "./units.js";
+/**
+ * Configurable bundle that applies a pipeline of voice-formatting transforms.
+ *
+ * Each option enables or disables one transform. Transforms are applied in a
+ * deliberate order: structural cleanup first, language expansions second, user
+ * replacements last.
+ *
+ * @example
+ * ```ts
+ * const formatter = new VoiceFormatter({
+ *   stripMarkdown: true,
+ *   expandCurrency: true,
+ *   numberDigitCutoff: 2025,
+ *   customReplacements: [[/\bDr\./, "Doctor"]],
+ * });
+ * const tts = new CartesiaTTSService({
+ *   textTransforms: [["*", formatter]],
+ * });
+ * ```
+ */
+// biome-ignore lint/suspicious/noUnsafeDeclarationMerging: adds Python's `__call__` signature to the class.
+export class VoiceFormatter {
+    _transforms;
+    /** Initialize the voice formatter. */
+    constructor(options = {}) {
+        const call = async (text, textType) => self.transform(text, textType);
+        const self = Object.setPrototypeOf(call, new.target.prototype);
+        self._transforms = [];
+        if (options.stripMarkdown ?? true) {
+            self._transforms.push(stripMarkdown);
+        }
+        // emailToSpeech must run before expandPhoneNumbers (phone regex matches
+        // digit-only domains) and before normalizeAcronyms (all-caps local parts get
+        // letter-spaced, breaking the email pattern).
+        if (options.emailToSpeech ?? true) {
+            self._transforms.push(emailToSpeech);
+        }
+        if (options.expandPhoneNumbers ?? true) {
+            self._transforms.push(expandPhoneNumbers);
+        }
+        if (options.normalizeDates ?? true) {
+            self._transforms.push(normalizeDates);
+        }
+        if (options.expandCurrency ?? true) {
+            self._transforms.push(expandCurrency);
+        }
+        if (options.expandPercentages ?? true) {
+            self._transforms.push(expandPercentages);
+        }
+        // expandUnits must run before normalizeAcronyms: uppercase unit abbreviations
+        // like "MB" or "MPH" would be letter-spaced first and then not recognized.
+        if (options.expandUnits ?? true) {
+            self._transforms.push(expandUnits);
+        }
+        if (options.normalizeAcronyms ?? true) {
+            self._transforms.push(normalizeAcronyms);
+        }
+        if (options.expandNumbers ?? false) {
+            self._transforms.push(expandNumbers(options.numberDigitCutoff ?? null));
+        }
+        if (options.customReplacements && options.customReplacements.length > 0) {
+            self._transforms.push(replaceText(options.customReplacements));
+        }
+        // biome-ignore lint/correctness/noConstructorReturn: returning the callable is the point (see above).
+        return self;
+    }
+    /**
+     * Apply all configured transforms in order.
+     *
+     * Python's `__call__`; calling the instance runs this.
+     *
+     * @param text Input text to transform.
+     * @param textType Text type passed through to each transform.
+     * @returns Transformed text ready for TTS synthesis.
+     */
+    async transform(text, textType) {
+        for (const transform of this._transforms) {
+            text = await transform(text, textType);
+        }
+        return text;
+    }
+}
+//# sourceMappingURL=voice_formatter.js.map

package/dist/utils/text/unicode_digits.d.ts

@@ -0,0 +1,3 @@
+/** Replace every Unicode decimal digit with its ASCII digit (`"٥٠"` → `"50"`). */
+export declare function toAsciiDigits(text: string): string;
+//# sourceMappingURL=unicode_digits.d.ts.map

package/dist/utils/text/unicode_digits.js

@@ -0,0 +1,34 @@
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Python's `\\d` (in str patterns) matches any Unicode decimal digit, and
+// `int()` / `float()` accept them: `int("٥٠") == 50`. JavaScript's `\\p{Nd}`
+// matches the same characters, but `Number` / `BigInt` only take ASCII digits.
+// `toAsciiDigits` converts first, so ported code parses what Python parses.
+//
+// Generated from Python 3.14.5 unicodedata (Unicode 16.0.0):
+// the code points whose decimal value is 0; each starts a run of ten digits 0-9.
+const ZERO_CODE_POINTS = [
+    0x30, 0x660, 0x6f0, 0x7c0, 0x966, 0x9e6, 0xa66, 0xae6, 0xb66, 0xbe6, 0xc66, 0xce6, 0xd66, 0xde6,
+    0xe50, 0xed0, 0xf20, 0x1040, 0x1090, 0x17e0, 0x1810, 0x1946, 0x19d0, 0x1a80, 0x1a90, 0x1b50,
+    0x1bb0, 0x1c40, 0x1c50, 0xa620, 0xa8d0, 0xa900, 0xa9d0, 0xa9f0, 0xaa50, 0xabf0, 0xff10, 0x104a0,
+    0x10d30, 0x10d40, 0x11066, 0x110f0, 0x11136, 0x111d0, 0x112f0, 0x11450, 0x114d0, 0x11650, 0x116c0,
+    0x116d0, 0x116da, 0x11730, 0x118e0, 0x11950, 0x11bf0, 0x11c50, 0x11d50, 0x11da0, 0x11f50, 0x16130,
+    0x16a60, 0x16ac0, 0x16b50, 0x16d70, 0x1ccf0, 0x1d7ce, 0x1d7d8, 0x1d7e2, 0x1d7ec, 0x1d7f6, 0x1e140,
+    0x1e2f0, 0x1e4f0, 0x1e5f1, 0x1e950, 0x1fbf0,
+];
+const DIGIT_VALUE = new Map();
+for (const zero of ZERO_CODE_POINTS) {
+    for (let i = 0; i < 10; i++)
+        DIGIT_VALUE.set(zero + i, i);
+}
+/** Replace every Unicode decimal digit with its ASCII digit (`"٥٠"` → `"50"`). */
+export function toAsciiDigits(text) {
+    let out = "";
+    for (const ch of text) {
+        const value = DIGIT_VALUE.get(ch.codePointAt(0));
+        out += value === undefined ? ch : String(value);
+    }
+    return out;
+}
+//# sourceMappingURL=unicode_digits.js.map

package/dist/utils/text/word_timestamp_utils.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Merge punctuation/space-only tokens into the preceding word.
+ *
+ * Some TTS services (e.g. Inworld) emit spaces and punctuation as separate
+ * word-timestamp tokens rather than attaching them to the adjacent word.
+ * This function collapses those tokens so downstream consumers always receive
+ * words with trailing punctuation already attached — identical to the format
+ * produced by ElevenLabs or Cartesia.
+ *
+ * A token is considered punct/space-only when its text contains no alphanumeric
+ * characters after stripping XML/HTML tags. Such tokens are appended to the
+ * preceding word's text and their timestamp is discarded (the preceding word's
+ * timestamp is kept). Leading punct/space tokens with no preceding word are
+ * silently discarded. Every output token is stripped of leading and trailing
+ * whitespace (spaces, tabs, newlines).
+ *
+ * @param wordTimes Raw list of `[word, timestamp]` pairs from the TTS service.
+ * @returns Merged list where every entry contains at least one alphanumeric
+ *   character and has no leading or trailing whitespace.
+ *
+ * @example
+ * mergePunctTokens([["questions", 1.0], [", ", 1.2], ["explain", 1.4]]);
+ * // → [["questions,", 1.0], ["explain", 1.4]]
+ */
+export declare function mergePunctTokens(wordTimes: readonly (readonly [string, number])[]): [string, number][];
+//# sourceMappingURL=word_timestamp_utils.d.ts.map

package/dist/utils/text/word_timestamp_utils.js

@@ -0,0 +1,52 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/text/word_timestamp_utils.py
+/** Utilities for normalizing word-timestamp streams from TTS services. */
+const TAG_RE = /<[^>]+>/g;
+const ALNUM_RE = /[\p{L}\p{N}]/u;
+/**
+ * Merge punctuation/space-only tokens into the preceding word.
+ *
+ * Some TTS services (e.g. Inworld) emit spaces and punctuation as separate
+ * word-timestamp tokens rather than attaching them to the adjacent word.
+ * This function collapses those tokens so downstream consumers always receive
+ * words with trailing punctuation already attached — identical to the format
+ * produced by ElevenLabs or Cartesia.
+ *
+ * A token is considered punct/space-only when its text contains no alphanumeric
+ * characters after stripping XML/HTML tags. Such tokens are appended to the
+ * preceding word's text and their timestamp is discarded (the preceding word's
+ * timestamp is kept). Leading punct/space tokens with no preceding word are
+ * silently discarded. Every output token is stripped of leading and trailing
+ * whitespace (spaces, tabs, newlines).
+ *
+ * @param wordTimes Raw list of `[word, timestamp]` pairs from the TTS service.
+ * @returns Merged list where every entry contains at least one alphanumeric
+ *   character and has no leading or trailing whitespace.
+ *
+ * @example
+ * mergePunctTokens([["questions", 1.0], [", ", 1.2], ["explain", 1.4]]);
+ * // → [["questions,", 1.0], ["explain", 1.4]]
+ */
+export function mergePunctTokens(wordTimes) {
+    const merged = [];
+    for (const [word, ts] of wordTimes) {
+        const stripped = word.replace(TAG_RE, "");
+        const hasAlnum = ALNUM_RE.test(stripped);
+        if (!hasAlnum) {
+            const last = merged[merged.length - 1];
+            if (last) {
+                const [prevWord, prevTs] = last;
+                merged[merged.length - 1] = [prevWord + word, prevTs];
+            }
+            // else: leading punct/space with no preceding word → discard
+        }
+        else {
+            merged.push([word, ts]);
+        }
+    }
+    return merged.map(([word, ts]) => [word.trim(), ts]);
+}
+//# sourceMappingURL=word_timestamp_utils.js.map

package/dist/utils/time.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Time utilities: ISO8601 formatting, nanosecond conversions, and
+ * human-readable time strings.
+ */
+/** The current UTC time as an ISO8601 string with millisecond precision. */
+export declare function timeNowIso8601(): string;
+/** Convert seconds to (integer) nanoseconds. */
+export declare function secondsToNanoseconds(seconds: number): number;
+/** Convert nanoseconds to seconds. */
+export declare function nanosecondsToSeconds(nanoseconds: number): number;
+/** Convert nanoseconds to an "H:MM:SS.microseconds" string. */
+export declare function nanosecondsToStr(nanoseconds: number): string;
+//# sourceMappingURL=time.d.ts.map

package/dist/utils/time.js

@@ -0,0 +1,31 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/time.py
+/**
+ * Time utilities: ISO8601 formatting, nanosecond conversions, and
+ * human-readable time strings.
+ */
+/** The current UTC time as an ISO8601 string with millisecond precision. */
+export function timeNowIso8601() {
+    return new Date().toISOString().replace("Z", "+00:00");
+}
+/** Convert seconds to (integer) nanoseconds. */
+export function secondsToNanoseconds(seconds) {
+    return Math.trunc(seconds * 1_000_000_000);
+}
+/** Convert nanoseconds to seconds. */
+export function nanosecondsToSeconds(nanoseconds) {
+    return nanoseconds / 1_000_000_000;
+}
+/** Convert nanoseconds to an "H:MM:SS.microseconds" string. */
+export function nanosecondsToStr(nanoseconds) {
+    const totalSeconds = nanosecondsToSeconds(nanoseconds);
+    const hours = Math.floor(totalSeconds / 3600);
+    const minutes = Math.floor((totalSeconds % 3600) / 60);
+    const seconds = Math.floor(totalSeconds % 60);
+    const microseconds = Math.trunc((totalSeconds - Math.trunc(totalSeconds)) * 1_000_000);
+    return `${hours}:${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}.${String(microseconds).padStart(6, "0")}`;
+}
+//# sourceMappingURL=time.js.map

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

@@ -0,0 +1,3 @@
+/** OpenTelemetry tracing utilities for Pipecat. */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/tracing/index.js

@@ -0,0 +1,8 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/tracing/__init__.py
+/** OpenTelemetry tracing utilities for Pipecat. */
+export {};
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,198 @@
+/**
+ * Functions for adding attributes to OpenTelemetry spans.
+ *
+ * This module provides specialized functions for adding service-specific
+ * attributes to OpenTelemetry spans, following standard semantic conventions
+ * where applicable and Pipecat-specific conventions for additional context.
+ *
+ * Porting notes:
+ * - Upstream's keyword arguments become an options object after the span.
+ *   Extra keyword arguments (upstream `**kwargs`) are any other keys of that
+ *   object; they are used verbatim as attribute names.
+ * - Settings field names are camelCase in TS (`givenFields()`); they are
+ *   converted back to snake_case for the `settings.*` attribute names so spans
+ *   carry the same attribute names as upstream.
+ */
+import type { ServiceSettings } from "../../services/settings.ts";
+import type { OtelSpan } from "./setup.ts";
+/** Convert a camelCase name back to upstream's snake_case (`voiceId` → `voice_id`). */
+export declare function _camelToSnake(name: string): string;
+/**
+ * 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 declare function _getProviderNameFromServiceName(serviceName: string): string;
+export interface TtsSpanAttributesOptions {
+    /** Name of the TTS service (e.g., "cartesia"). */
+    serviceName: string;
+    /** Model name/identifier. */
+    model: string;
+    /** Voice identifier. */
+    voiceId: string;
+    /** The text being synthesized. */
+    text?: string | null;
+    /** Service configuration settings. */
+    settings?: ServiceSettings | null;
+    /** Number of characters in the text. */
+    characterCount?: number | null;
+    /** Name of the operation (default: "tts"). */
+    operationName?: string;
+    /** Time to first byte in seconds. */
+    ttfb?: number | null;
+    /** Additional attributes to add. */
+    [key: string]: unknown;
+}
+/**
+ * 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 declare function addTtsSpanAttributes(span: OtelSpan, options: TtsSpanAttributesOptions): void;
+export interface SttSpanAttributesOptions {
+    /** Name of the STT service (e.g., "deepgram"). */
+    serviceName: string;
+    /** Model name/identifier. */
+    model: string;
+    /** Name of the operation (default: "stt"). */
+    operationName?: string;
+    /** The transcribed text. */
+    transcript?: string | null;
+    /** Whether this is a final transcript. */
+    isFinal?: boolean | null;
+    /** Detected or configured language. */
+    language?: string | null;
+    /** User ID associated with the audio being transcribed. */
+    userId?: string | null;
+    /** Service configuration settings. */
+    settings?: ServiceSettings | null;
+    /** Whether voice activity detection is enabled. */
+    vadEnabled?: boolean;
+    /** Time to first byte in seconds. */
+    ttfb?: number | null;
+    /** Additional attributes to add. */
+    [key: string]: unknown;
+}
+/**
+ * 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 declare function addSttSpanAttributes(span: OtelSpan, options: SttSpanAttributesOptions): void;
+export interface LlmSpanAttributesOptions {
+    /** Name of the LLM service (e.g., "openai"). */
+    serviceName: string;
+    /** Model name/identifier. */
+    model: string;
+    /** Whether streaming is enabled. */
+    stream?: boolean;
+    /** JSON-serialized messages. */
+    messages?: string | null;
+    /** Aggregated output text from the LLM. */
+    output?: string | null;
+    /** JSON-serialized tools configuration. */
+    tools?: string | null;
+    /** Number of tools available. */
+    toolCount?: number | null;
+    /** Tool selection configuration. */
+    toolChoice?: string | null;
+    /** System instructions. */
+    systemInstructions?: string | null;
+    /** Service parameters. */
+    parameters?: Record<string, unknown> | null;
+    /** Additional parameters. */
+    extraParameters?: Record<string, unknown> | null;
+    /** Time to first byte in seconds. */
+    ttfb?: number | null;
+    /** Additional attributes to add. */
+    [key: string]: unknown;
+}
+/**
+ * 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 declare function addLlmSpanAttributes(span: OtelSpan, options: LlmSpanAttributesOptions): void;
+export interface GeminiLiveSpanAttributesOptions {
+    /** Name of the service. */
+    serviceName: string;
+    /** Model name/identifier. */
+    model: string;
+    /** Name of the operation (setup, model_turn, tool_call, etc.). */
+    operationName: string;
+    /** Voice identifier used for output. */
+    voiceId?: string | null;
+    /** Language code for the session. */
+    language?: string | null;
+    /** Supported modalities (e.g., "AUDIO", "TEXT"). */
+    modalities?: string | null;
+    /** Service configuration settings. */
+    settings?: ServiceSettings | null;
+    /** Available tools/functions list. */
+    tools?: unknown[] | null;
+    /** JSON-serialized tools for detailed inspection. */
+    toolsSerialized?: string | null;
+    /** Transcription text. */
+    transcript?: string | null;
+    /** Whether transcript is input (true) or output (false). */
+    isInput?: boolean | null;
+    /** Text output from model. */
+    textOutput?: string | null;
+    /** Size of audio data in bytes. */
+    audioDataSize?: number | null;
+    /** Additional attributes to add. */
+    [key: string]: unknown;
+}
+/**
+ * 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 declare function addGeminiLiveSpanAttributes(span: OtelSpan, options: GeminiLiveSpanAttributesOptions): void;
+export interface OpenaiRealtimeSpanAttributesOptions {
+    /** Name of the service. */
+    serviceName: string;
+    /** Model name/identifier. */
+    model: string;
+    /** Name of the operation (setup, transcription, response, etc.). */
+    operationName: string;
+    /** Session configuration properties. */
+    sessionProperties?: Record<string, unknown> | null;
+    /** Transcription text. */
+    transcript?: string | null;
+    /** Whether transcript is input (true) or output (false). */
+    isInput?: boolean | null;
+    /** JSON-serialized context messages. */
+    contextMessages?: string | null;
+    /** Function calls being made. */
+    functionCalls?: unknown[] | null;
+    /** Available tools/functions list. */
+    tools?: unknown[] | null;
+    /** JSON-serialized tools for detailed inspection. */
+    toolsSerialized?: string | null;
+    /** Size of audio data in bytes. */
+    audioDataSize?: number | null;
+    /** Additional attributes to add. */
+    [key: string]: unknown;
+}
+/**
+ * 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 declare function addOpenaiRealtimeSpanAttributes(span: OtelSpan, options: OpenaiRealtimeSpanAttributesOptions): void;
+//# sourceMappingURL=service_attributes.d.ts.map