@nhtio/adk 1.20260609.0 → 1.20260610.0

package/batteries/media/engines/tesseract_js.cjs

@@ -0,0 +1,87 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../chunk-Ble4zEEl.js");
+const require_tool_registry = require("../../../tool_registry-CKJPze3j.js");
+require("../../../guards.cjs");
+const require_exceptions = require("../../../exceptions-CQi_lNs1.js");
+//#region src/batteries/media/engines/tesseract_js.ts
+/**
+* A cross-environment OCR {@link @nhtio/adk/batteries/media/contracts!MediaEngine}
+* backed by tesseract.js (WASM Tesseract — Node and browsers, no binary).
+*
+* @module @nhtio/adk/batteries/media/engines/tesseract_js
+*
+* @remarks
+* The local-by-default OCR engine. Language data files download on first use of each
+* language; point `langPath`/`cachePath` at a writable location to control where (the
+* factory requires `languages` up front so a deployment never silently fetches packs for
+* languages it didn't plan for). Workers are created per recognize call and terminated in
+* `finally` — slower than a pooled setup but leak-free by construction; consumers who need
+* pooling can BYO an engine that holds a worker.
+*
+* `tesseract.js` is an optional peer dependency, lazily imported on first actual use.
+*
+* Declares one convert capability: `image/*` to `txt`/`hocr`/`json` (OCR is a format
+* conversion — image in, text out). Language hints ride `request.options.languages`.
+*/
+/**
+* Construct the tesseract.js OCR engine.
+*
+* @param options - Languages (required) and data-path overrides.
+* @returns The engine.
+*/
+var tesseractJsEngine = (options) => {
+	if (!Array.isArray(options?.languages) || options.languages.length === 0) throw new require_exceptions.E_INVALID_MEDIA_PIPELINE_CONFIG(["tesseractJsEngine requires languages (e.g. [\"eng\"]) — language packs download on first use and are never chosen silently"]);
+	let modPromise;
+	const getModule = () => {
+		modPromise ??= Promise.resolve(options.tesseract ? options.tesseract() : import("tesseract.js")).catch((err) => {
+			throw new require_exceptions.E_INVALID_MEDIA_PIPELINE_CONFIG([`the tesseract.js engine could not load its peer dependency "tesseract.js": ${require_tool_registry.isError(err) ? err.message : String(err)} — install it (pnpm add tesseract.js)`]);
+		});
+		return modPromise;
+	};
+	const convert = async (request) => {
+		const mod = await getModule();
+		const languages = request.options?.languages ?? options.languages;
+		const worker = await mod.createWorker(languages, void 0, {
+			...options.langPath ? { langPath: options.langPath } : {},
+			...options.cachePath ? { cachePath: options.cachePath } : {}
+		});
+		try {
+			const result = await worker.recognize(typeof globalThis.Buffer !== "undefined" ? globalThis.Buffer.from(request.bytes.buffer, request.bytes.byteOffset, request.bytes.byteLength) : new Blob([request.bytes], { type: request.mimeType }));
+			let text = result.data.text;
+			let mimeType = "text/plain";
+			if (request.to === "json") {
+				text = JSON.stringify({
+					text: result.data.text,
+					confidence: result.data.confidence
+				});
+				mimeType = "application/json";
+			} else if (request.to === "hocr") {
+				const hocr = result.data.hocr;
+				text = hocr ?? result.data.text;
+				mimeType = hocr ? "text/html" : "text/plain";
+			}
+			return { outputs: [{
+				bytes: new TextEncoder().encode(text),
+				mimeType
+			}] };
+		} finally {
+			await worker.terminate();
+		}
+	};
+	return {
+		id: "tesseract.js",
+		converts: [{
+			from: ["image/*"],
+			to: [
+				"txt",
+				"hocr",
+				"json"
+			],
+			convert
+		}]
+	};
+};
+//#endregion
+exports.tesseractJsEngine = tesseractJsEngine;
+
+//# sourceMappingURL=tesseract_js.cjs.map

