Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* v0.40.4.0 — `gbrain search --explain` formatter.
*
* Pins output format for the per-stage attribution view. Stable shape so
* scripts that grep `--explain` output don't break under refactors.
*/
import { describe, test, expect } from 'bun:test';
import type { SearchResult } from '../../src/core/types.ts';
import {
formatResultExplain,
formatResultsExplain,
formatAutocutSummary,
formatDegradedSummary,
buildScoreDetails,
} from '../../src/core/search/explain-formatter.ts';
import type { AutocutDecision } from '../../src/core/search/autocut.ts';
function r(slug: string, score: number, extras: Partial<SearchResult> = {}): SearchResult {
return {
slug,
page_id: 1,
title: slug,
type: 'note',
chunk_text: `body of ${slug}`,
chunk_source: 'compiled_truth',
chunk_id: 1000,
chunk_index: 0,
score,
stale: false,
source_id: 'default',
...extras,
};
}
describe('formatResultExplain — no boosts', () => {
test('result with no attribution → "no boosts applied"', () => {
const out = formatResultExplain(r('a/b', 1.5), 1);
expect(out).toContain('1. a/b (score=1.5)');
expect(out).toContain('base=1.5 (rrf+cosine)');
expect(out).toContain('no boosts applied');
expect(out).toContain('= final 1.5');
});
test('base_score equals score when no stage stamped base_score', () => {
const out = formatResultExplain(r('a/b', 3.14), 1);
expect(out).toContain('base=3.14');
});
});
describe('formatResultExplain — every boost type', () => {
test('title_mention_boost (search.title_qualified) renders apart from the exact title boost', () => {
const res = r('people/alice-example', 1.25, { base_score: 1.0, title_mention_boost: 1.25 });
const out = formatResultExplain(res, 1);
expect(out).toContain('+ title-mention ×1.25');
expect(out).not.toContain('no boosts applied');
expect(buildScoreDetails(res).boosts).toEqual({ title_mention: { factor: 1.25 } });
});
test('backlink_boost renders', () => {
const out = formatResultExplain(
r('a/b', 1.5, { base_score: 1.0, backlink_boost: 1.5 }),
1,
);
expect(out).toContain('+ backlink ×1.5');
expect(out).not.toContain('no boosts applied');
});
test('salience_boost renders', () => {
const out = formatResultExplain(
r('a/b', 1.2, { base_score: 1.0, salience_boost: 1.2 }),
1,
);
expect(out).toContain('+ salience ×1.2');
});
test('recency_boost renders', () => {
const out = formatResultExplain(
r('a/b', 1.3, { base_score: 1.0, recency_boost: 1.3 }),
1,
);
expect(out).toContain('+ recency ×1.3');
});
test('exact_match_boost renders', () => {
const out = formatResultExplain(
r('a/b', 2.0, { base_score: 1.0, exact_match_boost: 2.0 }),
1,
);
expect(out).toContain('+ exact-match ×2');
});
test('graph_adjacency_boost + hits render', () => {
const out = formatResultExplain(
r('hub', 1.05, { base_score: 1.0, graph_adjacency_boost: 1.05, graph_adjacency_hits: 3 }),
1,
);
expect(out).toContain('+ adjacency ×1.05 (hits=3)');
});
test('graph_cross_source_boost + cross_source_hits render', () => {
const out = formatResultExplain(
r('hub', 1.10, { base_score: 1.0, graph_cross_source_boost: 1.10, graph_cross_source_hits: 2 }),
1,
);
expect(out).toContain('+ cross_source ×1.1 (other_sources=2)');
});
test('session_demote_factor renders as DEMOTE not boost', () => {
const out = formatResultExplain(
r('chat/b', 0.95, {
base_score: 1.0,
session_demote_factor: 0.95,
graph_session_prefix: 'chat',
graph_session_demoted: true,
}),
1,
);
expect(out).toContain('- session_demote ×0.95 (prefix=chat)');
});
test('reranker_delta positive renders as rank-up arrow', () => {
const out = formatResultExplain(
r('a/b', 1.0, { base_score: 1.0, reranker_delta: 2 }),
1,
);
expect(out).toContain('↑ reranker rank +2');
});
test('reranker_delta negative renders as rank-down arrow', () => {
const out = formatResultExplain(
r('a/b', 1.0, { base_score: 1.0, reranker_delta: -1 }),
1,
);
expect(out).toContain('↓ reranker rank -1');
});
test('reranker_delta = 0 → no rendering (no movement)', () => {
const out = formatResultExplain(
r('a/b', 1.0, { base_score: 1.0, reranker_delta: 0 }),
1,
);
expect(out).not.toContain('reranker rank');
expect(out).toContain('no boosts applied');
});
});
describe('formatResultExplain — multi-stage stacking', () => {
test('three boosts render as separate lines in order', () => {
const out = formatResultExplain(
r('hub', 1.5, {
base_score: 1.0,
backlink_boost: 1.1,
salience_boost: 1.05,
graph_adjacency_boost: 1.05,
graph_adjacency_hits: 3,
}),
1,
);
const lines = out.split('\n');
// base, +backlink, +salience, +adjacency, = final → 5 substantive lines + header.
expect(lines.length).toBeGreaterThanOrEqual(6);
expect(out).toMatch(/\+ backlink[\s\S]*\+ salience[\s\S]*\+ adjacency/);
});
});
describe('formatResultsExplain — list rendering', () => {
test('empty list', () => {
expect(formatResultsExplain([])).toBe('No results.\n');
});
test('multiple results separated by blank lines, trailing newline', () => {
const out = formatResultsExplain([
r('a', 1.0),
r('b', 0.9),
]);
expect(out).toContain('1. a');
expect(out).toContain('2. b');
expect(out).toMatch(/\n\n2\./); // blank line between entries
expect(out.endsWith('\n')).toBe(true);
});
test('rank numbering is 1-based', () => {
const out = formatResultsExplain([
r('first', 10),
r('second', 9),
r('third', 8),
]);
expect(out).toContain('1. first');
expect(out).toContain('2. second');
expect(out).toContain('3. third');
});
});
describe('formatResultExplain — number formatting', () => {
test('trailing zeros stripped', () => {
const out = formatResultExplain(r('a/b', 1.0), 1);
expect(out).toContain('score=1');
expect(out).not.toContain('score=1.0000');
});
test('non-zero fractional digits preserved up to 4 places', () => {
const out = formatResultExplain(r('a/b', 0.1234), 1);
expect(out).toContain('score=0.1234');
});
test('NaN preserved as "NaN"', () => {
const out = formatResultExplain(r('a/b', NaN), 1);
expect(out).toContain('score=NaN');
});
});
describe('v0.42.3.0 — autocut in --explain', () => {
test('rerank_score renders per result (the cliff signal)', () => {
const out = formatResultExplain(r('a/b', 1.2, { rerank_score: 0.87 }), 1);
expect(out).toContain('rerank score=0.87');
});
test('no rerank score line when absent', () => {
const out = formatResultExplain(r('a/b', 1.2), 1);
expect(out).not.toContain('rerank score');
});
const applied: AutocutDecision = {
applied: true,
signal: 'rerank',
cut: 2,
kept: 2,
total: 7,
gapRatio: 0.41,
};
const declined: AutocutDecision = {
applied: false,
signal: 'none',
cut: 7,
kept: 7,
total: 7,
gapRatio: 0.05,
};
test('formatAutocutSummary — applied cut', () => {
const s = formatAutocutSummary(applied);
expect(s).toContain('kept 2/7');
expect(s).toContain('0.41');
});
test('formatAutocutSummary — declined', () => {
const s = formatAutocutSummary(declined);
expect(s).toContain('no cut');
expect(s).toContain('full 7');
});
test('formatAutocutSummary — undefined → null (omit cleanly)', () => {
expect(formatAutocutSummary(undefined)).toBeNull();
});
test('formatResultsExplain prepends the autocut summary when meta has a decision', () => {
const out = formatResultsExplain([r('a/b', 1.2, { rerank_score: 0.9 })], {
vector_enabled: true,
detail_resolved: null,
expansion_applied: false,
autocut: applied,
});
expect(out.startsWith('autocut:')).toBe(true);
expect(out).toContain('kept 2/7');
});
test('formatResultsExplain omits the summary when meta has no autocut decision', () => {
const out = formatResultsExplain([r('a/b', 1.2)]);
expect(out.startsWith('autocut:')).toBe(false);
});
});
describe('formatDegradedSummary — v0.48.2 skipped-stage line', () => {
test('null when the run was clean', () => {
expect(formatDegradedSummary(undefined)).toBeNull();
expect(formatDegradedSummary([])).toBeNull();
});
test('names each stage with its reason', () => {
expect(formatDegradedSummary([{ stage: 'reranker_skipped', reason: 'no_key' }])).toBe(
'degraded: reranker_skipped (no_key)',
);
expect(
formatDegradedSummary([{ stage: 'keyword_zero' }, { stage: 'reranker_skipped', reason: 'no_key' }]),
).toBe('degraded: keyword_zero, reranker_skipped (no_key)');
});
test('formatResultsExplain prepends the degraded line', () => {
const out = formatResultsExplain([r('a/b', 1.5)], {
degraded: [{ stage: 'reranker_skipped', reason: 'no_key' }],
} as any);
expect(out.startsWith('degraded: reranker_skipped (no_key)\n\n1. a/b')).toBe(true);
});
test('autocut line precedes the degraded line when both exist', () => {
const out = formatResultsExplain([r('a/b', 1.5)], {
autocut: { applied: false, signal: 'rerank', gapRatio: 0.1, kept: 1, total: 1 } as any,
degraded: [{ stage: 'reranker_skipped', reason: 'no_key' }],
} as any);
const [first, second, blank, body] = out.split('\n');
expect(first.startsWith('autocut:')).toBe(true);
expect(second).toBe('degraded: reranker_skipped (no_key)');
expect(blank).toBe('');
expect(body.startsWith('1. a/b')).toBe(true);
});
});