@pipedog/core 0.0.0 → 0.2.0

package/dist/utils/tracing/turn_trace_observer.js

@@ -0,0 +1,233 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/tracing/turn_trace_observer.py
+/**
+ * Turn trace observer for OpenTelemetry tracing in Pipecat.
+ *
+ * This module provides an observer that creates trace spans for each
+ * conversation turn, integrating with the turn tracking system to provide
+ * hierarchical tracing of conversation flows.
+ *
+ * Porting notes: upstream gets the tracer in `__init__`. Core imports
+ * OpenTelemetry asynchronously, so an observer built before that import
+ * finished gets its tracer on first use instead (`_getTracer()`).
+ */
+import { StartFrame } from "../../frames/frames.js";
+import { BaseObserver, } from "../../observers/base_observer.js";
+import { logger } from "../logger.js";
+import { getOpenTelemetry, isTracingAvailable, } from "./setup.js";
+import { TracingContext } from "./tracing_context.js";
+/**
+ * Observer that creates trace spans for each conversation turn.
+ *
+ * This observer uses TurnTrackingObserver to track turns and creates
+ * OpenTelemetry spans for each turn. Service spans (STT, LLM, TTS)
+ * become children of the turn spans.
+ *
+ * If conversation tracing is enabled, turns become children of a
+ * conversation span that encapsulates the entire session.
+ */
+export class TurnTraceObserver extends BaseObserver {
+    _turnTracker;
+    _latencyTracker;
+    _tracingContext;
+    _currentSpan = null;
+    _currentTurnNumber = 0;
+    _traceContextMap = new Map();
+    _tracer;
+    // Conversation tracking properties
+    _conversationSpan = null;
+    _conversationId;
+    _additionalSpanAttributes;
+    /** Initialize the turn trace observer. */
+    constructor(options) {
+        super(options);
+        this._turnTracker = options.turnTracker;
+        this._latencyTracker = options.latencyTracker;
+        this._tracingContext = options.tracingContext || new TracingContext();
+        this._tracer = getOpenTelemetry()?.api.trace.getTracer("pipecat.turn") ?? null;
+        this._conversationId = options.conversationId ?? null;
+        this._additionalSpanAttributes = options.additionalSpanAttributes || {};
+        this._turnTracker.eventHandler("on_turn_started", async (_tracker, turnNumber) => {
+            await this._handleTurnStarted(turnNumber);
+        });
+        this._turnTracker.eventHandler("on_turn_ended", async (_tracker, turnNumber, duration, wasInterrupted) => {
+            await this._handleTurnEnded(turnNumber, duration, wasInterrupted);
+        });
+        this._latencyTracker.eventHandler("on_latency_measured", async (_tracker, latencySeconds) => {
+            await this._handleLatencyMeasured(latencySeconds);
+        });
+    }
+    /**
+     * The turn tracer, resolved on first use if OpenTelemetry was not available
+     * yet when the observer was built (core imports it asynchronously).
+     */
+    _getTracer() {
+        this._tracer ??= getOpenTelemetry()?.api.trace.getTracer("pipecat.turn") ?? null;
+        return this._tracer;
+    }
+    /**
+     * Handle latency measurement events.
+     *
+     * Called when the latency tracker measures user-to-bot latency.
+     * Adds the latency as an attribute to the current turn span.
+     *
+     * @param latencySeconds The measured latency in seconds.
+     */
+    async _handleLatencyMeasured(latencySeconds) {
+        if (this._currentSpan && isTracingAvailable()) {
+            this._currentSpan.setAttribute("turn.user_bot_latency_seconds", latencySeconds);
+            logger.debug(`Turn ${this._currentTurnNumber} user-bot latency: ${latencySeconds.toFixed(3)}s`);
+        }
+    }
+    /**
+     * Process a frame without modifying it.
+     *
+     * Handles StartFrame to begin conversation tracing early, ensuring
+     * that any spans created before Turn 1 (e.g., from flow initialization)
+     * are properly attached to the conversation trace.
+     *
+     * @param data The frame push event data.
+     */
+    async onPushFrame(data) {
+        if (data.frame instanceof StartFrame && !this._conversationSpan) {
+            this.startConversationTracing(this._conversationId);
+        }
+    }
+    /**
+     * Start a new conversation span.
+     *
+     * @param conversationId Optional custom ID for the conversation. If null, a UUID will be generated.
+     */
+    startConversationTracing(conversationId = null) {
+        const tracer = this._getTracer();
+        if (!isTracingAvailable() || !tracer) {
+            return;
+        }
+        // Generate a conversation ID if not provided
+        if (conversationId === null) {
+            conversationId = TracingContext.generateConversationId();
+            logger.debug(`Generated new conversation ID: ${conversationId}`);
+        }
+        this._conversationId = conversationId;
+        // Create a new span for this conversation
+        const conversationSpan = tracer.startSpan("conversation");
+        this._conversationSpan = conversationSpan;
+        // Set span attributes
+        conversationSpan.setAttribute("conversation.id", conversationId);
+        conversationSpan.setAttribute("conversation.type", "voice");
+        // Set custom otel attributes if provided
+        for (const [k, v] of Object.entries(this._additionalSpanAttributes || {})) {
+            conversationSpan.setAttribute(k, v);
+        }
+        // Update the tracing context
+        this._tracingContext.setConversationContext(conversationSpan.spanContext(), conversationId);
+        logger.debug(`Started tracing for Conversation ${conversationId}`);
+    }
+    /** End the current conversation span and ensure the last turn is closed. */
+    endConversationTracing() {
+        if (!isTracingAvailable()) {
+            return;
+        }
+        // First, ensure any active turn is closed properly
+        if (this._currentSpan) {
+            // If we have an active turn span, end it with a standard duration
+            logger.debug(`Ending Turn ${this._currentTurnNumber} due to conversation end`);
+            this._currentSpan.setAttribute("turn.was_interrupted", true);
+            this._currentSpan.setAttribute("turn.ended_by_conversation_end", true);
+            this._currentSpan.end();
+            this._currentSpan = null;
+            // Clear the turn context
+            this._tracingContext.setTurnContext(null);
+        }
+        // Now end the conversation span if it exists
+        if (this._conversationSpan) {
+            // End the span
+            this._conversationSpan.end();
+            this._conversationSpan = null;
+            // Clear the conversation context
+            this._tracingContext.setConversationContext(null);
+            logger.debug(`Ended tracing for Conversation ${this._conversationId}`);
+            this._conversationId = null;
+        }
+    }
+    /** Handle a turn start event by creating a new span. */
+    async _handleTurnStarted(turnNumber) {
+        const tracer = this._getTracer();
+        if (!isTracingAvailable() || !tracer) {
+            return;
+        }
+        if (turnNumber === 1 && !this._conversationSpan) {
+            this.startConversationTracing(this._conversationId);
+        }
+        // Get the parent context - conversation if available, otherwise use root context
+        let parentContext = null;
+        if (this._conversationSpan) {
+            parentContext = this._tracingContext.getConversationContext();
+        }
+        // Create a new span for this turn
+        const currentSpan = tracer.startSpan("turn", undefined, parentContext ?? undefined);
+        this._currentSpan = currentSpan;
+        this._currentTurnNumber = turnNumber;
+        // Set span attributes
+        currentSpan.setAttribute("turn.number", turnNumber);
+        currentSpan.setAttribute("turn.type", "conversation");
+        // Add conversation ID attribute if available
+        if (this._conversationId) {
+            currentSpan.setAttribute("conversation.id", this._conversationId);
+        }
+        // Store the span context so services can become children of this span
+        this._traceContextMap.set(turnNumber, currentSpan.spanContext());
+        // Update the tracing context so services can access this span
+        this._tracingContext.setTurnContext(currentSpan.spanContext());
+        logger.debug(`Started tracing for Turn ${turnNumber}`);
+    }
+    /** Handle a turn end event by ending the current span. */
+    async _handleTurnEnded(turnNumber, duration, wasInterrupted) {
+        if (!isTracingAvailable() || !this._currentSpan) {
+            return;
+        }
+        // Only end the span if it matches the current turn
+        if (turnNumber === this._currentTurnNumber) {
+            // Set additional attributes
+            this._currentSpan.setAttribute("turn.duration_seconds", duration);
+            this._currentSpan.setAttribute("turn.was_interrupted", wasInterrupted);
+            // End the span
+            this._currentSpan.end();
+            this._currentSpan = null;
+            // Clear the turn context
+            this._tracingContext.setTurnContext(null);
+            logger.debug(`Ended tracing for Turn ${turnNumber}`);
+        }
+    }
+    /**
+     * Get the span context for the current turn.
+     *
+     * This can be used by services to create child spans.
+     *
+     * @returns The current turn's span context or null if not available.
+     */
+    getCurrentTurnContext() {
+        if (!isTracingAvailable() || !this._currentSpan) {
+            return null;
+        }
+        return this._currentSpan.spanContext();
+    }
+    /**
+     * Get the span context for a specific turn.
+     *
+     * This can be used by services to create child spans.
+     *
+     * @param turnNumber The turn number to get context for.
+     * @returns The specified turn's span context or null if not available.
+     */
+    getTurnContext(turnNumber) {
+        if (!isTracingAvailable()) {
+            return null;
+        }
+        return this._traceContextMap.get(turnNumber) ?? null;
+    }
+}
+//# sourceMappingURL=turn_trace_observer.js.map