package/batteries/media/engines/tesseract_js.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tesseract_js.cjs","names":[],"sources":["../../../../src/batteries/media/engines/tesseract_js.ts"],"sourcesContent":["/**\n * A cross-environment OCR {@link @nhtio/adk/batteries/media/contracts!MediaEngine}\n * backed by tesseract.js (WASM Tesseract — Node and browsers, no binary).\n *\n * @module @nhtio/adk/batteries/media/engines/tesseract_js\n *\n * @remarks\n * The local-by-default OCR engine. Language data files download on first use of each\n * language; point `langPath`/`cachePath` at a writable location to control where (the\n * factory requires `languages` up front so a deployment never silently fetches packs for\n * languages it didn't plan for). Workers are created per recognize call and terminated in\n * `finally` — slower than a pooled setup but leak-free by construction; consumers who need\n * pooling can BYO an engine that holds a worker.\n *\n * `tesseract.js` is an optional peer dependency, lazily imported on first actual use.\n *\n * Declares one convert capability: `image/*` to `txt`/`hocr`/`json` (OCR is a format\n * conversion — image in, text out). Language hints ride `request.options.languages`.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type * as TesseractNS from 'tesseract.js'\nimport type { MediaEngine, ConvertRequest, ConvertResult } from '../contracts'\n\ntype TesseractModule = typeof TesseractNS\n\n/** Options for {@link tesseractJsEngine}. */\nexport interface TesseractJsEngineOptions {\n  /** Languages to load, e.g. `['eng']`. REQUIRED — language packs download on first use. */\n  languages: readonly string[]\n  /** Where language data is fetched from / cached (forwarded to createWorker). */\n  langPath?: string\n  /** Local cache directory for downloaded language data. */\n  cachePath?: string\n  /** Override the module resolution. Default: `import('tesseract.js')`. */\n  tesseract?: () => TesseractModule | Promise<TesseractModule>\n}\n\n/**\n * Construct the tesseract.js OCR engine.\n *\n * @param options - Languages (required) and data-path overrides.\n * @returns The engine.\n */\nexport const tesseractJsEngine = (options: TesseractJsEngineOptions): MediaEngine => {\n  if (!Array.isArray(options?.languages) || options.languages.length === 0) {\n    throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n      'tesseractJsEngine requires languages (e.g. [\"eng\"]) — language packs download on first use and are never chosen silently',\n    ])\n  }\n  let modPromise: Promise<TesseractModule> | undefined\n  const getModule = (): Promise<TesseractModule> => {\n    modPromise ??= Promise.resolve(\n      options.tesseract ? options.tesseract() : import('tesseract.js')\n    ).catch((err) => {\n      const detail = isError(err) ? err.message : String(err)\n      throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n        `the tesseract.js engine could not load its peer dependency \"tesseract.js\": ${detail} — install it (pnpm add tesseract.js)`,\n      ])\n    })\n    return modPromise\n  }\n\n  const convert = async (request: ConvertRequest): Promise<ConvertResult> => {\n    const mod = await getModule()\n    const languages = (request.options?.languages ?? options.languages) as string[]\n    const worker = await mod.createWorker(languages, undefined, {\n      ...(options.langPath ? { langPath: options.langPath } : {}),\n      ...(options.cachePath ? { cachePath: options.cachePath } : {}),\n    })\n    try {\n      const result = await worker.recognize(\n        // tesseract.js accepts Buffer/Blob/ImageLike; raw bytes work via Buffer in Node\n        typeof globalThis.Buffer !== 'undefined'\n          ? globalThis.Buffer.from(\n              request.bytes.buffer,\n              request.bytes.byteOffset,\n              request.bytes.byteLength\n            )\n          : new Blob([request.bytes as BlobPart], { type: request.mimeType })\n      )\n      let text = result.data.text\n      let mimeType = 'text/plain'\n      if (request.to === 'json') {\n        text = JSON.stringify({ text: result.data.text, confidence: result.data.confidence })\n        mimeType = 'application/json'\n      } else if (request.to === 'hocr') {\n        // hocr requires opting into the output at recognize time in tesseract.js v5+;\n        // fall back to text when unavailable rather than failing the read.\n        const hocr = (result.data as { hocr?: string | null }).hocr\n        text = hocr ?? result.data.text\n        mimeType = hocr ? 'text/html' : 'text/plain'\n      }\n      return { outputs: [{ bytes: new TextEncoder().encode(text), mimeType }] }\n    } finally {\n      await worker.terminate()\n    }\n  }\n\n  return {\n    id: 'tesseract.js',\n    converts: [\n      {\n        from: ['image/*'],\n        to: ['txt', 'hocr', 'json'],\n        convert,\n      },\n    ],\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,IAAa,qBAAqB,YAAmD;CACnF,IAAI,CAAC,MAAM,QAAQ,SAAS,SAAS,KAAK,QAAQ,UAAU,WAAW,GACrE,MAAM,IAAI,mBAAA,gCAAgC,CACxC,4HACF,CAAC;CAEH,IAAI;CACJ,MAAM,kBAA4C;EAChD,eAAe,QAAQ,QACrB,QAAQ,YAAY,QAAQ,UAAU,IAAI,OAAO,eACnD,EAAE,OAAO,QAAQ;GAEf,MAAM,IAAI,mBAAA,gCAAgC,CACxC,8EAFa,sBAAA,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,EAEiC,sCACvF,CAAC;EACH,CAAC;EACD,OAAO;CACT;CAEA,MAAM,UAAU,OAAO,YAAoD;EACzE,MAAM,MAAM,MAAM,UAAU;EAC5B,MAAM,YAAa,QAAQ,SAAS,aAAa,QAAQ;EACzD,MAAM,SAAS,MAAM,IAAI,aAAa,WAAW,KAAA,GAAW;GAC1D,GAAI,QAAQ,WAAW,EAAE,UAAU,QAAQ,SAAS,IAAI,CAAC;GACzD,GAAI,QAAQ,YAAY,EAAE,WAAW,QAAQ,UAAU,IAAI,CAAC;EAC9D,CAAC;EACD,IAAI;GACF,MAAM,SAAS,MAAM,OAAO,UAE1B,OAAO,WAAW,WAAW,cACzB,WAAW,OAAO,KAChB,QAAQ,MAAM,QACd,QAAQ,MAAM,YACd,QAAQ,MAAM,UAChB,IACA,IAAI,KAAK,CAAC,QAAQ,KAAiB,GAAG,EAAE,MAAM,QAAQ,SAAS,CAAC,CACtE;GACA,IAAI,OAAO,OAAO,KAAK;GACvB,IAAI,WAAW;GACf,IAAI,QAAQ,OAAO,QAAQ;IACzB,OAAO,KAAK,UAAU;KAAE,MAAM,OAAO,KAAK;KAAM,YAAY,OAAO,KAAK;IAAW,CAAC;IACpF,WAAW;GACb,OAAO,IAAI,QAAQ,OAAO,QAAQ;IAGhC,MAAM,OAAQ,OAAO,KAAkC;IACvD,OAAO,QAAQ,OAAO,KAAK;IAC3B,WAAW,OAAO,cAAc;GAClC;GACA,OAAO,EAAE,SAAS,CAAC;IAAE,OAAO,IAAI,YAAY,EAAE,OAAO,IAAI;IAAG;GAAS,CAAC,EAAE;EAC1E,UAAU;GACR,MAAM,OAAO,UAAU;EACzB;CACF;CAEA,OAAO;EACL,IAAI;EACJ,UAAU,CACR;GACE,MAAM,CAAC,SAAS;GAChB,IAAI;IAAC;IAAO;IAAQ;GAAM;GAC1B;EACF,CACF;CACF;AACF"}

package/batteries/media/engines/tesseract_js.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A cross-environment OCR {@link @nhtio/adk/batteries/media/contracts!MediaEngine}
+ * backed by tesseract.js (WASM Tesseract — Node and browsers, no binary).
+ *
+ * @module @nhtio/adk/batteries/media/engines/tesseract_js
+ *
+ * @remarks
+ * The local-by-default OCR engine. Language data files download on first use of each
+ * language; point `langPath`/`cachePath` at a writable location to control where (the
+ * factory requires `languages` up front so a deployment never silently fetches packs for
+ * languages it didn't plan for). Workers are created per recognize call and terminated in
+ * `finally` — slower than a pooled setup but leak-free by construction; consumers who need
+ * pooling can BYO an engine that holds a worker.
+ *
+ * `tesseract.js` is an optional peer dependency, lazily imported on first actual use.
+ *
+ * Declares one convert capability: `image/*` to `txt`/`hocr`/`json` (OCR is a format
+ * conversion — image in, text out). Language hints ride `request.options.languages`.
+ */
+import type * as TesseractNS from 'tesseract.js';
+import type { MediaEngine } from "../contracts";
+type TesseractModule = typeof TesseractNS;
+/** Options for {@link tesseractJsEngine}. */
+export interface TesseractJsEngineOptions {
+    /** Languages to load, e.g. `['eng']`. REQUIRED — language packs download on first use. */
+    languages: readonly string[];
+    /** Where language data is fetched from / cached (forwarded to createWorker). */
+    langPath?: string;
+    /** Local cache directory for downloaded language data. */
+    cachePath?: string;
+    /** Override the module resolution. Default: `import('tesseract.js')`. */
+    tesseract?: () => TesseractModule | Promise<TesseractModule>;
+}
+/**
+ * Construct the tesseract.js OCR engine.
+ *
+ * @param options - Languages (required) and data-path overrides.
+ * @returns The engine.
+ */
+export declare const tesseractJsEngine: (options: TesseractJsEngineOptions) => MediaEngine;
+export {};

package/batteries/media/engines/tesseract_js.mjs

@@ -0,0 +1,85 @@
+import { o as isError } from "../../../tool_registry-791Vrjtf.mjs";
+import "../../../guards.mjs";
+import { t as E_INVALID_MEDIA_PIPELINE_CONFIG } from "../../../exceptions-C7FSHEnV.mjs";
+//#region src/batteries/media/engines/tesseract_js.ts
+/**
+* A cross-environment OCR {@link @nhtio/adk/batteries/media/contracts!MediaEngine}
+* backed by tesseract.js (WASM Tesseract — Node and browsers, no binary).
+*
+* @module @nhtio/adk/batteries/media/engines/tesseract_js
+*
+* @remarks
+* The local-by-default OCR engine. Language data files download on first use of each
+* language; point `langPath`/`cachePath` at a writable location to control where (the
+* factory requires `languages` up front so a deployment never silently fetches packs for
+* languages it didn't plan for). Workers are created per recognize call and terminated in
+* `finally` — slower than a pooled setup but leak-free by construction; consumers who need
+* pooling can BYO an engine that holds a worker.
+*
+* `tesseract.js` is an optional peer dependency, lazily imported on first actual use.
+*
+* Declares one convert capability: `image/*` to `txt`/`hocr`/`json` (OCR is a format
+* conversion — image in, text out). Language hints ride `request.options.languages`.
+*/
+/**
+* Construct the tesseract.js OCR engine.
+*
+* @param options - Languages (required) and data-path overrides.
+* @returns The engine.
+*/
+var tesseractJsEngine = (options) => {
+	if (!Array.isArray(options?.languages) || options.languages.length === 0) throw new E_INVALID_MEDIA_PIPELINE_CONFIG(["tesseractJsEngine requires languages (e.g. [\"eng\"]) — language packs download on first use and are never chosen silently"]);
+	let modPromise;
+	const getModule = () => {
+		modPromise ??= Promise.resolve(options.tesseract ? options.tesseract() : import("tesseract.js")).catch((err) => {
+			throw new E_INVALID_MEDIA_PIPELINE_CONFIG([`the tesseract.js engine could not load its peer dependency "tesseract.js": ${isError(err) ? err.message : String(err)} — install it (pnpm add tesseract.js)`]);
+		});
+		return modPromise;
+	};
+	const convert = async (request) => {
+		const mod = await getModule();
+		const languages = request.options?.languages ?? options.languages;
+		const worker = await mod.createWorker(languages, void 0, {
+			...options.langPath ? { langPath: options.langPath } : {},
+			...options.cachePath ? { cachePath: options.cachePath } : {}
+		});
+		try {
+			const result = await worker.recognize(typeof globalThis.Buffer !== "undefined" ? globalThis.Buffer.from(request.bytes.buffer, request.bytes.byteOffset, request.bytes.byteLength) : new Blob([request.bytes], { type: request.mimeType }));
+			let text = result.data.text;
+			let mimeType = "text/plain";
+			if (request.to === "json") {
+				text = JSON.stringify({
+					text: result.data.text,
+					confidence: result.data.confidence
+				});
+				mimeType = "application/json";
+			} else if (request.to === "hocr") {
+				const hocr = result.data.hocr;
+				text = hocr ?? result.data.text;
+				mimeType = hocr ? "text/html" : "text/plain";
+			}
+			return { outputs: [{
+				bytes: new TextEncoder().encode(text),
+				mimeType
+			}] };
+		} finally {
+			await worker.terminate();
+		}
+	};
+	return {
+		id: "tesseract.js",
+		converts: [{
+			from: ["image/*"],
+			to: [
+				"txt",
+				"hocr",
+				"json"
+			],
+			convert
+		}]
+	};
+};
+//#endregion
+export { tesseractJsEngine };
+
+//# sourceMappingURL=tesseract_js.mjs.map

package/batteries/media/engines/tesseract_js.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"tesseract_js.mjs","names":[],"sources":["../../../../src/batteries/media/engines/tesseract_js.ts"],"sourcesContent":["/**\n * A cross-environment OCR {@link @nhtio/adk/batteries/media/contracts!MediaEngine}\n * backed by tesseract.js (WASM Tesseract — Node and browsers, no binary).\n *\n * @module @nhtio/adk/batteries/media/engines/tesseract_js\n *\n * @remarks\n * The local-by-default OCR engine. Language data files download on first use of each\n * language; point `langPath`/`cachePath` at a writable location to control where (the\n * factory requires `languages` up front so a deployment never silently fetches packs for\n * languages it didn't plan for). Workers are created per recognize call and terminated in\n * `finally` — slower than a pooled setup but leak-free by construction; consumers who need\n * pooling can BYO an engine that holds a worker.\n *\n * `tesseract.js` is an optional peer dependency, lazily imported on first actual use.\n *\n * Declares one convert capability: `image/*` to `txt`/`hocr`/`json` (OCR is a format\n * conversion — image in, text out). Language hints ride `request.options.languages`.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type * as TesseractNS from 'tesseract.js'\nimport type { MediaEngine, ConvertRequest, ConvertResult } from '../contracts'\n\ntype TesseractModule = typeof TesseractNS\n\n/** Options for {@link tesseractJsEngine}. */\nexport interface TesseractJsEngineOptions {\n  /** Languages to load, e.g. `['eng']`. REQUIRED — language packs download on first use. */\n  languages: readonly string[]\n  /** Where language data is fetched from / cached (forwarded to createWorker). */\n  langPath?: string\n  /** Local cache directory for downloaded language data. */\n  cachePath?: string\n  /** Override the module resolution. Default: `import('tesseract.js')`. */\n  tesseract?: () => TesseractModule | Promise<TesseractModule>\n}\n\n/**\n * Construct the tesseract.js OCR engine.\n *\n * @param options - Languages (required) and data-path overrides.\n * @returns The engine.\n */\nexport const tesseractJsEngine = (options: TesseractJsEngineOptions): MediaEngine => {\n  if (!Array.isArray(options?.languages) || options.languages.length === 0) {\n    throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n      'tesseractJsEngine requires languages (e.g. [\"eng\"]) — language packs download on first use and are never chosen silently',\n    ])\n  }\n  let modPromise: Promise<TesseractModule> | undefined\n  const getModule = (): Promise<TesseractModule> => {\n    modPromise ??= Promise.resolve(\n      options.tesseract ? options.tesseract() : import('tesseract.js')\n    ).catch((err) => {\n      const detail = isError(err) ? err.message : String(err)\n      throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n        `the tesseract.js engine could not load its peer dependency \"tesseract.js\": ${detail} — install it (pnpm add tesseract.js)`,\n      ])\n    })\n    return modPromise\n  }\n\n  const convert = async (request: ConvertRequest): Promise<ConvertResult> => {\n    const mod = await getModule()\n    const languages = (request.options?.languages ?? options.languages) as string[]\n    const worker = await mod.createWorker(languages, undefined, {\n      ...(options.langPath ? { langPath: options.langPath } : {}),\n      ...(options.cachePath ? { cachePath: options.cachePath } : {}),\n    })\n    try {\n      const result = await worker.recognize(\n        // tesseract.js accepts Buffer/Blob/ImageLike; raw bytes work via Buffer in Node\n        typeof globalThis.Buffer !== 'undefined'\n          ? globalThis.Buffer.from(\n              request.bytes.buffer,\n              request.bytes.byteOffset,\n              request.bytes.byteLength\n            )\n          : new Blob([request.bytes as BlobPart], { type: request.mimeType })\n      )\n      let text = result.data.text\n      let mimeType = 'text/plain'\n      if (request.to === 'json') {\n        text = JSON.stringify({ text: result.data.text, confidence: result.data.confidence })\n        mimeType = 'application/json'\n      } else if (request.to === 'hocr') {\n        // hocr requires opting into the output at recognize time in tesseract.js v5+;\n        // fall back to text when unavailable rather than failing the read.\n        const hocr = (result.data as { hocr?: string | null }).hocr\n        text = hocr ?? result.data.text\n        mimeType = hocr ? 'text/html' : 'text/plain'\n      }\n      return { outputs: [{ bytes: new TextEncoder().encode(text), mimeType }] }\n    } finally {\n      await worker.terminate()\n    }\n  }\n\n  return {\n    id: 'tesseract.js',\n    converts: [\n      {\n        from: ['image/*'],\n        to: ['txt', 'hocr', 'json'],\n        convert,\n      },\n    ],\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6CA,IAAa,qBAAqB,YAAmD;CACnF,IAAI,CAAC,MAAM,QAAQ,SAAS,SAAS,KAAK,QAAQ,UAAU,WAAW,GACrE,MAAM,IAAI,gCAAgC,CACxC,4HACF,CAAC;CAEH,IAAI;CACJ,MAAM,kBAA4C;EAChD,eAAe,QAAQ,QACrB,QAAQ,YAAY,QAAQ,UAAU,IAAI,OAAO,eACnD,EAAE,OAAO,QAAQ;GAEf,MAAM,IAAI,gCAAgC,CACxC,8EAFa,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,EAEiC,sCACvF,CAAC;EACH,CAAC;EACD,OAAO;CACT;CAEA,MAAM,UAAU,OAAO,YAAoD;EACzE,MAAM,MAAM,MAAM,UAAU;EAC5B,MAAM,YAAa,QAAQ,SAAS,aAAa,QAAQ;EACzD,MAAM,SAAS,MAAM,IAAI,aAAa,WAAW,KAAA,GAAW;GAC1D,GAAI,QAAQ,WAAW,EAAE,UAAU,QAAQ,SAAS,IAAI,CAAC;GACzD,GAAI,QAAQ,YAAY,EAAE,WAAW,QAAQ,UAAU,IAAI,CAAC;EAC9D,CAAC;EACD,IAAI;GACF,MAAM,SAAS,MAAM,OAAO,UAE1B,OAAO,WAAW,WAAW,cACzB,WAAW,OAAO,KAChB,QAAQ,MAAM,QACd,QAAQ,MAAM,YACd,QAAQ,MAAM,UAChB,IACA,IAAI,KAAK,CAAC,QAAQ,KAAiB,GAAG,EAAE,MAAM,QAAQ,SAAS,CAAC,CACtE;GACA,IAAI,OAAO,OAAO,KAAK;GACvB,IAAI,WAAW;GACf,IAAI,QAAQ,OAAO,QAAQ;IACzB,OAAO,KAAK,UAAU;KAAE,MAAM,OAAO,KAAK;KAAM,YAAY,OAAO,KAAK;IAAW,CAAC;IACpF,WAAW;GACb,OAAO,IAAI,QAAQ,OAAO,QAAQ;IAGhC,MAAM,OAAQ,OAAO,KAAkC;IACvD,OAAO,QAAQ,OAAO,KAAK;IAC3B,WAAW,OAAO,cAAc;GAClC;GACA,OAAO,EAAE,SAAS,CAAC;IAAE,OAAO,IAAI,YAAY,EAAE,OAAO,IAAI;IAAG;GAAS,CAAC,EAAE;EAC1E,UAAU;GACR,MAAM,OAAO,UAAU;EACzB;CACF;CAEA,OAAO;EACL,IAAI;EACJ,UAAU,CACR;GACE,MAAM,CAAC,SAAS;GAChB,IAAI;IAAC;IAAO;IAAQ;GAAM;GAC1B;EACF,CACF;CACF;AACF"}

package/batteries/media/engines/transformers_asr.cjs

@@ -0,0 +1,111 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../chunk-Ble4zEEl.js");
+const require_tool_registry = require("../../../tool_registry-CKJPze3j.js");
+require("../../../guards.cjs");
+const require_batteries_media_contracts = require("../contracts.cjs");
+const require_exceptions = require("../../../exceptions-CQi_lNs1.js");
+//#region src/batteries/media/engines/transformers_asr.ts
+/**
+* A cross-environment transcription {@link @nhtio/adk/batteries/media/contracts!MediaEngine}
+* backed by `@huggingface/transformers` Whisper (ONNX in Node, WASM/WebGPU in browsers).
+*
+* @module @nhtio/adk/batteries/media/engines/transformers_asr
+*
+* @remarks
+* The local-by-default speech-to-text engine: no external API, no binary. Declares one
+* convert capability: the virtual `pcm` token to `txt`/`srt`/`vtt`/`json` (transcription is a
+* format conversion — PCM in, text out). The Whisper model id is REQUIRED — models are
+* multi-hundred-megabyte downloads on first use and the battery never triggers one silently
+* (the loud-config rule). Input is 16 kHz mono PCM, exactly what the transcribe step
+* supplies; `lang`/`translate` ride `request.options`. `srt`/`vtt` output is assembled from
+* chunk timestamps; `json` returns the chunk structure verbatim.
+*
+* `@huggingface/transformers` is an optional peer dependency, lazily imported on first
+* actual use.
+*/
+var pad = (n, width = 2) => String(Math.floor(n)).padStart(width, "0");
+var formatTimestamp = (seconds, separator) => {
+	const h = Math.floor(seconds / 3600);
+	const m = Math.floor(seconds % 3600 / 60);
+	const s = Math.floor(seconds % 60);
+	const ms = Math.floor(seconds % 1 * 1e3);
+	return `${pad(h)}:${pad(m)}:${pad(s)}${separator}${String(ms).padStart(3, "0")}`;
+};
+var toSubtitles = (chunks, kind) => {
+	const sep = kind === "srt" ? "," : ".";
+	const blocks = chunks.map((chunk, i) => {
+		const [start, end] = chunk.timestamp;
+		const range = `${formatTimestamp(start, sep)} --> ${formatTimestamp(end ?? start, sep)}`;
+		return kind === "srt" ? `${i + 1}\n${range}\n${chunk.text.trim()}` : `${range}\n${chunk.text.trim()}`;
+	});
+	return kind === "vtt" ? `WEBVTT\n\n${blocks.join("\n\n")}\n` : `${blocks.join("\n\n")}\n`;
+};
+/**
+* Construct the transformers.js Whisper ASR engine.
+*
+* @param options - Model id (required) and overrides.
+* @returns The engine.
+*/
+var transformersAsrEngine = (options) => {
+	if (typeof options?.model !== "string" || options.model.length === 0) throw new require_exceptions.E_INVALID_MEDIA_PIPELINE_CONFIG(["transformersAsrEngine requires an explicit Whisper model id (e.g. onnx-community/whisper-base) — models are large downloads and are never chosen silently"]);
+	let pipePromise;
+	const getPipeline = () => {
+		pipePromise ??= (async () => {
+			let mod;
+			try {
+				mod = await (options.transformers ? options.transformers() : import("@huggingface/transformers"));
+			} catch (err) {
+				throw new require_exceptions.E_INVALID_MEDIA_PIPELINE_CONFIG([`the transformers ASR engine could not load its peer dependency "@huggingface/transformers": ${require_tool_registry.isError(err) ? err.message : String(err)} — install it (pnpm add @huggingface/transformers)`]);
+			}
+			return await mod.pipeline("automatic-speech-recognition", options.model, { ...options.pipelineOptions ?? {} });
+		})();
+		return pipePromise;
+	};
+	const convert = async (request) => {
+		const pipe = await getPipeline();
+		const lang = request.options?.lang;
+		const translate = request.options?.translate;
+		const wantsTimestamps = request.to === "srt" || request.to === "vtt" || request.to === "json";
+		const result = await pipe(require_batteries_media_contracts.bytesToPcm(request.bytes), {
+			...lang ? { language: lang } : {},
+			...translate ? { task: "translate" } : {},
+			...wantsTimestamps ? { return_timestamps: true } : {},
+			chunk_length_s: 30
+		});
+		const output = Array.isArray(result) ? result[0] : result;
+		let text;
+		let mimeType = "text/plain";
+		if (request.to === "json") {
+			text = JSON.stringify({
+				text: output.text,
+				chunks: output.chunks ?? []
+			});
+			mimeType = "application/json";
+		} else if (request.to === "srt" || request.to === "vtt") text = toSubtitles(output.chunks ?? [{
+			timestamp: [0, null],
+			text: output.text
+		}], request.to);
+		else text = output.text.trim();
+		return { outputs: [{
+			bytes: new TextEncoder().encode(text),
+			mimeType
+		}] };
+	};
+	return {
+		id: "transformers-asr",
+		converts: [{
+			from: [require_batteries_media_contracts.PCM_MIME],
+			to: [
+				"txt",
+				"srt",
+				"vtt",
+				"json"
+			],
+			convert
+		}]
+	};
+};
+//#endregion
+exports.transformersAsrEngine = transformersAsrEngine;
+
+//# sourceMappingURL=transformers_asr.cjs.map

package/batteries/media/engines/transformers_asr.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformers_asr.cjs","names":[],"sources":["../../../../src/batteries/media/engines/transformers_asr.ts"],"sourcesContent":["/**\n * A cross-environment transcription {@link @nhtio/adk/batteries/media/contracts!MediaEngine}\n * backed by `@huggingface/transformers` Whisper (ONNX in Node, WASM/WebGPU in browsers).\n *\n * @module @nhtio/adk/batteries/media/engines/transformers_asr\n *\n * @remarks\n * The local-by-default speech-to-text engine: no external API, no binary. Declares one\n * convert capability: the virtual `pcm` token to `txt`/`srt`/`vtt`/`json` (transcription is a\n * format conversion — PCM in, text out). The Whisper model id is REQUIRED — models are\n * multi-hundred-megabyte downloads on first use and the battery never triggers one silently\n * (the loud-config rule). Input is 16 kHz mono PCM, exactly what the transcribe step\n * supplies; `lang`/`translate` ride `request.options`. `srt`/`vtt` output is assembled from\n * chunk timestamps; `json` returns the chunk structure verbatim.\n *\n * `@huggingface/transformers` is an optional peer dependency, lazily imported on first\n * actual use.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { bytesToPcm, PCM_MIME } from '../contracts'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type * as TransformersNS from '@huggingface/transformers'\nimport type { MediaEngine, ConvertRequest, ConvertResult } from '../contracts'\n\ntype TransformersModule = typeof TransformersNS\n\ninterface AsrChunk {\n  timestamp: [number, number | null]\n  text: string\n}\n\ninterface AsrPipelineOutput {\n  text: string\n  chunks?: AsrChunk[]\n}\n\ntype AsrPipelineFn = (\n  audio: Float32Array,\n  options: Record<string, unknown>\n) => Promise<AsrPipelineOutput | AsrPipelineOutput[]>\n\n/** Options for {@link transformersAsrEngine}. */\nexport interface TransformersAsrEngineOptions {\n  /**\n   * The Whisper model id, e.g. `onnx-community/whisper-base`. REQUIRED — no default, no\n   * surprise downloads.\n   */\n  model: string\n  /** Override the module resolution. Default: `import('@huggingface/transformers')`. */\n  transformers?: () => TransformersModule | Promise<TransformersModule>\n  /** Extra options forwarded to `pipeline()` (device, dtype, cache_dir…). */\n  pipelineOptions?: Record<string, unknown>\n}\n\nconst pad = (n: number, width = 2): string => String(Math.floor(n)).padStart(width, '0')\n\nconst formatTimestamp = (seconds: number, separator: ',' | '.'): string => {\n  const h = Math.floor(seconds / 3600)\n  const m = Math.floor((seconds % 3600) / 60)\n  const s = Math.floor(seconds % 60)\n  const ms = Math.floor((seconds % 1) * 1000)\n  return `${pad(h)}:${pad(m)}:${pad(s)}${separator}${String(ms).padStart(3, '0')}`\n}\n\nconst toSubtitles = (chunks: AsrChunk[], kind: 'srt' | 'vtt'): string => {\n  const sep = kind === 'srt' ? ',' : '.'\n  const blocks = chunks.map((chunk, i) => {\n    const [start, end] = chunk.timestamp\n    const range = `${formatTimestamp(start, sep)} --> ${formatTimestamp(end ?? start, sep)}`\n    return kind === 'srt'\n      ? `${i + 1}\\n${range}\\n${chunk.text.trim()}`\n      : `${range}\\n${chunk.text.trim()}`\n  })\n  return kind === 'vtt' ? `WEBVTT\\n\\n${blocks.join('\\n\\n')}\\n` : `${blocks.join('\\n\\n')}\\n`\n}\n\n/**\n * Construct the transformers.js Whisper ASR engine.\n *\n * @param options - Model id (required) and overrides.\n * @returns The engine.\n */\nexport const transformersAsrEngine = (options: TransformersAsrEngineOptions): MediaEngine => {\n  if (typeof options?.model !== 'string' || options.model.length === 0) {\n    throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n      'transformersAsrEngine requires an explicit Whisper model id (e.g. onnx-community/whisper-base) — models are large downloads and are never chosen silently',\n    ])\n  }\n  let pipePromise: Promise<AsrPipelineFn> | undefined\n  const getPipeline = (): Promise<AsrPipelineFn> => {\n    pipePromise ??= (async () => {\n      let mod: TransformersModule\n      try {\n        mod = await (options.transformers\n          ? options.transformers()\n          : import('@huggingface/transformers'))\n      } catch (err) {\n        const detail = isError(err) ? err.message : String(err)\n        throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n          `the transformers ASR engine could not load its peer dependency \"@huggingface/transformers\": ${detail} — install it (pnpm add @huggingface/transformers)`,\n        ])\n      }\n      const pipe = await mod.pipeline('automatic-speech-recognition', options.model, {\n        ...(options.pipelineOptions ?? {}),\n      } as never)\n      return pipe as unknown as AsrPipelineFn\n    })()\n    return pipePromise\n  }\n\n  const convert = async (request: ConvertRequest): Promise<ConvertResult> => {\n    const pipe = await getPipeline()\n    const lang = request.options?.lang\n    const translate = request.options?.translate\n    const wantsTimestamps = request.to === 'srt' || request.to === 'vtt' || request.to === 'json'\n    const result = await pipe(bytesToPcm(request.bytes), {\n      ...(lang ? { language: lang } : {}),\n      ...(translate ? { task: 'translate' } : {}),\n      ...(wantsTimestamps ? { return_timestamps: true } : {}),\n      chunk_length_s: 30,\n    })\n    const output = Array.isArray(result) ? result[0] : result\n    let text: string\n    let mimeType = 'text/plain'\n    if (request.to === 'json') {\n      text = JSON.stringify({ text: output.text, chunks: output.chunks ?? [] })\n      mimeType = 'application/json'\n    } else if (request.to === 'srt' || request.to === 'vtt') {\n      const chunks = output.chunks ?? [\n        { timestamp: [0, null] as [number, null], text: output.text },\n      ]\n      text = toSubtitles(chunks, request.to)\n    } else {\n      text = output.text.trim()\n    }\n    return { outputs: [{ bytes: new TextEncoder().encode(text), mimeType }] }\n  }\n\n  return {\n    id: 'transformers-asr',\n    converts: [\n      {\n        from: [PCM_MIME],\n        to: ['txt', 'srt', 'vtt', 'json'],\n        convert,\n      },\n    ],\n  }\n}\n"],"mappings":"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"}

