Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
6.9 KB
Raw Blame
/**
 * Embedding pass for typed take claims.
 *
 * Runs from `gbrain takes embed` and, unless `takes.auto_embed` is off, from
 * every `embed --stale` drain (which the cycle's embed phase and the
 * embedding-model migration drain both use). A take is stale when it has no
 * vector, its claim changed since it was embedded, or another model or width
 * produced its vector (#5885). Each write is bound to the claim text and model
 * it was computed from, so a claim edited mid-flight keeps its NULL vector.
 */

import type { BrainEngine, StaleTakeRow, TakeEmbeddingInput } from './engine.ts';
import { embedBatchWithBackoff } from '../commands/embed.ts';
import { getEmbeddingDimensions, getEmbeddingModel } from './ai/gateway.ts';
import { slog } from './console-prefix.ts';
import { currentEmbeddingSignature } from './embedding.ts';

const DEFAULT_BATCH_SIZE = 100;

export interface EmbedTakesOpts {
  batchSize?: number;
  dryRun?: boolean;
  signal?: AbortSignal;
  sourceId?: string;
  assertOwned?: (tx: BrainEngine) => Promise<void>;
  embedFn?: (texts: string[], opts: { abortSignal?: AbortSignal }) => Promise<Float32Array[]>;
  onProgress?: (done: number, total: number, embedded: number) => void;
}

export interface EmbedTakesResult {
  total_stale: number;
  embedded: number;
  would_embed: number;
  /** Vectors not written because the take's claim changed while they were computed; the next pass embeds the new claim. */
  discarded: number;
  failures: number;
  failure_samples: string[];
  dryRun: boolean;
}

/** `takes.auto_embed` (config) with `GBRAIN_EMBED_TAKES` (env) taking precedence; default on. */
export async function takesAutoEmbedEnabled(engine: Pick<BrainEngine, 'getConfig'>): Promise<boolean> {
  const raw = process.env.GBRAIN_EMBED_TAKES ?? await engine.getConfig('takes.auto_embed');
  return raw == null || !['0', 'false', 'off', 'no'].includes(raw.trim().toLowerCase());
}

/** Width of `takes.embedding`, or null when the column is absent. */
export async function readTakesEmbeddingDim(engine: Pick<BrainEngine, 'executeRaw'>): Promise<number | null> {
  const rows = await engine.executeRaw<{ formatted: string | null }>(
    `SELECT format_type(a.atttypid, a.atttypmod) AS formatted
       FROM pg_attribute a
       JOIN pg_class c ON c.oid = a.attrelid
       JOIN pg_namespace n ON n.oid = c.relnamespace
      WHERE n.nspname = 'public' AND c.relname = 'takes' AND a.attname = 'embedding' AND NOT a.attisdropped`,
  );
  const dims = Number(rows[0]?.formatted?.match(/^(?:halfvec|vector)\((\d+)\)$/)?.[1]);
  return Number.isInteger(dims) && dims > 0 ? dims : null;
}

/** Embed active takes that have no current-model vector for their current claim. */
export async function embedStaleTakes(
  engine: BrainEngine,
  opts: EmbedTakesOpts = {},
): Promise<EmbedTakesResult> {
  const model = getEmbeddingModel();
  const dims = getEmbeddingDimensions();
  const scope = { model, dims, ...(opts.sourceId ? { sourceId: opts.sourceId } : {}) };
  const stale = await engine.countStaleTakes(scope) > 0 ? await engine.listStaleTakes(scope) : [];
  const result: EmbedTakesResult = {
    total_stale: stale.length,
    embedded: 0,
    would_embed: opts.dryRun ? stale.length : 0,
    discarded: 0,
    failures: 0,
    failure_samples: [],
    dryRun: !!opts.dryRun,
  };
  if (opts.dryRun || stale.length === 0) {
    opts.onProgress?.(stale.length, stale.length, 0);
    return result;
  }
  const columnDims = await readTakesEmbeddingDim(engine);
  if (columnDims !== dims) {
    result.failures = stale.length;
    result.failure_samples.push(
      `takes_embedding_width_mismatch: takes.embedding is ${columnDims === null ? 'absent' : `${columnDims}d`}, the configured model is ${dims}d. ` +
      'Fix: gbrain migrate embeddings --status',
    );
    return result;
  }

  const batchSize = Math.min(500, Math.max(1, Math.floor(opts.batchSize ?? DEFAULT_BATCH_SIZE)));
  const embedFn = opts.embedFn ?? ((texts: string[], embedOpts: { abortSignal?: AbortSignal }) =>
    embedBatchWithBackoff(texts, embedOpts));

  for (let start = 0; start < stale.length; start += batchSize) {
    if (opts.signal?.aborted) break;
    const batch = stale.slice(start, start + batchSize);
    try {
      const embeddings = await embedFn(
        batch.map((row) => row.claim),
        { abortSignal: opts.signal },
      );
      if (embeddings.length !== batch.length) {
        throw new Error(`embedding provider returned ${embeddings.length} vectors for ${batch.length} takes`);
      }
      const writes: TakeEmbeddingInput[] = batch.map((row: StaleTakeRow, index) => ({
        take_id: row.take_id,
        embedding: embeddings[index],
        claim: row.claim,
        model,
      }));
      const written = opts.assertOwned
        ? await engine.transaction(async tx => { await opts.assertOwned!(tx); return tx.updateTakeEmbeddings(writes, { signal: opts.signal }); })
        : await engine.updateTakeEmbeddings(writes, { signal: opts.signal });
      result.embedded += written;
      result.discarded += batch.length - written;
    } catch (error: unknown) {
      result.failures += batch.length;
      if (result.failure_samples.length < 10) {
        result.failure_samples.push(error instanceof Error ? error.message : String(error));
      }
    }
    opts.onProgress?.(Math.min(start + batch.length, stale.length), stale.length, result.embedded);
  }

  return result;
}

/**
 * The takes pass of an `embed --stale` drain (#5885). Runs when `opts.takes`
 * is true, or when it is unset and takes.auto_embed allows it; records its
 * result on the drain result and counts its failures there too.
 */
export async function embedTakesForStaleDrain(
  engine: BrainEngine,
  opts: EmbedTakesOpts & { quiet?: boolean; takes?: boolean },
  result: { failures: number; failure_samples: string[]; takes?: EmbedTakesResult },
): Promise<void> {
  if (!(opts.takes ?? await takesAutoEmbedEnabled(engine))) return;
  // No configured model to bind a vector to (embedding_identity_unverified): the chunk drain runs signature-free; takes wait.
  if (currentEmbeddingSignature() === null) return;
  let takes: EmbedTakesResult;
  try {
    takes = await embedStaleTakes(engine, opts);
  } catch (error: unknown) {
    takes = { total_stale: 0, embedded: 0, would_embed: 0, discarded: 0, failures: 1, dryRun: !!opts.dryRun,
      failure_samples: [error instanceof Error ? error.message : String(error)] };
  }
  result.takes = takes;
  if (takes.failures > 0) {
    result.failures += takes.failures;
    result.failure_samples.push(...takes.failure_samples.slice(0, Math.max(0, 10 - result.failure_samples.length)).map(sample => `takes: ${sample}`));
  }
  if (opts.quiet || takes.total_stale === 0) return;
  slog(opts.dryRun
    ? `[dry-run] Would embed ${takes.would_embed} stale take(s)`
    : `[embed] takes: embedded ${takes.embedded} of ${takes.total_stale} stale take(s)${takes.discarded ? `, ${takes.discarded} changed mid-flight (re-embedded next run)` : ''}`);
}