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
12.3 KB
Raw Blame
/**
 * Cross-encoder rerank stage - the final reader step
 * (retrieval-precision-quality-loop, card A / t_110867f5).
 *
 * {@link applyCrossEncoderRerank} re-scores the top-K fused candidates
 * jointly against the query using a learned cross-encoder, then re-orders
 * that block by the returned relevance scores. It is appended AFTER the
 * heuristic reranks (relevance rerank, entity boost, MMR, usage decay) in
 * the reader tail, so it is the last word on ordering.
 *
 * Three invariants, mirroring the embedding-provider discipline:
 *   1. Disabled (the default) -> the input is returned unchanged, with no
 *      HTTP call, no allocation of a new array, and no telemetry. The
 *      reader tail is byte-identical to the pre-feature baseline.
 *   2. Enabled but unconfigured -> fail closed. Endpoint resolution
 *      (`resolveOpenAiCompatEndpoint`) throws a typed `SearchError`, the
 *      same discipline `openai-compat.ts` applies when semantic is
 *      enabled without a base_url/model/key. This is a configuration
 *      error the operator must fix, not a hot-path degrade.
 *   3. Enabled and configured but the endpoint errors at request time ->
 *      degrade gracefully to the heuristic-ordered input (never throw
 *      into the hot path) and emit one fail-open telemetry event.
 */

import { resolveOpenAiCompatEndpoint } from "../embeddings/provider-resolve.ts";
import type { BrainSearchResult, ResolvedRerankConfig } from "../types.ts";
import { makeRerankProvider } from "./provider.ts";
import type { RerankProvider } from "./contract.ts";
import type { DecisionProvider } from "../../decision-model/contract.ts";
import type { DecisionRerankExtras } from "./decision-model.ts";
import {
  RERANK_FAILURE_CATEGORY,
  RerankEndpointError,
  rerankCategoryForError,
  type RerankFailureCategory,
} from "./failure.ts";
import { classifyRerankSunset, rerankSunsetHasPassed } from "./sunset.ts";
import type { EmbeddingSunsetSurvey } from "../embeddings/sunset.ts";

/** Fixed-precision so the reason string is stable for a given score. */
function fmtScore(x: number): string {
  return x.toFixed(4);
}

interface RerankTelemetryBase {
  /** Number of top candidates handed to the cross-encoder. */
  readonly candidateCount: number;
}

/** The rerank re-ordered the top-K block. */
export interface RerankAppliedEvent extends RerankTelemetryBase {
  readonly status: "applied";
}

/** The rerank request failed and the heuristic order was served. */
export interface RerankErrorEvent extends RerankTelemetryBase {
  readonly status: "error";
  /** Why, as a closed category computed from the typed failure. */
  readonly category: RerankFailureCategory;
  /** The provider-shaped failure message, for the operator-facing warning. */
  readonly reason: string;
}

export type RerankTelemetryEvent = RerankAppliedEvent | RerankErrorEvent;

