@nhtio/adk 1.20260531.2 → 1.20260602.0

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

@@ -0,0 +1,45 @@
+/**
+ * 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.
+ */
+export declare const E_INVALID_OPENAI_EMBEDDINGS_OPTIONS: import("../../../factories").CreatedException<[
+    string
+]>;
+/**
+ * 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.
+ */
+export declare const E_OPENAI_EMBEDDINGS_HTTP_ERROR: import("../../../factories").CreatedException<[
+    number,
+    string
+]>;
+/**
+ * Thrown when the request handshake does not complete before `requestTimeoutMs` (and retries are
+ * exhausted). Non-fatal. Printf arg: `[requestTimeoutMs]`.
+ */
+export declare const E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT: import("../../../factories").CreatedException<[
+    number
+]>;
+/**
+ * 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]`.
+ */
+export declare const E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE: import("../../../factories").CreatedException<[
+    string
+]>;

package/batteries/embeddings/openai/exceptions.mjs

@@ -0,0 +1,43 @@
+import { t as createException } from "../../../exceptions-BeWH2FwP.mjs";
+import "../../../factories.mjs";
+//#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 = 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 = 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 = 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 = createException("E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE", "OpenAI Embeddings response malformed: %s", "E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE", 502, false);
+//#endregion
+export { E_INVALID_OPENAI_EMBEDDINGS_OPTIONS, E_OPENAI_EMBEDDINGS_HTTP_ERROR, E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE, E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT };
+
+//# sourceMappingURL=exceptions.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"exceptions.mjs","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,gBACjD,uCACA,iDACA,uCACA,KACA,IACF;;;;;;AAOA,IAAa,iCAAiC,gBAC5C,kCACA,uCACA,kCACA,KACA,KACF;;;;;AAMA,IAAa,sCAAsC,gBACjD,uCACA,kDACA,uCACA,KACA,KACF;;;;;;AAOA,IAAa,yCAAyC,gBACpD,0CACA,4CACA,0CACA,KACA,KACF"}

package/batteries/embeddings/openai/helpers.cjs

@@ -0,0 +1,25 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../chunk-Ble4zEEl.js");
+//#region src/batteries/embeddings/openai/helpers.ts
+/**
+* Applies the configured query/document instruction prefix to a batch of inputs.
+*
+* @remarks
+* `kind: 'query'` → prepend `queryPrefix` (if set); `kind: 'document'` → prepend `documentPrefix`
+* (if set). When the relevant prefix is unset, inputs pass through verbatim. This is the single
+* source of truth for prefix handling shared by both batteries.
+*
+* @param texts - The raw inputs to embed.
+* @param kind - Whether these are queries or documents.
+* @param options - Carries `queryPrefix` / `documentPrefix`.
+* @returns A new array with prefixes applied (never mutates the input).
+*/
+var applyEmbeddingPrefix = (texts, kind, options) => {
+	const prefix = kind === "query" ? options.queryPrefix : options.documentPrefix;
+	if (!prefix) return texts.slice();
+	return texts.map((t) => `${prefix}${t}`);
+};
+//#endregion
+exports.applyEmbeddingPrefix = applyEmbeddingPrefix;
+
+//# sourceMappingURL=helpers.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.cjs","names":[],"sources":["../../../../src/batteries/embeddings/openai/helpers.ts"],"sourcesContent":["/**\n * Shared, engine-agnostic helpers for the embeddings batteries.\n *\n * @module @nhtio/adk/batteries/embeddings/openai/helpers\n *\n * @remarks\n * Owned by the OpenAI Embeddings battery (the environment-neutral one) and re-used by the WebLLM\n * Embeddings battery, so query/document prefixing behaves identically across both — the engine is\n * the only difference between the batteries.\n */\n\nimport type { BaseEmbeddingsAdapterOptions, EmbeddingKind } from './types'\n\n/**\n * Applies the configured query/document instruction prefix to a batch of inputs.\n *\n * @remarks\n * `kind: 'query'` → prepend `queryPrefix` (if set); `kind: 'document'` → prepend `documentPrefix`\n * (if set). When the relevant prefix is unset, inputs pass through verbatim. This is the single\n * source of truth for prefix handling shared by both batteries.\n *\n * @param texts - The raw inputs to embed.\n * @param kind - Whether these are queries or documents.\n * @param options - Carries `queryPrefix` / `documentPrefix`.\n * @returns A new array with prefixes applied (never mutates the input).\n */\nexport const applyEmbeddingPrefix = (\n  texts: readonly string[],\n  kind: EmbeddingKind,\n  options: Pick<BaseEmbeddingsAdapterOptions, 'queryPrefix' | 'documentPrefix'>\n): string[] => {\n  const prefix = kind === 'query' ? options.queryPrefix : options.documentPrefix\n  if (!prefix) return texts.slice()\n  return texts.map((t) => `${prefix}${t}`)\n}\n"],"mappings":";;;;;;;;;;;;;;;;AA0BA,IAAa,wBACX,OACA,MACA,YACa;CACb,MAAM,SAAS,SAAS,UAAU,QAAQ,cAAc,QAAQ;CAChE,IAAI,CAAC,QAAQ,OAAO,MAAM,MAAM;CAChC,OAAO,MAAM,KAAK,MAAM,GAAG,SAAS,GAAG;AACzC"}

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

