@nhtio/adk 0.1.0-master-274a6b08 → 0.1.0-master-a4cc5f78

package/CHANGELOG.md

@@ -15,6 +15,19 @@ you *when* you got it, not *what changed*: a `^` range will float across battery
 breaking changes, so pin an exact version if you need stability and read the entry before
 upgrading.
 
+## 2026-07-18
+
+### Added
+
+- **New generation engine: `local_diffusion` — a BYO-inference-subprocess image-generation engine over a stdio line protocol.** The Node-only {@link LocalDiffusionGenerationAdapter} (`@nhtio/adk/batteries/generation/local_diffusion`, subpath-only — excluded from the environment-neutral generation aggregate) drives a user-supplied inference subprocess over a stdin/stdout line protocol (modeled on DiffusionBee), so a consumer can run a local Stable-Diffusion checkpoint without the ADK bundling Python/torch. Same `generate`/`edit` → `Promise<GeneratedMediaOutput[]>` contract as the other generation engines, plus streamed per-step progress (`dnpr` → the `generating` lifecycle phase), best-effort cancellation (`AbortSignal` → advisory `__stop__`, with `reset()`/`dispose()` as the hard stop), single-flight admission, `outputDir`-contained cleanup of backend-written files, and both inline-base64 and file-path image results. Ships the protocol + a documented Python reference backend; the consumer supplies the process.
+
+## 2026-07-13
+
+### Added
+
+- **New battery domain: `tts` — text-to-speech synthesis generating audio from text.** Two new engines under the shared contract `synthesize(text, opts?) → Promise<GeneratedMediaOutput>`: a model-backed {@link TransformersJsTtsAdapter} (`@nhtio/adk/batteries/tts/transformers_js`, MMS-VITS / SpeechT5 via `@huggingface/transformers`), and a zero-config, node-only {@link NativeTtsAdapter} (`@nhtio/adk/batteries/tts/native`) that shells out to macOS `say`, Linux `espeak-ng`, or Windows PowerShell.
+- **New embeddings battery: Ollama.** A fourth engine ships under the shared embeddings shape, targeting Ollama's native `/api/embed` endpoint. The new {@link OllamaEmbeddingsAdapter} (`@nhtio/adk/batteries/embeddings/ollama`) supports `baseURL`, `truncate`, `keepAlive`, and runtime `options`, with zero environment constraints (runs in Node, browser, edge).
+
 ## 2026-07-12
 
 ### Added

package/batteries/embeddings/index.d.ts

@@ -19,6 +19,11 @@
  * {@link @nhtio/adk/batteries/embeddings/openai/types!BaseEmbeddingsAdapterOptions}.
  */
 export { OpenAIEmbeddingsAdapter } from "./openai/index";
+export { OllamaEmbeddingsAdapter } from "./ollama/index";
+export { ollamaEmbeddingsOptionsSchema } from "./ollama/index";
+export { validateOptions as validateOllamaEmbeddingsOptions } from "./ollama/index";
+export type { OllamaEmbeddingsAdapterOptions, OllamaEmbeddingsRuntimeOptions, OllamaEmbeddingsRequestBody, OllamaEmbeddingsResponseBody, } from "./ollama/index";
+export { E_INVALID_OLLAMA_EMBEDDINGS_OPTIONS, E_OLLAMA_EMBEDDINGS_HTTP_ERROR, E_OLLAMA_EMBEDDINGS_REQUEST_TIMEOUT, E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE, } from "./ollama/index";
 export { applyEmbeddingPrefix } from "./openai/index";
 export { openAIEmbeddingsOptionsSchema } from "./openai/index";
 export { validateOptions as validateOpenAIEmbeddingsOptions } from "./openai/index";

package/batteries/embeddings/ollama/adapter.cjs