package/batteries/media/engines/transformers_asr.d.ts

@@ -0,0 +1,41 @@
+/**
+ * A cross-environment transcription {@link @nhtio/adk/batteries/media/contracts!MediaEngine}
+ * backed by `@huggingface/transformers` Whisper (ONNX in Node, WASM/WebGPU in browsers).
+ *
+ * @module @nhtio/adk/batteries/media/engines/transformers_asr
+ *
+ * @remarks
+ * The local-by-default speech-to-text engine: no external API, no binary. Declares one
+ * convert capability: the virtual `pcm` token to `txt`/`srt`/`vtt`/`json` (transcription is a
+ * format conversion — PCM in, text out). The Whisper model id is REQUIRED — models are
+ * multi-hundred-megabyte downloads on first use and the battery never triggers one silently
+ * (the loud-config rule). Input is 16 kHz mono PCM, exactly what the transcribe step
+ * supplies; `lang`/`translate` ride `request.options`. `srt`/`vtt` output is assembled from
+ * chunk timestamps; `json` returns the chunk structure verbatim.
+ *
+ * `@huggingface/transformers` is an optional peer dependency, lazily imported on first
+ * actual use.
+ */
+import type * as TransformersNS from '@huggingface/transformers';
+import type { MediaEngine } from "../contracts";
+type TransformersModule = typeof TransformersNS;
+/** Options for {@link transformersAsrEngine}. */
+export interface TransformersAsrEngineOptions {
+    /**
+     * The Whisper model id, e.g. `onnx-community/whisper-base`. REQUIRED — no default, no
+     * surprise downloads.
+     */
+    model: string;
+    /** Override the module resolution. Default: `import('@huggingface/transformers')`. */
+    transformers?: () => TransformersModule | Promise<TransformersModule>;
+    /** Extra options forwarded to `pipeline()` (device, dtype, cache_dir…). */
+    pipelineOptions?: Record<string, unknown>;
+}
+/**
+ * Construct the transformers.js Whisper ASR engine.
+ *
+ * @param options - Model id (required) and overrides.
+ * @returns The engine.
+ */
+export declare const transformersAsrEngine: (options: TransformersAsrEngineOptions) => MediaEngine;
+export {};

