Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
3.4 KB
Raw Blame
/**
 * #5691 / #3783: the opt-in query instruction for instruction-style embedding
 * models. `embedding_query_prefix` lives in the brain's database config
 * (`gbrain config set embedding_query_prefix …`), so every mounted brain uses
 * its own value. Search reads it once per request and threads the exact bytes
 * to the query embedding and the query-cache key; keyword search and stored
 * document vectors never see it, and the gateway's global state is untouched.
 * There is no default: nothing is guessed from the model id at query time.
 */
import type { BrainEngine } from '../engine.ts';
import { embedQuery } from '../embedding.ts';

export const EMBEDDING_QUERY_PREFIX_KEY = 'embedding_query_prefix';

export async function loadEmbeddingQueryPrefix(engine: BrainEngine): Promise<string> {
  if (typeof engine.getConfig !== 'function') return '';
  try {
    return (await engine.getConfig(EMBEDDING_QUERY_PREFIX_KEY)) ?? '';
  } catch {
    return '';
  }
}

/**
 * #3783: the query-side embedding for callers outside hybrid search (think,
 * takes, CRAG escalation, auto-think, search diagnose, eval's vector
 * baseline). It loads the selected brain's prefix and embeds with the
 * unbounded `embedQuery`, so each call site keeps its own deadline behavior;
 * hybrid search keeps its bounded `embedQueryBounded`. Every query embed
 * outside these two paths is a bug the call-site guard
 * (test/query-embed-call-sites.test.ts) refuses.
 */
export async function embedQueryWithPrefix(
  engine: BrainEngine,
  text: string,
  opts?: { embeddingModel?: string; dimensions?: number },
): Promise<Float32Array> {
  const queryPrefix = await loadEmbeddingQueryPrefix(engine);
  return embedQuery(text, { ...(opts ?? {}), ...(queryPrefix ? { queryPrefix } : {}) });
}

/** Model families whose model cards ask for a query instruction, with the documented value. */
const QUERY_PREFIX_FAMILIES: ReadonlyArray<{ family: string; pattern: RegExp; value: string }> = [
  { family: 'Qwen3-Embedding', pattern: /qwen3[-_]?embed/,
    value: 'Instruct: Given a web search query, retrieve relevant passages that answer the query\nQuery:' },
  { family: 'e5', pattern: /(^|[/:_-])(multilingual-)?e5([-_.]|$)/, value: 'query: ' },
  { family: 'BGE', pattern: /(^|[/:_-])bge-(?!m3)/, value: 'Represent this sentence for searching relevant passages: ' },
  { family: 'nomic-embed', pattern: /nomic-embed/, value: 'search_query: ' },
  // PR #6062 (query half, @xorets): the model card's retrieval task prompt; the document-side `title: … | text: …`
  // formatting is a per-model document transform and stays a tracked feature, not a prefix.
  { family: 'EmbeddingGemma', pattern: /embeddinggemma/, value: 'task: search result | query: ' },
];

export function suggestedQueryPrefix(embeddingModel: string): { family: string; value: string } | null {
  const id = embeddingModel.toLowerCase();
  const match = QUERY_PREFIX_FAMILIES.find(f => f.pattern.test(id));
  return match ? { family: match.family, value: match.value } : null;
}

/** A POSIX-shell argument that reproduces `value` byte for byte (ANSI-C quoting when it holds a newline). */
export function shellQuoteConfigValue(value: string): string {
  if (/[\n\r\t]/.test(value)) {
    return `$'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, '\\n').replace(/\r/g, '\\r').replace(/\t/g, '\\t')}'`;
  }
  return `"${value.replace(/(["\\$`])/g, '\\$1')}"`;
}