minimax-code-sdk 0.1.0b1__tar.gz

minimax_code_sdk-0.1.0b1/.gitignore

@@ -0,0 +1,6 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/

minimax_code_sdk-0.1.0b1/CHANGELOG.md

@@ -0,0 +1,32 @@
+# `minimax-code-sdk` Changelog
+
+All notable changes to the `minimax-code-sdk` Python package are documented here. The SDK is
+versioned independently of the MiniMax Code CLI and of the TypeScript SDK. The first
+`## X.Y.Z · YYYY-MM-DD` heading is the version being released; see [RELEASING.md](RELEASING.md).
+
+## 0.1.0b1 · 2026-11-03
+
+First public beta. Install it with `pip install --pre minimax-code-sdk`; the API may still
+change before `0.1.0`.
+
+### Added
+
+- `MCode`, `start_thread()`, `resume_thread()`, `thread.run()` and `thread.run_streamed()` drive
+  `mcode exec --output-format=stream-json`, one CLI process per Turn, continuing the Session with
+  `--session`.
+- `SyncMCode` and `SyncThread`, a blocking API for scripts and notebooks without an event loop.
+- CLI resolution: explicit `MCodeOptions(bin=...)`, then `$MCODE_BIN`, then `mcode` on `PATH`.
+  Requires MiniMax Code CLI `0.6.3` or later and Python `3.10` or later.
+- Stream events are passed through unchanged as typed dicts (event `schemaVersion` 1), including
+  unknown event types; `thread.run()` folds them into `Turn.items`.
+- Typed errors for invocation, run, cancellation, protocol, missing CLI, version and busy Thread
+  failures, mapped from the CLI exit codes.
+- Cancellation through `StreamedTurn.cancel()`, early loop exit or task cancellation (`SIGINT`,
+  then `SIGKILL` after 10 seconds) and a `timeout_ms` backstop of `timeout_ms + 30s`.
+- `system_prompt` and `append_system_prompt` are passed through private temporary files.
+- Ships `py.typed`; the only runtime dependency is `typing_extensions`.
+
+### Not yet available
+
+- Interactive permission prompts (`permission="ask"`), custom in-process tools and a long-lived
+  ACP transport.

minimax_code_sdk-0.1.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MiniMax Code
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

minimax_code_sdk-0.1.0b1/PKG-INFO

