@molecule/api-ai-minimax 1.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +188 -0
- package/dist/provider.d.ts.map +1 -1
- package/dist/provider.js +39 -5
- package/package.json +14 -8
package/README.md
ADDED
|
@@ -0,0 +1,188 @@
|
|
|
1
|
+
<!--
|
|
2
|
+
AUTO-GENERATED — DO NOT EDIT THIS FILE.
|
|
3
|
+
Generated by `mlcl sync-docs` from the package's src/index.ts JSDoc + mlcl/registry.json.
|
|
4
|
+
Edits here are overwritten on the next commit (molecule's pre-commit hook regenerates).
|
|
5
|
+
To change this document, edit the module-level JSDoc in src/index.ts.
|
|
6
|
+
Generated: 2026-08-04T01:47:34.069Z
|
|
7
|
+
-->
|
|
8
|
+
|
|
9
|
+
# @molecule/api-ai-minimax
|
|
10
|
+
|
|
11
|
+
> **Auto-generated, AI-first package reference** for the [molecule.dev](https://molecule.dev) ecosystem.
|
|
12
|
+
> It is written to be read by coding agents as much as by people, and is generated from this
|
|
13
|
+
> package's source — edit `src/index.ts` JSDoc, not this file.
|
|
14
|
+
|
|
15
|
+
MiniMax AI provider for molecule.dev.
|
|
16
|
+
|
|
17
|
+
## Type
|
|
18
|
+
|
|
19
|
+
`provider`
|
|
20
|
+
|
|
21
|
+
## Installation
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npm install @molecule/api-ai-minimax @molecule/api-ai @molecule/api-bond @molecule/api-i18n @molecule/api-secrets
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## API
|
|
28
|
+
|
|
29
|
+
### Interfaces
|
|
30
|
+
|
|
31
|
+
#### `MiniMaxConfig`
|
|
32
|
+
|
|
33
|
+
Configuration for MiniMax.
|
|
34
|
+
|
|
35
|
+
```typescript
|
|
36
|
+
interface MiniMaxConfig {
|
|
37
|
+
/** Called on each rate-limited/overloaded upstream response, before any retry sleep. */
|
|
38
|
+
onRateLimit?: AiRateLimitCallback
|
|
39
|
+
/** API key. Defaults to MINIMAX_API_KEY env var. */
|
|
40
|
+
apiKey?: string
|
|
41
|
+
/** Default model. Defaults to 'minimax-m3'. */
|
|
42
|
+
defaultModel?: string
|
|
43
|
+
/** Maximum tokens for completions. */
|
|
44
|
+
maxTokens?: number
|
|
45
|
+
/** Base URL override (for proxies). Defaults to 'https://api.minimax.io' (MiniMax's INTERNATIONAL host; use 'https://api.minimaxi.com' for mainland China — keys are scoped per host). */
|
|
46
|
+
baseUrl?: string
|
|
47
|
+
/**
|
|
48
|
+
* Chat-completions path appended to {@link baseUrl}. Defaults to
|
|
49
|
+
* `/v1/chat/completions` (MiniMax-direct puts the version in the path). Set
|
|
50
|
+
* this when the same open-weight model is served by a US OpenAI-compatible
|
|
51
|
+
* host whose version prefix lives in the base URL instead — e.g. DeepInfra:
|
|
52
|
+
* `baseUrl='https://api.deepinfra.com/v1/openai'` + `completionsPath='/chat/completions'`.
|
|
53
|
+
*/
|
|
54
|
+
completionsPath?: string
|
|
55
|
+
/**
|
|
56
|
+
* Optional catalog-id → upstream-model-id map, applied to the outbound request
|
|
57
|
+
* ONLY. Lets a US OpenAI-compatible host (DeepInfra) receive its namespaced id
|
|
58
|
+
* (`MiniMaxAI/MiniMax-M3`) while the rest of the platform — pricing, cost
|
|
59
|
+
* ceilings, display — keeps using the canonical catalog id (`minimax-m3`). An
|
|
60
|
+
* id not in the map passes through unchanged.
|
|
61
|
+
*/
|
|
62
|
+
modelMap?: Record<string, string>
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
#### `ProcessEnv`
|
|
67
|
+
|
|
68
|
+
Process Env interface.
|
|
69
|
+
|
|
70
|
+
```typescript
|
|
71
|
+
interface ProcessEnv {
|
|
72
|
+
MINIMAX_API_KEY: string
|
|
73
|
+
/** Base URL override (for credential brokers / gateways / US OpenAI-compatible hosts). */
|
|
74
|
+
MINIMAX_BASE_URL?: string
|
|
75
|
+
/** Chat-completions path override (see {@link MiniMaxConfig.completionsPath}). */
|
|
76
|
+
MINIMAX_COMPLETIONS_PATH?: string
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
### Functions
|
|
81
|
+
|
|
82
|
+
#### `createProvider(config)`
|
|
83
|
+
|
|
84
|
+
Creates a MiniMax AI provider instance.
|
|
85
|
+
|
|
86
|
+
```typescript
|
|
87
|
+
function createProvider(config?: MiniMaxConfig): AIProvider
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
- `config` — MiniMax-specific configuration (API key, model, max tokens, base URL).
|
|
91
|
+
|
|
92
|
+
**Returns:** An `AIProvider` backed by the MiniMax Chat Completions API.
|
|
93
|
+
|
|
94
|
+
### Constants
|
|
95
|
+
|
|
96
|
+
#### `aiMinimaxSecretDefinitions`
|
|
97
|
+
|
|
98
|
+
Secret definitions required by the MiniMax AI bond.
|
|
99
|
+
|
|
100
|
+
```typescript
|
|
101
|
+
const aiMinimaxSecretDefinitions: SecretDefinition[]
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
#### `provider`
|
|
105
|
+
|
|
106
|
+
The provider implementation.
|
|
107
|
+
|
|
108
|
+
```typescript
|
|
109
|
+
const provider: AIProvider
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
## Core Interface
|
|
113
|
+
|
|
114
|
+
Implements `@molecule/api-ai` interface.
|
|
115
|
+
|
|
116
|
+
## Bond Wiring
|
|
117
|
+
|
|
118
|
+
Setup function to register this provider with the bond system:
|
|
119
|
+
|
|
120
|
+
```typescript
|
|
121
|
+
import { bond } from '@molecule/api-bond'
|
|
122
|
+
import { provider } from '@molecule/api-ai-minimax'
|
|
123
|
+
|
|
124
|
+
export function setupAiMinimax(): void {
|
|
125
|
+
bond('ai', 'minimax', provider)
|
|
126
|
+
}
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
## Injection Notes
|
|
130
|
+
|
|
131
|
+
### Requirements
|
|
132
|
+
|
|
133
|
+
Peer dependencies:
|
|
134
|
+
|
|
135
|
+
- `@molecule/api-ai` ^1.0.1
|
|
136
|
+
- `@molecule/api-bond` ^1.0.1
|
|
137
|
+
- `@molecule/api-i18n` ^1.0.1
|
|
138
|
+
- `@molecule/api-secrets` ^1.0.1
|
|
139
|
+
|
|
140
|
+
### Environment Variables
|
|
141
|
+
|
|
142
|
+
- `MINIMAX_API_KEY` _(required)_ — MiniMax API key
|
|
143
|
+
- Setup: Create an interface key in the MiniMax platform user center.
|
|
144
|
+
- Get it here: [https://platform.minimax.io/](https://platform.minimax.io/)
|
|
145
|
+
|
|
146
|
+
### Runtime Dependencies
|
|
147
|
+
|
|
148
|
+
- `@molecule/api-ai`
|
|
149
|
+
- `@molecule/api-bond`
|
|
150
|
+
- `@molecule/api-i18n`
|
|
151
|
+
- `@molecule/api-secrets`
|
|
152
|
+
|
|
153
|
+
Config: `MINIMAX_API_KEY` (SERVER-side only) plus an optional default model id/base URL.
|
|
154
|
+
|
|
155
|
+
**Missing `MINIMAX_API_KEY` fails fast**: the provider throws naming the exact env var on
|
|
156
|
+
first use (the exported `provider` is a lazy proxy, so this fires on the first `chat()` call,
|
|
157
|
+
not at bond/module-load time) — it never silently sends an empty key.
|
|
158
|
+
|
|
159
|
+
**Error message disambiguation**: a plain 400 that ISN'T a context-length error (bad param,
|
|
160
|
+
malformed tool schema) gets its own non-retryable message distinct from the generic
|
|
161
|
+
"AI service error. Please try again." used for retryable failures.
|
|
162
|
+
|
|
163
|
+
## E2E Tests
|
|
164
|
+
|
|
165
|
+
Integration checklist — drive the real UI (live preview, no mocks), adapt
|
|
166
|
+
each item to this app's actual chat/AI screens, and check every box off one
|
|
167
|
+
by one. A box you can't check is an integration bug to fix — not a skip. The
|
|
168
|
+
sandbox HAS an AI provider bonded, so the flow runs live end-to-end; AI
|
|
169
|
+
output is NON-DETERMINISTIC, so assert on STRUCTURE/behavior, not exact text:
|
|
170
|
+
|
|
171
|
+
- [ ] A message sent through the real chat UI comes back as a RELEVANT AI
|
|
172
|
+
reply — not an echo of the prompt, a hardcoded stub, or an empty bubble.
|
|
173
|
+
Ask something with a checkable answer (e.g. "What is 2 + 2?") and confirm
|
|
174
|
+
the response actually contains it ("4"), proving a live model answered.
|
|
175
|
+
- [ ] If the app streams, tokens render INCREMENTALLY — text grows word by
|
|
176
|
+
word in the UI, not one final blob dumped after a long frozen spinner. (A
|
|
177
|
+
streamed `chat()` yields `text` chunks then a final `done`; a single late
|
|
178
|
+
blob means the reply was awaited whole and streaming is broken.)
|
|
179
|
+
- [ ] Multi-turn CONTEXT is preserved: a follow-up that refers back to the
|
|
180
|
+
previous turn (e.g. after "2 + 2", ask "now double that" -> understood as 8) works — proving the full `messages` history is sent, not just the last
|
|
181
|
+
line.
|
|
182
|
+
- [ ] A provider failure (bad/missing key, rate limit, timeout) surfaces as
|
|
183
|
+
a graceful in-UI error message, NOT a crash, blank screen, a spinner that
|
|
184
|
+
never resolves, or an unhandled 500. Force one and watch the UI recover.
|
|
185
|
+
- [ ] The provider key + the provider call are SERVER-side only: the key
|
|
186
|
+
never reaches the browser (check the network tab, the JS bundle, and page
|
|
187
|
+
globals), and no route proxies arbitrary prompts to the model without auth
|
|
188
|
+
- a token cap — an open AI endpoint is an unbounded bill and abuse vector.
|
package/dist/provider.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,UAAU,EAOX,MAAM,kBAAkB,CAAA;AASzB,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;
|
|
1
|
+
{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,UAAU,EAOX,MAAM,kBAAkB,CAAA;AASzB,OAAO,cAAc,CAAA;AAErB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AA+oB/C;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,UAAU,CAEjE"}
|
package/dist/provider.js
CHANGED
|
@@ -72,7 +72,12 @@ class MiniMaxAIProvider {
|
|
|
72
72
|
const canonicalModel = params.model ?? this.defaultModel;
|
|
73
73
|
const model = this.modelMap[canonicalModel] ?? canonicalModel;
|
|
74
74
|
const maxTokens = params.maxTokens ?? this.maxTokens;
|
|
75
|
-
const messages = this.formatMessages(params.messages, params.system, params.cacheControl
|
|
75
|
+
const messages = this.formatMessages(params.messages, params.system, params.cacheControl,
|
|
76
|
+
// M3 is natively multimodal (M2.x is text-only) — forward image blocks
|
|
77
|
+
// for it; both the native host and the DeepInfra re-host accept the
|
|
78
|
+
// OpenAI image_url data-URI form. Gate on the CANONICAL id: the mapped
|
|
79
|
+
// upstream id never matches the family anchor.
|
|
80
|
+
isM3Family(canonicalModel));
|
|
76
81
|
const body = {
|
|
77
82
|
// Abuse attribution (see ChatParams.endUserId): OpenAI-compatible APIs
|
|
78
83
|
// scope enforcement by `user`, so an abusive tenant can be actioned
|
|
@@ -91,14 +96,33 @@ class MiniMaxAIProvider {
|
|
|
91
96
|
const allTools = [...functions, ...serverTools];
|
|
92
97
|
if (allTools.length > 0) {
|
|
93
98
|
body.tools = allTools;
|
|
99
|
+
// Honor forced tool choice (discovery mode relies on it — an unenforced
|
|
100
|
+
// 'required' lets the model narrate the call as text instead of emitting
|
|
101
|
+
// tool_use). OpenAI-compatible forms; 'auto' is the API default → omit.
|
|
102
|
+
if (params.toolChoice === 'required') {
|
|
103
|
+
body.tool_choice = 'required';
|
|
104
|
+
}
|
|
105
|
+
else if (typeof params.toolChoice === 'object' && params.toolChoice.type === 'tool') {
|
|
106
|
+
body.tool_choice = { type: 'function', function: { name: params.toolChoice.name } };
|
|
107
|
+
}
|
|
94
108
|
}
|
|
95
109
|
// MiniMax's native API has no reasoning_effort / thinking budget. M3 takes
|
|
96
110
|
// `thinking: {type: "adaptive" | "disabled"}` (the OpenAI-compatible
|
|
97
111
|
// endpoint defaults to adaptive when omitted); M2.x thinking is always on
|
|
98
112
|
// and takes no param. Synthase runs M3 as a non-thinking executor (like
|
|
99
113
|
// DeepSeek), so explicitly disable unless thinking was requested.
|
|
100
|
-
|
|
114
|
+
// Family-gate on the CANONICAL id: `model` is the mapped upstream id on
|
|
115
|
+
// re-hosts (`MiniMaxAI/MiniMax-M3`), which the `minimax-m3` anchor never
|
|
116
|
+
// matches — that omission left thinking defaulted ON for every US turn.
|
|
117
|
+
if (isM3Family(canonicalModel)) {
|
|
101
118
|
body.thinking = { type: params.thinking ? 'adaptive' : 'disabled' };
|
|
119
|
+
if (!params.thinking) {
|
|
120
|
+
// Open-weights re-hosts (DeepInfra) IGNORE the native `thinking` param
|
|
121
|
+
// and default reasoning ON — only `chat_template_kwargs.enable_thinking`
|
|
122
|
+
// reaches the template there. The native host accepts both together
|
|
123
|
+
// (verified live 2026-08-28), so send both and each host honors its own.
|
|
124
|
+
body.chat_template_kwargs = { enable_thinking: false };
|
|
125
|
+
}
|
|
102
126
|
}
|
|
103
127
|
// Keep thinking out of the visible message: with reasoning_split, thinking
|
|
104
128
|
// arrives in `reasoning_content` (parsed below) instead of inline
|
|
@@ -212,15 +236,17 @@ class MiniMaxAIProvider {
|
|
|
212
236
|
/**
|
|
213
237
|
* Converts internal `ChatMessage` objects to the OpenAI-compatible message format.
|
|
214
238
|
* System prompt is prepended as a system role message.
|
|
215
|
-
*
|
|
239
|
+
* Image blocks are forwarded only for vision-capable models (M3 family);
|
|
240
|
+
* text-only M2.x models get them skipped.
|
|
216
241
|
*
|
|
217
242
|
* @param messages - The chat messages to format.
|
|
218
243
|
* @param system - Optional system prompt to prepend.
|
|
219
244
|
* @param cacheControl - Optional cache hint for the system prompt block.
|
|
220
245
|
* @param cacheControl.type - Ephemeral cache policy label expected by MiniMax.
|
|
246
|
+
* @param supportsImages - Whether the target model accepts image input.
|
|
221
247
|
* @returns The formatted messages array for the MiniMax API.
|
|
222
248
|
*/
|
|
223
|
-
formatMessages(messages, system, cacheControl) {
|
|
249
|
+
formatMessages(messages, system, cacheControl, supportsImages = false) {
|
|
224
250
|
const formatted = [];
|
|
225
251
|
if (system) {
|
|
226
252
|
if (cacheControl) {
|
|
@@ -251,7 +277,15 @@ class MiniMaxAIProvider {
|
|
|
251
277
|
parts.push({ type: 'text', text: block.text });
|
|
252
278
|
break;
|
|
253
279
|
case 'image':
|
|
254
|
-
//
|
|
280
|
+
// M3 family is natively multimodal; M2.x is text-only. Dropping an
|
|
281
|
+
// image SILENTLY (the pre-M3 behavior for every model) made the
|
|
282
|
+
// model answer blind to attachments with no error anywhere.
|
|
283
|
+
if (supportsImages) {
|
|
284
|
+
parts.push({
|
|
285
|
+
type: 'image_url',
|
|
286
|
+
image_url: { url: `data:${block.mediaType};base64,${block.data}` },
|
|
287
|
+
});
|
|
288
|
+
}
|
|
255
289
|
break;
|
|
256
290
|
case 'tool_use':
|
|
257
291
|
toolCalls.push({
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@molecule/api-ai-minimax",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "MiniMax AI provider for molecule.dev",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -17,7 +17,8 @@
|
|
|
17
17
|
}
|
|
18
18
|
},
|
|
19
19
|
"files": [
|
|
20
|
-
"dist"
|
|
20
|
+
"dist",
|
|
21
|
+
"README.md"
|
|
21
22
|
],
|
|
22
23
|
"keywords": [
|
|
23
24
|
"molecule",
|
|
@@ -25,18 +26,23 @@
|
|
|
25
26
|
"minimax"
|
|
26
27
|
],
|
|
27
28
|
"license": "Apache-2.0",
|
|
29
|
+
"repository": {
|
|
30
|
+
"type": "git",
|
|
31
|
+
"url": "https://github.com/molecule-dev/molecule.git",
|
|
32
|
+
"directory": "packages/api/bonds/ai/minimax"
|
|
33
|
+
},
|
|
28
34
|
"devDependencies": {
|
|
29
|
-
"@molecule/api-ai": "1.
|
|
30
|
-
"@molecule/api-bond": "1.0.
|
|
35
|
+
"@molecule/api-ai": "1.2.0",
|
|
36
|
+
"@molecule/api-bond": "1.0.1",
|
|
31
37
|
"@types/node": "26.1.2",
|
|
32
38
|
"typescript": "6.0.3",
|
|
33
39
|
"vitest": "4.1.10"
|
|
34
40
|
},
|
|
35
41
|
"peerDependencies": {
|
|
36
|
-
"@molecule/api-ai": "^1.0.
|
|
37
|
-
"@molecule/api-bond": "^1.0.
|
|
38
|
-
"@molecule/api-i18n": "^1.0.
|
|
39
|
-
"@molecule/api-secrets": "^1.0.
|
|
42
|
+
"@molecule/api-ai": "^1.0.1",
|
|
43
|
+
"@molecule/api-bond": "^1.0.1",
|
|
44
|
+
"@molecule/api-i18n": "^1.0.1",
|
|
45
|
+
"@molecule/api-secrets": "^1.0.1"
|
|
40
46
|
},
|
|
41
47
|
"peerDependenciesMeta": {
|
|
42
48
|
"@molecule/api-ai": {
|