@nhtio/adk 0.1.0-master-e04b0eba → 0.1.0-master-bd43a4ea

package/batteries/embeddings/webllm/adapter.cjs

@@ -0,0 +1,147 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../chunk-Ble4zEEl.js");
+const require_tool_registry = require("../../../tool_registry-CtCQ4Xoz.js");
+require("../../../guards.cjs");
+const require_batteries_embeddings_openai_helpers = require("../openai/helpers.cjs");
+const require_batteries_embeddings_webllm_exceptions = require("./exceptions.cjs");
+const require_batteries_embeddings_webllm_validation = require("./validation.cjs");
+//#region src/batteries/embeddings/webllm/adapter.ts
+/**
+* WebLLM (WebGPU, in-process) Embeddings adapter battery.
+*
+* @module @nhtio/adk/batteries/embeddings/webllm/adapter
+*
+* @remarks
+* Embeddings battery backed by WebLLM's in-process `engine.embeddings.create()` (the OpenAI-style
+* embeddings API exposed by `@mlc-ai/web-llm`). Runs entirely in the browser on WebGPU — no
+* network round-trip, no API key.
+*
+* This class is the **same battery** as {@link @nhtio/adk/batteries/embeddings/openai!OpenAIEmbeddingsAdapter}
+* in every user-facing respect — identical method surface (`isAvailable` / `dimensions` /
+* `preload` / `reset` / `embed` / `embedMany`), identical `number[]` return shape, identical
+* query/document prefix handling (the shared `applyEmbeddingPrefix` helper) — differing only in
+* the engine. Construction validates eagerly and throws
+* {@link @nhtio/adk/batteries/embeddings/webllm/exceptions!E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS} on failure.
+*
+* `@mlc-ai/web-llm` is an optional peer dependency, imported lazily so non-WebGPU consumers pay
+* nothing for it.
+*/
+var defaultCreateEngine = async ({ model, engineConfig, chatOptions, onInitProgress }) => {
+	const { CreateMLCEngine } = await import("@mlc-ai/web-llm");
+	return await CreateMLCEngine(model, {
+		...engineConfig ?? {},
+		initProgressCallback: onInitProgress
+	}, chatOptions);
+};
+/**
+* Embeddings adapter for WebLLM's in-process embeddings API.
+*
+* @remarks
+* Reusable: construct once, call {@link WebLLMEmbeddingsAdapter.embed} / {@link embedMany} as many
+* times as needed. The engine is resolved lazily on first use (or via {@link preload}) and cached
+* with single-flight semantics so concurrent calls share one load.
+*/
+var WebLLMEmbeddingsAdapter = class WebLLMEmbeddingsAdapter {
+	#options;
+	#engine;
+	#enginePromise;
+	/**
+	* Whether WebGPU — and therefore this battery — is available in the current runtime.
+	*/
+	static isAvailable() {
+		return typeof globalThis.navigator !== "undefined" && "gpu" in globalThis.navigator && typeof globalThis.navigator.gpu !== "undefined";
+	}
+	/**
+	* @param options - Constructor options. Validated eagerly.
+	* @throws {@link @nhtio/adk/batteries/embeddings/webllm/exceptions!E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS} when `options` does not satisfy
+	*   {@link @nhtio/adk/batteries/embeddings/webllm/validation!webLLMEmbeddingsOptionsSchema} (e.g. missing `model`).
+	*/
+	constructor(options) {
+		this.#options = require_batteries_embeddings_webllm_validation.validateOptions(options);
+		this.#engine = this.#options.engine;
+	}
+	/** Declared output dimensionality (from options), or `undefined` if not configured. */
+	get dimensions() {
+		return this.#options.dimensions;
+	}
+	/** Whether WebGPU is available, honoring an injected `isWebGPUAvailable` probe. */
+	isAvailable() {
+		return (this.#options.isWebGPUAvailable ?? WebLLMEmbeddingsAdapter.isAvailable)();
+	}
+	/**
+	* Eagerly loads (and caches) the engine so the first `embed` call is fast. Idempotent.
+	*
+	* @throws {@link @nhtio/adk/batteries/embeddings/webllm/exceptions!E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS} when no WebGPU is available and no engine
+	*   was injected.
+	* @throws {@link @nhtio/adk/batteries/embeddings/webllm/exceptions!E_WEBLLM_EMBEDDINGS_ENGINE_ERROR} when engine creation fails.
+	*/
+	async preload() {
+		await this.#resolveEngine();
+	}
+	/** Drops the cached engine and in-flight load so the next call reloads. */
+	reset() {
+		this.#engine = void 0;
+		this.#enginePromise = void 0;
+	}
+	async #resolveEngine() {
+		if (this.#engine) return this.#engine;
+		if (!this.isAvailable()) throw new require_batteries_embeddings_webllm_exceptions.E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS(["WebLLM requires a browser/runtime with WebGPU support"]);
+		this.#enginePromise ??= (async () => {
+			const createEngine = this.#options.createEngine ?? defaultCreateEngine;
+			try {
+				const engine = await createEngine({
+					model: this.#options.model,
+					engineConfig: this.#options.engineConfig,
+					chatOptions: this.#options.chatOptions,
+					onInitProgress: this.#options.onInitProgress
+				});
+				this.#engine = engine;
+				return engine;
+			} catch (err) {
+				this.#enginePromise = void 0;
+				throw new require_batteries_embeddings_webllm_exceptions.E_WEBLLM_EMBEDDINGS_ENGINE_ERROR([require_tool_registry.isError(err) ? err.message : String(err)]);
+			}
+		})();
+		return this.#enginePromise;
+	}
+	/**
+	* 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 engine 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/embeddings/webllm/exceptions!E_WEBLLM_EMBEDDINGS_ENGINE_ERROR} when the engine 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 engine = await this.#resolveEngine();
+		let response;
+		try {
+			response = await engine.embeddings.create({
+				model: this.#options.model,
+				input
+			});
+		} catch (err) {
+			throw new require_batteries_embeddings_webllm_exceptions.E_WEBLLM_EMBEDDINGS_ENGINE_ERROR([require_tool_registry.isError(err) ? err.message : String(err)]);
+		}
+		if (!response || !Array.isArray(response.data) || response.data.length !== input.length) throw new require_batteries_embeddings_webllm_exceptions.E_WEBLLM_EMBEDDINGS_ENGINE_ERROR([`expected ${input.length} vectors, got ${response?.data?.length ?? "none"}`]);
+		return response.data.slice().sort((a, b) => a.index - b.index).map((d) => d.embedding);
+	}
+};
+//#endregion
+exports.WebLLMEmbeddingsAdapter = WebLLMEmbeddingsAdapter;
+
+//# sourceMappingURL=adapter.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.cjs","names":["#options","#engine","#resolveEngine","#enginePromise"],"sources":["../../../../src/batteries/embeddings/webllm/adapter.ts"],"sourcesContent":["/**\n * WebLLM (WebGPU, in-process) Embeddings adapter battery.\n *\n * @module @nhtio/adk/batteries/embeddings/webllm/adapter\n *\n * @remarks\n * Embeddings battery backed by WebLLM's in-process `engine.embeddings.create()` (the OpenAI-style\n * embeddings API exposed by `@mlc-ai/web-llm`). Runs entirely in the browser on WebGPU — no\n * network round-trip, no API key.\n *\n * This class is the **same battery** as {@link @nhtio/adk/batteries/embeddings/openai!OpenAIEmbeddingsAdapter}\n * in every user-facing respect — identical method surface (`isAvailable` / `dimensions` /\n * `preload` / `reset` / `embed` / `embedMany`), identical `number[]` return shape, identical\n * query/document prefix handling (the shared `applyEmbeddingPrefix` helper) — differing only in\n * the engine. Construction validates eagerly and throws\n * {@link @nhtio/adk/batteries/embeddings/webllm/exceptions!E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS} on failure.\n *\n * `@mlc-ai/web-llm` is an optional peer dependency, imported lazily so non-WebGPU consumers pay\n * nothing for it.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { validateOptions } from './validation'\nimport { applyEmbeddingPrefix } from '../openai/helpers'\nimport { E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS, E_WEBLLM_EMBEDDINGS_ENGINE_ERROR } from './exceptions'\nimport type { EmbedOptions } from '../openai/types'\nimport type {\n  WebLLMEmbeddingsAdapterOptions,\n  WebLLMEmbeddingsEngine,\n  CreateWebLLMEmbeddingsEngine,\n} from './types'\n\nconst defaultCreateEngine: CreateWebLLMEmbeddingsEngine = async ({\n  model,\n  engineConfig,\n  chatOptions,\n  onInitProgress,\n}) => {\n  const { CreateMLCEngine } = await import('@mlc-ai/web-llm')\n  return (await CreateMLCEngine(\n    model,\n    { ...(engineConfig ?? {}), initProgressCallback: onInitProgress },\n    chatOptions\n  )) as WebLLMEmbeddingsEngine\n}\n\n/**\n * Embeddings adapter for WebLLM's in-process embeddings API.\n *\n * @remarks\n * Reusable: construct once, call {@link WebLLMEmbeddingsAdapter.embed} / {@link embedMany} as many\n * times as needed. The engine is resolved lazily on first use (or via {@link preload}) and cached\n * with single-flight semantics so concurrent calls share one load.\n */\nexport class WebLLMEmbeddingsAdapter {\n  readonly #options: WebLLMEmbeddingsAdapterOptions\n  #engine: WebLLMEmbeddingsEngine | undefined\n  #enginePromise: Promise<WebLLMEmbeddingsEngine> | undefined\n\n  /**\n   * Whether WebGPU — and therefore this battery — is available in the current runtime.\n   */\n  public static isAvailable(): boolean {\n    return (\n      typeof globalThis.navigator !== 'undefined' &&\n      'gpu' in globalThis.navigator &&\n      typeof (globalThis.navigator as { gpu?: unknown }).gpu !== 'undefined'\n    )\n  }\n\n  /**\n   * @param options - Constructor options. Validated eagerly.\n   * @throws {@link @nhtio/adk/batteries/embeddings/webllm/exceptions!E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS} when `options` does not satisfy\n   *   {@link @nhtio/adk/batteries/embeddings/webllm/validation!webLLMEmbeddingsOptionsSchema} (e.g. missing `model`).\n   */\n  constructor(options: unknown) {\n    this.#options = validateOptions(options)\n    this.#engine = this.#options.engine\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  /** Whether WebGPU is available, honoring an injected `isWebGPUAvailable` probe. */\n  isAvailable(): boolean {\n    return (this.#options.isWebGPUAvailable ?? WebLLMEmbeddingsAdapter.isAvailable)()\n  }\n\n  /**\n   * Eagerly loads (and caches) the engine so the first `embed` call is fast. Idempotent.\n   *\n   * @throws {@link @nhtio/adk/batteries/embeddings/webllm/exceptions!E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS} when no WebGPU is available and no engine\n   *   was injected.\n   * @throws {@link @nhtio/adk/batteries/embeddings/webllm/exceptions!E_WEBLLM_EMBEDDINGS_ENGINE_ERROR} when engine creation fails.\n   */\n  async preload(): Promise<void> {\n    await this.#resolveEngine()\n  }\n\n  /** Drops the cached engine and in-flight load so the next call reloads. */\n  reset(): void {\n    this.#engine = undefined\n    this.#enginePromise = undefined\n  }\n\n  async #resolveEngine(): Promise<WebLLMEmbeddingsEngine> {\n    if (this.#engine) return this.#engine\n    if (!this.isAvailable()) {\n      throw new E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS([\n        'WebLLM requires a browser/runtime with WebGPU support',\n      ])\n    }\n    this.#enginePromise ??= (async () => {\n      const createEngine = this.#options.createEngine ?? defaultCreateEngine\n      try {\n        const engine = await createEngine({\n          model: this.#options.model,\n          engineConfig: this.#options.engineConfig,\n          chatOptions: this.#options.chatOptions,\n          onInitProgress: this.#options.onInitProgress,\n        })\n        this.#engine = engine\n        return engine\n      } catch (err) {\n        // Clear the cached promise so a later call can retry a transient load failure.\n        this.#enginePromise = undefined\n        throw new E_WEBLLM_EMBEDDINGS_ENGINE_ERROR([isError(err) ? err.message : String(err)])\n      }\n    })()\n    return this.#enginePromise\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 engine 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/embeddings/webllm/exceptions!E_WEBLLM_EMBEDDINGS_ENGINE_ERROR} when the engine call fails or returns a\n   *   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 engine = await this.#resolveEngine()\n\n    let response: { data?: Array<{ embedding: number[]; index: number }> }\n    try {\n      response = await engine.embeddings.create({ model: this.#options.model, input })\n    } catch (err) {\n      throw new E_WEBLLM_EMBEDDINGS_ENGINE_ERROR([isError(err) ? err.message : String(err)])\n    }\n\n    if (!response || !Array.isArray(response.data) || response.data.length !== input.length) {\n      throw new E_WEBLLM_EMBEDDINGS_ENGINE_ERROR([\n        `expected ${input.length} vectors, got ${response?.data?.length ?? 'none'}`,\n      ])\n    }\n    return response.data\n      .slice()\n      .sort((a, b) => a.index - b.index)\n      .map((d) => d.embedding)\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,IAAM,sBAAoD,OAAO,EAC/D,OACA,cACA,aACA,qBACI;CACJ,MAAM,EAAE,oBAAoB,MAAM,OAAO;CACzC,OAAQ,MAAM,gBACZ,OACA;EAAE,GAAI,gBAAgB,CAAC;EAAI,sBAAsB;CAAe,GAChE,WACF;AACF;;;;;;;;;AAUA,IAAa,0BAAb,MAAa,wBAAwB;CACnC;CACA;CACA;;;;CAKA,OAAc,cAAuB;EACnC,OACE,OAAO,WAAW,cAAc,eAChC,SAAS,WAAW,aACpB,OAAQ,WAAW,UAAgC,QAAQ;CAE/D;;;;;;CAOA,YAAY,SAAkB;EAC5B,KAAKA,WAAW,+CAAA,gBAAgB,OAAO;EACvC,KAAKC,UAAU,KAAKD,SAAS;CAC/B;;CAGA,IAAI,aAAiC;EACnC,OAAO,KAAKA,SAAS;CACvB;;CAGA,cAAuB;EACrB,QAAQ,KAAKA,SAAS,qBAAqB,wBAAwB,aAAa;CAClF;;;;;;;;CASA,MAAM,UAAyB;EAC7B,MAAM,KAAKE,eAAe;CAC5B;;CAGA,QAAc;EACZ,KAAKD,UAAU,KAAA;EACf,KAAKE,iBAAiB,KAAA;CACxB;CAEA,MAAMD,iBAAkD;EACtD,IAAI,KAAKD,SAAS,OAAO,KAAKA;EAC9B,IAAI,CAAC,KAAK,YAAY,GACpB,MAAM,IAAI,+CAAA,oCAAoC,CAC5C,uDACF,CAAC;EAEH,KAAKE,oBAAoB,YAAY;GACnC,MAAM,eAAe,KAAKH,SAAS,gBAAgB;GACnD,IAAI;IACF,MAAM,SAAS,MAAM,aAAa;KAChC,OAAO,KAAKA,SAAS;KACrB,cAAc,KAAKA,SAAS;KAC5B,aAAa,KAAKA,SAAS;KAC3B,gBAAgB,KAAKA,SAAS;IAChC,CAAC;IACD,KAAKC,UAAU;IACf,OAAO;GACT,SAAS,KAAK;IAEZ,KAAKE,iBAAiB,KAAA;IACtB,MAAM,IAAI,+CAAA,iCAAiC,CAAC,sBAAA,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,CAAC,CAAC;GACvF;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,SAAS,MAAM,KAAKE,eAAe;EAEzC,IAAI;EACJ,IAAI;GACF,WAAW,MAAM,OAAO,WAAW,OAAO;IAAE,OAAO,KAAKF,SAAS;IAAO;GAAM,CAAC;EACjF,SAAS,KAAK;GACZ,MAAM,IAAI,+CAAA,iCAAiC,CAAC,sBAAA,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,CAAC,CAAC;EACvF;EAEA,IAAI,CAAC,YAAY,CAAC,MAAM,QAAQ,SAAS,IAAI,KAAK,SAAS,KAAK,WAAW,MAAM,QAC/E,MAAM,IAAI,+CAAA,iCAAiC,CACzC,YAAY,MAAM,OAAO,gBAAgB,UAAU,MAAM,UAAU,QACrE,CAAC;EAEH,OAAO,SAAS,KACb,MAAM,EACN,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,KAAK,EAChC,KAAK,MAAM,EAAE,SAAS;CAC3B;AACF"}

package/batteries/embeddings/webllm/adapter.d.ts

@@ -0,0 +1,74 @@
+/**
+ * WebLLM (WebGPU, in-process) Embeddings adapter battery.
+ *
+ * @module @nhtio/adk/batteries/embeddings/webllm/adapter
+ *
+ * @remarks
+ * Embeddings battery backed by WebLLM's in-process `engine.embeddings.create()` (the OpenAI-style
+ * embeddings API exposed by `@mlc-ai/web-llm`). Runs entirely in the browser on WebGPU — no
+ * network round-trip, no API key.
+ *
+ * This class is the **same battery** as {@link @nhtio/adk/batteries/embeddings/openai!OpenAIEmbeddingsAdapter}
+ * in every user-facing respect — identical method surface (`isAvailable` / `dimensions` /
+ * `preload` / `reset` / `embed` / `embedMany`), identical `number[]` return shape, identical
+ * query/document prefix handling (the shared `applyEmbeddingPrefix` helper) — differing only in
+ * the engine. Construction validates eagerly and throws
+ * {@link @nhtio/adk/batteries/embeddings/webllm/exceptions!E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS} on failure.
+ *
+ * `@mlc-ai/web-llm` is an optional peer dependency, imported lazily so non-WebGPU consumers pay
+ * nothing for it.
+ */
+import type { EmbedOptions } from "../openai/types";
+/**
+ * Embeddings adapter for WebLLM's in-process embeddings API.
+ *
+ * @remarks
+ * Reusable: construct once, call {@link WebLLMEmbeddingsAdapter.embed} / {@link embedMany} as many
+ * times as needed. The engine 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 WebLLMEmbeddingsAdapter {
+    #private;
+    /**
+     * Whether WebGPU — and therefore this battery — is available in the current runtime.
+     */
+    static isAvailable(): boolean;
+    /**
+     * @param options - Constructor options. Validated eagerly.
+     * @throws {@link @nhtio/adk/batteries/embeddings/webllm/exceptions!E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS} when `options` does not satisfy
+     *   {@link @nhtio/adk/batteries/embeddings/webllm/validation!webLLMEmbeddingsOptionsSchema} (e.g. missing `model`).
+     */
+    constructor(options: unknown);
+    /** Declared output dimensionality (from options), or `undefined` if not configured. */
+    get dimensions(): number | undefined;
+    /** Whether WebGPU is available, honoring an injected `isWebGPUAvailable` probe. */
+    isAvailable(): boolean;
+    /**
+     * Eagerly loads (and caches) the engine so the first `embed` call is fast. Idempotent.
+     *
+     * @throws {@link @nhtio/adk/batteries/embeddings/webllm/exceptions!E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS} when no WebGPU is available and no engine
+     *   was injected.
+     * @throws {@link @nhtio/adk/batteries/embeddings/webllm/exceptions!E_WEBLLM_EMBEDDINGS_ENGINE_ERROR} when engine creation fails.
+     */
+    preload(): Promise<void>;
+    /** Drops the cached engine and in-flight load so the next call reloads. */
+    reset(): 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 engine 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/embeddings/webllm/exceptions!E_WEBLLM_EMBEDDINGS_ENGINE_ERROR} when the engine call fails or returns a
+     *   malformed result.
+     */
+    embedMany(texts: string[], opts?: EmbedOptions): Promise<number[][]>;
+}