package/batteries/media/engines/transformers_asr.mjs

@@ -0,0 +1,109 @@
+import { o as isError } from "../../../tool_registry-791Vrjtf.mjs";
+import "../../../guards.mjs";
+import { PCM_MIME, bytesToPcm } from "../contracts.mjs";
+import { t as E_INVALID_MEDIA_PIPELINE_CONFIG } from "../../../exceptions-C7FSHEnV.mjs";
+//#region src/batteries/media/engines/transformers_asr.ts
+/**
+* A cross-environment transcription {@link @nhtio/adk/batteries/media/contracts!MediaEngine}
+* backed by `@huggingface/transformers` Whisper (ONNX in Node, WASM/WebGPU in browsers).
+*
+* @module @nhtio/adk/batteries/media/engines/transformers_asr
+*
+* @remarks
+* The local-by-default speech-to-text engine: no external API, no binary. Declares one
+* convert capability: the virtual `pcm` token to `txt`/`srt`/`vtt`/`json` (transcription is a
+* format conversion — PCM in, text out). The Whisper model id is REQUIRED — models are
+* multi-hundred-megabyte downloads on first use and the battery never triggers one silently
+* (the loud-config rule). Input is 16 kHz mono PCM, exactly what the transcribe step
+* supplies; `lang`/`translate` ride `request.options`. `srt`/`vtt` output is assembled from
+* chunk timestamps; `json` returns the chunk structure verbatim.
+*
+* `@huggingface/transformers` is an optional peer dependency, lazily imported on first
+* actual use.
+*/
+var pad = (n, width = 2) => String(Math.floor(n)).padStart(width, "0");
+var formatTimestamp = (seconds, separator) => {
+	const h = Math.floor(seconds / 3600);
+	const m = Math.floor(seconds % 3600 / 60);
+	const s = Math.floor(seconds % 60);
+	const ms = Math.floor(seconds % 1 * 1e3);
+	return `${pad(h)}:${pad(m)}:${pad(s)}${separator}${String(ms).padStart(3, "0")}`;
+};
+var toSubtitles = (chunks, kind) => {
+	const sep = kind === "srt" ? "," : ".";
+	const blocks = chunks.map((chunk, i) => {
+		const [start, end] = chunk.timestamp;
+		const range = `${formatTimestamp(start, sep)} --> ${formatTimestamp(end ?? start, sep)}`;
+		return kind === "srt" ? `${i + 1}\n${range}\n${chunk.text.trim()}` : `${range}\n${chunk.text.trim()}`;
+	});
+	return kind === "vtt" ? `WEBVTT\n\n${blocks.join("\n\n")}\n` : `${blocks.join("\n\n")}\n`;
+};
+/**
+* Construct the transformers.js Whisper ASR engine.
+*
+* @param options - Model id (required) and overrides.
+* @returns The engine.
+*/
+var transformersAsrEngine = (options) => {
+	if (typeof options?.model !== "string" || options.model.length === 0) throw new E_INVALID_MEDIA_PIPELINE_CONFIG(["transformersAsrEngine requires an explicit Whisper model id (e.g. onnx-community/whisper-base) — models are large downloads and are never chosen silently"]);
+	let pipePromise;
+	const getPipeline = () => {
+		pipePromise ??= (async () => {
+			let mod;
+			try {
+				mod = await (options.transformers ? options.transformers() : import("@huggingface/transformers"));
+			} catch (err) {
+				throw new E_INVALID_MEDIA_PIPELINE_CONFIG([`the transformers ASR engine could not load its peer dependency "@huggingface/transformers": ${isError(err) ? err.message : String(err)} — install it (pnpm add @huggingface/transformers)`]);
+			}
+			return await mod.pipeline("automatic-speech-recognition", options.model, { ...options.pipelineOptions ?? {} });
+		})();
+		return pipePromise;
+	};
+	const convert = async (request) => {
+		const pipe = await getPipeline();
+		const lang = request.options?.lang;
+		const translate = request.options?.translate;
+		const wantsTimestamps = request.to === "srt" || request.to === "vtt" || request.to === "json";
+		const result = await pipe(bytesToPcm(request.bytes), {
+			...lang ? { language: lang } : {},
+			...translate ? { task: "translate" } : {},
+			...wantsTimestamps ? { return_timestamps: true } : {},
+			chunk_length_s: 30
+		});
+		const output = Array.isArray(result) ? result[0] : result;
+		let text;
+		let mimeType = "text/plain";
+		if (request.to === "json") {
+			text = JSON.stringify({
+				text: output.text,
+				chunks: output.chunks ?? []
+			});
+			mimeType = "application/json";
+		} else if (request.to === "srt" || request.to === "vtt") text = toSubtitles(output.chunks ?? [{
+			timestamp: [0, null],
+			text: output.text
+		}], request.to);
+		else text = output.text.trim();
+		return { outputs: [{
+			bytes: new TextEncoder().encode(text),
+			mimeType
+		}] };
+	};
+	return {
+		id: "transformers-asr",
+		converts: [{
+			from: [PCM_MIME],
+			to: [
+				"txt",
+				"srt",
+				"vtt",
+				"json"
+			],
+			convert
+		}]
+	};
+};
+//#endregion
+export { transformersAsrEngine };
+
+//# sourceMappingURL=transformers_asr.mjs.map

