Skip to content

Local-first 🧠 memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.

TypeScript
11.5 KB
Raw Blame
/**
 * Native ZeroEntropy embedding provider (Retrieval & Ranking Quality).
 *
 * Calls the ZeroEntropy native embed API (`POST {base}/models/embed`)
 * directly over `fetch` - no SDK, no new dependency - instead of routing
 * through the OpenAI-compatible wrapper. Request/response shape per the
 * ZeroEntropy API reference:
 *
 *   request:  { model, input_type, input: string[], encoding_format, dimensions? }
 *   response: { results: [{ embedding: number[] }, ...], usage? }
 *
 * `results` preserves input order (there is no per-item index field), so
 * vectors map positionally. Network discipline mirrors the OpenAI-compat
 * provider: concurrency bounded process-wide per provider identity and
 * endpoint (`provider-semaphore.ts`), per-request timeout, batches closing on
 * whichever of `embedding_batch_size` / `embedding_batch_tokens` fills
 * first, retry on 429/5xx and network/timeout with jittered backoff,
 * vectors unit-normalised so cosine equals 1 - L2²/2.
 *
 * The interface is symmetric (one `embed`), so `input_type` is fixed to
 * "document" - consistent with how OSB treats query and passage embeddings
 * uniformly across every provider.
 */

import { isRequestTimeout, SearchError } from "../types.ts";
import type { ResolvedEmbeddingConfig } from "../types.ts";
import type { EmbedCallOptions, EmbeddingProvider, EmbedKind, PingResult } from "./contract.ts";
import {
  RETRYABLE_STATUSES,
  assertHttpEgressEndpoint,
  chunkArrayByTokenBudget,
  jittered,
  linkAbortSignal,
  sleep,
  unitNormaliseInPlace,
} from "./http-util.ts";
import { providerCeilingKey, providerSemaphore } from "./provider-semaphore.ts";

const ZEROENTROPY_INPUT_TYPE = "document";

interface ZeroEntropyEmbeddingResponse {
  readonly results: ReadonlyArray<{ readonly embedding: ReadonlyArray<number> }>;
}

interface ResolvedHttp {
  readonly url: string;
  readonly apiKey: string;
}

function resolveHttp(config: ResolvedEmbeddingConfig): ResolvedHttp {
  if (!config.baseUrl) {
    throw new SearchError(
      "INVALID_INPUT",
      "embedding_base_url is required when semantic is enabled",
    );
  }
  if (!config.model) {
    throw new SearchError("INVALID_INPUT", "embedding_model is required when semantic is enabled");
  }
  if (!config.apiKey) {
    throw new SearchError(
      "EMBEDDING_KEY_MISSING",
      "embedding_api_key is required when semantic is enabled",
    );
  }
  const base = assertHttpEgressEndpoint(config.baseUrl, "embedding_base_url", {
    allowInsecureHttp: config.allowInsecureHttp === true,
    key: "embedding_allow_insecure_http",
  }).replace(/\/+$/, "");
  return { url: `${base}/models/embed`, apiKey: config.apiKey };
}

export interface ZeroEntropyProviderOptions {
  /** Override default `[1000, 2000]` ms backoffs (used by tests). */
  readonly backoffMs?: ReadonlyArray<number>;
}

export class ZeroEntropyProvider implements EmbeddingProvider {
  readonly name = "zeroentropy";
  readonly model: string;
  private _dimension: number | null;
  private readonly config: ResolvedEmbeddingConfig;
  private readonly http: ResolvedHttp;
  private readonly backoffMs: ReadonlyArray<number>;
  private retriesSeen = 0;
  /**
   * Registry key of the process-wide ceiling this provider shares.
   * Resolved once, from the CONFIGURED identity, so it cannot move when
   * `_dimension` is learned from the first response.
   */
  private readonly ceilingKey: string;

  constructor(config: ResolvedEmbeddingConfig, opts?: ZeroEntropyProviderOptions) {
    this.config = config;
    this.http = resolveHttp(config);
    this.model = config.model!;
    this._dimension = config.dimension;
    this.backoffMs = opts?.backoffMs ?? [1000, 2000];
    this.ceilingKey = providerCeilingKey(this.name, config, this.http.url);
  }

