dvgateway-sdk 1.0.0

package/dist/observability/logger.js

@@ -0,0 +1,70 @@
+/**
+ * Structured JSON logger with PII redaction support.
+ * Implements the Logger interface — swap to any log library (pino, winston) as needed.
+ */
+const PII_PATTERNS = [
+    // Korean mobile numbers: 010-1234-5678 or 01012345678
+    { pattern: /\b(010|011|016|017|018|019)[-.]?\d{3,4}[-.]?\d{4}\b/g, replacement: '***-****' },
+    // General phone numbers: +82-10-1234-5678
+    { pattern: /\+?\d{1,3}[-.\s]?\(?\d{1,4}\)?[-.\s]?\d{1,4}[-.\s]?\d{1,9}/g, replacement: '[PHONE]' },
+];
+function redactPii(value) {
+    if (typeof value === 'string') {
+        let result = value;
+        for (const { pattern, replacement } of PII_PATTERNS) {
+            result = result.replace(pattern, replacement);
+        }
+        return result;
+    }
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        const redacted = {};
+        for (const [k, v] of Object.entries(value)) {
+            // Never log these fields at any level
+            if (['caller', 'callee', 'transcript', 'text', 'password', 'secret', 'token'].includes(k)) {
+                redacted[k] = '[REDACTED]';
+            }
+            else {
+                redacted[k] = redactPii(v);
+            }
+        }
+        return redacted;
+    }
+    return value;
+}
+const LEVEL_VALUES = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+export function createLogger(opts = {}) {
+    const minLevel = LEVEL_VALUES[opts.level ?? 'info'];
+    const shouldRedact = opts.redactPii !== false;
+    function write(level, ctx, msg) {
+        if (LEVEL_VALUES[level] < minLevel)
+            return;
+        const entry = {
+            level,
+            time: new Date().toISOString(),
+            msg,
+            ...opts.baseContext,
+            ...(shouldRedact ? redactPii(ctx) : ctx),
+        };
+        const line = JSON.stringify(entry);
+        if (level === 'error' || level === 'warn') {
+            process.stderr.write(line + '\n');
+        }
+        else {
+            process.stdout.write(line + '\n');
+        }
+    }
+    return {
+        debug: (ctx, msg) => write('debug', ctx, msg),
+        info: (ctx, msg) => write('info', ctx, msg),
+        warn: (ctx, msg) => write('warn', ctx, msg),
+        error: (ctx, msg) => write('error', ctx, msg),
+    };
+}
+/** Default singleton logger */
+export const defaultLogger = createLogger({ level: 'info', redactPii: true });
+//# sourceMappingURL=logger.js.map

package/dist/observability/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/observability/logger.ts"],"names":[],"mappings":"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"}

package/dist/observability/metrics.d.ts

@@ -0,0 +1,53 @@
+/**
+ * SDK Metrics
+ *
+ * Lightweight pipeline latency and throughput tracking.
+ * Emits OpenTelemetry-compatible spans when an OTel tracer is provided,
+ * otherwise records to in-memory histograms for Prometheus scraping.
+ *
+ * GenAI Semantic Conventions (OTel v1.37+):
+ *   gen_ai.operation.name, gen_ai.system, gen_ai.request.model,
+ *   gen_ai.usage.input_tokens, gen_ai.usage.output_tokens
+ */
+import type { Logger } from '../types/index.js';
+export declare class Histogram {
+    private readonly buckets;
+    private readonly counts;
+    private sum;
+    private count;
+    constructor(buckets?: number[]);
+    observe(value: number): void;
+    /** Returns p50, p95, p99 in ms */
+    percentiles(): {
+        p50: number;
+        p95: number;
+        p99: number;
+        mean: number;
+    };
+    private percentile;
+    toPrometheus(name: string, labels?: Record<string, string>): string;
+}
+export declare class Counter {
+    private value;
+    increment(by?: number): void;
+    get(): number;
+    reset(): void;
+}
+export declare class PipelineMetrics {
+    readonly sttLatency: Histogram;
+    readonly llmTtft: Histogram;
+    readonly ttsLatency: Histogram;
+    readonly e2eLatency: Histogram;
+    readonly transcriptsTotal: Counter;
+    readonly ttsInjectionsTotal: Counter;
+    readonly errorsTotal: Counter;
+    readonly activeCalls: Counter;
+    private readonly logger;
+    constructor(logger: Logger);
+    /** Start a latency measurement; returns a function to stop it */
+    startTimer(): () => number;
+    logSummary(): void;
+    /** Prometheus text format for scraping */
+    toPrometheus(): string;
+}
+//# sourceMappingURL=metrics.d.ts.map

