onbuzz 4.9.0 → 4.9.1

package/src/services/embeddings/providerInterface.js

@@ -0,0 +1,206 @@
+/**
+ * EmbeddingProvider — abstract base for cloud + local embedding backends.
+ *
+ * Why an abstract class (not a duck-typed object): we want the same shape
+ * — Float32Array out, batch + single APIs, capability metadata, single
+ * error vocabulary — across every provider so the orchestrator never
+ * needs to know which one it's talking to. Subclasses override
+ * `_embed(texts, kind)` and the base handles input validation, batching,
+ * L2-normalization, dimension checks, and error wrapping.
+ *
+ * Vector convention: we always return L2-normalized Float32Array, so
+ * cosine similarity in the VectorStore reduces to a dot product — saves
+ * a divide-per-query at search time. The base enforces normalization
+ * after the subclass returns raw vectors.
+ *
+ * Query vs document: BGE / nomic / e5 embed queries and documents into
+ * the same space but want different prefixes ("search_query: ..." vs
+ * "search_document: ..."). Subclasses that distinguish read the `kind`
+ * argument; providers that don't simply ignore it. The base class
+ * forwards kind transparently.
+ */
+
+/**
+ * Error vocabulary shared by every provider. Mirrors the agent-scheduler
+ * error categorisation (persistent vs transient): transient codes are
+ * retry / fallback candidates; persistent codes surface to the user.
+ */
+export const EMBEDDING_ERROR_CODES = Object.freeze({
+  NETWORK_ERROR:        'NETWORK_ERROR',         // transient
+  RATE_LIMITED:         'RATE_LIMITED',          // transient
+  PROVIDER_UNAVAILABLE: 'PROVIDER_UNAVAILABLE',  // transient
+  AUTH_ERROR:           'AUTH_ERROR',            // persistent
+  MODEL_NOT_FOUND:      'MODEL_NOT_FOUND',       // persistent
+  INVALID_INPUT:        'INVALID_INPUT',         // persistent
+  DIMENSION_MISMATCH:   'DIMENSION_MISMATCH',    // persistent
+  NOT_INITIALIZED:      'NOT_INITIALIZED',       // persistent
+});
+
+export class EmbeddingError extends Error {
+  /**
+   * @param {string} code - One of EMBEDDING_ERROR_CODES values.
+   * @param {string} message
+   * @param {object} [opts]
+   * @param {Error}   [opts.cause]
+   * @param {string}  [opts.provider]
+   * @param {boolean} [opts.transient] - If true, orchestrator may retry / fall back.
+   */
+  constructor(code, message, opts = {}) {
+    super(message);
+    this.name = 'EmbeddingError';
+    this.code = code;
+    this.provider = opts.provider || null;
+    this.transient = opts.transient ?? false;
+    if (opts.cause) this.cause = opts.cause;
+  }
+}
+
+/**
+ * @typedef {Object} EmbeddingProviderInfo
+ * @property {string}   name          - 'azure' | 'openai' | 'local'
+ * @property {string}   modelId       - The concrete model identifier
+ * @property {number}   dimensions    - Vector size in floats
+ * @property {number}   maxBatchSize  - Max texts per `_embed` call
+ * @property {number}   maxTokensPerText - Hard upper bound on a single input
+ * @property {boolean}  distinguishesQueryAndDocument - Honours the `kind` arg?
+ * @property {boolean}  isLocal       - True for offline providers
+ */
+
+export class EmbeddingProvider {
+  /**
+   * Synchronous capability description. Must be cheap and side-effect-free
+   * (the orchestrator reads it on every request to validate inputs).
+   * @returns {EmbeddingProviderInfo}
+   */
+  getInfo() {
+    throw new Error(`${this.constructor.name}.getInfo() must be implemented`);
+  }
+
+  /**
+   * Can this provider serve requests right now? For cloud providers this
+   * checks that the API key + endpoint are set; for local it checks that
+   * the model has been loaded. Should NOT throw — returns a structured
+   * result so callers can show a remediation message.
+   * @returns {Promise<{ok: boolean, reason?: string}>}
+   */
+  async health() {
+    return { ok: true };
+  }
+
+  /**
+   * Embed a single query. Convenience over `embedDocuments([text], 'query')`.
+   * @param {string} text
+   * @returns {Promise<Float32Array>}
+   */
+  async embedQuery(text) {
+    if (typeof text !== 'string' || text.length === 0) {
+      throw new EmbeddingError(
+        EMBEDDING_ERROR_CODES.INVALID_INPUT,
+        'embedQuery requires a non-empty string',
+        { provider: this.getInfo().name },
+      );
+    }
+    const [vec] = await this.embedDocuments([text], 'query');
+    return vec;
+  }
+
+  /**
+   * Embed many texts. Returns an array of Float32Array (L2-normalized) in
+   * the SAME order as the input. Batches under `maxBatchSize` transparently.
+   * Throws EmbeddingError on failure with a code from EMBEDDING_ERROR_CODES.
+   *
+   * @param {string[]} texts
+   * @param {'document'|'query'} [kind='document']
+   * @returns {Promise<Float32Array[]>}
+   */
+  async embedDocuments(texts, kind = 'document') {
+    if (!Array.isArray(texts) || texts.length === 0) {
+      throw new EmbeddingError(
+        EMBEDDING_ERROR_CODES.INVALID_INPUT,
+        'embedDocuments requires a non-empty array of strings',
+        { provider: this.getInfo().name },
+      );
+    }
+    for (let i = 0; i < texts.length; i++) {
+      if (typeof texts[i] !== 'string' || texts[i].length === 0) {
+        throw new EmbeddingError(
+          EMBEDDING_ERROR_CODES.INVALID_INPUT,
+          `embedDocuments[${i}] is not a non-empty string`,
+          { provider: this.getInfo().name },
+        );
+      }
+    }
+
+    const { maxBatchSize, dimensions, name } = this.getInfo();
+    const out = [];
+    for (let start = 0; start < texts.length; start += maxBatchSize) {
+      const batch = texts.slice(start, start + maxBatchSize);
+      const raw = await this._embed(batch, kind);
+      if (!Array.isArray(raw) || raw.length !== batch.length) {
+        throw new EmbeddingError(
+          EMBEDDING_ERROR_CODES.PROVIDER_UNAVAILABLE,
+          `Provider returned ${Array.isArray(raw) ? raw.length : 'non-array'} vectors for ${batch.length} inputs`,
+          { provider: name, transient: true },
+        );
+      }
+      for (const v of raw) {
+        const f32 = v instanceof Float32Array ? v : Float32Array.from(v);
+        if (f32.length !== dimensions) {
+          throw new EmbeddingError(
+            EMBEDDING_ERROR_CODES.DIMENSION_MISMATCH,
+            `Expected ${dimensions} dims; got ${f32.length}`,
+            { provider: name },
+          );
+        }
+        normalizeInPlace(f32);
+        out.push(f32);
+      }
+    }
+    return out;
+  }
+
+  /**
+   * Subclasses implement this: send `texts` to the provider, return an
+   * array of array-likes of numbers (the base class normalizes + validates
+   * dimensions before handing the result back to callers).
+   *
+   * Should throw EmbeddingError with a useful code on failure. Network /
+   * 5xx / 429 → transient codes; auth / bad request → persistent codes.
+   *
+   * @param {string[]} texts
+   * @param {'document'|'query'} kind
+   * @returns {Promise<(number[]|Float32Array)[]>}
+   * @protected
+   */
+  async _embed(texts, kind) {
+    throw new Error(`${this.constructor.name}._embed() must be implemented`);
+  }
+
+  /**
+   * Stable model fingerprint, used by VectorStore to detect provider /
+   * model changes and trigger re-embed. Default = `name:modelId`; override
+   * if a single modelId has multiple incompatible internal versions.
+   * @returns {string}
+   */
+  getModelFingerprint() {
+    const { name, modelId } = this.getInfo();
+    return `${name}:${modelId}`;
+  }
+}
+
+/**
+ * L2-normalize a vector in place so cosine(a, b) reduces to dot(a, b).
+ * Exposed for tests and for the VectorStore to validate stored vectors.
+ * Hot path — avoid allocations.
+ * @param {Float32Array} v
+ * @returns {Float32Array} the same array, normalized
+ */
+export function normalizeInPlace(v) {
+  let sum = 0;
+  for (let i = 0; i < v.length; i++) sum += v[i] * v[i];
+  const norm = Math.sqrt(sum);
+  if (norm === 0) return v;
+  const inv = 1 / norm;
+  for (let i = 0; i < v.length; i++) v[i] = v[i] * inv;
+  return v;
+}