  get dimension(): number | null {
    return this._dimension;
  }

  consumeRetryCount(): number {
    const n = this.retriesSeen;
    this.retriesSeen = 0;
    return n;
  }

  async embed(
    texts: ReadonlyArray<string>,
    _kind?: EmbedKind,
    opts?: EmbedCallOptions,
  ): Promise<number[][]> {
    if (texts.length === 0) return [];
    const batches = chunkArrayByTokenBudget(
      texts.map((t, i) => ({ text: t, originalIndex: i })),
      this.config.batchSize,
      this.config.batchTokens,
      (b) => b.text,
    );
    const sem = providerSemaphore(this.ceilingKey, this.config.concurrency);
    const out: number[][] = new Array(texts.length);
    const cancel = new AbortController();
    const unlink = linkAbortSignal(opts?.signal, cancel);
    // The dispatch report fires once per call, for the first batch that
    // reaches the wire: the caller's embed interval starts when the
    // request actually leaves, not at an await inside a later batch task.
    let dispatched = false;

    const tasks = batches.map(async (batch) => {
      // A free permit is taken synchronously, so the batch reaches `fetch`
      // in the caller's tick (recall-lane-latency): `await acquire()` alone
      // would park the dispatch on a microtask until the caller's
      // synchronous work - the keyword lanes - had finished.
      const permit = sem.tryAcquire() ?? (await sem.acquire());
      try {
        if (cancel.signal.aborted) return;
        if (dispatched === false && opts?.onDispatch !== undefined) {
          dispatched = true;
          opts.onDispatch();
        }
        const vectors = await this.embedBatchWithRetry(
          batch.map((b) => b.text),
          { maxAttempts: this.config.maxRetries, parentSignal: cancel.signal },
        );
        for (let i = 0; i < vectors.length; i++) {
          out[batch[i]!.originalIndex] = vectors[i]!;
        }
      } finally {
        permit();
      }
    });

    try {
      try {
        await Promise.all(tasks);
      } catch (firstError) {
        cancel.abort();
        await Promise.allSettled(tasks);
        if (firstError instanceof SearchError) throw firstError;
        throw new SearchError("EMBEDDING_PROVIDER_HTTP", String(firstError));
      }
    } finally {
      cancel.abort();
      unlink();
    }
    return out;
  }

  async ping(): Promise<PingResult> {
    try {
      const vectors = await this.embedBatchWithRetry(["check"], { maxAttempts: 1 });
      const v = vectors[0];
      if (!v) return { ok: false, reason: "empty response" };
      return { ok: true, dimension: v.length };
    } catch (e) {
      const reason = e instanceof Error ? e.message : String(e);
      // See the openai-compat provider: a request abandoned on our own
      // clock learned nothing, and must not read as a refusal.
      return isRequestTimeout(e) ? { ok: false, reason, timedOut: true } : { ok: false, reason };
    }
  }

