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
7.9 KB
Raw Blame
/**
 * OpenAI-compatible cross-encoder rerank provider
 * (retrieval-precision-quality-loop, card A / t_110867f5).
 *
 * Calls a `{base_url}/rerank` endpoint — the shape Cohere, Jina,
 * text-embeddings-inference, and vLLM's rerank route share — with
 * `{ model, query, documents }` and reads one relevance score per
 * document back. Both the wrapped `{ results: [{ index, relevance_score }] }`
 * shape and the bare `[{ index, score }]` array shape are accepted, so a
 * single provider works across compatible backends.
 *
 * Network rules mirror `embeddings/openai-compat.ts` at a smaller scale:
 * one request (the top-K candidate set is small, no batching), a
 * per-request timeout, and provider-shaped `RerankEndpointError`s (a
 * `SearchError` with code `RERANK_PROVIDER_HTTP` plus a closed failure
 * category, see `failure.ts`). Retries are
 * intentionally omitted: this is an opt-in final reader step that
 * degrades gracefully to the heuristic ordering on ANY failure (see
 * `applyCrossEncoderRerank`), so a slow retry loop would only add latency
 * to the hot path for a result the caller already has a good answer for.
 */

import { assertHttpEgressEndpoint, linkAbortSignal } from "../embeddings/http-util.ts";
import type { OpenAiCompatEndpoint } from "../embeddings/provider-resolve.ts";
import type { RerankCallOptions, RerankProvider } from "./contract.ts";
import {
  RERANK_FAILURE_CATEGORY,
  RerankEndpointError,
  rerankCategoryForStatus,
} from "./failure.ts";

/** A 2xx body this build cannot read as one score per document. */
function malformed(message: string): RerankEndpointError {
  return new RerankEndpointError(message, { category: RERANK_FAILURE_CATEGORY.malformed });
}

/** Default per-request timeout when the caller does not override it. */
export const DEFAULT_RERANK_TIMEOUT_MS = 5000;

interface RerankResultItem {
  readonly index: number;
  readonly relevance_score?: number;
  readonly score?: number;
}

interface WrappedRerankResponse {
  readonly results: ReadonlyArray<RerankResultItem>;
}

function extractItems(json: unknown): ReadonlyArray<RerankResultItem> {
  if (Array.isArray(json)) return json as ReadonlyArray<RerankResultItem>;
  if (
    json !== null &&
    typeof json === "object" &&
    Array.isArray((json as WrappedRerankResponse).results)
  ) {
    return (json as WrappedRerankResponse).results;
  }
  throw malformed("rerank response shape: expected an array or a { results: [...] } object");
}

function scoreOf(item: RerankResultItem): number {
  const raw = item.relevance_score ?? item.score;
  if (typeof raw !== "number" || !Number.isFinite(raw)) {
    throw malformed(`rerank response: item at index ${item.index} has no finite relevance score`);
  }
  return raw;
}

export class CrossEncoderRerankProvider implements RerankProvider {
  readonly name = "openai-compat-rerank";
  readonly model: string;
  private readonly endpoint: OpenAiCompatEndpoint;
  private readonly url: string;
  private readonly timeoutMs: number;

  constructor(endpoint: OpenAiCompatEndpoint, opts?: { readonly timeoutMs?: number }) {
    this.endpoint = endpoint;
    this.model = endpoint.model;
    // Same endpoint rule the embedding providers answer to: the vault
    // query text and the bearer key both travel to this host.
    const base = assertHttpEgressEndpoint(endpoint.baseUrl, "search_rerank_base_url", {
      allowInsecureHttp: endpoint.allowInsecureHttp === true,
      key: "search_rerank_allow_insecure_http",
    });
    this.url = `${base.replace(/\/+$/, "")}/rerank`;
    this.timeoutMs = opts?.timeoutMs ?? DEFAULT_RERANK_TIMEOUT_MS;
  }

  async rerank(
    query: string,
    documents: ReadonlyArray<string>,
    opts?: RerankCallOptions,
  ): Promise<number[]> {
    if (documents.length === 0) return [];

    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
    const unlink = linkAbortSignal(opts?.signal, controller);
    // The timeout and the caller's signal cover the body read as well as
    // the fetch, so the timer is cleared only once the body is in.
    let text: string;
    try {
      let response: Response;
      try {
        response = await fetch(this.url, {
          method: "POST",
          headers: {
            "content-type": "application/json",
            authorization: `Bearer ${this.endpoint.apiKey}`,
          },
          body: JSON.stringify({
            model: this.model,
            query,
            documents: [...documents],
          }),
          // No cross-host redirect may take the bearer key - or the query -
          // somewhere the operator did not configure.
          redirect: "error",
          signal: controller.signal,
        });
      } catch (e) {
        const cause = e instanceof Error ? e : new Error(String(e));
        // The caller cancelled: its own abort reason travels up unchanged,
        // so the caller recognises its cancellation by name.
        if (opts?.signal?.aborted === true) throw opts.signal.reason;
        if (controller.signal.aborted) {
          throw new RerankEndpointError(`rerank request timed out after ${this.timeoutMs}ms`, {
            category: RERANK_FAILURE_CATEGORY.timeout,
          });
        }
        throw new RerankEndpointError(`network error: ${cause.message}`, {
          category: RERANK_FAILURE_CATEGORY.network,
        });
      }

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

      // Read and parse apart: a stream that breaks while the 2xx body is
      // read is the path failing (`network`), while a body that arrived
      // whole and is not JSON is the endpoint's answer (`malformed`).
      try {
        text = await response.text();
      } catch (e) {
        // The timer and the caller's signal abort a stalled body too, and
        // read the same way they do for the fetch.
        if (opts?.signal?.aborted === true) throw opts.signal.reason;
        if (controller.signal.aborted) {
          throw new RerankEndpointError(`rerank request timed out after ${this.timeoutMs}ms`, {
            category: RERANK_FAILURE_CATEGORY.timeout,
          });
        }
        const msg = e instanceof Error ? e.message : String(e);
        throw new RerankEndpointError(`network error: ${msg}`, {
          category: RERANK_FAILURE_CATEGORY.network,
        });
      }
    } finally {
      clearTimeout(timer);
      unlink();
    }
    let json: unknown;
    try {
      // Parsed through a Response rather than JSON.parse, so the parse
      // error, and with it the message, is the one `response.json()` gave.
      json = await new Response(text).json();
    } catch (e) {
      const msg = e instanceof Error ? e.message : String(e);
      throw malformed(`rerank response not JSON: ${msg}`);
    }

    const items = extractItems(json);
    if (items.length !== documents.length) {
      throw malformed(
        `rerank response shape: expected ${documents.length} scores, got ${items.length}`,
      );
    }

    // Map back to input order. Each item carries its own `index`, so a
    // backend that returns them sorted by score is realigned here.
    const scores: number[] = Array.from({ length: documents.length }, () => Number.NaN);
    const seen: boolean[] = Array.from({ length: documents.length }, () => false);
    for (const item of items) {
      if (
        typeof item.index !== "number" ||
        item.index < 0 ||
        item.index >= documents.length ||
        !Number.isInteger(item.index)
      ) {
        throw malformed(`rerank response: out-of-range index ${item.index}`);
      }
      if (seen[item.index]) {
        throw malformed(`rerank response: duplicate index ${item.index}`);
      }
      seen[item.index] = true;
      scores[item.index] = scoreOf(item);
    }
    return scores;
  }
}