minimax

What this skill does

# MiniMax M-series Production Wiring

OpenAI-compatible chat-completion endpoint at `https://api.minimax.io/v1` with the **M2.7-highspeed reasoning model** (premium tier as of 2026-04-29). LOOKS LIKE OPENAI but **silently drops 6 OpenAI parameters** and exposes `<think>` reasoning traces inside `content`. Beyond chat-completion, the API is MiniMax-native (different URLs, different body shapes, different error envelopes — HTTP 200 + `base_resp.status_code` instead of HTTP 4xx).

The model itself is a **competent qualitative judge + theory explainer + tool orchestrator** for finance/quant work, but **cannot do raw math** on realistic data sizes (saturates reasoning budget) and **hallucinates plausible details** under input uncertainty (6 documented instances). For production: pair it with Python for math, sandbox validators for code, and deterministic detectors for pattern recognition.

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues. Source-of-truth campaign archive: `~/own/amonic/minimax/` (read-only reference; do not modify from this skill).

> **🆕 MiniMax-M3 is live (2026-06-01).** This file covers **M2.7**. For M3 — native vision,
> `reasoning_split` clean output, `response_format` acceptance, 512K input ceiling / 512K output cap,
> `n=1`, and the docs-vs-reality discrepancies — use the sibling skill
> [`../m3/SKILL.md`](../m3/SKILL.md) and the evidence doc
> [`../../references/M3-EMPIRICAL.md`](../../references/M3-EMPIRICAL.md). The defensive snippets
> below (`<think>` strip, `base_resp` retry, cached-token reader) apply to M3 unchanged.

---

## When to use M2.7 vs not — the decision table

| Workload                                       | Verdict                     | Why                                                                                        |
| ---------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------ |
| Tagging / classification (5-15 token outputs)  | ✅ Use plain `MiniMax-M2.7` | Plain is 2.5× faster than -highspeed for short outputs (cross-over at ~150 tokens).        |
| Summarization / long-form generation           | ✅ Use `-highspeed`         | -highspeed wins at >150 tokens. ~50 TPS asymptote (NOT the 100 TPS plan claim).            |
| Trade signal JSON output                       | ✅ Production-ready         | 6/6 verified across L1+L2+L3 layers with strict system prompt. Confidence well-calibrated. |
| Financial theory explanation                   | ✅ Graduate-level           | Black-Scholes derivations, FTAP, KKT, vol skew microstructure all correct.                 |
| Long-context retrieval (≤ 30K tokens)          | ✅ 4/4 needle retrieval     | NO "lost in the middle" effect. Perfect retrieval at 10/50/85/98% positions.               |
| Tool orchestration (agent loop)                | ✅ 4/4 correct selection    | Parallel + chained tool calls work. Refuses irrelevant queries gracefully.                 |
| Math / Black-Scholes / Sharpe on N≥50 returns  | ❌ DO NOT USE               | Saturates 8-16K reasoning tokens; route to Python (numpy/scipy/cvxpy).                     |
| QP / constrained optimization (Markowitz)      | ❌ DO NOT USE               | Same saturation pattern. Use scipy.optimize / cvxpy.                                       |
| Risk metrics on realistic data (N=252 returns) | ❌ DO NOT USE               | Even SINGLE metric saturates. Pre-summarize aggregates before passing.                     |
| Chart pattern recognition                      | ❌ DO NOT USE               | Hallucinates patterns in pure noise. Use TA-Lib / CV / classical algos.                    |
| Code generation (final, deployable)            | ⚠️ Scaffold-only            | Compiles 100%, runs 0% on first try (hallucinates library imports). Sandbox-validate.      |
| Vision / image input                           | ❌ NOT SUPPORTED            | M2.7 is text-only. `image_url` silently dropped at INPUT level.                            |
| TTS / video                                    | ⚠️ Plan-gated               | Endpoints exist (`/v1/t2a_v2`, `/v1/video_generation`) but error 2061 on Plus-High-Speed.  |
| Embeddings (bulk RAG)                          | ⚠️ RPM-tight                | `/v1/embeddings` accessible but rate-limited beyond ~5 calls. Use local embeddings.        |

---

## Top 10 production rules

1. **Always set a system prompt — it's at-most break-even, often net-positive.** Long instructions in `messages[0]` get ~70% billing rate AND replace MiniMax's hidden ~30-token default. Detailed instructions belong in system role, NEVER user content.

2. **Strip `<think>...</think>` from `content` before displaying.** M-series exposes its reasoning trace inside the content string. Production: `re.sub(r"<think>[\s\S]*?</think>\s*", "", content)`. Server-side stripping for billing on assistant replay (multi-turn doesn't double-bill).

3. **`max_tokens` ≥ 1024 for non-trivial tasks. 512 is a silent-empty footgun.** Reasoning consumes budget BEFORE visible content. Branch on `finish_reason == "length"` defensively.

4. **Trust capability params, suspect control params.** Honored: `tools`, `messages`, `max_tokens`, `temperature`, `stream`. Silently dropped: `stop`, `tool_choice`, `response_format`, streaming `usage`, `image_url`, `messages[].name`.

5. **For JSON output, prompt-engineer it — `response_format` is silently dropped.** Strict system prompt + `temperature=0.2` + `max_tokens=4096` + `try/except json.loads` = 100% reliability (6/6 verified).

6. **Plain `MiniMax-M2.7` for short-output workloads (<150 visible tokens); `-highspeed` for long-form.** "Highspeed" is COUNTERINTUITIVELY slower for short outputs (Karakeep tagging at 5-15 tokens: plain is 2.5× faster).

7. **Caching is COST-only on MiniMax, not LATENCY.** Add `cache_control: {type: "ephemeral"}` to system messages for ~95% input-token cost reduction; don't expect interactive-UX latency benefits. Activates at ~600+ prompt_tokens. Prefix-match works (varied user + stable system gets ~70% hit rate).

8. **Route financial math to Python — M2.7 saturates on QP / numerical integration / Sharpe on N≥50 returns.** Pre-summarize aggregates (mean / stdev / n) and pass them; M2.7 handles the final-step formula. Define financial primitives as TOOLS for agent-loop orchestration.

9. **NEVER trust M2.7-generated code without sandbox validation.** `compile()` is INSUFFICIENT. M2.7 invents library imports (`SMA`, `RSI`, `BollingerBands` from `backtesting.lib` — none exist). Run in subprocess + capture exit code + iterative repair on failure.

10. **NO HTTP 429 — rate-limited responses are HTTP 200 + `base_resp.status_code=1002`.** Standard retry middleware that watches HTTP status WILL NOT catch this. Use code-prefix-based handler: `1xxx` family = retry with backoff; `2xxx` family = fix request, don't retry.

---

## Canonical Tier F agentic stack (quant-LLM workflow)

```
F4: long-context retrieval         → M2.7 finds facts from filings/research
        ↓
F2: structured judgment as JSON    → M2.7 emits trade signal
        ↓
F6: tool orchestration             → M2.7 selects + calls tools (parallel + chained)
        ↓
F1+F8+F9: Python math layer        → numpy/scipy/cvxpy compute deterministically
        ↓
F3: textbook explanation           → M2.7 narrates the result with theory
        ↓
F5: sandbox-validated code         → M2.7 scaffolds; subprocess validates
```

**The pattern**: M2.7 for judgment / theory / orchestration; Python for math / validation / pattern detection. Never mix "explain + compute" in one prompt for complex problems — saturation is the failure mode.

| Primitive    | M2.7's role                                  | Python's role                                   |