  private async embedBatchWithRetry(
    texts: string[],
    opts?: { maxAttempts?: number; parentSignal?: AbortSignal },
  ): Promise<number[][]> {
    const maxAttempts = opts?.maxAttempts ?? 3;
    let lastError: SearchError | null = null;
    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
      if (opts?.parentSignal?.aborted) {
        throw new SearchError("EMBEDDING_PROVIDER_HTTP", "embed cancelled");
      }
      try {
        return await this.embedBatchOnce(texts, opts?.parentSignal);
      } catch (e) {
        const err = this.classifyError(e);
        if (!err.retriable || attempt >= maxAttempts) throw err.error;
        lastError = err.error;
        this.retriesSeen++;
        const wait = jittered(
          this.backoffMs[attempt - 1] ?? this.backoffMs[this.backoffMs.length - 1] ?? 4000,
        );
        await sleep(wait);
      }
    }
    throw lastError ?? new SearchError("EMBEDDING_PROVIDER_HTTP", "retry loop exhausted");
  }

  private async embedBatchOnce(texts: string[], parentSignal?: AbortSignal): Promise<number[][]> {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
    const onParentAbort = () => controller.abort();
    if (parentSignal) {
      if (parentSignal.aborted) controller.abort();
      else parentSignal.addEventListener("abort", onParentAbort, { once: true });
    }
    let response: Response;
    try {
      response = await fetch(this.http.url, {
        method: "POST",
        headers: {
          "content-type": "application/json",
          authorization: `Bearer ${this.http.apiKey}`,
        },
        body: JSON.stringify({
          model: this.model,
          input_type: ZEROENTROPY_INPUT_TYPE,
          input: texts,
          encoding_format: "float",
          ...(this._dimension !== null ? { dimensions: this._dimension } : {}),
        }),
        // No cross-host redirect may take the bearer key - or the chunk
        // bodies - somewhere the operator did not configure.
        redirect: "error",
        signal: controller.signal,
      });
    } catch (e) {
      const cause = e instanceof Error ? e : new Error(String(e));
      if (cause.name === "AbortError") {
        if (parentSignal?.aborted) {
          throw new SearchError("EMBEDDING_PROVIDER_HTTP", "embed cancelled");
        }
        throw new SearchError(
          "EMBEDDING_PROVIDER_TIMEOUT",
          `embedding request timed out after ${this.config.timeoutMs}ms`,
        );
      }
      throw new SearchError("EMBEDDING_PROVIDER_HTTP", `network error: ${cause.message}`);
    } finally {
      clearTimeout(timer);
      if (parentSignal) parentSignal.removeEventListener("abort", onParentAbort);
    }

    if (!response.ok) {
      const body = await response.text().catch(() => "");
      const head = body.slice(0, 300);
      throw new SearchError(
        "EMBEDDING_PROVIDER_HTTP",
        `embedding HTTP ${response.status}: ${head || response.statusText}`,
      );
    }

    let json: ZeroEntropyEmbeddingResponse;
    try {
      json = (await response.json()) as ZeroEntropyEmbeddingResponse;
    } catch (e) {
      const msg = e instanceof Error ? e.message : String(e);
      throw new SearchError("EMBEDDING_PROVIDER_HTTP", `embedding response not JSON: ${msg}`);
    }

    if (!Array.isArray(json.results) || json.results.length !== texts.length) {
      throw new SearchError(
        "EMBEDDING_PROVIDER_HTTP",
        `embedding response shape: expected ${texts.length} vectors, got ${json.results?.length ?? "none"}`,
      );
    }

    const ordered: number[][] = new Array(texts.length);
    for (let i = 0; i < json.results.length; i++) {
      const item = json.results[i]!;
      if (!Array.isArray(item.embedding)) {
        throw new SearchError(
          "EMBEDDING_PROVIDER_HTTP",
          `embedding response: results[${i}].embedding is not an array`,
        );
      }
      const arr = (item.embedding as ReadonlyArray<number>).slice();
      if (this._dimension === null) {
        this._dimension = arr.length;
      } else if (this._dimension !== arr.length) {
        throw new SearchError(
          "EMBEDDING_DIMENSION_MISMATCH",
          `embedding dimension changed mid-batch: expected ${this._dimension}, got ${arr.length}`,
        );
      }
      ordered[i] = unitNormaliseInPlace(arr);
    }
    return ordered;
  }

  private classifyError(e: unknown): { retriable: boolean; error: SearchError } {
    if (e instanceof SearchError) {
      if (e.message.includes("embed cancelled")) return { retriable: false, error: e };
      if (e.code === "EMBEDDING_PROVIDER_TIMEOUT") return { retriable: true, error: e };
      if (e.code === "EMBEDDING_PROVIDER_HTTP") {
        const m = e.message.match(/HTTP (\d+)/);
        if (m) return { retriable: RETRYABLE_STATUSES.has(Number(m[1])), error: e };
        return { retriable: true, error: e };
      }
      return { retriable: false, error: e };
    }
    return { retriable: false, error: new SearchError("EMBEDDING_PROVIDER_HTTP", String(e)) };
  }
}