opensandbox-code-interpreter 0.1.2.dev0__py3-none-any.whl → 1.1.1__py3-none-any.whl

code_interpreter/__init__.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

code_interpreter/adapters/__init__.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

code_interpreter/adapters/code_adapter.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -22,6 +22,7 @@ API clients and handling SSE streaming for real-time code execution.
 
 import json
 import logging
+import time
 
 import httpx
 from opensandbox.adapters.converter.event_node import EventNode
@@ -32,6 +33,7 @@ from opensandbox.adapters.converter.execution_event_dispatcher import (
     ExecutionEventDispatcher,
 )
 from opensandbox.adapters.converter.response_handler import (
+    extract_request_id,
     handle_api_error,
     require_parsed,
 )
@@ -39,6 +41,7 @@ from opensandbox.config import ConnectionConfig
 from opensandbox.exceptions import InvalidArgumentException, SandboxApiException
 from opensandbox.models.execd import Execution, ExecutionHandlers
 from opensandbox.models.sandboxes import SandboxEndpoint
+from opensandbox.transport import unwrap_retry_transport
 
 from code_interpreter.adapters.converter.code_execution_converter import (
     CodeExecutionConverter,
@@ -49,18 +52,28 @@ from code_interpreter.services.code import Codes
 logger = logging.getLogger(__name__)
 
 
+def _normalize_sse_event(event_dict: dict) -> dict:
+    if "type" in event_dict and "timestamp" in event_dict:
+        return event_dict
+    if "code" in event_dict and "message" in event_dict:
+        return {
+            "type": "error",
+            "timestamp": int(time.time() * 1000),
+            "error": {
+                "ename": str(event_dict["code"]),
+                "evalue": str(event_dict["message"]),
+                "traceback": [],
+            },
+        }
+    return event_dict
+
+
 class CodesAdapter(Codes):
     """
     Adapter implementation for code execution service.
 
-    This adapter wraps auto-generated API clients and provides the concrete
-    implementation of the Codes interface. It handles both standard
-    API calls and SSE streaming for real-time code execution output.
-
-    Similar to CommandServiceAdapter, this adapter uses:
-    - Generated API clients for simple operations (create_context, interrupt)
-    - Direct httpx SSE streaming for run
-    - ExceptionConverter for unified exception handling
+    Handles standard API calls plus direct httpx SSE streaming for
+    real-time code execution output.
     """
 
     RUN_CODE_PATH = "/code"
@@ -85,10 +98,7 @@ class CodesAdapter(Codes):
         timeout_seconds = self.connection_config.request_timeout.total_seconds()
         timeout = httpx.Timeout(timeout_seconds)
 
-        headers = {
-            "User-Agent": self.connection_config.user_agent,
-            **self.connection_config.headers,
-        }
+        headers = self.execd_endpoint.build_request_headers(self.connection_config)
 
         # Execd API does not require authentication
         self._client = Client(
@@ -96,12 +106,19 @@ class CodesAdapter(Codes):
             timeout=timeout,
         )
 
-        # Inject httpx client (adapter-owned)
+        # Adapter clients must own their transports: aclose() closes them,
+        # and the shared/user connection_config transport must survive that.
+        self._owns_clients = self.connection_config.owns_transport
+        main_transport: httpx.AsyncBaseTransport | None
+        if self._owns_clients:
+            main_transport = self.connection_config.new_owned_transport()
+        else:
+            main_transport = self.connection_config.transport
         self._httpx_client = httpx.AsyncClient(
             base_url=base_url,
             headers=headers,
             timeout=timeout,
-            transport=self.connection_config.transport,
+            transport=main_transport,
         )
         self._client.set_async_httpx_client(self._httpx_client)
 
@@ -111,6 +128,14 @@ class CodesAdapter(Codes):
             "Accept": "text/event-stream",
             "Cache-Control": "no-cache",
         }
+        # SSE bootstraps bypass the retry wrapper: request bodies are
+        # not replayable and a non-idempotent status opt-in would cause
+        # duplicate execution on a resent SSE POST.
+        sse_transport = (
+            self.connection_config.new_owned_transport()
+            if self._owns_clients
+            else self.connection_config.transport
+        )
         self._sse_client = httpx.AsyncClient(
             headers=sse_headers,
             timeout=httpx.Timeout(
@@ -119,7 +144,7 @@ class CodesAdapter(Codes):
                 write=timeout_seconds,
                 pool=None,
             ),
-            transport=self.connection_config.transport,
+            transport=unwrap_retry_transport(sse_transport),
         )
 
     async def _get_client(self):
