@nhtio/adk 1.20260625.1 → 1.20260626.0

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

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

package/batteries/embeddings/transformers_js/pooling.mjs

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

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

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

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

@@ -12,9 +12,11 @@
  * Pipeline/dtype/device shapes are **local aliases** of `@huggingface/transformers` types, never
  * direct re-exports of the externalized peer.
  */
+import type { BatteryLifecycleHooks } from "../../llm/chat_common/index";
 import type { BaseEmbeddingsAdapterOptions } from "../openai/types";
 import type { FeatureExtractionPipeline, DataType as TransformersDataType, DeviceType as TransformersDeviceType, ProgressCallback } from '@huggingface/transformers';
 export type { EmbeddingKind, EmbedOptions, BaseEmbeddingsAdapterOptions } from "../openai/types";
+export type { BatteryLifecyclePhase, BatteryLifecycleBattery, BatteryLifecycleReport, BatteryLifecycleCallback, BatteryLifecycleHooks, } from "../../llm/chat_common/index";
 /** The transformers.js feature-extraction pipeline this battery drives. */
 export type TransformersJsEmbeddingsPipeline = FeatureExtractionPipeline;
 /** Quantization/precision dtype: `'auto'|'fp32'|'fp16'|'q8'|'q4'|…`. */
@@ -25,6 +27,25 @@ export type TransformersJsEmbeddingsDeviceType = TransformersDeviceType;
 export type TransformersJsEmbeddingsProgressCallback = ProgressCallback;
 /** The pooling method applied to the model's per-token hidden states to produce one sentence vector. */
 export type TransformersJsPooling = 'none' | 'mean' | 'cls' | 'first_token' | 'eos' | 'last_token';
+/**
+ * Who applies pooling + L2-normalization:
+ * - `'engine'` (default) — the transformers.js pipeline pools internally (today's exact behavior). Each
+ *   runtime (node-ONNX vs web-ONNX/WebGPU) pools its own way, contributing to the node↔browser vector
+ *   gap.
+ * - `'battery'` — request raw `pooling:'none'` token states and pool + normalize in deterministic shared
+ *   JS (one implementation, identical across node + browser), removing post-processing variance and
+ *   leaving only the irreducible ORT-kernel floor. `pooling`/`normalize` then take effect in OUR code.
+ */
+export type TransformersJsPoolingOwner = 'engine' | 'battery';
+/**
+ * Custom model-source resolver — the dual-environment seam for serving model files from OPFS, a
+ * different source, or bundled bytes (see the LLM battery's `model_source` module). Called once per
+ * file; return bytes / a path-or-URL string / a `Response`, or `undefined` to fall through to HF.
+ */
+export type TransformersJsEmbeddingsModelSource = (req: {
+    repo: string;
+    filename: string;
+}) => Promise<Uint8Array | string | Response | undefined> | Uint8Array | string | Response | undefined;
 /**
  * Factory for lazily creating a feature-extraction pipeline. Defaults to a dynamic import of
  * `@huggingface/transformers` + `pipeline('feature-extraction', …)`; override to inject a pre-built
@@ -44,7 +65,7 @@ export type CreateTransformersJsEmbeddingsPipeline = (input: {
  * transformers.js pipeline fields. `model` accepts any ONNX feature-extraction model id (e.g.
  * `onnx-community/all-MiniLM-L6-v2-ONNX`) — there is no default.
  */