package/batteries/embeddings/webllm/adapter.mjs

@@ -0,0 +1,145 @@
+import { o as isError } from "../../../tool_registry-BGHg6KTq.mjs";
+import "../../../guards.mjs";
+import { applyEmbeddingPrefix } from "../openai/helpers.mjs";
+import { E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS, E_WEBLLM_EMBEDDINGS_ENGINE_ERROR } from "./exceptions.mjs";
+import { validateOptions } from "./validation.mjs";
+//#region src/batteries/embeddings/webllm/adapter.ts
+/**
+* WebLLM (WebGPU, in-process) Embeddings adapter battery.
+*
+* @module @nhtio/adk/batteries/embeddings/webllm/adapter
+*
+* @remarks
+* Embeddings battery backed by WebLLM's in-process `engine.embeddings.create()` (the OpenAI-style
+* embeddings API exposed by `@mlc-ai/web-llm`). Runs entirely in the browser on WebGPU — no
+* network round-trip, no API key.
+*
+* This class is the **same battery** as {@link @nhtio/adk/batteries/embeddings/openai!OpenAIEmbeddingsAdapter}
+* in every user-facing respect — identical method surface (`isAvailable` / `dimensions` /
+* `preload` / `reset` / `embed` / `embedMany`), identical `number[]` return shape, identical
+* query/document prefix handling (the shared `applyEmbeddingPrefix` helper) — differing only in
+* the engine. Construction validates eagerly and throws
+* {@link @nhtio/adk/batteries/embeddings/webllm/exceptions!E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS} on failure.
+*
+* `@mlc-ai/web-llm` is an optional peer dependency, imported lazily so non-WebGPU consumers pay
+* nothing for it.
+*/
+var defaultCreateEngine = async ({ model, engineConfig, chatOptions, onInitProgress }) => {
+	const { CreateMLCEngine } = await import("@mlc-ai/web-llm");
+	return await CreateMLCEngine(model, {
+		...engineConfig ?? {},
+		initProgressCallback: onInitProgress
+	}, chatOptions);
+};
+/**
+* Embeddings adapter for WebLLM's in-process embeddings API.
+*
+* @remarks
+* Reusable: construct once, call {@link WebLLMEmbeddingsAdapter.embed} / {@link embedMany} as many
+* times as needed. The engine is resolved lazily on first use (or via {@link preload}) and cached
+* with single-flight semantics so concurrent calls share one load.
+*/
+var WebLLMEmbeddingsAdapter = class WebLLMEmbeddingsAdapter {
+	#options;
+	#engine;
+	#enginePromise;
+	/**
+	* Whether WebGPU — and therefore this battery — is available in the current runtime.
+	*/
+	static isAvailable() {
+		return typeof globalThis.navigator !== "undefined" && "gpu" in globalThis.navigator && typeof globalThis.navigator.gpu !== "undefined";
+	}
+	/**
+	* @param options - Constructor options. Validated eagerly.
+	* @throws {@link @nhtio/adk/batteries/embeddings/webllm/exceptions!E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS} when `options` does not satisfy
+	*   {@link @nhtio/adk/batteries/embeddings/webllm/validation!webLLMEmbeddingsOptionsSchema} (e.g. missing `model`).
+	*/
+	constructor(options) {
+		this.#options = validateOptions(options);
+		this.#engine = this.#options.engine;
+	}
+	/** Declared output dimensionality (from options), or `undefined` if not configured. */
+	get dimensions() {
+		return this.#options.dimensions;
+	}
+	/** Whether WebGPU is available, honoring an injected `isWebGPUAvailable` probe. */
+	isAvailable() {
+		return (this.#options.isWebGPUAvailable ?? WebLLMEmbeddingsAdapter.isAvailable)();
+	}
+	/**
+	* Eagerly loads (and caches) the engine so the first `embed` call is fast. Idempotent.
+	*
+	* @throws {@link @nhtio/adk/batteries/embeddings/webllm/exceptions!E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS} when no WebGPU is available and no engine
+	*   was injected.
+	* @throws {@link @nhtio/adk/batteries/embeddings/webllm/exceptions!E_WEBLLM_EMBEDDINGS_ENGINE_ERROR} when engine creation fails.
+	*/
+	async preload() {
+		await this.#resolveEngine();
+	}
+	/** Drops the cached engine and in-flight load so the next call reloads. */
+	reset() {
+		this.#engine = void 0;
+		this.#enginePromise = void 0;
+	}
+	async #resolveEngine() {
+		if (this.#engine) return this.#engine;
+		if (!this.isAvailable()) throw new E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS(["WebLLM requires a browser/runtime with WebGPU support"]);
+		this.#enginePromise ??= (async () => {
+			const createEngine = this.#options.createEngine ?? defaultCreateEngine;
+			try {
+				const engine = await createEngine({
+					model: this.#options.model,
+					engineConfig: this.#options.engineConfig,
+					chatOptions: this.#options.chatOptions,
+					onInitProgress: this.#options.onInitProgress
+				});
+				this.#engine = engine;
+				return engine;
+			} catch (err) {
+				this.#enginePromise = void 0;
+				throw new E_WEBLLM_EMBEDDINGS_ENGINE_ERROR([isError(err) ? err.message : String(err)]);
+			}
+		})();
+		return this.#enginePromise;
+	}
+	/**
+	* 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 engine 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/embeddings/webllm/exceptions!E_WEBLLM_EMBEDDINGS_ENGINE_ERROR} when the engine call fails or returns a
+	*   malformed result.
+	*/
+	async embedMany(texts, opts) {
+		if (texts.length === 0) return [];
+		const input = applyEmbeddingPrefix(texts, opts?.kind ?? "document", this.#options);
+		const engine = await this.#resolveEngine();
+		let response;
+		try {
+			response = await engine.embeddings.create({
+				model: this.#options.model,
+				input
+			});
+		} catch (err) {
+			throw new E_WEBLLM_EMBEDDINGS_ENGINE_ERROR([isError(err) ? err.message : String(err)]);
+		}
+		if (!response || !Array.isArray(response.data) || response.data.length !== input.length) throw new E_WEBLLM_EMBEDDINGS_ENGINE_ERROR([`expected ${input.length} vectors, got ${response?.data?.length ?? "none"}`]);
+		return response.data.slice().sort((a, b) => a.index - b.index).map((d) => d.embedding);
+	}
+};
+//#endregion
+export { WebLLMEmbeddingsAdapter };
+
+//# sourceMappingURL=adapter.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.mjs","names":["#options","#engine","#resolveEngine","#enginePromise"],"sources":["../../../../src/batteries/embeddings/webllm/adapter.ts"],"sourcesContent":["/**\n * WebLLM (WebGPU, in-process) Embeddings adapter battery.\n *\n * @module @nhtio/adk/batteries/embeddings/webllm/adapter\n *\n * @remarks\n * Embeddings battery backed by WebLLM's in-process `engine.embeddings.create()` (the OpenAI-style\n * embeddings API exposed by `@mlc-ai/web-llm`). Runs entirely in the browser on WebGPU — no\n * network round-trip, no API key.\n *\n * This class is the **same battery** as {@link @nhtio/adk/batteries/embeddings/openai!OpenAIEmbeddingsAdapter}\n * in every user-facing respect — identical method surface (`isAvailable` / `dimensions` /\n * `preload` / `reset` / `embed` / `embedMany`), identical `number[]` return shape, identical\n * query/document prefix handling (the shared `applyEmbeddingPrefix` helper) — differing only in\n * the engine. Construction validates eagerly and throws\n * {@link @nhtio/adk/batteries/embeddings/webllm/exceptions!E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS} on failure.\n *\n * `@mlc-ai/web-llm` is an optional peer dependency, imported lazily so non-WebGPU consumers pay\n * nothing for it.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { validateOptions } from './validation'\nimport { applyEmbeddingPrefix } from '../openai/helpers'\nimport { E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS, E_WEBLLM_EMBEDDINGS_ENGINE_ERROR } from './exceptions'\nimport type { EmbedOptions } from '../openai/types'\nimport type {\n  WebLLMEmbeddingsAdapterOptions,\n  WebLLMEmbeddingsEngine,\n  CreateWebLLMEmbeddingsEngine,\n} from './types'\n\nconst defaultCreateEngine: CreateWebLLMEmbeddingsEngine = async ({\n  model,\n  engineConfig,\n  chatOptions,\n  onInitProgress,\n}) => {\n  const { CreateMLCEngine } = await import('@mlc-ai/web-llm')\n  return (await CreateMLCEngine(\n    model,\n    { ...(engineConfig ?? {}), initProgressCallback: onInitProgress },\n    chatOptions\n  )) as WebLLMEmbeddingsEngine\n}\n\n/**\n * Embeddings adapter for WebLLM's in-process embeddings API.\n *\n * @remarks\n * Reusable: construct once, call {@link WebLLMEmbeddingsAdapter.embed} / {@link embedMany} as many\n * times as needed. The engine is resolved lazily on first use (or via {@link preload}) and cached\n * with single-flight semantics so concurrent calls share one load.\n */\nexport class WebLLMEmbeddingsAdapter {\n  readonly #options: WebLLMEmbeddingsAdapterOptions\n  #engine: WebLLMEmbeddingsEngine | undefined\n  #enginePromise: Promise<WebLLMEmbeddingsEngine> | undefined\n\n  /**\n   * Whether WebGPU — and therefore this battery — is available in the current runtime.\n   */\n  public static isAvailable(): boolean {\n    return (\n      typeof globalThis.navigator !== 'undefined' &&\n      'gpu' in globalThis.navigator &&\n      typeof (globalThis.navigator as { gpu?: unknown }).gpu !== 'undefined'\n    )\n  }\n\n  /**\n   * @param options - Constructor options. Validated eagerly.\n   * @throws {@link @nhtio/adk/batteries/embeddings/webllm/exceptions!E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS} when `options` does not satisfy\n   *   {@link @nhtio/adk/batteries/embeddings/webllm/validation!webLLMEmbeddingsOptionsSchema} (e.g. missing `model`).\n   */\n  constructor(options: unknown) {\n    this.#options = validateOptions(options)\n    this.#engine = this.#options.engine\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  /** Whether WebGPU is available, honoring an injected `isWebGPUAvailable` probe. */\n  isAvailable(): boolean {\n    return (this.#options.isWebGPUAvailable ?? WebLLMEmbeddingsAdapter.isAvailable)()\n  }\n\n  /**\n   * Eagerly loads (and caches) the engine so the first `embed` call is fast. Idempotent.\n   *\n   * @throws {@link @nhtio/adk/batteries/embeddings/webllm/exceptions!E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS} when no WebGPU is available and no engine\n   *   was injected.\n   * @throws {@link @nhtio/adk/batteries/embeddings/webllm/exceptions!E_WEBLLM_EMBEDDINGS_ENGINE_ERROR} when engine creation fails.\n   */\n  async preload(): Promise<void> {\n    await this.#resolveEngine()\n  }\n\n  /** Drops the cached engine and in-flight load so the next call reloads. */\n  reset(): void {\n    this.#engine = undefined\n    this.#enginePromise = undefined\n  }\n\n  async #resolveEngine(): Promise<WebLLMEmbeddingsEngine> {\n    if (this.#engine) return this.#engine\n    if (!this.isAvailable()) {\n      throw new E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS([\n        'WebLLM requires a browser/runtime with WebGPU support',\n      ])\n    }\n    this.#enginePromise ??= (async () => {\n      const createEngine = this.#options.createEngine ?? defaultCreateEngine\n      try {\n        const engine = await createEngine({\n          model: this.#options.model,\n          engineConfig: this.#options.engineConfig,\n          chatOptions: this.#options.chatOptions,\n          onInitProgress: this.#options.onInitProgress,\n        })\n        this.#engine = engine\n        return engine\n      } catch (err) {\n        // Clear the cached promise so a later call can retry a transient load failure.\n        this.#enginePromise = undefined\n        throw new E_WEBLLM_EMBEDDINGS_ENGINE_ERROR([isError(err) ? err.message : String(err)])\n      }\n    })()\n    return this.#enginePromise\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 engine 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/embeddings/webllm/exceptions!E_WEBLLM_EMBEDDINGS_ENGINE_ERROR} when the engine call fails or returns a\n   *   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 engine = await this.#resolveEngine()\n\n    let response: { data?: Array<{ embedding: number[]; index: number }> }\n    try {\n      response = await engine.embeddings.create({ model: this.#options.model, input })\n    } catch (err) {\n      throw new E_WEBLLM_EMBEDDINGS_ENGINE_ERROR([isError(err) ? err.message : String(err)])\n    }\n\n    if (!response || !Array.isArray(response.data) || response.data.length !== input.length) {\n      throw new E_WEBLLM_EMBEDDINGS_ENGINE_ERROR([\n        `expected ${input.length} vectors, got ${response?.data?.length ?? 'none'}`,\n      ])\n    }\n    return response.data\n      .slice()\n      .sort((a, b) => a.index - b.index)\n      .map((d) => d.embedding)\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAgCA,IAAM,sBAAoD,OAAO,EAC/D,OACA,cACA,aACA,qBACI;CACJ,MAAM,EAAE,oBAAoB,MAAM,OAAO;CACzC,OAAQ,MAAM,gBACZ,OACA;EAAE,GAAI,gBAAgB,CAAC;EAAI,sBAAsB;CAAe,GAChE,WACF;AACF;;;;;;;;;AAUA,IAAa,0BAAb,MAAa,wBAAwB;CACnC;CACA;CACA;;;;CAKA,OAAc,cAAuB;EACnC,OACE,OAAO,WAAW,cAAc,eAChC,SAAS,WAAW,aACpB,OAAQ,WAAW,UAAgC,QAAQ;CAE/D;;;;;;CAOA,YAAY,SAAkB;EAC5B,KAAKA,WAAW,gBAAgB,OAAO;EACvC,KAAKC,UAAU,KAAKD,SAAS;CAC/B;;CAGA,IAAI,aAAiC;EACnC,OAAO,KAAKA,SAAS;CACvB;;CAGA,cAAuB;EACrB,QAAQ,KAAKA,SAAS,qBAAqB,wBAAwB,aAAa;CAClF;;;;;;;;CASA,MAAM,UAAyB;EAC7B,MAAM,KAAKE,eAAe;CAC5B;;CAGA,QAAc;EACZ,KAAKD,UAAU,KAAA;EACf,KAAKE,iBAAiB,KAAA;CACxB;CAEA,MAAMD,iBAAkD;EACtD,IAAI,KAAKD,SAAS,OAAO,KAAKA;EAC9B,IAAI,CAAC,KAAK,YAAY,GACpB,MAAM,IAAI,oCAAoC,CAC5C,uDACF,CAAC;EAEH,KAAKE,oBAAoB,YAAY;GACnC,MAAM,eAAe,KAAKH,SAAS,gBAAgB;GACnD,IAAI;IACF,MAAM,SAAS,MAAM,aAAa;KAChC,OAAO,KAAKA,SAAS;KACrB,cAAc,KAAKA,SAAS;KAC5B,aAAa,KAAKA,SAAS;KAC3B,gBAAgB,KAAKA,SAAS;IAChC,CAAC;IACD,KAAKC,UAAU;IACf,OAAO;GACT,SAAS,KAAK;IAEZ,KAAKE,iBAAiB,KAAA;IACtB,MAAM,IAAI,iCAAiC,CAAC,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,CAAC,CAAC;GACvF;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,SAAS,MAAM,KAAKE,eAAe;EAEzC,IAAI;EACJ,IAAI;GACF,WAAW,MAAM,OAAO,WAAW,OAAO;IAAE,OAAO,KAAKF,SAAS;IAAO;GAAM,CAAC;EACjF,SAAS,KAAK;GACZ,MAAM,IAAI,iCAAiC,CAAC,QAAQ,GAAG,IAAI,IAAI,UAAU,OAAO,GAAG,CAAC,CAAC;EACvF;EAEA,IAAI,CAAC,YAAY,CAAC,MAAM,QAAQ,SAAS,IAAI,KAAK,SAAS,KAAK,WAAW,MAAM,QAC/E,MAAM,IAAI,iCAAiC,CACzC,YAAY,MAAM,OAAO,gBAAgB,UAAU,MAAM,UAAU,QACrE,CAAC;EAEH,OAAO,SAAS,KACb,MAAM,EACN,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,KAAK,EAChC,KAAK,MAAM,EAAE,SAAS;CAC3B;AACF"}