package/dist/observability/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../src/observability/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAIhD,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAW;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,GAAG,CAAK;IAChB,OAAO,CAAC,KAAK,CAAK;gBAEN,OAAO,GAAE,MAAM,EAA8C;IAKzE,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAkB5B,kCAAkC;IAClC,WAAW,IAAI;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;IAUtE,OAAO,CAAC,UAAU;IAUlB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GAAG,MAAM;CAwBxE;AAED,qBAAa,OAAO;IAClB,OAAO,CAAC,KAAK,CAAK;IAElB,SAAS,CAAC,EAAE,SAAI,GAAG,IAAI;IAIvB,GAAG,IAAI,MAAM;IAIb,KAAK,IAAI,IAAI;CAGd;AAID,qBAAa,eAAe;IAC1B,QAAQ,CAAC,UAAU,YAAkD;IACrE,QAAQ,CAAC,OAAO,YAAuD;IACvE,QAAQ,CAAC,UAAU,YAAiD;IACpE,QAAQ,CAAC,UAAU,YAAwD;IAE3E,QAAQ,CAAC,gBAAgB,UAAmB;IAC5C,QAAQ,CAAC,kBAAkB,UAAiB;IAC5C,QAAQ,CAAC,WAAW,UAAwB;IAC5C,QAAQ,CAAC,WAAW,UAAwB;IAE5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,MAAM,EAAE,MAAM;IAI1B,iEAAiE;IACjE,UAAU,IAAI,MAAM,MAAM;IAK1B,UAAU,IAAI,IAAI;IAiBlB,0CAA0C;IAC1C,YAAY,IAAI,MAAM;CAYvB"}

package/dist/observability/metrics.js

