Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
14.8 KB
Raw Blame
/**
 * v0.40.4.0 — `gbrain search --explain` per-stage attribution formatter.
 *
 * Renders a SearchResult[] as a multi-line per-result breakdown of how
 * the final score was formed. Reads the boost_* / base_score / *_hits
 * fields populated by every boost stage (T6 stamp + T4 graph signals).
 *
 * Output shape per result:
 *
 *   1. people/alice-example (score=12.4)
 *      base=10.2 (rrf+cosine)
 *      + backlink ×1.08 (12 inbound)            ← when backlink_boost > 1
 *      + salience ×1.05 (mattering)             ← when salience_boost > 1
 *      + recency  ×1.00 (no decay applied)      ← when recency_boost > 1
 *      + exact-match ×1.50                      ← when exact_match_boost > 1
 *      + title-mention ×1.25                    ← when title_mention_boost > 1
 *      + adjacency ×1.05 (hits=3)               ← when graph_adjacency_boost set
 *      + cross_source ×1.10 (other_sources=2)   ← when graph_cross_source_boost set
 *      - session_demote ×0.95 (prefix=chat/x)   ← when session_demote_factor set
 *      ↑ reranker rank +2 (head improved)       ← when reranker_delta > 0
 *      ↓ reranker rank -1 (head moved down)     ← when reranker_delta < 0
 *      = final 12.4
 *
 * Empty path: when no stage stamped anything, prints
 *   "no boosts applied" + "= final {score}".
 *
 * JSON envelope: the same SearchResult fields are surfaced verbatim in
 * the existing `--json` output (operations layer JSON.stringify); no
 * separate JSON formatter needed.
 */

import type { SearchResult, HybridSearchMeta } from '../types.ts';
import type { DeliveryMeta } from './evidence-delivery.ts';
import type { AutocutDecision } from './autocut.ts';
import { formatTimingsSummary, type SearchTimingsMeta } from './stage-timings.ts';

/**
 * Format a single result with per-stage attribution. Returns a string
 * (multi-line, no trailing newline; caller joins with '\n' if rendering
 * many).
 */
