From 1abbe8d5a0cb52a9264a3e2b9e8043288a2b4817 Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Sat, 9 May 2026 23:42:02 -0700 Subject: [PATCH] feat(ai): add MiniMax recipe (#148 reworked) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 11th recipe. embo-01 model, 1536 dims, $0.07/1M tokens. OpenAI-compatible at api.minimax.chat. MiniMax requires a `type: 'db' | 'query'` field for asymmetric retrieval (documents indexed with type='db', queries embedded with type='query'). gbrain has no query/document signal at the embed-call site today, so v1 defaults to type='db' for both indexing and retrieval — same vector space, symmetric similarity. Asymmetric query support is a follow-up TODO that needs the embed seam to thread query/document context. Plumbed via src/core/ai/dims.ts: dimsProviderOptions returns {openaiCompatible: {type: 'db'}} for modelId === 'embo-01'. Conservative max_batch_tokens=4096 declared (MiniMax docs don't publish the limit). Recursive halving in the gateway catches token-limit errors at runtime. Tests: bun test test/ai/ — 101/101 (6 new + 95 prior). Plan: ~/.claude/plans/ok-lets-turn-this-enumerated-sonnet.md (commit 5 of 11). Reworked from #148. Co-Authored-By: cacity <20351699+cacity@users.noreply.github.com> Co-Authored-By: Claude Opus 4.7 (1M context) --- src/core/ai/dims.ts | 8 +++++ src/core/ai/recipes/index.ts | 2 ++ src/core/ai/recipes/minimax.ts | 44 +++++++++++++++++++++++++ test/ai/recipe-minimax.test.ts | 59 ++++++++++++++++++++++++++++++++++ 4 files changed, 113 insertions(+) create mode 100644 src/core/ai/recipes/minimax.ts create mode 100644 test/ai/recipe-minimax.test.ts diff --git a/src/core/ai/dims.ts b/src/core/ai/dims.ts index d08c46053..b36561a15 100644 --- a/src/core/ai/dims.ts +++ b/src/core/ai/dims.ts @@ -58,6 +58,14 @@ export function dimsProviderOptions( if (VOYAGE_OUTPUT_DIMENSION_MODELS.has(modelId)) { return { openaiCompatible: { output_dimension: dims } }; } + // MiniMax embo-01 takes a `type: 'db' | 'query'` field for asymmetric + // retrieval. Default to 'db' (the indexing path) so embed() works for + // import. Queries also embed with type:'db', making retrieval + // symmetric. Asymmetric query support is a follow-up TODO that needs + // a query/document signal threaded through the embed seam. + if (modelId === 'embo-01') { + return { openaiCompatible: { type: 'db' } }; + } return undefined; } } diff --git a/src/core/ai/recipes/index.ts b/src/core/ai/recipes/index.ts index e7bb41b34..5bf80db40 100644 --- a/src/core/ai/recipes/index.ts +++ b/src/core/ai/recipes/index.ts @@ -16,6 +16,7 @@ import { deepseek } from './deepseek.ts'; import { groq } from './groq.ts'; import { together } from './together.ts'; import { llamaServer } from './llama-server.ts'; +import { minimax } from './minimax.ts'; const ALL: Recipe[] = [ openai, @@ -28,6 +29,7 @@ const ALL: Recipe[] = [ groq, together, llamaServer, + minimax, ]; /** Map from `provider:id` key to recipe. */ diff --git a/src/core/ai/recipes/minimax.ts b/src/core/ai/recipes/minimax.ts new file mode 100644 index 000000000..ccb0b57c5 --- /dev/null +++ b/src/core/ai/recipes/minimax.ts @@ -0,0 +1,44 @@ +import type { Recipe } from '../types.ts'; + +/** + * MiniMax (海螺AI). OpenAI-compatible /embeddings endpoint at + * api.minimax.chat. The flagship embedding model is `embo-01` (1536 dims). + * + * MiniMax's API takes an extra `type: 'db' | 'query'` field for asymmetric + * retrieval. gbrain currently has no notion of "this is a document vs a + * query" at the embed-call site (embed() takes only texts), so we default + * to `type: 'db'` for the indexing path. Queries also embed with `type: + * 'db'`, making retrieval symmetric. This sacrifices some retrieval + * quality vs. a true asymmetric setup but works correctly. A follow-up + * TODO will thread query/document context through the embed seam for + * full asymmetric support. + * + * Reference: https://www.minimaxi.com/document/guides/embeddings + */ +export const minimax: Recipe = { + id: 'minimax', + name: 'MiniMax (海螺AI)', + tier: 'openai-compat', + implementation: 'openai-compatible', + base_url_default: 'https://api.minimax.chat/v1', + auth_env: { + required: ['MINIMAX_API_KEY'], + optional: ['MINIMAX_GROUP_ID'], + setup_url: 'https://www.minimaxi.com/document/guides/embeddings', + }, + touchpoints: { + embedding: { + models: ['embo-01'], + default_dims: 1536, + cost_per_1m_tokens_usd: 0.07, + price_last_verified: '2026-05-09', + // MiniMax docs don't publish a hard batch-token cap; declare a + // conservative 4096-token budget so the gateway pre-splits before + // hitting whatever undocumented server-side limit exists. Recursive + // halving in the gateway catches token-limit errors at runtime. + max_batch_tokens: 4096, + }, + }, + setup_hint: + 'Get an API key at https://www.minimaxi.com, then `export MINIMAX_API_KEY=...`', +}; diff --git a/test/ai/recipe-minimax.test.ts b/test/ai/recipe-minimax.test.ts new file mode 100644 index 000000000..a310c4a6f --- /dev/null +++ b/test/ai/recipe-minimax.test.ts @@ -0,0 +1,59 @@ +/** + * MiniMax recipe smoke (Commit 5 of the v0.32 wave). + * + * Coverage: + * - Recipe registered with expected shape + * - default auth: MINIMAX_API_KEY → "Bearer "; missing → AIConfigError + * - dimsProviderOptions threads `type: 'db'` for embo-01 (the asymmetric + * retrieval field default) — pins the v1 indexing-only behavior + */ + +import { describe, expect, test } from 'bun:test'; +import { getRecipe } from '../../src/core/ai/recipes/index.ts'; +import { defaultResolveAuth } from '../../src/core/ai/gateway.ts'; +import { dimsProviderOptions } from '../../src/core/ai/dims.ts'; +import { AIConfigError } from '../../src/core/ai/errors.ts'; + +describe('recipe: minimax', () => { + test('registered with expected shape', () => { + const r = getRecipe('minimax'); + expect(r).toBeDefined(); + expect(r!.id).toBe('minimax'); + expect(r!.tier).toBe('openai-compat'); + expect(r!.implementation).toBe('openai-compatible'); + expect(r!.base_url_default).toBe('https://api.minimax.chat/v1'); + expect(r!.auth_env?.required).toEqual(['MINIMAX_API_KEY']); + expect(r!.auth_env?.optional).toContain('MINIMAX_GROUP_ID'); + }); + + test('embedding touchpoint declares embo-01 + 1536 dims', () => { + const r = getRecipe('minimax')!; + expect(r.touchpoints.embedding).toBeDefined(); + expect(r.touchpoints.embedding!.models).toEqual(['embo-01']); + expect(r.touchpoints.embedding!.default_dims).toBe(1536); + expect(r.touchpoints.embedding!.user_provided_models ?? false).toBe(false); + expect(r.touchpoints.embedding!.max_batch_tokens).toBe(4096); + }); + + test('default auth: MINIMAX_API_KEY set → "Bearer "', () => { + const r = getRecipe('minimax')!; + const auth = defaultResolveAuth(r, { MINIMAX_API_KEY: 'fake-mm-key' }, 'embedding'); + expect(auth.headerName).toBe('Authorization'); + expect(auth.token).toBe('Bearer fake-mm-key'); + }); + + test('default auth: missing MINIMAX_API_KEY → AIConfigError', () => { + const r = getRecipe('minimax')!; + expect(() => defaultResolveAuth(r, {}, 'embedding')).toThrow(AIConfigError); + }); + + test('dimsProviderOptions threads type:db for embo-01', () => { + const opts = dimsProviderOptions('openai-compatible', 'embo-01', 1536); + expect(opts).toEqual({ openaiCompatible: { type: 'db' } }); + }); + + test('dimsProviderOptions returns undefined for non-MiniMax openai-compat models', () => { + expect(dimsProviderOptions('openai-compatible', 'voyage-3-lite', 512)).toBeUndefined(); + expect(dimsProviderOptions('openai-compatible', 'nomic-embed-text', 768)).toBeUndefined(); + }); +});