@nhtio/adk 1.20260625.1 → 1.20260626.0

package/CHANGELOG.md

@@ -15,6 +15,73 @@ you *when* you got it, not *what changed*: a `^` range will float across battery
 breaking changes, so pin an exact version if you need stability and read the entry before
 upgrading.
 
+## 2026-06-26
+
+### Added
+
+- **Portable generation vocabulary shared by the two text-out on-device batteries** (`transformers_js`,
+  `litert_lm`). Both now accept one canonical {@link ChatGenerationOptions} surface — `maxTokens`, `sampler`
+  (`'greedy'`|`'top-k'`|`'top-p'`), `temperature`, `topK`, `topP`, `seed`, `enableThinking`,
+  `multimodal: { image, audio }` — and each adapter maps it onto its own runtime API. Precedence is
+  **canonical-wins**: the canonical field is honored and the battery's native field (transformers.js
+  `maxNewTokens`, LiteRT `maxOutputTokens` / `samplerParams`) is the fallback consulted only when the canonical
+  one is absent, so existing native-field config keeps working. Defaults are identical across both batteries
+  and chosen for reproducibility (`sampler: 'greedy'`, `enableThinking: false` — many reasoning templates
+  default thinking *on* and burn the token budget before the answer; this turns it off unless asked).
+- **Normalized lifecycle hook surface across all on-device batteries** (`transformers_js`, `litert_lm`,
+  `webllm_chat_completions`, and the transformers.js embeddings battery). A new opt-in {@link BatteryLifecycleHooks}
+  block: an `onLifecycle` firehose plus per-phase hooks `onLoading` → `onCompiling` → `onReady` →
+  `onGenerating` → `onComplete` (or `onError`), each handed a normalized `BatteryLifecycleReport`
+  (`{ phase, battery, model, at, detail?, progress?, raw?, error? }`). `progress` is normalized to `0..1`
+  during `loading` when the provider reports it; the `compiling` phase marks the WebGPU/wasm shader/graph
+  build between download and first token — often the slowest part of a cold start, and previously invisible.
+  Purely additive — omit the hooks and behavior is byte-for-byte unchanged; a throwing consumer hook can never
+  abort a load or a turn. The existing per-provider `onInitProgress` is untouched.
+- **Multimodal INPUT for the transformers.js battery.** Image and audio flow through the model's processor
+  (called positionally, `_call(text, images, audio)`); a multimodal model genuinely perceives them. For the
+  common audio case — uncompressed PCM WAV — the battery decodes the RIFF itself with a `DataView`,
+  dependency-free and **env-neutral**, *before* importing the heavy peer (transformers.js's own `read_audio`
+  needs the Web Audio API's `AudioContext`, which does not exist in Node; compressed containers still fall
+  back to it, browser-only). Enable per kind via the canonical `multimodal: { image, audio }`.
+- **Opt-in media-OUTPUT seam (`extractMediaOutputs`) on the `transformers_js` and `litert_lm` batteries.**
+  Default absent → text-out, byte-for-byte unchanged. Supply the hook and a wrapped media-emitting model's
+  generated audio/image is persisted via `ctx.storeMediaBytes`, wrapped as a first-party `Media.toolGenerated(...)`,
+  and surfaced as an assistant `Message.attachments` entry (a media-only turn — empty text + attachment — is
+  legitimate). The batteries remain multimodal-in / text-out by default; this is for an LLM turn that produces
+  media alongside or instead of text.
+- **`'phi'` tool-call parser** added to the shared parser layer's `toolCallParser` set and the `'auto'`
+  priority order (`hermes → gemma → gpt_oss → phi → pythonic → llama3_json → mistral → qwen3_coder`). Anchored
+  on the literal `functools` token (verified against vLLM's `phi4_mini_json` parser), so it runs with the
+  other marker-anchored families ahead of the weak-signal JSON/pythonic forms.
+- **`EmbeddingGemma 300M`** (`onnx-community/embeddinggemma-300m-ONNX`) verified through the
+  `transformers_js` embeddings battery — 768-dim, unit-norm, deterministic — alongside the existing
+  MiniLM / BGE-small / Arctic-S entries.
+- **The real-model test matrix** (`tests/_fixtures/model_matrix.ts`, gated on `TEST_MODEL_MATRIX=1`): loads
+  each real ONNX / `.litertlm` model, drives one dispatch turn, and asserts the expected parser family or
+  multimodal grounding is extracted — because a small model may not emit the format its chat template implies
+  (Gemma 4 E2B emits the decoder-stripped `call:NAME{k:v}`, not the template's `<|tool_call>…`). A Node half
+  (`pnpm run test:matrix`) and a headed-WebGPU browser half (`pnpm run test:matrix:browser`, local-only — CI
+  runners have no GPU). `bin/capture_tool_outputs.ts` (`pnpm run capture:tools`) captures real raw output from
+  hosted big-only families (`qwen3_coder`, `gpt_oss`, `mistral`) via any OpenAI-compatible proxy into committed
+  parser fixtures — configured with `--base-url`/`--api-key` or the generic `CAPTURE_BASE_URL` /
+  `CAPTURE_API_KEY` env vars; never run in CI.
+- **Documentation: a dedicated "LLM Batteries" section** under Featured Batteries — an overview hub, a
+  "Shared Contract" page (the three `chat_common` pillars: parser layer, portable generation vocabulary,
+  lifecycle hooks), and a reference page per battery (OpenAI, Ollama, WebLLM, LiteRT-LM, Transformers.js) each
+  carrying a tested-model table grounded in the matrix. Plus a showcase, "Building the On-Device Batteries,"
+  documenting the parser archaeology, the false-green fixtures, and the one wall we could not engineer around:
+  **LiteRT-LM in the browser runs Gemma and only Gemma**, proven at the file-format level
+  (`tf_lite_prefill_decode` vs `tf_lite_artisan_text_decoder`) — converting a non-Gemma model to a
+  browser-runnable `.litertlm` is a dead end with the public toolchain. The dead `convert_model` / `deploy_model`
+  scripts (which described a fictional CLI) were removed and the conversion doc rewritten as "The Real-Model
+  Matrix." Docs are bundled in the npm package and served by the ADK Assembly MCP, so this ships with the release.
+
+### Changed
+
+- **`bin/capture_tool_outputs.ts` now reads its proxy URL/key from `CAPTURE_BASE_URL` / `CAPTURE_API_KEY`**
+  (or the existing `--base-url` / `--api-key` flags), replacing internal-specific env-var names. Dev tool only;
+  not part of the published runtime surface.
+
 ## 2026-06-25
 
 ### Added

package/batteries/embeddings/openai/adapter.cjs

@@ -1,6 +1,6 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../../chunk-Cek0wNdY.js");
-const require_tool_registry = require("../../../tool_registry-CIIfbY_w.js");
+const require_tool_registry = require("../../../tool_registry-DbS8Pem9.js");
 require("../../../guards.cjs");
 const require_lib_utils_retry = require("../../../lib/utils/retry.cjs");
 const require_batteries_embeddings_openai_exceptions = require("./exceptions.cjs");

package/batteries/embeddings/openai/adapter.mjs

@@ -1,4 +1,4 @@
-import { c as isError } from "../../../tool_registry-FeMMz993.mjs";
+import { c as isError } from "../../../tool_registry-Bj0JhXCv.mjs";
 import "../../../guards.mjs";
 import { computeBackoff, parseRetryAfter, sleepWithJitter } from "../../../lib/utils/retry.mjs";
 import { E_OPENAI_EMBEDDINGS_HTTP_ERROR, E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE, E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT } from "./exceptions.mjs";

package/batteries/embeddings/transformers_js/adapter.cjs

@@ -1,8 +1,11 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../../chunk-Cek0wNdY.js");
-const require_tool_registry = require("../../../tool_registry-CIIfbY_w.js");
+const require_tool_registry = require("../../../tool_registry-DbS8Pem9.js");
 require("../../../guards.cjs");
+const require_lifecycle = require("../../../lifecycle-vYQJ2rmf.js");
+const require_batteries_llm_transformers_js_model_source = require("../../llm/transformers_js/model_source.cjs");
 const require_batteries_embeddings_openai_helpers = require("../openai/helpers.cjs");
+const require_batteries_embeddings_transformers_js_pooling = require("./pooling.cjs");
 const require_batteries_embeddings_transformers_js_exceptions = require("./exceptions.cjs");
 const require_batteries_embeddings_transformers_js_validation = require("./validation.cjs");
 //#region src/batteries/embeddings/transformers_js/adapter.ts
@@ -27,13 +30,16 @@ const require_batteries_embeddings_transformers_js_validation = require("./valid
 * 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 defaultCreatePipeline = async ({ model, device, dtype, onInitProgress }) => {
-	const { pipeline } = await import("@huggingface/transformers");
-	return await pipeline("feature-extraction", model, {
-		...device ? { device } : {},
-		...dtype ? { dtype } : {},
-		...onInitProgress ? { progress_callback: onInitProgress } : {}
-	});
+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 ? require_batteries_llm_transformers_js_model_source.withModelSource(env, modelSource, load) : load();
+	};
 };
 /**
 * Embeddings adapter for transformers.js's feature-extraction pipeline.
@@ -79,22 +85,50 @@ var TransformersJsEmbeddingsAdapter = class TransformersJsEmbeddingsAdapter {
 		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 require_batteries_embeddings_transformers_js_exceptions.E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS(["the transformers.js embeddings battery is not available in this runtime"]);
+		const opts = this.#options;
 		this.#pipelinePromise ??= (async () => {
-			const createPipeline = this.#options.createPipeline ?? defaultCreatePipeline;
+			require_lifecycle.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;
+				require_lifecycle.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 {
+				require_lifecycle.emitLifecycle(opts, "transformers_js_embed", opts.model, "compiling", { detail: "compiling feature-extraction graph" });
 				const pipe = await createPipeline({
-					model: this.#options.model,
-					device: this.#options.device,
-					dtype: this.#options.dtype,
-					onInitProgress: this.#options.onInitProgress
+					model: opts.model,
+					device: opts.device,
+					dtype: opts.dtype,
+					onInitProgress: forwardedInitProgress
 				});
 				this.#pipeline = pipe;
+				require_lifecycle.emitLifecycle(opts, "transformers_js_embed", opts.model, "ready", { detail: "feature-extraction pipeline ready" });
 				return pipe;
 			} catch (err) {
 				this.#pipelinePromise = void 0;
+				require_lifecycle.emitLifecycle(opts, "transformers_js_embed", opts.model, "error", { error: err });
 				throw new require_batteries_embeddings_transformers_js_exceptions.E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR([`could not load the transformers.js pipeline: ${require_tool_registry.isError(err) ? err.message : String(err)} — install the peer dependency (pnpm add @huggingface/transformers)`]);
 			}
 		})();
@@ -124,19 +158,32 @@ var TransformersJsEmbeddingsAdapter = class TransformersJsEmbeddingsAdapter {
 		if (texts.length === 0) return [];
 		const input = require_batteries_embeddings_openai_helpers.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";
+		require_lifecycle.emitLifecycle(this.#options, "transformers_js_embed", this.#options.model, "generating");
 		let tensor;
 		try {
-			tensor = await pipe(input, {
-				pooling: this.#options.pooling ?? "mean",
-				normalize: this.#options.normalize ?? true
+			tensor = await pipe(input, battery ? { pooling: "none" } : {
+				pooling,
+				normalize
 			});
 		} catch (err) {
+			require_lifecycle.emitLifecycle(this.#options, "transformers_js_embed", this.#options.model, "error", { error: err });
 			throw new require_batteries_embeddings_transformers_js_exceptions.E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR([require_tool_registry.isError(err) ? err.message : String(err)]);
 		}
 		if (!tensor || typeof tensor.tolist !== "function") throw new require_batteries_embeddings_transformers_js_exceptions.E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR(["feature-extraction returned a non-Tensor result"]);
 		const list = tensor.tolist();
-		const vectors = Array.isArray(list) && Array.isArray(list[0]) ? list : [list];
-		if (vectors.length !== input.length) throw new require_batteries_embeddings_transformers_js_exceptions.E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR([`expected ${input.length} vectors, got ${vectors.length}`]);
+		let vectors;
+		if (battery) {
+			const states = list;
+			vectors = require_batteries_embeddings_transformers_js_pooling.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) {
+			require_lifecycle.emitLifecycle(this.#options, "transformers_js_embed", this.#options.model, "error", { error: /* @__PURE__ */ new Error(`expected ${input.length} vectors, got ${vectors.length}`) });
+			throw new require_batteries_embeddings_transformers_js_exceptions.E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR([`expected ${input.length} vectors, got ${vectors.length}`]);
+		}
+		require_lifecycle.emitLifecycle(this.#options, "transformers_js_embed", this.#options.model, "complete");
 		return vectors;
 	}
 };

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