package/src/services/embeddings/providers/azureCustomProvider.js

@@ -0,0 +1,154 @@
+/**
+ * AzureCustomEmbeddingProvider — point Loxia at YOUR Azure AI Foundry
+ * OpenAI-compatible deployment.
+ *
+ * Why this exists (not just "use openai provider"):
+ *   Azure AI Foundry exposes ALL embedding deployments (OpenAI-built
+ *   text-embedding-3-*, Cohere embed-v-4-*, third-party models) behind
+ *   a unified `/openai/v1/` endpoint that speaks the OpenAI REST shape.
+ *   In practice users who deploy a non-OpenAI model on Azure (e.g.
+ *   `embed-v-4-0`) hit exactly that endpoint, with their own URL +
+ *   deployment name + key, NOT OpenAI's hosted api.openai.com nor the
+ *   Loxia-backend proxy.
+ *
+ *   The `openai` provider already speaks the OpenAI REST shape but
+ *   defaults to api.openai.com and exposes a `url` override only via
+ *   the constructor — not through the Settings UI. Rather than overload
+ *   the openai provider with conditional UI ("are you on Azure or
+ *   real OpenAI?"), it's clearer to expose a separate provider option
+ *   labelled "Azure (custom OpenAI-compat deployment)" with its own
+ *   form fields (endpoint, deployment, dimensions, key).
+ *
+ * Wire shape (matches the OpenAI embeddings REST API):
+ *
+ *   POST {endpoint}/embeddings
+ *   Authorization: Bearer <api-key>
+ *   Content-Type: application/json
+ *
+ *   {
+ *     "input":           ["text 1", "text 2"],
+ *     "model":           "embed-v-4-0",   // user's deployment name
+ *     "encoding_format": "float"          // explicit; some compat layers
+ *                                         // require it
+ *   }
+ *
+ *   → { "data": [{ "embedding": [...] }, ...], "usage": {...} }
+ *
+ * Endpoint normalization: the user typically pastes the `baseURL` they
+ * got from Azure (e.g. `.../openai/v1/`). We auto-append `embeddings`
+ * so the user doesn't have to think about the suffix.
+ *
+ * Dimensions: model-dependent. The user supplies them — for
+ * embed-v-4-0 the default is 1536; for OpenAI text-embedding-3-* it's
+ * 1536/3072. We don't auto-detect because the base class needs to
+ * validate dimensions on every response.
+ */
+
+import { EmbeddingProvider, EmbeddingError, EMBEDDING_ERROR_CODES } from '../providerInterface.js';
+import { postEmbeddings, extractOpenAIShape } from './cloudHttpTransport.js';
+
+const DEFAULT_DIMS = 1536;       // embed-v-4-0 / text-embedding-3-small default
+const DEFAULT_MAX_BATCH = 16;    // safe across Azure deployments
+const DEFAULT_MAX_TOKENS = 8191;
+
+/**
+ * Normalize the user-supplied endpoint into a full POST URL. The
+ * Azure portal copy-paste typically gives the OpenAI-compat baseURL
+ * (e.g. `.../openai/v1/`) — we append `embeddings` if needed, strip
+ * trailing slashes, and leave already-suffixed URLs alone.
+ *
+ * Exported for tests + future shared use by other custom providers.
+ *
+ * @param {string} url
+ * @returns {string}
+ */
+export function normalizeEmbeddingsUrl(url) {
+  if (typeof url !== 'string' || !url.trim()) return url;
+  let u = url.trim().replace(/\/+$/, '');
+  if (!/\/embeddings$/.test(u)) u = `${u}/embeddings`;
+  return u;
+}
+
+export class AzureCustomEmbeddingProvider extends EmbeddingProvider {
+  /**
+   * @param {object} opts
+   * @param {string} opts.endpoint     - Raw or normalized URL; we auto-append `/embeddings`.
+   * @param {string} opts.deployment   - The deployed model name (e.g. `embed-v-4-0`).
+   * @param {() => string|null} opts.getApiKey - Returns the current API key.
+   * @param {number} [opts.dimensions]   - Required for non-default models; defaults to 1536.
+   * @param {number} [opts.maxBatchSize]
+   * @param {number} [opts.timeoutMs]
+   * @param {typeof fetch} [opts.fetchImpl]  - Injectable for tests.
+   */
+  constructor({
+    endpoint,
+    deployment,
+    getApiKey,
+    dimensions = DEFAULT_DIMS,
+    maxBatchSize = DEFAULT_MAX_BATCH,
+    timeoutMs,
+    fetchImpl,
+  } = {}) {
+    super();
+    if (!endpoint) throw new Error('AzureCustomEmbeddingProvider requires endpoint');
+    if (!deployment) throw new Error('AzureCustomEmbeddingProvider requires deployment (the deployed model name)');
+    if (typeof getApiKey !== 'function') {
+      throw new Error('AzureCustomEmbeddingProvider requires a getApiKey() callback');
+    }
+    this._url = normalizeEmbeddingsUrl(endpoint);
+    this._modelId = deployment;
+    this._getApiKey = getApiKey;
+    this._dimensions = Number.isInteger(dimensions) && dimensions > 0 ? dimensions : DEFAULT_DIMS;
+    this._maxBatchSize = Number.isInteger(maxBatchSize) && maxBatchSize > 0 ? maxBatchSize : DEFAULT_MAX_BATCH;
+    this._timeoutMs = timeoutMs;
+    this._fetchImpl = fetchImpl;
+  }
+
+  getInfo() {
+    return {
+      name: 'azure-custom',
+      modelId: this._modelId,
+      dimensions: this._dimensions,
+      maxBatchSize: this._maxBatchSize,
+      maxTokensPerText: DEFAULT_MAX_TOKENS,
+      distinguishesQueryAndDocument: false,
+      isLocal: false,
+    };
+  }
+
+  async health() {
+    const key = this._getApiKey();
+    if (!key) return { ok: false, reason: 'No API key set for the Azure custom deployment. Add one under Settings → Embeddings.' };
+    return { ok: true };
+  }
+
+  async _embed(texts, _kind) {
+    const apiKey = this._getApiKey();
+    if (!apiKey) {
+      throw new EmbeddingError(
+        EMBEDDING_ERROR_CODES.AUTH_ERROR,
+        'No API key set for the Azure custom deployment. Add one under Settings → Embeddings.',
+        { provider: 'azure-custom', transient: false },
+      );
+    }
+    return postEmbeddings({
+      url: this._url,
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      // `encoding_format: 'float'` is explicit per Azure / Cohere Embed v4
+      // best-practice docs. OpenAI's hosted endpoint accepts it without
+      // change; the compat layer requires it for some non-OpenAI models.
+      body: { input: texts, model: this._modelId, encoding_format: 'float' },
+      providerName: 'azure-custom',
+      extractVectors: extractOpenAIShape,
+      timeoutMs: this._timeoutMs,
+      fetchImpl: this._fetchImpl,
+    });
+  }
+
+  getModelFingerprint() {
+    return `azure-custom:${this._modelId}@${this._dimensions}d`;
+  }
+}

