minimax-code-sdk 0.1.0__py3-none-any.whl

minimax_code/errors.py

@@ -0,0 +1,167 @@
+"""SDK errors. Mirrors ``packages/code-sdk/src/errors.ts``."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import Any
+
+from .types import ExecResult, ThreadItem
+
+#: Exit codes of ``mcode exec`` (``MINIMAX_CODE_EXEC_EXIT_CODES`` in the CLI).
+MCODE_EXEC_EXIT_CODES: dict[str, int] = {
+    "success": 0,
+    "invocation": 2,
+    "config": 3,
+    "runtime": 4,
+    "timeout": 6,
+    "limit": 7,
+    "internal": 70,
+    "cancelled": 130,
+    "broken_pipe": 141,
+}
+
+MCODE_INSTALL_HINT = "npm install -g @minimax-ai/code@latest"
+
+
+class MCodeError(Exception):
+    """Base class for every error raised by the SDK."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        exit_code: int | None = None,
+        stderr: str = "",
+        session_id: str | None = None,
+        result: ExecResult | None = None,
+        items: Sequence[ThreadItem] = (),
+    ) -> None:
+        super().__init__(message)
+        self.exit_code = exit_code
+        #: Tail of the CLI stderr, for diagnostics only.
+        self.stderr = stderr
+        self.session_id = session_id
+        self.result = result
+        self.items = list(items)
+
+    def __reduce__(self) -> tuple[Any, ...]:
+        # The default reduce calls ``cls(*self.args)``, which breaks subclasses whose
+        # ``__init__`` takes other arguments. Rebuild from ``args`` and restore the attributes.
+        return (_restore_error, (type(self), self.args), self.__dict__)
+
+
+def _restore_error(cls: type[MCodeError], args: tuple[Any, ...]) -> MCodeError:
+    """Unpickles an ``MCodeError`` without calling its ``__init__``."""
+    return cls.__new__(cls, *args)
+
+
+class MCodeInvocationError(MCodeError):
+    """Invalid SDK options, or the CLI rejected the invocation (exit code 2)."""
+
+
+class MCodeRunError(MCodeError):
+    """The Turn ended with ``failed``, ``timeout`` or ``limit_exceeded``."""
+
+    def __init__(self, message: str, *, status: str, category: str | None = None, **kw: Any):
+        super().__init__(message, **kw)
+        self.status = status
+        self.category = category
+
+
+class MCodeAbortError(MCodeError):
+    """The Turn was cancelled."""
+
+
+class MCodeProtocolError(MCodeError):
+    """The CLI produced output the SDK cannot understand."""
+
+
+class MCodeNotFoundError(MCodeError):
+    """The ``mcode`` CLI could not be found."""
+
+
+class MCodeVersionError(MCodeError):
+    """The CLI is too old or speaks an unsupported schema version."""
+
+
+class ThreadBusyError(MCodeError):
+    """A Thread already has a Turn in progress."""
+
+    def __init__(self, thread_id: str | None) -> None:
+        super().__init__(f"Thread {thread_id or '(new)'} already has a Turn in progress.")
+
+
+_STATUS_BY_EXIT_CODE: dict[int, tuple[str, str | None]] = {
+    3: ("failed", "config"),
+    4: ("failed", "runtime"),
+    6: ("timeout", None),
+    7: ("limit_exceeded", None),
+    70: ("failed", "internal"),
+}
+
+
+def error_for_result(
+    result: ExecResult, items: Sequence[ThreadItem], *, exit_code: int | None, stderr: str
+) -> MCodeError:
+    common: dict[str, Any] = {
+        "exit_code": exit_code,
+        "stderr": stderr,
+        "session_id": result["sessionId"],
+        "result": result,
+        "items": items,
+    }
+    if result["status"] == "cancelled":
+        return MCodeAbortError("The MCode run was cancelled.", **common)
+    status = "failed" if result["status"] == "succeeded" else result["status"]
+    error: Any = result.get("error")
+    if not isinstance(error, dict):
+        error = {}
+    message = error.get("message")
+    reason = message if isinstance(message, str) and message else f"status {result['status']}"
+    category = error.get("category")
+    if not isinstance(category, str):
+        category = None
+    return MCodeRunError(
+        f"The MCode run ended with {status}: {reason}", status=status, category=category, **common
+    )
+
+
+def error_for_exit(
+    *,
+    exit_code: int | None,
+    stderr: str,
+    items: Sequence[ThreadItem],
+    session_id: str | None,
+    timed_out: bool = False,
+) -> MCodeError:
+    """Maps a CLI exit without ``exec.completed`` to an error. ``timed_out`` means the SDK's
+    ``timeout_ms`` backstop killed the CLI, which is a timeout and not a cancellation."""
+    lines = [line.strip() for line in stderr.splitlines() if line.strip()]
+    reason = lines[-1] if lines else f"exit code {exit_code}"
+    common: dict[str, Any] = {
+        "exit_code": exit_code,
+        "stderr": stderr,
+        "items": items,
+        "session_id": session_id,
+    }
+    if timed_out:
+        return MCodeRunError(
+            "The MCode run exceeded timeout_ms and was force-stopped by the SDK.",
+            status="timeout",
+            **common,
+        )
+    if exit_code == MCODE_EXEC_EXIT_CODES["invocation"]:
+        return MCodeInvocationError(f"mcode rejected the invocation: {reason}", **common)
+    if exit_code == MCODE_EXEC_EXIT_CODES["cancelled"] or (exit_code is not None and exit_code < 0):
+        return MCodeAbortError("The MCode run was cancelled.", **common)
+    if exit_code == MCODE_EXEC_EXIT_CODES["broken_pipe"]:
+        return MCodeProtocolError(f"mcode reported a broken output pipe: {reason}", **common)
+    if exit_code == 0:
+        return MCodeProtocolError("mcode exited without emitting exec.completed.", **common)
+    status, category = _STATUS_BY_EXIT_CODE.get(exit_code or -1, ("failed", "internal"))
+    return MCodeRunError(
+        f"The MCode run ended without a result: {reason}",
+        status=status,
+        category=category,
+        **common,
+    )