package/batteries/embeddings/webllm/exceptions.cjs

@@ -0,0 +1,31 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../chunk-Ble4zEEl.js");
+const require_exceptions = require("../../../exceptions-CitH5wZI.js");
+require("../../../factories.cjs");
+//#region src/batteries/embeddings/webllm/exceptions.ts
+/**
+* Battery-scoped exception constructors for WebLLM Embeddings adapter failures.
+*
+* @module @nhtio/adk/batteries/embeddings/webllm/exceptions
+*
+* @remarks
+* Battery-scoped exception classes for the WebLLM Embeddings adapter, minted via `createException`
+* from `@nhtio/adk/factories`. The categories mirror the OpenAI Embeddings battery one-to-one —
+* only the engine-specific failure exception differs (engine error vs HTTP error).
+*/
+/**
+* Thrown when the resolved adapter options fail validation against
+* `webLLMEmbeddingsOptionsSchema` — e.g. a missing/empty `model`, an unknown option key, or no
+* WebGPU support in the current runtime. Fatal: config bugs fail loud, not at embed time.
+*/
+var E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS = require_exceptions.createException("E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS", "Invalid WebLLM Embeddings adapter options: %s", "E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS", 529, true);
+/**
+* Thrown when the WebLLM engine fails to load or `engine.embeddings.create()` throws/returns a
+* malformed result. Non-fatal. Printf arg: `[detail]`.
+*/
+var E_WEBLLM_EMBEDDINGS_ENGINE_ERROR = require_exceptions.createException("E_WEBLLM_EMBEDDINGS_ENGINE_ERROR", "WebLLM Embeddings engine error: %s", "E_WEBLLM_EMBEDDINGS_ENGINE_ERROR", 502, false);
+//#endregion
+exports.E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS = E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS;
+exports.E_WEBLLM_EMBEDDINGS_ENGINE_ERROR = E_WEBLLM_EMBEDDINGS_ENGINE_ERROR;
+
+//# sourceMappingURL=exceptions.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.cjs","names":[],"sources":["../../../../src/batteries/embeddings/webllm/exceptions.ts"],"sourcesContent":["/**\n * Battery-scoped exception constructors for WebLLM Embeddings adapter failures.\n *\n * @module @nhtio/adk/batteries/embeddings/webllm/exceptions\n *\n * @remarks\n * Battery-scoped exception classes for the WebLLM Embeddings adapter, minted via `createException`\n * from `@nhtio/adk/factories`. The categories mirror the OpenAI Embeddings battery one-to-one —\n * only the engine-specific failure exception differs (engine error vs HTTP error).\n */\n\nimport { createException } from '@nhtio/adk/factories'\n\n/**\n * Thrown when the resolved adapter options fail validation against\n * `webLLMEmbeddingsOptionsSchema` — e.g. a missing/empty `model`, an unknown option key, or no\n * WebGPU support in the current runtime. Fatal: config bugs fail loud, not at embed time.\n */\nexport const E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS = createException<[string]>(\n  'E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS',\n  'Invalid WebLLM Embeddings adapter options: %s',\n  'E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS',\n  529,\n  true\n)\n\n/**\n * Thrown when the WebLLM engine fails to load or `engine.embeddings.create()` throws/returns a\n * malformed result. Non-fatal. Printf arg: `[detail]`.\n */\nexport const E_WEBLLM_EMBEDDINGS_ENGINE_ERROR = createException<[string]>(\n  'E_WEBLLM_EMBEDDINGS_ENGINE_ERROR',\n  'WebLLM Embeddings engine error: %s',\n  'E_WEBLLM_EMBEDDINGS_ENGINE_ERROR',\n  502,\n  false\n)\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAkBA,IAAa,sCAAsC,mBAAA,gBACjD,uCACA,iDACA,uCACA,KACA,IACF;;;;;AAMA,IAAa,mCAAmC,mBAAA,gBAC9C,oCACA,sCACA,oCACA,KACA,KACF"}

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