@@ -0,0 +1,143 @@
+/**
+ * SDK Metrics
+ *
+ * Lightweight pipeline latency and throughput tracking.
+ * Emits OpenTelemetry-compatible spans when an OTel tracer is provided,
+ * otherwise records to in-memory histograms for Prometheus scraping.
+ *
+ * GenAI Semantic Conventions (OTel v1.37+):
+ *   gen_ai.operation.name, gen_ai.system, gen_ai.request.model,
+ *   gen_ai.usage.input_tokens, gen_ai.usage.output_tokens
+ */
+// ─── Histogram (fixed buckets, zero dependencies) ─────────────────────────
+export class Histogram {
+    buckets;
+    counts;
+    sum = 0;
+    count = 0;
+    constructor(buckets = [10, 50, 100, 200, 500, 1000, 2000, 5000]) {
+        this.buckets = [...buckets].sort((a, b) => a - b);
+        this.counts = new Array(buckets.length + 1).fill(0);
+    }
+    observe(value) {
+        this.sum += value;
+        this.count++;
+        let placed = false;
+        for (let i = 0; i < this.buckets.length; i++) {
+            if (value <= this.buckets[i]) {
+                this.counts[i] = (this.counts[i] ?? 0) + 1;
+                placed = true;
+                break;
+            }
+        }
+        if (!placed) {
+            const last = this.counts.length - 1;
+            this.counts[last] = (this.counts[last] ?? 0) + 1;
+        }
+    }
+    /** Returns p50, p95, p99 in ms */
+    percentiles() {
+        if (this.count === 0)
+            return { p50: 0, p95: 0, p99: 0, mean: 0 };
+        return {
+            p50: this.percentile(0.50),
+            p95: this.percentile(0.95),
+            p99: this.percentile(0.99),
+            mean: this.sum / this.count,
+        };
+    }
+    percentile(p) {
+        const target = Math.ceil(p * this.count);
+        let cumulative = 0;
+        for (let i = 0; i < this.buckets.length; i++) {
+            cumulative += this.counts[i] ?? 0;
+            if (cumulative >= target)
+                return this.buckets[i] ?? 0;
+        }
+        return this.buckets[this.buckets.length - 1] ?? 0;
+    }
+    toPrometheus(name, labels = {}) {
+        const labelStr = Object.entries(labels)
+            .map(([k, v]) => `${k}="${v}"`)
+            .join(',');
+        const l = labelStr ? `{${labelStr}}` : '';
+        const lines = [];
+        let cumulative = 0;
+        for (let i = 0; i < this.buckets.length; i++) {
+            cumulative += this.counts[i] ?? 0;
+            const bucketLabel = labelStr
+                ? `{${labelStr},le="${this.buckets[i]}"}`
+                : `{le="${this.buckets[i]}"}`;
+            lines.push(`${name}_bucket${bucketLabel} ${cumulative}`);
+        }
+        cumulative += this.counts[this.counts.length - 1] ?? 0;
+        const infLabel = labelStr
+            ? `{${labelStr},le="+Inf"}`
+            : `{le="+Inf"}`;
+        lines.push(`${name}_bucket${infLabel} ${cumulative}`);
+        lines.push(`${name}_sum${l} ${this.sum}`);
+        lines.push(`${name}_count${l} ${this.count}`);
+        return lines.join('\n');
+    }
+}
+export class Counter {
+    value = 0;
+    increment(by = 1) {
+        this.value += by;
+    }
+    get() {
+        return this.value;
+    }
+    reset() {
+        this.value = 0;
+    }
+}
+// ─── Pipeline Metrics Registry ────────────────────────────────────────────
+export class PipelineMetrics {
+    sttLatency = new Histogram([50, 100, 200, 500, 1000, 2000]);
+    llmTtft = new Histogram([20, 50, 80, 120, 200, 500, 1000]);
+    ttsLatency = new Histogram([50, 100, 150, 300, 500, 1000]);
+    e2eLatency = new Histogram([100, 200, 300, 500, 700, 1000, 2000]);
+    transcriptsTotal = new Counter();
+    ttsInjectionsTotal = new Counter();
+    errorsTotal = new Counter();
+    activeCalls = new Counter();
+    logger;
+    constructor(logger) {
+        this.logger = logger;
+    }
+    /** Start a latency measurement; returns a function to stop it */
+    startTimer() {
+        const start = Date.now();
+        return () => Date.now() - start;
+    }
+    logSummary() {
+        const stt = this.sttLatency.percentiles();
+        const llm = this.llmTtft.percentiles();
+        const tts = this.ttsLatency.percentiles();
+        const e2e = this.e2eLatency.percentiles();
+        this.logger.info({
+            stt_p50_ms: stt.p50, stt_p95_ms: stt.p95,
+            llm_ttft_p50_ms: llm.p50, llm_ttft_p95_ms: llm.p95,
+            tts_p50_ms: tts.p50, tts_p95_ms: tts.p95,
+            e2e_p50_ms: e2e.p50, e2e_p95_ms: e2e.p95,
+            transcripts: this.transcriptsTotal.get(),
+            tts_injections: this.ttsInjectionsTotal.get(),
+            errors: this.errorsTotal.get(),
+        }, 'DVGateway SDK metrics summary');
+    }
+    /** Prometheus text format for scraping */
+    toPrometheus() {
+        return [
+            this.sttLatency.toPrometheus('dvgw_stt_latency_ms'),
+            this.llmTtft.toPrometheus('dvgw_llm_ttft_ms'),
+            this.ttsLatency.toPrometheus('dvgw_tts_latency_ms'),
+            this.e2eLatency.toPrometheus('dvgw_e2e_latency_ms'),
+            `dvgw_transcripts_total ${this.transcriptsTotal.get()}`,
+            `dvgw_tts_injections_total ${this.ttsInjectionsTotal.get()}`,
+            `dvgw_errors_total ${this.errorsTotal.get()}`,
+            `dvgw_active_calls ${this.activeCalls.get()}`,
+        ].join('\n');
+    }
+}
+//# sourceMappingURL=metrics.js.map