@@ -0,0 +1,25 @@
+/**
+ * Shared, engine-agnostic helpers for the embeddings batteries.
+ *
+ * @module @nhtio/adk/batteries/embeddings/openai/helpers
+ *
+ * @remarks
+ * Owned by the OpenAI Embeddings battery (the environment-neutral one) and re-used by the WebLLM
+ * Embeddings battery, so query/document prefixing behaves identically across both — the engine is
+ * the only difference between the batteries.
+ */
+import type { BaseEmbeddingsAdapterOptions, EmbeddingKind } from "./types";
+/**
+ * Applies the configured query/document instruction prefix to a batch of inputs.
+ *
+ * @remarks
+ * `kind: 'query'` → prepend `queryPrefix` (if set); `kind: 'document'` → prepend `documentPrefix`
+ * (if set). When the relevant prefix is unset, inputs pass through verbatim. This is the single
+ * source of truth for prefix handling shared by both batteries.
+ *
+ * @param texts - The raw inputs to embed.
+ * @param kind - Whether these are queries or documents.
+ * @param options - Carries `queryPrefix` / `documentPrefix`.
+ * @returns A new array with prefixes applied (never mutates the input).
+ */
+export declare const applyEmbeddingPrefix: (texts: readonly string[], kind: EmbeddingKind, options: Pick<BaseEmbeddingsAdapterOptions, "queryPrefix" | "documentPrefix">) => string[];

package/batteries/embeddings/openai/helpers.mjs

@@ -0,0 +1,23 @@
+//#region src/batteries/embeddings/openai/helpers.ts
+/**
+* Applies the configured query/document instruction prefix to a batch of inputs.
+*
+* @remarks
+* `kind: 'query'` → prepend `queryPrefix` (if set); `kind: 'document'` → prepend `documentPrefix`
+* (if set). When the relevant prefix is unset, inputs pass through verbatim. This is the single
+* source of truth for prefix handling shared by both batteries.
+*
+* @param texts - The raw inputs to embed.
+* @param kind - Whether these are queries or documents.
+* @param options - Carries `queryPrefix` / `documentPrefix`.
+* @returns A new array with prefixes applied (never mutates the input).
+*/
+var applyEmbeddingPrefix = (texts, kind, options) => {
+	const prefix = kind === "query" ? options.queryPrefix : options.documentPrefix;
+	if (!prefix) return texts.slice();
+	return texts.map((t) => `${prefix}${t}`);
+};
+//#endregion
+export { applyEmbeddingPrefix };
+
+//# sourceMappingURL=helpers.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.mjs","names":[],"sources":["../../../../src/batteries/embeddings/openai/helpers.ts"],"sourcesContent":["/**\n * Shared, engine-agnostic helpers for the embeddings batteries.\n *\n * @module @nhtio/adk/batteries/embeddings/openai/helpers\n *\n * @remarks\n * Owned by the OpenAI Embeddings battery (the environment-neutral one) and re-used by the WebLLM\n * Embeddings battery, so query/document prefixing behaves identically across both — the engine is\n * the only difference between the batteries.\n */\n\nimport type { BaseEmbeddingsAdapterOptions, EmbeddingKind } from './types'\n\n/**\n * Applies the configured query/document instruction prefix to a batch of inputs.\n *\n * @remarks\n * `kind: 'query'` → prepend `queryPrefix` (if set); `kind: 'document'` → prepend `documentPrefix`\n * (if set). When the relevant prefix is unset, inputs pass through verbatim. This is the single\n * source of truth for prefix handling shared by both batteries.\n *\n * @param texts - The raw inputs to embed.\n * @param kind - Whether these are queries or documents.\n * @param options - Carries `queryPrefix` / `documentPrefix`.\n * @returns A new array with prefixes applied (never mutates the input).\n */\nexport const applyEmbeddingPrefix = (\n  texts: readonly string[],\n  kind: EmbeddingKind,\n  options: Pick<BaseEmbeddingsAdapterOptions, 'queryPrefix' | 'documentPrefix'>\n): string[] => {\n  const prefix = kind === 'query' ? options.queryPrefix : options.documentPrefix\n  if (!prefix) return texts.slice()\n  return texts.map((t) => `${prefix}${t}`)\n}\n"],"mappings":";;;;;;;;;;;;;;AA0BA,IAAa,wBACX,OACA,MACA,YACa;CACb,MAAM,SAAS,SAAS,UAAU,QAAQ,cAAc,QAAQ;CAChE,IAAI,CAAC,QAAQ,OAAO,MAAM,MAAM;CAChC,OAAO,MAAM,KAAK,MAAM,GAAG,SAAS,GAAG;AACzC"}

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

