Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
3.7 KB
Raw Blame
import { getRecipe } from './recipes/index.ts';
import { parseModelId } from './model-resolver.ts';
import { DEFAULT_RERANKER_MODEL } from './defaults.ts';

export interface RerankerReadiness {
  /** The provider:model string that was evaluated. */
  model: string;
  /** Provider id as `parseModelId` resolves it (`:` or `/` separator), or '' when unparseable. */
  provider: string;
  /** Canonical model id (recipe alias resolved), or '' when unparseable. */
  modelId: string;
  /** A recipe with this provider id is registered. */
  recipeKnown: boolean;
  /** The recipe declares a reranker touchpoint. */
  hasTouchpoint: boolean;
  /** The model id is on the touchpoint's allowlist (or the list is open). */
  modelListed: boolean;
  /** The env var the recipe needs for auth (first `auth_env.required`), or null. */
  requiredKey: string | null;
  /** Every required key is present in the caller-supplied env. */
  keyPresent: boolean;
  selfHosted: boolean;
  /** Everything above is green: a rerank call would actually be issued. */
  ready: boolean;
}

export interface RerankerReadinessOpts {
  /** Provider ids with a base-URL override (self-hosted endpoints). */
  baseUrlOverrides?: Record<string, string | undefined> | null;
}

/**
 * Evaluate readiness for `model` against `env`. Pure; never throws;

 */
export function rerankerReadiness(
  model: string,
  env: Record<string, string | undefined>,
  opts: RerankerReadinessOpts = {},
): RerankerReadiness {
  let provider = '';
  let modelId = '';
  try {
    const parsed = parseModelId(model);
    provider = parsed.providerId;
    modelId = parsed.modelId;
  } catch {
    // Unparseable (no `provider:model` shape) — every flag below stays false.
  }
  const recipe = provider ? getRecipe(provider) : undefined;
  const tp = recipe?.touchpoints.reranker;
  const required = recipe?.auth_env?.required ?? [];
  // A recipe with a custom resolveAuth (e.g. Azure Entra) mints its own
  // credential — mirror the gateway: no env key is required from us.
  const needsEnvKey = !!recipe && (!recipe.resolveAuth || !!recipe.authPresent) && required.length > 0;
  const keyPresent = !!recipe && (recipe.authPresent ? recipe.authPresent(env) : (!needsEnvKey || required.every((k) => !!env[k])));
  // Alias canonicalization mirrors resolveRecipe(): a recipe alias key is
  // accepted wherever the gateway accepts it.
  const canonicalModelId = recipe?.aliases?.[modelId] ?? modelId;
  const listed = !!tp && (tp.models.length === 0 || tp.models.includes(canonicalModelId));
  const selfHosted = !!provider && !!opts.baseUrlOverrides?.[provider];
  return {
    model,
    provider,
    modelId: canonicalModelId,
    recipeKnown: !!recipe,
    hasTouchpoint: !!tp,
    modelListed: listed,
    // Name the key that is actually missing (multi-key recipes), else the first.
    requiredKey: needsEnvKey ? (required.find((k) => !env[k]) ?? required[0]!) : null,
    keyPresent,
    selfHosted,
    ready: !!recipe && !!tp && listed && keyPresent,
  };
}

/**
 * Paste-ready fix for a not-ready reranker, one line, no trailing newline.
 * Returns null when `r.ready` (nothing to fix). Order matters: a dead
 * provider needs a model switch before any key talk.
 */
export function describeRerankerFix(r: RerankerReadiness): string | null {
  if (r.ready) return null;
  if (!r.recipeKnown || !r.hasTouchpoint || !r.modelListed) {
    return (
      `${r.model} is not a known reranker (provider:model) — set one: ` +
      `gbrain config set search.reranker.model ${DEFAULT_RERANKER_MODEL}`
    );
  }
  if (!r.keyPresent && r.requiredKey) {
    return (
      `${r.requiredKey} not set — export ${r.requiredKey}=… ` +
      `(or turn reranking off: gbrain config set search.reranker.enabled false)`
    );
  }
  return `reranker ${r.model} is not ready`;
}