md-semantic-search 0.3.0 → 0.4.0

package/src/metrics.mjs

@@ -0,0 +1,186 @@
+// @ts-check
+/**
+ * Retrieval evaluation metrics (issue #56).
+ *
+ * Pure, dependency-free ranking metrics used by the golden-set harness. They
+ * operate on a list of ranked hits plus graded relevance judgements so the
+ * same functions work for chunk-level and document-level evaluation.
+ *
+ * Relevance judgements use the graded scale from the benchmark design:
+ *   0 = irrelevant, 1 = related, 2 = useful support, 3 = direct answer.
+ * For metrics that need binary relevance (`MRR`, `Hit@k`, `Recall@k`) a grade
+ * threshold separates relevant from irrelevant. The default threshold is > 0
+ * (any non-zero grade counts as relevant); pass `minRelevant` to require, e.g.
+ * grade >= 2 for stricter precision-oriented slices.
+ */
+
+/**
+ * @typedef {Object} BenchHit
+ * @property {string} file - document id of the hit (canonical identity)
+ *
+ * @typedef {Object} GradeConf
+ * @property {number[]} [grades] - per-document top grade: index i is the best
+ *   grade over all judgements for doc i (default: []).
+ * @property {number} [minRelevant=1] - minimum grade that counts as relevant.
+ */
+
+/**
+ * nDCG@k (normalized discounted cumulative gain) with graded relevance.
+ * Uses the standard log2 discount (position 1 has no discount).
+ * @param {string[]} ranked - ranked document ids (hits, best first)
+ * @param {(doc:string, rankIndex:number)=>number} grade - grade(doc, idx) >= 0
+ * @param {number} k
+ * @returns {number} in [0, 1]; 1 = perfect ordering at the top-k.
+ */
+export function ndcgAtK(ranked, grade, k) {
+  const top = ranked.slice(0, k);
+  if (top.length === 0) return 0;
+  let dcg = 0;
+  for (let i = 0; i < top.length; i++) {
+    const g = grade(top[i], i);
+    if (g <= 0) continue;
+    dcg += g / Math.log2(i + 2); // log2(1+1)=1 for rank 0, log2(3) for rank 1, ...
+  }
+  if (dcg === 0) return 0;
+  // Ideal DCG: sort all relevant grades (any doc) descending, take top-k.
+  const all = (ranked ?? []).map((doc, i) => grade(doc, i)).filter((g) => g > 0);
+  const ideal = [...all].sort((a, b) => b - a).slice(0, k);
+  let idcg = 0;
+  for (let i = 0; i < ideal.length; i++) idcg += ideal[i] / Math.log2(i + 2);
+  return idcg === 0 ? 0 : dcg / idcg;
+}
+
+/**
+ * Reciprocal rank of the first relevant doc (MRR contribution for one query).
+ * @param {string[]} ranked
+ * @param {(doc:string)=>boolean} isRelevant
+ * @returns {number} 1/rank if a relevant doc is found, else 0.
+ */
+export function reciprocalRank(ranked, isRelevant) {
+  for (let i = 0; i < ranked.length; i++) {
+    if (isRelevant(ranked[i])) return 1 / (i + 1);
+  }
+  return 0;
+}
+
+/**
+ * Hit@k — 1 if any relevant doc appears in the top-k.
+ * @param {string[]} ranked
+ * @param {(doc:string)=>boolean} isRelevant
+ * @param {number} k
+ * @returns {0|1}
+ */
+export function hitAtK(ranked, isRelevant, k) {
+  return ranked.slice(0, k).some(isRelevant) ? 1 : 0;
+}
+
+/**
+ * Recall@k — fraction of ALL relevant docs that appear in the top-k.
+ * @param {string[]} ranked
+ * @param {(doc:string)=>boolean} isRelevant
+ * @param {number} k
+ * @returns {number} in [0, 1].
+ */
+export function recallAtK(ranked, isRelevant, k) {
+  const relevantCount = (ranked ?? []).filter(isRelevant).length;
+  if (relevantCount === 0) return 0;
+  const retrieved = ranked.slice(0, k).filter(isRelevant).length;
+  return retrieved / relevantCount;
+}
+
+/**
+ * Build a top-grade helper: for each doc, the highest grade across qrels.
+ * @param {Record<string, number>} docGrades - doc id -> best grade observed.
+ * @returns {(doc:string)=>number}
+ */
+export function gradeByDoc(docGrades) {
+  /** @type {Record<string, number>} */
+  const table = Object.create(null);
+  for (const [doc, g] of Object.entries(docGrades)) {
+    table[doc] = g;
+  }
+  return (doc) => table[doc] ?? 0;
+}
+
+/**
+ * Convenience: compute the core aggregate metrics for one query in one pass.
+ * @param {string[]} ranked - ranked doc ids, best first (top-N as returned).
+ * @param {Record<string, number>} docGrades - doc->top grade (graded qrels).
+ * @param {object} [opts]
+ * @param {number} [opts.k=10]
+ * @param {number} [opts.minRelevant=1]
+ * @param {string[]} [opts.allRelevant] - all relevant doc ids (for Recall when
+ *   the ranked list is truncated at k). Defaults to the keys of docGrades with
+ *   grade >= minRelevant.
+ * @returns {{ndcg:number, mrr:number, hit:0|1, recall:number}}
+ */
+export function queryMetrics(ranked, docGrades, opts = {}) {
+  const { k = 10, minRelevant = 1 } = opts;
+  const grade = gradeByDoc(docGrades);
+  const isRelevant = (doc) => grade(doc) >= minRelevant;
+  const allRelevant = opts.allRelevant ??
+    Object.entries(docGrades).filter(([, g]) => g >= minRelevant).map(([d]) => d);
+  // Recall needs the FULL ranked set; when truncated, patch with allRelevant.
+  const fullRanked = ranked.length >= k ? ranked : [...ranked, ...allRelevant.filter((d) => !ranked.includes(d))];
+  return {
+    ndcg: ndcgAtK(ranked, grade, k),
+    mrr: reciprocalRank(ranked, isRelevant),
+    hit: hitAtK(ranked, isRelevant, k),
+    recall: recallAtK(fullRanked, isRelevant, k),
+  };
+}
+
+/**
+ * Aggregate a list of per-query metric objects into means + win/tie/loss.
+ * @param {Array<{ndcg:number, mrr:number, hit:0|1, recall:number}>} qm
+ * @returns {{mean:{ndcg:number, mrr:number, hit:number, recall:number}, n:number}}
+ */
+export function aggregateMetrics(qm) {
+  const n = qm.length;
+  if (n === 0) return { mean: { ndcg: 0, mrr: 0, hit: 0, recall: 0 }, n: 0 };
+  const sum = (key) => qm.reduce((acc, m) => acc + m[key], 0) / n;
+  return {
+    n,
+    mean: { ndcg: sum('ndcg'), mrr: sum('mrr'), hit: sum('hit'), recall: sum('recall') },
+  };
+}
+
+/**
+ * Win/tie/loss between two per-query metric series (paired comparison).
+ * Uses nDCG@10 as the primary comparison metric.
+ * @param {Array<{ndcg:number}>} a
+ * @param {Array<{ndcg:number}>} b
+ * @param {number} [epsilon=1e-6]
+ * @returns {{win:number, tie:number, loss:number}}
+ */
+export function winTieLoss(a, b, epsilon = 1e-6) {
+  let win = 0, tie = 0, loss = 0;
+  for (let i = 0; i < Math.min(a.length, b.length); i++) {
+    const d = a[i].ndcg - b[i].ndcg;
+    if (d > epsilon) win++;
+    else if (d < -epsilon) loss++;
+    else tie++;
+  }
+  return { win, tie, loss };
+}
+
+/**
+ * Document-level redundancy fraction over the top-k hits: the proportion of
+ * top-k hits whose file id duplicates an EARLIER top-k hit's file. A value of
+ * 0 means every top-k hit comes from a distinct file; 1 means every hit after
+ * the first reuses an already-seen source file.
+ * @param {Array<{file:string}>} ranked - ranked hits, best first.
+ * @param {number} k - window size.
+ * @returns {number} in [0, 1]; 0 when no hits are present.
+ */
+export function redundancyAtK(ranked, k) {
+  const seen = new Set();
+  let redundant = 0;
+  const counted = ranked.slice(0, k);
+  for (let i = 0; i < counted.length; i++) {
+    const doc = counted[i].file;
+    if (seen.has(doc)) redundant++;
+    else seen.add(doc);
+  }
+  return counted.length === 0 ? 0 : redundant / counted.length;
+}