@@ -0,0 +1,17 @@
+/**
+ * OpenAI Embeddings adapter battery — the environment-neutral embeddings battery and owner of the
+ * shared embeddings option base.
+ *
+ * @module @nhtio/adk/batteries/embeddings/openai
+ *
+ * @remarks
+ * Re-exports the adapter class, the shared prefix helper, every option / wire-shape type alias
+ * (including the shared {@link BaseEmbeddingsAdapterOptions}, {@link EmbeddingKind},
+ * {@link EmbedOptions}, and {@link EmbeddingsRetryConfig} that the WebLLM Embeddings battery builds
+ * on), the validation schema + `validateOptions` wrapper, and the battery-scoped exceptions.
+ */
+export { OpenAIEmbeddingsAdapter } from "./adapter";
+export { applyEmbeddingPrefix } from "./helpers";
+export { openAIEmbeddingsOptionsSchema, validateOptions } from "./validation";
+export type { EmbeddingKind, EmbedOptions, EmbeddingsRetryConfig, BaseEmbeddingsAdapterOptions, OpenAIEmbeddingsAdapterOptions, OpenAIEmbeddingsRequestBody, OpenAIEmbeddingsResponseBody, } from "./types";
+export { E_INVALID_OPENAI_EMBEDDINGS_OPTIONS, E_OPENAI_EMBEDDINGS_HTTP_ERROR, E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT, E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE, } from "./exceptions";

package/batteries/embeddings/openai/types.cjs

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

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

@@ -0,0 +1,123 @@
+/**
+ * Option and wire-shape types for the OpenAI Embeddings adapter, plus the shared embeddings
+ * battery base type both bundled embeddings batteries build on.
+ *
+ * @module @nhtio/adk/batteries/embeddings/openai/types
+ *
+ * @remarks
+ * This module owns the **shared** embeddings option base ({@link BaseEmbeddingsAdapterOptions})
+ * and the shared call shapes ({@link EmbeddingKind}, {@link EmbedOptions}). The WebLLM Embeddings
+ * battery re-exports and `extends` these rather than redefining them, so the two batteries differ
+ * only in their engine — exactly how the WebLLM Chat Completions battery extends the OpenAI Chat
+ * Completions option type.
+ */
+/**
+ * Whether a piece of text is being embedded as a search **query** or as a corpus **document**.
+ *
+ * @remarks
+ * Asymmetric-embedding models (e.g. Snowflake Arctic Embed) expect a short instruction prefix on
+ * queries but not on documents. The battery prepends {@link BaseEmbeddingsAdapterOptions.queryPrefix}
+ * when `kind === 'query'` and {@link BaseEmbeddingsAdapterOptions.documentPrefix} when
+ * `kind === 'document'` — each only if the corresponding prefix option is set. Defaults to
+ * `'document'`, so the neutral (un-prefixed, unless a document prefix is configured) path is taken
+ * when a caller does not specify.
+ */
+export type EmbeddingKind = 'query' | 'document';
+/**
+ * Per-call options accepted by `embed` / `embedMany`. Identical across both batteries.
+ */
+export interface EmbedOptions {
+    /** Whether the input is a query or a document. Defaults to `'document'`. */
+    kind?: EmbeddingKind;
+}
+/**
+ * Retry/backoff configuration for HTTP-backed embeddings batteries. Mirrors the chat battery's
+ * `ChatCompletionsRetryConfig` so behavior is consistent across the bundled batteries.
+ */
+export interface EmbeddingsRetryConfig {
+    /** Max total attempts (including the first). Default `1` (no retry). */
+    maxAttempts?: number;
+    /** Base backoff delay in ms; doubled each attempt. Default `500`. */
+    baseDelayMs?: number;
+    /** Backoff ceiling in ms. Default `30_000`. */
+    maxDelayMs?: number;
+    /** HTTP statuses eligible for retry. Default `[429, 500, 502, 503, 504]`. */
+    retriableStatuses?: number[];
+    /** Honor an upstream `Retry-After` header when present. Default `true`. */
+    honorRetryAfter?: boolean;
+}
+/**
+ * Options shared by **every** embeddings battery, regardless of engine.
+ *
+ * @remarks
+ * Engine-specific batteries extend this with their own transport/engine fields. `model` is
+ * **required with no default** — naming the embedding model is the caller's responsibility, never
+ * the battery's.
+ */
+export interface BaseEmbeddingsAdapterOptions {
+    /**
+     * Model id to embed with. **Required, no default.** For OpenAI this is e.g.
+     * `text-embedding-3-small`; for WebLLM it is an MLC embedding model id (e.g.
+     * `snowflake-arctic-embed-m-q0f32-MLC`).
+     */
+    model: string;
+    /**
+     * Instruction prefix prepended to inputs embedded with `kind: 'query'`. Unset → no prefix.
+     * For Snowflake Arctic Embed, the documented value is
+     * `'Represent this sentence for searching relevant passages: '`.
+     */
+    queryPrefix?: string;
+    /**
+     * Instruction prefix prepended to inputs embedded with `kind: 'document'`. Unset → no prefix.
+     * Most asymmetric models (including Arctic) use no document prefix; exposed for symmetry and
+     * the models that do.
+     */
+    documentPrefix?: string;
+    /**
+     * Declared output dimensionality, surfaced via `adapter.dimensions`. Optional metadata for
+     * callers that pre-allocate buffers; the battery does not enforce it against responses.
+     */
+    dimensions?: number;
+}
+/**
+ * Constructor options for {@link @nhtio/adk/batteries/embeddings/openai/adapter!OpenAIEmbeddingsAdapter}.
+ *
+ * @remarks
+ * Extends {@link BaseEmbeddingsAdapterOptions} with the HTTP transport fields the WebLLM battery
+ * deliberately omits. Targets any OpenAI-`/v1/embeddings`-compatible endpoint (OpenAI proper,
+ * Azure-behind-proxy, vLLM, Together, a local gateway, etc.).
+ */
+export interface OpenAIEmbeddingsAdapterOptions extends BaseEmbeddingsAdapterOptions {
+    /** Bearer token. Sent as `Authorization: Bearer <apiKey>` unless overridden by `headers`. */
+    apiKey?: string;
+    /** API base URL. Default `https://api.openai.com/v1`. A trailing slash is trimmed. */
+    baseURL?: string;
+    /** Extra request headers. Override built defaults (including `Authorization`) key-by-key. */
+    headers?: Record<string, string>;
+    /** Custom `fetch` implementation. Default `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Retry/backoff configuration. Default: a single attempt (no retry). */
+    retry?: EmbeddingsRetryConfig;
+    /** Per-request handshake timeout in ms. `0`/unset disables the timeout. */
+    requestTimeoutMs?: number;
+}
+/**
+ * The JSON request body POSTed to `/v1/embeddings`.
+ */
+export interface OpenAIEmbeddingsRequestBody {
+    model: string;
+    input: string[];
+    encoding_format: 'float';
+    dimensions?: number;
+}
+/**
+ * The relevant subset of the `/v1/embeddings` JSON response shape.
+ */
+export interface OpenAIEmbeddingsResponseBody {
+    data: Array<{
+        embedding: number[];
+        index: number;
+    }>;
+    model?: string;
+    object?: string;
+}