-export interface TransformersJsEmbeddingsAdapterOptions extends BaseEmbeddingsAdapterOptions {
+export interface TransformersJsEmbeddingsAdapterOptions extends BaseEmbeddingsAdapterOptions, BatteryLifecycleHooks {
     /** A pre-built pipeline. When provided, the battery uses it directly and skips lazy creation. */
     pipeline?: TransformersJsEmbeddingsPipeline;
     /** Override the pipeline factory. Default: `pipeline('feature-extraction', …)` via dynamic import. */
@@ -57,6 +78,18 @@ export interface TransformersJsEmbeddingsAdapterOptions extends BaseEmbeddingsAd
     pooling?: TransformersJsPooling;
     /** L2-normalise the embeddings (default `true`). */
     normalize?: boolean;
+    /**
+     * Who pools + normalizes (default `'engine'` — today's behavior, byte-identical). Set `'battery'` to
+     * pool + L2-normalize in deterministic shared JS for tighter node↔browser parity. See
+     * {@link TransformersJsPoolingOwner}.
+     */
+    poolingOwner?: TransformersJsPoolingOwner;
+    /**
+     * Custom model-source resolver (OPFS / separate source / bundled bytes). When set, model files load
+     * through it behind the global-`env` mutex; otherwise straight from HF (unchanged). See
+     * {@link TransformersJsEmbeddingsModelSource}.
+     */
+    modelSource?: TransformersJsEmbeddingsModelSource;
     /** Called with model-load progress reports while weights download/compile. */
     onInitProgress?: TransformersJsEmbeddingsProgressCallback;
     /** Override the availability probe. Default: `true` whenever the peer is importable (env-neutral). */

package/batteries/embeddings/transformers_js/validation.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_batteries_embeddings_transformers_js_exceptions = require("./exceptions.cjs");
 let _nhtio_validation = require("@nhtio/validation");
@@ -27,8 +27,17 @@ var transformersJsEmbeddingsOptionsSchema = _nhtio_validation.validator.object({
 	dtype: _nhtio_validation.validator.string().optional(),
 	pooling: _nhtio_validation.validator.string().valid("none", "mean", "cls", "first_token", "eos", "last_token").default("mean"),
 	normalize: _nhtio_validation.validator.boolean().default(true),
+	poolingOwner: _nhtio_validation.validator.string().valid("engine", "battery").default("engine"),
+	modelSource: _nhtio_validation.validator.function().optional(),
 	onInitProgress: _nhtio_validation.validator.function().optional(),
-	isAvailable: _nhtio_validation.validator.function().optional()
+	isAvailable: _nhtio_validation.validator.function().optional(),
+	onLifecycle: _nhtio_validation.validator.function().optional(),
+	onLoading: _nhtio_validation.validator.function().optional(),
+	onCompiling: _nhtio_validation.validator.function().optional(),
+	onReady: _nhtio_validation.validator.function().optional(),
+	onGenerating: _nhtio_validation.validator.function().optional(),
+	onComplete: _nhtio_validation.validator.function().optional(),
+	onError: _nhtio_validation.validator.function().optional()
 }).unknown(false);
 var isValidationError = (value) => require_tool_registry.isError(value) && Array.isArray(value.details);
 var formatValidationDetails = (err) => err.details.map((d) => d.message).join(" and ");

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

@@ -1 +1 @@
-{"version":3,"file":"validation.cjs","names":[],"sources":["../../../../src/batteries/embeddings/transformers_js/validation.ts"],"sourcesContent":["/**\n * Runtime validation schema and wrapper for transformers.js Embeddings adapter options.\n *\n * @module @nhtio/adk/batteries/embeddings/transformers_js/validation\n *\n * @remarks\n * Validates `TransformersJsEmbeddingsAdapterOptions` at construction time. Throws\n * `E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS` on failure. `model` is required; unknown top-level\n * keys are rejected so typos fail loud.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { validator, ValidationError } from '@nhtio/validation'\nimport { E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS } from './exceptions'\nimport type { TransformersJsEmbeddingsAdapterOptions } from './types'\n\n/** Validator schema for `TransformersJsEmbeddingsAdapterOptions`. Rejects unknown top-level keys. */\nexport const transformersJsEmbeddingsOptionsSchema = validator\n  .object<TransformersJsEmbeddingsAdapterOptions>({\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    // Pipeline knobs (the transformers.js pipeline is a callable object — accept function or object)\n    pipeline: validator\n      .alternatives(validator.function(), validator.object().unknown(true))\n      .optional(),\n    createPipeline: validator.function().optional(),\n    device: validator.string().optional(),\n    dtype: validator.string().optional(),\n    pooling: validator\n      .string()\n      .valid('none', 'mean', 'cls', 'first_token', 'eos', 'last_token')\n      .default('mean'),\n    normalize: validator.boolean().default(true),\n    onInitProgress: validator.function().optional(),\n    isAvailable: validator.function().optional(),\n  })\n  .unknown(false)\n\nconst isValidationError = (value: unknown): value is ValidationError =>\n  isError(value) && Array.isArray((value as ValidationError).details)\n\nconst formatValidationDetails = (err: ValidationError): string =>\n  err.details.map((d) => d.message).join(' and ')\n\n/**\n * Validates an arbitrary input against `transformersJsEmbeddingsOptionsSchema`.\n *\n * @param input - The raw options object to validate.\n * @returns The resolved options object with defaults filled in.\n * @throws {@link @nhtio/adk/batteries!E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS} when invalid.\n */\nexport const validateOptions = (input: unknown): TransformersJsEmbeddingsAdapterOptions => {\n  const { value, error } = transformersJsEmbeddingsOptionsSchema.validate(input, {\n    abortEarly: false,\n    convert: false,\n  })\n  if (error && isValidationError(error)) {\n    throw new E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS([formatValidationDetails(error)], {\n      cause: error,\n    })\n  }\n  return value as TransformersJsEmbeddingsAdapterOptions\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAiBA,IAAa,wCAAwC,kBAAA,UAClD,OAA+C;CAE9C,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,UAAU,kBAAA,UACP,aAAa,kBAAA,UAAU,SAAS,GAAG,kBAAA,UAAU,OAAO,EAAE,QAAQ,IAAI,CAAC,EACnE,SAAS;CACZ,gBAAgB,kBAAA,UAAU,SAAS,EAAE,SAAS;CAC9C,QAAQ,kBAAA,UAAU,OAAO,EAAE,SAAS;CACpC,OAAO,kBAAA,UAAU,OAAO,EAAE,SAAS;CACnC,SAAS,kBAAA,UACN,OAAO,EACP,MAAM,QAAQ,QAAQ,OAAO,eAAe,OAAO,YAAY,EAC/D,QAAQ,MAAM;CACjB,WAAW,kBAAA,UAAU,QAAQ,EAAE,QAAQ,IAAI;CAC3C,gBAAgB,kBAAA,UAAU,SAAS,EAAE,SAAS;CAC9C,aAAa,kBAAA,UAAU,SAAS,EAAE,SAAS;AAC7C,CAAC,EACA,QAAQ,KAAK;AAEhB,IAAM,qBAAqB,UACzB,sBAAA,QAAQ,KAAK,KAAK,MAAM,QAAS,MAA0B,OAAO;AAEpE,IAAM,2BAA2B,QAC/B,IAAI,QAAQ,KAAK,MAAM,EAAE,OAAO,EAAE,KAAK,OAAO;;;;;;;;AAShD,IAAa,mBAAmB,UAA2D;CACzF,MAAM,EAAE,OAAO,UAAU,sCAAsC,SAAS,OAAO;EAC7E,YAAY;EACZ,SAAS;CACX,CAAC;CACD,IAAI,SAAS,kBAAkB,KAAK,GAClC,MAAM,IAAI,wDAAA,6CAA6C,CAAC,wBAAwB,KAAK,CAAC,GAAG,EACvF,OAAO,MACT,CAAC;CAEH,OAAO;AACT"}
+{"version":3,"file":"validation.cjs","names":[],"sources":["../../../../src/batteries/embeddings/transformers_js/validation.ts"],"sourcesContent":["/**\n * Runtime validation schema and wrapper for transformers.js Embeddings adapter options.\n *\n * @module @nhtio/adk/batteries/embeddings/transformers_js/validation\n *\n * @remarks\n * Validates `TransformersJsEmbeddingsAdapterOptions` at construction time. Throws\n * `E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS` on failure. `model` is required; unknown top-level\n * keys are rejected so typos fail loud.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { validator, ValidationError } from '@nhtio/validation'\nimport { E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS } from './exceptions'\nimport type { TransformersJsEmbeddingsAdapterOptions } from './types'\n\n/** Validator schema for `TransformersJsEmbeddingsAdapterOptions`. Rejects unknown top-level keys. */\nexport const transformersJsEmbeddingsOptionsSchema = validator\n  .object<TransformersJsEmbeddingsAdapterOptions>({\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    // Pipeline knobs (the transformers.js pipeline is a callable object — accept function or object)\n    pipeline: validator\n      .alternatives(validator.function(), validator.object().unknown(true))\n      .optional(),\n    createPipeline: validator.function().optional(),\n    device: validator.string().optional(),\n    dtype: validator.string().optional(),\n    pooling: validator\n      .string()\n      .valid('none', 'mean', 'cls', 'first_token', 'eos', 'last_token')\n      .default('mean'),\n    normalize: validator.boolean().default(true),\n    poolingOwner: validator.string().valid('engine', 'battery').default('engine'),\n    modelSource: validator.function().optional(),\n    onInitProgress: validator.function().optional(),\n    isAvailable: validator.function().optional(),\n    // ── Lifecycle hooks (opt-in, normalized phase machine; additive over onInitProgress) ──\n    onLifecycle: validator.function().optional(),\n    onLoading: validator.function().optional(),\n    onCompiling: validator.function().optional(),\n    onReady: validator.function().optional(),\n    onGenerating: validator.function().optional(),\n    onComplete: validator.function().optional(),\n    onError: validator.function().optional(),\n  })\n  .unknown(false)\n\nconst isValidationError = (value: unknown): value is ValidationError =>\n  isError(value) && Array.isArray((value as ValidationError).details)\n\nconst formatValidationDetails = (err: ValidationError): string =>\n  err.details.map((d) => d.message).join(' and ')\n\n/**\n * Validates an arbitrary input against `transformersJsEmbeddingsOptionsSchema`.\n *\n * @param input - The raw options object to validate.\n * @returns The resolved options object with defaults filled in.\n * @throws {@link @nhtio/adk/batteries!E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS} when invalid.\n */\nexport const validateOptions = (input: unknown): TransformersJsEmbeddingsAdapterOptions => {\n  const { value, error } = transformersJsEmbeddingsOptionsSchema.validate(input, {\n    abortEarly: false,\n    convert: false,\n  })\n  if (error && isValidationError(error)) {\n    throw new E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS([formatValidationDetails(error)], {\n      cause: error,\n    })\n  }\n  return value as TransformersJsEmbeddingsAdapterOptions\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAiBA,IAAa,wCAAwC,kBAAA,UAClD,OAA+C;CAE9C,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,UAAU,kBAAA,UACP,aAAa,kBAAA,UAAU,SAAS,GAAG,kBAAA,UAAU,OAAO,EAAE,QAAQ,IAAI,CAAC,EACnE,SAAS;CACZ,gBAAgB,kBAAA,UAAU,SAAS,EAAE,SAAS;CAC9C,QAAQ,kBAAA,UAAU,OAAO,EAAE,SAAS;CACpC,OAAO,kBAAA,UAAU,OAAO,EAAE,SAAS;CACnC,SAAS,kBAAA,UACN,OAAO,EACP,MAAM,QAAQ,QAAQ,OAAO,eAAe,OAAO,YAAY,EAC/D,QAAQ,MAAM;CACjB,WAAW,kBAAA,UAAU,QAAQ,EAAE,QAAQ,IAAI;CAC3C,cAAc,kBAAA,UAAU,OAAO,EAAE,MAAM,UAAU,SAAS,EAAE,QAAQ,QAAQ;CAC5E,aAAa,kBAAA,UAAU,SAAS,EAAE,SAAS;CAC3C,gBAAgB,kBAAA,UAAU,SAAS,EAAE,SAAS;CAC9C,aAAa,kBAAA,UAAU,SAAS,EAAE,SAAS;CAE3C,aAAa,kBAAA,UAAU,SAAS,EAAE,SAAS;CAC3C,WAAW,kBAAA,UAAU,SAAS,EAAE,SAAS;CACzC,aAAa,kBAAA,UAAU,SAAS,EAAE,SAAS;CAC3C,SAAS,kBAAA,UAAU,SAAS,EAAE,SAAS;CACvC,cAAc,kBAAA,UAAU,SAAS,EAAE,SAAS;CAC5C,YAAY,kBAAA,UAAU,SAAS,EAAE,SAAS;CAC1C,SAAS,kBAAA,UAAU,SAAS,EAAE,SAAS;AACzC,CAAC,EACA,QAAQ,KAAK;AAEhB,IAAM,qBAAqB,UACzB,sBAAA,QAAQ,KAAK,KAAK,MAAM,QAAS,MAA0B,OAAO;AAEpE,IAAM,2BAA2B,QAC/B,IAAI,QAAQ,KAAK,MAAM,EAAE,OAAO,EAAE,KAAK,OAAO;;;;;;;;AAShD,IAAa,mBAAmB,UAA2D;CACzF,MAAM,EAAE,OAAO,UAAU,sCAAsC,SAAS,OAAO;EAC7E,YAAY;EACZ,SAAS;CACX,CAAC;CACD,IAAI,SAAS,kBAAkB,KAAK,GAClC,MAAM,IAAI,wDAAA,6CAA6C,CAAC,wBAAwB,KAAK,CAAC,GAAG,EACvF,OAAO,MACT,CAAC;CAEH,OAAO;AACT"}

package/batteries/embeddings/transformers_js/validation.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 { E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS } from "./exceptions.mjs";
 import { validator } from "@nhtio/validation";
@@ -25,8 +25,17 @@ var transformersJsEmbeddingsOptionsSchema = validator.object({
 	dtype: validator.string().optional(),
 	pooling: validator.string().valid("none", "mean", "cls", "first_token", "eos", "last_token").default("mean"),
 	normalize: validator.boolean().default(true),
+	poolingOwner: validator.string().valid("engine", "battery").default("engine"),
+	modelSource: validator.function().optional(),
 	onInitProgress: validator.function().optional(),
-	isAvailable: validator.function().optional()
+	isAvailable: validator.function().optional(),
+	onLifecycle: validator.function().optional(),
+	onLoading: validator.function().optional(),
+	onCompiling: validator.function().optional(),
+	onReady: validator.function().optional(),
+	onGenerating: validator.function().optional(),
+	onComplete: validator.function().optional(),
+	onError: validator.function().optional()
 }).unknown(false);
 var isValidationError = (value) => isError(value) && Array.isArray(value.details);
 var formatValidationDetails = (err) => err.details.map((d) => d.message).join(" and ");

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

@@ -1 +1 @@
-{"version":3,"file":"validation.mjs","names":[],"sources":["../../../../src/batteries/embeddings/transformers_js/validation.ts"],"sourcesContent":["/**\n * Runtime validation schema and wrapper for transformers.js Embeddings adapter options.\n *\n * @module @nhtio/adk/batteries/embeddings/transformers_js/validation\n *\n * @remarks\n * Validates `TransformersJsEmbeddingsAdapterOptions` at construction time. Throws\n * `E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS` on failure. `model` is required; unknown top-level\n * keys are rejected so typos fail loud.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { validator, ValidationError } from '@nhtio/validation'\nimport { E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS } from './exceptions'\nimport type { TransformersJsEmbeddingsAdapterOptions } from './types'\n\n/** Validator schema for `TransformersJsEmbeddingsAdapterOptions`. Rejects unknown top-level keys. */\nexport const transformersJsEmbeddingsOptionsSchema = validator\n  .object<TransformersJsEmbeddingsAdapterOptions>({\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    // Pipeline knobs (the transformers.js pipeline is a callable object — accept function or object)\n    pipeline: validator\n      .alternatives(validator.function(), validator.object().unknown(true))\n      .optional(),\n    createPipeline: validator.function().optional(),\n    device: validator.string().optional(),\n    dtype: validator.string().optional(),\n    pooling: validator\n      .string()\n      .valid('none', 'mean', 'cls', 'first_token', 'eos', 'last_token')\n      .default('mean'),\n    normalize: validator.boolean().default(true),\n    onInitProgress: validator.function().optional(),\n    isAvailable: validator.function().optional(),\n  })\n  .unknown(false)\n\nconst isValidationError = (value: unknown): value is ValidationError =>\n  isError(value) && Array.isArray((value as ValidationError).details)\n\nconst formatValidationDetails = (err: ValidationError): string =>\n  err.details.map((d) => d.message).join(' and ')\n\n/**\n * Validates an arbitrary input against `transformersJsEmbeddingsOptionsSchema`.\n *\n * @param input - The raw options object to validate.\n * @returns The resolved options object with defaults filled in.\n * @throws {@link @nhtio/adk/batteries!E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS} when invalid.\n */\nexport const validateOptions = (input: unknown): TransformersJsEmbeddingsAdapterOptions => {\n  const { value, error } = transformersJsEmbeddingsOptionsSchema.validate(input, {\n    abortEarly: false,\n    convert: false,\n  })\n  if (error && isValidationError(error)) {\n    throw new E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS([formatValidationDetails(error)], {\n      cause: error,\n    })\n  }\n  return value as TransformersJsEmbeddingsAdapterOptions\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,IAAa,wCAAwC,UAClD,OAA+C;CAE9C,OAAO,UAAU,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS;CAC1C,aAAa,UAAU,OAAO,EAAE,SAAS;CACzC,gBAAgB,UAAU,OAAO,EAAE,SAAS;CAC5C,YAAY,UAAU,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,SAAS;CAEzD,UAAU,UACP,aAAa,UAAU,SAAS,GAAG,UAAU,OAAO,EAAE,QAAQ,IAAI,CAAC,EACnE,SAAS;CACZ,gBAAgB,UAAU,SAAS,EAAE,SAAS;CAC9C,QAAQ,UAAU,OAAO,EAAE,SAAS;CACpC,OAAO,UAAU,OAAO,EAAE,SAAS;CACnC,SAAS,UACN,OAAO,EACP,MAAM,QAAQ,QAAQ,OAAO,eAAe,OAAO,YAAY,EAC/D,QAAQ,MAAM;CACjB,WAAW,UAAU,QAAQ,EAAE,QAAQ,IAAI;CAC3C,gBAAgB,UAAU,SAAS,EAAE,SAAS;CAC9C,aAAa,UAAU,SAAS,EAAE,SAAS;AAC7C,CAAC,EACA,QAAQ,KAAK;AAEhB,IAAM,qBAAqB,UACzB,QAAQ,KAAK,KAAK,MAAM,QAAS,MAA0B,OAAO;AAEpE,IAAM,2BAA2B,QAC/B,IAAI,QAAQ,KAAK,MAAM,EAAE,OAAO,EAAE,KAAK,OAAO;;;;;;;;AAShD,IAAa,mBAAmB,UAA2D;CACzF,MAAM,EAAE,OAAO,UAAU,sCAAsC,SAAS,OAAO;EAC7E,YAAY;EACZ,SAAS;CACX,CAAC;CACD,IAAI,SAAS,kBAAkB,KAAK,GAClC,MAAM,IAAI,6CAA6C,CAAC,wBAAwB,KAAK,CAAC,GAAG,EACvF,OAAO,MACT,CAAC;CAEH,OAAO;AACT"}
+{"version":3,"file":"validation.mjs","names":[],"sources":["../../../../src/batteries/embeddings/transformers_js/validation.ts"],"sourcesContent":["/**\n * Runtime validation schema and wrapper for transformers.js Embeddings adapter options.\n *\n * @module @nhtio/adk/batteries/embeddings/transformers_js/validation\n *\n * @remarks\n * Validates `TransformersJsEmbeddingsAdapterOptions` at construction time. Throws\n * `E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS` on failure. `model` is required; unknown top-level\n * keys are rejected so typos fail loud.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { validator, ValidationError } from '@nhtio/validation'\nimport { E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS } from './exceptions'\nimport type { TransformersJsEmbeddingsAdapterOptions } from './types'\n\n/** Validator schema for `TransformersJsEmbeddingsAdapterOptions`. Rejects unknown top-level keys. */\nexport const transformersJsEmbeddingsOptionsSchema = validator\n  .object<TransformersJsEmbeddingsAdapterOptions>({\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    // Pipeline knobs (the transformers.js pipeline is a callable object — accept function or object)\n    pipeline: validator\n      .alternatives(validator.function(), validator.object().unknown(true))\n      .optional(),\n    createPipeline: validator.function().optional(),\n    device: validator.string().optional(),\n    dtype: validator.string().optional(),\n    pooling: validator\n      .string()\n      .valid('none', 'mean', 'cls', 'first_token', 'eos', 'last_token')\n      .default('mean'),\n    normalize: validator.boolean().default(true),\n    poolingOwner: validator.string().valid('engine', 'battery').default('engine'),\n    modelSource: validator.function().optional(),\n    onInitProgress: validator.function().optional(),\n    isAvailable: validator.function().optional(),\n    // ── Lifecycle hooks (opt-in, normalized phase machine; additive over onInitProgress) ──\n    onLifecycle: validator.function().optional(),\n    onLoading: validator.function().optional(),\n    onCompiling: validator.function().optional(),\n    onReady: validator.function().optional(),\n    onGenerating: validator.function().optional(),\n    onComplete: validator.function().optional(),\n    onError: validator.function().optional(),\n  })\n  .unknown(false)\n\nconst isValidationError = (value: unknown): value is ValidationError =>\n  isError(value) && Array.isArray((value as ValidationError).details)\n\nconst formatValidationDetails = (err: ValidationError): string =>\n  err.details.map((d) => d.message).join(' and ')\n\n/**\n * Validates an arbitrary input against `transformersJsEmbeddingsOptionsSchema`.\n *\n * @param input - The raw options object to validate.\n * @returns The resolved options object with defaults filled in.\n * @throws {@link @nhtio/adk/batteries!E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS} when invalid.\n */\nexport const validateOptions = (input: unknown): TransformersJsEmbeddingsAdapterOptions => {\n  const { value, error } = transformersJsEmbeddingsOptionsSchema.validate(input, {\n    abortEarly: false,\n    convert: false,\n  })\n  if (error && isValidationError(error)) {\n    throw new E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS([formatValidationDetails(error)], {\n      cause: error,\n    })\n  }\n  return value as TransformersJsEmbeddingsAdapterOptions\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,IAAa,wCAAwC,UAClD,OAA+C;CAE9C,OAAO,UAAU,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS;CAC1C,aAAa,UAAU,OAAO,EAAE,SAAS;CACzC,gBAAgB,UAAU,OAAO,EAAE,SAAS;CAC5C,YAAY,UAAU,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,SAAS;CAEzD,UAAU,UACP,aAAa,UAAU,SAAS,GAAG,UAAU,OAAO,EAAE,QAAQ,IAAI,CAAC,EACnE,SAAS;CACZ,gBAAgB,UAAU,SAAS,EAAE,SAAS;CAC9C,QAAQ,UAAU,OAAO,EAAE,SAAS;CACpC,OAAO,UAAU,OAAO,EAAE,SAAS;CACnC,SAAS,UACN,OAAO,EACP,MAAM,QAAQ,QAAQ,OAAO,eAAe,OAAO,YAAY,EAC/D,QAAQ,MAAM;CACjB,WAAW,UAAU,QAAQ,EAAE,QAAQ,IAAI;CAC3C,cAAc,UAAU,OAAO,EAAE,MAAM,UAAU,SAAS,EAAE,QAAQ,QAAQ;CAC5E,aAAa,UAAU,SAAS,EAAE,SAAS;CAC3C,gBAAgB,UAAU,SAAS,EAAE,SAAS;CAC9C,aAAa,UAAU,SAAS,EAAE,SAAS;CAE3C,aAAa,UAAU,SAAS,EAAE,SAAS;CAC3C,WAAW,UAAU,SAAS,EAAE,SAAS;CACzC,aAAa,UAAU,SAAS,EAAE,SAAS;CAC3C,SAAS,UAAU,SAAS,EAAE,SAAS;CACvC,cAAc,UAAU,SAAS,EAAE,SAAS;CAC5C,YAAY,UAAU,SAAS,EAAE,SAAS;CAC1C,SAAS,UAAU,SAAS,EAAE,SAAS;AACzC,CAAC,EACA,QAAQ,KAAK;AAEhB,IAAM,qBAAqB,UACzB,QAAQ,KAAK,KAAK,MAAM,QAAS,MAA0B,OAAO;AAEpE,IAAM,2BAA2B,QAC/B,IAAI,QAAQ,KAAK,MAAM,EAAE,OAAO,EAAE,KAAK,OAAO;;;;;;;;AAShD,IAAa,mBAAmB,UAA2D;CACzF,MAAM,EAAE,OAAO,UAAU,sCAAsC,SAAS,OAAO;EAC7E,YAAY;EACZ,SAAS;CACX,CAAC;CACD,IAAI,SAAS,kBAAkB,KAAK,GAClC,MAAM,IAAI,6CAA6C,CAAC,wBAAwB,KAAK,CAAC,GAAG,EACvF,OAAO,MACT,CAAC;CAEH,OAAO;AACT"}

package/batteries/embeddings/transformers_js.cjs

@@ -1,10 +1,14 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../../chunk-Cek0wNdY.js");
+const require_batteries_embeddings_transformers_js_pooling = require("./transformers_js/pooling.cjs");
 const require_batteries_embeddings_transformers_js_exceptions = require("./transformers_js/exceptions.cjs");
 const require_batteries_embeddings_transformers_js_validation = require("./transformers_js/validation.cjs");
 const require_batteries_embeddings_transformers_js_adapter = require("./transformers_js/adapter.cjs");
 exports.E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS = require_batteries_embeddings_transformers_js_exceptions.E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS;
 exports.E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR = require_batteries_embeddings_transformers_js_exceptions.E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR;
 exports.TransformersJsEmbeddingsAdapter = require_batteries_embeddings_transformers_js_adapter.TransformersJsEmbeddingsAdapter;
+exports.defaultPoolAndNormalize = require_batteries_embeddings_transformers_js_pooling.defaultPoolAndNormalize;
+exports.l2Normalize = require_batteries_embeddings_transformers_js_pooling.l2Normalize;
+exports.poolAndNormalize = require_batteries_embeddings_transformers_js_pooling.poolAndNormalize;
 exports.transformersJsEmbeddingsOptionsSchema = require_batteries_embeddings_transformers_js_validation.transformersJsEmbeddingsOptionsSchema;
 exports.validateOptions = require_batteries_embeddings_transformers_js_validation.validateOptions;

package/batteries/embeddings/transformers_js.mjs

@@ -1,4 +1,5 @@
+import { defaultPoolAndNormalize, l2Normalize, poolAndNormalize } from "./transformers_js/pooling.mjs";
 import { E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS, E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR } from "./transformers_js/exceptions.mjs";
 import { transformersJsEmbeddingsOptionsSchema, validateOptions } from "./transformers_js/validation.mjs";
 import { TransformersJsEmbeddingsAdapter } from "./transformers_js/adapter.mjs";
-export { E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS, E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR, TransformersJsEmbeddingsAdapter, transformersJsEmbeddingsOptionsSchema, validateOptions };
+export { E_INVALID_TRANSFORMERS_JS_EMBEDDINGS_OPTIONS, E_TRANSFORMERS_JS_EMBEDDINGS_ENGINE_ERROR, TransformersJsEmbeddingsAdapter, defaultPoolAndNormalize, l2Normalize, poolAndNormalize, transformersJsEmbeddingsOptionsSchema, validateOptions };

package/batteries/embeddings/webllm/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_batteries_embeddings_openai_helpers = require("../openai/helpers.cjs");
 const require_batteries_embeddings_webllm_exceptions = require("./exceptions.cjs");

package/batteries/embeddings/webllm/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 { applyEmbeddingPrefix } from "../openai/helpers.mjs";
 import { E_INVALID_WEBLLM_EMBEDDINGS_OPTIONS, E_WEBLLM_EMBEDDINGS_ENGINE_ERROR } from "./exceptions.mjs";

package/batteries/encoding.cjs

@@ -1,12 +1,12 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 require("../chunk-Cek0wNdY.js");
-const require_tool_registry = require("../tool_registry-CIIfbY_w.js");
-const require_thought = require("../thought-CU7PYkB1.js");
-const require_tool = require("../tool-Bt6tmFXT.js");
-const require_spooled_artifact = require("../spooled_artifact-MbMz6NXX.js");
-const require_common = require("../common-CpcsEqPY.js");
-const require_tool_call = require("../tool_call-BixyvnWZ.js");
-const require_spooled_markdown_artifact = require("../spooled_markdown_artifact-Gj0ruiLJ.js");
+const require_tool_registry = require("../tool_registry-DbS8Pem9.js");
+const require_thought = require("../thought-CE88bddw.js");
+const require_tool = require("../tool-BngpaOWb.js");
+const require_spooled_artifact = require("../spooled_artifact-DrIR90nV.js");
+const require_common = require("../common-ax3vKu6O.js");
+const require_tool_call = require("../tool_call-CZVmISyc.js");
+const require_spooled_markdown_artifact = require("../spooled_markdown_artifact-rg_WCNWq.js");
 require("../index.cjs");
 const require_batteries_storage_in_memory = require("./storage/in_memory.cjs");
 let _nhtio_encoder = require("@nhtio/encoder");

package/batteries/encoding.mjs

@@ -1,10 +1,10 @@
-import { a as Tokenizable, r as Registry, t as ToolRegistry } from "../tool_registry-FeMMz993.mjs";
-import { i as Identity, n as Message, r as Memory, t as Thought } from "../thought-DmcfCRAw.mjs";
-import { t as Tool } from "../tool-C_uxdxjp.mjs";
-import { a as resolveMediaReader, c as ArtifactTool, i as registerSpoolReaderResolver, o as resolveSpoolReader, r as registerMediaReaderResolver, t as SpooledArtifact } from "../spooled_artifact-fgc1lutm.mjs";
-import { a as inMemoryMediaReader, c as Retrievable, n as MEDIA_READER_TAG_IN_MEMORY, r as fromFetch, t as MEDIA_READER_TAG_FETCH } from "../common-0CmrSKNb.mjs";
-import { n as Media, o as decodeBase64, t as ToolCall } from "../tool_call-pfvAsgkY.mjs";
-import { n as SpooledJsonArtifact, t as SpooledMarkdownArtifact } from "../spooled_markdown_artifact-3sK6HFRw.mjs";
+import { i as Registry, r as Tokenizable, t as ToolRegistry } from "../tool_registry-Bj0JhXCv.mjs";
+import { i as Identity, n as Message, r as Memory, t as Thought } from "../thought-DdiQCpgX.mjs";
+import { t as Tool } from "../tool-asIfCjxb.mjs";
+import { a as resolveMediaReader, c as ArtifactTool, i as registerSpoolReaderResolver, o as resolveSpoolReader, r as registerMediaReaderResolver, t as SpooledArtifact } from "../spooled_artifact-BnbqIZ3a.mjs";
+import { a as inMemoryMediaReader, c as Retrievable, n as MEDIA_READER_TAG_IN_MEMORY, r as fromFetch, t as MEDIA_READER_TAG_FETCH } from "../common-DJH3UemH.mjs";
+import { n as Media, o as decodeBase64, t as ToolCall } from "../tool_call-TtzdXxcb.mjs";
+import { n as SpooledJsonArtifact, t as SpooledMarkdownArtifact } from "../spooled_markdown_artifact-BJH_JZFm.mjs";
 import "../index.mjs";
 import { InMemorySpoolReader, SPOOL_READER_TAG_IN_MEMORY } from "./storage/in_memory.mjs";
 import { registerClass } from "@nhtio/encoder";

package/batteries/llm/chat_common/generation.d.ts

@@ -0,0 +1,122 @@
+/**
+ * The portable, battery-agnostic GENERATION contract shared by the on-device LLM batteries.
+ *
+ * @remarks
+ * INTERNAL to the bundled LLM batteries — intentionally NOT `@module`-tagged, so it stays private and
+ * is inlined into each consumer by the bundler (the same convention as `chat_common/helpers.ts`).
+ *
+ * **Why this exists.** transformers.js and LiteRT-LM express the same generation concepts with different
+ * option names and shapes — `maxNewTokens` vs `maxOutputTokens`, a flat `doSample`+`temperature`/`topK`/
+ * `topP` vs a nested `samplerParams:{type,k,p,…}`, one `multimodal:{image,audio}` object vs two
+ * `visionModalityEnabled`/`audioModalityEnabled` booleans. Swapping batteries therefore meant rewriting
+ * the config. This module defines ONE canonical surface ({@link ChatGenerationOptions}) that both
+ * batteries accept; each adapter maps it onto its native API via {@link resolveGenerationOptions}.
+ *
+ * **Contract.** The canonical fields are additive — every native field a battery already exposed
+ * remains a working escape hatch. When BOTH a canonical field and its native equivalent are set, the
+ * **canonical value wins** (it is the portable intent; the native field is the low-level override that
+ * the resolver only consults when the canonical one is absent). All values carry the same
+ * deterministic-friendly defaults across batteries (greedy, temp 0.7, top-k 40, top-p 0.95, max 1024).
+ */
+/**
+ * The portable sampler strategy. Maps to each battery's native mechanism:
+ * - `'greedy'` — deterministic argmax. transformers.js `do_sample:false`; LiteRT `SamplerType.GREEDY`
+ *   (which is top-1, so `k` is forced to 1).
+ * - `'top-k'` — sample from the top-`k` logits. transformers.js `do_sample:true`+`top_k`; LiteRT
+ *   `SamplerType.TOP_K`+`k`.
+ * - `'top-p'` — nucleus sampling. transformers.js `do_sample:true`+`top_p`; LiteRT `SamplerType.TOP_P`+`p`.
+ */
+export type ChatSampler = 'greedy' | 'top-k' | 'top-p';
+/** The canonical generation options both on-device batteries accept. Every field optional + defaulted. */
+export interface ChatGenerationOptions {
+    /**
+     * Maximum tokens to GENERATE this turn. The portable spelling of transformers.js `maxNewTokens` /
+     * LiteRT `maxOutputTokens`. Default `1024`.
+     */
+    maxTokens?: number;
+    /** Sampler strategy (default `'greedy'` — deterministic). See {@link ChatSampler}. */
+    sampler?: ChatSampler;
+    /** Sampling temperature, used when `sampler` is `'top-k'`/`'top-p'`. Always pinned. Default `0.7`. */
+    temperature?: number;
+    /** Top-K cutoff, used when `sampler` is `'top-k'`. Default `40`. */
+    topK?: number;
+    /** Top-P (nucleus) cutoff, used when `sampler` is `'top-p'`. Default `0.95`. */
+    topP?: number;
+    /** RNG seed for reproducible sampling (best-effort; only honoured by batteries that expose it). */
+    seed?: number;
+    /**
+     * Whether to enable the model's "thinking"/reasoning mode, passed EXPLICITLY to the chat template.
+     * Default `false` — many reasoning templates default thinking ON and burn the budget. Already shared
+     * by both batteries under this exact name; restated here so the whole generation contract is in one place.
+     */
+    enableThinking?: boolean;
+    /**
+     * Enable multimodal input by kind. The portable spelling of transformers.js `multimodal:{image,audio}`
+     * / LiteRT `visionModalityEnabled`+`audioModalityEnabled`.
+     */
+    multimodal?: {
+        image?: boolean;
+        audio?: boolean;
+    };
+}
+/** The resolved, fully-defaulted generation config the adapters consume. */
+export interface ResolvedGenerationOptions {
+    /** Max tokens to generate this turn. */
+    maxTokens: number;
+    /** The resolved sampler strategy. */
+    sampler: ChatSampler;
+    /** Sampling temperature (used by `'top-k'`/`'top-p'`). */
+    temperature: number;
+    /** Top-K cutoff (used by `'top-k'`). */
+    topK: number;
+    /** Top-P (nucleus) cutoff (used by `'top-p'`). */
+    topP: number;
+    /** RNG seed, when provided. */
+    seed?: number;
+    /** Whether thinking/reasoning mode is enabled. */
+    enableThinking: boolean;
+    /** Resolved multimodal-input flags by kind. */
+    multimodal: {
+        image: boolean;
+        audio: boolean;
+    };
+}
+/** Deterministic-friendly defaults, identical across batteries. */
+export declare const GENERATION_DEFAULTS: ResolvedGenerationOptions;
+/**
+ * Resolve the canonical {@link ChatGenerationOptions} (already merged across option layers) into a
+ * fully-defaulted {@link ResolvedGenerationOptions}. Native per-battery fallbacks are passed via
+ * `nativeFallbacks` and consulted ONLY when the canonical field is absent (canonical wins). The adapter
+ * then maps the resolved shape onto its runtime API.
+ *
+ * @param canonical - The canonical fields from the merged adapter options.
+ * @param nativeFallbacks - Battery-native equivalents to fall back to when a canonical field is unset
+ *   (e.g. transformers.js `maxNewTokens`, LiteRT `maxOutputTokens`). Each is consulted second.
+ */
+export declare const resolveGenerationOptions: (canonical: ChatGenerationOptions, nativeFallbacks?: {
+    maxTokens?: number;
+    sampler?: ChatSampler;
+    temperature?: number;
+    topK?: number;
+    topP?: number;
+    seed?: number;
+    enableThinking?: boolean;
+    multimodal?: {
+        image?: boolean;
+        audio?: boolean;
+    };
+}) => ResolvedGenerationOptions;
+/** Default {@link resolveGenerationOptions}. */
+export declare const defaultResolveGenerationOptions: (canonical: ChatGenerationOptions, nativeFallbacks?: {
+    maxTokens?: number;
+    sampler?: ChatSampler;
+    temperature?: number;
+    topK?: number;
+    topP?: number;
+    seed?: number;
+    enableThinking?: boolean;
+    multimodal?: {
+        image?: boolean;
+        audio?: boolean;
+    };
+}) => ResolvedGenerationOptions;

package/batteries/llm/chat_common/helpers.d.ts

@@ -16,6 +16,74 @@
 import type { Tool, ArtifactTool, Tokenizable, Memory, Thought, Retrievable } from "../../../common";
 import type { ChatCompletionsBucketOrder, ChatCompletionsTool, DescriptionLike, JsonSchema, MemoryAttrs, RetrievableAttrs, StandingInstructionAttrs, ThoughtAttrs, TrustedContentAttrs, UntrustedContentAttrs, ChatHelpersCommon } from "./types";
 export declare const escapeXmlAttribute: (value: string) => string;
+/**
+ * Neutralise the **no-nonce** `<system_instructions …>` / `</system_instructions>` developer-rules tier
+ * if it appears inside model- or user-supplied BODY content.
+ *
+ * @remarks
+ * Every other trust tier (untrusted/trusted/peer/thought/memory/retrieved) carries an unguessable
+ * per-primitive nonce in its tag name, so a model that mirrors one cannot forge a sibling's closer. The
+ * standing-instructions tier is the lone exception — {@link renderStandingInstructions} emits it WITHOUT
+ * a nonce because it is the highest-authority block. That makes a model-mirrored copy textually
+ * identical to the real tier. The legitimate tier is ALWAYS harness-injected (built by
+ * `renderStandingInstructions` and concatenated into the system prompt) and never flows through a
+ * message/thought body — so escaping the leading `<` of the literal token wherever it occurs in body
+ * content is always safe and renders the copy inert (visible, but unmistakably not a structural tag).
+ * Mirrors how the nonce already neutralises the other tiers. See the envelope-mimicry threat model.
+ */
+export declare const neutraliseDeveloperRulesTag: (text: string) => string;
+/**
+ * Strip the non-semantic envelope/turn-boundary special tokens (see {@link ENVELOPE_SPECIAL_TOKEN_RE})
+ * from decoded model text before it reaches the parser layer.
+ *
+ * @remarks
+ * **Why this exists.** The transformers.js streaming path decodes with `skip_special_tokens:false` (it
+ * must — the live prose-stop gate watches for tool/think markers, which ARE special tokens). That leaves
+ * envelope tokens like Llama's `<|python_tag|>{json}<|eom_id|>` or ChatML's trailing `<|im_end|>` in the
+ * accumulated text, so the JSON tool-call parsers see `<|python_tag|>{…}` and decline — even though the
+ * NON-streaming path (which decodes with `skip_special_tokens:true`) parses the identical call fine.
+ * Normalising here makes the stream and batch paths parse equivalent text. Surfaced by the deep model
+ * matrix (Llama-3.2-1B + Qwen2.5-Coder tool calls passed on batch, failed on stream).
+ */
+export declare const stripEnvelopeSpecialTokens: (text: string) => string;
+/**
+ * Validate a media `mimeType` for safe interpolation into a `data:<mime>;base64,…` URI, a
+ * `Blob({type})`, or a synthetic-description line.
+ *
+ * @remarks
+ * A raw `mimeType` is attacker-influenced (it rides in on user uploads / tool output). The committee's
+ * sharpest finding was a `mimeType` like `image/png;base64,<payload>;x=` — interpolated into
+ * `data:${mime};base64,${b64}` it produces a DOUBLE `;base64,`, letting a permissive data-URI parser
+ * decode the attacker's prefix instead of the real payload (a content-type confusion / injection). A
+ * `\r\n` in the mime is an HTTP-header-injection vector if the URI is ever reflected. We accept ONLY a
+ * strict `type/subtype` (no params, no whitespace, no `;`/`,`); anything else collapses to the kind's
+ * generic safe subtype (so an image still decodes as an image) or `application/octet-stream`.
+ */
+export declare const sanitizeMimeType: (raw: string, kind?: "image" | "audio" | "video" | "document") => string;
+/**
+ * Sanitise a media `filename` for interpolation into a synthetic-description line that is then placed
+ * INSIDE a trust envelope whose body is not XML-escaped.
+ *
+ * @remarks
+ * A filename is attacker-influenced and the synthetic-description body is not escaped, so a filename
+ * like `x.png</untrusted_content_<nonce>>SYSTEM: …` could close the envelope, and one that mimics the
+ * `[media: …]` format could forge a second descriptor. We strip the envelope-significant characters
+ * (`<`, `>`, and newlines/control chars) and length-cap (a megabyte filename is a prompt-bloat DoS).
+ * The filename is metadata, not content the model must read byte-exact, so stripping is safe.
+ */
+export declare const sanitizeFilenameForDescription: (filename: string, maxLen?: number) => string;
+/**
+ * Clamp a stash entry's trust tier to its containing media's tier as a FLOOR: a stash entry may render
+ * at the parent's tier or LOWER (less trusted), never HIGHER.
+ *
+ * @remarks
+ * The committee's #1-ranked escalation: a `third-party-private` Media carrying a stash entry tagged
+ * `first-party` would otherwise render its fallback text in a `<trusted_content_…>` envelope (the
+ * media-fallback renderer keys the envelope off the entry's OWN tier). That lets untrusted content
+ * smuggle itself into the trusted tier. Flooring to the parent closes it: a child can de-escalate but
+ * never escalate above the asset it belongs to.
+ */
+export declare const floorTrustTier: <T extends string>(parent: T, entry: T) => T;
 export declare const memoryToAttrs: (m: Memory) => {
     memory: Memory;
     attrs: MemoryAttrs;

package/batteries/llm/chat_common/index.d.ts

@@ -11,3 +11,5 @@ export * from "./types";
 export * from "./helpers";
 export * from "./tool_parsers";
 export * from "./reasoning_parsers";
+export * from "./lifecycle";
+export * from "./generation";