Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.2 KB
Raw Blame
/**
 * Search-tune recommendation builder — moved from src/commands/search.ts in
 * the CLI→MCP gap-closure wave so the `search_tune` op and the CLI derive the
 * same recommendations. STRICTLY READ-ONLY: applying a recommendation
 * (`gbrain search tune` with the apply flag) is CLI-only by design [CDX-21]
 * and stays in the command file.
 */

import type { BrainEngine } from '../engine.ts';
import { loadSearchModeConfig, resolveSearchMode, type SearchMode } from './mode.ts';
import { readSearchStats, telemetryCoverage, type TelemetryCoverage } from './telemetry.ts';
import { semanticResultCacheAvailable } from './query-cache.ts';

export interface TuneRecommendation {
  knob: string;
  current: unknown;
  suggested: unknown;
  reason: string;
  apply_command: string;
}

export interface TuneReport {
  schema_version: 2;
  status: 'insufficient_data' | 'no_recommendations' | 'has_recommendations';
  total_calls: number;
  cache_hit_rate: number;
  active_mode: SearchMode;
  coverage: TelemetryCoverage;
  recommendations: TuneRecommendation[];
}

/** Below this many recorded searches the report is 'insufficient_data'. */
export const TUNE_MIN_CALLS = 20;

export async function buildTuneRecommendations(engine: BrainEngine): Promise<TuneReport> {
  const modeInput = await loadSearchModeConfig(engine);
  const resolved = resolveSearchMode(modeInput);
  const stats = await readSearchStats(engine, { days: 7 });

  const base = {
    schema_version: 2 as const,
    total_calls: stats.total_calls,
    cache_hit_rate: stats.cache_hit_rate,
    active_mode: resolved.resolved_mode,
    coverage: telemetryCoverage(),
  };

  // Recommendation 1: low call volume → no data yet.
  if (stats.total_calls < TUNE_MIN_CALLS) {
    return { ...base, status: 'insufficient_data', recommendations: [] };
  }

  const recs: TuneRecommendation[] = [];

  // Recommendation 2: budget pressure under conservative.
  if (resolved.resolved_mode === 'conservative' && stats.total_calls > 0) {
    const dropPctPerCall = stats.total_budget_dropped / stats.total_calls;
    if (dropPctPerCall > 2) {
      recs.push({
        knob: 'search.mode',
        current: 'conservative',
        suggested: 'balanced',
        reason: `Avg ${dropPctPerCall.toFixed(1)} results dropped per search by the 4K budget. Consider balanced (12K budget) or raise search.tokenBudget.`,
        apply_command: 'gbrain config set search.mode balanced',
      });
    }
  }

  // Recommendation 3: high cache hit rate → bump similarity threshold.
  if (semanticResultCacheAvailable() && stats.cache_hit_rate > 0.85 && stats.cache_hits + stats.cache_misses > 50) {
    recs.push({
      knob: 'search.cache.similarity_threshold',
      current: resolved.cache_similarity_threshold,
      suggested: 0.94,
      reason: `Cache hit rate is ${(stats.cache_hit_rate * 100).toFixed(1)}%. You can raise similarity threshold to 0.94 for tighter freshness at small recall cost.`,
      apply_command: 'gbrain config set search.cache.similarity_threshold 0.94',
    });
  }

  // Recommendation 4: tokenmax + Haiku subagent.
  const subagentModel = await engine.getConfig('models.tier.subagent');
  if (resolved.resolved_mode === 'tokenmax' && subagentModel && /haiku/i.test(subagentModel)) {
    recs.push({
      knob: 'search.mode',
      current: 'tokenmax',
      suggested: 'balanced',
      reason: 'Subagent tier is Haiku but mode is tokenmax. Balanced caps the result payload at 12K tokens by default, reducing downstream input volume. Semantic result caching is temporarily disabled.',
      apply_command: 'gbrain config set search.mode balanced',
    });
  }

  // Recommendation 5: cache disabled but available — fix the free win.
  if (semanticResultCacheAvailable() && !resolved.cache_enabled && stats.total_calls > 5) {
    recs.push({
      knob: 'search.cache.enabled',
      current: false,
      suggested: true,
      reason: 'Cache is disabled but mode bundles enable it by default. Cache is a free win (zero LLM cost, big latency drop on repeat queries).',
      apply_command: 'gbrain config unset search.cache.enabled',
    });
  }

  return {
    ...base,
    status: recs.length === 0 ? 'no_recommendations' : 'has_recommendations',
    recommendations: recs,
  };
}