export interface ApplyCrossEncoderRerankOptions {
  /** Inject a provider (tests / alternate backends). Defaults to the HTTP one. */
  readonly provider?: RerankProvider;
  /** Environment map for env-key resolution; defaults to `process.env`. */
  readonly env?: Readonly<Record<string, string | undefined>>;
  /** Per-request timeout override for the default provider. */
  readonly timeoutMs?: number;
  /**
   * Fail-open telemetry sink. Invoked at most once per call - on success
   * (`applied`) or on a request-time degrade (`error`). Never invoked on
   * the disabled path. The caller wraps this so a throwing sink can never
   * fail the search.
   */
  readonly onTelemetry?: (event: RerankTelemetryEvent) => void;
  /**
   * Visibility tokens for a result path, or null when unresolvable. Used
   * only by the `decision-model` kind, which never sends a candidate whose
   * page is private or whose visibility cannot be resolved.
   */
  readonly resolveVisibility?: (path: string) => ReadonlyArray<string> | null;
  /**
   * The `<private>` regions of a result's page, or null when the page
   * cannot be read. `decision-model` kind only: a chunk that carries part
   * of a region is never sent.
   */
  readonly resolvePrivateRegions?: (path: string) => ReadonlyArray<string> | null;
  /**
   * Skip the `decision-model` kind for this call (the hook surfaces, which
   * run under a tighter time budget than a decision request). The order is
   * returned unchanged and `onDecisionFallback` fires.
   */
  readonly skipDecisionModel?: boolean;
  /**
   * Called when the `decision-model` kind returned the heuristic order in
   * place of the configured one (degraded, not active, or skipped).
   */
  readonly onDecisionFallback?: () => void;
  /** Inject a decision provider (tests). `decision-model` kind only. */
  readonly decisionProvider?: DecisionProvider;
  /** Receives the extra decision answers (e.g. `answerable`). */
  readonly onDecisionExtras?: (extras: DecisionRerankExtras) => void;
  /**
   * Decision-model kind only: the `status` and `updated` frontmatter
   * values of a result's page, sent beside its passage.
   */
  readonly resolveMeta?: (path: string) => Readonly<Record<string, string>> | null;
  /** The eval gate measures `enforce` whatever the configured mode. */
  readonly decisionModeOverride?: "shadow" | "enforce";
  /**
   * The caller's cancellation (the composite hybrid deadline). An aborted
   * call stops its provider request and rejects with the signal's reason
   * instead of degrading, because nobody is waiting for the order.
   */
  readonly signal?: AbortSignal;
  /**
   * `openai-compat` kind only: consult the rerank sunset survey for the
   * configured model, and skip the request once its announced shutdown
   * date has passed. Absent: the survey is not consulted (direct callers
   * and tests that measure the endpoint they are pointed at).
   */
  readonly sunset?: RerankSunsetOptions;
}

/**
 * The sunset skip's inputs. The clock is the caller's own, so this stage
 * reads no wall clock; the survey defaults to the shipped one.
 */
export interface RerankSunsetOptions {
  readonly nowMs: number;
  readonly survey?: EmbeddingSunsetSurvey;
  /** Called once when the configured model is past its announced date. */
  readonly onSkip: () => void;
}

interface Scored {
  readonly result: BrainSearchResult;
  readonly index: number;
  readonly score: number;
}

/**
 * Re-order the top-K block by cross-encoder score, honouring the
 * `minScore` floor. Deterministic given the scores: qualifying candidates
 * (score >= floor) sort by score descending, ties broken by original
 * index; below-floor candidates keep their original relative order and
 * sit below the qualifying ones. Each reranked hit gains a
 * `cross_encoder:` reason so explainability shows the stage fired.
 */
function reorderTopK(
  head: ReadonlyArray<BrainSearchResult>,
  scores: ReadonlyArray<number>,
  minScore: number,
): BrainSearchResult[] {
  const scored: Scored[] = head.map((result, index) => ({
    result,
    index,
    score: scores[index] ?? Number.NEGATIVE_INFINITY,
  }));
  const qualifying = scored.filter((s) => s.score >= minScore);
  const belowFloor = scored.filter((s) => s.score < minScore);
  qualifying.sort((a, b) => b.score - a.score || a.index - b.index);
  return [...qualifying, ...belowFloor].map((s) =>
    Object.freeze({
      ...s.result,
      reasons: Object.freeze([...s.result.reasons, `cross_encoder: ${fmtScore(s.score)}`]),
    }),
  );
}

/**
 * Apply the optional cross-encoder rerank stage. Returns the input
 * unchanged when disabled or on a request-time endpoint error; throws a
 * typed `SearchError` when enabled but the endpoint is unconfigured.
 */