package/batteries/embeddings/openai/validation.cjs

@@ -0,0 +1,56 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../../chunk-Ble4zEEl.js");
+require("../../../guards.cjs");
+const require_batteries_embeddings_openai_exceptions = require("./exceptions.cjs");
+let _nhtio_validation = require("@nhtio/validation");
+//#region src/batteries/embeddings/openai/validation.ts
+var retrySchema = _nhtio_validation.validator.object({
+	maxAttempts: _nhtio_validation.validator.number().integer().min(1).default(1),
+	baseDelayMs: _nhtio_validation.validator.number().integer().min(0).default(500),
+	maxDelayMs: _nhtio_validation.validator.number().integer().min(1).default(3e4),
+	retriableStatuses: _nhtio_validation.validator.array().items(_nhtio_validation.validator.number().integer().min(100).max(599)).default([
+		429,
+		500,
+		502,
+		503,
+		504
+	]),
+	honorRetryAfter: _nhtio_validation.validator.boolean().default(true)
+}).unknown(false);
+/**
+* Validator schema for `OpenAIEmbeddingsAdapterOptions`. Rejects unknown top-level keys.
+*/
+var openAIEmbeddingsOptionsSchema = _nhtio_validation.validator.object({
+	model: _nhtio_validation.validator.string().min(1).required(),
+	queryPrefix: _nhtio_validation.validator.string().optional(),
+	documentPrefix: _nhtio_validation.validator.string().optional(),
+	dimensions: _nhtio_validation.validator.number().integer().min(1).optional(),
+	apiKey: _nhtio_validation.validator.string().optional(),
+	baseURL: _nhtio_validation.validator.string().optional(),
+	headers: _nhtio_validation.validator.object().pattern(_nhtio_validation.validator.string(), _nhtio_validation.validator.string()).optional(),
+	fetch: _nhtio_validation.validator.function().optional(),
+	retry: retrySchema.optional(),
+	requestTimeoutMs: _nhtio_validation.validator.number().integer().min(0).default(0)
+}).unknown(false);
+var formatValidationDetails = (err) => err.details.map((d) => d.message).join(" and ");
+/**
+* Validates an arbitrary input against `openAIEmbeddingsOptionsSchema` and returns the resolved
+* options shape. Throws `E_INVALID_OPENAI_EMBEDDINGS_OPTIONS` (carrying the validator's report on
+* `cause`) on failure.
+*
+* @param input - The raw options object to validate.
+* @returns The resolved options object with defaults filled in.
+*/
+var validateOptions = (input) => {
+	const { value, error } = openAIEmbeddingsOptionsSchema.validate(input, {
+		abortEarly: false,
+		convert: false
+	});
+	if (error) throw new require_batteries_embeddings_openai_exceptions.E_INVALID_OPENAI_EMBEDDINGS_OPTIONS([formatValidationDetails(error)], { cause: error });
+	return value;
+};
+//#endregion
+exports.openAIEmbeddingsOptionsSchema = openAIEmbeddingsOptionsSchema;
+exports.validateOptions = validateOptions;
+
+//# sourceMappingURL=validation.cjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validation.cjs","names":[],"sources":["../../../../src/batteries/embeddings/openai/validation.ts"],"sourcesContent":["/**\n * Runtime validation schema and wrapper for OpenAI Embeddings adapter options.\n *\n * @module @nhtio/adk/batteries/embeddings/openai/validation\n *\n * @remarks\n * Validates `OpenAIEmbeddingsAdapterOptions` at construction time. Throws\n * `E_INVALID_OPENAI_EMBEDDINGS_OPTIONS` on failure — the same hard-fail policy as every other ADK\n * contract. `model` is required; unknown top-level keys are rejected so typos fail loud.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { validator, ValidationError } from '@nhtio/validation'\nimport { E_INVALID_OPENAI_EMBEDDINGS_OPTIONS } from './exceptions'\nimport type { OpenAIEmbeddingsAdapterOptions } from './types'\n\nconst retrySchema = validator\n  .object({\n    maxAttempts: validator.number().integer().min(1).default(1),\n    baseDelayMs: validator.number().integer().min(0).default(500),\n    maxDelayMs: validator.number().integer().min(1).default(30_000),\n    retriableStatuses: validator\n      .array()\n      .items(validator.number().integer().min(100).max(599))\n      .default([429, 500, 502, 503, 504]),\n    honorRetryAfter: validator.boolean().default(true),\n  })\n  .unknown(false)\n\n/**\n * Validator schema for `OpenAIEmbeddingsAdapterOptions`. Rejects unknown top-level keys.\n */\nexport const openAIEmbeddingsOptionsSchema = validator\n  .object<OpenAIEmbeddingsAdapterOptions>({\n    // Shared base\n    model: validator.string().min(1).required(),\n    queryPrefix: validator.string().optional(),\n    documentPrefix: validator.string().optional(),\n    dimensions: validator.number().integer().min(1).optional(),\n    // HTTP transport\n    apiKey: validator.string().optional(),\n    baseURL: validator.string().optional(),\n    headers: validator.object().pattern(validator.string(), validator.string()).optional(),\n    fetch: validator.function().optional(),\n    retry: retrySchema.optional(),\n    requestTimeoutMs: validator.number().integer().min(0).default(0),\n  })\n  .unknown(false)\n\nconst formatValidationDetails = (err: ValidationError): string =>\n  err.details.map((d) => d.message).join(' and ')\n\n/**\n * Validates an arbitrary input against `openAIEmbeddingsOptionsSchema` and returns the resolved\n * options shape. Throws `E_INVALID_OPENAI_EMBEDDINGS_OPTIONS` (carrying the validator's report on\n * `cause`) on failure.\n *\n * @param input - The raw options object to validate.\n * @returns The resolved options object with defaults filled in.\n */\nexport const validateOptions = (input: unknown): OpenAIEmbeddingsAdapterOptions => {\n  const { value, error } = openAIEmbeddingsOptionsSchema.validate(input, {\n    abortEarly: false,\n    convert: false,\n  })\n  if (error) {\n    throw new E_INVALID_OPENAI_EMBEDDINGS_OPTIONS([formatValidationDetails(error)], {\n      cause: error,\n    })\n  }\n  return value as OpenAIEmbeddingsAdapterOptions\n}\n\nconst isValidationError = (value: unknown): value is ValidationError =>\n  isError(value) && Array.isArray((value as ValidationError).details)\n\nvoid isValidationError\n"],"mappings":";;;;;;AAgBA,IAAM,cAAc,kBAAA,UACjB,OAAO;CACN,aAAa,kBAAA,UAAU,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,QAAQ,CAAC;CAC1D,aAAa,kBAAA,UAAU,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG;CAC5D,YAAY,kBAAA,UAAU,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAM;CAC9D,mBAAmB,kBAAA,UAChB,MAAM,EACN,MAAM,kBAAA,UAAU,OAAO,EAAE,QAAQ,EAAE,IAAI,GAAG,EAAE,IAAI,GAAG,CAAC,EACpD,QAAQ;EAAC;EAAK;EAAK;EAAK;EAAK;CAAG,CAAC;CACpC,iBAAiB,kBAAA,UAAU,QAAQ,EAAE,QAAQ,IAAI;AACnD,CAAC,EACA,QAAQ,KAAK;;;;AAKhB,IAAa,gCAAgC,kBAAA,UAC1C,OAAuC;CAEtC,OAAO,kBAAA,UAAU,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS;CAC1C,aAAa,kBAAA,UAAU,OAAO,EAAE,SAAS;CACzC,gBAAgB,kBAAA,UAAU,OAAO,EAAE,SAAS;CAC5C,YAAY,kBAAA,UAAU,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,SAAS;CAEzD,QAAQ,kBAAA,UAAU,OAAO,EAAE,SAAS;CACpC,SAAS,kBAAA,UAAU,OAAO,EAAE,SAAS;CACrC,SAAS,kBAAA,UAAU,OAAO,EAAE,QAAQ,kBAAA,UAAU,OAAO,GAAG,kBAAA,UAAU,OAAO,CAAC,EAAE,SAAS;CACrF,OAAO,kBAAA,UAAU,SAAS,EAAE,SAAS;CACrC,OAAO,YAAY,SAAS;CAC5B,kBAAkB,kBAAA,UAAU,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,QAAQ,CAAC;AACjE,CAAC,EACA,QAAQ,KAAK;AAEhB,IAAM,2BAA2B,QAC/B,IAAI,QAAQ,KAAK,MAAM,EAAE,OAAO,EAAE,KAAK,OAAO;;;;;;;;;AAUhD,IAAa,mBAAmB,UAAmD;CACjF,MAAM,EAAE,OAAO,UAAU,8BAA8B,SAAS,OAAO;EACrE,YAAY;EACZ,SAAS;CACX,CAAC;CACD,IAAI,OACF,MAAM,IAAI,+CAAA,oCAAoC,CAAC,wBAAwB,KAAK,CAAC,GAAG,EAC9E,OAAO,MACT,CAAC;CAEH,OAAO;AACT"}

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

