@pipedog/core 0.1.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/tracing/service_decorators.js

@@ -12,8 +12,8 @@
  *
  * Porting notes:
  * - Upstream decides at import time whether tracing is available and returns
- *   a no-op decorator otherwise. Here OpenTelemetry is registered at runtime
- *   (`registerOpenTelemetry()`), possibly after service classes are defined,
+ *   a no-op decorator otherwise. Here OpenTelemetry is imported asynchronously
+ *   or registered at runtime (see `setup.ts`), possibly after service classes are defined,
  *   so the wrappers check `isTracingAvailable()` when they run instead. With
  *   tracing unavailable they call straight through, as upstream's no-op does.
  * - Every decorator works three ways:

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

@@ -1,4 +1,4 @@
-export type OtelAttributeValue = string | number | boolean | readonly string[] | readonly number[] | readonly boolean[];
+export type OtelAttributeValue = string | number | boolean | ReadonlyArray<string | null | undefined> | ReadonlyArray<number | null | undefined> | ReadonlyArray<boolean | null | undefined>;
 /** `SpanContext` from `@opentelemetry/api`. */
 export interface OtelSpanContext {
     traceId: string;
@@ -35,10 +35,10 @@ export interface OtelApi {
 /** The `@opentelemetry/sdk-trace-base` module (v2). */
 export interface OtelSdkTraceBase {
     BasicTracerProvider: new (config?: {
-        resource?: unknown;
-        spanProcessors?: unknown[];
+        resource?: any;
+        spanProcessors?: any[];
     }) => unknown;
-    BatchSpanProcessor: new (exporter: unknown) => unknown;
+    BatchSpanProcessor: new (exporter: any) => unknown;
     ConsoleSpanExporter: new () => unknown;
 }
 /** The `@opentelemetry/resources` module (v2). */
@@ -55,8 +55,20 @@ export interface OpenTelemetryModules {
     resources?: OtelResources | null;
 }
 /**
- * Make OpenTelemetry available to Pipecat (upstream's optional import).
- * Pass `null` to disable tracing again.
+ * Wait for the automatic `import("@opentelemetry/api")` started when core
+ * loaded, and report whether tracing is available.
+ *
+ * `PipelineWorker` awaits this in its async setup, so a worker built before
+ * the import finished (e.g. at module top level) still traces; the turn trace
+ * observer and the service decorators check availability when they run.
+ *
+ * @returns True if tracing is available, False otherwise.
+ */
+export declare function loadOpenTelemetry(): Promise<boolean>;
+/**
+ * Make OpenTelemetry available to Pipecat explicitly, instead of (or before)
+ * the automatic import of `@opentelemetry/api`. Pass `null` to disable
+ * tracing again.
  */
 export declare function registerOpenTelemetry(modules: OpenTelemetryModules | null): void;
 /** The registered OpenTelemetry modules, or null if tracing is unavailable. */

package/dist/utils/tracing/setup.js

@@ -10,33 +10,83 @@
  * OpenTelemetry tracing for Pipecat applications. It handles the optional
  * nature of OpenTelemetry dependencies and provides a safe setup process.
  *
- * Porting notes: upstream detects OpenTelemetry by trying to import it. Core
- * takes no third-party dependencies, so the OpenTelemetry JS modules are
- * handed in instead, once, at startup:
+ * Porting notes: upstream detects OpenTelemetry by trying to import it, and
+ * treats it as an optional extra (`pipecat-ai[tracing]`). Here
+ * `@opentelemetry/api` is an optional peer dependency of `@pipedog/core`:
+ *
+ * - When this module loads it starts a dynamic `import("@opentelemetry/api")`
+ *   (no top-level await, so importing core never waits or throws). If the
+ *   package is not installed the import fails quietly and tracing stays
+ *   unavailable, exactly like upstream's `OPENTELEMETRY_AVAILABLE = False`.
+ *   Because the import is asynchronous, `isTracingAvailable()` turns true a
+ *   moment after core loads; `await loadOpenTelemetry()` waits for it.
+ *   Nothing latches the early "unavailable": `PipelineWorker` awaits it in
+ *   its async setup before creating the tracing observers.
+ * - `registerOpenTelemetry()` hands the modules in explicitly and
+ *   synchronously (it wins over the automatic import). `@pipedog/tracing`'s
+ *   `setupTracing()` does this, also registering `@opentelemetry/sdk-trace-base`
+ *   and `@opentelemetry/resources`, which this module's `setupTracing()` needs.
+ *
+ * Without OpenTelemetry every tracing helper is a no-op, as upstream behaves.
  *
  * @example
  * import * as api from "@opentelemetry/api";
  * import * as sdk from "@opentelemetry/sdk-trace-base";
  * import * as resources from "@opentelemetry/resources";
- * import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
  *
  * registerOpenTelemetry({ api, sdk, resources });
- * setupTracing({
- *   serviceName: "my-service",
- *   exporter: new OTLPTraceExporter({ url: "http://localhost:4318/v1/traces" }),
- * });
- *
- * Until `registerOpenTelemetry()` is called, `isTracingAvailable()` is false and
- * every tracing helper is a no-op, as upstream behaves without OpenTelemetry.
+ * setupTracing({ serviceName: "my-service", exporter: new sdk.ConsoleSpanExporter() });
  */
 import { rethrowIfCancelled } from "@pipedog/asyncio";
 import { logger } from "../logger.js";
 let openTelemetry = null;
+/** Set once `registerOpenTelemetry()` is called; the automatic import then leaves things alone. */
+let registeredExplicitly = false;
+/**
+ * Import `@opentelemetry/api` if it is installed (upstream's optional import).
+ *
+ * The specifier is a string literal so bundlers (esbuild/wrangler, Bun.build)
+ * bundle the package when it is installed; when it is not, they leave the
+ * `import()` in place and it rejects at runtime, which is caught here.
+ */
+async function importOpenTelemetryApi() {
+    try {
+        const mod = (await import("@opentelemetry/api"));
+        // CommonJS interop (some bundlers) puts the exports on `default`.
+        const api = mod?.trace ? mod : mod?.default;
+        return api?.trace && api.context ? api : null;
+    }
+    catch (e) {
+        rethrowIfCancelled(e);
+        return null;
+    }
+}
+const autoLoad = importOpenTelemetryApi().then((api) => {
+    if (api && !registeredExplicitly) {
+        openTelemetry = { api };
+    }
+});
+/**
+ * Wait for the automatic `import("@opentelemetry/api")` started when core
+ * loaded, and report whether tracing is available.
+ *
+ * `PipelineWorker` awaits this in its async setup, so a worker built before
+ * the import finished (e.g. at module top level) still traces; the turn trace
+ * observer and the service decorators check availability when they run.
+ *
+ * @returns True if tracing is available, False otherwise.
+ */
+export async function loadOpenTelemetry() {
+    await autoLoad;
+    return isTracingAvailable();
+}
 /**
- * Make OpenTelemetry available to Pipecat (upstream's optional import).
- * Pass `null` to disable tracing again.
+ * Make OpenTelemetry available to Pipecat explicitly, instead of (or before)
+ * the automatic import of `@opentelemetry/api`. Pass `null` to disable
+ * tracing again.
  */
 export function registerOpenTelemetry(modules) {
+    registeredExplicitly = true;
     openTelemetry = modules;
 }
 /** The registered OpenTelemetry modules, or null if tracing is unavailable. */

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

@@ -38,6 +38,11 @@ export declare class TurnTraceObserver extends BaseObserver {
     protected _additionalSpanAttributes: Record<string, OtelAttributeValue>;
     /** Initialize the turn trace observer. */
     constructor(options: TurnTraceObserverOptions);
+    /**
+     * The turn tracer, resolved on first use if OpenTelemetry was not available
+     * yet when the observer was built (core imports it asynchronously).
+     */
+    protected _getTracer(): OtelTracer | null;
     /**
      * Handle latency measurement events.
      *

package/dist/utils/tracing/turn_trace_observer.js

@@ -9,6 +9,10 @@
  * 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";
@@ -56,6 +60,14 @@ export class TurnTraceObserver extends BaseObserver {
             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.
      *
@@ -90,7 +102,8 @@ export class TurnTraceObserver extends BaseObserver {
      * @param conversationId Optional custom ID for the conversation. If null, a UUID will be generated.
      */
     startConversationTracing(conversationId = null) {
-        if (!isTracingAvailable() || !this._tracer) {
+        const tracer = this._getTracer();
+        if (!isTracingAvailable() || !tracer) {
             return;
         }
         // Generate a conversation ID if not provided
@@ -100,7 +113,7 @@ export class TurnTraceObserver extends BaseObserver {
         }
         this._conversationId = conversationId;
         // Create a new span for this conversation
-        const conversationSpan = this._tracer.startSpan("conversation");
+        const conversationSpan = tracer.startSpan("conversation");
         this._conversationSpan = conversationSpan;
         // Set span attributes
         conversationSpan.setAttribute("conversation.id", conversationId);
@@ -142,7 +155,8 @@ export class TurnTraceObserver extends BaseObserver {
     }
     /** Handle a turn start event by creating a new span. */
     async _handleTurnStarted(turnNumber) {
-        if (!isTracingAvailable() || !this._tracer) {
+        const tracer = this._getTracer();
+        if (!isTracingAvailable() || !tracer) {
             return;
         }
         if (turnNumber === 1 && !this._conversationSpan) {
@@ -154,7 +168,7 @@ export class TurnTraceObserver extends BaseObserver {
             parentContext = this._tracingContext.getConversationContext();
         }
         // Create a new span for this turn
-        const currentSpan = this._tracer.startSpan("turn", undefined, parentContext ?? undefined);
+        const currentSpan = tracer.startSpan("turn", undefined, parentContext ?? undefined);
         this._currentSpan = currentSpan;
         this._currentTurnNumber = turnNumber;
         // Set span attributes

package/dist/utils/yaml.d.ts

@@ -1,37 +1,138 @@
-/**
- * YAML loading helpers shared across Pipecat's YAML-based configuration.
- *
- * The main helper is `includeLoader`, which builds a loader class that
- * understands an `!include <relative-path>` tag so a document can pull in
- * other files:
- *
- * ```yaml
- * judge: !include judge_audio.yaml
- * task_messages: !include prompts/greeting.yaml
- * ```
- *
- * Include paths are not confined to the base directory; `..` and absolute
- * paths reach anywhere the process can read. Use these loaders only on
- * trusted documents.
- *
- * Not ported yet: Upstream builds on PyYAML loader classes and reads
- * included files from disk. Core takes no YAML dependency and has no
- * filesystem access (Workers), so only the interface is here; both functions
- * throw until a YAML parser and file reader are wired in.
- */
-/** A YAML node, as handed to a constructor. */
-export interface YamlNode {
-    /** Whether the node is a scalar (as opposed to a sequence or mapping). */
-    readonly isScalar: boolean;
-    /** The scalar value, for scalar nodes. */
-    readonly value?: unknown;
+/** 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: unknown, node: YamlNode) => unknown;
+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`.
@@ -41,24 +142,38 @@ export interface YamlLoaderClass {
  * resolve against `baseDir` and may reach outside it.
  *
  * This mutates `loaderClass`. Register on a private subclass rather than on
- * the base loader itself so the constructor has no global side effects;
+ * `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): void;
+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.
+ * 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 base Loader class to subclass. Defaults to the safe loader; pass a
- *   custom one to keep its resolvers and constructors.
- * @returns A loader class to load documents with.
+ * @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, _base?: YamlLoaderClass): YamlLoaderClass;
+export declare function includeLoader(baseDir: string, options: IncludeLoaderOptions): YamlLoaderClass;
 //# sourceMappingURL=yaml.d.ts.map