[hetaoBackend]

Summary

Adds packages/code-sdk-python, the Python counterpart of @minimax-ai/code-sdk. The PyPI name is minimax-code-sdk, the import is minimax_code, it is MIT licensed and needs Python 3.10+. Its only runtime dependency is typing_extensions.

The SDK has the same shape as the TS SDK. Each Turn runs mcode exec --output-format=stream-json --input=- --input-format=json and later Turns continue the Session with --session. Events are typed from packages/code-sdk/src/types.ts (schemaVersion 1) and are passed through unchanged.

API sketch

from minimax_code import MCode, MCodeOptions, ThreadOptions, RunOptions

client = MCode(MCodeOptions(bin=None, data_dir=None, env=None, config_path=None))
thread = client.start_thread(ThreadOptions(cwd=".", model="minimax/MiniMax-M3", permission="smart"))

turn = await thread.run("Fix the failing test", RunOptions(timeout_ms=600_000))
turn.final_response, turn.items, turn.usage, turn.session_id

streamed = await thread.run_streamed("Explain the diff")
async for event in streamed:   # raw CLI events; turn.failed is an ordinary event
    ...
streamed.cancel()              # SIGINT; breaking out of the loop or cancelling the task also stops the CLI

later = client.resume_thread(thread.id)

from minimax_code import SyncMCode   # blocking wrapper

• The CLI is found from bin, then $MCODE_BIN, then PATH. JS entries run through node. The SDK checks mcode --version against a minimum of 0.6.3, the same as the TS SDK.
• Errors follow the TS SDK: MCodeNotFoundError, MCodeVersionError, MCodeInvocationError, MCodeRunError (with status and category), MCodeAbortError, MCodeProtocolError and ThreadBusyError. They carry exit_code, the stderr tail, session_id, result and items. Exit codes map the same way as MCODE_EXEC_EXIT_CODES.
• item.* events are merged by id, and duplicate snapshot updates are dropped, the same as ItemAccumulator. System prompts are passed through private temp files that are removed after the Turn.

Design choice

For 0.1 the SDK uses exec-per-turn, the same transport as the TS SDK, so the two SDKs behave the same and the CLI needs no changes. This transport cannot handle interactive approvals (permission="ask") or tools defined in Python. A long-lived ACP transport (mcode acp plus the agent-client-protocol client) is planned for 0.2, behind the same Thread API.

Repo changes outside the package

• .github/workflows/python-sdk.yml runs ruff, ruff format, mypy (strict) and pytest on Ubuntu and macOS with Python 3.10 and 3.13. It triggers only on changes under its own paths, and the existing verify jobs are untouched.
• release/public-source.json records the new files.
• scripts/source-inventory.mjs now skips local Python caches (.venv, __pycache__, .pytest_cache, .mypy_cache, .ruff_cache). Without this, running uv sync locally breaks check:source because of the .venv symlinks.
• No publishing workflow is added.

Testing

• uv run pytest -W error: 15 unit tests passed and 3 e2e tests were skipped (they are opt-in). The unit tests use a fake mcode script and cover arguments, multi-turn and resume, streaming and dedupe, failure, invocation, crash and protocol errors, a missing CLI, an old CLI version, cancellation by cancel(), by task cancel and by break, the busy-thread error and the sync wrapper. They passed on Python 3.12 and 3.10.
• ruff check, ruff format --check and mypy --strict are clean.
• E2E against dist/cli.js built from this branch (0.7.2) with a real MiniMax model: MCODE_SDK_E2E=1 uv run pytest -m e2e covers a single run, a streamed run and multi-turn resume, and all 3 passed. A manual check also confirmed:
  • streamed.cancel() ends the stream with exec.completed status cancelled.
  • Task cancel stops the CLI.
  • The same Thread can run again afterwards.
• pnpm verify --profile full passes locally on Linux.

Follow-ups

• 0.2: ACP transport with permission callbacks and interrupt. On the mcode side, ACP needs to return usage, duration and stop reason in _meta.
• Generate the types from a JSON schema exported by packages/protocol instead of mirroring them by hand.
• Add a contract test against the real CLI stream, like the TS SDK's cli-contract.test.ts.
• Add PyPI release automation once the API is settled.
• Add Windows CI. The unit-test fake currently relies on a POSIX shebang and pkill.

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}