Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
14.2 KB
Raw Blame
/**
 * Read-only search-mode dashboard builder — moved from src/commands/search.ts
 * in the CLI→MCP gap-closure wave so the `search_modes` op and the CLI render
 * the same report. Pure reads: never mutates config (the `modes --reset` lane
 * stays in the command file).
 */

import type { BrainEngine } from '../engine.ts';
import { semanticResultCacheAvailable } from './query-cache.ts';
import {
  MODE_BUNDLES,
  SEARCH_MODE_CONFIG_KEYS,
  loadSearchModeConfig,
  resolveSearchMode,
  attributeKnob,
  type SearchMode,
  type ModeBundle,
} from './mode.ts';
import { describeRerankerFix } from '../ai/reranker-readiness.ts';
import { rerankerReadinessForEngine } from '../ai/reranker-readiness-engine.ts';

export const KNOB_DESCRIPTIONS: Record<keyof ModeBundle, string> = {
  cache_enabled: 'Semantic query cache on/off',
  cache_similarity_threshold: 'Cosine-similarity floor for cache hits (0..1)',
  cache_ttl_seconds: 'Per-row cache TTL',
  intentWeighting: 'Zero-LLM intent classifier weight adjustments',
  keywordOrFallback: 'Keyword-arm AND→OR zero-recall fallback',
  tokenBudget: 'Per-call token-budget cap (undefined = no cap)',
  expansion: 'LLM multi-query expansion: the `query` default when `expand` is unset (`search` never expands)',
  expansion_variant_budget: 'Total RRF weight shared by expansion variant lists (null = legacy weight 1 each; (0, 4])',
  searchLimit: 'Default `limit` for the operation layer',
  reranker_enabled: 'Cross-encoder reranker on/off',
  reranker_model: 'Provider:model for the reranker',
  reranker_top_n_in: 'Candidates sent to reranker per call',
  reranker_top_n_out: 'Cap on reranked output (null = no truncate)',
  reranker_timeout_ms: 'HTTP timeout for the reranker call',
  floor_ratio: 'Floor-ratio gate for metadata boosts (0..1, undefined = off)',
  title_boost: 'Title-phrase boost multiplier (query is a title token-run; 1.0 = off)',
  // v0.46.15 retrieval wave knobs
  evidence_cosine_floor: 'Cosine floor for evidence high_vector_match; also decides the rerank gate grade (0..1)',
  // W3 confidence-gated reranking
  reranker_gate: 'Confidence-gated reranking: off, or shadow (grade before the reranker, stamp meta.rerank_gate, still rerank)',
  reranker_gate_min_gap: 'Rerank gate δ: cosine margin rank-1 needs over the best other page to count as a strong vector match (0..1, 0.05 default)',
  autocut_min_top: 'Weak-top floor — autocut no-ops when the top score is below this (0 disables)',
  // v0.36 cross-modal knobs (D3 registry)
  cross_modal_both_text_weight: "D6 'both'-mode RRF weight for text branch (0.6 default)",
  cross_modal_both_image_weight: "D6 'both'-mode RRF weight for image branch (0.4 default)",
  image_query_text_refinement_weight: 'D13 searchByImage text-refinement RRF weight (0.4 default)',
  image_query_image_refinement_weight: 'D13 searchByImage image branch RRF weight (0.6 default)',
  unified_multimodal: 'Phase 3 — route all queries through embedding_multimodal column',
  unified_multimodal_only: 'Phase 3 strict — bypass dual-column fallback when unified is on',
  cross_modal_llm_intent: 'Commit 4 — Haiku tie-break for ambiguous modality classification',
  // v0.40.4 graph signals
  graph_signals: 'Selective graph signals: adjacency hub + cross-source hub + session diversification',
  // v0.40.3.0 contextual retrieval
  contextual_retrieval: 'CR tier (none|title|per_chunk_synopsis) — wraps chunks at embed time',
  contextual_retrieval_disabled: 'Soft kill switch — neutralizes CR wrapping for queries + new embeds',
  // v0.42.3.0 autocut
  autocut: 'Score-discontinuity result-sizing (cuts at the rerank-score cliff; no-op without a reranker)',
  autocut_jump: 'Autocut sensitivity: min normalized score gap that counts as a cliff (0..1, 0.20 default)',
  autocut_min_keep: 'Autocut floor: never trim the returned set below this many results (integer >= 1, 1 default)',
  // v0.43 relational recall
  relationalRetrieval: 'Typed-edge relational recall arm (relational queries walk the graph; no-op otherwise)',
  relational_retrieval_depth: 'Max hops for relational traversal (1..3, 2 default)',
  relational_rerank_pin: 'Relational-arm rows re-pinned above reranked text rows in fused order (0 = off; 0..10, 3 default)',
  relational_planner: 'Multi-hop planner: questions chaining 2-3 typed relations walk typed hop chains with evidence (also keyless recall)',
  relational_orient_onehop: 'Typed one-hop walks read edges written on either page by the relation type signature (opt-in; null = follow relational_planner)',
  relational_chain_slots: 'When a multi-hop chain fired, up to this many chain rows (answers, then evidence pages) lead page 1 (0..10; 0 = single evidence slot)',
  collapse: 'Result-time collapse: same-slug twins in other sources, redirect stubs and copies of one document fold into the best row (listed in collapsed)',
  rank_priors: 'Rank priors after the reranker: organization over person when no person is named, weak OCR matches, dated over undated rows on when-questions',
  keyword_phrase: 'Keyword phrase factor (opt-in): a chunk holding the query as one contiguous phrase ranks higher in the keyword arm',
  qualified_aliases: 'Qualified alias hop (opt-in): a 3-6 word phrase inside the query that is the alias of exactly one readable page leads with that page',
  title_qualified: 'Qualified title boost (opt-in): a person or company title mentioned inside a longer query gets the title boost',
  diverse_pool_depth: 'Session-diverse pool before the reranker: each arm fetches at least N candidates, one row per session, the reranker reads at least N (0..100; 0 = off)',
  // Ranker wave (Phase E2) arm-confidence fusion
  keyword_arm_confidence_floor: 'Keyword-arm confidence floor: below this margin ratio the keyword + title lists fuse at half weight (null = off; (0, 1])',
  // Ranker wave (Phase E3) metadata boost gate
  metadata_boost_gate: 'Post-fusion metadata boosts (backlink/salience/recency/graph/alias): always, or lexical = only when a keyword/title/relational row fused',
};