@@ -135,6 +160,21 @@ class CodesAdapter(Codes):
         """Return SSE client (read timeout disabled) for execd streaming."""
         return self._sse_client
 
+    async def aclose(self) -> None:
+        """Release the adapter-owned HTTP clients.
+
+        Never closes the shared ``connection_config.transport``; the sandbox
+        stays usable after ``aclose()``. Clients wrapping a user-supplied
+        transport are left open (httpx would close the caller's transport
+        with them).
+        """
+        if not self._owns_clients:
+            return
+        try:
+            await self._httpx_client.aclose()
+        finally:
+            await self._sse_client.aclose()
+
     async def create_context(self, language: str) -> CodeContext:
         """
         Creates a new execution context for code interpretation.
@@ -197,7 +237,9 @@ class CodesAdapter(Codes):
             )
             handle_api_error(response_obj, "List code contexts")
             parsed_list = require_parsed(response_obj, list, "List code contexts")
-            return [CodeExecutionConverter.from_api_code_context(c) for c in parsed_list]
+            return [
+                CodeExecutionConverter.from_api_code_context(c) for c in parsed_list
+            ]
         except Exception as e:
             logger.error("Failed to list contexts", exc_info=e)
             raise ExceptionConverter.to_sandbox_exception(e) from e
@@ -243,14 +285,18 @@ class CodesAdapter(Codes):
         """
         Executes code within the specified context using SSE streaming.
 
-        Similar to CommandServiceAdapter.run, this uses direct httpx
+        Uses direct httpx
         streaming to handle SSE responses from the execd service.
         """
         if not code.strip():
             raise InvalidArgumentException("Code cannot be empty")
 
         try:
-            if context is not None and language is not None and context.language != language:
+            if (
+                context is not None
+                and language is not None
+                and context.language != language
+            ):
                 raise InvalidArgumentException(
                     f"language '{language}' must match context.language '{context.language}'"
                 )
@@ -280,13 +326,12 @@ class CodesAdapter(Codes):
                     await response.aread()
                     error_body = response.text
                     logger.error(
-                        "Failed to run code. Status: %s, Body: %s",
-                        response.status_code,
-                        error_body,
+                        f"Failed to run code. Status: {response.status_code}, Body: {error_body}"
                     )
                     raise SandboxApiException(
-                        message=f"Failed to run code. Status code: {response.status_code}",
+                        message=f"Failed to run code. Status code: {response.status_code}, Body: {error_body}",
                         status_code=response.status_code,
+                        request_id=extract_request_id(response.headers),
                     )
 
                 dispatcher = ExecutionEventDispatcher(execution, handlers)
@@ -301,22 +346,20 @@ class CodesAdapter(Codes):
                         data = data[5:].strip()
 
                     try:
-                        event_dict = json.loads(data)
+                        event_dict = _normalize_sse_event(json.loads(data))
                         event_node = EventNode(**event_dict)
                         await dispatcher.dispatch(event_node)
                     except json.JSONDecodeError:
-                        logger.debug("Failed to parse SSE line: %s", line)
+                        logger.debug(f"Failed to parse SSE line: {line}")
                         continue
                     except Exception as e:
-                        logger.error("Error processing event: %s", data, exc_info=e)
+                        logger.error(f"Error processing event: {data}", exc_info=e)
                         continue
 
             return execution
 
         except Exception as e:
-            logger.error(
-                "Failed to run code (length: %s)", len(code), exc_info=e
-            )
+            logger.error(f"Failed to run code (length: {len(code)})", exc_info=e)
             raise ExceptionConverter.to_sandbox_exception(e) from e
 
     async def interrupt(self, execution_id: str) -> None:
@@ -339,3 +382,23 @@ class CodesAdapter(Codes):
         except Exception as e:
             logger.error("Failed to interrupt code execution", exc_info=e)
             raise ExceptionConverter.to_sandbox_exception(e) from e
+
+    async def ping(self) -> bool:
+        """
+        Check if the execd code execution service is alive.
+
+        Uses the shared generated API client so the ping exercises the same
+        HTTP client and endpoint that serve code execution requests.
+        """
+        try:
+            from opensandbox.api.execd.api.health import ping as ping_api
+
+            client = await self._get_client()
+            response_obj = await ping_api.asyncio_detailed(client=client)
+
+            handle_api_error(response_obj, "Ping code interpreter")
+            return True
+
+        except Exception as e:
+            logger.debug(f"Code interpreter ping failed: {e}")
+            return False

code_interpreter/adapters/converter/__init__.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

code_interpreter/adapters/converter/code_execution_converter.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

code_interpreter/adapters/factory.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

code_interpreter/code_interpreter.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -21,12 +21,17 @@ functionality with specialized code execution features, including multi-language
 support, session management, and variable persistence.
 """
 