@@ -0,0 +1,25 @@
+/**
+ * Battery-scoped exception constructors for WebLLM Embeddings adapter failures.
+ *
+ * @module @nhtio/adk/batteries/embeddings/webllm/exceptions
+ *
+ * @remarks
+ * Battery-scoped exception classes for the WebLLM Embeddings adapter, minted via `createException`
+ * from `@nhtio/adk/factories`. The categories mirror the OpenAI Embeddings battery one-to-one —
+ * only the engine-specific failure exception differs (engine error vs HTTP error).
+ */
+/**
+ * Thrown when the resolved adapter options fail validation against
+ * `webLLMEmbeddingsOptionsSchema` — e.g. a missing/empty `model`, an unknown option key, or no
+ * WebGPU support in the current runtime. Fatal: config bugs fail loud, not at embed time.
+ */
+export declare const E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS: import("../../../factories").CreatedException<[
+    string
+]>;
+/**
+ * Thrown when the WebLLM engine fails to load or `engine.embeddings.create()` throws/returns a
+ * malformed result. Non-fatal. Printf arg: `[detail]`.
+ */
+export declare const E_WEBLLM_EMBEDDINGS_ENGINE_ERROR: import("../../../factories").CreatedException<[
+    string
+]>;

package/batteries/embeddings/webllm/exceptions.mjs