@@ -1 +1 @@
-{"version":3,"file":"adapter.cjs","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 { validateOptions } from './validation'\nimport { applyEmbeddingPrefix } from '../openai/helpers'\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 defaultCreatePipeline: CreateTransformersJsEmbeddingsPipeline = async ({\n  model,\n  device,\n  dtype,\n  onInitProgress,\n}) => {\n  const { pipeline } = await import('@huggingface/transformers')\n  return (await pipeline('feature-extraction', model, {\n    ...(device ? { device } : {}),\n    ...(dtype ? { dtype } : {}),\n    ...(onInitProgress ? { progress_callback: onInitProgress } : {}),\n  } as never)) as unknown as TransformersJsEmbeddingsPipeline\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  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    this.#pipelinePromise ??= (async () => {\n      const createPipeline = this.#options.createPipeline ?? defaultCreatePipeline\n      try {\n        const pipe = await createPipeline({\n          model: this.#options.model,\n          device: this.#options.device,\n          dtype: this.#options.dtype,\n          onInitProgress: this.#options.onInitProgress,\n        })\n        this.#pipeline = pipe\n        return pipe\n      } catch (err) {\n        this.#pipelinePromise = undefined\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\n    let tensor: { tolist: () => unknown; dims?: number[] }\n    try {\n      tensor = (await (pipe as unknown as (i: unknown, o: unknown) => Promise<unknown>)(input, {\n        pooling: this.#options.pooling ?? 'mean',\n        normalize: this.#options.normalize ?? true,\n      })) as { tolist: () => unknown; dims?: number[] }\n    } catch (err) {\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    // With pooling, the Tensor is [batch, hidden] → tolist() yields number[][].\n    const list = tensor.tolist()\n    const vectors =\n      Array.isArray(list) && Array.isArray(list[0]) ? (list as number[][]) : [list as number[]]\n\n    if (vectors.length !== input.length) {\n      throw new E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR([\n        `expected ${input.length} vectors, got ${vectors.length}`,\n      ])\n    }\n    return vectors\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,IAAM,wBAAgE,OAAO,EAC3E,OACA,QACA,OACA,qBACI;CACJ,MAAM,EAAE,aAAa,MAAM,OAAO;CAClC,OAAQ,MAAM,SAAS,sBAAsB,OAAO;EAClD,GAAI,SAAS,EAAE,OAAO,IAAI,CAAC;EAC3B,GAAI,QAAQ,EAAE,MAAM,IAAI,CAAC;EACzB,GAAI,iBAAiB,EAAE,mBAAmB,eAAe,IAAI,CAAC;CAChE,CAAU;AACZ;;;;;;;;;AAUA,IAAa,kCAAb,MAAa,gCAAgC;CAC3C;CACA;CACA;;;;;CAMA,OAAc,cAAuB;EACnC,OAAO;CACT;;;;;CAMA,YAAY,SAAkB;EAC5B,KAAKA,WAAW,wDAAA,gBAAgB,OAAO;EACvC,KAAKC,YAAY,KAAKD,SAAS;CACjC;;CAGA,IAAI,aAAiC;EACnC,OAAO,KAAKA,SAAS;CACvB;;CAGA,cAAuB;EACrB,QAAQ,KAAKA,SAAS,eAAe,gCAAgC,aAAa;CACpF;;CAGA,MAAM,UAAyB;EAC7B,MAAM,KAAKE,iBAAiB;CAC9B;;CAGA,QAAc;EACZ,KAAKD,YAAY,KAAA;EACjB,KAAKE,mBAAmB,KAAA;CAC1B;CAEA,MAAMD,mBAA8D;EAClE,IAAI,KAAKD,WAAW,OAAO,KAAKA;EAChC,IAAI,CAAC,KAAK,YAAY,GACpB,MAAM,IAAI,wDAAA,6CAA6C,CACrD,yEACF,CAAC;EAEH,KAAKE,sBAAsB,YAAY;GACrC,MAAM,iBAAiB,KAAKH,SAAS,kBAAkB;GACvD,IAAI;IACF,MAAM,OAAO,MAAM,eAAe;KAChC,OAAO,KAAKA,SAAS;KACrB,QAAQ,KAAKA,SAAS;KACtB,OAAO,KAAKA,SAAS;KACrB,gBAAgB,KAAKA,SAAS;IAChC,CAAC;IACD,KAAKC,YAAY;IACjB,OAAO;GACT,SAAS,KAAK;IACZ,KAAKE,mBAAmB,KAAA;IACxB,MAAM,IAAI,wDAAA,0CAA0C,CAClD,gDAAgD,sBAAA,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,EAAE,oEAC3F,CAAC;GACH;EACF,GAAG;EACH,OAAO,KAAKA;CACd;;;;;;;;CASA,MAAM,MAAM,MAAc,MAAwC;EAChE,MAAM,CAAC,OAAO,MAAM,KAAK,UAAU,CAAC,IAAI,GAAG,IAAI;EAC/C,OAAO;CACT;;;;;;;;;;CAWA,MAAM,UAAU,OAAiB,MAA0C;EACzE,IAAI,MAAM,WAAW,GAAG,OAAO,CAAC;EAEhC,MAAM,QAAQ,4CAAA,qBAAqB,OADtB,MAAM,QAAQ,YACqB,KAAKH,QAAQ;EAE7D,MAAM,OAAO,MAAM,KAAKE,iBAAiB;EAEzC,IAAI;EACJ,IAAI;GACF,SAAU,MAAO,KAAiE,OAAO;IACvF,SAAS,KAAKF,SAAS,WAAW;IAClC,WAAW,KAAKA,SAAS,aAAa;GACxC,CAAC;EACH,SAAS,KAAK;GACZ,MAAM,IAAI,wDAAA,0CAA0C,CAClD,sBAAA,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,CACzC,CAAC;EACH;EAEA,IAAI,CAAC,UAAU,OAAO,OAAO,WAAW,YACtC,MAAM,IAAI,wDAAA,0CAA0C,CAClD,iDACF,CAAC;EAIH,MAAM,OAAO,OAAO,OAAO;EAC3B,MAAM,UACJ,MAAM,QAAQ,IAAI,KAAK,MAAM,QAAQ,KAAK,EAAE,IAAK,OAAsB,CAAC,IAAgB;EAE1F,IAAI,QAAQ,WAAW,MAAM,QAC3B,MAAM,IAAI,wDAAA,0CAA0C,CAClD,YAAY,MAAM,OAAO,gBAAgB,QAAQ,QACnD,CAAC;EAEH,OAAO;CACT;AACF"}
+{"version":3,"file":"adapter.cjs","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/adapter.d.ts

@@ -48,6 +48,17 @@ export declare class TransformersJsEmbeddingsAdapter {
     preload(): Promise<void>;
     /** Drops the cached pipeline and in-flight load so the next call reloads. */
     reset(): void;
+    /**
+     * 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.
+     */
+    dispose(): Promise<void>;
     /**
      * Embeds a single string.
      *

package/batteries/embeddings/transformers_js/adapter.mjs

@@ -1,6 +1,9 @@
-import { c as isError } from "../../../tool_registry-FeMMz993.mjs";
+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
@@ -25,13 +28,16 @@ import { validateOptions } from "./validation.mjs";
 * 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 defaultCreatePipeline = async ({ model, device, dtype, onInitProgress }) => {
-	const { pipeline } = await import("@huggingface/transformers");
-	return await pipeline("feature-extraction", model, {
-		...device ? { device } : {},
-		...dtype ? { dtype } : {},
-		...onInitProgress ? { progress_callback: onInitProgress } : {}
-	});
+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.
@@ -77,22 +83,50 @@ var TransformersJsEmbeddingsAdapter = class TransformersJsEmbeddingsAdapter {
 		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 () => {
-			const createPipeline = this.#options.createPipeline ?? defaultCreatePipeline;
+			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: this.#options.model,
-					device: this.#options.device,
-					dtype: this.#options.dtype,
-					onInitProgress: this.#options.onInitProgress
+					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)`]);
 			}
 		})();
@@ -122,19 +156,32 @@ var TransformersJsEmbeddingsAdapter = class TransformersJsEmbeddingsAdapter {
 		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, {
-				pooling: this.#options.pooling ?? "mean",
-				normalize: this.#options.normalize ?? true
+			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();
-		const vectors = Array.isArray(list) && Array.isArray(list[0]) ? list : [list];
-		if (vectors.length !== input.length) throw new E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR([`expected ${input.length} vectors, got ${vectors.length}`]);
+		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;
 	}
 };

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

@@ -1 +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 { validateOptions } from './validation'\nimport { applyEmbeddingPrefix } from '../openai/helpers'\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 defaultCreatePipeline: CreateTransformersJsEmbeddingsPipeline = async ({\n  model,\n  device,\n  dtype,\n  onInitProgress,\n}) => {\n  const { pipeline } = await import('@huggingface/transformers')\n  return (await pipeline('feature-extraction', model, {\n    ...(device ? { device } : {}),\n    ...(dtype ? { dtype } : {}),\n    ...(onInitProgress ? { progress_callback: onInitProgress } : {}),\n  } as never)) as unknown as TransformersJsEmbeddingsPipeline\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  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    this.#pipelinePromise ??= (async () => {\n      const createPipeline = this.#options.createPipeline ?? defaultCreatePipeline\n      try {\n        const pipe = await createPipeline({\n          model: this.#options.model,\n          device: this.#options.device,\n          dtype: this.#options.dtype,\n          onInitProgress: this.#options.onInitProgress,\n        })\n        this.#pipeline = pipe\n        return pipe\n      } catch (err) {\n        this.#pipelinePromise = undefined\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\n    let tensor: { tolist: () => unknown; dims?: number[] }\n    try {\n      tensor = (await (pipe as unknown as (i: unknown, o: unknown) => Promise<unknown>)(input, {\n        pooling: this.#options.pooling ?? 'mean',\n        normalize: this.#options.normalize ?? true,\n      })) as { tolist: () => unknown; dims?: number[] }\n    } catch (err) {\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    // With pooling, the Tensor is [batch, hidden] → tolist() yields number[][].\n    const list = tensor.tolist()\n    const vectors =\n      Array.isArray(list) && Array.isArray(list[0]) ? (list as number[][]) : [list as number[]]\n\n    if (vectors.length !== input.length) {\n      throw new E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR([\n        `expected ${input.length} vectors, got ${vectors.length}`,\n      ])\n    }\n    return vectors\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,IAAM,wBAAgE,OAAO,EAC3E,OACA,QACA,OACA,qBACI;CACJ,MAAM,EAAE,aAAa,MAAM,OAAO;CAClC,OAAQ,MAAM,SAAS,sBAAsB,OAAO;EAClD,GAAI,SAAS,EAAE,OAAO,IAAI,CAAC;EAC3B,GAAI,QAAQ,EAAE,MAAM,IAAI,CAAC;EACzB,GAAI,iBAAiB,EAAE,mBAAmB,eAAe,IAAI,CAAC;CAChE,CAAU;AACZ;;;;;;;;;AAUA,IAAa,kCAAb,MAAa,gCAAgC;CAC3C;CACA;CACA;;;;;CAMA,OAAc,cAAuB;EACnC,OAAO;CACT;;;;;CAMA,YAAY,SAAkB;EAC5B,KAAKA,WAAW,gBAAgB,OAAO;EACvC,KAAKC,YAAY,KAAKD,SAAS;CACjC;;CAGA,IAAI,aAAiC;EACnC,OAAO,KAAKA,SAAS;CACvB;;CAGA,cAAuB;EACrB,QAAQ,KAAKA,SAAS,eAAe,gCAAgC,aAAa;CACpF;;CAGA,MAAM,UAAyB;EAC7B,MAAM,KAAKE,iBAAiB;CAC9B;;CAGA,QAAc;EACZ,KAAKD,YAAY,KAAA;EACjB,KAAKE,mBAAmB,KAAA;CAC1B;CAEA,MAAMD,mBAA8D;EAClE,IAAI,KAAKD,WAAW,OAAO,KAAKA;EAChC,IAAI,CAAC,KAAK,YAAY,GACpB,MAAM,IAAI,6CAA6C,CACrD,yEACF,CAAC;EAEH,KAAKE,sBAAsB,YAAY;GACrC,MAAM,iBAAiB,KAAKH,SAAS,kBAAkB;GACvD,IAAI;IACF,MAAM,OAAO,MAAM,eAAe;KAChC,OAAO,KAAKA,SAAS;KACrB,QAAQ,KAAKA,SAAS;KACtB,OAAO,KAAKA,SAAS;KACrB,gBAAgB,KAAKA,SAAS;IAChC,CAAC;IACD,KAAKC,YAAY;IACjB,OAAO;GACT,SAAS,KAAK;IACZ,KAAKE,mBAAmB,KAAA;IACxB,MAAM,IAAI,0CAA0C,CAClD,gDAAgD,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,EAAE,oEAC3F,CAAC;GACH;EACF,GAAG;EACH,OAAO,KAAKA;CACd;;;;;;;;CASA,MAAM,MAAM,MAAc,MAAwC;EAChE,MAAM,CAAC,OAAO,MAAM,KAAK,UAAU,CAAC,IAAI,GAAG,IAAI;EAC/C,OAAO;CACT;;;;;;;;;;CAWA,MAAM,UAAU,OAAiB,MAA0C;EACzE,IAAI,MAAM,WAAW,GAAG,OAAO,CAAC;EAEhC,MAAM,QAAQ,qBAAqB,OADtB,MAAM,QAAQ,YACqB,KAAKH,QAAQ;EAE7D,MAAM,OAAO,MAAM,KAAKE,iBAAiB;EAEzC,IAAI;EACJ,IAAI;GACF,SAAU,MAAO,KAAiE,OAAO;IACvF,SAAS,KAAKF,SAAS,WAAW;IAClC,WAAW,KAAKA,SAAS,aAAa;GACxC,CAAC;EACH,SAAS,KAAK;GACZ,MAAM,IAAI,0CAA0C,CAClD,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,CACzC,CAAC;EACH;EAEA,IAAI,CAAC,UAAU,OAAO,OAAO,WAAW,YACtC,MAAM,IAAI,0CAA0C,CAClD,iDACF,CAAC;EAIH,MAAM,OAAO,OAAO,OAAO;EAC3B,MAAM,UACJ,MAAM,QAAQ,IAAI,KAAK,MAAM,QAAQ,KAAK,EAAE,IAAK,OAAsB,CAAC,IAAgB;EAE1F,IAAI,QAAQ,WAAW,MAAM,QAC3B,MAAM,IAAI,0CAA0C,CAClD,YAAY,MAAM,OAAO,gBAAgB,QAAQ,QACnD,CAAC;EAEH,OAAO;CACT;AACF"}
+{"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/index.d.ts

@@ -12,5 +12,7 @@
  */
 export { TransformersJsEmbeddingsAdapter } from "./adapter";
 export { transformersJsEmbeddingsOptionsSchema, validateOptions } from "./validation";
-export type { EmbeddingKind, EmbedOptions, BaseEmbeddingsAdapterOptions, TransformersJsEmbeddingsAdapterOptions, TransformersJsEmbeddingsPipeline, TransformersJsEmbeddingsDataType, TransformersJsEmbeddingsDeviceType, TransformersJsEmbeddingsProgressCallback, TransformersJsPooling, CreateTransformersJsEmbeddingsPipeline, } from "./types";
+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"}