package/dist/observability/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../src/observability/metrics.ts"],"names":[],"mappings":"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"}

package/dist/observability/metrics.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=metrics.test.d.ts.map

package/dist/observability/metrics.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.test.d.ts","sourceRoot":"","sources":["../../src/observability/metrics.test.ts"],"names":[],"mappings":""}

package/dist/observability/metrics.test.js

@@ -0,0 +1,122 @@
+import { Histogram, Counter, PipelineMetrics } from './metrics.js';
+const mockLogger = {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+};
+describe('Counter', () => {
+    it('should start at 0', () => {
+        const c = new Counter();
+        expect(c.get()).toBe(0);
+    });
+    it('should increment by 1 by default', () => {
+        const c = new Counter();
+        c.increment();
+        c.increment();
+        expect(c.get()).toBe(2);
+    });
+    it('should increment by custom amount', () => {
+        const c = new Counter();
+        c.increment(5);
+        c.increment(3);
+        expect(c.get()).toBe(8);
+    });
+    it('should reset to 0', () => {
+        const c = new Counter();
+        c.increment(10);
+        c.reset();
+        expect(c.get()).toBe(0);
+    });
+});
+describe('Histogram', () => {
+    it('should return zeros when empty', () => {
+        const h = new Histogram();
+        const p = h.percentiles();
+        expect(p.p50).toBe(0);
+        expect(p.p95).toBe(0);
+        expect(p.p99).toBe(0);
+        expect(p.mean).toBe(0);
+    });
+    it('should track a single observation', () => {
+        const h = new Histogram([10, 50, 100]);
+        h.observe(25);
+        const p = h.percentiles();
+        expect(p.p50).toBe(50); // falls in ≤50 bucket
+        expect(p.mean).toBe(25);
+    });
+    it('should compute percentiles over multiple observations', () => {
+        const h = new Histogram([100, 200, 500, 1000]);
+        // 50 observations at 50ms, 40 at 300ms, 10 at 800ms
+        for (let i = 0; i < 50; i++)
+            h.observe(50);
+        for (let i = 0; i < 40; i++)
+            h.observe(300);
+        for (let i = 0; i < 10; i++)
+            h.observe(800);
+        const p = h.percentiles();
+        expect(p.p50).toBe(100); // 50th of 100: target=50, cumulative at bucket ≤100 = 50 → matches
+        expect(p.p95).toBe(1000); // 95th of 100: target=95, cumulative at ≤500 = 90 → next bucket ≤1000
+        expect(p.p99).toBe(1000); // 99th of 100: target=99, in bucket ≤1000
+    });
+    it('should handle values above the largest bucket', () => {
+        const h = new Histogram([10, 100]);
+        h.observe(9999);
+        const p = h.percentiles();
+        expect(p.p50).toBe(100); // falls into the overflow bucket, percentile returns last bucket
+        expect(p.mean).toBe(9999);
+    });
+    it('should produce Prometheus text output', () => {
+        const h = new Histogram([10, 100]);
+        h.observe(5);
+        h.observe(50);
+        const text = h.toPrometheus('test_latency');
+        expect(text).toContain('test_latency_bucket{le="10"} 1');
+        expect(text).toContain('test_latency_bucket{le="100"} 2');
+        expect(text).toContain('test_latency_bucket{le="+Inf"} 2');
+        expect(text).toContain('test_latency_sum 55');
+        expect(text).toContain('test_latency_count 2');
+    });
+    it('should produce Prometheus text with labels', () => {
+        const h = new Histogram([100]);
+        h.observe(50);
+        const text = h.toPrometheus('test_latency', { provider: 'deepgram' });
+        expect(text).toContain('provider="deepgram"');
+    });
+});
+describe('PipelineMetrics', () => {
+    it('should have all histogram and counter instances', () => {
+        const m = new PipelineMetrics(mockLogger);
+        expect(m.sttLatency).toBeInstanceOf(Histogram);
+        expect(m.llmTtft).toBeInstanceOf(Histogram);
+        expect(m.ttsLatency).toBeInstanceOf(Histogram);
+        expect(m.e2eLatency).toBeInstanceOf(Histogram);
+        expect(m.transcriptsTotal).toBeInstanceOf(Counter);
+        expect(m.ttsInjectionsTotal).toBeInstanceOf(Counter);
+        expect(m.errorsTotal).toBeInstanceOf(Counter);
+        expect(m.activeCalls).toBeInstanceOf(Counter);
+    });
+    it('should measure timer duration', async () => {
+        const m = new PipelineMetrics(mockLogger);
+        const stop = m.startTimer();
+        await new Promise((r) => setTimeout(r, 50));
+        const elapsed = stop();
+        expect(elapsed).toBeGreaterThanOrEqual(40);
+        expect(elapsed).toBeLessThan(200);
+    });
+    it('should produce Prometheus output', () => {
+        const m = new PipelineMetrics(mockLogger);
+        m.sttLatency.observe(100);
+        m.transcriptsTotal.increment();
+        const output = m.toPrometheus();
+        expect(output).toContain('dvgw_stt_latency_ms');
+        expect(output).toContain('dvgw_transcripts_total 1');
+    });
+    it('should log summary without errors', () => {
+        const m = new PipelineMetrics(mockLogger);
+        m.sttLatency.observe(100);
+        m.logSummary();
+        expect(mockLogger.info).toHaveBeenCalled();
+    });
+});
+//# sourceMappingURL=metrics.test.js.map

