@nhtio/adk 1.20260625.0 → 1.20260626.0

package/batteries/embeddings/transformers_js/adapter.mjs

@@ -0,0 +1,191 @@
+import { c as isError } from "../../../tool_registry-Bj0JhXCv.mjs";
+import "../../../guards.mjs";
+import { n as emitLifecycle } from "../../../lifecycle-C4kwYJ-N.mjs";
+import { withModelSource } from "../../llm/transformers_js/model_source.mjs";
+import { applyEmbeddingPrefix } from "../openai/helpers.mjs";
+import { poolAndNormalize } from "./pooling.mjs";
+import { E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS, E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR } from "./exceptions.mjs";
+import { validateOptions } from "./validation.mjs";
+//#region src/batteries/embeddings/transformers_js/adapter.ts
+/**
+* transformers.js (ONNX, dual-environment) Embeddings adapter battery.
+*
+* @module @nhtio/adk/batteries/embeddings/transformers_js/adapter
+*
+* @remarks
+* Embeddings battery backed by transformers.js's `feature-extraction` pipeline. **Environment-neutral**
+* — runs in Node (via `onnxruntime-node`) and the browser (via `onnxruntime-web` / WebGPU), auto-
+* selected by the package; there is no WebGPU requirement, so this battery is surfaced from the
+* environment-neutral `@nhtio/adk/batteries/embeddings` barrel alongside the OpenAI one.
+*
+* Same user-facing surface as the OpenAI / WebLLM embeddings batteries (`isAvailable` / `dimensions` /
+* `preload` / `reset` / `embed` / `embedMany`), same `number[]` return shape, same query/document
+* prefix handling (the shared `applyEmbeddingPrefix`).
+*
+* `@huggingface/transformers` is an optional peer dependency, imported lazily.
+*
+* **Cross-runtime vector caveat:** embeddings produced here are not guaranteed bit-identical to those
+* from a different runtime (WebLLM/MLC, or even node-ONNX vs web-ONNX for the same model). A vector
+* corpus must be embedded AND queried by one backend.
+*/
+var makeDefaultCreatePipeline = (modelSource) => {
+	return async ({ model, device, dtype, onInitProgress }) => {
+		const { pipeline, env } = await import("@huggingface/transformers");
+		const load = async () => await pipeline("feature-extraction", model, {
+			...device ? { device } : {},
+			...dtype ? { dtype } : {},
+			...onInitProgress ? { progress_callback: onInitProgress } : {}
+		});
+		return modelSource ? withModelSource(env, modelSource, load) : load();
+	};
+};
+/**
+* Embeddings adapter for transformers.js's feature-extraction pipeline.
+*
+* @remarks
+* Reusable: construct once, call {@link TransformersJsEmbeddingsAdapter.embed} / {@link embedMany} as
+* many times as needed. The pipeline is resolved lazily on first use (or via {@link preload}) and
+* cached with single-flight semantics so concurrent calls share one load.
+*/
+var TransformersJsEmbeddingsAdapter = class TransformersJsEmbeddingsAdapter {
+	#options;
+	#pipeline;
+	#pipelinePromise;
+	/**
+	* Whether this battery is available. transformers.js is environment-neutral (Node + browser), so
+	* this is `true` whenever the runtime can import the peer — there is no WebGPU requirement.
+	*/
+	static isAvailable() {
+		return true;
+	}
+	/**
+	* @param options - Constructor options. Validated eagerly.
+	* @throws {@link @nhtio/adk/batteries!E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS} when invalid.
+	*/
+	constructor(options) {
+		this.#options = validateOptions(options);
+		this.#pipeline = this.#options.pipeline;
+	}
+	/** Declared output dimensionality (from options), or `undefined` if not configured. */
+	get dimensions() {
+		return this.#options.dimensions;
+	}
+	/** Instance availability probe (honours an injected `isAvailable`). */
+	isAvailable() {
+		return (this.#options.isAvailable ?? TransformersJsEmbeddingsAdapter.isAvailable)();
+	}
+	/** Eagerly loads (and caches) the pipeline so the first `embed` call is fast. Idempotent. */
+	async preload() {
+		await this.#resolvePipeline();
+	}
+	/** Drops the cached pipeline and in-flight load so the next call reloads. */
+	reset() {
+		this.#pipeline = void 0;
+		this.#pipelinePromise = void 0;
+	}
+	/**
+	* Release the loaded model's ONNX sessions + GPU/wasm buffers, then drop the cached pipeline.
+	*
+	* @remarks
+	* `reset()` only nulls the JS reference; the native ONNX Runtime sessions and WebGPU/wasm device memory
+	* stay alive until GC. Loading many embedding models back-to-back in one browser session (e.g. a full
+	* matrix run) accumulates those sessions until the heap is exhausted. `FeatureExtractionPipeline`
+	* extends `Pipeline`, which exposes `dispose()` — this awaits it so the memory is reclaimed between
+	* loads, swallows a disposal error (teardown must not throw), and finishes with `reset()`. Idempotent.
+	*/
+	async dispose() {
+		const pipeWithDispose = this.#pipeline ?? await this.#pipelinePromise?.catch(() => void 0);
+		if (typeof pipeWithDispose?.dispose === "function") await Promise.resolve(pipeWithDispose.dispose()).catch(() => void 0);
+		this.reset();
+	}
+	async #resolvePipeline() {
+		if (this.#pipeline) return this.#pipeline;
+		if (!this.isAvailable()) throw new E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS(["the transformers.js embeddings battery is not available in this runtime"]);
+		const opts = this.#options;
+		this.#pipelinePromise ??= (async () => {
+			emitLifecycle(opts, "transformers_js_embed", opts.model, "loading", { detail: "loading feature-extraction pipeline" });
+			const forwardedInitProgress = opts.onLifecycle ?? opts.onLoading ?? opts.onReady ?? opts.onGenerating ?? opts.onError ? (info) => {
+				const p = info?.progress;
+				emitLifecycle(opts, "transformers_js_embed", opts.model, "loading", {
+					...typeof p === "number" ? { progress: p / 100 } : {},
+					raw: info
+				});
+				opts.onInitProgress?.(info);
+			} : opts.onInitProgress;
+			const createPipeline = opts.createPipeline ?? makeDefaultCreatePipeline(opts.modelSource);
+			try {
+				emitLifecycle(opts, "transformers_js_embed", opts.model, "compiling", { detail: "compiling feature-extraction graph" });
+				const pipe = await createPipeline({
+					model: opts.model,
+					device: opts.device,
+					dtype: opts.dtype,
+					onInitProgress: forwardedInitProgress
+				});
+				this.#pipeline = pipe;
+				emitLifecycle(opts, "transformers_js_embed", opts.model, "ready", { detail: "feature-extraction pipeline ready" });
+				return pipe;
+			} catch (err) {
+				this.#pipelinePromise = void 0;
+				emitLifecycle(opts, "transformers_js_embed", opts.model, "error", { error: err });
+				throw new E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR([`could not load the transformers.js pipeline: ${isError(err) ? err.message : String(err)} — install the peer dependency (pnpm add @huggingface/transformers)`]);
+			}
+		})();
+		return this.#pipelinePromise;
+	}
+	/**
+	* Embeds a single string.
+	*
+	* @param text - The input text.
+	* @param opts - Per-call options (`kind`).
+	* @returns The embedding vector as a plain `number[]`.
+	*/
+	async embed(text, opts) {
+		const [vec] = await this.embedMany([text], opts);
+		return vec;
+	}
+	/**
+	* Embeds a batch of strings in a single pipeline call.
+	*
+	* @param texts - The input texts.
+	* @param opts - Per-call options (`kind`). Defaults to `kind: 'document'`.
+	* @returns One embedding vector per input, in input order, each a plain `number[]`.
+	* @throws {@link @nhtio/adk/batteries!E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR} when the call fails
+	*   or returns a malformed result.
+	*/
+	async embedMany(texts, opts) {
+		if (texts.length === 0) return [];
+		const input = applyEmbeddingPrefix(texts, opts?.kind ?? "document", this.#options);
+		const pipe = await this.#resolvePipeline();
+		const pooling = this.#options.pooling ?? "mean";
+		const normalize = this.#options.normalize ?? true;
+		const battery = (this.#options.poolingOwner ?? "engine") === "battery";
+		emitLifecycle(this.#options, "transformers_js_embed", this.#options.model, "generating");
+		let tensor;
+		try {
+			tensor = await pipe(input, battery ? { pooling: "none" } : {
+				pooling,
+				normalize
+			});
+		} catch (err) {
+			emitLifecycle(this.#options, "transformers_js_embed", this.#options.model, "error", { error: err });
+			throw new E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR([isError(err) ? err.message : String(err)]);
+		}
+		if (!tensor || typeof tensor.tolist !== "function") throw new E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR(["feature-extraction returned a non-Tensor result"]);
+		const list = tensor.tolist();
+		let vectors;
+		if (battery) {
+			const states = list;
+			vectors = poolAndNormalize(Array.isArray(states) && Array.isArray(states[0]) && Array.isArray(states[0][0]) ? states : [states], pooling, normalize);
+		} else vectors = Array.isArray(list) && Array.isArray(list[0]) ? list : [list];
+		if (vectors.length !== input.length) {
+			emitLifecycle(this.#options, "transformers_js_embed", this.#options.model, "error", { error: /* @__PURE__ */ new Error(`expected ${input.length} vectors, got ${vectors.length}`) });
+			throw new E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR([`expected ${input.length} vectors, got ${vectors.length}`]);
+		}
+		emitLifecycle(this.#options, "transformers_js_embed", this.#options.model, "complete");
+		return vectors;
+	}
+};
+//#endregion
+export { TransformersJsEmbeddingsAdapter };
+
+//# sourceMappingURL=adapter.mjs.map

package/batteries/embeddings/transformers_js/adapter.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.mjs","names":["#options","#pipeline","#resolvePipeline","#pipelinePromise"],"sources":["../../../../src/batteries/embeddings/transformers_js/adapter.ts"],"sourcesContent":["/**\n * transformers.js (ONNX, dual-environment) Embeddings adapter battery.\n *\n * @module @nhtio/adk/batteries/embeddings/transformers_js/adapter\n *\n * @remarks\n * Embeddings battery backed by transformers.js's `feature-extraction` pipeline. **Environment-neutral**\n * — runs in Node (via `onnxruntime-node`) and the browser (via `onnxruntime-web` / WebGPU), auto-\n * selected by the package; there is no WebGPU requirement, so this battery is surfaced from the\n * environment-neutral `@nhtio/adk/batteries/embeddings` barrel alongside the OpenAI one.\n *\n * Same user-facing surface as the OpenAI / WebLLM embeddings batteries (`isAvailable` / `dimensions` /\n * `preload` / `reset` / `embed` / `embedMany`), same `number[]` return shape, same query/document\n * prefix handling (the shared `applyEmbeddingPrefix`).\n *\n * `@huggingface/transformers` is an optional peer dependency, imported lazily.\n *\n * **Cross-runtime vector caveat:** embeddings produced here are not guaranteed bit-identical to those\n * from a different runtime (WebLLM/MLC, or even node-ONNX vs web-ONNX for the same model). A vector\n * corpus must be embedded AND queried by one backend.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { poolAndNormalize } from './pooling'\nimport { validateOptions } from './validation'\nimport { applyEmbeddingPrefix } from '../openai/helpers'\nimport { emitLifecycle } from '../../llm/chat_common/lifecycle'\nimport { withModelSource } from '../../llm/transformers_js/model_source'\nimport {\n  E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS,\n  E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR,\n} from './exceptions'\nimport type { EmbedOptions } from '../openai/types'\nimport type {\n  TransformersJsEmbeddingsAdapterOptions,\n  TransformersJsEmbeddingsPipeline,\n  CreateTransformersJsEmbeddingsPipeline,\n} from './types'\n\nconst makeDefaultCreatePipeline = (\n  modelSource: TransformersJsEmbeddingsAdapterOptions['modelSource']\n): CreateTransformersJsEmbeddingsPipeline => {\n  return async ({ model, device, dtype, onInitProgress }) => {\n    const transformers = await import('@huggingface/transformers')\n    const { pipeline, env } = transformers\n    const load = async () =>\n      (await pipeline('feature-extraction', model, {\n        ...(device ? { device } : {}),\n        ...(dtype ? { dtype } : {}),\n        ...(onInitProgress ? { progress_callback: onInitProgress } : {}),\n      } as never)) as unknown as TransformersJsEmbeddingsPipeline\n    // When a custom model source is configured, serve files through it behind the global-`env` mutex.\n    return modelSource ? withModelSource(env as never, modelSource, load) : load()\n  }\n}\n\n/**\n * Embeddings adapter for transformers.js's feature-extraction pipeline.\n *\n * @remarks\n * Reusable: construct once, call {@link TransformersJsEmbeddingsAdapter.embed} / {@link embedMany} as\n * many times as needed. The pipeline is resolved lazily on first use (or via {@link preload}) and\n * cached with single-flight semantics so concurrent calls share one load.\n */\nexport class TransformersJsEmbeddingsAdapter {\n  readonly #options: TransformersJsEmbeddingsAdapterOptions\n  #pipeline: TransformersJsEmbeddingsPipeline | undefined\n  #pipelinePromise: Promise<TransformersJsEmbeddingsPipeline> | undefined\n\n  /**\n   * Whether this battery is available. transformers.js is environment-neutral (Node + browser), so\n   * this is `true` whenever the runtime can import the peer — there is no WebGPU requirement.\n   */\n  public static isAvailable(): boolean {\n    return true\n  }\n\n  /**\n   * @param options - Constructor options. Validated eagerly.\n   * @throws {@link @nhtio/adk/batteries!E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS} when invalid.\n   */\n  constructor(options: unknown) {\n    this.#options = validateOptions(options)\n    this.#pipeline = this.#options.pipeline\n  }\n\n  /** Declared output dimensionality (from options), or `undefined` if not configured. */\n  get dimensions(): number | undefined {\n    return this.#options.dimensions\n  }\n\n  /** Instance availability probe (honours an injected `isAvailable`). */\n  isAvailable(): boolean {\n    return (this.#options.isAvailable ?? TransformersJsEmbeddingsAdapter.isAvailable)()\n  }\n\n  /** Eagerly loads (and caches) the pipeline so the first `embed` call is fast. Idempotent. */\n  async preload(): Promise<void> {\n    await this.#resolvePipeline()\n  }\n\n  /** Drops the cached pipeline and in-flight load so the next call reloads. */\n  reset(): void {\n    this.#pipeline = undefined\n    this.#pipelinePromise = undefined\n  }\n\n  /**\n   * Release the loaded model's ONNX sessions + GPU/wasm buffers, then drop the cached pipeline.\n   *\n   * @remarks\n   * `reset()` only nulls the JS reference; the native ONNX Runtime sessions and WebGPU/wasm device memory\n   * stay alive until GC. Loading many embedding models back-to-back in one browser session (e.g. a full\n   * matrix run) accumulates those sessions until the heap is exhausted. `FeatureExtractionPipeline`\n   * extends `Pipeline`, which exposes `dispose()` — this awaits it so the memory is reclaimed between\n   * loads, swallows a disposal error (teardown must not throw), and finishes with `reset()`. Idempotent.\n   */\n  async dispose(): Promise<void> {\n    const pipeline = this.#pipeline ?? (await this.#pipelinePromise?.catch(() => undefined))\n    const pipeWithDispose = pipeline as { dispose?: () => Promise<unknown> } | undefined\n    if (typeof pipeWithDispose?.dispose === 'function') {\n      await Promise.resolve(pipeWithDispose.dispose()).catch(() => undefined)\n    }\n    this.reset()\n  }\n\n  async #resolvePipeline(): Promise<TransformersJsEmbeddingsPipeline> {\n    if (this.#pipeline) return this.#pipeline\n    if (!this.isAvailable()) {\n      throw new E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS([\n        'the transformers.js embeddings battery is not available in this runtime',\n      ])\n    }\n    const opts = this.#options\n    this.#pipelinePromise ??= (async () => {\n      emitLifecycle(opts, 'transformers_js_embed', opts.model, 'loading', {\n        detail: 'loading feature-extraction pipeline',\n      })\n      // Forward each provider download event into a normalized `loading` lifecycle report.\n      const hasLifecycle =\n        opts.onLifecycle ?? opts.onLoading ?? opts.onReady ?? opts.onGenerating ?? opts.onError\n      const forwardedInitProgress = hasLifecycle\n        ? (info: unknown) => {\n            const p = (info as { progress?: number } | undefined)?.progress\n            emitLifecycle(opts, 'transformers_js_embed', opts.model, 'loading', {\n              ...(typeof p === 'number' ? { progress: p / 100 } : {}),\n              raw: info,\n            })\n            opts.onInitProgress?.(info as never)\n          }\n        : opts.onInitProgress\n      const createPipeline = opts.createPipeline ?? makeDefaultCreatePipeline(opts.modelSource)\n      try {\n        // `from_pretrained` covers both fetch (reported via progress_callback → `loading`) and the\n        // ONNX-graph / WebGPU-WASM warmup. Mark the latter as `compiling` — a COARSE upper-bound marker\n        // (fetch + compile overlap inside the call), consistent with the LLM batteries.\n        emitLifecycle(opts, 'transformers_js_embed', opts.model, 'compiling', {\n          detail: 'compiling feature-extraction graph',\n        })\n        const pipe = await createPipeline({\n          model: opts.model,\n          device: opts.device,\n          dtype: opts.dtype,\n          onInitProgress: forwardedInitProgress,\n        })\n        this.#pipeline = pipe\n        emitLifecycle(opts, 'transformers_js_embed', opts.model, 'ready', {\n          detail: 'feature-extraction pipeline ready',\n        })\n        return pipe\n      } catch (err) {\n        this.#pipelinePromise = undefined\n        emitLifecycle(opts, 'transformers_js_embed', opts.model, 'error', { error: err })\n        throw new E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR([\n          `could not load the transformers.js pipeline: ${isError(err) ? err.message : String(err)} — install the peer dependency (pnpm add @huggingface/transformers)`,\n        ])\n      }\n    })()\n    return this.#pipelinePromise\n  }\n\n  /**\n   * Embeds a single string.\n   *\n   * @param text - The input text.\n   * @param opts - Per-call options (`kind`).\n   * @returns The embedding vector as a plain `number[]`.\n   */\n  async embed(text: string, opts?: EmbedOptions): Promise<number[]> {\n    const [vec] = await this.embedMany([text], opts)\n    return vec\n  }\n\n  /**\n   * Embeds a batch of strings in a single pipeline call.\n   *\n   * @param texts - The input texts.\n   * @param opts - Per-call options (`kind`). Defaults to `kind: 'document'`.\n   * @returns One embedding vector per input, in input order, each a plain `number[]`.\n   * @throws {@link @nhtio/adk/batteries!E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR} when the call fails\n   *   or returns a malformed result.\n   */\n  async embedMany(texts: string[], opts?: EmbedOptions): Promise<number[][]> {\n    if (texts.length === 0) return []\n    const kind = opts?.kind ?? 'document'\n    const input = applyEmbeddingPrefix(texts, kind, this.#options)\n\n    const pipe = await this.#resolvePipeline()\n    const pooling = this.#options.pooling ?? 'mean'\n    const normalize = this.#options.normalize ?? true\n    const battery = (this.#options.poolingOwner ?? 'engine') === 'battery'\n\n    emitLifecycle(this.#options, 'transformers_js_embed', this.#options.model, 'generating')\n\n    let tensor: { tolist: () => unknown; dims?: number[] }\n    try {\n      tensor = (await (pipe as unknown as (i: unknown, o: unknown) => Promise<unknown>)(\n        input,\n        // 'battery' owner: request RAW token states (no engine pooling/normalize) and do it ourselves\n        // in deterministic JS. 'engine' owner: delegate to the pipeline exactly as before.\n        battery ? { pooling: 'none' } : { pooling, normalize }\n      )) as { tolist: () => unknown; dims?: number[] }\n    } catch (err) {\n      emitLifecycle(this.#options, 'transformers_js_embed', this.#options.model, 'error', {\n        error: err,\n      })\n      throw new E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR([\n        isError(err) ? err.message : String(err),\n      ])\n    }\n\n    if (!tensor || typeof tensor.tolist !== 'function') {\n      throw new E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR([\n        'feature-extraction returned a non-Tensor result',\n      ])\n    }\n\n    const list = tensor.tolist()\n    let vectors: number[][]\n    if (battery) {\n      // Raw states: tolist() → [batch, seq, hidden]. A single ungrouped input may come back as\n      // [seq, hidden] → wrap to a batch of one. Pool + normalize deterministically.\n      const states = list as unknown[]\n      const tokenStates = (\n        Array.isArray(states) &&\n        Array.isArray(states[0]) &&\n        Array.isArray((states[0] as unknown[])[0])\n          ? states\n          : [states]\n      ) as number[][][]\n      vectors = poolAndNormalize(tokenStates, pooling, normalize)\n    } else {\n      // With engine pooling, the Tensor is [batch, hidden] → tolist() yields number[][].\n      vectors =\n        Array.isArray(list) && Array.isArray(list[0]) ? (list as number[][]) : [list as number[]]\n    }\n\n    if (vectors.length !== input.length) {\n      emitLifecycle(this.#options, 'transformers_js_embed', this.#options.model, 'error', {\n        error: new Error(`expected ${input.length} vectors, got ${vectors.length}`),\n      })\n      throw new E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR([\n        `expected ${input.length} vectors, got ${vectors.length}`,\n      ])\n    }\n    emitLifecycle(this.#options, 'transformers_js_embed', this.#options.model, 'complete')\n    return vectors\n  }\n}\n"],"mappings":"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"}

package/batteries/embeddings/transformers_js/exceptions.cjs

@@ -0,0 +1,32 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../chunk-Cek0wNdY.js");
+const require_exceptions = require("../../../exceptions-BfOYct3J.js");
+require("../../../factories.cjs");
+//#region src/batteries/embeddings/transformers_js/exceptions.ts
+/**
+* Battery-scoped exception constructors for the transformers.js Embeddings adapter.
+*
+* @module @nhtio/adk/batteries/embeddings/transformers_js/exceptions
+*
+* @remarks
+* Battery-scoped exception classes for the transformers.js (`@huggingface/transformers`) Embeddings
+* adapter, minted via `createException` from `@nhtio/adk/factories`. Categories mirror the OpenAI and
+* WebLLM embeddings batteries one-to-one — only the engine-specific failure differs.
+*/
+/**
+* Thrown when the resolved adapter options fail validation against
+* `transformersJsEmbeddingsOptionsSchema` — e.g. a missing/empty `model` or an unknown option key.
+* Fatal: config bugs fail loud, not at embed time.
+*/
+var E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS = require_exceptions.createException("E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS", "Invalid transformers.js Embeddings adapter options: %s", "E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS", 529, true);
+/**
+* Thrown when the transformers.js pipeline fails to load (e.g. the `@huggingface/transformers` peer
+* is not installed) or the `feature-extraction` call throws/returns a malformed result. Non-fatal.
+* Printf arg: `[detail]`.
+*/
+var E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR = require_exceptions.createException("E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR", "transformers.js Embeddings engine error: %s", "E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR", 502, false);
+//#endregion
+exports.E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS = E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS;
+exports.E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR = E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR;
+
+//# sourceMappingURL=exceptions.cjs.map

package/batteries/embeddings/transformers_js/exceptions.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.cjs","names":[],"sources":["../../../../src/batteries/embeddings/transformers_js/exceptions.ts"],"sourcesContent":["/**\n * Battery-scoped exception constructors for the transformers.js Embeddings adapter.\n *\n * @module @nhtio/adk/batteries/embeddings/transformers_js/exceptions\n *\n * @remarks\n * Battery-scoped exception classes for the transformers.js (`@huggingface/transformers`) Embeddings\n * adapter, minted via `createException` from `@nhtio/adk/factories`. Categories mirror the OpenAI and\n * WebLLM embeddings batteries one-to-one — only the engine-specific failure differs.\n */\n\nimport { createException } from '@nhtio/adk/factories'\n\n/**\n * Thrown when the resolved adapter options fail validation against\n * `transformersJsEmbeddingsOptionsSchema` — e.g. a missing/empty `model` or an unknown option key.\n * Fatal: config bugs fail loud, not at embed time.\n */\nexport const E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS = createException<[string]>(\n  'E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS',\n  'Invalid transformers.js Embeddings adapter options: %s',\n  'E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS',\n  529,\n  true\n)\n\n/**\n * Thrown when the transformers.js pipeline fails to load (e.g. the `@huggingface/transformers` peer\n * is not installed) or the `feature-extraction` call throws/returns a malformed result. Non-fatal.\n * Printf arg: `[detail]`.\n */\nexport const E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR = createException<[string]>(\n  'E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR',\n  'transformers.js Embeddings engine error: %s',\n  'E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR',\n  502,\n  false\n)\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAkBA,IAAa,+CAA+C,mBAAA,gBAC1D,gDACA,0DACA,gDACA,KACA,IACF;;;;;;AAOA,IAAa,4CAA4C,mBAAA,gBACvD,6CACA,+CACA,6CACA,KACA,KACF"}

package/batteries/embeddings/transformers_js/exceptions.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Battery-scoped exception constructors for the transformers.js Embeddings adapter.
+ *
+ * @module @nhtio/adk/batteries/embeddings/transformers_js/exceptions
+ *
+ * @remarks
+ * Battery-scoped exception classes for the transformers.js (`@huggingface/transformers`) Embeddings
+ * adapter, minted via `createException` from `@nhtio/adk/factories`. Categories mirror the OpenAI and
+ * WebLLM embeddings batteries one-to-one — only the engine-specific failure differs.
+ */
+/**
+ * Thrown when the resolved adapter options fail validation against
+ * `transformersJsEmbeddingsOptionsSchema` — e.g. a missing/empty `model` or an unknown option key.
+ * Fatal: config bugs fail loud, not at embed time.
+ */
+export declare const E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS: import("../../../factories").CreatedException<[
+    string
+]>;
+/**
+ * Thrown when the transformers.js pipeline fails to load (e.g. the `@huggingface/transformers` peer
+ * is not installed) or the `feature-extraction` call throws/returns a malformed result. Non-fatal.
+ * Printf arg: `[detail]`.
+ */
+export declare const E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR: import("../../../factories").CreatedException<[
+    string
+]>;

package/batteries/embeddings/transformers_js/exceptions.mjs

@@ -0,0 +1,29 @@
+import { t as createException } from "../../../exceptions-DgmgW0MU.mjs";
+import "../../../factories.mjs";
+//#region src/batteries/embeddings/transformers_js/exceptions.ts
+/**
+* Battery-scoped exception constructors for the transformers.js Embeddings adapter.
+*
+* @module @nhtio/adk/batteries/embeddings/transformers_js/exceptions
+*
+* @remarks
+* Battery-scoped exception classes for the transformers.js (`@huggingface/transformers`) Embeddings
+* adapter, minted via `createException` from `@nhtio/adk/factories`. Categories mirror the OpenAI and
+* WebLLM embeddings batteries one-to-one — only the engine-specific failure differs.
+*/
+/**
+* Thrown when the resolved adapter options fail validation against
+* `transformersJsEmbeddingsOptionsSchema` — e.g. a missing/empty `model` or an unknown option key.
+* Fatal: config bugs fail loud, not at embed time.
+*/
+var E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS = createException("E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS", "Invalid transformers.js Embeddings adapter options: %s", "E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS", 529, true);
+/**
+* Thrown when the transformers.js pipeline fails to load (e.g. the `@huggingface/transformers` peer
+* is not installed) or the `feature-extraction` call throws/returns a malformed result. Non-fatal.
+* Printf arg: `[detail]`.
+*/
+var E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR = createException("E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR", "transformers.js Embeddings engine error: %s", "E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR", 502, false);
+//#endregion
+export { E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS, E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR };
+
+//# sourceMappingURL=exceptions.mjs.map

package/batteries/embeddings/transformers_js/exceptions.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.mjs","names":[],"sources":["../../../../src/batteries/embeddings/transformers_js/exceptions.ts"],"sourcesContent":["/**\n * Battery-scoped exception constructors for the transformers.js Embeddings adapter.\n *\n * @module @nhtio/adk/batteries/embeddings/transformers_js/exceptions\n *\n * @remarks\n * Battery-scoped exception classes for the transformers.js (`@huggingface/transformers`) Embeddings\n * adapter, minted via `createException` from `@nhtio/adk/factories`. Categories mirror the OpenAI and\n * WebLLM embeddings batteries one-to-one — only the engine-specific failure differs.\n */\n\nimport { createException } from '@nhtio/adk/factories'\n\n/**\n * Thrown when the resolved adapter options fail validation against\n * `transformersJsEmbeddingsOptionsSchema` — e.g. a missing/empty `model` or an unknown option key.\n * Fatal: config bugs fail loud, not at embed time.\n */\nexport const E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS = createException<[string]>(\n  'E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS',\n  'Invalid transformers.js Embeddings adapter options: %s',\n  'E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS',\n  529,\n  true\n)\n\n/**\n * Thrown when the transformers.js pipeline fails to load (e.g. the `@huggingface/transformers` peer\n * is not installed) or the `feature-extraction` call throws/returns a malformed result. Non-fatal.\n * Printf arg: `[detail]`.\n */\nexport const E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR = createException<[string]>(\n  'E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR',\n  'transformers.js Embeddings engine error: %s',\n  'E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR',\n  502,\n  false\n)\n"],"mappings":";;;;;;;;;;;;;;;;;;AAkBA,IAAa,+CAA+C,gBAC1D,gDACA,0DACA,gDACA,KACA,IACF;;;;;;AAOA,IAAa,4CAA4C,gBACvD,6CACA,+CACA,6CACA,KACA,KACF"}

package/batteries/embeddings/transformers_js/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * transformers.js Embeddings adapter battery — dual-environment ONNX feature-extraction.
+ *
+ * @module @nhtio/adk/batteries/embeddings/transformers_js
+ *
+ * @remarks
+ * Environment-neutral (Node + browser, ONNX Runtime auto-selected) — so, unlike the WebLLM embeddings
+ * battery, it IS re-exported from the environment-neutral `@nhtio/adk/batteries/embeddings` barrel.
+ * Re-exports the adapter class, the validation schema + `validateOptions` wrapper, every option /
+ * pipeline type alias (including the shared base shapes re-exported from the OpenAI battery), and the
+ * battery-scoped exceptions.
+ */
+export { TransformersJsEmbeddingsAdapter } from "./adapter";
+export { transformersJsEmbeddingsOptionsSchema, validateOptions } from "./validation";
+export { poolAndNormalize, defaultPoolAndNormalize, l2Normalize } from "./pooling";
+export type { TokenStates3D, Pooled2D } from "./pooling";
+export type { EmbeddingKind, EmbedOptions, BaseEmbeddingsAdapterOptions, TransformersJsEmbeddingsAdapterOptions, TransformersJsEmbeddingsPipeline, TransformersJsEmbeddingsDataType, TransformersJsEmbeddingsDeviceType, TransformersJsEmbeddingsProgressCallback, TransformersJsPooling, TransformersJsPoolingOwner, TransformersJsEmbeddingsModelSource, CreateTransformersJsEmbeddingsPipeline, BatteryLifecyclePhase, BatteryLifecycleBattery, BatteryLifecycleReport, BatteryLifecycleCallback, BatteryLifecycleHooks, } from "./types";
+export { E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS, E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR, } from "./exceptions";

package/batteries/embeddings/transformers_js/pooling.cjs

@@ -0,0 +1,67 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../chunk-Cek0wNdY.js");
+//#region src/batteries/embeddings/transformers_js/pooling.ts
+/**
+* Mean-pool a `[seq, hidden]` matrix into a `[hidden]` vector.
+*
+* @param rows - The per-token hidden-state rows.
+*/
+var meanPool = (rows) => {
+	const seq = rows.length;
+	if (seq === 0) return [];
+	const hidden = rows[0].length;
+	const out = new Array(hidden).fill(0);
+	for (const row of rows) for (let h = 0; h < hidden; h++) out[h] += row[h];
+	for (let h = 0; h < hidden; h++) out[h] /= seq;
+	return out;
+};
+/**
+* L2-normalize a vector in place-safe fashion (returns a new array). A zero vector is returned
+* unchanged (no divide-by-zero).
+*
+* @param vec - The vector to normalize.
+*/
+var l2Normalize = (vec) => {
+	let sumSq = 0;
+	for (const v of vec) sumSq += v * v;
+	const norm = Math.sqrt(sumSq);
+	if (norm === 0) return vec.slice();
+	return vec.map((v) => v / norm);
+};
+/**
+* Pool a single `[seq, hidden]` matrix into one `[hidden]` vector per the strategy.
+*
+* @param rows - The per-token hidden-state rows for one input.
+* @param pooling - The pooling strategy.
+*/
+var poolOne = (rows, pooling) => {
+	switch (pooling) {
+		case "cls":
+		case "first_token": return (rows[0] ?? []).slice();
+		case "eos":
+		case "last_token": return (rows[rows.length - 1] ?? []).slice();
+		case "none": return meanPool(rows);
+		default: return meanPool(rows);
+	}
+};
+/**
+* Pool raw `[batch, seq, hidden]` token states into `[batch, hidden]` vectors and optionally
+* L2-normalize — the deterministic battery-owned path (`poolingOwner: 'battery'`).
+*
+* @param tokenStates - The `[batch, seq, hidden]` raw states from `pooling:'none'`.
+* @param pooling - The pooling strategy (`'mean'` default).
+* @param normalize - Whether to L2-normalize each pooled vector (default `true`).
+* @returns One pooled (and optionally normalized) vector per batch row.
+*/
+var poolAndNormalize = (tokenStates, pooling, normalize) => tokenStates.map((rows) => {
+	const pooled = poolOne(rows, pooling);
+	return normalize ? l2Normalize(pooled) : pooled;
+});
+/** Default {@link poolAndNormalize}. */
+var defaultPoolAndNormalize = poolAndNormalize;
+//#endregion
+exports.defaultPoolAndNormalize = defaultPoolAndNormalize;
+exports.l2Normalize = l2Normalize;
+exports.poolAndNormalize = poolAndNormalize;
+
+//# sourceMappingURL=pooling.cjs.map

package/batteries/embeddings/transformers_js/pooling.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pooling.cjs","names":[],"sources":["../../../../src/batteries/embeddings/transformers_js/pooling.ts"],"sourcesContent":["/**\n * Deterministic, battery-owned pooling + L2-normalization for the transformers.js embeddings battery.\n *\n * @module @nhtio/adk/batteries/embeddings/transformers_js/pooling\n *\n * @remarks\n * Used when `poolingOwner: 'battery'`. The pipeline is asked for raw `pooling:'none'` token states —\n * a `[batch, seq, hidden]` tensor — and this module pools them into one vector per input in pure JS,\n * identically across Node and the browser. That removes the per-runtime post-processing variance that\n * widens the node↔browser cosine gap; only the irreducible ONNX-Runtime kernel floor remains.\n *\n * Pooling strategies mirror the transformers.js feature-extraction options:\n * - `mean` — attention-unaware mean over the sequence axis (matches the pipeline's `'mean'`, which\n *   also means over all positions for a single ungrouped sequence).\n * - `cls` / `first_token` — the first token's hidden state.\n * - `eos` / `last_token` — the last token's hidden state.\n * - `none` — no pooling (caller already has the vector); returned unchanged per row.\n */\n\n/** A 3-D `[batch, seq, hidden]` nested array (raw token states from `pooling:'none'`). */\nexport type TokenStates3D = number[][][]\n/** A 2-D `[batch, hidden]` nested array (already-pooled vectors). */\nexport type Pooled2D = number[][]\n\n/**\n * Mean-pool a `[seq, hidden]` matrix into a `[hidden]` vector.\n *\n * @param rows - The per-token hidden-state rows.\n */\nconst meanPool = (rows: number[][]): number[] => {\n  const seq = rows.length\n  if (seq === 0) return []\n  const hidden = rows[0].length\n  const out = new Array<number>(hidden).fill(0)\n  for (const row of rows) {\n    for (let h = 0; h < hidden; h++) out[h] += row[h]\n  }\n  for (let h = 0; h < hidden; h++) out[h] /= seq\n  return out\n}\n\n/**\n * L2-normalize a vector in place-safe fashion (returns a new array). A zero vector is returned\n * unchanged (no divide-by-zero).\n *\n * @param vec - The vector to normalize.\n */\nexport const l2Normalize = (vec: number[]): number[] => {\n  let sumSq = 0\n  for (const v of vec) sumSq += v * v\n  const norm = Math.sqrt(sumSq)\n  if (norm === 0) return vec.slice()\n  return vec.map((v) => v / norm)\n}\n\n/**\n * Pool a single `[seq, hidden]` matrix into one `[hidden]` vector per the strategy.\n *\n * @param rows - The per-token hidden-state rows for one input.\n * @param pooling - The pooling strategy.\n */\nconst poolOne = (rows: number[][], pooling: string): number[] => {\n  switch (pooling) {\n    case 'cls':\n    case 'first_token':\n      return (rows[0] ?? []).slice()\n    case 'eos':\n    case 'last_token':\n      return (rows[rows.length - 1] ?? []).slice()\n    case 'none':\n      // No pooling requested but we have token states — fall back to mean so a vector still results.\n      return meanPool(rows)\n    case 'mean':\n    default:\n      return meanPool(rows)\n  }\n}\n\n/**\n * Pool raw `[batch, seq, hidden]` token states into `[batch, hidden]` vectors and optionally\n * L2-normalize — the deterministic battery-owned path (`poolingOwner: 'battery'`).\n *\n * @param tokenStates - The `[batch, seq, hidden]` raw states from `pooling:'none'`.\n * @param pooling - The pooling strategy (`'mean'` default).\n * @param normalize - Whether to L2-normalize each pooled vector (default `true`).\n * @returns One pooled (and optionally normalized) vector per batch row.\n */\nexport const poolAndNormalize = (\n  tokenStates: TokenStates3D,\n  pooling: string,\n  normalize: boolean\n): Pooled2D =>\n  tokenStates.map((rows) => {\n    const pooled = poolOne(rows, pooling)\n    return normalize ? l2Normalize(pooled) : pooled\n  })\n\n/** Default {@link poolAndNormalize}. */\nexport const defaultPoolAndNormalize = poolAndNormalize\n"],"mappings":";;;;;;;;AA6BA,IAAM,YAAY,SAA+B;CAC/C,MAAM,MAAM,KAAK;CACjB,IAAI,QAAQ,GAAG,OAAO,CAAC;CACvB,MAAM,SAAS,KAAK,GAAG;CACvB,MAAM,MAAM,IAAI,MAAc,MAAM,EAAE,KAAK,CAAC;CAC5C,KAAK,MAAM,OAAO,MAChB,KAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,KAAK,IAAI,MAAM,IAAI;CAEjD,KAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,KAAK,IAAI,MAAM;CAC3C,OAAO;AACT;;;;;;;AAQA,IAAa,eAAe,QAA4B;CACtD,IAAI,QAAQ;CACZ,KAAK,MAAM,KAAK,KAAK,SAAS,IAAI;CAClC,MAAM,OAAO,KAAK,KAAK,KAAK;CAC5B,IAAI,SAAS,GAAG,OAAO,IAAI,MAAM;CACjC,OAAO,IAAI,KAAK,MAAM,IAAI,IAAI;AAChC;;;;;;;AAQA,IAAM,WAAW,MAAkB,YAA8B;CAC/D,QAAQ,SAAR;EACE,KAAK;EACL,KAAK,eACH,QAAQ,KAAK,MAAM,CAAC,GAAG,MAAM;EAC/B,KAAK;EACL,KAAK,cACH,QAAQ,KAAK,KAAK,SAAS,MAAM,CAAC,GAAG,MAAM;EAC7C,KAAK,QAEH,OAAO,SAAS,IAAI;EAEtB,SACE,OAAO,SAAS,IAAI;CACxB;AACF;;;;;;;;;;AAWA,IAAa,oBACX,aACA,SACA,cAEA,YAAY,KAAK,SAAS;CACxB,MAAM,SAAS,QAAQ,MAAM,OAAO;CACpC,OAAO,YAAY,YAAY,MAAM,IAAI;AAC3C,CAAC;;AAGH,IAAa,0BAA0B"}

package/batteries/embeddings/transformers_js/pooling.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Deterministic, battery-owned pooling + L2-normalization for the transformers.js embeddings battery.
+ *
+ * @module @nhtio/adk/batteries/embeddings/transformers_js/pooling
+ *
+ * @remarks
+ * Used when `poolingOwner: 'battery'`. The pipeline is asked for raw `pooling:'none'` token states —
+ * a `[batch, seq, hidden]` tensor — and this module pools them into one vector per input in pure JS,
+ * identically across Node and the browser. That removes the per-runtime post-processing variance that
+ * widens the node↔browser cosine gap; only the irreducible ONNX-Runtime kernel floor remains.
+ *
+ * Pooling strategies mirror the transformers.js feature-extraction options:
+ * - `mean` — attention-unaware mean over the sequence axis (matches the pipeline's `'mean'`, which
+ *   also means over all positions for a single ungrouped sequence).
+ * - `cls` / `first_token` — the first token's hidden state.
+ * - `eos` / `last_token` — the last token's hidden state.
+ * - `none` — no pooling (caller already has the vector); returned unchanged per row.
+ */
+/** A 3-D `[batch, seq, hidden]` nested array (raw token states from `pooling:'none'`). */
+export type TokenStates3D = number[][][];
+/** A 2-D `[batch, hidden]` nested array (already-pooled vectors). */
+export type Pooled2D = number[][];
+/**
+ * L2-normalize a vector in place-safe fashion (returns a new array). A zero vector is returned
+ * unchanged (no divide-by-zero).
+ *
+ * @param vec - The vector to normalize.
+ */
+export declare const l2Normalize: (vec: number[]) => number[];
+/**
+ * Pool raw `[batch, seq, hidden]` token states into `[batch, hidden]` vectors and optionally
+ * L2-normalize — the deterministic battery-owned path (`poolingOwner: 'battery'`).
+ *
+ * @param tokenStates - The `[batch, seq, hidden]` raw states from `pooling:'none'`.
+ * @param pooling - The pooling strategy (`'mean'` default).
+ * @param normalize - Whether to L2-normalize each pooled vector (default `true`).
+ * @returns One pooled (and optionally normalized) vector per batch row.
+ */
+export declare const poolAndNormalize: (tokenStates: TokenStates3D, pooling: string, normalize: boolean) => Pooled2D;
+/** Default {@link poolAndNormalize}. */
+export declare const defaultPoolAndNormalize: (tokenStates: TokenStates3D, pooling: string, normalize: boolean) => Pooled2D;

package/batteries/embeddings/transformers_js/pooling.mjs

@@ -0,0 +1,63 @@
+//#region src/batteries/embeddings/transformers_js/pooling.ts
+/**
+* Mean-pool a `[seq, hidden]` matrix into a `[hidden]` vector.
+*
+* @param rows - The per-token hidden-state rows.
+*/
+var meanPool = (rows) => {
+	const seq = rows.length;
+	if (seq === 0) return [];
+	const hidden = rows[0].length;
+	const out = new Array(hidden).fill(0);
+	for (const row of rows) for (let h = 0; h < hidden; h++) out[h] += row[h];
+	for (let h = 0; h < hidden; h++) out[h] /= seq;
+	return out;
+};
+/**
+* L2-normalize a vector in place-safe fashion (returns a new array). A zero vector is returned
+* unchanged (no divide-by-zero).
+*
+* @param vec - The vector to normalize.
+*/
+var l2Normalize = (vec) => {
+	let sumSq = 0;
+	for (const v of vec) sumSq += v * v;
+	const norm = Math.sqrt(sumSq);
+	if (norm === 0) return vec.slice();
+	return vec.map((v) => v / norm);
+};
+/**
+* Pool a single `[seq, hidden]` matrix into one `[hidden]` vector per the strategy.
+*
+* @param rows - The per-token hidden-state rows for one input.
+* @param pooling - The pooling strategy.
+*/
+var poolOne = (rows, pooling) => {
+	switch (pooling) {
+		case "cls":
+		case "first_token": return (rows[0] ?? []).slice();
+		case "eos":
+		case "last_token": return (rows[rows.length - 1] ?? []).slice();
+		case "none": return meanPool(rows);
+		default: return meanPool(rows);
+	}
+};
+/**
+* Pool raw `[batch, seq, hidden]` token states into `[batch, hidden]` vectors and optionally
+* L2-normalize — the deterministic battery-owned path (`poolingOwner: 'battery'`).
+*
+* @param tokenStates - The `[batch, seq, hidden]` raw states from `pooling:'none'`.
+* @param pooling - The pooling strategy (`'mean'` default).
+* @param normalize - Whether to L2-normalize each pooled vector (default `true`).
+* @returns One pooled (and optionally normalized) vector per batch row.
+*/
+var poolAndNormalize = (tokenStates, pooling, normalize) => tokenStates.map((rows) => {
+	const pooled = poolOne(rows, pooling);
+	return normalize ? l2Normalize(pooled) : pooled;
+});
+/** Default {@link poolAndNormalize}. */
+var defaultPoolAndNormalize = poolAndNormalize;
+//#endregion
+export { defaultPoolAndNormalize, l2Normalize, poolAndNormalize };
+
+//# sourceMappingURL=pooling.mjs.map

package/batteries/embeddings/transformers_js/pooling.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pooling.mjs","names":[],"sources":["../../../../src/batteries/embeddings/transformers_js/pooling.ts"],"sourcesContent":["/**\n * Deterministic, battery-owned pooling + L2-normalization for the transformers.js embeddings battery.\n *\n * @module @nhtio/adk/batteries/embeddings/transformers_js/pooling\n *\n * @remarks\n * Used when `poolingOwner: 'battery'`. The pipeline is asked for raw `pooling:'none'` token states —\n * a `[batch, seq, hidden]` tensor — and this module pools them into one vector per input in pure JS,\n * identically across Node and the browser. That removes the per-runtime post-processing variance that\n * widens the node↔browser cosine gap; only the irreducible ONNX-Runtime kernel floor remains.\n *\n * Pooling strategies mirror the transformers.js feature-extraction options:\n * - `mean` — attention-unaware mean over the sequence axis (matches the pipeline's `'mean'`, which\n *   also means over all positions for a single ungrouped sequence).\n * - `cls` / `first_token` — the first token's hidden state.\n * - `eos` / `last_token` — the last token's hidden state.\n * - `none` — no pooling (caller already has the vector); returned unchanged per row.\n */\n\n/** A 3-D `[batch, seq, hidden]` nested array (raw token states from `pooling:'none'`). */\nexport type TokenStates3D = number[][][]\n/** A 2-D `[batch, hidden]` nested array (already-pooled vectors). */\nexport type Pooled2D = number[][]\n\n/**\n * Mean-pool a `[seq, hidden]` matrix into a `[hidden]` vector.\n *\n * @param rows - The per-token hidden-state rows.\n */\nconst meanPool = (rows: number[][]): number[] => {\n  const seq = rows.length\n  if (seq === 0) return []\n  const hidden = rows[0].length\n  const out = new Array<number>(hidden).fill(0)\n  for (const row of rows) {\n    for (let h = 0; h < hidden; h++) out[h] += row[h]\n  }\n  for (let h = 0; h < hidden; h++) out[h] /= seq\n  return out\n}\n\n/**\n * L2-normalize a vector in place-safe fashion (returns a new array). A zero vector is returned\n * unchanged (no divide-by-zero).\n *\n * @param vec - The vector to normalize.\n */\nexport const l2Normalize = (vec: number[]): number[] => {\n  let sumSq = 0\n  for (const v of vec) sumSq += v * v\n  const norm = Math.sqrt(sumSq)\n  if (norm === 0) return vec.slice()\n  return vec.map((v) => v / norm)\n}\n\n/**\n * Pool a single `[seq, hidden]` matrix into one `[hidden]` vector per the strategy.\n *\n * @param rows - The per-token hidden-state rows for one input.\n * @param pooling - The pooling strategy.\n */\nconst poolOne = (rows: number[][], pooling: string): number[] => {\n  switch (pooling) {\n    case 'cls':\n    case 'first_token':\n      return (rows[0] ?? []).slice()\n    case 'eos':\n    case 'last_token':\n      return (rows[rows.length - 1] ?? []).slice()\n    case 'none':\n      // No pooling requested but we have token states — fall back to mean so a vector still results.\n      return meanPool(rows)\n    case 'mean':\n    default:\n      return meanPool(rows)\n  }\n}\n\n/**\n * Pool raw `[batch, seq, hidden]` token states into `[batch, hidden]` vectors and optionally\n * L2-normalize — the deterministic battery-owned path (`poolingOwner: 'battery'`).\n *\n * @param tokenStates - The `[batch, seq, hidden]` raw states from `pooling:'none'`.\n * @param pooling - The pooling strategy (`'mean'` default).\n * @param normalize - Whether to L2-normalize each pooled vector (default `true`).\n * @returns One pooled (and optionally normalized) vector per batch row.\n */\nexport const poolAndNormalize = (\n  tokenStates: TokenStates3D,\n  pooling: string,\n  normalize: boolean\n): Pooled2D =>\n  tokenStates.map((rows) => {\n    const pooled = poolOne(rows, pooling)\n    return normalize ? l2Normalize(pooled) : pooled\n  })\n\n/** Default {@link poolAndNormalize}. */\nexport const defaultPoolAndNormalize = poolAndNormalize\n"],"mappings":";;;;;;AA6BA,IAAM,YAAY,SAA+B;CAC/C,MAAM,MAAM,KAAK;CACjB,IAAI,QAAQ,GAAG,OAAO,CAAC;CACvB,MAAM,SAAS,KAAK,GAAG;CACvB,MAAM,MAAM,IAAI,MAAc,MAAM,EAAE,KAAK,CAAC;CAC5C,KAAK,MAAM,OAAO,MAChB,KAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,KAAK,IAAI,MAAM,IAAI;CAEjD,KAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,KAAK,IAAI,MAAM;CAC3C,OAAO;AACT;;;;;;;AAQA,IAAa,eAAe,QAA4B;CACtD,IAAI,QAAQ;CACZ,KAAK,MAAM,KAAK,KAAK,SAAS,IAAI;CAClC,MAAM,OAAO,KAAK,KAAK,KAAK;CAC5B,IAAI,SAAS,GAAG,OAAO,IAAI,MAAM;CACjC,OAAO,IAAI,KAAK,MAAM,IAAI,IAAI;AAChC;;;;;;;AAQA,IAAM,WAAW,MAAkB,YAA8B;CAC/D,QAAQ,SAAR;EACE,KAAK;EACL,KAAK,eACH,QAAQ,KAAK,MAAM,CAAC,GAAG,MAAM;EAC/B,KAAK;EACL,KAAK,cACH,QAAQ,KAAK,KAAK,SAAS,MAAM,CAAC,GAAG,MAAM;EAC7C,KAAK,QAEH,OAAO,SAAS,IAAI;EAEtB,SACE,OAAO,SAAS,IAAI;CACxB;AACF;;;;;;;;;;AAWA,IAAa,oBACX,aACA,SACA,cAEA,YAAY,KAAK,SAAS;CACxB,MAAM,SAAS,QAAQ,MAAM,OAAO;CACpC,OAAO,YAAY,YAAY,MAAM,IAAI;AAC3C,CAAC;;AAGH,IAAa,0BAA0B"}

package/batteries/embeddings/transformers_js/types.cjs

@@ -0,0 +1,2 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../chunk-Cek0wNdY.js");