@@ -0,0 +1,139 @@
+Metadata-Version: 2.5
+Name: minimax-code-sdk
+Version: 0.1.0b1
+Summary: Python SDK for driving the local MiniMax Code (mcode) agent.
+Project-URL: Homepage, https://agent.minimax.io
+Project-URL: Repository, https://github.com/MiniMax-AI/minimax-code
+Project-URL: Issues, https://github.com/MiniMax-AI/minimax-code/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,coding-agent,mcode,minimax,minimax-code,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: typing-extensions>=4.7
+Description-Content-Type: text/markdown
+
+# minimax-code-sdk
+
+Python SDK for driving the local [MiniMax Code](https://agent.minimax.io) agent (`mcode`).
+
+It mirrors the TypeScript SDK
+[`@minimax-ai/code-sdk`](https://github.com/MiniMax-AI/minimax-code/tree/main/packages/code-sdk): every Turn runs
+`mcode exec --output-format=stream-json` and continues the Session with `--session`.
+
+## Requirements
+
+- Python 3.10+
+- The `mcode` CLI (0.6.3 or newer): `npm install -g @minimax-ai/code`
+
+## Install
+
+```bash
+pip install --pre minimax-code-sdk   # or: uv add --prerelease=allow minimax-code-sdk
+```
+
+The SDK is in beta, so installers need `--pre` (or an exact version such as
+`minimax-code-sdk==0.1.0b1`) until `0.1.0` is released. Import it as `minimax_code`.
+
+The CLI is found from `MCodeOptions(bin=...)`, then the `MCODE_BIN` environment variable,
+then `PATH`.
+
+## Quick start
+
+```python
+import asyncio
+from minimax_code import MCode, ThreadOptions
+
+
+async def main() -> None:
+    client = MCode()
+    thread = client.start_thread(ThreadOptions(cwd=".", permission="smart"))
+
+    turn = await thread.run("Summarize this repository in one sentence.")
+    print(turn.final_response, turn.usage)
+
+    # Same Session, next Turn.
+    turn = await thread.run("Now list its top-level directories.")
+
+    # Persist thread.id and continue later.
+    later = client.resume_thread(thread.id)
+    print((await later.run("What did I ask first?")).final_response)
+
+
+asyncio.run(main())
+```
+
+### Streaming
+
+```python
+streamed = await thread.run_streamed("Fix the failing test.")
+async for event in streamed:
+    if event["type"] == "item.updated" and event["item"]["type"] == "agent_message":
+        print(event["item"].get("contentDelta", ""), end="")
+    elif event["type"] == "turn.failed":
+        print("failed:", event.get("error"))
+```
+
+Events are the CLI's stream-json events, passed through unchanged (unknown types included).
+`turn.failed` is an ordinary event; iteration raises only for process or protocol failures.
+
+### Cancellation
+
+- `streamed.cancel()` sends SIGINT; the stream ends with the CLI's final events.
+- Leaving the `async for` early, or cancelling the task running `thread.run()`, stops the CLI
+  (SIGINT, then SIGKILL after a grace period).
+- `RunOptions(timeout_ms=...)` is enforced by the CLI.
+
+### Blocking API
+
+```python
+from minimax_code import SyncMCode
+
+with SyncMCode() as client:
+    thread = client.start_thread()
+    print(thread.run("hello").final_response)
+    for event in thread.run_streamed("again"):
+        print(event["type"])
+```
+
+## Options
+
+| Object | Fields |
+| --- | --- |
+| `MCodeOptions` | `bin`, `data_dir` (`MINIMAX_DATA_DIR`), `env` (replaces `os.environ`), `config_path` |
+| `ThreadOptions` | `cwd`, `model` (`provider/model`), `effort`, `permission` (`smart`/`full`/`off`), `mode`, `prompt_mode`, `system_prompt`, `append_system_prompt` |
+| `RunOptions` | `files`, `timeout_ms`, `max_steps` |
+
+## Errors
+
+All errors subclass `MCodeError` (with `exit_code`, `stderr`, `session_id`, `result`, `items`):
+`MCodeNotFoundError`, `MCodeVersionError`, `MCodeInvocationError`, `MCodeRunError`
+(`status`, `category`), `MCodeAbortError`, `MCodeProtocolError`, `ThreadBusyError`.
+
+## Limitations
+
+Each Turn is a separate process, so interactive permission prompts (`permission="ask"`) and
+custom in-process tools are not supported yet. A long-lived ACP transport is planned.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+```
+
+End-to-end tests against a real CLI and model are opt-in:
+`MCODE_SDK_E2E=1 MCODE_BIN=/path/to/mcode uv run pytest -m e2e`.
+
+Release notes are in
+[CHANGELOG.md](https://github.com/MiniMax-AI/minimax-code/blob/main/packages/code-sdk-python/CHANGELOG.md);
+maintainers publish with
+[RELEASING.md](https://github.com/MiniMax-AI/minimax-code/blob/main/packages/code-sdk-python/RELEASING.md).
+
+## License
+
+MIT

minimax_code_sdk-0.1.0b1/README.md

@@ -0,0 +1,121 @@
+# minimax-code-sdk
+
+Python SDK for driving the local [MiniMax Code](https://agent.minimax.io) agent (`mcode`).
+
+It mirrors the TypeScript SDK
+[`@minimax-ai/code-sdk`](https://github.com/MiniMax-AI/minimax-code/tree/main/packages/code-sdk): every Turn runs
+`mcode exec --output-format=stream-json` and continues the Session with `--session`.
+
+## Requirements
+
+- Python 3.10+
+- The `mcode` CLI (0.6.3 or newer): `npm install -g @minimax-ai/code`
+
+## Install
+
+```bash
+pip install --pre minimax-code-sdk   # or: uv add --prerelease=allow minimax-code-sdk
+```
+
+The SDK is in beta, so installers need `--pre` (or an exact version such as
+`minimax-code-sdk==0.1.0b1`) until `0.1.0` is released. Import it as `minimax_code`.
+
+The CLI is found from `MCodeOptions(bin=...)`, then the `MCODE_BIN` environment variable,
+then `PATH`.
+
+## Quick start
+
+```python
+import asyncio
+from minimax_code import MCode, ThreadOptions
+
+
+async def main() -> None:
+    client = MCode()
+    thread = client.start_thread(ThreadOptions(cwd=".", permission="smart"))
+
+    turn = await thread.run("Summarize this repository in one sentence.")
+    print(turn.final_response, turn.usage)
+
+    # Same Session, next Turn.
+    turn = await thread.run("Now list its top-level directories.")
+
+    # Persist thread.id and continue later.
+    later = client.resume_thread(thread.id)
+    print((await later.run("What did I ask first?")).final_response)
+
+
+asyncio.run(main())
+```
+
+### Streaming
+
+```python
+streamed = await thread.run_streamed("Fix the failing test.")
+async for event in streamed:
+    if event["type"] == "item.updated" and event["item"]["type"] == "agent_message":
+        print(event["item"].get("contentDelta", ""), end="")
+    elif event["type"] == "turn.failed":
+        print("failed:", event.get("error"))
+```
+
+Events are the CLI's stream-json events, passed through unchanged (unknown types included).
+`turn.failed` is an ordinary event; iteration raises only for process or protocol failures.
+
+### Cancellation
+
+- `streamed.cancel()` sends SIGINT; the stream ends with the CLI's final events.
+- Leaving the `async for` early, or cancelling the task running `thread.run()`, stops the CLI
+  (SIGINT, then SIGKILL after a grace period).
+- `RunOptions(timeout_ms=...)` is enforced by the CLI.
+
+### Blocking API
+
+```python
+from minimax_code import SyncMCode
+
+with SyncMCode() as client:
+    thread = client.start_thread()
+    print(thread.run("hello").final_response)
+    for event in thread.run_streamed("again"):
+        print(event["type"])
+```
+
+## Options
+
+| Object | Fields |
+| --- | --- |
+| `MCodeOptions` | `bin`, `data_dir` (`MINIMAX_DATA_DIR`), `env` (replaces `os.environ`), `config_path` |
+| `ThreadOptions` | `cwd`, `model` (`provider/model`), `effort`, `permission` (`smart`/`full`/`off`), `mode`, `prompt_mode`, `system_prompt`, `append_system_prompt` |
+| `RunOptions` | `files`, `timeout_ms`, `max_steps` |
+
+## Errors
+
+All errors subclass `MCodeError` (with `exit_code`, `stderr`, `session_id`, `result`, `items`):
+`MCodeNotFoundError`, `MCodeVersionError`, `MCodeInvocationError`, `MCodeRunError`
+(`status`, `category`), `MCodeAbortError`, `MCodeProtocolError`, `ThreadBusyError`.
+
+## Limitations
+
+Each Turn is a separate process, so interactive permission prompts (`permission="ask"`) and
+custom in-process tools are not supported yet. A long-lived ACP transport is planned.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check . && uv run ruff format --check . && uv run mypy
+```
+
+End-to-end tests against a real CLI and model are opt-in:
+`MCODE_SDK_E2E=1 MCODE_BIN=/path/to/mcode uv run pytest -m e2e`.
+
+Release notes are in
+[CHANGELOG.md](https://github.com/MiniMax-AI/minimax-code/blob/main/packages/code-sdk-python/CHANGELOG.md);
+maintainers publish with
+[RELEASING.md](https://github.com/MiniMax-AI/minimax-code/blob/main/packages/code-sdk-python/RELEASING.md).
+
+## License
+
+MIT

minimax_code_sdk-0.1.0b1/RELEASING.md

@@ -0,0 +1,135 @@
+# Releasing `minimax-code-sdk`
+
+The Python SDK is published to the public PyPI index as `minimax-code-sdk` by the
+`Python SDK release` workflow (`.github/workflows/python-sdk-release.yml`) using PyPI Trusted
+Publishing. No PyPI token is stored in the repository or in GitHub secrets. It is versioned
+independently of the CLI and of `@minimax-ai/code-sdk`.
+
+## Rules
+
+- Publish only from a commit on `main` that went through a reviewed pull request. The workflow
+  rejects a tag whose commit is not contained in `origin/main`.
+- A published version is immutable. PyPI never accepts the same file name twice, even after a
+  release is deleted. Fix problems in a new version; prefer **yanking** a broken release over
+  deleting it.
+- Versions are stable `X.Y.Z` or PEP 440 pre-releases `X.Y.ZaN`, `X.Y.ZbN` and `X.Y.ZrcN` (for
+  example `0.1.0b1`), written in canonical form. Never use npm-style `0.1.0-beta.1`. See
+  [Pre-releases](#pre-releases).
+- Release tags are `code-sdk-python-v<version>`, for example `code-sdk-python-v0.1.0b1`. They are separate from CLI tags (`vX.Y.Z`) and
+  TypeScript SDK tags (`code-sdk-vX.Y.Z`). Never move or delete a pushed release tag.
+- Do not upload from a workstation. If the workflow is unavailable, fix the workflow.
+
+## One-time setup
+
+1. The PyPI project `minimax-code-sdk` belongs to the `minimax-ai` PyPI organization. Every
+   owner and maintainer account uses two-factor authentication.
+2. On PyPI, add a Trusted Publisher (a *pending* publisher before the first upload) with:
+
+   | Field | Value |
+   | --- | --- |
+   | PyPI project name | `minimax-code-sdk` |
+   | Owner | `MiniMax-AI` |
+   | Repository | `minimax-code` |
+   | Workflow | `python-sdk-release.yml` |
+   | Environment | `pypi` |
+
+3. For rehearsals, add the same publisher on TestPyPI with environment `testpypi`. TestPyPI
+   accounts and projects are separate from PyPI.
+4. In the GitHub repository settings, create the environments `pypi` and `testpypi`. Give
+   `pypi` required reviewers and restrict its deployment refs to `code-sdk-python-v*` tags.
+
+## 1. Prepare the release in a pull request
+
+1. Update `version` in `packages/code-sdk-python/pyproject.toml` and `__version__` in
+   `src/minimax_code/__init__.py`.
+2. Add a section at the top of `CHANGELOG.md`: `## X.Y.Z · YYYY-MM-DD` with the user-visible
+   changes.
+3. If the minimum supported CLI, the Python range or the event `schemaVersion` changes, update the
+   README and `MIN_CLI_VERSION` in `src/minimax_code/_cli.py`.
+4. Run the local checks:
+
+   ```bash
+   cd packages/code-sdk-python
+   uv sync --locked
+   uv run ruff check . && uv run ruff format --check . && uv run mypy && uv run pytest -W error
+   uv run python scripts/release_check.py metadata --index pypi
+   ```
+
+5. Merge the pull request into `main` after the usual review and checks.
+
+## 2. Optional: rehearse on TestPyPI
+
+Run the `Python SDK release` workflow manually with `repository: testpypi`. It runs every
+check below and uploads to TestPyPI. Each version can be uploaded to TestPyPI only once, so
+rehearse only versions you intend to release. A manual run with `repository: none` builds and
+checks without uploading anywhere.
+
+## 3. Tag and publish
+
+```bash
+git switch main
+git pull --ff-only
+git tag -a code-sdk-python-vX.Y.Z -m "minimax-code-sdk X.Y.Z"
+git push origin code-sdk-python-vX.Y.Z
+```
+
+The tag push starts the workflow. Its `build` job:
+
+1. checks that the tag matches `pyproject.toml`, `__version__` and the first CHANGELOG heading,
+   that the tagged commit is on `origin/main`, and that the version is not on PyPI yet;
+2. runs ruff, mypy and the test suite;
+3. builds the wheel and sdist with `uv build` and runs `twine check --strict`;
+4. runs `scripts/release_check.py dist`, which rejects unexpected wheel entries, local or
+   generated files and unsafe paths in the sdist, and prints the sha256 of both files;
+5. scans the extracted archives with the repository's public text policy
+   (`scripts/lib/public-text-policy.mjs`) and Gitleaks;
+6. installs the wheel into an empty virtual environment and checks `minimax_code.__version__`.
+
+The `publish-pypi` job then waits for approval on the `pypi` environment and uploads exactly the
+checked files with `pypa/gh-action-pypi-publish`, which also attaches PyPI attestations.
+
+## Pre-releases
+
+Pre-releases go to the real PyPI index through the same workflow and checks; only the version
+differs. Installers skip them unless the user passes `--pre` (pip), `--prerelease=allow` (uv) or
+pins the exact version, so `pip install minimax-code-sdk` keeps resolving to the newest stable
+release once one exists. Keep the README install instructions in line with the latest release.
+
+- Fix a broken pre-release with the next number (`0.1.0b2`), not by reusing a version.
+- Promote by releasing `0.1.0` with its own CHANGELOG section; earlier pre-releases stay in the
+  history and need no cleanup.
+- When the first stable release ships, drop `--pre` from the README install instructions and
+  replace `Development Status :: 4 - Beta` in `pyproject.toml` as appropriate.
+
+## 4. Read back
+
+```bash
+curl -fsS https://pypi.org/pypi/minimax-code-sdk/X.Y.Z/json \
+  | python3 -c 'import json,sys; [print(u["digests"]["sha256"], u["filename"]) for u in json.load(sys.stdin)["urls"]]'
+```
+
+Both digests must equal the `sha256` lines printed by the `Check distribution contents` step. If
+they differ, stop: the index holds different bytes than the checked files.
+
+## 5. Smoke test the published package
+
+```bash
+smoke="$(mktemp -d)" && cd "$smoke"
+uv venv -q && uv pip install -q "minimax-code-sdk==X.Y.Z"
+.venv/bin/python -c "import minimax_code; print(minimax_code.__version__, minimax_code.MCode)"
+```
+
+It must print `X.Y.Z` and the `MCode` class. PyPI's CDN can take a few minutes to serve a new
+version.
+
+## Failure handling
+
+- **The `build` job fails**: nothing was published. Fix it in a pull request, merge, and tag a new
+  commit. If the version number itself was wrong, use a new version; do not reuse the tag.
+- **`publish-pypi` fails before upload** (Trusted Publisher mismatch, network): fix the cause and
+  re-run the failed job of the same workflow run. The artifact is the already checked build.
+- **Upload accepted but read-back fails**: wait and repeat the read-back. Do not re-run the upload
+  unless PyPI confirms the version does not exist.
+- **Digests differ or the smoke test fails**: the version is published and cannot be replaced.
+  Release a fixed version and yank the broken one on PyPI (*Manage project → Releases → Options →
+  Yank*) with a reason.

minimax_code_sdk-0.1.0b1/examples/basic.py

@@ -0,0 +1,22 @@
+"""Run one Turn, a follow-up Turn, and resume the Session from its id."""
+
+import asyncio
+import sys
+
+from minimax_code import MCode, ThreadOptions
+
+
+async def main() -> None:
+    client = MCode()
+    thread = client.start_thread(ThreadOptions(cwd=".", permission="smart"))
+    turn = await thread.run(sys.argv[1] if len(sys.argv) > 1 else "Say hello in one sentence.")
+    print(turn.final_response)
+    print("session:", thread.id, "usage:", turn.usage)
+
+    assert thread.id is not None
+    resumed = client.resume_thread(thread.id)
+    print((await resumed.run("Repeat your previous answer in five words.")).final_response)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

minimax_code_sdk-0.1.0b1/examples/streaming.py

@@ -0,0 +1,24 @@
+"""Print the agent's answer as it streams, and tool calls as they finish."""
+
+import asyncio
+import sys
+
+from minimax_code import MCode
+
+
+async def main() -> None:
+    thread = MCode().start_thread()
+    streamed = await thread.run_streamed(sys.argv[1] if len(sys.argv) > 1 else "List files here.")
+    async for event in streamed:
+        item = event.get("item")
+        if item and item["type"] == "agent_message":
+            print(item.get("contentDelta", ""), end="", flush=True)
+        elif item and item["type"] == "tool_call" and event["type"] == "item.completed":
+            print(f"\n[tool] {item.get('toolCall', {}).get('name')}")
+        elif event["type"] == "turn.failed":
+            print("\nturn failed:", event.get("error"))
+    print()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

minimax_code_sdk-0.1.0b1/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "minimax-code-sdk"
+version = "0.1.0b1"
+description = "Python SDK for driving the local MiniMax Code (mcode) agent."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+dependencies = ["typing_extensions>=4.7"]
+keywords = ["minimax", "minimax-code", "mcode", "agent", "coding-agent", "sdk"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://agent.minimax.io"
+Repository = "https://github.com/MiniMax-AI/minimax-code"
+Issues = "https://github.com/MiniMax-AI/minimax-code/issues"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "ruff>=0.6", "mypy>=1.11"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/minimax_code"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+markers = ["e2e: runs a real mcode CLI against a real model (opt-in via MCODE_SDK_E2E=1)"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP", "SIM", "RUF"]
+
+[tool.mypy]
+strict = true
+python_version = "3.10"
+files = ["src", "tests"]