+import asyncio
+import contextlib
 import logging
+import time
+from datetime import timedelta
 
 from opensandbox.exceptions import (
     InvalidArgumentException,
     SandboxException,
     SandboxInternalException,
+    SandboxReadyTimeoutException,
 )
 from opensandbox.sandbox import Sandbox
 
@@ -35,6 +40,21 @@ from code_interpreter.services.code import Codes
 
 logger = logging.getLogger(__name__)
 
+DEFAULT_READY_TIMEOUT = timedelta(seconds=30)
+DEFAULT_HEALTH_CHECK_POLLING_INTERVAL = timedelta(milliseconds=200)
+
+# Strict health check script: verifies the code interpreter runtime (Jupyter
+# kernel gateway) is actually serving inside the sandbox. execd starts serving
+# /ping before the entrypoint launches Jupyter, and the setup stage may run
+# short-lived "jupyter kernelspec" helpers, so a daemon ping or a process-name
+# grep cannot prove the runtime is ready. Probing the Jupyter listen port
+# (127.0.0.1:${JUPYTER_PORT:-44771}, same default as the entrypoint) only
+# passes once the server accepts connections.
+RUNTIME_PROCESS_CHECK_COMMAND = (
+    "bash -c 'exec 3<>/dev/tcp/127.0.0.1/${JUPYTER_PORT:-44771}' "
+    "&& exit 0 || exit 1"
+)
+
 
 class CodeInterpreter:
     """
@@ -45,7 +65,7 @@ class CodeInterpreter:
 
     Key Features:
 
-    - Multi-language Code Execution: Support for Python, JavaScript, Bash, Java, Kotlin
+    - Multi-language Code Execution: Python, JavaScript, TypeScript, Go, Bash
     - Session Management: Persistent execution contexts with variable state
     - Sandbox Integration: Full access to underlying sandbox file system and command execution
     - Streaming Execution: Real-time code execution with output streaming
@@ -54,11 +74,12 @@ class CodeInterpreter:
     Usage Example:
 
     ```python
-    # First create a sandbox instance
-
+    # The sandbox must use the opensandbox/code-interpreter image (or a
+    # derivative); the strict health check requires the Jupyter runtime.
     sandbox = await Sandbox.create(
-        "python:3.11",
-        resource={"cpu": "1", "memory": "2Gi"}
+        "opensandbox/code-interpreter:latest",
+        entrypoint=["/opt/code-interpreter/code-interpreter.sh"],
+        resource={"cpu": "1", "memory": "2Gi"},
     )
 
     # Then create a code interpreter wrapping the sandbox
@@ -68,9 +89,10 @@ class CodeInterpreter:
     from code_interpreter.models.code import SupportedLanguage
     context = await interpreter.codes.create_context(SupportedLanguage.PYTHON)
     result = await interpreter.codes.run("print('Hello World')", context=context)
-    print(result.logs.stdout)  # Output: Hello World
+    print(result.text)  # Output: Hello World
 
     # Access underlying sandbox for file operations
+    from opensandbox.models.filesystem import WriteEntry
     await interpreter.sandbox.files.write_files([
         WriteEntry(path="data.txt", data="Hello")
     ])
@@ -79,10 +101,16 @@ class CodeInterpreter:
         context=context,
     )
 
-    # Always clean up resources
+    # Clean up: closing the interpreter releases its HTTP clients; the
+    # underlying sandbox lifecycle stays caller-owned.
+    await interpreter.aclose()
     await sandbox.kill()
     await sandbox.close()
     ```
+
+    CodeInterpreter also supports the async context-manager protocol; exiting
+    the ``async with`` block releases the interpreter's HTTP clients (not the
+    sandbox).
     """
 
     def __init__(self, sandbox: Sandbox, code_service: Codes) -> None:
@@ -142,6 +170,24 @@ class CodeInterpreter:
         """
         return self._sandbox.commands
 
+    async def aclose(self) -> None:
+        """
+        Release resources owned by the code interpreter.
+
+        Closes the HTTP clients used by the code execution service. The
+        underlying sandbox is NOT affected; manage its lifecycle separately
+        (``sandbox.kill()`` / ``sandbox.close()``). Safe to call multiple times.
+        """
+        aclose = getattr(self._code_service, "aclose", None)
+        if aclose is not None:
+            await aclose()
+
+    async def __aenter__(self) -> "CodeInterpreter":
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.aclose()
+
     @property
     def metrics(self):
         """
@@ -169,14 +215,114 @@ class CodeInterpreter:
         """
         return self._code_service
 
+    async def ping(self) -> bool:
+        """
+        Check if the code execution service (execd) is responsive.
+
+        Returns:
+            True if the code execution service is responsive, False otherwise
+        """
+        return await self._code_service.ping()
+
+    async def is_healthy(self) -> bool:
+        """
+        Check if the code interpreter is healthy (strict check).
+
+        Healthy means both:
+
+        - the code execution service (execd) answers ``GET /ping``; and
+        - the code interpreter runtime (Jupyter kernel gateway) is serving
+          inside the sandbox, verified by probing its listen port through the
+          execd command API.
+
+        Exceptions raised by either leg are treated as unhealthy.
+
+        Returns:
+            True if healthy, False otherwise
+        """
+        try:
+            return await self.ping() and await self._is_runtime_process_alive()
+        except Exception:
+            return False
+
+    async def _is_runtime_process_alive(self) -> bool:
+        """
+        Check if the code interpreter runtime (Jupyter) is serving.
+
+        Probes the runtime listen port through the sandbox command service and
+        treats a failed command (non-zero exit surfaced as an execution error)
+        as an unhealthy runtime.
+        """
+        try:
+            execution = await self._sandbox.commands.run(
+                RUNTIME_PROCESS_CHECK_COMMAND
+            )
+            return execution.error is None
+        except Exception:
+            return False
+
+    async def check_ready(
+        self,
+        timeout: timedelta,
+        polling_interval: timedelta,
+    ) -> None:
+        """
+        Wait for the code interpreter to pass the strict health check with polling.
+
+        Raises:
+            SandboxReadyTimeoutException: if the health check doesn't pass within timeout
+        """
+        logger.info(
+            f"Waiting for code interpreter {self.id} to pass health check "
+            f"(timeout: {timeout.total_seconds()}s)"
+        )
+
+        deadline = time.monotonic() + timeout.total_seconds()
+        attempt = 0
+
+        while time.monotonic() < deadline:
+            attempt += 1
+            if await self.is_healthy():
+                logger.info(
+                    f"Code interpreter {self.id} passed health check "
+                    f"after {attempt} attempts"
+                )
+                return
+
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            await asyncio.sleep(min(polling_interval.total_seconds(), remaining))
+
+        raise SandboxReadyTimeoutException(
+            f"Code interpreter {self.id} health check timed out after "
+            f"{timeout.total_seconds()}s ({attempt} attempts). The code execution "
+            f"service (execd) or the interpreter runtime (Jupyter) did not become "
+            f"ready. Pass skip_health_check=True to skip this check."
+        )
+
     @classmethod
-    async def create(cls, sandbox: Sandbox) -> "CodeInterpreter":
+    async def create(
+        cls,
+        sandbox: Sandbox,
+        *,
+        ready_timeout: timedelta = DEFAULT_READY_TIMEOUT,
+        health_check_polling_interval: timedelta = DEFAULT_HEALTH_CHECK_POLLING_INTERVAL,
+        skip_health_check: bool = False,
+    ) -> "CodeInterpreter":
         """
         Creates a CodeInterpreter from an existing Sandbox instance.
 
         This factory method handles the creation and initialization of CodeInterpreter
         services, including the code execution service and language configuration.
 