export function formatResultExplain(
  result: SearchResult,
  rank: number,  // 1-based for human display
): string {
  const lines: string[] = [];
  lines.push(`${rank}. ${result.slug} (score=${fmt(result.score)})`);

  // base_score is the pre-boost RRF+cosine result. When undefined
  // (result wasn't routed through runPostFusionStages), fall back to
  // final score and label "no boosts applied" downstream.
  const base = result.base_score ?? result.score;
  // Which retrieval arm instances found this row, at what rank, and their
  // RRF contribution (page votes on the lead chunk, own votes otherwise).
  if (result.rrf && result.rrf.arms.length > 0) {
    const found = result.rrf.arms.map(v => `${v.arm} #${v.rank + 1} (+${fmt(v.contribution)})`).join(', ');
    lines.push(`   found by: ${found}`);
  }
  lines.push(`   base=${fmt(base)} (rrf+cosine)`);
  // v0.46.15: raw query↔chunk cosine (the calibrated semantic signal evidence
  // keys off). Absent on keyword-only / no-embedding paths.
  if (typeof result.cosine === 'number') {
    lines.push(`   cosine=${fmt(result.cosine)} (raw query↔chunk similarity)`);
  }

  let anyBoost = false;

  if (result.backlink_boost !== undefined && result.backlink_boost !== 1.0) {
    anyBoost = true;
    const inbound = result.backlink_count !== undefined ? ` (${result.backlink_count} inbound)` : '';
    lines.push(`   + backlink ×${fmt(result.backlink_boost)}${inbound}`);
  }
  if (result.salience_boost !== undefined && result.salience_boost !== 1.0) {
    anyBoost = true;
    lines.push(`   + salience ×${fmt(result.salience_boost)}`);
  }
  if (result.recency_boost !== undefined && result.recency_boost !== 1.0) {
    anyBoost = true;
    lines.push(`   + recency  ×${fmt(result.recency_boost)}`);
  }
  if (result.exact_match_boost !== undefined && result.exact_match_boost !== 1.0) {
    anyBoost = true;
    lines.push(`   + exact-match ×${fmt(result.exact_match_boost)}`);
  }
  if (result.title_mention_boost !== undefined && result.title_mention_boost !== 1.0) {
    anyBoost = true;
    lines.push(`   + title-mention ×${fmt(result.title_mention_boost)}`);
  }
  if (result.graph_adjacency_boost !== undefined) {
    anyBoost = true;
    const hits = result.graph_adjacency_hits ?? '?';
    lines.push(`   + adjacency ×${fmt(result.graph_adjacency_boost)} (hits=${hits})`);
  }
  if (result.graph_cross_source_boost !== undefined) {
    anyBoost = true;
    const cs = result.graph_cross_source_hits ?? '?';
    lines.push(`   + cross_source ×${fmt(result.graph_cross_source_boost)} (other_sources=${cs})`);
  }
  if (result.session_demote_factor !== undefined) {
    anyBoost = true;
    const prefix = result.graph_session_prefix ?? '?';
    lines.push(`   - session_demote ×${fmt(result.session_demote_factor)} (prefix=${prefix})`);
  }
  if (result.feedback_boost !== undefined && result.feedback_boost !== 1.0) {
    anyBoost = true;
    lines.push(`   + feedback ×${fmt(result.feedback_boost)} (use-attributed ratings)`);
  }
  if (result.reranker_delta !== undefined && result.reranker_delta !== 0) {
    anyBoost = true;
    const arrow = result.reranker_delta > 0 ? '↑' : '↓';
    lines.push(`   ${arrow} reranker rank ${result.reranker_delta > 0 ? '+' : ''}${result.reranker_delta}`);
  }
  // v0.42.3.0 — show the cross-encoder rerank score (the signal autocut cuts
  // on). Surfacing it per result makes the autocut cliff legible: every kept
  // result sits at or above the cut threshold.
  if (result.rerank_score !== undefined) {
    anyBoost = true;
    lines.push(`   • rerank score=${fmt(result.rerank_score)}`);
  }

  if (!anyBoost) {
    lines.push(`   no boosts applied`);
  }

  lines.push(`   = final ${fmt(result.score)}`);
  // Evidence delivery: the unit this result was delivered as, and under auto why.
  const d = result.delivered;
  if (d) {
    const why = [d.reason, d.fallback_reason ? `fallback ${d.fallback_reason}` : null].filter(Boolean).join(', ');
    lines.push(`   evidence: ${d.unit}${why ? ` (${why})` : ''}${d.truncated ? ', truncated' : ''}`);
  }
  return lines.join('\n');
}

/**
 * v0.42.3.0 — one-line autocut summary for `--explain`. Returns null when
 * autocut didn't run (no decision in meta) so callers can omit it cleanly.
 */
export function formatAutocutSummary(decision: AutocutDecision | undefined): string | null {
  if (!decision) return null;
  if (!decision.applied) {
    return `autocut: no cut (signal=${decision.signal}, gap=${fmt(decision.gapRatio)} < threshold) — full ${decision.total} returned`;
  }
  return `autocut: cut at the rerank cliff (gap=${fmt(decision.gapRatio)}) — kept ${decision.kept}/${decision.total}`;
}

/**
 * v0.48.2 — one-line degraded summary for `--explain` (null when the run was
 * clean). Reads the closed `degraded[]` vocabulary, e.g.
 * `degraded: reranker_skipped (no_key)` — the only place a silently skipped
 * reranker is visible from the CLI.
 */
export function formatDegradedSummary(degraded: HybridSearchMeta['degraded'] | undefined): string | null {
  if (!degraded || degraded.length === 0) return null;
  return `degraded: ${degraded.map((d) => (d.reason ? `${d.stage} (${d.reason})` : d.stage)).join(', ')}`;
}

/**
 * W3 — one-line rerank gate summary for `--explain` (null when the gate is
 * off, so gate-off explain output is byte-identical).
 */