package/dist/utils/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Types shared across Pipecat, independent of any provider SDK.
+ *
+ * The `NOT_GIVEN` sentinel lives here so that settings, contexts and anything
+ * else needing "this value was not provided" share one meaning. Provider SDKs
+ * ship their own equivalents; those belong to the SDK and are translated at the
+ * adapter boundary rather than used inside Pipecat.
+ */
+/**
+ * Sentinel type meaning "this value was not provided".
+ *
+ * Distinct from `null`, which is a meaningful value in most of the places
+ * this is used (typically "this service doesn't support this field").
+ * `NOT_GIVEN` is the singleton instance; test for it with `isGiven()`
+ * rather than comparing directly.
+ *
+ * DIVERGENCE: upstream makes the sentinel falsy (`__bool__` returns False) so
+ * `value or default` treats a missing value as absent. JavaScript objects are
+ * always truthy, so use `isGiven(value) ? value : fallback` instead.
+ */
+export declare class NotGiven {
+    #private;
+    /** Return the singleton instance, creating it on first use. */
+    constructor();
+    /** Return the sentinel's name. */
+    toString(): string;
+    toJSON(): string;
+}
+/** Singleton sentinel meaning "this value was not provided". */
+export declare const NOT_GIVEN: NotGiven;
+/**
+ * Check whether a value was explicitly provided.
+ *
+ * Also acts as a type guard: inside a true branch, the value is narrowed to
+ * exclude `NotGiven` (e.g. `string | null | NotGiven` becomes `string | null`).
+ *
+ * @example
+ * if (isGiven(delta.voice)) {
+ *   // caller wants to change the voice
+ * }
+ *
+ * @param value The value to check.
+ * @returns `true` if `value` is anything other than `NOT_GIVEN`.
+ */
+export declare function isGiven<T>(value: T | NotGiven): value is T;
+/**
+ * Extract a value that must have been provided.
+ *
+ * Intended for reads where `NOT_GIVEN` should never appear, such as a
+ * store-mode settings object (see `services/settings`). Narrows away
+ * `NotGiven` at the type level and throws at runtime if that invariant is
+ * violated.
+ *
+ * @example
+ * const resolvedModel = assertGiven(this._settings.model); // narrowed string | null
+ *
+ * @param value The value to extract.
+ * @returns The value, narrowed to exclude `NotGiven`.
+ * @throws Error If `value` is `NOT_GIVEN` (upstream: RuntimeError).
+ */
+export declare function assertGiven<T>(value: T | NotGiven): T;
+/**
+ * Extract a value that must have been provided and must not be empty.
+ *
+ * Like `assertGiven()`, but also rejects `null` (and `undefined`) and the
+ * empty string, which is what an unset or blank environment variable
+ * produces. Use it for settings a service cannot work without, such as a
+ * local model or voice that no provider will validate on its behalf.
+ *
+ * @example
+ * const voice = requireGiven(this._settings.voice, "Piper TTS voice"); // narrowed string
+ *
+ * @param value The value to extract.
+ * @param what How to name the value in the error, e.g. `"Piper TTS voice"`.
+ * @returns The value, narrowed to exclude `NotGiven` and `null`.
+ * @throws Error If `value` is `NOT_GIVEN` (upstream: RuntimeError).
+ * @throws Error If `value` is `null` or an empty string (upstream: ValueError).
+ */
+export declare function requireGiven<T>(value: T | null | undefined | NotGiven, what: string): T;
+//# sourceMappingURL=types.d.ts.map

