@nhtio/adk 1.20260625.0 → 1.20260626.0

package/CHANGELOG.md

@@ -15,6 +15,120 @@ 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
+
+- **New opt-in LLM battery `@nhtio/adk/batteries/llm/transformers_js` — on-device ONNX text generation,
+  in Node AND the browser.** Ships `TransformersJsAdapter`, a one-line {@link DispatchExecutorFn} wrapping
+  [`@huggingface/transformers`](https://www.npmjs.com/package/@huggingface/transformers) (an optional peer,
+  already present for the media ASR engine). Unlike the WebLLM and LiteRT-LM batteries (WebGPU/browser-only),
+  transformers.js is **environment-neutral** — it auto-selects `onnxruntime-node` (native, plain Node, no GPU)
+  or `onnxruntime-web` (WASM + WebGPU) — so this battery runs server-side and client-side from one codepath
+  and does **not** gate on `navigator.gpu`. `device`/`dtype` pick the backend and quantization. `STASH_KEY`
+  is `'transformersJs'`.
+- **New opt-in embeddings battery `@nhtio/adk/batteries/embeddings/transformers_js`.** Ships
+  `TransformersJsEmbeddingsAdapter` — on-device `feature-extraction` embeddings with the same
+  `embed`/`embedMany`/`dimensions`/`preload`/`reset`/`isAvailable` surface and `number[]` return shape as the
+  OpenAI and WebLLM embedders, plus `pooling` (default `'mean'`) and `normalize` (default `true`). Being
+  environment-neutral, it is surfaced from the `@nhtio/adk/batteries/embeddings` aggregate barrel (alongside
+  OpenAI; WebLLM stays deep-import-only).
+- **New shared, configurable tool-call + reasoning text-parser layer** (re-exported from both
+  `transformers_js` and `litert_lm`). Text-only on-device runtimes inject tool definitions into the chat
+  template but emit tool calls and reasoning as **family-specific raw text**, not structured fields — so the
+  battery parses them out, the way vLLM/SGLang/Ollama do (post-hoc, per-family, flag-selected). Two options,
+  both defaulting to `'auto'` (try the bundled family parsers in priority order, first match wins):
+  - `toolCallParser`: `'auto'` · `'hermes'` · `'gemma'` (E2B/E4B) · `'gpt_oss'` (Harmony) · `'pythonic'` ·
+    `'llama3_json'` · `'mistral'` · `'qwen3_coder'` · `'none'` · a custom `ToolCallParserFn`.
+  - `reasoningParser`: `'auto'` · `'think_tag'` (`<think>…</think>`) · `'harmony_analysis'` · `'gemma_channel'`
+    · `'none'` · a custom `ReasoningParserFn`.
+  Marker-anchored families run first (no cross-family false positives); weak-signal JSON/pythonic forms are
+  gated on the callee being a real tool. Parsed reasoning becomes ADK Thoughts; cleaned prose is the assistant
+  Message; tool-call `arguments` are a plain object (no `JSON.parse`). Bundled defaults target the small ONNX /
+  Ollama-Cloud-tier open-weight families (Gemma 4 E2B/E4B, gpt-oss:20b, Qwen3-Instruct, Llama 3.2, SmolLM).
+  Gemma's tool-call + reasoning delimiters were verified byte-exact against the model's own
+  `tokenizer_config.json`; both batteries were validated end-to-end against real ONNX models (MiniLM embeddings,
+  SmolLM2-135M generation).
+
+### Fixed
+
+- **LiteRT-LM tool calling and reasoning extraction now actually work** (`@nhtio/adk/batteries/llm/litert_lm`).
+  The battery as first shipped (v1.20260625.0) read `Message.tool_calls` and `Message.channels` off model
+  output — but the `@litert-lm/core` v0.13.1 JS runtime is **text-in / text-out** and never populates those
+  fields on output (they are input-only wire fields; the package README confirms text-only I/O). So the prior
+  tool-calling and reasoning support was **non-functional against real models** (the mocked tests passed
+  because the fakes populated the fields). The adapter now parses tool calls and reasoning out of the model's
+  **text** via the new shared parser layer, with the same `toolCallParser` / `reasoningParser` options
+  (default `'auto'`). If you relied on LiteRT-LM tool calls or thoughts before, they begin functioning with
+  this release.
+
 ## 2026-06-24
 
 ### Added

package/batteries/embeddings/index.d.ts

@@ -4,22 +4,28 @@
  * @module @nhtio/adk/batteries/embeddings
  *
  * @remarks