export function formatRerankGateSummary(gate: HybridSearchMeta['rerank_gate'] | undefined): string | null {
  if (!gate) return null;
  if (!gate.eligible) return `rerank gate (${gate.mode}): not graded (${gate.ineligible_reason})`;
  const signal = [
    gate.top_cosine !== undefined ? `cosine ${fmt(gate.top_cosine)}` : null,
    gate.gap !== undefined ? `gap ${fmt(gate.gap)}` : null,
    `${gate.candidates} candidates`,
  ].filter(Boolean).join(', ');
  const verdict = gate.would_skip ? 'would skip' : gate.skip_blocked ? `would rerank (${gate.skip_blocked})` : 'would rerank';
  return `rerank gate (${gate.mode}): ${gate.grade} ${gate.reason} — ${verdict} (${signal})`;
}

/** One-line evidence-delivery summary for `--explain` (null when the stage did not run). */
export function formatDeliverySummary(delivery: DeliveryMeta | undefined): string | null {
  if (!delivery) return null;
  const fallbacks = delivery.fallbacks.length > 0 ? `; fallbacks: ${delivery.fallbacks.join(', ')}` : '';
  const dropped = delivery.dropped > 0 ? `; dropped ${delivery.dropped} (${Object.entries(delivery.dropped_reasons).map(([k, v]) => `${k}=${v}`).join(', ')})` : '';
  return `evidence: ${delivery.applied_unit} — ${delivery.blocks} blocks, ${delivery.budget_used}/${delivery.budget_tokens} tokens (${delivery.tokenizer})${dropped}${fallbacks}`;
}

/**
 * System One: one line per slot that ran in shadow or on (null when none did,
 * so all-off explain output is byte-identical).
 */
export function formatDecideSummary(decide: HybridSearchMeta['decide'] | undefined): string | null {
  if (!decide) return null;
  const lines = Object.entries(decide).filter(([, m]) => m).map(([slot, m]) => {
    const mode = m!.effective === m!.mode ? m!.mode : `${m!.mode} (inactive: ${m!.skipped ?? 'unknown'})`;
    const who = m!.provider ? ` — ${m!.provider}${m!.model_resolved ? ` (resolved ${m!.model_resolved})` : ''}` : '';
    const parts: string[] = [];
    if (m!.answer) parts.push(m!.answer);
    if (m!.judged !== undefined) parts.push(`judged ${m!.judged}`);
    if (m!.threshold !== undefined) parts.push(`threshold ${fmt(m!.threshold)}`);
    if (m!.outcomes) parts.push(Object.entries(m!.outcomes).map(([o, n]) => `${o} ${n}`).join(', '));
    if (m!.agreement) parts.push(`top-1 ${m!.agreement.top1 ? 'agrees' : 'differs'}, tau ${fmt(m!.agreement.kendall_tau)}`);
    if (m!.skipped && m!.effective === m!.mode) parts.push(`skipped: ${m!.skipped}`);
    return `decide ${slot}: ${mode}${who}${parts.length ? `; ${parts.join('; ')}` : ''}`;
  });
  return lines.length > 0 ? lines.join('\n') : null;
}

/**
 * Format a full result list. Caller passes the SearchResult[] directly;
 * the formatter handles enumeration. Returns a single string (multi-line
 * with trailing newline so callers can `process.stdout.write(out)`).
 */
export function formatResultsExplain(
  results: SearchResult[],
  meta?: HybridSearchMeta & { delivery?: DeliveryMeta; timings?: SearchTimingsMeta },
): string {
  if (results.length === 0) return 'No results.\n';
  const body = results.map((r, i) => formatResultExplain(r, i + 1)).join('\n\n') + '\n';
  // v0.42.3.0 — prepend the autocut summary when meta carries a decision;
  // v0.48.2 — and the degraded summary when any stage was skipped.
  const head = [formatAutocutSummary(meta?.autocut), formatDegradedSummary(meta?.degraded), formatRerankGateSummary(meta?.rerank_gate), formatDeliverySummary(meta?.delivery), formatDecideSummary(meta?.decide), formatTimingsSummary(meta?.timings)]
    .filter((l): l is string => l !== null);
  return head.length > 0 ? `${head.join('\n')}\n\n${body}` : body;
}

/** A ranking stage's state in score_details: it ran, was skipped (with why), or never ran on this path. */
export type StageState<T> = ({ state: 'applied' } & T) | { state: 'skipped' | 'not_run'; reason: string };

