Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Parse and validate `provider:model` strings against the recipe registry.
*/
import type { ParsedModelId, Recipe, TouchpointKind, ChatTouchpoint, EmbeddingTouchpoint, ExpansionTouchpoint, RerankerTouchpoint } from './types.ts';
import { getRecipe, RECIPES } from './recipes/index.ts';
import { AIConfigError } from './errors.ts';
import { renderCanonicalMigrationCommands } from './defaults.ts';
/**
* Split "openai:text-embedding-3-large" or "openai/text-embedding-3-large"
* into { providerId, modelId }. Colon takes precedence so OpenRouter nested
* ids like "openrouter:anthropic/claude-sonnet-4-6" route as
* { providerId: 'openrouter', modelId: 'anthropic/claude-sonnet-4-6' }.
*
* v0.41.21.0: slash form added so users typing `anthropic/claude-sonnet-4-6`
* (the form OpenRouter recipes emit and CLI `--judge-model` accepts) reach
* the gateway successfully. Pre-fix the colon-only check threw at every
* gateway entry point (chat / embed / rerank), so a slash-form id passed
* pricing checks via splitProviderModelId in `src/core/model-id.ts` and
* then died here at the gateway resolver. Closes the end-to-end bug class.
*
* Bare names without ANY separator still throw — `claude-sonnet-4-6` alone
* doesn't tell us which provider to route through.
*/
export function parseModelId(id: string): ParsedModelId {
if (!id || typeof id !== 'string') {
throw new AIConfigError(
`Invalid model id: ${JSON.stringify(id)}`,
'Expected format: provider:model (e.g. openai:text-embedding-3-large)',
);
}
// Colon wins over slash (OpenRouter nested-id semantic).
const colon = id.indexOf(':');
let sepIdx: number;
if (colon !== -1) {
sepIdx = colon;
} else {
const slash = id.indexOf('/');
if (slash === -1) {
throw new AIConfigError(
`Model id "${id}" is missing a provider prefix.`,
'Use format provider:model (preferred) or provider/model, e.g. openai:text-embedding-3-large',
);
}
sepIdx = slash;
}
const providerId = id.slice(0, sepIdx).trim().toLowerCase();
const modelId = id.slice(sepIdx + 1).trim();
if (!providerId || !modelId) {
throw new AIConfigError(
`Model id "${id}" has empty provider or model.`,
'Use format provider:model, e.g. openai:text-embedding-3-large',
);
}
return { providerId, modelId };
}
/**
* Resolve a `provider:model` string to a Recipe + canonical modelId.
* Honors `recipe.aliases` (Codex F-OV-5) so users can pass undated forms.
* Throws AIConfigError if unknown provider.
*/
export function resolveRecipe(modelId: string): { parsed: ParsedModelId; recipe: Recipe } {
const parsed = parseModelId(modelId);
const recipe = getRecipe(parsed.providerId);
if (!recipe) {
throw new AIConfigError(
`Unknown provider: "${parsed.providerId}"`,
`Known providers: ${[...knownProviderIds()].join(', ')}. For stored embeddings, run gbrain migrate embeddings --status and preview an explicit migration with ${renderCanonicalMigrationCommands().recommendedDryRun}. Do not relabel existing vectors or change only the configured model. For reranking, select a supported model with gbrain config set search.reranker.model voyage:rerank-2.5.`,
);
}
// Apply alias if the modelId matches an alias key. Canonical wins.
const canonical = recipe.aliases?.[parsed.modelId];
if (canonical) {
return { parsed: { providerId: parsed.providerId, modelId: canonical }, recipe };
}
return { parsed, recipe };
}
/**
* Resolve the declared chat context window for a provider-qualified model.
* Model-specific recipe metadata wins over the provider-wide default.
* Returns undefined when the provider has no chat context declaration.
*/
export function resolveChatContextTokens(modelId: string): number | undefined {
const { parsed, recipe } = resolveRecipe(modelId);
const chat = recipe.touchpoints.chat;
return chat?.model_context_tokens?.[parsed.modelId] ?? chat?.max_context_tokens;
}
type KnownTouchpointKey = 'embedding' | 'expansion' | 'chat' | 'reranker';
function getTouchpoint(recipe: Recipe, touchpoint: TouchpointKind): EmbeddingTouchpoint | ExpansionTouchpoint | ChatTouchpoint | RerankerTouchpoint | undefined {
if (touchpoint === 'embedding' || touchpoint === 'expansion' || touchpoint === 'chat' || touchpoint === 'reranker') {
return recipe.touchpoints[touchpoint as KnownTouchpointKey];
}
return undefined;
}
/**
* Assert the resolved recipe actually offers the requested touchpoint.
*
* This checks the PROVIDER's capability (anthropic has no embeddings; voyage
* has no chat), never the model id. Recipe `models:` arrays are informational
* — defaults for `--model <provider>` shorthand, guard-test fixtures for the
* repo's own hardcoded defaults, display in `gbrain providers list` — not a
* runtime allowlist. Frontier models ship weekly; any id the user names goes
* to the provider, and a nonexistent one surfaces as the provider's own
* `model_not_found` at call time (`gbrain models doctor` probes the configured
* models live for a pre-flight check).
*/
export function assertTouchpoint(
recipe: Recipe,
touchpoint: TouchpointKind,
modelId: string,
): void {
const tp = getTouchpoint(recipe, touchpoint);
if (!tp) {
throw new AIConfigError(
`Provider "${recipe.id}" does not support touchpoint "${touchpoint}".`,
touchpoint === 'embedding' && recipe.id === 'anthropic'
? 'Anthropic has no embedding model. Use openai or google for embeddings.'
: touchpoint === 'chat' && recipe.id === 'voyage'
? `${recipe.name} is configured here only for embeddings. Use openai/anthropic/google/deepseek/groq/together for chat.`
: undefined,
);
}
}
export function knownProviderIds(): string[] {
return [...RECIPES.keys()];
}
/**
* Native embedding width for `modelId` under `recipe`.
*
* Resolution: the recipe's `model_dims` entry for this model, else the
* recipe-wide `default_dims`. Returns 0 when neither is known (the
* user-provided-model recipes declare `default_dims: 0` to force an explicit
* `--embedding-dimensions`), so callers keep their existing falsy checks.
*
* Accepts a bare model id (`bge-m3`, or one that itself contains a colon
* like Ollama's pullable tag `qwen3-embedding:8b`) or a qualified one
* (`ollama:bge-m3`, `ollama:qwen3-embedding:8b`); the id is tried as-is
* first, then with a leading `provider:` prefix stripped, so call sites can
* pass whichever they hold without a bare model-internal colon being
* mistaken for the provider separator (#3904).
*
* Fixes #2051: a recipe-wide default silently picked 768 for every Ollama
* model, so `init --embedding-model ollama:bge-m3` built a 768-wide column
* for a model that emits 1024 and only failed at first insert.
*/
export function embeddingDimsForModel(
recipe: Recipe,
modelId: string | undefined,
): number {
const tp = recipe.touchpoints.embedding;
if (!tp) return 0;
if (!modelId) return tp.default_dims ?? 0;
// Try the id exactly as given first. This covers bare model ids that
// themselves contain a colon (e.g. Ollama's `qwen3-embedding:8b` pullable
// tag) — stripping the FIRST colon unconditionally would mistake the
// model's own colon for a `provider:` separator and truncate it.
let declared = lookupDims(tp.model_dims, modelId);
if (typeof declared !== 'number') {
// Strip a leading `provider:` so the qualified form also resolves.
// Slash-form ids (openrouter nested) are left intact — they're the model id.
const colon = modelId.indexOf(':');
const bare = colon === -1 ? modelId : modelId.slice(colon + 1);
declared = lookupDims(tp.model_dims, bare);
}
if (typeof declared === 'number' && declared > 0) return declared;
return tp.default_dims ?? 0;
}
// #4123: fold BOTH sides — configured ids arrive cased (`ollama:Qwen3-Embed-8B`)
// and user-editable recipe model_dims tables can carry cased keys too.
// Exact match first (zero behavior change for today's all-lowercase
// tables), then a case-insensitive scan. Without this, a cased id fell
// through to default_dims and `gbrain init` built a wrong-width column.
function lookupDims(
table: Record<string, number> | undefined,
key: string,
): number | undefined {
if (!table) return undefined;
const exact = table[key];
if (typeof exact === 'number') return exact;
const keyFolded = key.toLowerCase();
for (const [k, v] of Object.entries(table)) {
if (k.toLowerCase() === keyFolded) return v;
}
return undefined;
}