minimax_code/sync.py

@@ -0,0 +1,71 @@
+"""Blocking wrappers around the async API, for code that has no running event loop.
+
+They cannot be called where an event loop is already running, such as a Jupyter notebook cell or
+an ``async def`` function (``RuntimeError: Cannot run the event loop while another loop is
+running``); use the async API with ``await`` there.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Iterator
+from typing import Any
+
+from .client import MCode
+from .thread import Thread
+from .types import MCodeOptions, RunOptions, ThreadEvent, ThreadOptions, Turn
+
+
+class SyncThread:
+    def __init__(self, loop: asyncio.AbstractEventLoop, thread: Thread) -> None:
+        self._loop = loop
+        self._thread = thread
+
+    @property
+    def id(self) -> str | None:
+        return self._thread.id
+
+    def run(self, input: str, options: RunOptions | None = None) -> Turn:
+        return self._loop.run_until_complete(self._thread.run(input, options))
+
+    def run_streamed(self, input: str, options: RunOptions | None = None) -> Iterator[ThreadEvent]:
+        """Yields events; closing the iterator early cancels the Turn."""
+        streamed = self._loop.run_until_complete(self._thread.run_streamed(input, options))
+        events = streamed.events
+        try:
+            while True:
+                try:
+                    yield self._loop.run_until_complete(events.__anext__())
+                except StopAsyncIteration:
+                    return
+        finally:
+            self._loop.run_until_complete(streamed.aclose())
+
+
+class SyncMCode:
+    """Blocking client. Owns a private event loop; call ``close()`` (or use ``with``) when done."""
+
+    def __init__(self, options: MCodeOptions | None = None) -> None:
+        self._loop = asyncio.new_event_loop()
+        self._client = MCode(options)
+
+    def start_thread(self, options: ThreadOptions | None = None) -> SyncThread:
+        return SyncThread(self._loop, self._client.start_thread(options))
+
+    def resume_thread(self, thread_id: str, options: ThreadOptions | None = None) -> SyncThread:
+        """Continues an existing Session; pass the ``cwd`` it was created with (see
+        ``MCode.resume_thread``)."""
+        return SyncThread(self._loop, self._client.resume_thread(thread_id, options))
+
+    def close(self) -> None:
+        if not self._loop.is_closed():
+            # Let subprocess transports finish closing before the loop goes away.
+            self._loop.run_until_complete(asyncio.sleep(0.05))
+            self._loop.run_until_complete(self._loop.shutdown_asyncgens())
+            self._loop.close()
+
+    def __enter__(self) -> SyncMCode:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()