package/dist/utils/types.js

@@ -0,0 +1,108 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/types.py
+/**
+ * Types shared across Pipecat, independent of any provider SDK.
+ *
+ * The `NOT_GIVEN` sentinel lives here so that settings, contexts and anything
+ * else needing "this value was not provided" share one meaning. Provider SDKs
+ * ship their own equivalents; those belong to the SDK and are translated at the
+ * adapter boundary rather than used inside Pipecat.
+ */
+/**
+ * Sentinel type meaning "this value was not provided".
+ *
+ * Distinct from `null`, which is a meaningful value in most of the places
+ * this is used (typically "this service doesn't support this field").
+ * `NOT_GIVEN` is the singleton instance; test for it with `isGiven()`
+ * rather than comparing directly.
+ *
+ * DIVERGENCE: upstream makes the sentinel falsy (`__bool__` returns False) so
+ * `value or default` treats a missing value as absent. JavaScript objects are
+ * always truthy, so use `isGiven(value) ? value : fallback` instead.
+ */
+export class NotGiven {
+    static #instance = null;
+    /** Return the singleton instance, creating it on first use. */
+    constructor() {
+        if (NotGiven.#instance !== null) {
+            // biome-ignore lint/correctness/noConstructorReturn: singleton, as upstream's __new__.
+            return NotGiven.#instance;
+        }
+        NotGiven.#instance = this;
+    }
+    /** Return the sentinel's name. */
+    toString() {
+        return "NOT_GIVEN";
+    }
+    toJSON() {
+        return "NOT_GIVEN";
+    }
+}
+/** Singleton sentinel meaning "this value was not provided". */
+export const NOT_GIVEN = new NotGiven();
+/**
+ * Check whether a value was explicitly provided.
+ *
+ * Also acts as a type guard: inside a true branch, the value is narrowed to
+ * exclude `NotGiven` (e.g. `string | null | NotGiven` becomes `string | null`).
+ *
+ * @example
+ * if (isGiven(delta.voice)) {
+ *   // caller wants to change the voice
+ * }
+ *
+ * @param value The value to check.
+ * @returns `true` if `value` is anything other than `NOT_GIVEN`.
+ */
+export function isGiven(value) {
+    return !(value instanceof NotGiven);
+}
+/**
+ * Extract a value that must have been provided.
+ *
+ * Intended for reads where `NOT_GIVEN` should never appear, such as a
+ * store-mode settings object (see `services/settings`). Narrows away
+ * `NotGiven` at the type level and throws at runtime if that invariant is
+ * violated.
+ *
+ * @example
+ * const resolvedModel = assertGiven(this._settings.model); // narrowed string | null
+ *
+ * @param value The value to extract.
+ * @returns The value, narrowed to exclude `NotGiven`.
+ * @throws Error If `value` is `NOT_GIVEN` (upstream: RuntimeError).
+ */
+export function assertGiven(value) {
+    if (!isGiven(value)) {
+        throw new Error("Expected a value, got NOT_GIVEN");
+    }
+    return value;
+}
+/**
+ * Extract a value that must have been provided and must not be empty.
+ *
+ * Like `assertGiven()`, but also rejects `null` (and `undefined`) and the
+ * empty string, which is what an unset or blank environment variable
+ * produces. Use it for settings a service cannot work without, such as a
+ * local model or voice that no provider will validate on its behalf.
+ *
+ * @example
+ * const voice = requireGiven(this._settings.voice, "Piper TTS voice"); // narrowed string
+ *
+ * @param value The value to extract.
+ * @param what How to name the value in the error, e.g. `"Piper TTS voice"`.
+ * @returns The value, narrowed to exclude `NotGiven` and `null`.
+ * @throws Error If `value` is `NOT_GIVEN` (upstream: RuntimeError).
+ * @throws Error If `value` is `null` or an empty string (upstream: ValueError).
+ */
+export function requireGiven(value, what) {
+    const given = assertGiven(value);
+    if (given === null || given === undefined || given === "") {
+        throw new Error(`${what} must be specified`);
+    }
+    return given;
+}
+//# sourceMappingURL=types.js.map

