@nhtio/adk 1.20260531.2 → 1.20260601.0

package/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to `@nhtio/adk` are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 2026-06-01
+
+### Added
+
+- **Embeddings batteries** (`@nhtio/adk/batteries/embeddings/openai`,
+  `@nhtio/adk/batteries/embeddings/webllm`) — two opt-in embedders that share one shape and differ
+  only in their engine. `OpenAIEmbeddingsAdapter` POSTs to any OpenAI-`/v1/embeddings`-compatible
+  endpoint over raw `fetch` (Node/browser/edge/workers); `WebLLMEmbeddingsAdapter` embeds in-process
+  on WebGPU via `@mlc-ai/web-llm`. Both expose `embed` / `embedMany` / `dimensions` / `preload` /
+  `reset` / `isAvailable`, return wire-native `number[]` / `number[][]`, require an explicit `model`
+  (no default), and handle query/document instruction prefixes identically via a shared
+  `kind: 'query' | 'document'` option. The environment-neutral OpenAI battery is re-exported from
+  `@nhtio/adk/batteries/embeddings`; the WebGPU-only WebLLM battery is reachable only via its own
+  subpath. Embedders are tools you call from your own retrieval middleware — they do not plug into
+  an executor slot. See the new `docs/assembly/batteries-embeddings.md`.
+
+### Fixed
+
+- **`E_INVALID_TURN_RUNNER_CONFIG` now names the offending field.** A misconfigured `TurnRunner`
+  previously threw a generic "cannot be instantiated with the provided configuration" with no
+  indication of which field failed. The exception now carries the validator's field-level detail
+  (e.g. `…: storeMediaBytesCallback is required`) and attaches the raw `ValidationError` on `cause`.
+- **Unknown-tool errors now list the available tools.** When the model calls a tool that is not in
+  the registry, the OpenAI and WebLLM Chat Completions batteries persist a tool-call error reading
+  `Tool not found: <name>. Available tools: <a, b, c>.` (or `No tools are available this turn.`) so
+  the model can self-correct on the next iteration instead of dead-ending on an opaque "not found".
+
 ## 2026-05-31
 
 ### Added

package/batteries/embeddings/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Environment-neutral aggregate barrel for bundled embeddings batteries.
+ *
+ * @module @nhtio/adk/batteries/embeddings
+ *
+ * @remarks
+ * Aggregate barrel for the embeddings batteries. Re-exports only the **environment-neutral**
+ * embeddings battery — currently just the OpenAI battery (raw `fetch`, runs anywhere) — so
+ * consumers can import this barrel from either Node or the browser without dragging in
+ * environment-specific runtime requirements.
+ *
+ * The browser/WebGPU-only WebLLM embeddings battery is reachable only through its own subpath:
+ *
+ * - `@nhtio/adk/batteries/embeddings/webllm` — browser-only (uses WebGPU via `@mlc-ai/web-llm`).
+ *
+ * Deep-import that subpath when you need it; don't expect it to be re-exported here. The two
+ * batteries share one option base and an identical method surface — see
+ * {@link @nhtio/adk/batteries/embeddings/openai/types!BaseEmbeddingsAdapterOptions}.
+ */
+export { OpenAIEmbeddingsAdapter } from "./openai/index";
+export { applyEmbeddingPrefix } from "./openai/index";
+export { openAIEmbeddingsOptionsSchema } from "./openai/index";
+export { validateOptions as validateOpenAIEmbeddingsOptions } from "./openai/index";
+export type { EmbeddingKind, EmbedOptions, EmbeddingsRetryConfig, BaseEmbeddingsAdapterOptions, OpenAIEmbeddingsAdapterOptions, OpenAIEmbeddingsRequestBody, OpenAIEmbeddingsResponseBody, } from "./openai/index";
+export { E_INVALID_OPENAI_EMBEDDINGS_OPTIONS, E_OPENAI_EMBEDDINGS_HTTP_ERROR, E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT, E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE, } from "./openai/index";

package/batteries/embeddings/openai/adapter.cjs