/**
 * Knobs whose legitimate `null` has a meaning of its own. The text renderer
 * used to print `String(value ?? '(undefined)')`, so `expansion_variant_budget`
 * at its bundle default (null = legacy weighting) rendered as `(undefined)` —
 * indistinguishable from an unset knob. Null now renders distinctly; plain
 * `(undefined)` stays reserved for knobs that are genuinely unset.
 */
export const KNOB_NULL_LABELS: Partial<Record<keyof ModeBundle, string>> = {
  expansion_variant_budget: 'legacy (null)',
  reranker_top_n_out: 'no truncate (null)',
  keyword_arm_confidence_floor: 'off (null)',
};

/** Render one resolved knob value for the human `gbrain search modes` table. */
export function formatKnobValue(knob: string, value: unknown): string {
  if (value === undefined) return '(undefined)';
  if (value === null) return KNOB_NULL_LABELS[knob as keyof ModeBundle] ?? '(null)';
  return String(value);
}

/**
 * #4604: honest scope note carried on every report. The dashboard resolves
 * the BRAIN-LEVEL planes (config override > mode bundle); per-call
 * SearchOpts overrides on individual searches are not represented here —
 * a live search that passes its own knobs can legitimately differ from
 * this report for that one call. The `expansion` row is `query`'s default
 * when a call leaves `expand` unset, and `search` never expands; say so here,
 * on the surface operators actually read, so the dashboard answers for the
 * primary agent verb.
 */
export const MODES_REPORT_PER_CALL_NOTE =
  'Resolved from config overrides + the active mode bundle. Per-call SearchOpts ' +
  'overrides on individual searches are not shown — a call that passes its own ' +
  'knobs (e.g. expand, autocut, relational) wins for that call only. The `query` ' +
  'op expands when the resolved `expansion` row below is on (off in every ' +
  'mode by default; `search.expansion` overrides it) unless the call passes `expand` ' +
  '(`--expand` / `expand: true` forces it, `--no-expand` / `expand: false` ' +
  'skips it), while `search` never expands. Expansion needs configured embedding and expansion ' +
  'providers; requested expansion is not proof a provider ran. A configured ' +
  'cloud expander receives the query and may charge for the call.';

export interface SearchModesReport {
  schema_version: 2;
  active_mode: SearchMode;
  active_mode_valid: boolean;
  resolved: Record<keyof ModeBundle, { value: unknown; source: string; source_detail: string; description: string }>;
  bundles: Record<SearchMode, ModeBundle>;
  config_keys: ReadonlyArray<string>;
  /**
   * v0.48.2 — is the RESOLVED reranker actually going to run? Same predicate
   * doctor's `reranker_health` and init use (`reranker-readiness.ts`), fed the
   * file-plane + process env. Absent only when readiness itself threw.
   */
  reranker_readiness?: RerankerReadinessReport;
  /**
   * #8744: when the configured contextual-retrieval tier is per_chunk_synopsis,
   * how many chunks actually carry synopsis vectors (import and sync embed at
   * the title tier; the sweep is `gbrain reindex --synopsis`). Brain-wide
   * counts, so ABSENT on the remote surface.
   */
  synopsis_coverage?: SynopsisCoverageReport;
  /** #4604: what this report does NOT include (per-call plane). */
  per_call_note: string;
  _meta?: {
    metric_glossary?: Record<string, string>;
  };
}

export interface SynopsisCoverageReport {
  eligible_pages: number;
  eligible_chunks: number;
  synopsis_pages: number;
  synopsis_chunks: number;
  coverage_pct: number | null;
  large_title_pages: number;
  line: string;
  fix: string;
}