@@ -0,0 +1,24 @@
+/**
+ * Runtime validation schema and wrapper for OpenAI Embeddings adapter options.
+ *
+ * @module @nhtio/adk/batteries/embeddings/openai/validation
+ *
+ * @remarks
+ * Validates `OpenAIEmbeddingsAdapterOptions` at construction time. Throws
+ * `E_INVALID_OPENAI_EMBEDDINGS_OPTIONS` on failure — the same hard-fail policy as every other ADK
+ * contract. `model` is required; unknown top-level keys are rejected so typos fail loud.
+ */
+import type { OpenAIEmbeddingsAdapterOptions } from "./types";
+/**
+ * Validator schema for `OpenAIEmbeddingsAdapterOptions`. Rejects unknown top-level keys.
+ */
+export declare const openAIEmbeddingsOptionsSchema: import("@nhtio/validation").ObjectSchema<OpenAIEmbeddingsAdapterOptions>;
+/**
+ * Validates an arbitrary input against `openAIEmbeddingsOptionsSchema` and returns the resolved
+ * options shape. Throws `E_INVALID_OPENAI_EMBEDDINGS_OPTIONS` (carrying the validator's report on
+ * `cause`) on failure.
+ *
+ * @param input - The raw options object to validate.
+ * @returns The resolved options object with defaults filled in.
+ */
+export declare const validateOptions: (input: unknown) => OpenAIEmbeddingsAdapterOptions;