package/src/services/embeddings/providers/azureProvider.js

@@ -0,0 +1,122 @@
+/**
+ * AzureEmbeddingProvider — talks to Azure OpenAI Embeddings via the
+ * Loxia backend proxy at `${baseUrl}/llm/embed`.
+ *
+ * Why through the backend (not direct to Azure):
+ *   - Same auth path as chat: ApiKeyManager holds the Loxia key, the
+ *     backend holds the Azure key. No raw Azure credentials in the CLI.
+ *   - Brand routing happens server-side: autopilot and onbuzz both
+ *     point at the same shared embedding deployment per current
+ *     architectural decision (single endpoint for both brands).
+ *   - Lets us swap models / deployments without redeploying the CLI.
+ *
+ * Backend contract (must match autopilot-backend `/llm/embed` route):
+ *
+ *   POST ${baseUrl}/llm/embed
+ *   Authorization: Bearer <loxiaApiKey>
+ *   Content-Type:  application/json
+ *
+ *   { "input": ["text 1", "text 2"], "model": "text-embedding-3-small" }
+ *
+ *   →  { "data": [{ "embedding": [0.1, …] }, …],
+ *        "usage": { "prompt_tokens": N, "total_tokens": N },
+ *        "model": "text-embedding-3-small" }
+ *
+ * NOTE: The backend `/llm/embed` route is the server-side counterpart
+ * that proxies to Azure OpenAI Embeddings. If it doesn't exist yet,
+ * this provider will fail with PROVIDER_UNAVAILABLE on the first call.
+ * That's intentional — surface the missing infrastructure clearly.
+ */
+
+import { EmbeddingProvider, EmbeddingError, EMBEDDING_ERROR_CODES } from '../providerInterface.js';
+import { postEmbeddings, extractOpenAIShape } from './cloudHttpTransport.js';
+
+/**
+ * Default Azure embedding model. Loxia routes both autopilot + onbuzz
+ * to the same deployment per the shared-endpoint decision; the deployment
+ * name lives on the backend side.
+ */
+const DEFAULT_MODEL = 'text-embedding-3-small';
+const DEFAULT_DIMS = 1536;
+const DEFAULT_MAX_BATCH = 16;
+const DEFAULT_MAX_TOKENS = 8191;
+
+export class AzureEmbeddingProvider extends EmbeddingProvider {
+  /**
+   * @param {object} opts
+   * @param {string} opts.baseUrl    - Loxia backend base URL (matches aiService).
+   * @param {() => string|null} opts.getApiKey  - Callback returning the current
+   *        Loxia API key. Callback (not stored string) so key rotation in the
+   *        ApiKeyManager is picked up immediately without re-instantiating.
+   * @param {string} [opts.modelId]
+   * @param {number} [opts.dimensions]
+   * @param {number} [opts.maxBatchSize]
+   * @param {number} [opts.timeoutMs]
+   * @param {typeof fetch} [opts.fetchImpl] - Injectable for tests.
+   */
+  constructor({
+    baseUrl,
+    getApiKey,
+    modelId = DEFAULT_MODEL,
+    dimensions = DEFAULT_DIMS,
+    maxBatchSize = DEFAULT_MAX_BATCH,
+    timeoutMs,
+    fetchImpl,
+  }) {
+    super();
+    if (!baseUrl) {
+      throw new Error('AzureEmbeddingProvider requires a baseUrl');
+    }
+    if (typeof getApiKey !== 'function') {
+      throw new Error('AzureEmbeddingProvider requires a getApiKey() callback');
+    }
+    this._baseUrl = baseUrl.replace(/\/+$/, '');
+    this._getApiKey = getApiKey;
+    this._modelId = modelId;
+    this._dimensions = dimensions;
+    this._maxBatchSize = maxBatchSize;
+    this._timeoutMs = timeoutMs;
+    this._fetchImpl = fetchImpl;
+  }
+
+  getInfo() {
+    return {
+      name: 'azure',
+      modelId: this._modelId,
+      dimensions: this._dimensions,
+      maxBatchSize: this._maxBatchSize,
+      maxTokensPerText: DEFAULT_MAX_TOKENS,
+      distinguishesQueryAndDocument: false, // OpenAI-family models don't
+      isLocal: false,
+    };
+  }
+
+  async health() {
+    const key = this._getApiKey();
+    if (!key) return { ok: false, reason: 'No Loxia API key available — sign in or set one in Settings.' };
+    return { ok: true };
+  }
+
+  async _embed(texts, _kind) {
+    const apiKey = this._getApiKey();
+    if (!apiKey) {
+      throw new EmbeddingError(
+        EMBEDDING_ERROR_CODES.AUTH_ERROR,
+        'No Loxia API key available — sign in or set one in Settings.',
+        { provider: 'azure', transient: false },
+      );
+    }
+    return postEmbeddings({
+      url: `${this._baseUrl}/llm/embed`,
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+      },
+      body: { input: texts, model: this._modelId },
+      providerName: 'azure',
+      extractVectors: extractOpenAIShape,
+      timeoutMs: this._timeoutMs,
+      fetchImpl: this._fetchImpl,
+    });
+  }
+}