@@ -0,0 +1,28 @@
+import { t as createException } from "../../../exceptions-BeWH2FwP.mjs";
+import "../../../factories.mjs";
+//#region src/batteries/embeddings/webllm/exceptions.ts
+/**
+* Battery-scoped exception constructors for WebLLM Embeddings adapter failures.
+*
+* @module @nhtio/adk/batteries/embeddings/webllm/exceptions
+*
+* @remarks
+* Battery-scoped exception classes for the WebLLM Embeddings adapter, minted via `createException`
+* from `@nhtio/adk/factories`. The categories mirror the OpenAI Embeddings battery one-to-one —
+* only the engine-specific failure exception differs (engine error vs HTTP error).
+*/
+/**
+* Thrown when the resolved adapter options fail validation against
+* `webLLMEmbeddingsOptionsSchema` — e.g. a missing/empty `model`, an unknown option key, or no
+* WebGPU support in the current runtime. Fatal: config bugs fail loud, not at embed time.
+*/
+var E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS = createException("E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS", "Invalid WebLLM Embeddings adapter options: %s", "E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS", 529, true);
+/**
+* Thrown when the WebLLM engine fails to load or `engine.embeddings.create()` throws/returns a
+* malformed result. Non-fatal. Printf arg: `[detail]`.
+*/
+var E_WEBLLM_EMBEDDINGS_ENGINE_ERROR = createException("E_WEBLLM_EMBEDDINGS_ENGINE_ERROR", "WebLLM Embeddings engine error: %s", "E_WEBLLM_EMBEDDINGS_ENGINE_ERROR", 502, false);
+//#endregion
+export { E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS, E_WEBLLM_EMBEDDINGS_ENGINE_ERROR };
+
+//# sourceMappingURL=exceptions.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.mjs","names":[],"sources":["../../../../src/batteries/embeddings/webllm/exceptions.ts"],"sourcesContent":["/**\n * Battery-scoped exception constructors for WebLLM Embeddings adapter failures.\n *\n * @module @nhtio/adk/batteries/embeddings/webllm/exceptions\n *\n * @remarks\n * Battery-scoped exception classes for the WebLLM Embeddings adapter, minted via `createException`\n * from `@nhtio/adk/factories`. The categories mirror the OpenAI Embeddings battery one-to-one —\n * only the engine-specific failure exception differs (engine error vs HTTP error).\n */\n\nimport { createException } from '@nhtio/adk/factories'\n\n/**\n * Thrown when the resolved adapter options fail validation against\n * `webLLMEmbeddingsOptionsSchema` — e.g. a missing/empty `model`, an unknown option key, or no\n * WebGPU support in the current runtime. Fatal: config bugs fail loud, not at embed time.\n */\nexport const E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS = createException<[string]>(\n  'E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS',\n  'Invalid WebLLM Embeddings adapter options: %s',\n  'E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS',\n  529,\n  true\n)\n\n/**\n * Thrown when the WebLLM engine fails to load or `engine.embeddings.create()` throws/returns a\n * malformed result. Non-fatal. Printf arg: `[detail]`.\n */\nexport const E_WEBLLM_EMBEDDINGS_ENGINE_ERROR = createException<[string]>(\n  'E_WEBLLM_EMBEDDINGS_ENGINE_ERROR',\n  'WebLLM Embeddings engine error: %s',\n  'E_WEBLLM_EMBEDDINGS_ENGINE_ERROR',\n  502,\n  false\n)\n"],"mappings":";;;;;;;;;;;;;;;;;;AAkBA,IAAa,sCAAsC,gBACjD,uCACA,iDACA,uCACA,KACA,IACF;;;;;AAMA,IAAa,mCAAmC,gBAC9C,oCACA,sCACA,oCACA,KACA,KACF"}

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