package/dist/utils/utils.d.ts

@@ -0,0 +1,5 @@
+/** Generate a unique id for an object. */
+export declare function objId(): number;
+/** Generate a unique count for an object based on its class name. */
+export declare function objCount(obj: object): number;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils/utils.js

@@ -0,0 +1,22 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/utils/utils.py
+/**
+ * Utility functions for object identification and counting.
+ */
+const counts = new Map();
+let nextId = 0;
+/** Generate a unique id for an object. */
+export function objId() {
+    return nextId++;
+}
+/** Generate a unique count for an object based on its class name. */
+export function objCount(obj) {
+    const name = obj.constructor.name;
+    const count = counts.get(name) ?? 0;
+    counts.set(name, count + 1);
+    return count;
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils/yaml.d.ts

@@ -0,0 +1,179 @@
+/** Position of a node in its document (0-based line and column, like PyYAML's `Mark`). */
+export interface YamlMark {
+    line: number;
+    column: number;
+}
+/** Base class of the errors raised while loading YAML (`yaml.YAMLError`). */
+export declare class YAMLError extends Error {
+    name: string;
+}
+/** A YAML error tied to a place in the document (`yaml.MarkedYAMLError`). */
+export declare class MarkedYAMLError extends YAMLError {
+    name: string;
+    readonly problem: string;
+    readonly problemMark: YamlMark | null;
+    constructor(problem: string, problemMark?: YamlMark | null);
+}
+/** The document is not valid YAML (`yaml.parser.ParserError` / `yaml.scanner.ScannerError`). */
+export declare class ParserError extends MarkedYAMLError {
+    name: string;
+}
+/** A node could not be turned into a value (`yaml.constructor.ConstructorError`). */
+export declare class ConstructorError extends MarkedYAMLError {
+    name: string;
+}
+/** A scalar node (`yaml.ScalarNode`). `value` is its text. */
+export declare class ScalarNode {
+    readonly isScalar = true;
+    readonly tag: string;
+    readonly value: string;
+    readonly startMark: YamlMark | null;
+    /** How the scalar was written: `null` when plain, else `'`, `"`, `|` or `>`. */
+    readonly style: string | null;
+    constructor(tag: string, value: string, startMark: YamlMark | null, style?: string | null);
+}
+/** A sequence node (`yaml.SequenceNode`). */
+export declare class SequenceNode {
+    readonly isScalar = false;
+    readonly tag: string;
+    readonly value: YamlNode[];
+    readonly startMark: YamlMark | null;
+    constructor(tag: string, value: YamlNode[], startMark: YamlMark | null);
+}
+/** A mapping node (`yaml.MappingNode`). `value` holds the key and value nodes in order. */
+export declare class MappingNode {
+    readonly isScalar = false;
+    readonly tag: string;
+    value: [YamlNode, YamlNode][];
+    readonly startMark: YamlMark | null;
+    constructor(tag: string, value: [YamlNode, YamlNode][], startMark: YamlMark | null);
+}
+/** A YAML node, as handed to a constructor. */
+export type YamlNode = ScalarNode | SequenceNode | MappingNode;
+/** A tag constructor registered on a loader class. */
+export type YamlConstructor = (loader: SafeLoader, node: YamlNode) => unknown;
+/**
+ * Implicit resolvers by the first character of the plain scalars they apply
+ * to (`""` for the empty scalar, `null` for any): `[tag, pattern]` pairs,
+ * tried in order.
+ */
+export type YamlImplicitResolvers = Map<string | null, [string, RegExp][]>;
+/** The loader-class shape the helpers work with (a `yaml.SafeLoader` subclass upstream). */
+export interface YamlLoaderClass {
+    new (stream: string): SafeLoader;
+    yamlConstructors: Map<string, YamlConstructor>;
+    yamlImplicitResolvers: YamlImplicitResolvers;
+    /** Register a constructor for a tag on this loader class. */
+    addConstructor(tag: string, fn: YamlConstructor): void;
+    /** Register an implicit resolver on this loader class. */
+    addImplicitResolver(tag: string, regexp: RegExp, first: Iterable<string> | null): void;
+}
+/**
+ * The safe loader (`yaml.SafeLoader`): loads standard YAML 1.1 tags into
+ * plain values. Subclass it and register constructors or resolvers on the
+ * subclass to extend it; registrations never reach the parent class.
+ */
+export declare class SafeLoader {
+    #private;
+    static yamlConstructors: Map<string, YamlConstructor>;
+    static yamlImplicitResolvers: YamlImplicitResolvers;
+    /** Register `fn` as the constructor for `tag` on this class (copying the parent's table first). */
+    static addConstructor(tag: string, fn: YamlConstructor): void;
+    /**
+     * Resolve plain scalars matching `regexp` (and starting with one of `first`,
+     * or any character when null) to `tag` on this class.
+     */
+    static addImplicitResolver(tag: string, regexp: RegExp, first: Iterable<string> | null): void;
+    constructor(stream: string);
+    /** Load the stream's single document (`get_single_data`); `null` for an empty stream. */
+    getSingleData(): unknown;
+    /** Compose the stream's single document into nodes, resolving tags. */
+    getSingleNode(): YamlNode | null;
+    /** The tag a plain scalar resolves to under this class's implicit resolvers. */
+    resolveScalar(value: string): string;
+    /** Construct the value of a whole document. */
+    constructDocument(node: YamlNode): unknown;
+    /** Construct the value of `node` with the constructor registered for its tag. */
+    constructObject(node: YamlNode): unknown;
+    /** The text of a scalar node. */
+    constructScalar(node: YamlNode): string;
+    /** The values of a sequence node. */
+    constructSequence(node: YamlNode): unknown[];
+    /**
+     * The entries of a mapping node, as an object, after applying `<<` merge
+     * keys. Keys are scalars; a sequence or mapping key is an error, as an
+     * unhashable key is upstream.
+     */
+    constructMapping(node: YamlNode): Record<string, unknown>;
+    /** The entries of a sequence of one-entry mappings (`!!omap`, `!!pairs`) as `[key, value]` pairs. */
+    constructPairs(node: YamlNode): [unknown, unknown][];
+}
+/**
+ * Parse the single YAML document in `stream` (`yaml.load(stream, Loader)`).
+ *
+ * @param stream The YAML text.
+ * @param Loader The loader class to load with. Defaults to `SafeLoader`.
+ */
+export declare function load(stream: string, Loader?: YamlLoaderClass): unknown;
+/**
+ * Register an implicit resolver (`yaml.add_implicit_resolver`) on `Loader`.
+ *
+ * @param tag The tag plain scalars matching `regexp` resolve to.
+ * @param regexp The pattern a plain scalar must match.
+ * @param first The characters such scalars start with, or null for any.
+ */
+export declare function addImplicitResolver(tag: string, regexp: RegExp, first?: Iterable<string> | null, options?: {
+    Loader?: YamlLoaderClass;
+}): void;
+/**
+ * Reads an included file as UTF-8 text. Throws if the file can't be read
+ * (Node's `ENOENT` error is upstream's `FileNotFoundError`).
+ */
+export type YamlFileReader = (path: string) => string;
+export interface IncludeOptions {
+    /** Reads `!include`d files, e.g. `(p) => readFileSync(p, "utf8")`. */
+    readFile: YamlFileReader;
+}
+/**
+ * Register an `!include <relative-path>` constructor on `loaderClass`.
+ *
+ * Included files load with the same loader class, so nested includes work and
+ * scalars get the same resolver treatment as the top-level document. Paths
+ * resolve against `baseDir` and may reach outside it.
+ *
+ * This mutates `loaderClass`. Register on a private subclass rather than on
+ * `SafeLoader` itself so the constructor has no global side effects;
+ * `includeLoader` does that for you.
+ *
+ * @param loaderClass The loader class to register the constructor on.
+ * @param baseDir Directory that `!include` paths resolve against.
+ * @param options How to read the included files.
+ */
+export declare function addIncludeConstructor(loaderClass: YamlLoaderClass, baseDir: string, options: IncludeOptions): void;
+export interface IncludeLoaderOptions extends IncludeOptions {
+    /**
+     * Loader class to subclass. Defaults to `SafeLoader`; pass a custom
+     * `SafeLoader` subclass to keep its resolvers and constructors.
+     */
+    base?: YamlLoaderClass;
+}
+/**
+ * Build a loader class that resolves `!include` relative to `baseDir`.
+ *
+ * Returns a fresh subclass of `base` with the include constructor
+ * registered, so `base` itself is left untouched.
+ *
+ * @param baseDir Directory that `!include` paths resolve against, typically
+ *   the directory of the document being loaded.
+ * @param options How to read included files, and the loader class to subclass.
+ * @returns A loader class to pass to `load`.
+ *
+ * @example
+ * ```ts
+ * const data = load(readFileSync(path, "utf8"), includeLoader(dirname(path), {
+ *   readFile: (p) => readFileSync(p, "utf8"),
+ * }));
+ * ```
+ */
+export declare function includeLoader(baseDir: string, options: IncludeLoaderOptions): YamlLoaderClass;
+//# sourceMappingURL=yaml.d.ts.map