package/batteries/media/engines/transformers_asr.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformers_asr.mjs","names":[],"sources":["../../../../src/batteries/media/engines/transformers_asr.ts"],"sourcesContent":["/**\n * A cross-environment transcription {@link @nhtio/adk/batteries/media/contracts!MediaEngine}\n * backed by `@huggingface/transformers` Whisper (ONNX in Node, WASM/WebGPU in browsers).\n *\n * @module @nhtio/adk/batteries/media/engines/transformers_asr\n *\n * @remarks\n * The local-by-default speech-to-text engine: no external API, no binary. Declares one\n * convert capability: the virtual `pcm` token to `txt`/`srt`/`vtt`/`json` (transcription is a\n * format conversion — PCM in, text out). The Whisper model id is REQUIRED — models are\n * multi-hundred-megabyte downloads on first use and the battery never triggers one silently\n * (the loud-config rule). Input is 16 kHz mono PCM, exactly what the transcribe step\n * supplies; `lang`/`translate` ride `request.options`. `srt`/`vtt` output is assembled from\n * chunk timestamps; `json` returns the chunk structure verbatim.\n *\n * `@huggingface/transformers` is an optional peer dependency, lazily imported on first\n * actual use.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { bytesToPcm, PCM_MIME } from '../contracts'\nimport { E_INVALID_MEDIA_PIPELINE_CONFIG } from '../exceptions'\nimport type * as TransformersNS from '@huggingface/transformers'\nimport type { MediaEngine, ConvertRequest, ConvertResult } from '../contracts'\n\ntype TransformersModule = typeof TransformersNS\n\ninterface AsrChunk {\n  timestamp: [number, number | null]\n  text: string\n}\n\ninterface AsrPipelineOutput {\n  text: string\n  chunks?: AsrChunk[]\n}\n\ntype AsrPipelineFn = (\n  audio: Float32Array,\n  options: Record<string, unknown>\n) => Promise<AsrPipelineOutput | AsrPipelineOutput[]>\n\n/** Options for {@link transformersAsrEngine}. */\nexport interface TransformersAsrEngineOptions {\n  /**\n   * The Whisper model id, e.g. `onnx-community/whisper-base`. REQUIRED — no default, no\n   * surprise downloads.\n   */\n  model: string\n  /** Override the module resolution. Default: `import('@huggingface/transformers')`. */\n  transformers?: () => TransformersModule | Promise<TransformersModule>\n  /** Extra options forwarded to `pipeline()` (device, dtype, cache_dir…). */\n  pipelineOptions?: Record<string, unknown>\n}\n\nconst pad = (n: number, width = 2): string => String(Math.floor(n)).padStart(width, '0')\n\nconst formatTimestamp = (seconds: number, separator: ',' | '.'): string => {\n  const h = Math.floor(seconds / 3600)\n  const m = Math.floor((seconds % 3600) / 60)\n  const s = Math.floor(seconds % 60)\n  const ms = Math.floor((seconds % 1) * 1000)\n  return `${pad(h)}:${pad(m)}:${pad(s)}${separator}${String(ms).padStart(3, '0')}`\n}\n\nconst toSubtitles = (chunks: AsrChunk[], kind: 'srt' | 'vtt'): string => {\n  const sep = kind === 'srt' ? ',' : '.'\n  const blocks = chunks.map((chunk, i) => {\n    const [start, end] = chunk.timestamp\n    const range = `${formatTimestamp(start, sep)} --> ${formatTimestamp(end ?? start, sep)}`\n    return kind === 'srt'\n      ? `${i + 1}\\n${range}\\n${chunk.text.trim()}`\n      : `${range}\\n${chunk.text.trim()}`\n  })\n  return kind === 'vtt' ? `WEBVTT\\n\\n${blocks.join('\\n\\n')}\\n` : `${blocks.join('\\n\\n')}\\n`\n}\n\n/**\n * Construct the transformers.js Whisper ASR engine.\n *\n * @param options - Model id (required) and overrides.\n * @returns The engine.\n */\nexport const transformersAsrEngine = (options: TransformersAsrEngineOptions): MediaEngine => {\n  if (typeof options?.model !== 'string' || options.model.length === 0) {\n    throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n      'transformersAsrEngine requires an explicit Whisper model id (e.g. onnx-community/whisper-base) — models are large downloads and are never chosen silently',\n    ])\n  }\n  let pipePromise: Promise<AsrPipelineFn> | undefined\n  const getPipeline = (): Promise<AsrPipelineFn> => {\n    pipePromise ??= (async () => {\n      let mod: TransformersModule\n      try {\n        mod = await (options.transformers\n          ? options.transformers()\n          : import('@huggingface/transformers'))\n      } catch (err) {\n        const detail = isError(err) ? err.message : String(err)\n        throw new E_INVALID_MEDIA_PIPELINE_CONFIG([\n          `the transformers ASR engine could not load its peer dependency \"@huggingface/transformers\": ${detail} — install it (pnpm add @huggingface/transformers)`,\n        ])\n      }\n      const pipe = await mod.pipeline('automatic-speech-recognition', options.model, {\n        ...(options.pipelineOptions ?? {}),\n      } as never)\n      return pipe as unknown as AsrPipelineFn\n    })()\n    return pipePromise\n  }\n\n  const convert = async (request: ConvertRequest): Promise<ConvertResult> => {\n    const pipe = await getPipeline()\n    const lang = request.options?.lang\n    const translate = request.options?.translate\n    const wantsTimestamps = request.to === 'srt' || request.to === 'vtt' || request.to === 'json'\n    const result = await pipe(bytesToPcm(request.bytes), {\n      ...(lang ? { language: lang } : {}),\n      ...(translate ? { task: 'translate' } : {}),\n      ...(wantsTimestamps ? { return_timestamps: true } : {}),\n      chunk_length_s: 30,\n    })\n    const output = Array.isArray(result) ? result[0] : result\n    let text: string\n    let mimeType = 'text/plain'\n    if (request.to === 'json') {\n      text = JSON.stringify({ text: output.text, chunks: output.chunks ?? [] })\n      mimeType = 'application/json'\n    } else if (request.to === 'srt' || request.to === 'vtt') {\n      const chunks = output.chunks ?? [\n        { timestamp: [0, null] as [number, null], text: output.text },\n      ]\n      text = toSubtitles(chunks, request.to)\n    } else {\n      text = output.text.trim()\n    }\n    return { outputs: [{ bytes: new TextEncoder().encode(text), mimeType }] }\n  }\n\n  return {\n    id: 'transformers-asr',\n    converts: [\n      {\n        from: [PCM_MIME],\n        to: ['txt', 'srt', 'vtt', 'json'],\n        convert,\n      },\n    ],\n  }\n}\n"],"mappings":"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"}