package/batteries/embeddings/openai/validation.mjs

@@ -0,0 +1,53 @@
+import "../../../guards.mjs";
+import { E_INVALID_OPENAI_EMBEDDINGS_OPTIONS } from "./exceptions.mjs";
+import { validator } from "@nhtio/validation";
+//#region src/batteries/embeddings/openai/validation.ts
+var retrySchema = validator.object({
+	maxAttempts: validator.number().integer().min(1).default(1),
+	baseDelayMs: validator.number().integer().min(0).default(500),
+	maxDelayMs: validator.number().integer().min(1).default(3e4),
+	retriableStatuses: validator.array().items(validator.number().integer().min(100).max(599)).default([
+		429,
+		500,
+		502,
+		503,
+		504
+	]),
+	honorRetryAfter: validator.boolean().default(true)
+}).unknown(false);
+/**
+* Validator schema for `OpenAIEmbeddingsAdapterOptions`. Rejects unknown top-level keys.
+*/
+var openAIEmbeddingsOptionsSchema = validator.object({
+	model: validator.string().min(1).required(),
+	queryPrefix: validator.string().optional(),
+	documentPrefix: validator.string().optional(),
+	dimensions: validator.number().integer().min(1).optional(),
+	apiKey: validator.string().optional(),
+	baseURL: validator.string().optional(),
+	headers: validator.object().pattern(validator.string(), validator.string()).optional(),
+	fetch: validator.function().optional(),
+	retry: retrySchema.optional(),
+	requestTimeoutMs: validator.number().integer().min(0).default(0)
+}).unknown(false);
+var formatValidationDetails = (err) => err.details.map((d) => d.message).join(" and ");
+/**
+* Validates an arbitrary input against `openAIEmbeddingsOptionsSchema` and returns the resolved
+* options shape. Throws `E_INVALID_OPENAI_EMBEDDINGS_OPTIONS` (carrying the validator's report on
+* `cause`) on failure.
+*
+* @param input - The raw options object to validate.
+* @returns The resolved options object with defaults filled in.
+*/
+var validateOptions = (input) => {
+	const { value, error } = openAIEmbeddingsOptionsSchema.validate(input, {
+		abortEarly: false,
+		convert: false
+	});
+	if (error) throw new E_INVALID_OPENAI_EMBEDDINGS_OPTIONS([formatValidationDetails(error)], { cause: error });
+	return value;
+};
+//#endregion
+export { openAIEmbeddingsOptionsSchema, validateOptions };
+
+//# sourceMappingURL=validation.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"validation.mjs","names":[],"sources":["../../../../src/batteries/embeddings/openai/validation.ts"],"sourcesContent":["/**\n * Runtime validation schema and wrapper for OpenAI Embeddings adapter options.\n *\n * @module @nhtio/adk/batteries/embeddings/openai/validation\n *\n * @remarks\n * Validates `OpenAIEmbeddingsAdapterOptions` at construction time. Throws\n * `E_INVALID_OPENAI_EMBEDDINGS_OPTIONS` on failure — the same hard-fail policy as every other ADK\n * contract. `model` is required; unknown top-level keys are rejected so typos fail loud.\n */\n\nimport { isError } from '@nhtio/adk/guards'\nimport { validator, ValidationError } from '@nhtio/validation'\nimport { E_INVALID_OPENAI_EMBEDDINGS_OPTIONS } from './exceptions'\nimport type { OpenAIEmbeddingsAdapterOptions } from './types'\n\nconst retrySchema = validator\n  .object({\n    maxAttempts: validator.number().integer().min(1).default(1),\n    baseDelayMs: validator.number().integer().min(0).default(500),\n    maxDelayMs: validator.number().integer().min(1).default(30_000),\n    retriableStatuses: validator\n      .array()\n      .items(validator.number().integer().min(100).max(599))\n      .default([429, 500, 502, 503, 504]),\n    honorRetryAfter: validator.boolean().default(true),\n  })\n  .unknown(false)\n\n/**\n * Validator schema for `OpenAIEmbeddingsAdapterOptions`. Rejects unknown top-level keys.\n */\nexport const openAIEmbeddingsOptionsSchema = validator\n  .object<OpenAIEmbeddingsAdapterOptions>({\n    // Shared base\n    model: validator.string().min(1).required(),\n    queryPrefix: validator.string().optional(),\n    documentPrefix: validator.string().optional(),\n    dimensions: validator.number().integer().min(1).optional(),\n    // HTTP transport\n    apiKey: validator.string().optional(),\n    baseURL: validator.string().optional(),\n    headers: validator.object().pattern(validator.string(), validator.string()).optional(),\n    fetch: validator.function().optional(),\n    retry: retrySchema.optional(),\n    requestTimeoutMs: validator.number().integer().min(0).default(0),\n  })\n  .unknown(false)\n\nconst formatValidationDetails = (err: ValidationError): string =>\n  err.details.map((d) => d.message).join(' and ')\n\n/**\n * Validates an arbitrary input against `openAIEmbeddingsOptionsSchema` and returns the resolved\n * options shape. Throws `E_INVALID_OPENAI_EMBEDDINGS_OPTIONS` (carrying the validator's report on\n * `cause`) on failure.\n *\n * @param input - The raw options object to validate.\n * @returns The resolved options object with defaults filled in.\n */\nexport const validateOptions = (input: unknown): OpenAIEmbeddingsAdapterOptions => {\n  const { value, error } = openAIEmbeddingsOptionsSchema.validate(input, {\n    abortEarly: false,\n    convert: false,\n  })\n  if (error) {\n    throw new E_INVALID_OPENAI_EMBEDDINGS_OPTIONS([formatValidationDetails(error)], {\n      cause: error,\n    })\n  }\n  return value as OpenAIEmbeddingsAdapterOptions\n}\n\nconst isValidationError = (value: unknown): value is ValidationError =>\n  isError(value) && Array.isArray((value as ValidationError).details)\n\nvoid isValidationError\n"],"mappings":";;;;AAgBA,IAAM,cAAc,UACjB,OAAO;CACN,aAAa,UAAU,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,QAAQ,CAAC;CAC1D,aAAa,UAAU,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAG;CAC5D,YAAY,UAAU,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,QAAQ,GAAM;CAC9D,mBAAmB,UAChB,MAAM,EACN,MAAM,UAAU,OAAO,EAAE,QAAQ,EAAE,IAAI,GAAG,EAAE,IAAI,GAAG,CAAC,EACpD,QAAQ;EAAC;EAAK;EAAK;EAAK;EAAK;CAAG,CAAC;CACpC,iBAAiB,UAAU,QAAQ,EAAE,QAAQ,IAAI;AACnD,CAAC,EACA,QAAQ,KAAK;;;;AAKhB,IAAa,gCAAgC,UAC1C,OAAuC;CAEtC,OAAO,UAAU,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS;CAC1C,aAAa,UAAU,OAAO,EAAE,SAAS;CACzC,gBAAgB,UAAU,OAAO,EAAE,SAAS;CAC5C,YAAY,UAAU,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,SAAS;CAEzD,QAAQ,UAAU,OAAO,EAAE,SAAS;CACpC,SAAS,UAAU,OAAO,EAAE,SAAS;CACrC,SAAS,UAAU,OAAO,EAAE,QAAQ,UAAU,OAAO,GAAG,UAAU,OAAO,CAAC,EAAE,SAAS;CACrF,OAAO,UAAU,SAAS,EAAE,SAAS;CACrC,OAAO,YAAY,SAAS;CAC5B,kBAAkB,UAAU,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE,QAAQ,CAAC;AACjE,CAAC,EACA,QAAQ,KAAK;AAEhB,IAAM,2BAA2B,QAC/B,IAAI,QAAQ,KAAK,MAAM,EAAE,OAAO,EAAE,KAAK,OAAO;;;;;;;;;AAUhD,IAAa,mBAAmB,UAAmD;CACjF,MAAM,EAAE,OAAO,UAAU,8BAA8B,SAAS,OAAO;EACrE,YAAY;EACZ,SAAS;CACX,CAAC;CACD,IAAI,OACF,MAAM,IAAI,oCAAoC,CAAC,wBAAwB,KAAK,CAAC,GAAG,EAC9E,OAAO,MACT,CAAC;CAEH,OAAO;AACT"}