@@ -0,0 +1,15 @@
+/**
+ * WebLLM Embeddings adapter battery — WebGPU/in-process embeddings via `@mlc-ai/web-llm`.
+ *
+ * @module @nhtio/adk/batteries/embeddings/webllm
+ *
+ * @remarks
+ * Browser/WebGPU-only, so reachable solely through this subpath (never re-exported from the
+ * environment-neutral `@nhtio/adk/batteries/embeddings` barrel). Re-exports the adapter class, the
+ * validation schema + `validateOptions` wrapper, every option / engine type alias (including the
+ * shared base shapes re-exported from the OpenAI battery), and the battery-scoped exceptions.
+ */
+export { WebLLMEmbeddingsAdapter } from "./adapter";
+export { webLLMEmbeddingsOptionsSchema, validateOptions } from "./validation";
+export type { EmbeddingKind, EmbedOptions, BaseEmbeddingsAdapterOptions, WebLLMEmbeddingsAdapterOptions, WebLLMEmbeddingsEngine, WebLLMEmbeddingsInitProgressReport, CreateWebLLMEmbeddingsEngine, } from "./types";
+export { E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS, E_WEBLLM_EMBEDDINGS_ENGINE_ERROR } from "./exceptions";

package/batteries/embeddings/webllm/types.cjs

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

