Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* #4616: the embedding gateway never hands back a vector that an ANN index
* cannot serve. A zero-norm, NaN or ±Inf vector has no cosine direction, so
* HNSW silently skips its row: `gbrain get` and keyword search find the chunk
* while vector search never returns it. Empty inputs are refused before the
* provider call.
*
* The refusal is terminal per item: the other inputs of the same call keep
* their (already paid) vectors, carried on the error aligned with the input,
* so a caller that can store a partial result stores it and leaves only the
* degenerate chunks unembedded. A caller that cannot simply fails the call,
* and nothing degenerate is ever written.
*/
import { AIConfigError } from './errors.ts';
import { modelMatchKey } from './dims.ts';
import type { Recipe } from './types.ts';
export const EMBEDDING_ZERO_NORM = 'embedding_zero_norm';
export const EMBEDDING_ZERO_NORM_DOCS = 'docs/guides/write-refusals.md#embedding_zero_norm';
/** Real embeddings have norms near 1; below this the direction is noise. */
export const EMBEDDING_NORM_EPSILON = 1e-6;
export type DegenerateEmbeddingReason = 'empty_input' | 'zero_norm' | 'non_finite';
export function degenerateEmbeddingReason(vector: ArrayLike<number>): DegenerateEmbeddingReason | null {
let sum = 0;
for (let i = 0; i < vector.length; i++) {
const value = vector[i]!;
if (!Number.isFinite(value)) return 'non_finite';
sum += value * value;
}
return Math.sqrt(sum) < EMBEDDING_NORM_EPSILON ? 'zero_norm' : null;
}
export class EmbeddingZeroNormError extends AIConfigError {
readonly code = EMBEDDING_ZERO_NORM;
readonly docs = EMBEDDING_ZERO_NORM_DOCS;
constructor(
readonly failures: { index: number; reason: DegenerateEmbeddingReason }[],
readonly vectors: (Float32Array | null)[],
readonly model: string,
) {
const reasons = [...new Set(failures.map(f => f.reason))].join(', ');
super(
`${EMBEDDING_ZERO_NORM}: the embedding provider ${model} gave no usable vector for ${failures.length === 1 ? 'one input' : 'some inputs'} (${reasons}); ` +
`those inputs were not indexed and the rest of the batch was kept.`,
'Inspect the affected chunk text (empty, whitespace- or symbol-only chunks are the usual cause) or the provider, then re-embed the page with `gbrain embed <slug>`.',
);
this.name = 'EmbeddingZeroNormError';
}
/** The recovery command filled with the page the failed chunks belong to. */
suggestionFor(slug: string, sourceId?: string): string {
const source = sourceId && sourceId !== 'default' ? ` --source ${sourceId}` : '';
return `Inspect the chunk text of ${slug} (empty, whitespace- or symbol-only chunks are the usual cause) or the embedding provider, ` +
`then run \`gbrain embed ${slug}${source}\`. See ${EMBEDDING_ZERO_NORM_DOCS}.`;
}
}
export function isEmbeddingZeroNormError(error: unknown): error is EmbeddingZeroNormError {
return error instanceof EmbeddingZeroNormError;
}
/**
* Merge per-slice refusals of one logical call into a single error whose
* vectors and indices are aligned with the caller's full input.
*/
export function mergeZeroNormErrors(total: number, slices: { offset: number; vectors: Float32Array[] | null; error?: EmbeddingZeroNormError }[],
model: string): EmbeddingZeroNormError | null {
if (!slices.some(s => s.error)) return null;
const vectors: (Float32Array | null)[] = new Array(total).fill(null);
const failures: EmbeddingZeroNormError['failures'] = [];
for (const slice of slices) {
const source = slice.error?.vectors ?? slice.vectors ?? [];
source.forEach((v, i) => { vectors[slice.offset + i] = v; });
for (const f of slice.error?.failures ?? []) failures.push({ index: slice.offset + f.index, reason: f.reason });
}
return new EmbeddingZeroNormError(failures, vectors, model);
}
/** Indexes of inputs worth sending: empty and whitespace-only inputs never reach the provider. */
export function sendableEmbeddingInputs(texts: string[]): number[] {
return texts.flatMap((text, i) => (text.trim() ? [i] : []));
}
/**
* Place the provider's vectors (one per sent input) back at their input
* positions and refuse every empty or degenerate item. Returns the full
* aligned result when every item is usable.
*/
export function screenEmbeddings(texts: string[], sent: number[], vectors: Float32Array[], model: string): Float32Array[] {
const out: (Float32Array | null)[] = new Array(texts.length).fill(null);
sent.forEach((index, j) => { out[index] = vectors[j] ?? null; });
return screenAlignedEmbeddings(out, model);
}
/** Refuse every missing (empty input) or degenerate vector of an input-aligned result. */
export function screenAlignedEmbeddings(out: (Float32Array | null)[], model: string): Float32Array[] {
const failures: EmbeddingZeroNormError['failures'] = [];
out.forEach((vector, index) => {
const reason = vector ? degenerateEmbeddingReason(vector) : 'empty_input';
if (!reason) return;
failures.push({ index, reason });
out[index] = null;
});
if (failures.length) throw new EmbeddingZeroNormError(failures, out, model);
return out as Float32Array[];
}
/**
* PR #5921 / wave 14 P3.18: fit a Matryoshka model's native-width response to the brain's width by the rule its
* card documents (keep the first `expected` coordinates, L2-normalize), when the recipe's embedding touchpoint
* declares the model (`matryoshka`) with that native width and lists `expected` among its prefixes. Every other
* vector returns as it came, so the caller's dim-mismatch check still decides. A prefix whose norm overflows is
* refused here; a zero or non-finite prefix returns unnormalized and `screenAlignedEmbeddings` refuses it per item.
*/
export function fitMatryoshkaPrefix(recipe: Recipe, modelId: string, vector: number[], expected: number): number[] {
const declared = recipe.touchpoints?.embedding?.matryoshka?.[modelMatchKey(modelId)];
if (!declared || !Array.isArray(vector) || vector.length !== declared.native || expected === declared.native || !declared.prefixes.includes(expected)) return vector;
const prefix = vector.slice(0, expected);
if (degenerateEmbeddingReason(prefix)) return prefix;
let sum = 0;
for (const value of prefix) sum += value * value;
const norm = Math.sqrt(sum);
if (!Number.isFinite(norm)) {
throw new AIConfigError(`Embedding provider returned a ${expected}-dim prefix with a non-finite norm for ${modelId}.`,
'Retry after checking provider output; a vector whose norm overflows is not safe to index.');
}
return prefix.map(value => value / norm);
}