package/batteries/embeddings/openai.cjs

@@ -0,0 +1,14 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../../chunk-Ble4zEEl.js");
+const require_batteries_embeddings_openai_exceptions = require("./openai/exceptions.cjs");
+const require_batteries_embeddings_openai_validation = require("./openai/validation.cjs");
+const require_batteries_embeddings_openai_helpers = require("./openai/helpers.cjs");
+const require_batteries_embeddings_openai_adapter = require("./openai/adapter.cjs");
+exports.E_INVALID_OPENAI_EMBEDDINGS_OPTIONS = require_batteries_embeddings_openai_exceptions.E_INVALID_OPENAI_EMBEDDINGS_OPTIONS;
+exports.E_OPENAI_EMBEDDINGS_HTTP_ERROR = require_batteries_embeddings_openai_exceptions.E_OPENAI_EMBEDDINGS_HTTP_ERROR;
+exports.E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE = require_batteries_embeddings_openai_exceptions.E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE;
+exports.E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT = require_batteries_embeddings_openai_exceptions.E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT;
+exports.OpenAIEmbeddingsAdapter = require_batteries_embeddings_openai_adapter.OpenAIEmbeddingsAdapter;
+exports.applyEmbeddingPrefix = require_batteries_embeddings_openai_helpers.applyEmbeddingPrefix;
+exports.openAIEmbeddingsOptionsSchema = require_batteries_embeddings_openai_validation.openAIEmbeddingsOptionsSchema;
+exports.validateOptions = require_batteries_embeddings_openai_validation.validateOptions;

package/batteries/embeddings/openai.mjs

@@ -0,0 +1,5 @@
+import { E_INVALID_OPENAI_EMBEDDINGS_OPTIONS, E_OPENAI_EMBEDDINGS_HTTP_ERROR, E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE, E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT } from "./openai/exceptions.mjs";
+import { openAIEmbeddingsOptionsSchema, validateOptions } from "./openai/validation.mjs";
+import { applyEmbeddingPrefix } from "./openai/helpers.mjs";
+import { OpenAIEmbeddingsAdapter } from "./openai/adapter.mjs";
+export { E_INVALID_OPENAI_EMBEDDINGS_OPTIONS, E_OPENAI_EMBEDDINGS_HTTP_ERROR, E_OPENAI_EMBEDDINGS_MALFORMED_RESPONSE, E_OPENAI_EMBEDDINGS_REQUEST_TIMEOUT, OpenAIEmbeddingsAdapter, applyEmbeddingPrefix, openAIEmbeddingsOptionsSchema, validateOptions };