Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Per-provider dimension parameter resolver.
*
* Critical: OpenAI text-embedding-3-* defaults to 3072 dims on the API side.
* Without explicit dimensions passthrough, existing 1536-dim brains break.
* Similarly, Gemini gemini-embedding-001 defaults to 3072.
*
* This module centralizes the knowledge of "which provider needs which
* providerOptions shape to produce vector(N)".
*/
import type { Implementation } from './types.ts';
import { AIConfigError } from './errors.ts';
/**
* Match key only — NEVER sent to a provider (#4123). Provider model ids are
* case-sensitive on the wire (model-resolver.ts lowercases only the provider
* prefix and preserves the model id verbatim; `Qwen/Qwen3-Embedding-4B`
* 500s if lowercased at the provider). Hub-form ids arrive mixed-case, so
* every lookup in this module folds through this key; every literal in this
* module's tables and comparisons is already lowercase, making the fold
* total. Error messages keep the ORIGINAL id so they stay paste-ready.
*/
export function modelMatchKey(id: string): string {
return id.trim().toLowerCase();
}
// Voyage hosted models that accept `output_dimension` (values:
// 256 / 512 / 1024 / 2048). Per Voyage's API parameter docs as of 2026-05.
// voyage-4-nano is intentionally NOT in this set: it's the open-weight
// variant listed separately by Voyage as fixed 1024-dim. Adding it here
// would tell the SDK to send `dimensions: N`, which voyageCompatFetch then
// rewrites to `output_dimension: N` — and Voyage's hosted nano endpoint
// rejects the parameter. The negative regression assertion in
// test/ai/gateway.test.ts pins this contract.
const VOYAGE_OUTPUT_DIMENSION_MODELS = new Set([
'voyage-4-large',
'voyage-4',
'voyage-4-lite',
// voyage-code-4: hosted, flexible dims 256/512/1024/2048 per Voyage's
// embeddings docs (verified 2026-08-15).
'voyage-code-4',
'voyage-3-large',
'voyage-3.5',
'voyage-3.5-lite',
'voyage-code-3',
]);
// Voyage's flexible-dim endpoint only accepts these four discrete values.
// Per Voyage's API docs (2026-05). Out-of-range requests are rejected with
// HTTP 400 by the upstream — catching it locally produces a clearer error
// with the valid-values hint. The most common way to hit this in
// production: `embedding_model: voyage:voyage-4-large` configured without
// `embedding_dimensions`, where the gateway falls back to
// DEFAULT_EMBEDDING_DIMENSIONS=1536 (an OpenAI default, not a Voyage one).
export const VOYAGE_VALID_OUTPUT_DIMS = [256, 512, 1024, 2048] as const;
export function supportsVoyageOutputDimension(modelId: string): boolean {
return VOYAGE_OUTPUT_DIMENSION_MODELS.has(modelMatchKey(modelId));
}
export function isValidVoyageOutputDim(dims: number): boolean {
return (VOYAGE_VALID_OUTPUT_DIMS as readonly number[]).includes(dims);
}
// v0.36.0.0 (D13): OpenAI text-embedding-3-* accepts arbitrary truncation via
// Matryoshka — any positive integer up to the model's native size. When a
// brain is configured with `embedding_dimensions` OUTSIDE that range, OpenAI
// returns HTTP 400 at first embed. We catch it locally with a paste-ready
// fix so users don't see opaque "vector dimension mismatch" errors after a
// `gbrain migrate embeddings --to openai:...` lands them at the wrong dim.
const OPENAI_TEXT3_MAX_DIMS: Record<string, number> = {
'text-embedding-3-small': 1536,
'text-embedding-3-large': 3072,
};
export function isOpenAITextEmbedding3Model(modelId: string): boolean {
return modelMatchKey(modelId) in OPENAI_TEXT3_MAX_DIMS;
}
export function maxOpenAITextEmbedding3Dim(modelId: string): number | undefined {
return OPENAI_TEXT3_MAX_DIMS[modelMatchKey(modelId)];
}
export function isValidOpenAITextEmbedding3Dim(modelId: string, dims: number): boolean {
const max = OPENAI_TEXT3_MAX_DIMS[modelMatchKey(modelId)];
if (max === undefined) return false;
return Number.isInteger(dims) && dims >= 1 && dims <= max;
}
// Perplexity hosted embeddings (#1046): Matryoshka-style flexible dims,
// any integer from 128 up to the model's native size. `dimensions` is the
// native wire field (no translation needed); output encoding divergence
// (base64 int8) is handled by perplexityCompatFetch in gateway.ts.
const PERPLEXITY_EMBEDDING_MAX_DIMS: Record<string, number> = {
'pplx-embed-v1-0.6b': 1024,
'pplx-embed-v1-4b': 2560,
};
export const PERPLEXITY_MIN_DIMS = 128;
export function isPerplexityEmbeddingModel(modelId: string): boolean {
return modelMatchKey(modelId) in PERPLEXITY_EMBEDDING_MAX_DIMS;
}
export function maxPerplexityEmbeddingDim(modelId: string): number | undefined {
return PERPLEXITY_EMBEDDING_MAX_DIMS[modelMatchKey(modelId)];
}
export function isValidPerplexityDim(modelId: string, dims: number): boolean {
const max = PERPLEXITY_EMBEDDING_MAX_DIMS[modelMatchKey(modelId)];
if (max === undefined) return false;
return Number.isInteger(dims) && dims >= PERPLEXITY_MIN_DIMS && dims <= max;
}
// NVIDIA NIM hosted embedding models use asymmetric input_type values. Most
// emit fixed natural dimensions, but llama-nemotron-embed-1b-v2 accepts
// Matryoshka-style dimension overrides (e.g. matching an existing 1280d
// brain column without re-embedding through another provider).
const NVIDIA_EMBEDDING_DIMS: Record<string, number> = {
'nvidia/nv-embedqa-e5-v5': 1024,
'nvidia/llama-nemotron-embed-1b-v2': 2048,
// PR #5921: 4096 native; 2048/1024 are client-side prefixes (recipe `matryoshka`), never a `dimensions` override.
'nvidia/nemotron-3-embed-8b': 4096,
'nvidia/nv-embed-v1': 4096,
'nvidia/nv-embedcode-7b-v1': 4096,
};
const NVIDIA_EMBEDDING_DIM_OPTIONS: Record<string, number[]> = {
'nvidia/llama-nemotron-embed-1b-v2': [1024, 1280, 1536, 2048],
};
export function isNvidiaEmbeddingModel(modelId: string): boolean {
return modelMatchKey(modelId) in NVIDIA_EMBEDDING_DIMS;
}
export function nvidiaEmbeddingDim(modelId: string): number | undefined {
return NVIDIA_EMBEDDING_DIMS[modelMatchKey(modelId)];
}
export function nvidiaEmbeddingDimOptions(modelId: string): number[] | undefined {
return NVIDIA_EMBEDDING_DIM_OPTIONS[modelMatchKey(modelId)];
}
export function supportsNvidiaEmbeddingDimension(modelId: string, dims: number): boolean {
const options = nvidiaEmbeddingDimOptions(modelId);
return !!options && options.includes(dims);
}
// Qwen3-Embedding native widths, module scope alongside the other dim tables
// (#4123 — was re-allocated per call inside the openai-compatible branch).
// Keys cover Ollama's colon-tag form and the hyphenated hub form; all
// lowercase — lookups fold through modelMatchKey.
const QWEN3_EMBEDDING_NATIVE_DIMS: Record<string, number> = {
'qwen3-embedding': 1024,
'qwen3-embedding:0.6b': 1024,
'qwen3-embedding:4b': 2560,
'qwen3-embedding:8b': 4096,
'qwen3-embedding-0.6b': 1024,
'qwen3-embedding-4b': 2560,
'qwen3-embedding-8b': 4096,
};
export function dimsProviderOptions(
implementation: Implementation,
modelId: string,
dims: number,
inputType?: 'query' | 'document',
): Record<string, any> | undefined {
// #4123: all comparisons below run on the folded key; `modelId` (original
// case) survives untouched for error messages and is never mutated.
const matchId = modelMatchKey(modelId);
switch (implementation) {
case 'native-openai': {
// text-embedding-3-* supports dimensions; text-embedding-ada-002 does not.
// OpenAI embeddings are symmetric — inputType ignored.
if (matchId.startsWith('text-embedding-3')) {
// v0.36.0.0 (D13): fail-loud when configured dim is outside the
// model's Matryoshka range. OpenAI returns HTTP 400 otherwise with
// a generic message that misroutes as a network blip.
if (isOpenAITextEmbedding3Model(modelId) && !isValidOpenAITextEmbedding3Dim(modelId, dims)) {
const max = maxOpenAITextEmbedding3Dim(modelId)!;
throw new AIConfigError(
`OpenAI model "${modelId}" supports embedding_dimensions in 1..${max}, got ${dims}.`,
`Use a width between 1 and ${max} (${Math.min(1024, max)} is a common default). On an existing brain a width change re-embeds; ` +
`preview it with \`gbrain migrate embeddings --to openai:${modelId} --dim ${Math.min(1024, max)} --dry-run\` (pages and facts are kept).`,
);
}
return { openai: { dimensions: dims } };
}
return undefined;
}
case 'native-google': {
if (matchId.startsWith('gemini-embedding') || matchId === 'text-embedding-004') {
return { google: { outputDimensionality: dims } };
}
return undefined;
}
case 'native-anthropic':
// Anthropic has no embedding model.
return undefined;
case 'openai-compatible':
// Voyage hosted flexible-dim models — accept `output_dimension`
// (translated by voyageCompatFetch) AND `input_type: query|document`
// for asymmetric retrieval. inputType is opt-in: when undefined,
// emit no field (preserves pre-v0.35.0.0 callers + existing tests).
// When threaded explicitly by embedQuery()/embed(), it reaches Voyage.
if (supportsVoyageOutputDimension(modelId)) {
// Fail-loud at the embed boundary if the user configured a dim
// Voyage doesn't accept. The most common path here: a brain with
// `embedding_model: voyage:voyage-4-large` but no explicit
// `embedding_dimensions`, where the gateway falls back to the
// module default (1536). Without this guard, Voyage's HTTP 400 is
// the only signal — usually mis-attributed as a transient network
// error.
if (!isValidVoyageOutputDim(dims)) {
throw new AIConfigError(
`Voyage model "${modelId}" supports output_dimension only in ` +
`{${VOYAGE_VALID_OUTPUT_DIMS.join(', ')}}, got ${dims}.`,
`Set \`embedding_dimensions\` to one of ` +
`${VOYAGE_VALID_OUTPUT_DIMS.join('/')} in your gbrain config, or ` +
`switch to a fixed-dim Voyage model (e.g. voyage-3, voyage-3-lite).`,
);
}
return {
openaiCompatible: {
dimensions: dims,
...(inputType ? { input_type: inputType } : {}),
},
};
}
if (isPerplexityEmbeddingModel(modelId)) {
if (!isValidPerplexityDim(modelId, dims)) {
const max = maxPerplexityEmbeddingDim(modelId)!;
throw new AIConfigError(
`Perplexity model "${modelId}" supports embedding_dimensions in ` +
`${PERPLEXITY_MIN_DIMS}..${max}, got ${dims}.`,
`Set \`embedding_dimensions\` to a value between ${PERPLEXITY_MIN_DIMS} and ${max} ` +
`in your gbrain config.`,
);
}
return { openaiCompatible: { dimensions: dims } };
}
// NVIDIA NIM hosted embeddings are OpenAI-compatible but require
// asymmetric input_type. Use passage for indexing/document-side vectors
// and query for search-side vectors. Only llama-nemotron-embed-1b-v2
// supports a dimensions override; fixed-dim models reject it.
if (isNvidiaEmbeddingModel(modelId)) {
const opts: Record<string, any> = {
input_type: inputType === 'query' ? 'query' : 'passage',
};
if (supportsNvidiaEmbeddingDimension(modelId, dims)) opts.dimensions = dims;
return { openaiCompatible: opts };
}
// OpenAI text-embedding-3 family on the openai-compatible adapter
// (Azure OpenAI hosts these via its OpenAI-compatible /embeddings
// endpoint). The provider defaults to the model's native size (3072
// for `-large`, 1536 for `-small`); without `dimensions`, brains
// configured for a smaller width (e.g. 1536) hard-fail at first embed.
// Azure/OpenAI-compat embeddings are symmetric — inputType ignored.
// v0.36.0.0 (D13): same range validation as native-openai path.
// Lowercased for matching only — providers' model ids are case-sensitive
// (SiliconFlow serves `Qwen/Qwen3-Embedding-4B` and 500s on the
// lowercase form), so the ORIGINAL id goes on the wire while every
// literal compared here is already lowercase (gbrain#4123). matchId is
// the folded form of modelId (modelMatchKey above).
const bareModelId = matchId.includes('/') ? matchId.split('/').pop()! : matchId;
if (bareModelId.startsWith('text-embedding-3')) {
if (isOpenAITextEmbedding3Model(bareModelId) && !isValidOpenAITextEmbedding3Dim(bareModelId, dims)) {
const max = maxOpenAITextEmbedding3Dim(bareModelId)!;
throw new AIConfigError(
`OpenAI model "${modelId}" supports embedding_dimensions in 1..${max}, got ${dims}.`,
`Use a width between 1 and ${max} (${Math.min(1024, max)} is a common default). On an existing brain a width change re-embeds; ` +
`preview it with \`gbrain migrate embeddings --to <provider>:${modelId} --dim ${Math.min(1024, max)} --dry-run\` (pages and facts are kept).`,
);
}
return { openaiCompatible: { dimensions: dims } };
}
// OpenAI-compatible routers such as OpenRouter serve Gemini embeddings
// with the same native 3072 default the header notes for
// gemini-embedding-001, so narrower brains (e.g. 1024) otherwise
// hard-fail on the first embed without explicit dimensions passthrough.
if (bareModelId.startsWith('gemini-embedding') || bareModelId === 'text-embedding-004') {
return { openaiCompatible: { dimensions: dims } };
}
// DashScope text-embedding-v3 (Matryoshka 64-1024) and Zhipu
// embedding-3 (Matryoshka 256-2048) both accept `dimensions` on the
// OpenAI-compat path. Without this, user-selected non-default dims are
// silently ignored and the provider returns its default size.
// Symmetric retrieval — inputType ignored.
if (matchId === 'text-embedding-v3' || matchId === 'embedding-3') {
return { openaiCompatible: { dimensions: dims } };
}
// Qwen3-Embedding family on Ollama (and any other openai-compatible
// provider serving it) supports Matryoshka truncation via `dimensions`.
// Native sizes: 0.6B=1024, 4B=2560, 8B=4096. Without `dimensions`,
// Ollama returns the native size and brains configured for narrower
// widths hard-fail with a dim-mismatch error. Two naming schemes reach
// this path: Ollama's colon-tag form (`qwen3-embedding:4b`) and the
// hyphenated hub form used by OpenRouter/HF-style routers
// (`qwen/qwen3-embedding-8b` — org prefix stripped to
// `qwen3-embedding-8b` above). Match both.
if (bareModelId === 'qwen3-embedding' || bareModelId.startsWith('qwen3-embedding:') || bareModelId.startsWith('qwen3-embedding-')) {
// Only send `dimensions` when it actually differs from the model's
// native width. Fixed-dim OpenAI-compatible backends serving this
// family (e.g. vLLM) reject the parameter outright with HTTP 400
// ("does not support matryoshka representation") even when the
// requested value equals the native size; omitting it in the equal
// case is semantically identical for Ollama and keeps vLLM working.
if (QWEN3_EMBEDDING_NATIVE_DIMS[bareModelId] === dims) return undefined;
return { openaiCompatible: { dimensions: dims } };
}
// MiniMax embo-01 takes a `type: 'db' | 'query'` field for asymmetric
// retrieval. Today still hardcoded to 'db' for back-compat — opting
// into the new inputType seam is a follow-up (see plan's deferred
// section "Fix MiniMax embo-01 asymmetry"). When fixed: map
// inputType==='query' → type:'query', else 'db'.
if (matchId === 'embo-01') {
return { openaiCompatible: { type: 'db' } };
}
return undefined;
}
}