@@ -0,0 +1,187 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../chunk-Cek0wNdY.js");
+const require_tokenizable = require("../../../tokenizable-CAwoWiev.js");
+require("../../../guards.cjs");
+const require_lib_utils_retry = require("../../../lib/utils/retry.cjs");
+const require_batteries_embeddings_openai_helpers = require("../openai/helpers.cjs");
+const require_batteries_embeddings_ollama_exceptions = require("./exceptions.cjs");
+const require_batteries_embeddings_ollama_validation = require("./validation.cjs");
+//#region src/batteries/embeddings/ollama/adapter.ts
+/**
+* Cross-environment Ollama Embeddings adapter battery.
+*
+* @module @nhtio/adk/batteries/embeddings/ollama/adapter
+*
+* @remarks
+* Opinionated embeddings battery for the Ollama `/api/embed` wire shape. Ships an
+* {@link OllamaEmbeddingsAdapter} that targets any Ollama-compatible endpoint over raw `fetch` —
+* no SDK dependency, so it runs unchanged in Node, the browser, edge runtimes, and workers.
+*
+* The class shares its method surface, return types, prefix handling, and option base with the
+* OpenAI Embeddings battery: the two differ only in their engine. See
+* {@link @nhtio/adk/batteries/embeddings/openai/types!BaseEmbeddingsAdapterOptions}.
+*
+* Construction validates options eagerly via {@link @nhtio/adk/batteries/embeddings/ollama/validation!validateOptions} and throws
+* {@link @nhtio/adk/batteries/embeddings/ollama/exceptions!E_INVALID_OLLAMA_EMBEDDINGS_OPTIONS} on failure — config bugs fail loud, not at embed time.
+*/
+/**
+* Embeddings adapter for the Ollama `/api/embed` wire shape.
+*
+* @remarks
+* Reusable: construct once, call {@link OllamaEmbeddingsAdapter.embed} / {@link embedMany} as many
+* times as needed. `embedMany` issues one request per call (Ollama embeds a batch in a single
+* round-trip); `embed` is sugar over `embedMany([text])`.
+*/
+var OllamaEmbeddingsAdapter = class OllamaEmbeddingsAdapter {
+	#options;
+	/**
+	* Whether this battery can run in the current environment. For the HTTP-backed Ollama battery
+	* this is always `true` (a `fetch` is always resolvable); present for surface-parity with the
+	* WebLLM battery's WebGPU gate.
+	*/
+	static isAvailable() {
+		return true;
+	}
+	/**
+	* @param options - Constructor options. Validated eagerly.
+	* @throws {@link @nhtio/adk/batteries/embeddings/ollama/exceptions!E_INVALID_OLLAMA_EMBEDDINGS_OPTIONS} when `options` does not satisfy
+	*   {@link @nhtio/adk/batteries/embeddings/ollama/validation!ollamaEmbeddingsOptionsSchema} (e.g. missing `model`).
+	*/
+	constructor(options) {
+		this.#options = require_batteries_embeddings_ollama_validation.validateOptions(options);
+	}
+	/** Declared output dimensionality (from options), or `undefined` if not configured. */
+	get dimensions() {
+		return this.#options.dimensions;
+	}
+	/** See {@link OllamaEmbeddingsAdapter.isAvailable}. Instance alias for surface-parity. */
+	isAvailable() {
+		return OllamaEmbeddingsAdapter.isAvailable();
+	}
+	/**
+	* No-op warm-up. The Ollama battery has no engine to preload; present for surface-parity with
+	* the WebLLM battery so callers can treat the two interchangeably.
+	*/
+	async preload() {}
+	/**
+	* No-op state reset. Present for surface-parity with the WebLLM battery.
+	*/
+	reset() {}
+	/**
+	* 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 request.
+	*
+	* @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/ollama/exceptions!E_OLLAMA_EMBEDDINGS_HTTP_ERROR} on a non-2xx response or transport failure.
+	* @throws {@link @nhtio/adk/batteries/embeddings/ollama/exceptions!E_OLLAMA_EMBEDDINGS_REQUEST_TIMEOUT} when the handshake exceeds `requestTimeoutMs`.
+	* @throws {@link @nhtio/adk/batteries/embeddings/ollama/exceptions!E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE} when the 2xx body is not the expected shape.
+	*/
+	async embedMany(texts, opts) {
+		if (texts.length === 0) return [];
+		const input = require_batteries_embeddings_openai_helpers.applyEmbeddingPrefix(texts, opts?.kind ?? "document", this.#options);
+		const body = {
+			model: this.#options.model,
+			input,
+			...this.#options.dimensions !== void 0 ? { dimensions: this.#options.dimensions } : {},
+			...this.#options.truncate !== void 0 ? { truncate: this.#options.truncate } : {},
+			...this.#options.keepAlive !== void 0 ? { keep_alive: this.#options.keepAlive } : {},
+			...this.#options.options !== void 0 ? { options: this.#options.options } : {}
+		};
+		const rawBase = this.#options.baseURL ?? "http://localhost:11434";
+		const url = `${rawBase.endsWith("/") ? rawBase.slice(0, -1) : rawBase}/api/embed`;
+		const headers = { "Content-Type": "application/json" };
+		if (this.#options.apiKey) headers["Authorization"] = `Bearer ${this.#options.apiKey}`;
+		if (this.#options.headers) Object.assign(headers, this.#options.headers);
+		const retryCfg = {
+			maxAttempts: this.#options.retry?.maxAttempts ?? 1,
+			baseDelayMs: this.#options.retry?.baseDelayMs ?? 500,
+			maxDelayMs: this.#options.retry?.maxDelayMs ?? 3e4,
+			retriableStatuses: this.#options.retry?.retriableStatuses ?? [
+				429,
+				500,
+				502,
+				503,
+				504
+			],
+			honorRetryAfter: this.#options.retry?.honorRetryAfter ?? true
+		};
+		const fetchFn = this.#options.fetch ?? globalThis.fetch;
+		const requestTimeoutMs = this.#options.requestTimeoutMs ?? 0;
+		const maxAttempts = retryCfg.maxAttempts;
+		let attempt = 1;
+		while (attempt <= maxAttempts) {
+			const controller = new AbortController();
+			let timeoutHandle;
+			if (requestTimeoutMs > 0) timeoutHandle = setTimeout(() => controller.abort(), requestTimeoutMs);
+			let response;
+			try {
+				response = await fetchFn(url, {
+					method: "POST",
+					headers,
+					body: JSON.stringify(body),
+					signal: controller.signal
+				});
+			} catch (err) {
+				if (timeoutHandle !== void 0) clearTimeout(timeoutHandle);
+				if (controller.signal.aborted) {
+					if (attempt < maxAttempts) {
+						await require_lib_utils_retry.sleepWithJitter(require_lib_utils_retry.computeBackoff(attempt, retryCfg));
+						attempt += 1;
+						continue;
+					}
+					throw new require_batteries_embeddings_ollama_exceptions.E_OLLAMA_EMBEDDINGS_REQUEST_TIMEOUT([requestTimeoutMs]);
+				}
+				if (attempt < maxAttempts) {
+					await require_lib_utils_retry.sleepWithJitter(require_lib_utils_retry.computeBackoff(attempt, retryCfg));
+					attempt += 1;
+					continue;
+				}
+				throw new require_batteries_embeddings_ollama_exceptions.E_OLLAMA_EMBEDDINGS_HTTP_ERROR([0, require_tokenizable.isError(err) ? err.message : String(err)]);
+			}
+			if (timeoutHandle !== void 0) clearTimeout(timeoutHandle);
+			if (!response.ok) {
+				const status = response.status;
+				if (retryCfg.retriableStatuses.includes(status) && attempt < maxAttempts) {
+					let delay = require_lib_utils_retry.computeBackoff(attempt, retryCfg);
+					if (retryCfg.honorRetryAfter) {
+						const ra = response.headers.get("Retry-After");
+						if (ra) {
+							const raMs = require_lib_utils_retry.parseRetryAfter(ra);
+							if (raMs > 0) delay = Math.min(Math.max(delay, raMs), retryCfg.maxDelayMs);
+						}
+					}
+					await require_lib_utils_retry.sleepWithJitter(delay);
+					attempt += 1;
+					continue;
+				}
+				throw new require_batteries_embeddings_ollama_exceptions.E_OLLAMA_EMBEDDINGS_HTTP_ERROR([status, await response.text().catch(() => "")]);
+			}
+			let parsed;
+			try {
+				parsed = await response.json();
+			} catch (err) {
+				throw new require_batteries_embeddings_ollama_exceptions.E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE([require_tokenizable.isError(err) ? err.message : String(err)]);
+			}
+			if (!parsed || !Array.isArray(parsed.embeddings) || parsed.embeddings.length !== input.length) throw new require_batteries_embeddings_ollama_exceptions.E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE([`expected ${input.length} vectors, got ${parsed?.embeddings?.length ?? "none"}`]);
+			for (const vec of parsed.embeddings) if (!Array.isArray(vec) || !vec.every((n) => typeof n === "number" && Number.isFinite(n))) throw new require_batteries_embeddings_ollama_exceptions.E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE(["response contained a vector that was not an array of finite numbers"]);
+			return parsed.embeddings;
+		}
+		throw new require_batteries_embeddings_ollama_exceptions.E_OLLAMA_EMBEDDINGS_HTTP_ERROR([0, "retry loop exhausted without a response"]);
+	}
+};
+//#endregion
+exports.OllamaEmbeddingsAdapter = OllamaEmbeddingsAdapter;
+
+//# sourceMappingURL=adapter.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.cjs","names":["#options"],"sources":["../../../../src/batteries/embeddings/ollama/adapter.ts"],"sourcesContent":["/**\n * Cross-environment Ollama Embeddings adapter battery.\n *\n * @module @nhtio/adk/batteries/embeddings/ollama/adapter\n *\n * @remarks\n * Opinionated embeddings battery for the Ollama `/api/embed` wire shape. Ships an\n * {@link OllamaEmbeddingsAdapter} that targets any Ollama-compatible endpoint over raw `fetch` —\n * no SDK dependency, so it runs unchanged in Node, the browser, edge runtimes, and workers.\n *\n * The class shares its method surface, return types, prefix handling, and option base with the\n * OpenAI Embeddings battery: the two differ only in their engine. See\n * {@link @nhtio/adk/batteries/embeddings/openai/types!BaseEmbeddingsAdapterOptions}.\n *\n * Construction validates options eagerly via {@link @nhtio/adk/batteries/embeddings/ollama/validation!validateOptions} and throws\n * {@link @nhtio/adk/batteries/embeddings/ollama/exceptions!E_INVALID_OLLAMA_EMBEDDINGS_OPTIONS} on failure — config bugs fail loud, not at embed time.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { validateOptions } from './validation'\nimport { applyEmbeddingPrefix } from '../openai/helpers'\n// Accepted-shared-runtime tier (see CONTRIBUTING.md → Design Decisions → #13 Battery design):\n// pure, class-free retry primitives shared with the Chat Completions LLM batteries. No core class\n// coupling — same tier as guards/createException — so this deep relative reach is accepted as-is,\n// not re-exported through a shim.\nimport { computeBackoff, sleepWithJitter, parseRetryAfter } from '../../../lib/utils/retry'\nimport {\n  E_OLLAMA_EMBEDDINGS_HTTP_ERROR,\n  E_OLLAMA_EMBEDDINGS_REQUEST_TIMEOUT,\n  E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE,\n} from './exceptions'\nimport type {\n  EmbedOptions,\n  EmbeddingsRetryConfig,\n  OllamaEmbeddingsAdapterOptions,\n  OllamaEmbeddingsRequestBody,\n  OllamaEmbeddingsResponseBody,\n} from './types'\n\n// ─── Adapter class ────────────────────────────────────────────────────────────\n\n/**\n * Embeddings adapter for the Ollama `/api/embed` wire shape.\n *\n * @remarks\n * Reusable: construct once, call {@link OllamaEmbeddingsAdapter.embed} / {@link embedMany} as many\n * times as needed. `embedMany` issues one request per call (Ollama embeds a batch in a single\n * round-trip); `embed` is sugar over `embedMany([text])`.\n */\nexport class OllamaEmbeddingsAdapter {\n  readonly #options: OllamaEmbeddingsAdapterOptions\n\n  /**\n   * Whether this battery can run in the current environment. For the HTTP-backed Ollama battery\n   * this is always `true` (a `fetch` is always resolvable); present for surface-parity with the\n   * WebLLM battery's WebGPU gate.\n   */\n  public static isAvailable(): boolean {\n    return true\n  }\n\n  /**\n   * @param options - Constructor options. Validated eagerly.\n   * @throws {@link @nhtio/adk/batteries/embeddings/ollama/exceptions!E_INVALID_OLLAMA_EMBEDDINGS_OPTIONS} when `options` does not satisfy\n   *   {@link @nhtio/adk/batteries/embeddings/ollama/validation!ollamaEmbeddingsOptionsSchema} (e.g. missing `model`).\n   */\n  constructor(options: unknown) {\n    this.#options = validateOptions(options)\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  /** See {@link OllamaEmbeddingsAdapter.isAvailable}. Instance alias for surface-parity. */\n  isAvailable(): boolean {\n    return OllamaEmbeddingsAdapter.isAvailable()\n  }\n\n  /**\n   * No-op warm-up. The Ollama battery has no engine to preload; present for surface-parity with\n   * the WebLLM battery so callers can treat the two interchangeably.\n   */\n  async preload(): Promise<void> {\n    // intentionally empty — nothing to warm for an HTTP-backed battery\n  }\n\n  /**\n   * No-op state reset. Present for surface-parity with the WebLLM battery.\n   */\n  reset(): void {\n    // intentionally empty — the Ollama battery holds no engine state\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 request.\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/ollama/exceptions!E_OLLAMA_EMBEDDINGS_HTTP_ERROR} on a non-2xx response or transport failure.\n   * @throws {@link @nhtio/adk/batteries/embeddings/ollama/exceptions!E_OLLAMA_EMBEDDINGS_REQUEST_TIMEOUT} when the handshake exceeds `requestTimeoutMs`.\n   * @throws {@link @nhtio/adk/batteries/embeddings/ollama/exceptions!E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE} when the 2xx body is not the expected shape.\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 body: OllamaEmbeddingsRequestBody = {\n      model: this.#options.model,\n      input,\n      ...(this.#options.dimensions !== undefined ? { dimensions: this.#options.dimensions } : {}),\n      ...(this.#options.truncate !== undefined ? { truncate: this.#options.truncate } : {}),\n      ...(this.#options.keepAlive !== undefined ? { keep_alive: this.#options.keepAlive } : {}),\n      ...(this.#options.options !== undefined ? { options: this.#options.options } : {}),\n    }\n\n    const rawBase = this.#options.baseURL ?? 'http://localhost:11434'\n    const baseURL = rawBase.endsWith('/') ? rawBase.slice(0, -1) : rawBase\n    const url = `${baseURL}/api/embed`\n\n    const headers: Record<string, string> = { 'Content-Type': 'application/json' }\n    if (this.#options.apiKey) {\n      headers['Authorization'] = `Bearer ${this.#options.apiKey}`\n    }\n    if (this.#options.headers) {\n      Object.assign(headers, this.#options.headers)\n    }\n\n    const retryCfg: Required<EmbeddingsRetryConfig> = {\n      maxAttempts: this.#options.retry?.maxAttempts ?? 1,\n      baseDelayMs: this.#options.retry?.baseDelayMs ?? 500,\n      maxDelayMs: this.#options.retry?.maxDelayMs ?? 30_000,\n      retriableStatuses: this.#options.retry?.retriableStatuses ?? [429, 500, 502, 503, 504],\n      honorRetryAfter: this.#options.retry?.honorRetryAfter ?? true,\n    }\n\n    const fetchFn = this.#options.fetch ?? globalThis.fetch\n    const requestTimeoutMs = this.#options.requestTimeoutMs ?? 0\n    const maxAttempts = retryCfg.maxAttempts\n\n    let attempt = 1\n    while (attempt <= maxAttempts) {\n      const controller = new AbortController()\n      let timeoutHandle: ReturnType<typeof setTimeout> | undefined\n      if (requestTimeoutMs > 0) {\n        timeoutHandle = setTimeout(() => controller.abort(), requestTimeoutMs)\n      }\n\n      let response: Response\n      try {\n        response = await fetchFn(url, {\n          method: 'POST',\n          headers,\n          body: JSON.stringify(body),\n          signal: controller.signal,\n        })\n      } catch (err) {\n        if (timeoutHandle !== undefined) clearTimeout(timeoutHandle)\n        if (controller.signal.aborted) {\n          // Timed out before headers — retry if attempts remain.\n          if (attempt < maxAttempts) {\n            await sleepWithJitter(computeBackoff(attempt, retryCfg))\n            attempt += 1\n            continue\n          }\n          throw new E_OLLAMA_EMBEDDINGS_REQUEST_TIMEOUT([requestTimeoutMs])\n        }\n        // Generic transport failure — retry if attempts remain, else surface as status 0.\n        if (attempt < maxAttempts) {\n          await sleepWithJitter(computeBackoff(attempt, retryCfg))\n          attempt += 1\n          continue\n        }\n        throw new E_OLLAMA_EMBEDDINGS_HTTP_ERROR([0, isError(err) ? err.message : String(err)])\n      }\n      if (timeoutHandle !== undefined) clearTimeout(timeoutHandle)\n\n      if (!response.ok) {\n        const status = response.status\n        const retriable = retryCfg.retriableStatuses.includes(status)\n        if (retriable && attempt < maxAttempts) {\n          let delay = computeBackoff(attempt, retryCfg)\n          if (retryCfg.honorRetryAfter) {\n            const ra = response.headers.get('Retry-After')\n            if (ra) {\n              const raMs = parseRetryAfter(ra)\n              if (raMs > 0) delay = Math.min(Math.max(delay, raMs), retryCfg.maxDelayMs)\n            }\n          }\n          await sleepWithJitter(delay)\n          attempt += 1\n          continue\n        }\n        const detail = await response.text().catch(() => '')\n        throw new E_OLLAMA_EMBEDDINGS_HTTP_ERROR([status, detail])\n      }\n\n      let parsed: OllamaEmbeddingsResponseBody\n      try {\n        parsed = (await response.json()) as OllamaEmbeddingsResponseBody\n      } catch (err) {\n        throw new E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE([isError(err) ? err.message : String(err)])\n      }\n      if (\n        !parsed ||\n        !Array.isArray(parsed.embeddings) ||\n        parsed.embeddings.length !== input.length\n      ) {\n        throw new E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE([\n          `expected ${input.length} vectors, got ${parsed?.embeddings?.length ?? 'none'}`,\n        ])\n      }\n      // Every vector must be an array of finite numbers — a same-length-but-malformed body\n      // (e.g. `[null]`, `[[\"x\"]]`, `[{}]`) must not slip through typed as `number[][]`.\n      for (const vec of parsed.embeddings) {\n        if (!Array.isArray(vec) || !vec.every((n) => typeof n === 'number' && Number.isFinite(n))) {\n          throw new E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE([\n            'response contained a vector that was not an array of finite numbers',\n          ])\n        }\n      }\n      // Ollama returns embeddings positionally (no index field); return in input order directly.\n      return parsed.embeddings\n    }\n\n    // Unreachable: the loop either returns or throws. Satisfies the type checker.\n    throw new E_OLLAMA_EMBEDDINGS_HTTP_ERROR([0, 'retry loop exhausted without a response'])\n  }\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,73 @@
+/**
+ * Cross-environment Ollama Embeddings adapter battery.
+ *
+ * @module @nhtio/adk/batteries/embeddings/ollama/adapter
+ *
+ * @remarks
+ * Opinionated embeddings battery for the Ollama `/api/embed` wire shape. Ships an
+ * {@link OllamaEmbeddingsAdapter} that targets any Ollama-compatible endpoint over raw `fetch` —
+ * no SDK dependency, so it runs unchanged in Node, the browser, edge runtimes, and workers.
+ *
+ * The class shares its method surface, return types, prefix handling, and option base with the
+ * OpenAI Embeddings battery: the two differ only in their engine. See
+ * {@link @nhtio/adk/batteries/embeddings/openai/types!BaseEmbeddingsAdapterOptions}.
+ *
+ * Construction validates options eagerly via {@link @nhtio/adk/batteries/embeddings/ollama/validation!validateOptions} and throws
+ * {@link @nhtio/adk/batteries/embeddings/ollama/exceptions!E_INVALID_OLLAMA_EMBEDDINGS_OPTIONS} on failure — config bugs fail loud, not at embed time.
+ */
+import type { EmbedOptions } from "./types";
+/**
+ * Embeddings adapter for the Ollama `/api/embed` wire shape.
+ *
+ * @remarks
+ * Reusable: construct once, call {@link OllamaEmbeddingsAdapter.embed} / {@link embedMany} as many
+ * times as needed. `embedMany` issues one request per call (Ollama embeds a batch in a single
+ * round-trip); `embed` is sugar over `embedMany([text])`.
+ */
+export declare class OllamaEmbeddingsAdapter {
+    #private;
+    /**
+     * Whether this battery can run in the current environment. For the HTTP-backed Ollama battery
+     * this is always `true` (a `fetch` is always resolvable); present for surface-parity with the
+     * WebLLM battery's WebGPU gate.
+     */
+    static isAvailable(): boolean;
+    /**
+     * @param options - Constructor options. Validated eagerly.
+     * @throws {@link @nhtio/adk/batteries/embeddings/ollama/exceptions!E_INVALID_OLLAMA_EMBEDDINGS_OPTIONS} when `options` does not satisfy
+     *   {@link @nhtio/adk/batteries/embeddings/ollama/validation!ollamaEmbeddingsOptionsSchema} (e.g. missing `model`).
+     */
+    constructor(options: unknown);
+    /** Declared output dimensionality (from options), or `undefined` if not configured. */
+    get dimensions(): number | undefined;
+    /** See {@link OllamaEmbeddingsAdapter.isAvailable}. Instance alias for surface-parity. */
+    isAvailable(): boolean;
+    /**
+     * No-op warm-up. The Ollama battery has no engine to preload; present for surface-parity with
+     * the WebLLM battery so callers can treat the two interchangeably.
+     */
+    preload(): Promise<void>;
+    /**
+     * No-op state reset. Present for surface-parity with the WebLLM battery.
+     */
+    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 request.
+     *
+     * @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/ollama/exceptions!E_OLLAMA_EMBEDDINGS_HTTP_ERROR} on a non-2xx response or transport failure.
+     * @throws {@link @nhtio/adk/batteries/embeddings/ollama/exceptions!E_OLLAMA_EMBEDDINGS_REQUEST_TIMEOUT} when the handshake exceeds `requestTimeoutMs`.
+     * @throws {@link @nhtio/adk/batteries/embeddings/ollama/exceptions!E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE} when the 2xx body is not the expected shape.
+     */
+    embedMany(texts: string[], opts?: EmbedOptions): Promise<number[][]>;
+}

package/batteries/embeddings/ollama/adapter.mjs

@@ -0,0 +1,185 @@
+import { B as isError } from "../../../tokenizable-CNdPvlaY.mjs";
+import "../../../guards.mjs";
+import { computeBackoff, parseRetryAfter, sleepWithJitter } from "../../../lib/utils/retry.mjs";
+import { applyEmbeddingPrefix } from "../openai/helpers.mjs";
+import { E_OLLAMA_EMBEDDINGS_HTTP_ERROR, E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE, E_OLLAMA_EMBEDDINGS_REQUEST_TIMEOUT } from "./exceptions.mjs";
+import { validateOptions } from "./validation.mjs";
+//#region src/batteries/embeddings/ollama/adapter.ts
+/**
+* Cross-environment Ollama Embeddings adapter battery.
+*
+* @module @nhtio/adk/batteries/embeddings/ollama/adapter
+*
+* @remarks
+* Opinionated embeddings battery for the Ollama `/api/embed` wire shape. Ships an
+* {@link OllamaEmbeddingsAdapter} that targets any Ollama-compatible endpoint over raw `fetch` —
+* no SDK dependency, so it runs unchanged in Node, the browser, edge runtimes, and workers.
+*
+* The class shares its method surface, return types, prefix handling, and option base with the
+* OpenAI Embeddings battery: the two differ only in their engine. See
+* {@link @nhtio/adk/batteries/embeddings/openai/types!BaseEmbeddingsAdapterOptions}.
+*
+* Construction validates options eagerly via {@link @nhtio/adk/batteries/embeddings/ollama/validation!validateOptions} and throws
+* {@link @nhtio/adk/batteries/embeddings/ollama/exceptions!E_INVALID_OLLAMA_EMBEDDINGS_OPTIONS} on failure — config bugs fail loud, not at embed time.
+*/
+/**
+* Embeddings adapter for the Ollama `/api/embed` wire shape.
+*
+* @remarks
+* Reusable: construct once, call {@link OllamaEmbeddingsAdapter.embed} / {@link embedMany} as many
+* times as needed. `embedMany` issues one request per call (Ollama embeds a batch in a single
+* round-trip); `embed` is sugar over `embedMany([text])`.
+*/
+var OllamaEmbeddingsAdapter = class OllamaEmbeddingsAdapter {
+	#options;
+	/**
+	* Whether this battery can run in the current environment. For the HTTP-backed Ollama battery
+	* this is always `true` (a `fetch` is always resolvable); present for surface-parity with the
+	* WebLLM battery's WebGPU gate.
+	*/
+	static isAvailable() {
+		return true;
+	}
+	/**
+	* @param options - Constructor options. Validated eagerly.
+	* @throws {@link @nhtio/adk/batteries/embeddings/ollama/exceptions!E_INVALID_OLLAMA_EMBEDDINGS_OPTIONS} when `options` does not satisfy
+	*   {@link @nhtio/adk/batteries/embeddings/ollama/validation!ollamaEmbeddingsOptionsSchema} (e.g. missing `model`).
+	*/
+	constructor(options) {
+		this.#options = validateOptions(options);
+	}
+	/** Declared output dimensionality (from options), or `undefined` if not configured. */
+	get dimensions() {
+		return this.#options.dimensions;
+	}
+	/** See {@link OllamaEmbeddingsAdapter.isAvailable}. Instance alias for surface-parity. */
+	isAvailable() {
+		return OllamaEmbeddingsAdapter.isAvailable();
+	}
+	/**
+	* No-op warm-up. The Ollama battery has no engine to preload; present for surface-parity with
+	* the WebLLM battery so callers can treat the two interchangeably.
+	*/
+	async preload() {}
+	/**
+	* No-op state reset. Present for surface-parity with the WebLLM battery.
+	*/
+	reset() {}
+	/**
+	* 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 request.
+	*
+	* @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/ollama/exceptions!E_OLLAMA_EMBEDDINGS_HTTP_ERROR} on a non-2xx response or transport failure.
+	* @throws {@link @nhtio/adk/batteries/embeddings/ollama/exceptions!E_OLLAMA_EMBEDDINGS_REQUEST_TIMEOUT} when the handshake exceeds `requestTimeoutMs`.
+	* @throws {@link @nhtio/adk/batteries/embeddings/ollama/exceptions!E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE} when the 2xx body is not the expected shape.
+	*/
+	async embedMany(texts, opts) {
+		if (texts.length === 0) return [];
+		const input = applyEmbeddingPrefix(texts, opts?.kind ?? "document", this.#options);
+		const body = {
+			model: this.#options.model,
+			input,
+			...this.#options.dimensions !== void 0 ? { dimensions: this.#options.dimensions } : {},
+			...this.#options.truncate !== void 0 ? { truncate: this.#options.truncate } : {},
+			...this.#options.keepAlive !== void 0 ? { keep_alive: this.#options.keepAlive } : {},
+			...this.#options.options !== void 0 ? { options: this.#options.options } : {}
+		};
+		const rawBase = this.#options.baseURL ?? "http://localhost:11434";
+		const url = `${rawBase.endsWith("/") ? rawBase.slice(0, -1) : rawBase}/api/embed`;
+		const headers = { "Content-Type": "application/json" };
+		if (this.#options.apiKey) headers["Authorization"] = `Bearer ${this.#options.apiKey}`;
+		if (this.#options.headers) Object.assign(headers, this.#options.headers);
+		const retryCfg = {
+			maxAttempts: this.#options.retry?.maxAttempts ?? 1,
+			baseDelayMs: this.#options.retry?.baseDelayMs ?? 500,
+			maxDelayMs: this.#options.retry?.maxDelayMs ?? 3e4,
+			retriableStatuses: this.#options.retry?.retriableStatuses ?? [
+				429,
+				500,
+				502,
+				503,
+				504
+			],
+			honorRetryAfter: this.#options.retry?.honorRetryAfter ?? true
+		};
+		const fetchFn = this.#options.fetch ?? globalThis.fetch;
+		const requestTimeoutMs = this.#options.requestTimeoutMs ?? 0;
+		const maxAttempts = retryCfg.maxAttempts;
+		let attempt = 1;
+		while (attempt <= maxAttempts) {
+			const controller = new AbortController();
+			let timeoutHandle;
+			if (requestTimeoutMs > 0) timeoutHandle = setTimeout(() => controller.abort(), requestTimeoutMs);
+			let response;
+			try {
+				response = await fetchFn(url, {
+					method: "POST",
+					headers,
+					body: JSON.stringify(body),
+					signal: controller.signal
+				});
+			} catch (err) {
+				if (timeoutHandle !== void 0) clearTimeout(timeoutHandle);
+				if (controller.signal.aborted) {
+					if (attempt < maxAttempts) {
+						await sleepWithJitter(computeBackoff(attempt, retryCfg));
+						attempt += 1;
+						continue;
+					}
+					throw new E_OLLAMA_EMBEDDINGS_REQUEST_TIMEOUT([requestTimeoutMs]);
+				}
+				if (attempt < maxAttempts) {
+					await sleepWithJitter(computeBackoff(attempt, retryCfg));
+					attempt += 1;
+					continue;
+				}
+				throw new E_OLLAMA_EMBEDDINGS_HTTP_ERROR([0, isError(err) ? err.message : String(err)]);
+			}
+			if (timeoutHandle !== void 0) clearTimeout(timeoutHandle);
+			if (!response.ok) {
+				const status = response.status;
+				if (retryCfg.retriableStatuses.includes(status) && attempt < maxAttempts) {
+					let delay = computeBackoff(attempt, retryCfg);
+					if (retryCfg.honorRetryAfter) {
+						const ra = response.headers.get("Retry-After");
+						if (ra) {
+							const raMs = parseRetryAfter(ra);
+							if (raMs > 0) delay = Math.min(Math.max(delay, raMs), retryCfg.maxDelayMs);
+						}
+					}
+					await sleepWithJitter(delay);
+					attempt += 1;
+					continue;
+				}
+				throw new E_OLLAMA_EMBEDDINGS_HTTP_ERROR([status, await response.text().catch(() => "")]);
+			}
+			let parsed;
+			try {
+				parsed = await response.json();
+			} catch (err) {
+				throw new E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE([isError(err) ? err.message : String(err)]);
+			}
+			if (!parsed || !Array.isArray(parsed.embeddings) || parsed.embeddings.length !== input.length) throw new E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE([`expected ${input.length} vectors, got ${parsed?.embeddings?.length ?? "none"}`]);
+			for (const vec of parsed.embeddings) if (!Array.isArray(vec) || !vec.every((n) => typeof n === "number" && Number.isFinite(n))) throw new E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE(["response contained a vector that was not an array of finite numbers"]);
+			return parsed.embeddings;
+		}
+		throw new E_OLLAMA_EMBEDDINGS_HTTP_ERROR([0, "retry loop exhausted without a response"]);
+	}
+};
+//#endregion
+export { OllamaEmbeddingsAdapter };
+
+//# sourceMappingURL=adapter.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.mjs","names":["#options"],"sources":["../../../../src/batteries/embeddings/ollama/adapter.ts"],"sourcesContent":["/**\n * Cross-environment Ollama Embeddings adapter battery.\n *\n * @module @nhtio/adk/batteries/embeddings/ollama/adapter\n *\n * @remarks\n * Opinionated embeddings battery for the Ollama `/api/embed` wire shape. Ships an\n * {@link OllamaEmbeddingsAdapter} that targets any Ollama-compatible endpoint over raw `fetch` —\n * no SDK dependency, so it runs unchanged in Node, the browser, edge runtimes, and workers.\n *\n * The class shares its method surface, return types, prefix handling, and option base with the\n * OpenAI Embeddings battery: the two differ only in their engine. See\n * {@link @nhtio/adk/batteries/embeddings/openai/types!BaseEmbeddingsAdapterOptions}.\n *\n * Construction validates options eagerly via {@link @nhtio/adk/batteries/embeddings/ollama/validation!validateOptions} and throws\n * {@link @nhtio/adk/batteries/embeddings/ollama/exceptions!E_INVALID_OLLAMA_EMBEDDINGS_OPTIONS} on failure — config bugs fail loud, not at embed time.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { validateOptions } from './validation'\nimport { applyEmbeddingPrefix } from '../openai/helpers'\n// Accepted-shared-runtime tier (see CONTRIBUTING.md → Design Decisions → #13 Battery design):\n// pure, class-free retry primitives shared with the Chat Completions LLM batteries. No core class\n// coupling — same tier as guards/createException — so this deep relative reach is accepted as-is,\n// not re-exported through a shim.\nimport { computeBackoff, sleepWithJitter, parseRetryAfter } from '../../../lib/utils/retry'\nimport {\n  E_OLLAMA_EMBEDDINGS_HTTP_ERROR,\n  E_OLLAMA_EMBEDDINGS_REQUEST_TIMEOUT,\n  E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE,\n} from './exceptions'\nimport type {\n  EmbedOptions,\n  EmbeddingsRetryConfig,\n  OllamaEmbeddingsAdapterOptions,\n  OllamaEmbeddingsRequestBody,\n  OllamaEmbeddingsResponseBody,\n} from './types'\n\n// ─── Adapter class ────────────────────────────────────────────────────────────\n\n/**\n * Embeddings adapter for the Ollama `/api/embed` wire shape.\n *\n * @remarks\n * Reusable: construct once, call {@link OllamaEmbeddingsAdapter.embed} / {@link embedMany} as many\n * times as needed. `embedMany` issues one request per call (Ollama embeds a batch in a single\n * round-trip); `embed` is sugar over `embedMany([text])`.\n */\nexport class OllamaEmbeddingsAdapter {\n  readonly #options: OllamaEmbeddingsAdapterOptions\n\n  /**\n   * Whether this battery can run in the current environment. For the HTTP-backed Ollama battery\n   * this is always `true` (a `fetch` is always resolvable); present for surface-parity with the\n   * WebLLM battery's WebGPU gate.\n   */\n  public static isAvailable(): boolean {\n    return true\n  }\n\n  /**\n   * @param options - Constructor options. Validated eagerly.\n   * @throws {@link @nhtio/adk/batteries/embeddings/ollama/exceptions!E_INVALID_OLLAMA_EMBEDDINGS_OPTIONS} when `options` does not satisfy\n   *   {@link @nhtio/adk/batteries/embeddings/ollama/validation!ollamaEmbeddingsOptionsSchema} (e.g. missing `model`).\n   */\n  constructor(options: unknown) {\n    this.#options = validateOptions(options)\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  /** See {@link OllamaEmbeddingsAdapter.isAvailable}. Instance alias for surface-parity. */\n  isAvailable(): boolean {\n    return OllamaEmbeddingsAdapter.isAvailable()\n  }\n\n  /**\n   * No-op warm-up. The Ollama battery has no engine to preload; present for surface-parity with\n   * the WebLLM battery so callers can treat the two interchangeably.\n   */\n  async preload(): Promise<void> {\n    // intentionally empty — nothing to warm for an HTTP-backed battery\n  }\n\n  /**\n   * No-op state reset. Present for surface-parity with the WebLLM battery.\n   */\n  reset(): void {\n    // intentionally empty — the Ollama battery holds no engine state\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 request.\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/ollama/exceptions!E_OLLAMA_EMBEDDINGS_HTTP_ERROR} on a non-2xx response or transport failure.\n   * @throws {@link @nhtio/adk/batteries/embeddings/ollama/exceptions!E_OLLAMA_EMBEDDINGS_REQUEST_TIMEOUT} when the handshake exceeds `requestTimeoutMs`.\n   * @throws {@link @nhtio/adk/batteries/embeddings/ollama/exceptions!E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE} when the 2xx body is not the expected shape.\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 body: OllamaEmbeddingsRequestBody = {\n      model: this.#options.model,\n      input,\n      ...(this.#options.dimensions !== undefined ? { dimensions: this.#options.dimensions } : {}),\n      ...(this.#options.truncate !== undefined ? { truncate: this.#options.truncate } : {}),\n      ...(this.#options.keepAlive !== undefined ? { keep_alive: this.#options.keepAlive } : {}),\n      ...(this.#options.options !== undefined ? { options: this.#options.options } : {}),\n    }\n\n    const rawBase = this.#options.baseURL ?? 'http://localhost:11434'\n    const baseURL = rawBase.endsWith('/') ? rawBase.slice(0, -1) : rawBase\n    const url = `${baseURL}/api/embed`\n\n    const headers: Record<string, string> = { 'Content-Type': 'application/json' }\n    if (this.#options.apiKey) {\n      headers['Authorization'] = `Bearer ${this.#options.apiKey}`\n    }\n    if (this.#options.headers) {\n      Object.assign(headers, this.#options.headers)\n    }\n\n    const retryCfg: Required<EmbeddingsRetryConfig> = {\n      maxAttempts: this.#options.retry?.maxAttempts ?? 1,\n      baseDelayMs: this.#options.retry?.baseDelayMs ?? 500,\n      maxDelayMs: this.#options.retry?.maxDelayMs ?? 30_000,\n      retriableStatuses: this.#options.retry?.retriableStatuses ?? [429, 500, 502, 503, 504],\n      honorRetryAfter: this.#options.retry?.honorRetryAfter ?? true,\n    }\n\n    const fetchFn = this.#options.fetch ?? globalThis.fetch\n    const requestTimeoutMs = this.#options.requestTimeoutMs ?? 0\n    const maxAttempts = retryCfg.maxAttempts\n\n    let attempt = 1\n    while (attempt <= maxAttempts) {\n      const controller = new AbortController()\n      let timeoutHandle: ReturnType<typeof setTimeout> | undefined\n      if (requestTimeoutMs > 0) {\n        timeoutHandle = setTimeout(() => controller.abort(), requestTimeoutMs)\n      }\n\n      let response: Response\n      try {\n        response = await fetchFn(url, {\n          method: 'POST',\n          headers,\n          body: JSON.stringify(body),\n          signal: controller.signal,\n        })\n      } catch (err) {\n        if (timeoutHandle !== undefined) clearTimeout(timeoutHandle)\n        if (controller.signal.aborted) {\n          // Timed out before headers — retry if attempts remain.\n          if (attempt < maxAttempts) {\n            await sleepWithJitter(computeBackoff(attempt, retryCfg))\n            attempt += 1\n            continue\n          }\n          throw new E_OLLAMA_EMBEDDINGS_REQUEST_TIMEOUT([requestTimeoutMs])\n        }\n        // Generic transport failure — retry if attempts remain, else surface as status 0.\n        if (attempt < maxAttempts) {\n          await sleepWithJitter(computeBackoff(attempt, retryCfg))\n          attempt += 1\n          continue\n        }\n        throw new E_OLLAMA_EMBEDDINGS_HTTP_ERROR([0, isError(err) ? err.message : String(err)])\n      }\n      if (timeoutHandle !== undefined) clearTimeout(timeoutHandle)\n\n      if (!response.ok) {\n        const status = response.status\n        const retriable = retryCfg.retriableStatuses.includes(status)\n        if (retriable && attempt < maxAttempts) {\n          let delay = computeBackoff(attempt, retryCfg)\n          if (retryCfg.honorRetryAfter) {\n            const ra = response.headers.get('Retry-After')\n            if (ra) {\n              const raMs = parseRetryAfter(ra)\n              if (raMs > 0) delay = Math.min(Math.max(delay, raMs), retryCfg.maxDelayMs)\n            }\n          }\n          await sleepWithJitter(delay)\n          attempt += 1\n          continue\n        }\n        const detail = await response.text().catch(() => '')\n        throw new E_OLLAMA_EMBEDDINGS_HTTP_ERROR([status, detail])\n      }\n\n      let parsed: OllamaEmbeddingsResponseBody\n      try {\n        parsed = (await response.json()) as OllamaEmbeddingsResponseBody\n      } catch (err) {\n        throw new E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE([isError(err) ? err.message : String(err)])\n      }\n      if (\n        !parsed ||\n        !Array.isArray(parsed.embeddings) ||\n        parsed.embeddings.length !== input.length\n      ) {\n        throw new E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE([\n          `expected ${input.length} vectors, got ${parsed?.embeddings?.length ?? 'none'}`,\n        ])\n      }\n      // Every vector must be an array of finite numbers — a same-length-but-malformed body\n      // (e.g. `[null]`, `[[\"x\"]]`, `[{}]`) must not slip through typed as `number[][]`.\n      for (const vec of parsed.embeddings) {\n        if (!Array.isArray(vec) || !vec.every((n) => typeof n === 'number' && Number.isFinite(n))) {\n          throw new E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE([\n            'response contained a vector that was not an array of finite numbers',\n          ])\n        }\n      }\n      // Ollama returns embeddings positionally (no index field); return in input order directly.\n      return parsed.embeddings\n    }\n\n    // Unreachable: the loop either returns or throws. Satisfies the type checker.\n    throw new E_OLLAMA_EMBEDDINGS_HTTP_ERROR([0, 'retry loop exhausted without a response'])\n  }\n}\n"],"mappings":"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"}

package/batteries/embeddings/ollama/exceptions.cjs

@@ -0,0 +1,48 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../chunk-Cek0wNdY.js");
+const require_exceptions = require("../../../exceptions-BfOYct3J.js");
+require("../../../factories.cjs");
+//#region src/batteries/embeddings/ollama/exceptions.ts
+/**
+* Battery-scoped exception constructors for Ollama Embeddings adapter failures.
+*
+* @module @nhtio/adk/batteries/embeddings/ollama/exceptions
+*
+* @remarks
+* Battery-scoped exception classes for the Ollama Embeddings adapter. These exceptions are owned
+* by the battery (not the ADK core) and are minted via `createException` from
+* `@nhtio/adk/factories`. Re-exported from the battery's barrel.
+*
+* The categories mirror the OpenAI Embeddings battery one-to-one so the two batteries fail with
+* parallel semantics — only the engine-specific transport exception differs.
+*/
+/**
+* Thrown when the resolved adapter options fail validation against
+* `ollamaEmbeddingsOptionsSchema` — e.g. a missing/empty `model`, or an unknown option key.
+* Fatal: config bugs fail loud at construction time, not at embed time.
+*/
+var E_INVALID_OLLAMA_EMBEDDINGS_OPTIONS = require_exceptions.createException("E_INVALID_OLLAMA_EMBEDDINGS_OPTIONS", "Invalid Ollama Embeddings adapter options: %s", "E_INVALID_OLLAMA_EMBEDDINGS_OPTIONS", 529, true);
+/**
+* Thrown when the upstream `/api/embed` endpoint returns a non-2xx response (after retries
+* are exhausted), or the transport throws. Non-fatal. Printf args: `[status, detail]` — `status`
+* is `0` for a transport-level failure with no HTTP response.
+*/
+var E_OLLAMA_EMBEDDINGS_HTTP_ERROR = require_exceptions.createException("E_OLLAMA_EMBEDDINGS_HTTP_ERROR", "Ollama Embeddings HTTP error %d: %s", "E_OLLAMA_EMBEDDINGS_HTTP_ERROR", 502, false);
+/**
+* Thrown when the request handshake does not complete before `requestTimeoutMs` (and retries are
+* exhausted). Non-fatal. Printf arg: `[requestTimeoutMs]`.
+*/
+var E_OLLAMA_EMBEDDINGS_REQUEST_TIMEOUT = require_exceptions.createException("E_OLLAMA_EMBEDDINGS_REQUEST_TIMEOUT", "Ollama Embeddings request timed out after %dms", "E_OLLAMA_EMBEDDINGS_REQUEST_TIMEOUT", 504, false);
+/**
+* Thrown when a 2xx response body cannot be parsed into the expected
+* `{ embeddings: number[][] }` shape (malformed JSON, missing `embeddings`, wrong vector
+* count). Non-fatal. Printf arg: `[detail]`.
+*/
+var E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE = require_exceptions.createException("E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE", "Ollama Embeddings response malformed: %s", "E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE", 502, false);
+//#endregion
+exports.E_INVALID_OLLAMA_EMBEDDINGS_OPTIONS = E_INVALID_OLLAMA_EMBEDDINGS_OPTIONS;
+exports.E_OLLAMA_EMBEDDINGS_HTTP_ERROR = E_OLLAMA_EMBEDDINGS_HTTP_ERROR;
+exports.E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE = E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE;
+exports.E_OLLAMA_EMBEDDINGS_REQUEST_TIMEOUT = E_OLLAMA_EMBEDDINGS_REQUEST_TIMEOUT;
+
+//# sourceMappingURL=exceptions.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.cjs","names":[],"sources":["../../../../src/batteries/embeddings/ollama/exceptions.ts"],"sourcesContent":["/**\n * Battery-scoped exception constructors for Ollama Embeddings adapter failures.\n *\n * @module @nhtio/adk/batteries/embeddings/ollama/exceptions\n *\n * @remarks\n * Battery-scoped exception classes for the Ollama Embeddings adapter. These exceptions are owned\n * by the battery (not the ADK core) and are minted via `createException` from\n * `@nhtio/adk/factories`. Re-exported from the battery's barrel.\n *\n * The categories mirror the OpenAI Embeddings battery one-to-one so the two batteries fail with\n * parallel semantics — only the engine-specific transport exception differs.\n */\n\nimport { createException } from '@nhtio/adk/factories'\n\n/**\n * Thrown when the resolved adapter options fail validation against\n * `ollamaEmbeddingsOptionsSchema` — e.g. a missing/empty `model`, or an unknown option key.\n * Fatal: config bugs fail loud at construction time, not at embed time.\n */\nexport const E_INVALID_OLLAMA_EMBEDDINGS_OPTIONS = createException<[string]>(\n  'E_INVALID_OLLAMA_EMBEDDINGS_OPTIONS',\n  'Invalid Ollama Embeddings adapter options: %s',\n  'E_INVALID_OLLAMA_EMBEDDINGS_OPTIONS',\n  529,\n  true\n)\n\n/**\n * Thrown when the upstream `/api/embed` endpoint returns a non-2xx response (after retries\n * are exhausted), or the transport throws. Non-fatal. Printf args: `[status, detail]` — `status`\n * is `0` for a transport-level failure with no HTTP response.\n */\nexport const E_OLLAMA_EMBEDDINGS_HTTP_ERROR = createException<[number, string]>(\n  'E_OLLAMA_EMBEDDINGS_HTTP_ERROR',\n  'Ollama Embeddings HTTP error %d: %s',\n  'E_OLLAMA_EMBEDDINGS_HTTP_ERROR',\n  502,\n  false\n)\n\n/**\n * Thrown when the request handshake does not complete before `requestTimeoutMs` (and retries are\n * exhausted). Non-fatal. Printf arg: `[requestTimeoutMs]`.\n */\nexport const E_OLLAMA_EMBEDDINGS_REQUEST_TIMEOUT = createException<[number]>(\n  'E_OLLAMA_EMBEDDINGS_REQUEST_TIMEOUT',\n  'Ollama Embeddings request timed out after %dms',\n  'E_OLLAMA_EMBEDDINGS_REQUEST_TIMEOUT',\n  504,\n  false\n)\n\n/**\n * Thrown when a 2xx response body cannot be parsed into the expected\n * `{ embeddings: number[][] }` shape (malformed JSON, missing `embeddings`, wrong vector\n * count). Non-fatal. Printf arg: `[detail]`.\n */\nexport const E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE = createException<[string]>(\n  'E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE',\n  'Ollama Embeddings response malformed: %s',\n  'E_OLLAMA_EMBEDDINGS_MALFORMED_RESPONSE',\n  502,\n  false\n)\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAqBA,IAAa,sCAAsC,mBAAA,gBACjD,uCACA,iDACA,uCACA,KACA,IACF;;;;;;AAOA,IAAa,iCAAiC,mBAAA,gBAC5C,kCACA,uCACA,kCACA,KACA,KACF;;;;;AAMA,IAAa,sCAAsC,mBAAA,gBACjD,uCACA,kDACA,uCACA,KACA,KACF;;;;;;AAOA,IAAa,yCAAyC,mBAAA,gBACpD,0CACA,4CACA,0CACA,KACA,KACF"}