package/batteries/embeddings/webllm/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Option and engine types for the WebLLM Embeddings adapter.
+ *
+ * @module @nhtio/adk/batteries/embeddings/webllm/types
+ *
+ * @remarks
+ * Builds on the **shared** embeddings option base owned by the OpenAI Embeddings battery
+ * ({@link @nhtio/adk/batteries/embeddings/openai/types!BaseEmbeddingsAdapterOptions}). The two
+ * batteries differ only in their engine: this one `Omit`s nothing from the base (the base carries
+ * no HTTP fields) and adds the WebGPU/MLC engine knobs — exactly how the WebLLM Chat Completions
+ * battery extends the OpenAI Chat Completions option type.
+ */
+import type { BaseEmbeddingsAdapterOptions } from "../openai/types";
+import type { ChatOptions, InitProgressReport, MLCEngineConfig, MLCEngineInterface } from '@mlc-ai/web-llm';
+export type { EmbeddingKind, EmbedOptions, BaseEmbeddingsAdapterOptions } from "../openai/types";
+/** The WebLLM engine handle this battery drives. Alias of `MLCEngineInterface`. */
+export type WebLLMEmbeddingsEngine = MLCEngineInterface;
+/** Progress report emitted while the engine loads weights. Alias of `InitProgressReport`. */
+export type WebLLMEmbeddingsInitProgressReport = InitProgressReport;
+/**
+ * Factory for lazily creating a WebLLM engine. Defaults to `CreateMLCEngine` from
+ * `@mlc-ai/web-llm`; override to inject a pre-configured engine, a web-worker engine, or a test
+ * double.
+ */
+export type CreateWebLLMEmbeddingsEngine = (input: {
+    model: string;
+    engineConfig?: MLCEngineConfig;
+    chatOptions?: ChatOptions | ChatOptions[];
+    onInitProgress?: (report: InitProgressReport) => void;
+}) => Promise<WebLLMEmbeddingsEngine>;
+/**
+ * Constructor options for {@link @nhtio/adk/batteries/embeddings/webllm/adapter!WebLLMEmbeddingsAdapter}.
+ *
+ * @remarks
+ * Extends the shared {@link BaseEmbeddingsAdapterOptions} (carrying the required `model` and the
+ * shared prefix options) with WebGPU/MLC engine fields. `model` accepts any MLC embedding model id
+ * (e.g. `snowflake-arctic-embed-m-q0f32-MLC`) — there is no default; the caller names it.
+ */
+export interface WebLLMEmbeddingsAdapterOptions extends BaseEmbeddingsAdapterOptions {
+    /** A pre-loaded engine. When provided, the battery uses it directly and skips lazy creation. */
+    engine?: WebLLMEmbeddingsEngine;
+    /** Override the engine factory. Default: `CreateMLCEngine` via a lazy dynamic import. */
+    createEngine?: CreateWebLLMEmbeddingsEngine;
+    /** Passed to `CreateMLCEngine` as the engine config (app config, cache, log level, etc.). */
+    engineConfig?: MLCEngineConfig;
+    /** Passed to `CreateMLCEngine` as chat options (model-specific knobs). */
+    chatOptions?: ChatOptions | ChatOptions[];
+    /** Called with load-progress reports while weights download/compile. */
+    onInitProgress?: (report: InitProgressReport) => void;
+    /** Override the WebGPU availability probe. Default: checks `navigator.gpu`. */
+    isWebGPUAvailable?: () => boolean;
+}

package/batteries/embeddings/webllm/validation.cjs