export interface RerankerReadinessReport {
  model: string;
  enabled: boolean;
  ready: boolean;
  /** Env var the reranker needs; ABSENT on the remote (MCP) surface — see redactReadinessForRemote. */
  required_key?: string | null;
  /** ABSENT on the remote surface (host key inventory is not for untrusted callers). */
  key_present?: boolean;

  self_hosted: boolean;
  /** Paste-ready fix when not ready; null when ready; ABSENT on the remote surface (it names the key). */
  fix?: string | null;
}

/**
 * Remote (untrusted MCP) callers get the readiness verdict without the host's
 * provider-key inventory: which env vars exist on the machine is
 * fingerprinting data, and the paste-ready fix names them. `ready` stays —
 * it is observable anyway (reranked results carry `rerank_score`).
 */
export function redactReadinessForRemote(report: SearchModesReport): SearchModesReport {
  const rr = report.reranker_readiness;
  if (!rr) return report;
  // self_hosted is deployment topology (a private base-URL override exists) —
  // not needed for the verdict, so it stays local too.
  const { model, enabled, ready } = rr;
  const { synopsis_coverage: _brainWide, ...rest } = report;
  return { ...rest, reranker_readiness: { model, enabled, ready, self_hosted: false } };
}

export async function buildModesReport(engine: BrainEngine): Promise<SearchModesReport> {
  const input = await loadSearchModeConfig(engine);
  const resolved = resolveSearchMode(input);

  // #4604: derive the knob list from KNOB_DESCRIPTIONS (a Record over
  // EVERY ModeBundle key, so the type system forces a description — and
  // therefore a dashboard row — for each new knob). The previous literal
  // array hardcoded 12 of the bundle's knobs, leaving live overrides like
  // search.reranker.* and search.relational_retrieval invisible here while
  // they steered every real search.
  const knobs = Object.keys(KNOB_DESCRIPTIONS) as Array<keyof ModeBundle>;

  const attributions = {} as SearchModesReport['resolved'];
  for (const k of knobs) {
    const a = attributeKnob(k, input, resolved);
    attributions[k] = {
      value: a.value,
      source: a.source,
      source_detail: a.source_detail,
      description: KNOB_DESCRIPTIONS[k],
    };
  }

  if (!semanticResultCacheAvailable()) {
    attributions.cache_enabled = {
      ...attributions.cache_enabled,
      value: false,
      source: 'availability',
      source_detail: 'Semantic result caching is temporarily disabled; configured settings are retained.',
    };
  }

  let reranker_readiness: SearchModesReport['reranker_readiness'];
  try {
    // Same plane the CLI hands the gateway (env > file > DB-plane provider
    // keys + provider_base_urls) — shared with doctor's reranker_health via
    // rerankerReadinessForEngine so the two surfaces cannot drift.
    const { readiness: r } = await rerankerReadinessForEngine(engine, resolved.reranker_model);
    reranker_readiness = {
      model: r.model,
      enabled: resolved.reranker_enabled,
      ready: r.ready,
      required_key: r.requiredKey,
      key_present: r.keyPresent,
      self_hosted: r.selfHosted,
      fix: describeRerankerFix(r),
    };
  } catch (e) {
    // Never vanish silently — the user asking "is my reranker running" gets a
    // verdict line either way.
    reranker_readiness = {
      model: resolved.reranker_model,
      enabled: resolved.reranker_enabled,
      ready: false,
      required_key: null,
      key_present: false,
      self_hosted: false,
      fix: `readiness check failed: ${e instanceof Error ? e.message : String(e)} — run gbrain doctor`,
    };
  }

  let synopsis_coverage: SynopsisCoverageReport | undefined;
  try {
    const sweep = await import('../synopsis-sweep.ts');
    const c = await sweep.readSynopsisCoverage(engine);
    if (c.config.configured) {
      synopsis_coverage = { eligible_pages: c.eligible_pages, eligible_chunks: c.eligible_chunks, synopsis_pages: c.synopsis_pages,
        synopsis_chunks: c.synopsis_chunks, coverage_pct: c.coverage_pct, large_title_pages: c.large_title_pages,
        line: sweep.formatSynopsisCoverageLine(c), fix: sweep.SYNOPSIS_SWEEP_ARGV.join(' ') };
    }
  } catch { /* coverage is advisory; the doctor check synopsis_tier_coverage reports read failures */ }

  return {
    schema_version: 2,
    active_mode: resolved.resolved_mode,
    active_mode_valid: resolved.mode_valid,
    resolved: attributions,
    ...(reranker_readiness ? { reranker_readiness } : {}),
    ...(synopsis_coverage ? { synopsis_coverage } : {}),
    bundles: {
      conservative: { ...MODE_BUNDLES.conservative },
      balanced: { ...MODE_BUNDLES.balanced },
      tokenmax: { ...MODE_BUNDLES.tokenmax },
    },
    config_keys: SEARCH_MODE_CONFIG_KEYS,
    per_call_note: MODES_REPORT_PER_CALL_NOTE,
  };
}