package/src/models.mjs

@@ -1,67 +1,299 @@
+// @ts-check
 /**
- * Embedding model registry.
+ * Embedding model adapter registry (issue #60).
  *
- * `prefix` matters: the E5 family is trained with instruction prefixes
- * ("query: " / "passage: ") and ranks poorly without them. BGE-M3 is trained
- * WITHOUT prefixes, so forcing them in would hurt. Each entry declares how to
- * format inputs so the rest of the code stays model-agnostic.
+ * Each registered model declares an EXPLICIT adapter that makes preprocessing
+ * (query/document formatting), pooling, normalization, runtime dtype, token
+ * budget, and dimensions auditable. The shared `embed()` path no longer infers
+ * any of this from the model name — it reads the adapter fields, so adding a
+ * heterogeneous family (e.g. Qwen3 with instruction queries + last-token
+ * pooling) cannot silently produce wrong vectors.
+ *
+ * The adapter fingerprint hashes exactly the fields that change the produced
+ * vectors (formatting, pooling, normalization, dimension); model weights
+ * (id@revision) remain a separate identity. Unknown raw Hugging Face ids no
+ * longer silently inherit E5-style `query:`/`passage:` prefixes and mean
+ * pooling — they resolve to a neutral descriptor that FAILS at embed time with
+ * an actionable message until an explicit adapter is provided.
+ */
+import crypto from 'node:crypto';
+
+/**
+ * @typedef {'mean'|'last_token'|'none'} Pooling
+ *
+ * Runtime ONNX data type for the Transformers.js pipeline load. A subset of
+ * the valid dtype strings; `q8` is the project default (quantized weights).
+ * @typedef {'q8'|'q4'|'fp16'|'fp32'|'int8'|'uint8'} DType
+ *
+ * @typedef {Object} ModelAdapter
+ * @property {string} id - HF repo id (e.g. "Xenova/multilingual-e5-base")
+ * @property {string} [revision] - pinned revision (default "main")
+ * @property {number} nativeDim - native embedding dimension (>= 0 to infer)
+ * @property {number} dim - canonical embedding dimension; alias of nativeDim
+ *   for resolved adapters (legacy consumers read `dim`)
+ * @property {number[]} [dimensions] - allowed output dimensions (MRL policy);
+ *   always implicitly includes nativeDim when present
+ * @property {string} queryPrefix - text prepended to every query ('' = none)
+ * @property {string} passagePrefix - text prepended to every passage ('' = none)
+ * @property {Pooling} pooling - token pooling strategy
+ * @property {boolean} [normalize=true] - whether vectors are L2-normalized
+ * @property {DType} [dtype] - runtime ONNX dtype (default 'q8')
+ * @property {number} [maxTokens] - declared tokenizer budget (context window)
+ * @property {Record<string, unknown>} [sessionOptions] - ONNX Runtime session options (e.g. intraOpNumThreads)
+ * @property {string} [family] - formatting/pooling family key exposed by
+ *   `mdss stats`/`models` (e.g. 'e5', 'bge', 'qwen3'); NOT used for routing
+ * @property {string} [note] - human-readable description
+ * @property {boolean} [unknownAdapter] - true only for unconfigured raw ids;
+ *   such adapters are unusable for embedding until explicitly configured
+ */
+
+/**
+ * Registered adapters keyed by CLI/library alias.
+ * @type {Record<string, ModelAdapter>}
  */
 export const MODELS = {
   'e5-small': {
     id: 'Xenova/multilingual-e5-small',
+    nativeDim: 384,
     dim: 384,
     queryPrefix: 'query: ',
     passagePrefix: 'passage: ',
+    pooling: 'mean',
+    normalize: true,
+    dtype: 'q8',
+    maxTokens: 512,
+    family: 'e5',
     note: 'Fastest, ~120MB. Weak cross-lingual ranking — see RESEARCH.md.',
   },
   'e5-base': {
     id: 'Xenova/multilingual-e5-base',
+    nativeDim: 768,
     dim: 768,
     queryPrefix: 'query: ',
     passagePrefix: 'passage: ',
+    pooling: 'mean',
+    normalize: true,
+    dtype: 'q8',
+    maxTokens: 512,
+    family: 'e5',
     note: 'Default. ~280MB. Solid multilingual + cross-lingual balance.',
   },
   'e5-large': {
     id: 'Xenova/multilingual-e5-large',
+    nativeDim: 1024,
     dim: 1024,
     queryPrefix: 'query: ',
     passagePrefix: 'passage: ',
+    pooling: 'mean',
+    normalize: true,
+    dtype: 'q8',
+    maxTokens: 512,
+    family: 'e5',
     note: '~2.2GB. Higher quality, slower.',
   },
   'bge-m3': {
     id: 'Xenova/bge-m3',
+    nativeDim: 1024,
     dim: 1024,
     queryPrefix: '',
     passagePrefix: '',
+    pooling: 'mean',
+    normalize: true,
+    dtype: 'q8',
+    maxTokens: 512,
+    family: 'bge',
     note: '~2.3GB. Best cross-lingual separation in our tests; no prefixes.',
   },
+  'qwen3-embedding-0.6b': {
+    id: 'onnx-community/Qwen3-Embedding-0.6B-ONNX',
+    revision: 'c25a394dd583836952667c12f008335071b3f43d',
+    nativeDim: 1024,
+    dim: 1024,
+    queryPrefix: 'Instruct: Given a web search query, retrieve relevant passages that answer the query\nQuery:',
+    passagePrefix: '',
+    pooling: 'last_token',
+    normalize: true,
+    dtype: 'q8',
+    maxTokens: 32768,
+    family: 'qwen3',
+    note: '~613 MB q8. Opt-in Qwen3 embedding model.',
+  },
 };
 
 export const DEFAULT_MODEL = 'e5-base';
 