+        By default a strict health check runs before the interpreter is returned:
+        the code execution service (execd) must answer ``GET /ping`` AND the
+        code interpreter runtime (Jupyter kernel gateway) must be serving,
+        both within ``ready_timeout``. execd starts serving before the runtime
+        launches, so the daemon ping alone is not enough. Set
+        ``skip_health_check=True`` to opt out.
+
         CodeInterpreter must be created by wrapping an existing Sandbox instance with
         code execution capabilities. This design ensures clear separation of concerns:
         - Sandbox handles infrastructure (containers, resources, networking)
@@ -184,6 +330,10 @@ class CodeInterpreter:
 
         Args:
             sandbox: Existing sandbox instance to wrap with code execution capabilities
+            ready_timeout: Maximum time to wait for the code execution service health check
+            health_check_polling_interval: Time between health check attempts
+            skip_health_check: If True, do not wait for the code execution service
+                to become ready; the returned interpreter may fail on first use
 
         Returns:
             CodeInterpreter instance wrapping the sandbox
@@ -191,24 +341,41 @@ class CodeInterpreter:
         Raises:
             InvalidArgumentException: If sandbox is not provided
             SandboxException: If creation fails
+            SandboxReadyTimeoutException: If the code execution service health check
+                times out and ``skip_health_check`` is False
             SandboxInternalException: If internal service initialization fails
         """
         if sandbox is None:
             raise InvalidArgumentException("Sandbox instance must be provided")
 
-        logger.info("Creating code interpreter from sandbox: %s", sandbox.id)
+        logger.info(f"Creating code interpreter from sandbox: {sandbox.id}")
 
         factory = AdapterFactory(sandbox.connection_config)
 
         try:
             # Connect to the execd daemon endpoint for code execution services
             from opensandbox.constants import DEFAULT_EXECD_PORT
+
             code_interpreter_endpoint = await sandbox.get_endpoint(DEFAULT_EXECD_PORT)
-            code_execution_service = factory.create_code_execution_service(code_interpreter_endpoint)
+            code_execution_service = factory.create_code_execution_service(
+                code_interpreter_endpoint
+            )
+
+            interpreter = cls(sandbox, code_execution_service)
+            try:
+                if not skip_health_check:
+                    await interpreter.check_ready(
+                        ready_timeout, health_check_polling_interval
+                    )
+            except Exception:
+                # Don't leak the service's clients on a failed creation.
+                with contextlib.suppress(Exception):
+                    await interpreter.aclose()
+                raise
 
-            logger.info("Code interpreter %s created successfully", sandbox.id)
+            logger.info(f"Code interpreter {sandbox.id} created successfully")
 
-            return cls(sandbox, code_execution_service)
+            return interpreter
         except Exception as e:
             if isinstance(e, SandboxException):
                 raise

code_interpreter/models/__init__.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

code_interpreter/models/code.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

code_interpreter/models/code_sync.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -27,6 +27,7 @@ class SupportedLanguageSync:
     GO = "go"
     TYPESCRIPT = "typescript"
     BASH = "bash"
+    JAVASCRIPT = "javascript"
 
 
 class CodeContextSync(BaseModel):

code_interpreter/services/__init__.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

code_interpreter/services/code.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -38,10 +38,10 @@ class Codes(Protocol):
     Supported Languages:
 
     - Python: Full Python 3.x support with package management
-    - JavaScript/Node.js: ES6+ with npm package support
+    - JavaScript: ES6+ with npm package support
+    - TypeScript
+    - Go
     - Bash: Shell scripting with full system access
-    - Java: Compilation and execution with classpath management
-    - Kotlin: Script and compiled Kotlin execution
 
     Key Features:
 
@@ -212,3 +212,17 @@ class Codes(Protocol):
             SandboxException: If interruption fails
         """
         ...
+
+    async def ping(self) -> bool:
+        """
+        Check if the code execution service (execd) is alive.
+
+        The ping targets the execd daemon endpoint used by this service
+        (``GET /ping``). It does not verify that a specific language runtime
+        is ready, only that the daemon serving code execution requests is
+        responsive.
+
+        Returns:
+            True if the code execution service is responsive, False otherwise
+        """
+        ...

code_interpreter/sync/__init__.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.

code_interpreter/sync/adapters/__init__.py

@@ -1,5 +1,5 @@
 #
-# Copyright 2025 Alibaba Group Holding Ltd.
+# Copyright 2025 The OpenSandbox Authors
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.