package/batteries/media/exceptions.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Battery-scoped exceptions for the media pipeline battery.
+ *
+ * @remarks
+ * Internal sibling of the `@nhtio/adk/batteries/media` entry — re-exported from the battery's
+ * own barrel per the battery-scoped-exceptions rule. These are the typed errors the
+ * implementor-facing API throws; the agent-facing forge catches them and renders readable
+ * failure strings the model can act on.
+ *
+ * Error layering (see the design doc, frozen section 0):
+ *
+ * - Config errors (`E_INVALID_MEDIA_PIPELINE_CONFIG`) throw at pipeline construction or first
+ *   engine-resolver resolution. Fatal — a programmer mistake, not a runtime condition.
+ * - Syntactic pipe errors (`E_MEDIA_PIPE_SYNTAX`) carry line/col position plus a
+ *   "write it like:" exemplar, because models repair from instructions, not carets.
+ * - Semantic plan errors (`E_MEDIA_UNKNOWN_VERB`, `E_MEDIA_UNKNOWN_ARG`, `E_MEDIA_BAD_ARG`,
+ *   `E_MEDIA_MISSING_ARG`, `E_MEDIA_UNSUPPORTED_OP`, `E_MEDIA_ENGINE_REQUIRED`) are produced by
+ *   the plan validator walking the AST against the full verb table and the configured engines.
+ * - Render errors (`E_MEDIA_NOT_PIPE_EXPRESSIBLE`) come from `toPipe()` on plans containing
+ *   builder-only constructs.
+ * - Execution errors (`E_MEDIA_STEP_FAILED`, `E_MEDIA_STEP_UNAVAILABLE`) surface step-runtime
+ *   failures with the original error as `cause`.
+ */
+/**
+ * Thrown when `createMediaPipeline` receives an invalid configuration — a malformed engine,
+ * a resolver that resolved to a value failing its contract guard, or an invalid option shape.
+ */
+export declare const E_INVALID_MEDIA_PIPELINE_CONFIG: import("../../factories").CreatedException<[
+    string
+]>;
+/**
+ * Thrown by `parsePipe` when the pipe expression fails to tokenize or parse. The message carries
+ * line/col position and a corrective exemplar.
+ */
+export declare const E_MEDIA_PIPE_SYNTAX: import("../../factories").CreatedException<[
+    string
+]>;
+/**
+ * Thrown when a statement names a verb that does not exist in the verb table. The message
+ * includes a did-you-mean suggestion (Levenshtein over folded verb forms, including suffix-word
+ * matches) and the list of verbs available in this deployment.
+ */
+export declare const E_MEDIA_UNKNOWN_VERB: import("../../factories").CreatedException<[
+    string
+]>;
+/**
+ * Thrown when a statement passes an arg a verb does not declare. The message includes a
+ * did-you-mean suggestion and the verb's declared args.
+ */
+export declare const E_MEDIA_UNKNOWN_ARG: import("../../factories").CreatedException<[
+    string
+]>;
+/**
+ * Thrown when an arg value fails its declared type/enum/constraint — including descending
+ * ranges, invalid regex sources, malformed embedded JSON, and out-of-enum values.
+ */
+export declare const E_MEDIA_BAD_ARG: import("../../factories").CreatedException<[
+    string
+]>;
+/** Thrown when a verb's required arg is absent from the statement. */
+export declare const E_MEDIA_MISSING_ARG: import("../../factories").CreatedException<[
+    string
+]>;
+/**
+ * Thrown at plan validation when a verb cannot apply to the input's format family (e.g. a
+ * `sheet.*` verb on a PDF), or a namespace verb is used on the wrong media kind.
+ */
+export declare const E_MEDIA_UNSUPPORTED_OP: import("../../factories").CreatedException<[
+    string
+]>;
+/**
+ * Thrown at plan validation when a verb (or the specific input it is applied to) requires an
+ * engine that is not configured on this pipeline. The message states which engine slot is
+ * missing and — when the failure is input-specific — that the verb should not be retried on
+ * this media in this deployment.
+ */
+export declare const E_MEDIA_ENGINE_REQUIRED: import("../../factories").CreatedException<[
+    string
+]>;
+/**
+ * Thrown by `toPipe()` when the plan contains constructs the flat pipe grammar cannot express —
+ * currently only nested-builder media refs. Quoted-JSON structured args DO render; use `toOps()`
+ * for a total serialization.
+ */
+export declare const E_MEDIA_NOT_PIPE_EXPRESSIBLE: import("../../factories").CreatedException<[
+    string
+]>;
+/**
+ * Thrown by the step runtime when a step implementation fails mid-execution (corrupt input,
+ * engine error). Carries the underlying error as `cause`.
+ */
+export declare const E_MEDIA_STEP_FAILED: import("../../factories").CreatedException<[
+    string,
+    string
+]>;
+/**
+ * Thrown by the step runtime when a plan step has no registered implementation. Distinct from
+ * `E_MEDIA_ENGINE_REQUIRED`: this indicates the battery itself does not (yet) implement the
+ * verb, not that the consumer omitted an engine.
+ */
+export declare const E_MEDIA_STEP_UNAVAILABLE: import("../../factories").CreatedException<[
+    string
+]>;