export async function applyCrossEncoderRerank(
  results: ReadonlyArray<BrainSearchResult>,
  query: string,
  config: ResolvedRerankConfig,
  opts: ApplyCrossEncoderRerankOptions = {},
): Promise<ReadonlyArray<BrainSearchResult>> {
  // Invariant 1: disabled -> zero-cost no-op, byte-identical input.
  if (!config.enabled) return results;

  // The decision-model kind owns its own fail-open and privacy rules and
  // never emits rerank telemetry: a failed decision is recorded in the
  // `decision_model_call` record and returns the heuristic order unchanged.
  if (config.kind === "decision-model") {
    if (opts.skipDecisionModel === true) {
      opts.onDecisionFallback?.();
      return results;
    }
    // eslint-disable-next-line @typescript-eslint/no-require-imports
    const { applyDecisionModelRerank } =
      require("./decision-model.ts") as typeof import("./decision-model.ts");
    return applyDecisionModelRerank(results, query, config, {
      ...(opts.resolveVisibility !== undefined
        ? { resolveVisibility: opts.resolveVisibility }
        : {}),
      ...(opts.resolvePrivateRegions !== undefined
        ? { resolvePrivateRegions: opts.resolvePrivateRegions }
        : {}),
      ...(opts.onDecisionFallback !== undefined ? { onFallback: opts.onDecisionFallback } : {}),
      ...(opts.decisionProvider !== undefined ? { provider: opts.decisionProvider } : {}),
      ...(opts.env !== undefined ? { env: opts.env } : {}),
      ...(opts.onDecisionExtras !== undefined ? { onExtras: opts.onDecisionExtras } : {}),
      ...(opts.resolveMeta !== undefined ? { resolveMeta: opts.resolveMeta } : {}),
      ...(opts.decisionModeOverride !== undefined
        ? { modeOverride: opts.decisionModeOverride }
        : {}),
      ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
    });
  }

  // Resolve the provider. The bundled offline reranker ("local") needs no
  // endpoint - it is deterministic and network-free. The remote
  // "openai-compat" path resolves fail-closed (Invariant 2): a misconfigured
  // endpoint throws a typed SearchError (an operator error, not a hot-path
  // degrade). An injected provider (tests) bypasses both.
  let provider = opts.provider;
  if (!provider) {
    if (config.kind === "local") {
      // eslint-disable-next-line @typescript-eslint/no-require-imports
      const { LocalRerankProvider } = require("./local.ts") as typeof import("./local.ts");
      provider = new LocalRerankProvider();
    } else {
      const endpoint = resolveOpenAiCompatEndpoint(
        {
          enabled: true,
          baseUrl: config.baseUrl,
          model: config.model,
          envKey: config.envKey,
          apiKey: config.apiKey,
          env: opts.env,
          ...(config.allowInsecureHttp === true ? { allowInsecureHttp: true } : {}),
        },
        "search_rerank",
      );
      // resolveOpenAiCompatEndpoint only returns null when `enabled` is
      // false, which we ruled out above; the narrowing keeps TS honest.
      if (endpoint === null) return results;
      provider = makeRerankProvider(endpoint, { timeoutMs: opts.timeoutMs });
    }
  }

  if (results.length === 0) return results;

  // A model past its announced shutdown can only refuse the request, so
  // none is made. Only the remote kind keys on a model string a vendor
  // can retire; `local` is this build's own reranker.
  if (config.kind === "openai-compat" && opts.sunset !== undefined) {
    const verdict = classifyRerankSunset(config.model, opts.sunset.nowMs, opts.sunset.survey);
    if (rerankSunsetHasPassed(verdict)) {
      opts.sunset.onSkip();
      return results;
    }
  }

  const topK = Math.min(Math.max(1, config.topK), results.length);
  const head = results.slice(0, topK);
  const tail = results.slice(topK);
  const documents = head.map((r) => r.content);

  let scores: number[];
  try {
    scores = await provider.rerank(
      query,
      documents,
      opts.signal !== undefined ? { signal: opts.signal } : undefined,
    );
    if (scores.length !== documents.length) {
      throw new RerankEndpointError(`expected ${documents.length} scores, got ${scores.length}`, {
        category: RERANK_FAILURE_CATEGORY.malformed,
      });
    }
  } catch (e) {
    // A cancelled call is not an endpoint failure: no telemetry, and the
    // caller's own abort reason travels up.
    if (opts.signal?.aborted === true) throw opts.signal.reason;
    // Invariant 3: request-time degrade. Return the heuristic ordering
    // untouched and emit one fail-open telemetry event.
    opts.onTelemetry?.({
      status: "error",
      category: rerankCategoryForError(e),
      reason: e instanceof Error ? e.message : String(e),
      candidateCount: topK,
    });
    return results;
  }

  const reordered = reorderTopK(head, scores, config.minScore);
  opts.onTelemetry?.({ status: "applied", candidateCount: topK });
  return [...reordered, ...tail];
}