@@ -0,0 +1,185 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../chunk-Ble4zEEl.js");
+const require_tool_registry = require("../../../tool_registry-CoM6fy7F.js");
+require("../../../guards.cjs");
+const require_lib_utils_retry = require("../../../lib/utils/retry.cjs");
+const require_batteries_embeddings_openai_exceptions = require("./exceptions.cjs");
+const require_batteries_embeddings_openai_validation = require("./validation.cjs");
+const require_batteries_embeddings_openai_helpers = require("./helpers.cjs");
+//#region src/batteries/embeddings/openai/adapter.ts
+/**
+* Cross-environment OpenAI Embeddings adapter battery.
+*
+* @module @nhtio/adk/batteries/embeddings/openai/adapter
+*
+* @remarks
+* Opinionated embeddings battery for the OpenAI `/v1/embeddings` wire shape. Ships an
+* {@link OpenAIEmbeddingsAdapter} that targets any OpenAI-`/v1/embeddings`-compatible endpoint
+* (OpenAI proper, Azure-behind-proxy, vLLM, Together, a local gateway, etc.) 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
+* WebLLM 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/openai/validation!validateOptions} and throws
+* {@link @nhtio/adk/batteries/embeddings/openai/exceptions!E_INVALID_OPENAI_EMBEDDINGS_OPTIONS} on failure — config bugs fail loud, not at embed time.
+*/
+/**
+* Embeddings adapter for the OpenAI `/v1/embeddings` wire shape.
+*
+* @remarks
+* Reusable: construct once, call {@link OpenAIEmbeddingsAdapter.embed} / {@link embedMany} as many
+* times as needed. `embedMany` issues one request per call (OpenAI embeds a batch in a single
+* round-trip); `embed` is sugar over `embedMany([text])`.
+*/
+var OpenAIEmbeddingsAdapter = class OpenAIEmbeddingsAdapter {
+	#options;
+	/**
+	* Whether this battery can run in the current environment. For the HTTP-backed OpenAI 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/openai/exceptions!E_INVALID_OPENAI_EMBEDDINGS_OPTIONS} when `options` does not satisfy
+	*   {@link @nhtio/adk/batteries/embeddings/openai/validation!openAIEmbeddingsOptionsSchema} (e.g. missing `model`).
+	*/
+	constructor(options) {
+		this.#options = require_batteries_embeddings_openai_validation.validateOptions(options);
+	}
+	/** Declared output dimensionality (from options), or `undefined` if not configured. */
+	get dimensions() {
+		return this.#options.dimensions;
+	}
+	/** See {@link OpenAIEmbeddingsAdapter.isAvailable}. Instance alias for surface-parity. */
+	isAvailable() {
+		return OpenAIEmbeddingsAdapter.isAvailable();
+	}
+	/**
+	* No-op warm-up. The OpenAI 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/openai/exceptions!E_OPENAI_EMBEDDINGS_HTTP_ERROR} on a non-2xx response or transport failure.
+	* @throws {@link @nhtio/adk/batteries/embeddings/openai/exceptions!E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT} when the handshake exceeds `requestTimeoutMs`.
+	* @throws {@link @nhtio/adk/batteries/embeddings/openai/exceptions!E_OPENAI_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,
+			encoding_format: "float",
+			...this.#options.dimensions !== void 0 ? { dimensions: this.#options.dimensions } : {}
+		};
+		const rawBase = this.#options.baseURL ?? "https://api.openai.com/v1";
+		const url = `${rawBase.endsWith("/") ? rawBase.slice(0, -1) : rawBase}/embeddings`;
+		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_openai_exceptions.E_OPENAI_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_openai_exceptions.E_OPENAI_EMBEDDINGS_HTTP_ERROR([0, require_tool_registry.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_openai_exceptions.E_OPENAI_EMBEDDINGS_HTTP_ERROR([status, await response.text().catch(() => "")]);
+			}
+			let parsed;
+			try {
+				parsed = await response.json();
+			} catch (err) {
+				throw new require_batteries_embeddings_openai_exceptions.E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE([require_tool_registry.isError(err) ? err.message : String(err)]);
+			}
+			if (!parsed || !Array.isArray(parsed.data) || parsed.data.length !== input.length) throw new require_batteries_embeddings_openai_exceptions.E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE([`expected ${input.length} vectors, got ${parsed?.data?.length ?? "none"}`]);
+			return parsed.data.slice().sort((a, b) => a.index - b.index).map((d) => d.embedding);
+		}
+		throw new require_batteries_embeddings_openai_exceptions.E_OPENAI_EMBEDDINGS_HTTP_ERROR([0, "retry loop exhausted without a response"]);
+	}
+};
+//#endregion
+exports.OpenAIEmbeddingsAdapter = OpenAIEmbeddingsAdapter;
+
+//# sourceMappingURL=adapter.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.cjs","names":["#options"],"sources":["../../../../src/batteries/embeddings/openai/adapter.ts"],"sourcesContent":["/**\n * Cross-environment OpenAI Embeddings adapter battery.\n *\n * @module @nhtio/adk/batteries/embeddings/openai/adapter\n *\n * @remarks\n * Opinionated embeddings battery for the OpenAI `/v1/embeddings` wire shape. Ships an\n * {@link OpenAIEmbeddingsAdapter} that targets any OpenAI-`/v1/embeddings`-compatible endpoint\n * (OpenAI proper, Azure-behind-proxy, vLLM, Together, a local gateway, etc.) 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 * WebLLM 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/openai/validation!validateOptions} and throws\n * {@link @nhtio/adk/batteries/embeddings/openai/exceptions!E_INVALID_OPENAI_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 './helpers'\nimport { computeBackoff, sleepWithJitter, parseRetryAfter } from '../../../lib/utils/retry'\nimport {\n  E_OPENAI_EMBEDDINGS_HTTP_ERROR,\n  E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT,\n  E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE,\n} from './exceptions'\nimport type {\n  EmbedOptions,\n  EmbeddingsRetryConfig,\n  OpenAIEmbeddingsAdapterOptions,\n  OpenAIEmbeddingsRequestBody,\n  OpenAIEmbeddingsResponseBody,\n} from './types'\n\n// ─── Adapter class ────────────────────────────────────────────────────────────\n\n/**\n * Embeddings adapter for the OpenAI `/v1/embeddings` wire shape.\n *\n * @remarks\n * Reusable: construct once, call {@link OpenAIEmbeddingsAdapter.embed} / {@link embedMany} as many\n * times as needed. `embedMany` issues one request per call (OpenAI embeds a batch in a single\n * round-trip); `embed` is sugar over `embedMany([text])`.\n */\nexport class OpenAIEmbeddingsAdapter {\n  readonly #options: OpenAIEmbeddingsAdapterOptions\n\n  /**\n   * Whether this battery can run in the current environment. For the HTTP-backed OpenAI 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/openai/exceptions!E_INVALID_OPENAI_EMBEDDINGS_OPTIONS} when `options` does not satisfy\n   *   {@link @nhtio/adk/batteries/embeddings/openai/validation!openAIEmbeddingsOptionsSchema} (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 OpenAIEmbeddingsAdapter.isAvailable}. Instance alias for surface-parity. */\n  isAvailable(): boolean {\n    return OpenAIEmbeddingsAdapter.isAvailable()\n  }\n\n  /**\n   * No-op warm-up. The OpenAI 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 OpenAI 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/openai/exceptions!E_OPENAI_EMBEDDINGS_HTTP_ERROR} on a non-2xx response or transport failure.\n   * @throws {@link @nhtio/adk/batteries/embeddings/openai/exceptions!E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT} when the handshake exceeds `requestTimeoutMs`.\n   * @throws {@link @nhtio/adk/batteries/embeddings/openai/exceptions!E_OPENAI_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: OpenAIEmbeddingsRequestBody = {\n      model: this.#options.model,\n      input,\n      encoding_format: 'float',\n      ...(this.#options.dimensions !== undefined ? { dimensions: this.#options.dimensions } : {}),\n    }\n\n    const rawBase = this.#options.baseURL ?? 'https://api.openai.com/v1'\n    const baseURL = rawBase.endsWith('/') ? rawBase.slice(0, -1) : rawBase\n    const url = `${baseURL}/embeddings`\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_OPENAI_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_OPENAI_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_OPENAI_EMBEDDINGS_HTTP_ERROR([status, detail])\n      }\n\n      let parsed: OpenAIEmbeddingsResponseBody\n      try {\n        parsed = (await response.json()) as OpenAIEmbeddingsResponseBody\n      } catch (err) {\n        throw new E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE([isError(err) ? err.message : String(err)])\n      }\n      if (!parsed || !Array.isArray(parsed.data) || parsed.data.length !== input.length) {\n        throw new E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE([\n          `expected ${input.length} vectors, got ${parsed?.data?.length ?? 'none'}`,\n        ])\n      }\n      // OpenAI may return data out of order; sort by `index` to restore input order.\n      return parsed.data\n        .slice()\n        .sort((a, b) => a.index - b.index)\n        .map((d) => d.embedding)\n    }\n\n    // Unreachable: the loop either returns or throws. Satisfies the type checker.\n    throw new E_OPENAI_EMBEDDINGS_HTTP_ERROR([0, 'retry loop exhausted without a response'])\n  }\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,74 @@
+/**
+ * Cross-environment OpenAI Embeddings adapter battery.
+ *
+ * @module @nhtio/adk/batteries/embeddings/openai/adapter
+ *
+ * @remarks
+ * Opinionated embeddings battery for the OpenAI `/v1/embeddings` wire shape. Ships an
+ * {@link OpenAIEmbeddingsAdapter} that targets any OpenAI-`/v1/embeddings`-compatible endpoint
+ * (OpenAI proper, Azure-behind-proxy, vLLM, Together, a local gateway, etc.) 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
+ * WebLLM 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/openai/validation!validateOptions} and throws
+ * {@link @nhtio/adk/batteries/embeddings/openai/exceptions!E_INVALID_OPENAI_EMBEDDINGS_OPTIONS} on failure — config bugs fail loud, not at embed time.
+ */
+import type { EmbedOptions } from "./types";
+/**
+ * Embeddings adapter for the OpenAI `/v1/embeddings` wire shape.
+ *
+ * @remarks
+ * Reusable: construct once, call {@link OpenAIEmbeddingsAdapter.embed} / {@link embedMany} as many
+ * times as needed. `embedMany` issues one request per call (OpenAI embeds a batch in a single
+ * round-trip); `embed` is sugar over `embedMany([text])`.
+ */
+export declare class OpenAIEmbeddingsAdapter {
+    #private;
+    /**
+     * Whether this battery can run in the current environment. For the HTTP-backed OpenAI 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/openai/exceptions!E_INVALID_OPENAI_EMBEDDINGS_OPTIONS} when `options` does not satisfy
+     *   {@link @nhtio/adk/batteries/embeddings/openai/validation!openAIEmbeddingsOptionsSchema} (e.g. missing `model`).
+     */
+    constructor(options: unknown);
+    /** Declared output dimensionality (from options), or `undefined` if not configured. */
+    get dimensions(): number | undefined;
+    /** See {@link OpenAIEmbeddingsAdapter.isAvailable}. Instance alias for surface-parity. */
+    isAvailable(): boolean;
+    /**
+     * No-op warm-up. The OpenAI 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/openai/exceptions!E_OPENAI_EMBEDDINGS_HTTP_ERROR} on a non-2xx response or transport failure.
+     * @throws {@link @nhtio/adk/batteries/embeddings/openai/exceptions!E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT} when the handshake exceeds `requestTimeoutMs`.
+     * @throws {@link @nhtio/adk/batteries/embeddings/openai/exceptions!E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE} when the 2xx body is not the expected shape.
+     */
+    embedMany(texts: string[], opts?: EmbedOptions): Promise<number[][]>;
+}

package/batteries/embeddings/openai/adapter.mjs

@@ -0,0 +1,183 @@
+import { o as isError } from "../../../tool_registry-CbtMt21B.mjs";
+import "../../../guards.mjs";
+import { computeBackoff, parseRetryAfter, sleepWithJitter } from "../../../lib/utils/retry.mjs";
+import { E_OPENAI_EMBEDDINGS_HTTP_ERROR, E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE, E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT } from "./exceptions.mjs";
+import { validateOptions } from "./validation.mjs";
+import { applyEmbeddingPrefix } from "./helpers.mjs";
+//#region src/batteries/embeddings/openai/adapter.ts
+/**
+* Cross-environment OpenAI Embeddings adapter battery.
+*
+* @module @nhtio/adk/batteries/embeddings/openai/adapter
+*
+* @remarks
+* Opinionated embeddings battery for the OpenAI `/v1/embeddings` wire shape. Ships an
+* {@link OpenAIEmbeddingsAdapter} that targets any OpenAI-`/v1/embeddings`-compatible endpoint
+* (OpenAI proper, Azure-behind-proxy, vLLM, Together, a local gateway, etc.) 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
+* WebLLM 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/openai/validation!validateOptions} and throws
+* {@link @nhtio/adk/batteries/embeddings/openai/exceptions!E_INVALID_OPENAI_EMBEDDINGS_OPTIONS} on failure — config bugs fail loud, not at embed time.
+*/
+/**
+* Embeddings adapter for the OpenAI `/v1/embeddings` wire shape.
+*
+* @remarks
+* Reusable: construct once, call {@link OpenAIEmbeddingsAdapter.embed} / {@link embedMany} as many
+* times as needed. `embedMany` issues one request per call (OpenAI embeds a batch in a single
+* round-trip); `embed` is sugar over `embedMany([text])`.
+*/
+var OpenAIEmbeddingsAdapter = class OpenAIEmbeddingsAdapter {
+	#options;
+	/**
+	* Whether this battery can run in the current environment. For the HTTP-backed OpenAI 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/openai/exceptions!E_INVALID_OPENAI_EMBEDDINGS_OPTIONS} when `options` does not satisfy
+	*   {@link @nhtio/adk/batteries/embeddings/openai/validation!openAIEmbeddingsOptionsSchema} (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 OpenAIEmbeddingsAdapter.isAvailable}. Instance alias for surface-parity. */
+	isAvailable() {
+		return OpenAIEmbeddingsAdapter.isAvailable();
+	}
+	/**
+	* No-op warm-up. The OpenAI 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/openai/exceptions!E_OPENAI_EMBEDDINGS_HTTP_ERROR} on a non-2xx response or transport failure.
+	* @throws {@link @nhtio/adk/batteries/embeddings/openai/exceptions!E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT} when the handshake exceeds `requestTimeoutMs`.
+	* @throws {@link @nhtio/adk/batteries/embeddings/openai/exceptions!E_OPENAI_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,
+			encoding_format: "float",
+			...this.#options.dimensions !== void 0 ? { dimensions: this.#options.dimensions } : {}
+		};
+		const rawBase = this.#options.baseURL ?? "https://api.openai.com/v1";
+		const url = `${rawBase.endsWith("/") ? rawBase.slice(0, -1) : rawBase}/embeddings`;
+		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_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT([requestTimeoutMs]);
+				}
+				if (attempt < maxAttempts) {
+					await sleepWithJitter(computeBackoff(attempt, retryCfg));
+					attempt += 1;
+					continue;
+				}
+				throw new E_OPENAI_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_OPENAI_EMBEDDINGS_HTTP_ERROR([status, await response.text().catch(() => "")]);
+			}
+			let parsed;
+			try {
+				parsed = await response.json();
+			} catch (err) {
+				throw new E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE([isError(err) ? err.message : String(err)]);
+			}
+			if (!parsed || !Array.isArray(parsed.data) || parsed.data.length !== input.length) throw new E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE([`expected ${input.length} vectors, got ${parsed?.data?.length ?? "none"}`]);
+			return parsed.data.slice().sort((a, b) => a.index - b.index).map((d) => d.embedding);
+		}
+		throw new E_OPENAI_EMBEDDINGS_HTTP_ERROR([0, "retry loop exhausted without a response"]);
+	}
+};
+//#endregion
+export { OpenAIEmbeddingsAdapter };
+
+//# sourceMappingURL=adapter.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.mjs","names":["#options"],"sources":["../../../../src/batteries/embeddings/openai/adapter.ts"],"sourcesContent":["/**\n * Cross-environment OpenAI Embeddings adapter battery.\n *\n * @module @nhtio/adk/batteries/embeddings/openai/adapter\n *\n * @remarks\n * Opinionated embeddings battery for the OpenAI `/v1/embeddings` wire shape. Ships an\n * {@link OpenAIEmbeddingsAdapter} that targets any OpenAI-`/v1/embeddings`-compatible endpoint\n * (OpenAI proper, Azure-behind-proxy, vLLM, Together, a local gateway, etc.) 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 * WebLLM 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/openai/validation!validateOptions} and throws\n * {@link @nhtio/adk/batteries/embeddings/openai/exceptions!E_INVALID_OPENAI_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 './helpers'\nimport { computeBackoff, sleepWithJitter, parseRetryAfter } from '../../../lib/utils/retry'\nimport {\n  E_OPENAI_EMBEDDINGS_HTTP_ERROR,\n  E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT,\n  E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE,\n} from './exceptions'\nimport type {\n  EmbedOptions,\n  EmbeddingsRetryConfig,\n  OpenAIEmbeddingsAdapterOptions,\n  OpenAIEmbeddingsRequestBody,\n  OpenAIEmbeddingsResponseBody,\n} from './types'\n\n// ─── Adapter class ────────────────────────────────────────────────────────────\n\n/**\n * Embeddings adapter for the OpenAI `/v1/embeddings` wire shape.\n *\n * @remarks\n * Reusable: construct once, call {@link OpenAIEmbeddingsAdapter.embed} / {@link embedMany} as many\n * times as needed. `embedMany` issues one request per call (OpenAI embeds a batch in a single\n * round-trip); `embed` is sugar over `embedMany([text])`.\n */\nexport class OpenAIEmbeddingsAdapter {\n  readonly #options: OpenAIEmbeddingsAdapterOptions\n\n  /**\n   * Whether this battery can run in the current environment. For the HTTP-backed OpenAI 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/openai/exceptions!E_INVALID_OPENAI_EMBEDDINGS_OPTIONS} when `options` does not satisfy\n   *   {@link @nhtio/adk/batteries/embeddings/openai/validation!openAIEmbeddingsOptionsSchema} (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 OpenAIEmbeddingsAdapter.isAvailable}. Instance alias for surface-parity. */\n  isAvailable(): boolean {\n    return OpenAIEmbeddingsAdapter.isAvailable()\n  }\n\n  /**\n   * No-op warm-up. The OpenAI 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 OpenAI 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/openai/exceptions!E_OPENAI_EMBEDDINGS_HTTP_ERROR} on a non-2xx response or transport failure.\n   * @throws {@link @nhtio/adk/batteries/embeddings/openai/exceptions!E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT} when the handshake exceeds `requestTimeoutMs`.\n   * @throws {@link @nhtio/adk/batteries/embeddings/openai/exceptions!E_OPENAI_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: OpenAIEmbeddingsRequestBody = {\n      model: this.#options.model,\n      input,\n      encoding_format: 'float',\n      ...(this.#options.dimensions !== undefined ? { dimensions: this.#options.dimensions } : {}),\n    }\n\n    const rawBase = this.#options.baseURL ?? 'https://api.openai.com/v1'\n    const baseURL = rawBase.endsWith('/') ? rawBase.slice(0, -1) : rawBase\n    const url = `${baseURL}/embeddings`\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_OPENAI_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_OPENAI_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_OPENAI_EMBEDDINGS_HTTP_ERROR([status, detail])\n      }\n\n      let parsed: OpenAIEmbeddingsResponseBody\n      try {\n        parsed = (await response.json()) as OpenAIEmbeddingsResponseBody\n      } catch (err) {\n        throw new E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE([isError(err) ? err.message : String(err)])\n      }\n      if (!parsed || !Array.isArray(parsed.data) || parsed.data.length !== input.length) {\n        throw new E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE([\n          `expected ${input.length} vectors, got ${parsed?.data?.length ?? 'none'}`,\n        ])\n      }\n      // OpenAI may return data out of order; sort by `index` to restore input order.\n      return parsed.data\n        .slice()\n        .sort((a, b) => a.index - b.index)\n        .map((d) => d.embedding)\n    }\n\n    // Unreachable: the loop either returns or throws. Satisfies the type checker.\n    throw new E_OPENAI_EMBEDDINGS_HTTP_ERROR([0, 'retry loop exhausted without a response'])\n  }\n}\n"],"mappings":"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"}

package/batteries/embeddings/openai/exceptions.cjs

@@ -0,0 +1,48 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../chunk-Ble4zEEl.js");
+const require_exceptions = require("../../../exceptions-CitH5wZI.js");
+require("../../../factories.cjs");
+//#region src/batteries/embeddings/openai/exceptions.ts
+/**
+* Battery-scoped exception constructors for OpenAI Embeddings adapter failures.
+*
+* @module @nhtio/adk/batteries/embeddings/openai/exceptions
+*
+* @remarks
+* Battery-scoped exception classes for the OpenAI 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 WebLLM 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
+* `openAIEmbeddingsOptionsSchema` — 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_OPENAI_EMBEDDINGS_OPTIONS = require_exceptions.createException("E_INVALID_OPENAI_EMBEDDINGS_OPTIONS", "Invalid OpenAI Embeddings adapter options: %s", "E_INVALID_OPENAI_EMBEDDINGS_OPTIONS", 529, true);
+/**
+* Thrown when the upstream `/v1/embeddings` 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_OPENAI_EMBEDDINGS_HTTP_ERROR = require_exceptions.createException("E_OPENAI_EMBEDDINGS_HTTP_ERROR", "OpenAI Embeddings HTTP error %d: %s", "E_OPENAI_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_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT = require_exceptions.createException("E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT", "OpenAI Embeddings request timed out after %dms", "E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT", 504, false);
+/**
+* Thrown when a 2xx response body cannot be parsed into the expected
+* `{ data: [{ embedding: number[] }] }` shape (malformed JSON, missing `data`, wrong vector
+* count). Non-fatal. Printf arg: `[detail]`.
+*/
+var E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE = require_exceptions.createException("E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE", "OpenAI Embeddings response malformed: %s", "E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE", 502, false);
+//#endregion
+exports.E_INVALID_OPENAI_EMBEDDINGS_OPTIONS = E_INVALID_OPENAI_EMBEDDINGS_OPTIONS;
+exports.E_OPENAI_EMBEDDINGS_HTTP_ERROR = E_OPENAI_EMBEDDINGS_HTTP_ERROR;
+exports.E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE = E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE;
+exports.E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT = E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT;
+
+//# sourceMappingURL=exceptions.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.cjs","names":[],"sources":["../../../../src/batteries/embeddings/openai/exceptions.ts"],"sourcesContent":["/**\n * Battery-scoped exception constructors for OpenAI Embeddings adapter failures.\n *\n * @module @nhtio/adk/batteries/embeddings/openai/exceptions\n *\n * @remarks\n * Battery-scoped exception classes for the OpenAI 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 WebLLM 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 * `openAIEmbeddingsOptionsSchema` — 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_OPENAI_EMBEDDINGS_OPTIONS = createException<[string]>(\n  'E_INVALID_OPENAI_EMBEDDINGS_OPTIONS',\n  'Invalid OpenAI Embeddings adapter options: %s',\n  'E_INVALID_OPENAI_EMBEDDINGS_OPTIONS',\n  529,\n  true\n)\n\n/**\n * Thrown when the upstream `/v1/embeddings` 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_OPENAI_EMBEDDINGS_HTTP_ERROR = createException<[number, string]>(\n  'E_OPENAI_EMBEDDINGS_HTTP_ERROR',\n  'OpenAI Embeddings HTTP error %d: %s',\n  'E_OPENAI_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_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT = createException<[number]>(\n  'E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT',\n  'OpenAI Embeddings request timed out after %dms',\n  'E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT',\n  504,\n  false\n)\n\n/**\n * Thrown when a 2xx response body cannot be parsed into the expected\n * `{ data: [{ embedding: number[] }] }` shape (malformed JSON, missing `data`, wrong vector\n * count). Non-fatal. Printf arg: `[detail]`.\n */\nexport const E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE = createException<[string]>(\n  'E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE',\n  'OpenAI Embeddings response malformed: %s',\n  'E_OPENAI_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"}