package/src/services/embeddings/providers/cloudHttpTransport.js

@@ -0,0 +1,205 @@
+/**
+ * cloudHttpTransport — shared HTTP plumbing for the cloud embedding
+ * providers (Azure, OpenAI).
+ *
+ * Why factored out: Azure and OpenAI exchange the SAME request/response
+ * shape (the OpenAI embeddings API: `{ input, model }` in, `{ data: [{
+ * embedding: number[] }] }` out). They differ only in:
+ *   - URL (Loxia backend's `/llm/embed` proxy vs. api.openai.com directly)
+ *   - auth header (Loxia Authorization Bearer vs. OpenAI Bearer or
+ *     Azure api-key)
+ *   - whether a `deployment` is on the URL path or in the body
+ *
+ * The shared transport handles: timeouts via AbortController, JSON
+ * parse/serialize, status-code → EmbeddingError categorisation, and
+ * shape normalisation. The provider subclasses configure the URL +
+ * auth headers and stay thin.
+ *
+ * Error categorisation matches the agent-scheduler convention (see
+ * src/core/agentScheduler.js handleAIServiceFailure):
+ *   401/403         → AUTH_ERROR        (persistent)
+ *   404             → MODEL_NOT_FOUND   (persistent)
+ *   400/422         → INVALID_INPUT     (persistent)
+ *   429             → RATE_LIMITED      (transient)
+ *   5xx             → PROVIDER_UNAVAILABLE (transient)
+ *   network / abort → NETWORK_ERROR     (transient)
+ */
+
+import {
+  EmbeddingError,
+  EMBEDDING_ERROR_CODES,
+} from '../providerInterface.js';
+
+/**
+ * Default HTTP fetch timeout for embedding calls. Embedding APIs are
+ * fast (typically <1s for a batch of 16); a 30s ceiling catches stuck
+ * connections without making the agent wait noticeably on failure.
+ */
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * Send a single embeddings batch over HTTP and return raw number[][].
+ *
+ * @param {object} opts
+ * @param {string} opts.url      - Full POST URL.
+ * @param {Object} opts.headers  - Auth + content-type headers.
+ * @param {Object} opts.body     - Request body (will be JSON.stringify'd).
+ * @param {string} opts.providerName - For error tagging only.
+ * @param {(json: any) => number[][]} opts.extractVectors
+ *        - Pull the vectors out of the response payload. Different
+ *          providers nest them slightly differently; we don't try to
+ *          guess — each provider declares it explicitly.
+ * @param {number} [opts.timeoutMs=30_000]
+ * @param {typeof fetch} [opts.fetchImpl]  - Injectable for tests.
+ * @returns {Promise<number[][]>}
+ * @throws  {EmbeddingError}
+ */
+export async function postEmbeddings(opts) {
+  const {
+    url, headers, body, providerName, extractVectors,
+    timeoutMs = DEFAULT_TIMEOUT_MS, fetchImpl = globalThis.fetch,
+  } = opts;
+
+  if (typeof fetchImpl !== 'function') {
+    throw new EmbeddingError(
+      EMBEDDING_ERROR_CODES.NOT_INITIALIZED,
+      'global fetch is not available; pass a fetchImpl explicitly',
+      { provider: providerName },
+    );
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+  } catch (err) {
+    // Network failure / DNS / connection reset / abort.
+    const isAbort = err?.name === 'AbortError';
+    throw new EmbeddingError(
+      EMBEDDING_ERROR_CODES.NETWORK_ERROR,
+      isAbort ? `Request timed out after ${timeoutMs}ms` : `Network error: ${err?.message || err}`,
+      { provider: providerName, transient: true, cause: err },
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+
+  if (!response.ok) {
+    const text = await safeReadBody(response);
+    throw classifyHttpError(response.status, text, providerName);
+  }
+
+  let json;
+  try {
+    json = await response.json();
+  } catch (err) {
+    throw new EmbeddingError(
+      EMBEDDING_ERROR_CODES.PROVIDER_UNAVAILABLE,
+      `Provider returned non-JSON response: ${err?.message || err}`,
+      { provider: providerName, transient: true, cause: err },
+    );
+  }
+
+  let vectors;
+  try {
+    vectors = extractVectors(json);
+  } catch (err) {
+    throw new EmbeddingError(
+      EMBEDDING_ERROR_CODES.PROVIDER_UNAVAILABLE,
+      `Could not extract vectors from response: ${err?.message || err}`,
+      { provider: providerName, transient: true, cause: err },
+    );
+  }
+
+  if (!Array.isArray(vectors)) {
+    throw new EmbeddingError(
+      EMBEDDING_ERROR_CODES.PROVIDER_UNAVAILABLE,
+      `extractVectors returned ${typeof vectors}, expected array`,
+      { provider: providerName, transient: true },
+    );
+  }
+
+  return vectors;
+}
+
+/** Map an HTTP error response to the typed EmbeddingError. */
+export function classifyHttpError(status, bodyText, providerName) {
+  // Truncate the body so the error message doesn't bloat the log line.
+  const snippet = (bodyText || '').slice(0, 240).replace(/\s+/g, ' ').trim();
+  const tail = snippet ? ` — ${snippet}` : '';
+
+  if (status === 401 || status === 403) {
+    return new EmbeddingError(
+      EMBEDDING_ERROR_CODES.AUTH_ERROR,
+      `Auth rejected (HTTP ${status})${tail}`,
+      { provider: providerName, transient: false },
+    );
+  }
+  if (status === 404) {
+    return new EmbeddingError(
+      EMBEDDING_ERROR_CODES.MODEL_NOT_FOUND,
+      `Model or deployment not found (HTTP 404)${tail}`,
+      { provider: providerName, transient: false },
+    );
+  }
+  if (status === 400 || status === 422) {
+    return new EmbeddingError(
+      EMBEDDING_ERROR_CODES.INVALID_INPUT,
+      `Request rejected (HTTP ${status})${tail}`,
+      { provider: providerName, transient: false },
+    );
+  }
+  if (status === 429) {
+    return new EmbeddingError(
+      EMBEDDING_ERROR_CODES.RATE_LIMITED,
+      `Rate limited (HTTP 429)${tail}`,
+      { provider: providerName, transient: true },
+    );
+  }
+  if (status >= 500) {
+    return new EmbeddingError(
+      EMBEDDING_ERROR_CODES.PROVIDER_UNAVAILABLE,
+      `Provider error (HTTP ${status})${tail}`,
+      { provider: providerName, transient: true },
+    );
+  }
+  // Anything else gets the catch-all.
+  return new EmbeddingError(
+    EMBEDDING_ERROR_CODES.PROVIDER_UNAVAILABLE,
+    `Unexpected HTTP ${status}${tail}`,
+    { provider: providerName, transient: true },
+  );
+}
+
+/** Read a response body as text, swallowing further errors. */
+async function safeReadBody(response) {
+  try {
+    return await response.text();
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Extractor for the standard OpenAI-shape embeddings response:
+ *   { data: [{ embedding: number[] }, ...] }
+ * Both Azure OpenAI and OpenAI directly use this. Azure-via-Loxia-backend
+ * forwards the same shape after the proxy layer.
+ */
+export function extractOpenAIShape(json) {
+  if (!json || !Array.isArray(json.data)) {
+    throw new Error('response missing `data` array');
+  }
+  return json.data.map((row, i) => {
+    if (!row || !Array.isArray(row.embedding)) {
+      throw new Error(`data[${i}].embedding is not an array`);
+    }
+    return row.embedding;
+  });
+}