diff options
Diffstat (limited to '.rules/plan/00-00-overview.md')
| -rw-r--r-- | .rules/plan/00-00-overview.md | 110 |
1 files changed, 110 insertions, 0 deletions
diff --git a/.rules/plan/00-00-overview.md b/.rules/plan/00-00-overview.md new file mode 100644 index 0000000..1fad2ce --- /dev/null +++ b/.rules/plan/00-00-overview.md @@ -0,0 +1,110 @@ +# MiniMax Adapter Plan — Overview + +## Goal + +Convert the forked Claude adapter at `reference/dispatch-adapter-minimax/` +into a working `Dispatch::Adapter::MiniMax` adapter that talks to MiniMax's +Anthropic-compatible endpoint at `https://api.minimax.io/anthropic`, using +a single static API key (Token Plan). + +## Working directory + +All file paths in these plans are RELATIVE to the gem root: + +``` +reference/dispatch-adapter-minimax/ +``` + +When `run_tests` is called, `project_path` MUST be that directory. + +## Locked design decisions + +| # | Topic | Decision | +|---|---|---| +| 1 | Module name | `Dispatch::Adapter::MiniMax` (note CamelCase: `MiniMax`) | +| 2 | Default model | `MiniMax-M2.7` | +| 3 | `thinking` param | Keep, default `"high"`, plumb `thinking_delta` SSE through unchanged | +| 4 | Pricing / `Usage#cost` | Keep field, always `0.0`; strip `PricingTable` populated rows | +| 5 | `count_tokens` + `list_models` | Keep both (Python SDK uses both `/v1/messages/count_tokens` and `/v1/models`) | +| 6 | `cache_control` blocks | Keep (SDK emits them; MiniMax must accept or ignore) | +| 7 | Strict-tool-schema fallback | Keep harness, broaden matcher regex to also fire on MiniMax-shaped errors | +| 8 | API key resolution | constructor `api_key:` → `ENV["MINIMAX_API_KEY"]` → `~/.config/dispatch/minimax_api_key` (0600 plain text) → raise | + +## SDK-is-fair-game rule + +Whatever the Anthropic Python SDK does is *permitted* and considered safe. +It is a permission, not a constraint. We may do MORE if it is better and +safe; we don't have to emulate exactly. + +Reference clone: `reference/anthropic-sdk-python/` (already cloned). + +## Hard rules for every phase + +1. After every code change, call `run_tests` with + `project_path=reference/dispatch-adapter-minimax`. The `Overall:` line + in the results file MUST read `PASS` (rubocop AND rspec each exit 0) + before calling `ask_for_next_plan`. +2. NEVER weaken or delete a test to make it pass. Fix the implementation. + Tests that target removed code (OAuth, PKCE, cloaking, usage_client) + should be DELETED in their dedicated retarget phase, not weakened + earlier. +3. Do NOT add runtime gem dependencies. Stick to stdlib (`net/http`, + `uri`, `json`, `fileutils`, `digest`, `securerandom`). +4. Do NOT make live network calls in specs. Stub with WebMock / fixtures. +5. After phase 17 is complete, the gem must `bundle install` cleanly, + `bundle exec rubocop --autocorrect-all` must report no offenses, and + `bundle exec rspec` must pass with no `.skip` or `pending` examples. +6. Each plan file is self-contained. Do not look ahead at other plan + files. The system prompt + the current plan body is all you need. + +## MiniMax-specific request constraints + +These must be enforced in the request builder: + +- `temperature` range is `(0.0, 1.0]` — MiniMax explicitly errors outside. +- `image` and `document` content blocks are NOT supported — reject with + `ArgumentError` at request-build time. +- These input parameters get IGNORED by MiniMax (strip silently before + send to keep the wire clean): `top_k`, `stop_sequences`, `service_tier`, + `mcp_servers`, `context_management`, `container`. + +## Supported MiniMax models (hardcoded catalog) + +All seven share a 204,800-token context window: + +- `MiniMax-M2.7` (default) +- `MiniMax-M2.7-highspeed` +- `MiniMax-M2.5` +- `MiniMax-M2.5-highspeed` +- `MiniMax-M2.1` +- `MiniMax-M2.1-highspeed` +- `MiniMax-M2` + +## Steps + +| # | File | Phase | +|---|------|-------| +| 01 | `01-30-rename-namespace.md` | Rename files, modules, gemspec, requires | +| 02 | `02-30-strip-oauth-and-anthropic-machinery.md` | Delete OAuth / PKCE / cloaking / usage / rate-limit-headers files and methods | +| 03 | `03-15-keystore.md` | Replace `TokenStore` with simple `KeyStore` (env / file / explicit) | +| 04 | `04-15-simplify-headers.md` | Collapse `Headers.build` to bearer + content-type + accept | +| 05 | `05-10-config-swap.md` | `DEFAULT_BASE_URL` and `DEFAULT_MODEL` constants | +| 06 | `06-15-pricing-zero.md` | Zero out `PricingTable` so `Usage#cost` is always 0.0 | +| 07 | `07-15-model-catalog.md` | Hardcode the 7-model MiniMax catalog | +| 08 | `08-15-strip-ignored-params-and-temp.md` | Strip ignored params; validate temperature `(0,1]` | +| 09 | `09-15-reject-image-document.md` | Reject `image` / `document` content blocks at request build time | +| 10 | `10-10-broaden-strict-regex.md` | Broaden `strict_grammar_error?` matcher | +| 11 | `11-15-errors-module.md` | Rename `ClaudeErrors` → `MiniMaxErrors`, retarget mapping | +| 12 | `12-25-update-fixtures.md` | Replace SSE + JSON fixtures with MiniMax-shaped data | +| 13 | `13-25-retarget-headers-and-request-builder-specs.md` | Update headers_spec + request_builder_spec to new shapes | +| 14 | `14-25-retarget-response-builder-and-streaming-internals-specs.md` | Update response_builder_spec + sse_parser_spec + stream_collector_spec | +| 15 | `15-30-retarget-chat-and-counttokens-listmodels-specs.md` | Update chat_streaming + chat_non_streaming + chat_streaming_retry + count_tokens + list_models specs | +| 16 | `16-20-retarget-misc-specs.md` | Update model_catalog + pricing_table + errors + strict_fallback + http_client + rate_limiter + main `minimax_spec.rb` | +| 17 | `17-20-readme-changelog-examples.md` | Rewrite README, CHANGELOG, and examples | + +## Out-of-scope reminders + +- Live API smoke testing is NOT in this plan series — it's a manual step + after phase 17 and requires a real Token Plan API key. +- Adding new public methods or features beyond what the SDK already + exposes is out of scope. Stick to the parity surface. |