- * Aggregate barrel for the embeddings batteries. Re-exports only the **environment-neutral**
- * embeddings battery — currently just the OpenAI battery (raw `fetch`, runs anywhere) — so
- * consumers can import this barrel from either Node or the browser without dragging in
- * environment-specific runtime requirements.
+ * Aggregate barrel for the embeddings batteries. Re-exports the **environment-neutral** embeddings
+ * batteries — the OpenAI battery (raw `fetch`, runs anywhere) and the transformers.js battery (ONNX
+ * Runtime, auto-selecting native Node vs WASM/WebGPU in the browser) — so consumers can import this
+ * barrel from either Node or the browser without dragging in environment-specific runtime
+ * requirements.
  *
  * The browser/WebGPU-only WebLLM embeddings battery is reachable only through its own subpath:
  *
  * - `@nhtio/adk/batteries/embeddings/webllm` — browser-only (uses WebGPU via `@mlc-ai/web-llm`).
  *
- * Deep-import that subpath when you need it; don't expect it to be re-exported here. The two
- * batteries share one option base and an identical method surface — see
+ * Deep-import that subpath when you need it; don't expect it to be re-exported here. All batteries
+ * share one option base and an identical method surface — see
  * {@link @nhtio/adk/batteries/embeddings/openai/types!BaseEmbeddingsAdapterOptions}.
  */
 export { OpenAIEmbeddingsAdapter } from "./openai/index";
 export { applyEmbeddingPrefix } from "./openai/index";
 export { openAIEmbeddingsOptionsSchema } from "./openai/index";
 export { validateOptions as validateOpenAIEmbeddingsOptions } from "./openai/index";
+export { TransformersJsEmbeddingsAdapter } from "./transformers_js/index";
+export { transformersJsEmbeddingsOptionsSchema } from "./transformers_js/index";
+export { validateOptions as validateTransformersJsEmbeddingsOptions } from "./transformers_js/index";
+export type { TransformersJsEmbeddingsAdapterOptions, TransformersJsEmbeddingsPipeline, TransformersJsEmbeddingsDataType, TransformersJsEmbeddingsDeviceType, TransformersJsEmbeddingsProgressCallback, TransformersJsPooling, CreateTransformersJsEmbeddingsPipeline, } from "./transformers_js/index";
+export { E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS, E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR, } from "./transformers_js/index";
 export type { EmbeddingKind, EmbedOptions, EmbeddingsRetryConfig, BaseEmbeddingsAdapterOptions, OpenAIEmbeddingsAdapterOptions, OpenAIEmbeddingsRequestBody, OpenAIEmbeddingsResponseBody, } from "./openai/index";
 export { E_INVALID_OPENAI_EMBEDDINGS_OPTIONS, E_OPENAI_EMBEDDINGS_HTTP_ERROR, E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT, E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE, } from "./openai/index";

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

@@ -0,0 +1,193 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../chunk-Cek0wNdY.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
+/**
+* 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 ? require_batteries_llm_transformers_js_model_source.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 = require_batteries_embeddings_transformers_js_validation.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 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 () => {
+			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: 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)`]);
+			}
+		})();
+		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 = 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, 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();
+		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;
+	}
+};
+//#endregion
+exports.TransformersJsEmbeddingsAdapter = TransformersJsEmbeddingsAdapter;
+
+//# sourceMappingURL=adapter.cjs.map

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

@@ -0,0 +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 { 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

@@ -0,0 +1,80 @@
+/**
+ * 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.
+ */
+import type { EmbedOptions } from "../openai/types";
+/**
+ * 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.
+ */
+export declare class TransformersJsEmbeddingsAdapter {
+    #private;
+    /**
+     * 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(): boolean;
+    /**
+     * @param options - Constructor options. Validated eagerly.
+     * @throws {@link @nhtio/adk/batteries!E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS} when invalid.
+     */
+    constructor(options: unknown);
+    /** Declared output dimensionality (from options), or `undefined` if not configured. */
+    get dimensions(): number | undefined;
+    /** Instance availability probe (honours an injected `isAvailable`). */
+    isAvailable(): boolean;
+    /** Eagerly loads (and caches) the pipeline so the first `embed` call is fast. Idempotent. */
+    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.
+     *
+     * @param text - The input text.
+     * @param opts - Per-call options (`kind`).
+     * @returns The embedding vector as a plain `number[]`.
+     */
+    embed(text: string, opts?: EmbedOptions): Promise<number[]>;
+    /**
+     * 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.
+     */
+    embedMany(texts: string[], opts?: EmbedOptions): Promise<number[][]>;
+}