Skip to content

feat(text): align defaults with current M3/Messages API contract#204

Open
raylanlin wants to merge 4 commits into
MiniMax-AI:mainfrom
raylanlin:feat/m3-defaults-rev2
Open

feat(text): align defaults with current M3/Messages API contract#204
raylanlin wants to merge 4 commits into
MiniMax-AI:mainfrom
raylanlin:feat/m3-defaults-rev2

Conversation

@raylanlin

@raylanlin raylanlin commented Jul 18, 2026

Copy link
Copy Markdown
Collaborator

Follow-up to #172 (closed). Implements the remaining feedback from @NianJiuZst's review comment against the current Messages API contract.

Background

The M3 default model change from #172 landed in upstream v1.0.18. This PR addresses the other items in NianJiuZst's review that didn't make it in:

  1. max_tokens was kept at 4096; the official M3 recommendation is 131072 (128K), other models 65536 (64K).
  2. Thinking parameter was not added; Messages API says thinking is disabled by default when omitted, so the CLI must document and expose that as opt-in.
  3. Help text documented temperature as (0.0, 1.0]; the M3 Messages API uses [0, 2] with default 1.
  4. --top-p had no default documented; M3 Messages API contract default is 0.95.

The stacked quota commit (carrying #168) is removed; rebased cleanly on current main.

Changes

  • Model-aware max_tokens (src/commands/text/chat.ts, src/commands/text/repl.ts, src/sdk/text/index.ts, src/utils/model-defaults.ts): 131072 for M3, 65536 for others. --max-tokens flag always overrides. New shared helper resolveMaxTokens() keeps chat, repl, and the SDK in lockstep.
  • Thinking parameter (src/types/api.ts): new optional thinking?: {type: 'enabled' | 'disabled' | 'adaptive'} field. New --thinking <mode> CLI flag in both commands. Default: omitted (thinking disabled per API contract). Unknown values throw CLIError (exit code 2 / USAGE) before any network call.
  • Temperature [0, 2] default 1 (src/commands/text/chat.ts, src/commands/text/repl.ts, src/utils/model-defaults.ts): help text updated; new resolveTemperature() helper rejects out-of-range and non-numeric values up-front. We do not auto-send 1 when the flag is omitted — backward compat preserved.
  • Top-p default 0.95 (src/commands/text/chat.ts, src/commands/text/repl.ts): help text updated to mention 0.95 as the Messages API recommendation. Field still omitted from request body when flag is not passed — no behavior change for existing users.
  • Tests (test/utils/model-defaults.test.ts, test/sdk/text.test.ts, test/commands/text/chat.test.ts, test/commands/text/repl.test.ts): focused coverage for each of the above. Coverage spans three altitudes — pure helper unit, SDK round-trip via mock server, and full command execute() via --dry-run.

Quality gates

  • typecheck: clean (npx tsc --noEmit exit 0)
  • tests: 448 pass / 0 fail / 808 expect() calls (bun test; baseline 403/0/735 → +45 tests)
  • build: clean (bun run build exit 0; dist/mmx.mjs + dist/sdk.mjs produced)

Notes

  • max_tokens=131072 for M3 follows the official Messages API recommendation. The 524288 (512K) maximum is documented in the API contract but not enforced as a default — explicit --max-tokens overrides remain the user escape hatch (e.g. for --max-tokens 8192).
  • Thinking default of "omitted" matches the documented API behavior (thinking disabled by default for M3). If the project later wants a different default, that should be a separate discussion with reason.
  • --top-p 0.95 is documented in help but not auto-sent — no behavior change for existing users; new users see the recommended default in --help.
  • The resolveMaxTokens, resolveThinkingMode, and resolveTemperature helpers live in a new src/utils/model-defaults.ts so chat/repl/SDK stay in lockstep — preventing the kind of drift that motivated NianJiuZst's review in the first place.

cc @NianJiuZst — thank you for the detailed review on #172.


View with Codesmith Autofix with Codesmith
Need help on this PR? Tag /codesmith with what you need. Autofix is disabled.

raylanlin and others added 4 commits July 18, 2026 21:41
Follow-up to MiniMax-AI#172 (closed). Addresses NianJiuZst's review points 1 and 2
against the current Messages API contract.

Changes:
- New src/utils/model-defaults.ts: single source of truth for per-model
  max_tokens defaults (M3 -> 131072, others -> 65536) and thinking-mode
  validation. Imports kept symmetric across chat, repl, and the SDK to
  prevent drift.
- src/types/api.ts: add optional ChatRequest.thinking field with type
  'enabled' | 'disabled' | 'adaptive'.
- src/commands/text/{chat,repl}.ts:
  * default max_tokens now follows the Messages API recommendation per
    model instead of a flat 4096; --max-tokens flag still overrides
  * new --thinking <mode> flag; passing it sets ChatRequest.thinking;
    omitting the flag leaves the field absent so the API's default
    (thinking disabled for M3) applies unchanged
  * unknown --thinking values throw CLIError (exit 2 USAGE) before any
    network call
- src/sdk/text/index.ts: replace hard-coded 4096 default with the shared
  resolver; pass thinking through only when explicitly set, never
  auto-inject.

Help text for --max-tokens updated to '(default: 131072 for M3, 65536
for other models)' in both commands. Repl keeps model-aware default as
well so the value displayed in /history matches the actual request
ceiling.