/** Stable per-result score breakdown returned by `search`/`query` with `explain: true`. */
export interface ScoreDetails {
  /** The row's final score. */
  final: number;
  /** Arm-instance votes; `rank` is 1-based for display, `fusion_rank` the 0-based rank RRF used. */
  arms: Array<{ arm: string; rank: number; fusion_rank: number; k: number; weight: number; contribution: number; vote: 'page' | 'chunk'; chunk_id?: number }>;
  rrf: StageState<{ raw: number; normalized: number; compiled_truth_boost: number }>;
  blend: StageState<{ rrf_weight: number; norm_rrf: number; cosine_weight: number; cosine: number }>;
  /** Score entering the post-fusion boost stages. */
  base_score: number | null;
  /** Multiplicative factors applied after fusion, by stage (only stages that changed this row). */
  boosts: Record<string, { factor: number } & Record<string, unknown>>;
  rerank: StageState<{ score: number; delta: number | null; pinned: boolean }>;
}

/**
 * Pure projection of the stamps every ranking stage leaves on a row into one
 * stable object. Absent stamps become `not_run`/`skipped` states rather than
 * invented values, so the breakdown never claims a stage it did not observe.
 */
export function buildScoreDetails(result: SearchResult): ScoreDetails {
  const arms = (result.rrf?.arms ?? []).map(v => ({
    arm: v.arm, rank: v.rank + 1, fusion_rank: v.rank, k: v.k, weight: v.weight,
    contribution: v.contribution, vote: v.vote, ...(v.chunk_id !== undefined ? { chunk_id: v.chunk_id } : {}),
  }));
  const rrf: ScoreDetails['rrf'] = result.rrf
    ? { state: 'applied', raw: result.rrf.raw, normalized: result.rrf.normalized, compiled_truth_boost: result.rrf.compiled_truth_boost }
    : { state: 'not_run', reason: 'single_arm_path' };
  const blend: ScoreDetails['blend'] = result.blend_norm_rrf !== undefined && typeof result.cosine === 'number'
    ? { state: 'applied', rrf_weight: 0.7, norm_rrf: result.blend_norm_rrf, cosine_weight: 0.3, cosine: result.cosine }
    : { state: 'not_run', reason: 'no_query_embedding' };
  const boosts: ScoreDetails['boosts'] = {};
  const add = (name: string, factor: number | undefined, detail: Record<string, unknown> = {}) => {
    if (factor === undefined || factor === 1) return;
    const clean = Object.fromEntries(Object.entries(detail).filter(([, v]) => v !== undefined));
    boosts[name] = { factor, ...clean };
  };
  add('backlink', result.backlink_boost, { inbound: result.backlink_count });
  add('salience', result.salience_boost);
  add('recency', result.recency_boost);
  add('chronicle', result.chronicle_boost);
  add('title', result.title_match_boost);
  add('title_mention', result.title_mention_boost);
  add('adjacency', result.graph_adjacency_boost, { hits: result.graph_adjacency_hits });
  add('cross_source', result.graph_cross_source_boost, { other_sources: result.graph_cross_source_hits });
  add('session_demote', result.session_demote_factor, { prefix: result.graph_session_prefix });
  add('alias_resolved', result.alias_resolved_boost);
  add('supersede', result.supersede_penalty, { superseded_by: result.superseded_by });
  add('exact_match', result.exact_match_boost);
  const rerank: ScoreDetails['rerank'] = result.rerank_score !== undefined
    ? { state: 'applied', score: result.rerank_score, delta: result.reranker_delta ?? null, pinned: result.relational_pinned === true }
    : { state: 'not_run', reason: 'reranker_off_or_outside_head' };
  return { final: result.score, arms, rrf, blend, base_score: result.base_score ?? null, boosts, rerank };
}

/**
 * Compact number formatter. Drops trailing zeros for readability; 4
 * decimal places of precision is plenty for ranking scores (RRF lands
 * in the 0.01-0.05 band; backlink/salience boosts in the 1.0-1.6 band).
 */
function fmt(n: number): string {
  if (!Number.isFinite(n)) return String(n);
  // 4 decimals, then trim trailing zeros and an optional trailing dot.
  return n.toFixed(4).replace(/\.?0+$/, '');
}