Open History to see the last commit
1/**
2 * How a caller turns a shared chat intent into one provider's request body
3 * (issue #95). `reasoning` stays the readable fact. This object is the wire
4 * map. Unverified providers and non-chat rows are null — no guessed body.
5 * Unverified flags inside a verified map are null, not a default.
6 */
7
8export const SHARED_EFFORT_LEVELS = [
9 'off',
10 'minimal',
11 'low',
12 'medium',
13 'high',
14 'xhigh',
15 'max',
16] as const
17
18export type SharedEffortLevel = (typeof SHARED_EFFORT_LEVELS)[number]
19
20/** Value this model accepts for a shared level. null means omit the field. */
21export type EffortLevelMap = Record<SharedEffortLevel, string | null>
22
23export interface ThinkingRequest {
24 /** Request body for "thinking on, effort high". */
25 on: Record<string, unknown>
26 /** Explicit off, when silence would make the model think. */
27 off: Record<string, unknown> | null
28 /** Shared levels → the value this model accepts. null when unverified. */
29 levels: EffortLevelMap | null
30}
31
32export interface ChatRequestMap {
33 thinking: ThinkingRequest | null
34 maxTokensField: 'max_completion_tokens' | 'max_tokens' | null
35 /** True when the model wants `role: "developer"`; false when it rejects it. */
36 developerRole: boolean | null
37 replayReasoningContent: boolean | null
38 store: boolean | null
39 strictTools: boolean | null
40 sessionAffinity: boolean | null
41 cacheControl: 'anthropic' | null
42 toolStream: boolean | null
43 /** False when the provider rejects a top-level `reasoning_effort` field. */
44 reasoningEffort: boolean | null
45}
46
47const OPENAI_ON = { reasoning_effort: 'high' }
48const DEEPSEEK_ON = {
49 thinking: { type: 'enabled' },
50 reasoning_effort: 'high',
51}
52const DEEPSEEK_OFF = { thinking: { type: 'disabled' } }
53const GLM_ON = { thinking: { type: 'enabled', clear_thinking: false } }
54const GLM_OFF = { thinking: { type: 'disabled' } }
55const QWEN_ON = { enable_thinking: true }
56const VLLM_QWEN_ON = {
57 chat_template_kwargs: { enable_thinking: true, preserve_thinking: true },
58}
59const KIMI_ON = { thinking: { type: 'enabled' } }
60const KIMI_OFF = { thinking: { type: 'disabled' } }
61const MINIMAX_ON = { thinking: { type: 'adaptive' } }
62const MINIMAX_OFF = { thinking: { type: 'disabled' } }
63
64/** `openai/gpt-5.1`: off is sent as "none"; minimal, xhigh, and max are omitted. */
65const GPT_51_LEVELS: EffortLevelMap = {
66 off: 'none',
67 minimal: null,
68 low: 'low',
69 medium: 'medium',
70 high: 'high',
71 xhigh: null,
72 max: null,
73}
74
75/**
76 * SambaNova `ChatCompletionRequest.reasoning_effort`: low, medium, high.
77 * The enum has no off.
78 * https://raw.githubusercontent.com/sambanova/sambanova-inference-api-spec/refs/heads/main/openapi.documented.json
79 */
80const SAMBANOVA_LEVELS: EffortLevelMap = {
81 off: null,
82 minimal: null,
83 low: 'low',
84 medium: 'medium',
85 high: 'high',
86 xhigh: null,
87 max: null,
88}
89
90/** `minimax/MiniMax-M3.1-Flash-Preview`: the spec's `reasoning_effort` enum. It cannot stop thinking. */
91const MINIMAX_M31_FLASH_LEVELS: EffortLevelMap = {
92 off: null,
93 minimal: null,
94 low: 'low',
95 medium: 'medium',
96 high: 'high',
97 xhigh: 'xhigh',
98 max: 'max',
99}
100
101/** `deepseek/deepseek-flash`: only low, high, and max. medium is omitted. */
102const DEEPSEEK_FLASH_LEVELS: EffortLevelMap = {
103 off: null,
104 minimal: null,
105 low: 'low',
106 medium: null,
107 high: 'high',
108 xhigh: null,
109 max: 'max',
110}
111
112/** `kimi-k3`: the spec's `reasoning_effort` enum. It cannot stop thinking. */
113const KIMI_K3_LEVELS: EffortLevelMap = {
114 off: null,
115 minimal: null,
116 low: 'low',
117 medium: null,
118 high: 'high',
119 xhigh: null,
120 max: 'max',
121}
122
123/**
124 * Moonshot's per-model chat schemas, by exact id: `kimi-k3` takes
125 * `reasoning_effort` and always thinks, `kimi-k2.7-code` takes only
126 * `thinking.type: enabled`, `kimi-k2.6` also takes `disabled`. An id the
127 * spec does not map stays null.
128 */
129function kimiThinking(rawId: string): ThinkingRequest | null {
130 switch (rawId) {
131 case 'kimi-k3':
132 return { on: OPENAI_ON, off: null, levels: KIMI_K3_LEVELS }
133 case 'kimi-k2.7-code':
134 case 'kimi-k2.7-code-highspeed':
135 return { on: KIMI_ON, off: null, levels: null }
136 case 'kimi-k2.6':
137 return { on: KIMI_ON, off: KIMI_OFF, levels: null }
138 default:
139 return null
140 }
141}
142
143/** `zai/glm-5.2`: only high and max. */
144const GLM_52_LEVELS: EffortLevelMap = {
145 off: null,
146 minimal: null,
147 low: null,
148 medium: null,
149 high: 'high',
150 xhigh: null,
151 max: 'max',
152}
153
154/**
155 * `zai/glm-5.3` and `glm-5.3-flash`: only low, high, and max; any other
156 * value is an error (docs.z.ai/guides/capabilities/thinking).
157 */
158const GLM_53_LEVELS: EffortLevelMap = {
159 off: null,
160 minimal: null,
161 low: 'low',
162 medium: null,
163 high: 'high',
164 xhigh: null,
165 max: 'max',
166}
167
168/**
169 * Series the Z.AI spec names under `tool_stream`
170 * (docs.z.ai/openapi.json, ChatCompletionTextRequest). The vision request
171 * has no such field; for `glm-5.3-flash` and `glm-5.3-flashx` the source is
172 * docs.z.ai/guides/vlm/glm-5.3-flash ("enabling both stream: true and
173 * `tool_stream: true`").
174 */
175const GLM_TOOL_STREAM = [
176 'glm-5.3',
177 'glm-5.2',
178 'glm-5.1',
179 'glm-5',
180 'glm-4.7',
181 'glm-4.6',
182]
183
184function blank(partial: Partial<ChatRequestMap>): ChatRequestMap {
185 return {
186 thinking: null,
187 maxTokensField: null,
188 developerRole: null,
189 replayReasoningContent: null,
190 store: null,
191 strictTools: null,
192 sessionAffinity: null,
193 cacheControl: null,
194 toolStream: null,
195 reasoningEffort: null,
196 ...partial,
197 }
198}
199
200function bareId(rawId: string): string {
201 const slash = rawId.lastIndexOf('/')
202 return slash === -1 ? rawId : rawId.slice(slash + 1)
203}
204
205function matches(rawId: string, name: string): boolean {
206 const bare = bareId(rawId)
207 return bare === name || bare.startsWith(`${name}-`)
208}
209
210function levelsFor(providerId: string, rawId: string): EffortLevelMap | null {
211 if (providerId === 'openai' && matches(rawId, 'gpt-5.1')) return GPT_51_LEVELS
212 if (
213 (providerId === 'minimax' || providerId === 'minimax-cn') &&
214 matches(rawId, 'MiniMax-M3.1-Flash-Preview')
215 ) {
216 return MINIMAX_M31_FLASH_LEVELS
217 }
218 if (providerId === 'deepseek' && matches(rawId, 'deepseek-flash')) {
219 return DEEPSEEK_FLASH_LEVELS
220 }
221 if (providerId === 'zai' || providerId === 'glm') {
222 if (matches(rawId, 'glm-5.2')) return GLM_52_LEVELS
223 if (matches(rawId, 'glm-5.3')) return GLM_53_LEVELS
224 }
225 return null
226}
227
228function withLevels(
229 thinking: ThinkingRequest,
230 providerId: string,
231 rawId: string,
232): ThinkingRequest {
233 const levels = levelsFor(providerId, rawId)
234 return levels === null ? thinking : { ...thinking, levels }
235}
236
237/**
238 * Provider-wide request facts for one chat model. Model-specific level maps
239 * override the provider's `thinking.levels`. Anything not verified stays null.
240 */
241export function chatRequestMap(
242 providerId: string,
243 rawId: string,
244 activity: string | null | undefined,
245): ChatRequestMap | null {
246 if (activity !== 'chat') return null
247 switch (providerId) {
248 case 'openai':
249 return blank({
250 thinking: withLevels(
251 { on: OPENAI_ON, off: null, levels: null },
252 providerId,
253 rawId,
254 ),
255 maxTokensField: 'max_completion_tokens',
256 developerRole: true,
257 reasoningEffort: true,
258 })
259 case 'deepseek':
260 return blank({
261 thinking: withLevels(
262 { on: DEEPSEEK_ON, off: DEEPSEEK_OFF, levels: null },
263 providerId,
264 rawId,
265 ),
266 maxTokensField: 'max_tokens',
267 developerRole: false,
268 replayReasoningContent: true,
269 reasoningEffort: true,
270 })
271 case 'zai':
272 case 'glm':
273 return blank({
274 // The spec's `thinking` is "GLM-4.5 series and higher" only, and
275 // `thinking.type` is enabled | disabled, except that the GLM-5.3
276 // and GLM-5.3-FLASH series "can only be enabled".
277 thinking: matches(rawId, 'glm-4-32b')
278 ? null
279 : withLevels(
280 {
281 on: GLM_ON,
282 off: matches(rawId, 'glm-5.3') ? null : GLM_OFF,
283 levels: null,
284 },
285 providerId,
286 rawId,
287 ),
288 maxTokensField: 'max_tokens',
289 developerRole: false,
290 toolStream: GLM_TOOL_STREAM.some((name) => matches(rawId, name))
291 ? true
292 : null,
293 // `reasoning_effort` is "supported by GLM-5.2 and above"; the spec
294 // does not say what older models do with it.
295 reasoningEffort: levelsFor(providerId, rawId) === null ? null : true,
296 })
297 case 'qwen':
298 return blank({
299 thinking: withLevels(
300 { on: QWEN_ON, off: null, levels: null },
301 providerId,
302 rawId,
303 ),
304 developerRole: false,
305 })
306 // From MiniMax's chat spec, not probed: `max_tokens` is deprecated, the
307 // role enum has no `developer`, and every model takes adaptive thinking.
308 // `disabled` skips thinking on MiniMax-M3 only: M3.1-Flash-Preview
309 // answers 400 and the M2 models ignore it. The China platform's chat
310 // spec states the same of the same ids.
311 case 'minimax':
312 case 'minimax-cn':
313 return blank({
314 thinking: withLevels(
315 {
316 on: MINIMAX_ON,
317 off: matches(rawId, 'MiniMax-M3') ? MINIMAX_OFF : null,
318 levels: null,
319 },
320 providerId,
321 rawId,
322 ),
323 maxTokensField: 'max_completion_tokens',
324 developerRole: false,
325 reasoningEffort: true,
326 })
327 case 'vllm':
328 return blank({
329 thinking: withLevels(
330 { on: VLLM_QWEN_ON, off: null, levels: null },
331 providerId,
332 rawId,
333 ),
334 developerRole: false,
335 })
336 // Hugging Face's chat-completion schema names `max_tokens` only. The
337 // rest depends on the routed provider, so it stays null.
338 case 'huggingface':
339 return blank({ maxTokensField: 'max_tokens' })
340 // From Moonshot's chat spec, not probed. The international and China
341 // documents agree: `max_tokens` is deprecated for
342 // `max_completion_tokens`, the role enum has no `developer`, and only
343 // `kimi-k3` declares `reasoning_effort`. The spec does not say the other
344 // models reject it, so that stays null. For `kimi-k3` Moonshot's OpenClaw
345 // guide sets `maxTokensField: "max_tokens"` against the spec, so its
346 // field stays null until probed.
347 case 'moonshot':
348 case 'moonshotai-cn':
349 return blank({
350 thinking: kimiThinking(rawId),
351 maxTokensField: rawId === 'kimi-k3' ? null : 'max_completion_tokens',
352 developerRole: false,
353 reasoningEffort: rawId === 'kimi-k3' ? true : null,
354 })
355 case 'grok':
356 return blank({
357 developerRole: false,
358 reasoningEffort: false,
359 })
360 // Cohere's `/v2/chat` spec: the output cap is `max_tokens`, the message
361 // roles are user, assistant, system and tool, and the body has no
362 // `reasoning_effort` (the API answers 422 to it and to `developer`).
363 // `thinking` is null: only reasoning models take it, and this map is
364 // not per capability.
365 case 'cohere':
366 return blank({
367 maxTokensField: 'max_tokens',
368 developerRole: false,
369 reasoningEffort: false,
370 })
371 // SambaNova's own chat schema, not the OpenAI document schemas are
372 // generated from. `max_tokens` is what the guides send;
373 // `max_completion_tokens` describes the same cap. Roles are system,
374 // user, assistant, and tool. `reasoning_effort` is on the shared body
375 // (low | medium | high) with no off value.
376 // https://raw.githubusercontent.com/sambanova/sambanova-inference-api-spec/refs/heads/main/openapi.documented.json
377 case 'sambanova':
378 return blank({
379 thinking: {
380 on: { reasoning_effort: 'high' },
381 off: null,
382 levels: SAMBANOVA_LEVELS,
383 },
384 maxTokensField: 'max_tokens',
385 developerRole: false,
386 reasoningEffort: true,
387 })
388 default:
389 return null
390 }
391}