Co-authored-by: minimax <noreply@MiniMax.ai>
NianJiuZst review point 3 against the current Messages API contract.

Changes:
- --temperature help text updated from '(0.0, 1.0]' to '[0, 2] (default: 1)'
  in chat.ts and repl.ts. M3 Messages API documents this range.
- New resolveTemperature() helper in src/utils/model-defaults.ts validates
  --temperature before any network call: rejects non-numeric input and
  values outside [0, 2] with a clean error. Same surface in chat and repl.
- --top-p help text updated to mention 0.95 as the Messages API default.
  We do NOT auto-send 0.95 when the flag is omitted — backward compat:
  users without the flag see no change in the request body.
- New TOP_P_DEFAULT export in model-defaults.ts (0.95) for tests and
  future callers that want to mirror the documented default.

Co-authored-by: minimax <noreply@MiniMax.ai>
Adds focused coverage for the new behavior landed in the two previous
commits:

- model-aware max_tokens via resolveMaxTokens
  * M3 -> 131072 when caller / flag is absent
  * MiniMax-M2.7 -> 65536
  * MiniMax-M2.5 and unknown models fall back to 65536
  * caller-supplied flag (100, 524288) always wins
- thinking parameter plumbing
  * --thinking enabled / disabled propagates to ChatRequest.thinking
  * omitting --thinking leaves the field absent in the body
  * invalid values throw a clean error from resolveThinkingMode
- temperature range [0, 2] with default 1
  * resolveTemperature accepts 0, 1, 2, fractional 0.7 / 1.5, numeric strings
  * resolves [-0.01, 2.01] and non-numeric input as errors
- top_p default 0.95 documented via TOP_P_DEFAULT export
- help text in both chat and repl reflects the documented defaults and
  the full --thinking mode set

Coverage lives at the right altitude:
  - test/utils/model-defaults.test.ts — pure unit tests of the helper
  - test/sdk/text.test.ts           — SDK chat() roundtrip via mock server
  - test/commands/text/*.test.ts    — full command execute() via --dry-run

Co-authored-by: minimax <noreply@MiniMax.ai>
The Messages API documents per-model top_p defaults:
  - MiniMax-M3:  0.95
  - M2.x models: 0.9

PR MiniMax-AI#204 previously hardcoded 0.95 in the TOP_P_DEFAULT export and
the --top-p help text in both commands, which misrepresented the
M2.x default.

Replace TOP_P_DEFAULT constant with resolveTopPDefault(model)
function that returns the model-appropriate value (M3 -> 0.95,
everything else -> 0.9 as the safe M2.x fallback). Update help
text in mmx text chat and mmx text repl accordingly.

CLI behavior is unchanged: top_p is still only sent on the wire
when the user explicitly passes --top-p. The fix is help-text
accuracy / contract alignment, no payload change.

Verified against the current Messages API documentation at
https://platform.minimax.io/docs/api-reference/text-chat-anthropic
@raylanlin

Copy link
Copy Markdown
Collaborator Author

Self-review fix after cross-checking against the current Messages API docs:

The Messages API documents top_p as model-aware:

top_p   number<double>  default:0.95
Nucleus sampling parameter. Range [0, 1]. Default is 0.95 for MiniMax-M3 and 0.9 for M2.x models.

The first push of this PR hardcoded 0.95 in both the TOP_P_DEFAULT export and the --top-p help text, which misrepresented the M2.x default. Replacement (86262ca):

  • src/utils/model-defaults.ts: TOP_P_DEFAULT constant → resolveTopPDefault(model) function (M3 → 0.95, anything else → 0.9 as the safe M2.x fallback).
  • src/commands/text/chat.ts + src/commands/text/repl.ts: --top-p help text now reflects the per-model default ((default: 0.95 for M3, 0.9 for M2.x per Messages API)).
  • test/utils/model-defaults.test.ts: replaced the single TOP_P_DEFAULT assertion with a model-aware resolveTopPDefault describe block (4 cases).

Behavior unchanged: top_p is still only sent on the wire when the user explicitly passes --top-p. The fix is help-text accuracy / contract alignment only — no request-body change for existing users.

Quality gates after the fix: npx tsc --noEmit exit 0, bun test 451 pass / 0 fail / 811 expects (+3 net vs prior push), bun run build clean. Verified the docs at https://platform.minimax.io/docs/api-reference/text-chat-anthropic (which is the page @NianJiuZst cited in the #172 review).

cc @NianJiuZst — only noticed this when I went back to fetch the actual docs after the first push landed. Sorry the first pass oversimplified point 3.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant