Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
15.6 KB
Raw Blame
/**
 * 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;
  }
}