package/dist/observability/metrics.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.test.js","sourceRoot":"","sources":["../../src/observability/metrics.test.ts"],"names":[],"mappings":"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"}

package/dist/pipeline/builder.d.ts

@@ -0,0 +1,111 @@
+/**
+ * VoiceAI Pipeline Builder
+ *
+ * High-level fluent API for wiring STT → LLM → TTS pipelines.
+ * Handles the entire lifecycle: call events, audio streaming, AI processing,
+ * and TTS injection — all with a single .start() call.
+ *
+ * Architecture (2026 cascaded pipeline pattern):
+ *
+ *   Inbound call
+ *       ↓
+ *   AudioStream (WebSocket, slin16 → Float32)
+ *       ↓
+ *   [VAD filter] (optional, reduces STT API cost)
+ *       ↓
+ *   SttAdapter.startStream() → onTranscript(isFinal=true)
+ *       ↓
+ *   LlmAdapter.chat() → streaming tokens
+ *       ↓ (first token triggers TTS immediately)
+ *   TtsAdapter.synthesize() → PCM chunks
+ *       ↓
+ *   TtsInjector.injectStreaming()
+ *       ↓
+ *   Call audio (Asterisk)
+ *
+ * Latency budget target: <500ms end-to-end (STT ~200ms, LLM TTFT ~80ms, TTS TTFA ~150ms)
+ */
+import type { SttAdapter, TtsAdapter, LlmAdapter, CallSession, TranscriptResult, StreamDir, Logger } from '../types/index.js';
+import type { CallEventStream } from '../streams/call-events.js';
+import type { TtsInjector } from '../streams/tts-stream.js';
+import type { WsPool } from '../transport/ws-pool.js';
+declare class WithFallback<T extends SttAdapter | TtsAdapter | LlmAdapter> {
+    readonly primary: T;
+    readonly fallback?: T | undefined;
+    constructor(primary: T, fallback?: T | undefined);
+}
+export interface FallbackAdapter<T> {
+    fallback(adapter: T): this;
+}
+declare class SttStage implements FallbackAdapter<SttAdapter> {
+    private readonly _adapter;
+    private _fallback;
+    private readonly _builder;
+    constructor(_adapter: SttAdapter, _fallback: SttAdapter | undefined, _builder: PipelineBuilder);
+    fallback(adapter: SttAdapter): this;
+    toWrapped(): WithFallback<SttAdapter>;
+    llm(adapter: LlmAdapter): LlmStage;
+    forConference(): ConferencePipelineBuilder;
+}
+declare class LlmStage implements FallbackAdapter<LlmAdapter> {
+    private readonly _adapter;
+    private _fallback;
+    private readonly _stt;
+    private readonly _builder;
+    constructor(_adapter: LlmAdapter, _fallback: LlmAdapter | undefined, _stt: WithFallback<SttAdapter>, _builder: PipelineBuilder);
+    fallback(adapter: LlmAdapter): this;
+    tts(adapter: TtsAdapter): TtsStage;
+    toWrapped(): WithFallback<LlmAdapter>;
+}
+declare class TtsStage implements FallbackAdapter<TtsAdapter> {
+    private readonly _adapter;
+    private _fallback;
+    private readonly _stt;
+    private readonly _llm;
+    private readonly _builder;
+    constructor(_adapter: TtsAdapter, _fallback: TtsAdapter | undefined, _stt: WithFallback<SttAdapter>, _llm: WithFallback<LlmAdapter>, _builder: PipelineBuilder);
+    fallback(adapter: TtsAdapter): this;
+    audioFilter(opts: {
+        dir: StreamDir;
+    }): this;
+    onNewCall(handler: (session: CallSession) => void | Promise<void>): this;
+    onCallEnded(handler: (linkedId: string, durationSec: number) => void | Promise<void>): this;
+    onTranscript(handler: (result: TranscriptResult, session: CallSession) => void | Promise<void>): this;
+    onError(handler: (err: Error, linkedId?: string) => void | Promise<void>): this;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export declare class ConferencePipelineBuilder {
+    private readonly _builder;
+    private readonly _stt;
+    private _onTranscript?;
+    private _onError?;
+    constructor(_builder: PipelineBuilder, _stt: WithFallback<SttAdapter>);
+    onTranscript(handler: (result: TranscriptResult, session: CallSession) => void | Promise<void>): this;
+    onError(handler: (err: Error, linkedId?: string) => void | Promise<void>): this;
+    start(): Promise<void>;
+}
+export declare class PipelineBuilder {
+    private readonly wsPool;
+    private readonly callEvents;
+    private readonly ttsInjector;
+    private readonly logger;
+    private _dir;
+    private _onNewCall?;
+    private _onCallEnded?;
+    private _onTranscript?;
+    private _onError?;
+    private _activeCalls;
+    private _running;
+    constructor(wsPool: WsPool, callEvents: CallEventStream, ttsInjector: TtsInjector, logger: Logger);
+    /** Set the STT adapter (first step in fluent chain) */
+    stt(adapter: SttAdapter): SttStage;
+    private setLlm;
+    private setTts;
+    private startPipeline;
+    private handleCall;
+    private startConferencePipeline;
+    private stopPipeline;
+}
+export {};
+//# sourceMappingURL=builder.d.ts.map

package/dist/pipeline/builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.d.ts","sourceRoot":"","sources":["../../src/pipeline/builder.ts"],"names":[],"mappings":"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"}