@@ -0,0 +1,43 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../chunk-Ble4zEEl.js");
+require("../../../guards.cjs");
+const require_batteries_embeddings_webllm_exceptions = require("./exceptions.cjs");
+let _nhtio_validation = require("@nhtio/validation");
+//#region src/batteries/embeddings/webllm/validation.ts
+/**
+* Validator schema for `WebLLMEmbeddingsAdapterOptions`. Rejects unknown top-level keys.
+*/
+var webLLMEmbeddingsOptionsSchema = _nhtio_validation.validator.object({
+	model: _nhtio_validation.validator.string().min(1).required(),
+	queryPrefix: _nhtio_validation.validator.string().optional(),
+	documentPrefix: _nhtio_validation.validator.string().optional(),
+	dimensions: _nhtio_validation.validator.number().integer().min(1).optional(),
+	engine: _nhtio_validation.validator.object().unknown(true).optional(),
+	createEngine: _nhtio_validation.validator.function().optional(),
+	engineConfig: _nhtio_validation.validator.object().unknown(true).optional(),
+	chatOptions: _nhtio_validation.validator.alternatives(_nhtio_validation.validator.object().unknown(true), _nhtio_validation.validator.array().items(_nhtio_validation.validator.object().unknown(true))).optional(),
+	onInitProgress: _nhtio_validation.validator.function().optional(),
+	isWebGPUAvailable: _nhtio_validation.validator.function().optional()
+}).unknown(false);
+var formatValidationDetails = (err) => err.details.map((d) => d.message).join(" and ");
+/**
+* Validates an arbitrary input against `webLLMEmbeddingsOptionsSchema` and returns the resolved
+* options shape. Throws `E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS` (carrying the validator's report on
+* `cause`) on failure.
+*
+* @param input - The raw options object to validate.
+* @returns The resolved options object with defaults filled in.
+*/
+var validateOptions = (input) => {
+	const { value, error } = webLLMEmbeddingsOptionsSchema.validate(input, {
+		abortEarly: false,
+		convert: false
+	});
+	if (error) throw new require_batteries_embeddings_webllm_exceptions.E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS([formatValidationDetails(error)], { cause: error });
+	return value;
+};
+//#endregion
+exports.validateOptions = validateOptions;
+exports.webLLMEmbeddingsOptionsSchema = webLLMEmbeddingsOptionsSchema;
+
+//# sourceMappingURL=validation.cjs.map

package/batteries/embeddings/webllm/validation.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.cjs","names":[],"sources":["../../../../src/batteries/embeddings/webllm/validation.ts"],"sourcesContent":["/**\n * Runtime validation schema and wrapper for WebLLM Embeddings adapter options.\n *\n * @module @nhtio/adk/batteries/embeddings/webllm/validation\n *\n * @remarks\n * Validates `WebLLMEmbeddingsAdapterOptions` at construction time. Throws\n * `E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS` on failure. `model` is required; unknown top-level keys\n * are rejected so typos fail loud. WebGPU availability is checked at engine-resolution time (not\n * here), since an `engine` may be injected for tests/non-WebGPU paths.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { validator, ValidationError } from '@nhtio/validation'\nimport { E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS } from './exceptions'\nimport type { WebLLMEmbeddingsAdapterOptions } from './types'\n\n/**\n * Validator schema for `WebLLMEmbeddingsAdapterOptions`. Rejects unknown top-level keys.\n */\nexport const webLLMEmbeddingsOptionsSchema = validator\n  .object<WebLLMEmbeddingsAdapterOptions>({\n    // Shared base\n    model: validator.string().min(1).required(),\n    queryPrefix: validator.string().optional(),\n    documentPrefix: validator.string().optional(),\n    dimensions: validator.number().integer().min(1).optional(),\n    // Engine knobs\n    engine: validator.object().unknown(true).optional(),\n    createEngine: validator.function().optional(),\n    engineConfig: validator.object().unknown(true).optional(),\n    chatOptions: validator\n      .alternatives(\n        validator.object().unknown(true),\n        validator.array().items(validator.object().unknown(true))\n      )\n      .optional(),\n    onInitProgress: validator.function().optional(),\n    isWebGPUAvailable: validator.function().optional(),\n  })\n  .unknown(false)\n\nconst formatValidationDetails = (err: ValidationError): string =>\n  err.details.map((d) => d.message).join(' and ')\n\n/**\n * Validates an arbitrary input against `webLLMEmbeddingsOptionsSchema` and returns the resolved\n * options shape. Throws `E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS` (carrying the validator's report on\n * `cause`) on failure.\n *\n * @param input - The raw options object to validate.\n * @returns The resolved options object with defaults filled in.\n */\nexport const validateOptions = (input: unknown): WebLLMEmbeddingsAdapterOptions => {\n  const { value, error } = webLLMEmbeddingsOptionsSchema.validate(input, {\n    abortEarly: false,\n    convert: false,\n  })\n  if (error) {\n    throw new E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS([formatValidationDetails(error)], {\n      cause: error,\n    })\n  }\n  return value as WebLLMEmbeddingsAdapterOptions\n}\n\nconst isValidationError = (value: unknown): value is ValidationError =>\n  isError(value) && Array.isArray((value as ValidationError).details)\n\nvoid isValidationError\n"],"mappings":";;;;;;;;;AAoBA,IAAa,gCAAgC,kBAAA,UAC1C,OAAuC;CAEtC,OAAO,kBAAA,UAAU,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS;CAC1C,aAAa,kBAAA,UAAU,OAAO,EAAE,SAAS;CACzC,gBAAgB,kBAAA,UAAU,OAAO,EAAE,SAAS;CAC5C,YAAY,kBAAA,UAAU,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,SAAS;CAEzD,QAAQ,kBAAA,UAAU,OAAO,EAAE,QAAQ,IAAI,EAAE,SAAS;CAClD,cAAc,kBAAA,UAAU,SAAS,EAAE,SAAS;CAC5C,cAAc,kBAAA,UAAU,OAAO,EAAE,QAAQ,IAAI,EAAE,SAAS;CACxD,aAAa,kBAAA,UACV,aACC,kBAAA,UAAU,OAAO,EAAE,QAAQ,IAAI,GAC/B,kBAAA,UAAU,MAAM,EAAE,MAAM,kBAAA,UAAU,OAAO,EAAE,QAAQ,IAAI,CAAC,CAC1D,EACC,SAAS;CACZ,gBAAgB,kBAAA,UAAU,SAAS,EAAE,SAAS;CAC9C,mBAAmB,kBAAA,UAAU,SAAS,EAAE,SAAS;AACnD,CAAC,EACA,QAAQ,KAAK;AAEhB,IAAM,2BAA2B,QAC/B,IAAI,QAAQ,KAAK,MAAM,EAAE,OAAO,EAAE,KAAK,OAAO;;;;;;;;;AAUhD,IAAa,mBAAmB,UAAmD;CACjF,MAAM,EAAE,OAAO,UAAU,8BAA8B,SAAS,OAAO;EACrE,YAAY;EACZ,SAAS;CACX,CAAC;CACD,IAAI,OACF,MAAM,IAAI,+CAAA,oCAAoC,CAAC,wBAAwB,KAAK,CAAC,GAAG,EAC9E,OAAO,MACT,CAAC;CAEH,OAAO;AACT"}