+/** True for the pooling strategies the pipeline accepts. */
+export const POOLING = ['mean', 'last_token', 'none'];
+
+const POOLING_SET = new Set(POOLING);
+
+/** Map HF repo id → alias of the first registered adapter that owns it. */
+const aliasByRepoId = new Map();
+for (const [alias, adapter] of Object.entries(MODELS)) {
+  if (!aliasByRepoId.has(adapter.id)) aliasByRepoId.set(adapter.id, alias);
+}
+
+/** Ensure a resolved adapter exposes the legacy `dim` alias for nativeDim. */
+function withDim(adapter) {
+  return { ...adapter, dim: adapter.nativeDim };
+}
+
 /**
- * Resolve a model alias OR a raw HF id into a model descriptor.
- * A raw id may pin a revision with the `id@revision` syntax (defaults to
- * `main`), e.g. `--model "Xenova/multilingual-e5-small@a1b2c3d"`.
+ * Validate + normalize an explicit user-supplied adapter descriptor. Called
+ * with the neutral unknown-raw-id shape as a guard: a descriptor that lacks the
+ * vector-producing fields stays unusable.
+ * @param {Partial<ModelAdapter>|ModelAdapter} raw
+ * @returns {ModelAdapter}
+ */
+export function normalizeAdapter(raw) {
+  if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error('a custom model adapter must be an object with id, pooling, normalize, and dimension');
+  }
+  if (typeof raw.id !== 'string' || raw.id.trim().length === 0) {
+    throw new Error('a custom model adapter requires a nonempty `id`');
+  }
+  const pooling = raw.pooling ?? 'mean';
+  if (!POOLING_SET.has(pooling)) {
+    throw new Error(`unsupported pooling "${pooling}" — expected one of: ${POOLING.join(', ')}`);
+  }
+  const nativeDim = raw.nativeDim ?? raw.dim ?? 0;
+  if (!Number.isSafeInteger(nativeDim) || nativeDim < 0) {
+    throw new Error(`invalid adapter dimension ${nativeDim} — must be a non-negative safe integer`);
+  }
+  const dimensions = raw.dimensions !== undefined
+    ? (Array.isArray(raw.dimensions) && raw.dimensions.every(d => Number.isSafeInteger(d) && d > 0)
+      ? [...new Set(raw.dimensions)].sort((a, b) => a - b)
+      : [])
+    : [];
+  const adapter = withDim({
+    id: raw.id,
+    ...(raw.revision ? { revision: raw.revision } : {}),
+    nativeDim,
+    ...(dimensions.length > 0 ? { dimensions } : {}),
+    queryPrefix: typeof raw.queryPrefix === 'string' ? raw.queryPrefix : '',
+    passagePrefix: typeof raw.passagePrefix === 'string' ? raw.passagePrefix : '',
+    pooling,
+    normalize: raw.normalize !== false,
+    dtype: typeof raw.dtype === 'string' && raw.dtype.length > 0 ? raw.dtype : 'q8',
+    ...(Number.isSafeInteger(raw.maxTokens) && raw.maxTokens > 0
+      ? { maxTokens: raw.maxTokens } : {}),
+    ...(typeof raw.family === 'string' && raw.family.length > 0
+      ? { family: raw.family } : {}),
+    ...(typeof raw.note === 'string' ? { note: raw.note } : {}),
+  });
+  if (raw.unknownAdapter === true && typeof raw.dtype !== 'string') {
+    return { ...adapter, unknownAdapter: true };
+  }
+  return adapter;
+}
+
+/**
+ * Resolve a model alias, a registered id, or an explicit adapter descriptor
+ * into a usable ModelAdapter.
+ *
+ * - alias (`e5-base`) → the registered adapter;
+ * - registered repo id (± `@revision`) → the owning registered adapter;
+ * - an object descriptor → validated explicit adapter (advanced/library use);
+ * - ANY OTHER raw id → a NEUTRAL adapter flagged `unknownAdapter: true`. It is
+ *   NOT guessed to be E5-compatible; it keeps the index readable (load/check
+ *   only need id/revision/dim) but FAILS with an actionable message at embed
+ *   time until the caller supplies an explicit adapter (issue #60).
+ *
+ * @param {string|Partial<ModelAdapter>} [name]
+ * @returns {ModelAdapter}
  */
 export function resolveModel(name) {
-  if (!name) return MODELS[DEFAULT_MODEL];
-  if (MODELS[name]) return MODELS[name];
-  // Allow passing a raw HF/Xenova id; assume E5-style prefixes unless it's bge.
-  const isBge = /bge/i.test(name);
+  if (name === undefined || name === null || name === '') {
+    return withDim(MODELS[DEFAULT_MODEL]);
+  }
+  if (typeof name === 'object' && !Array.isArray(name)) {
+    return normalizeAdapter(name);
+  }
+  if (typeof name !== 'string') {
+    throw new Error(`model must be an alias, id, or adapter object — got ${typeof name}`);
+  }
+  if (MODELS[name]) return withDim(MODELS[name]);
+
+  // id@revision split; default revision "main" (issue #27 keeps it in the key).
   let id = name;
   let revision = 'main';
   const at = name.indexOf('@');
-  if (at > 0) {
+  const hasExplicitRevision = at > 0;
+  if (hasExplicitRevision) {
     id = name.slice(0, at);
-    revision = name.slice(at + 1) || 'main';
+    const requested = name.slice(at + 1);
+    revision = requested === '' ? 'main' : requested;
   }
-  return {
+  const alias = aliasByRepoId.get(id);
+  if (alias !== undefined) {
+    const registered = MODELS[alias];
+    const resolved = hasExplicitRevision ? { ...registered, revision } : registered;
+    return withDim(resolved);
+  }
+  // Unknown repo id: neutral, explicit-config-required adapter.
+  return normalizeAdapter({
     id,
-    revision,
+    ...(revision !== 'main' ? { revision } : {}),
+    pooling: 'none',
+    normalize: false,
+    nativeDim: 0,
     dim: 0,
+    unknownAdapter: true,
+  });
+}
+
+/**
+ * The subset of adapter fields that change the produced vectors and therefore
+ * participate in the adapter fingerprint. Kept as its own structural type so
+ * both registered adapters and legacy pre-profile descriptors can be hashed
+ * without requiring a full `ModelAdapter`.
+ * @typedef {Object} FingerprintInput
+ * @property {string} [queryPrefix]
+ * @property {string} [passagePrefix]
+ * @property {Pooling} [pooling]
+ * @property {boolean} [normalize]
+ * @property {number} [dim]
+ * @property {number} [nativeDim]
+ */
+
+/**
+ * Hash the vector-producing adapter semantics independently of model weights.
+ * Model id and revision remain in the existing persisted `model` identity.
+ *
+ * The hashed fields are EXACTLY those that change the produced vectors:
+ * formatting prefixes, pooling, normalization, and dimension. This hashing
+ * contract is stable (`adapter-v1`): normalizing default fields in a registered
+ * adapter must NOT change the bytes, so existing schema-v3 indexes and
+ * checkpoints built with E5/BGE keep their vectors reusable.
+ *
+ * @param {FingerprintInput} model
+ */
+export function embeddingAdapterFingerprint(model) {
+  const semantics = [
+    'embedding-adapter-v1',
+    `query-prefix:${model.queryPrefix ?? ''}`,
+    `passage-prefix:${model.passagePrefix ?? ''}`,
+    `pooling:${model.pooling ?? 'mean'}`,
+    `normalize:${model.normalize !== false}`,
+    `dimension:${model.nativeDim ?? model.dim ?? 0}`,
+  ].join('\u0000');
+  return `adapter-v1:${crypto.createHash('sha256').update(semantics).digest('hex')}`;
+}
+
+/**
+ * Adapter semantics used before registered model profiles (#50): the generic
+ * E5-style prefixes + mean pooling that once applied to every raw id (except a
+ * heuristic `bge` name match). Kept so pre-profile indexes remain readable and
+ * re-usable (see indexer `adapterCompatible`).
+ * @param {{id:string, dim:number, nativeDim?:number}} model
+ */
+export function legacyEmbeddingAdapterFingerprint(model) {
+  const isBge = /bge/i.test(model.id);
+  return embeddingAdapterFingerprint({
+    nativeDim: model.nativeDim ?? model.dim,
     queryPrefix: isBge ? '' : 'query: ',
     passagePrefix: isBge ? '' : 'passage: ',
-    note: 'Custom model id.',
-  };
+    pooling: 'mean',
+    normalize: true,
+  });
 }

package/src/rerank.mjs

@@ -0,0 +1,75 @@
+// @ts-check
+/**
+ * Cross-encoder re-ranking (issue #15).
+ *
+ * The first-pass ranking (cosine + RRF) is shallow: it scores a query against
+ * chunk *embeddings* independently. A cross-encoder feeds the query AND the
+ * passage into one transformer together, capturing pairwise relevance that
+ * bi-encoder cosine can miss — at the cost of a forward pass per candidate.
+ *
+ * `Xenova/bge-reranker-base` is an `XLMRobertaForSequenceClassification` with a
+ * SINGLE output class. Its raw logit IS the relevance score — that's exactly
+ * what BAAI's own FlagReranker returns (`model(...).logits.view(-1)`). Because
+ * of the single class we must NOT route this through the `text-classification`
+ * pipeline: it applies softmax, and softmax over one class is always 1.0 —
+ * useless. Hence the direct AutoModel + AutoTokenizer call below, with the
+ * query as `text` and the passage as `text_pair` (the cross-encoder input
+ * format).
+ */
+
+import { resolveSessionOptions } from './core.mjs';
+
+const _rerankers = new Map();
+
+export const RERANK_MODEL = 'Xenova/bge-reranker-base';
+
+/**
+ * Lazily load (and cache) the cross-encoder reranker. Nothing is loaded until
+ * the first actual re-rank, so `--rerank` costs nothing when not requested.
+ * @param {string} cacheDir
+ * @param {boolean} [offline=false] - never touch the network; require a cached model
+ * @returns {Promise<{tokenizer: import('@huggingface/transformers').PreTrainedTokenizer,
+ *   model: import('@huggingface/transformers').PreTrainedModel}>}
+ */
+export async function getReranker(cacheDir, offline = false) {
+  const sessionOptions = resolveSessionOptions();
+  const sessionKey = sessionOptions ? JSON.stringify(sessionOptions) : 'default';
+  const key = `${RERANK_MODEL}|${offline ? 'off' : 'on'}|${sessionKey}`;
+  if (_rerankers.has(key)) return _rerankers.get(key);
+  const { AutoModelForSequenceClassification, AutoTokenizer, env } =
+    await import('@huggingface/transformers');
+  if (cacheDir) env.cacheDir = cacheDir;
+  env.allowRemoteModels = !offline;
+  const tokenizer = await AutoTokenizer.from_pretrained(RERANK_MODEL);
+  // q8: the repo ships onnx/model_quantized.onnx (~1/4 of fp32). Same trade as
+  // the embedding extractor in core.mjs — near-identical scores, 4x smaller.
+  /** @type {Record<string, unknown>} */
+  const loadOpts = {
+    dtype: 'q8',
+    ...(sessionOptions ? { session_options: sessionOptions } : {}),
+  };
+  const model = await AutoModelForSequenceClassification.from_pretrained(RERANK_MODEL, loadOpts);
+  const r = { tokenizer, model };
+  _rerankers.set(key, r);
+  return r;
+}
+
+/**
+ * Score query↔passage relevance with the cross-encoder. Returns one raw logit
+ * per passage (higher = more relevant). Passages are NOT embedded: each
+ * (query, passage) pair runs through the model together, batched.
+ * @param {string} query
+ * @param {string[]} passages
+ * @param {string} cacheDir
+ * @param {boolean} [offline=false] - never touch the network; require a cached model
+ * @returns {Promise<number[]>}
+ */
+export async function rerankScores(query, passages, cacheDir, offline = false) {
+  if (passages.length === 0) return [];
+  const { tokenizer, model } = await getReranker(cacheDir, offline);
+  const queries = new Array(passages.length).fill(query);
+  const inputs = tokenizer(queries, { text_pair: passages, padding: true, truncation: true });
+  const outputs = await model(inputs);
+  // Single-class head → logits shape [batch, 1]; the logit is the relevance score.
+  return outputs.logits.tolist().map((row) => /** @type {number} */ (row[0]));
+}