opensandbox-code-interpreter 0.1.0__tar.gz → 0.1.2__tar.gz

{opensandbox_code_interpreter-0.1.0 → opensandbox_code_interpreter-0.1.2}/.gitignore

@@ -133,6 +133,8 @@ dist
 # Gatsby files
 .cache/
 public
+!docs/public/
+!docs/public/CNAME
 
 # Serverless directories
 .serverless/
@@ -222,6 +224,9 @@ secrets/
 
 # Generated API documentation
 docs/generated/
+docs/.vitepress/generated/
+docs/.vitepress/dist/
+docs/.vitepress/cache/
 apidocs/
 
 # Test results
@@ -263,3 +268,9 @@ nbdist/
 # Generated files
 generated/
 **/generated/**
+
+# gVisor runtime binaries (downloaded dynamically)
+kubernetes/test/kind/gvisor/runsc
+kubernetes/test/kind/gvisor/containerd-shim-runsc-v1
+bin/
+obj/

{opensandbox_code_interpreter-0.1.0 → opensandbox_code_interpreter-0.1.2}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: opensandbox-code-interpreter
-Version: 0.1.0
+Version: 0.1.2
 Summary: OpenSandbox Code Interpreter Python SDK - Advanced code execution with persistent contexts
-Project-URL: Homepage, https://github.com/alibaba/OpenSandbox
+Project-URL: Homepage, https://open-sandbox.ai
 Project-URL: Repository, https://github.com/alibaba/OpenSandbox
-Project-URL: Documentation, https://docs.opensandbox.io
+Project-URL: Documentation, https://open-sandbox.ai
 Project-URL: Issues, https://github.com/alibaba/OpenSandbox/issues
 Author-email: OpenSandbox Team <ninan.nn@alibaba-inc.com>
 License:                                  Apache License
@@ -223,11 +223,11 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
-Requires-Dist: opensandbox<0.2.0,>=0.1.0.dev0
-Requires-Dist: pydantic<3.0,>=2.0.0
+Requires-Dist: opensandbox<0.2.0,>=0.1.6
+Requires-Dist: pydantic<3.0,>=2.4.2
 Description-Content-Type: text/markdown
 
-# Alibaba Code Interpreter SDK for Python
+# OpenSandbox Code Interpreter SDK for Python
 
 English | [中文](README_zh.md)
 
@@ -274,14 +274,14 @@ from opensandbox.config import ConnectionConfig
 async def main() -> None:
     # 1. Configure connection
     config = ConnectionConfig(
-        domain="api.opensandbox.dev",
+        domain="api.opensandbox.io",
         api_key="your-api-key",
         request_timeout=timedelta(seconds=60),
     )
 
     # 2. Create a Sandbox with the code-interpreter image + runtime versions
     sandbox = await Sandbox.create(
-        "opensandbox/code-interpreter:latest",
+        "opensandbox/code-interpreter:v1.0.2",
         connection_config=config,
         entrypoint=["/opt/opensandbox/code-interpreter.sh"],
         env={
@@ -306,12 +306,16 @@ async def main() -> None:
             context=context,
         )
 
+        # Alternatively, you can pass a language directly (recommended: SupportedLanguage.*).
+        # This uses the default context for that language (state can persist across runs).
+        # result = await interpreter.codes.run("print('hi')", language=SupportedLanguage.PYTHON)
+
         # 7. Print output
         if result.result:
             print(result.result[0].text)
 
         # 8. Cleanup remote instance (optional but recommended)
-        await interpreter.kill()
+        await sandbox.kill()
 
 
 if __name__ == "__main__":
@@ -331,14 +335,14 @@ from opensandbox import SandboxSync
 from opensandbox.config import ConnectionConfigSync
 
 config = ConnectionConfigSync(
-    domain="api.opensandbox.dev",
+    domain="api.opensandbox.io",
     api_key="your-api-key",
     request_timeout=timedelta(seconds=60),
     transport=httpx.HTTPTransport(limits=httpx.Limits(max_connections=20)),
 )
 
 sandbox = SandboxSync.create(
-    "opensandbox/code-interpreter:latest",
+    "opensandbox/code-interpreter:v1.0.2",
     connection_config=config,
     entrypoint=["/opt/opensandbox/code-interpreter.sh"],
     env={"PYTHON_VERSION": "3.11"},
@@ -348,7 +352,15 @@ with sandbox:
     result = interpreter.codes.run("result = 2 + 2\nresult")
     if result.result:
         print(result.result[0].text)
-    interpreter.kill()
+    sandbox.kill()
+```
+
+### Installing Python packages at runtime
+
+You can install packages directly via `sandbox.commands.run(...)`:
+
+```python
+execution = await sandbox.commands.run("pip install pandas numpy")
 ```
 
 ## Runtime Configuration
@@ -372,6 +384,32 @@ creating the `Sandbox`.
 
 ## Usage Examples
 
+### 0. Run with `language` (default language context)
+
+You can pass `language` directly (recommended: `SupportedLanguage.*`) and skip `create_context`.
+When `context.id` is omitted, **execd will create/reuse a default session for that language**, so
+state can persist across runs:
+
+```python
+from code_interpreter import SupportedLanguage
+
+execution = await interpreter.codes.run(
+    "result = 2 + 2\nresult",
+    language=SupportedLanguage.PYTHON,
+)
+assert execution.result and execution.result[0].text == "4"
+```
+
+State persistence example (default Python context):
+
+```python
+from code_interpreter import SupportedLanguage
+
+await interpreter.codes.run("x = 42", language=SupportedLanguage.PYTHON)
+execution = await interpreter.codes.run("result = x\nresult", language=SupportedLanguage.PYTHON)
+assert execution.result and execution.result[0].text == "42"
+```
+
 ### 1. Java Code Execution
 
 ```python

{opensandbox_code_interpreter-0.1.0 → opensandbox_code_interpreter-0.1.2}/README.md

@@ -1,4 +1,4 @@
-# Alibaba Code Interpreter SDK for Python
+# OpenSandbox Code Interpreter SDK for Python
 
 English | [中文](README_zh.md)
 
@@ -45,14 +45,14 @@ from opensandbox.config import ConnectionConfig
 async def main() -> None:
     # 1. Configure connection
     config = ConnectionConfig(
-        domain="api.opensandbox.dev",
+        domain="api.opensandbox.io",
         api_key="your-api-key",
         request_timeout=timedelta(seconds=60),
     )
 
     # 2. Create a Sandbox with the code-interpreter image + runtime versions
     sandbox = await Sandbox.create(
-        "opensandbox/code-interpreter:latest",
+        "opensandbox/code-interpreter:v1.0.2",
         connection_config=config,
         entrypoint=["/opt/opensandbox/code-interpreter.sh"],
         env={
@@ -77,12 +77,16 @@ async def main() -> None:
             context=context,
         )
 
+        # Alternatively, you can pass a language directly (recommended: SupportedLanguage.*).
+        # This uses the default context for that language (state can persist across runs).
+        # result = await interpreter.codes.run("print('hi')", language=SupportedLanguage.PYTHON)
+
         # 7. Print output
         if result.result:
             print(result.result[0].text)
 
         # 8. Cleanup remote instance (optional but recommended)
-        await interpreter.kill()
+        await sandbox.kill()
 
 
 if __name__ == "__main__":
@@ -102,14 +106,14 @@ from opensandbox import SandboxSync
 from opensandbox.config import ConnectionConfigSync
 
 config = ConnectionConfigSync(
-    domain="api.opensandbox.dev",
+    domain="api.opensandbox.io",
     api_key="your-api-key",
     request_timeout=timedelta(seconds=60),
     transport=httpx.HTTPTransport(limits=httpx.Limits(max_connections=20)),
 )
 
 sandbox = SandboxSync.create(
-    "opensandbox/code-interpreter:latest",
+    "opensandbox/code-interpreter:v1.0.2",
     connection_config=config,
     entrypoint=["/opt/opensandbox/code-interpreter.sh"],
     env={"PYTHON_VERSION": "3.11"},
@@ -119,7 +123,15 @@ with sandbox:
     result = interpreter.codes.run("result = 2 + 2\nresult")
     if result.result:
         print(result.result[0].text)
-    interpreter.kill()
+    sandbox.kill()
+```
+
+### Installing Python packages at runtime
+
+You can install packages directly via `sandbox.commands.run(...)`:
+
+```python
+execution = await sandbox.commands.run("pip install pandas numpy")
 ```
 
 ## Runtime Configuration
@@ -143,6 +155,32 @@ creating the `Sandbox`.
 
 ## Usage Examples
 
+### 0. Run with `language` (default language context)
+
+You can pass `language` directly (recommended: `SupportedLanguage.*`) and skip `create_context`.
+When `context.id` is omitted, **execd will create/reuse a default session for that language**, so
+state can persist across runs:
+
+```python
+from code_interpreter import SupportedLanguage
+
+execution = await interpreter.codes.run(
+    "result = 2 + 2\nresult",
+    language=SupportedLanguage.PYTHON,
+)
+assert execution.result and execution.result[0].text == "4"
+```
+
+State persistence example (default Python context):
+
+```python
+from code_interpreter import SupportedLanguage
+
+await interpreter.codes.run("x = 42", language=SupportedLanguage.PYTHON)
+execution = await interpreter.codes.run("result = x\nresult", language=SupportedLanguage.PYTHON)
+assert execution.result and execution.result[0].text == "42"
+```
+
 ### 1. Java Code Execution
 
 ```python

{opensandbox_code_interpreter-0.1.0 → opensandbox_code_interpreter-0.1.2}/pyproject.toml

@@ -42,14 +42,14 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "pydantic>=2.0.0,<3.0",
-    "opensandbox>=0.1.0.dev0,<0.2.0",
+    "pydantic>=2.4.2,<3.0",
+    "opensandbox>=0.1.6,<0.2.0",
 ]
 
 [project.urls]
-Homepage = "https://github.com/alibaba/OpenSandbox"
+Homepage = "https://open-sandbox.ai"
 Repository = "https://github.com/alibaba/OpenSandbox"
-Documentation = "https://docs.opensandbox.io"
+Documentation = "https://open-sandbox.ai"
 Issues = "https://github.com/alibaba/OpenSandbox/issues"
 
 [tool.hatch.version]
@@ -105,17 +105,24 @@ ignore = [
 "__init__.py" = ["F401"]
 
 [tool.pyright]
-typeCheckingMode = "strict"
+typeCheckingMode = "standard"
 pythonVersion = "3.10"
+pythonPlatform = "All"
+
 include = ["src"]
-venvPath = "."
-venv = ".venv"
+
 exclude = [
     "**/node_modules",
     "**/__pycache__",
-    "**/.*",
+    "src/opensandbox/api/**",
 ]
 
+venvPath = "."
+venv = ".venv"
+
+reportMissingImports = true
+reportMissingTypeStubs = false
+
 [tool.pytest.ini_options]
 minversion = "6.0"
 addopts = "-ra -q --strict-markers --strict-config"

{opensandbox_code_interpreter-0.1.0 → opensandbox_code_interpreter-0.1.2}/src/code_interpreter/__init__.py

@@ -21,6 +21,9 @@ of the OpenSandbox infrastructure. It supports multiple programming languages,
 session management, and variable persistence across executions.
 """
 
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
 from code_interpreter.code_interpreter import CodeInterpreter
 from code_interpreter.models.code import (
     CodeContext,
@@ -36,9 +39,6 @@ __all__ = [
 ]
 
 try:
-    from importlib.metadata import PackageNotFoundError
-    from importlib.metadata import version as _pkg_version
-
     __version__ = _pkg_version("opensandbox-code-interpreter")
 except PackageNotFoundError:  # pragma: no cover
     # Fallback for editable/uninstalled source checkouts.

{opensandbox_code_interpreter-0.1.0 → opensandbox_code_interpreter-0.1.2}/src/code_interpreter/adapters/code_adapter.py

@@ -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,
 )
@@ -49,6 +51,22 @@ 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.
@@ -88,6 +106,7 @@ class CodesAdapter(Codes):
         headers = {
             "User-Agent": self.connection_config.user_agent,
             **self.connection_config.headers,
+            **self.execd_endpoint.headers,
         }
 
         # Execd API does not require authentication
@@ -167,10 +186,76 @@ class CodesAdapter(Codes):
             logger.error("Failed to create context", exc_info=e)
             raise ExceptionConverter.to_sandbox_exception(e) from e
 
+    async def get_context(self, context_id: str) -> CodeContext:
+        try:
+            from opensandbox.api.execd.api.code_interpreting import get_context
+            from opensandbox.api.execd.models.code_context import (
+                CodeContext as ApiCodeContext,
+            )
+
+            client = await self._get_client()
+            response_obj = await get_context.asyncio_detailed(
+                client=client,
+                context_id=context_id,
+            )
+            handle_api_error(response_obj, "Get code context")
+            parsed = require_parsed(response_obj, ApiCodeContext, "Get code context")
+            return CodeExecutionConverter.from_api_code_context(parsed)
+        except Exception as e:
+            logger.error("Failed to get context", exc_info=e)
+            raise ExceptionConverter.to_sandbox_exception(e) from e
+
+    async def list_contexts(self, language: str) -> list[CodeContext]:
+        try:
+            from opensandbox.api.execd.api.code_interpreting import list_contexts
+
+            client = await self._get_client()
+            response_obj = await list_contexts.asyncio_detailed(
+                client=client,
+                language=language,
+            )
+            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]
+        except Exception as e:
+            logger.error("Failed to list contexts", exc_info=e)
+            raise ExceptionConverter.to_sandbox_exception(e) from e
+
+    async def delete_context(self, context_id: str) -> None:
+        try:
+            from opensandbox.api.execd.api.code_interpreting import delete_context
+
+            client = await self._get_client()
+            response_obj = await delete_context.asyncio_detailed(
+                client=client,
+                context_id=context_id,
+            )
+            handle_api_error(response_obj, "Delete code context")
+        except Exception as e:
+            logger.error("Failed to delete context", exc_info=e)
+            raise ExceptionConverter.to_sandbox_exception(e) from e
+
+    async def delete_contexts(self, language: str) -> None:
+        try:
+            from opensandbox.api.execd.api.code_interpreting import (
+                delete_contexts_by_language,
+            )
+
+            client = await self._get_client()
+            response_obj = await delete_contexts_by_language.asyncio_detailed(
+                client=client,
+                language=language,
+            )
+            handle_api_error(response_obj, "Delete code contexts by language")
+        except Exception as e:
+            logger.error("Failed to delete contexts", exc_info=e)
+            raise ExceptionConverter.to_sandbox_exception(e) from e
+
     async def run(
         self,
         code: str,
         *,
+        language: str | None = None,
         context: CodeContext | None = None,
         handlers: ExecutionHandlers | None = None,
     ) -> Execution:
@@ -184,8 +269,15 @@ class CodesAdapter(Codes):
             raise InvalidArgumentException("Code cannot be empty")
 
         try:
-            # Default context: ephemeral python context (server-side behavior)
-            context = context or CodeContext(language=SupportedLanguage.PYTHON)
+            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}'"
+                )
+
+            # Default context: language default context (server-side behavior).
+            # When context.id is omitted, execd will create/reuse a default session per language.
+            if context is None:
+                context = CodeContext(language=language or SupportedLanguage.PYTHON)
             api_request = CodeExecutionConverter.to_api_run_code_request(code, context)
 
             # Prepare URL
@@ -214,6 +306,7 @@ class CodesAdapter(Codes):
                     raise SandboxApiException(
                         message=f"Failed to run code. Status code: {response.status_code}",
                         status_code=response.status_code,
+                        request_id=extract_request_id(response.headers),
                     )
 
                 dispatcher = ExecutionEventDispatcher(execution, handlers)
@@ -228,7 +321,7 @@ 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:

{opensandbox_code_interpreter-0.1.0 → opensandbox_code_interpreter-0.1.2}/src/code_interpreter/adapters/converter/code_execution_converter.py

@@ -82,9 +82,9 @@ class CodeExecutionConverter:
         Returns:
             Domain model code context
         """
-        from opensandbox.api.execd.types import UNSET
+        from opensandbox.api.execd.types import Unset
 
-        context_id = api_context.id if api_context.id is not UNSET else None
+        context_id = None if isinstance(api_context.id, Unset) else api_context.id
 
         return CodeContext(
             id=context_id,

{opensandbox_code_interpreter-0.1.0 → opensandbox_code_interpreter-0.1.2}/src/code_interpreter/code_interpreter.py

@@ -22,19 +22,12 @@ support, session management, and variable persistence.
 """
 
 import logging
-from datetime import datetime, timedelta, timezone
-from uuid import UUID
 
 from opensandbox.exceptions import (
     InvalidArgumentException,
     SandboxException,
     SandboxInternalException,
 )
-from opensandbox.models.sandboxes import (
-    SandboxEndpoint,
-    SandboxInfo,
-    SandboxMetrics,
-)
 from opensandbox.sandbox import Sandbox
 
 from code_interpreter.adapters.factory import AdapterFactory
@@ -87,8 +80,8 @@ class CodeInterpreter:
     )
 
     # Always clean up resources
-    await interpreter.kill()
-    await interpreter.sandbox.close()
+    await sandbox.kill()
+    await sandbox.close()
     ```
     """
 
@@ -116,12 +109,12 @@ class CodeInterpreter:
         return self._sandbox
 
     @property
-    def id(self) -> UUID:
+    def id(self) -> str:
         """
         Gets the unique identifier of this code interpreter (same as underlying sandbox ID).
 
         Returns:
-            UUID of the code interpreter/sandbox
+            ID of the code interpreter/sandbox
         """
         return self._sandbox.id
 
@@ -176,125 +169,6 @@ class CodeInterpreter:
         """
         return self._code_service
 
-    async def get_endpoint(self, port: int) -> SandboxEndpoint:
-        """
-        Gets a specific network endpoint for the underlying sandbox.
-
-        This allows access to specific ports exposed by the sandbox, which can be
-        useful for connecting to additional services or debugging interfaces.
-
-        Args:
-            port: The port number to get the endpoint for
-
-        Returns:
-            Endpoint information including host, port, and connection details
-
-        Raises:
-            SandboxException: If endpoint cannot be retrieved
-        """
-        return await self._sandbox.get_endpoint(port)
-
-    async def get_info(self) -> SandboxInfo:
-        """
-        Gets the current status of this sandbox.
-
-        Returns:
-            Current sandbox status including state and metadata
-
-        Raises:
-            SandboxException: If status cannot be retrieved
-        """
-        return await self._sandbox.get_info()
-
-    async def get_metrics(self) -> SandboxMetrics:
-        """
-        Gets the current resource usage metrics for the underlying sandbox.
-
-        Provides real-time information about CPU usage, memory consumption,
-        disk I/O, and other performance metrics.
-
-        Returns:
-            Current sandbox metrics including CPU, memory, and I/O statistics
-
-        Raises:
-            SandboxException: If metrics cannot be retrieved
-        """
-        return await self._sandbox.get_metrics()
-
-    async def renew(self, timeout: timedelta | int) -> None:
-        """
-        Renew the sandbox expiration time to delay automatic termination.
-
-        The new expiration time will be set to the current time plus the provided duration.
-
-        Args:
-            timeout: Duration to add to the current time to set the new expiration.
-                    Can be timedelta or seconds as int.
-
-        Raises:
-            SandboxException: If the operation fails
-        """
-        if isinstance(timeout, int):
-            timeout = timedelta(seconds=timeout)
-
-        logger.info(
-            "Renew code interpreter %s timeout, estimated expiration to %s",
-            self.id,
-            datetime.now(timezone.utc) + timeout,
-        )
-        await self._sandbox.renew(timeout)
-
-    async def pause(self) -> None:
-        """
-        Pauses the sandbox while preserving its state.
-
-        The sandbox will transition to PAUSED state and can be resumed later.
-        All running processes will be suspended.
-
-        Raises:
-            SandboxException: If pause operation fails
-        """
-        logger.info("Pausing code interpreter: %s", self.id)
-        await self._sandbox.pause()
-
-    async def resume(self) -> None:
-        """
-        Resumes a previously paused code interpreter.
-
-        The sandbox will transition from PAUSED to RUNNING state and all
-        suspended processes will be resumed.
-
-        Raises:
-            SandboxException: If resume operation fails
-        """
-        logger.info("Resuming code interpreter: %s", self.id)
-        await self._sandbox.resume()
-
-    async def kill(self) -> None:
-        """
-        This method sends a termination signal to the remote sandbox instance, causing it to stop immediately.
-        This is an irreversible operation.
-
-        Note: This method does NOT close the local `Sandbox` object resources (like connection pools).
-        You should call `close()` or use async context manager to clean up local resources.
-
-        Raises:
-            SandboxException: If termination fails
-        """
-        logger.info("Killing code interpreter: %s", self.id)
-        await self._sandbox.kill()
-
-    async def is_healthy(self) -> bool:
-        """
-        Checks if the code interpreter and its underlying sandbox are healthy and responsive.
-
-        This performs health checks on both the sandbox infrastructure and code execution services.
-
-        Returns:
-            True if both sandbox and code execution services are healthy, False otherwise
-        """
-        return await self._sandbox.is_healthy()
-
     @classmethod
     async def create(cls, sandbox: Sandbox) -> "CodeInterpreter":
         """

{opensandbox_code_interpreter-0.1.0 → opensandbox_code_interpreter-0.1.2}/src/code_interpreter/models/code.py

@@ -35,6 +35,7 @@ class SupportedLanguage:
     GO = "go"
     TYPESCRIPT = "typescript"
     BASH = "bash"
+    JAVASCRIPT = "javascript"
 
 
 class CodeContext(BaseModel):

{opensandbox_code_interpreter-0.1.0 → opensandbox_code_interpreter-0.1.2}/src/code_interpreter/services/code.py

@@ -20,7 +20,7 @@ Defines the contract for multi-language code interpretation with context managem
 session persistence, and real-time execution capabilities.
 """
 
-from typing import Protocol
+from typing import Protocol, overload
 
 from opensandbox.models.execd import Execution, ExecutionHandlers
 
@@ -91,10 +91,71 @@ class Codes(Protocol):
         """
         ...
 
+    async def get_context(self, context_id: str) -> CodeContext:
+        """
+        Get an existing execution context by id.
+
+        Args:
+            context_id: Context/session id
+
+        Returns:
+            The existing CodeContext
+        """
+        ...
+
+    async def list_contexts(self, language: str) -> list[CodeContext]:
+        """
+        List active contexts under a given language/runtime.
+
+        Args:
+            language: Execution runtime (e.g. "python", "bash")
+
+        Returns:
+            List of contexts
+        """
+        ...
+
+    async def delete_context(self, context_id: str) -> None:
+        """
+        Delete an execution context by id.
+
+        Args:
+            context_id: Context/session id to delete
+        """
+        ...
+
+    async def delete_contexts(self, language: str) -> None:
+        """
+        Delete all execution contexts under a given language/runtime.
+
+        Args:
+            language: Execution runtime (e.g. "python", "bash")
+        """
+        ...
+
+    @overload
+    async def run(
+        self,
+        code: str,
+        *,
+        context: CodeContext,
+        handlers: ExecutionHandlers | None = None,
+    ) -> Execution: ...
+
+    @overload
+    async def run(
+        self,
+        code: str,
+        *,
+        language: str,
+        handlers: ExecutionHandlers | None = None,
+    ) -> Execution: ...
+
     async def run(
         self,
         code: str,
         *,
+        language: str | None = None,
         context: CodeContext | None = None,
         handlers: ExecutionHandlers | None = None,
     ) -> Execution:
@@ -115,7 +176,11 @@ class Codes(Protocol):
 
         Args:
             code: Source code to execute.
-            context: Execution context (language + optional id). If None, a temporary Python context is used.
+            language: Convenience language selector for this run. If provided and ``context`` is None,
+                a **default context for this language** is used (execd will create/reuse a default
+                session when ``context.id`` is omitted). If both ``language`` and ``context`` are
+                provided, they must match.
+            context: Execution context (language + optional id). If None, the default Python context is used.
             handlers: Optional streaming handlers for stdout/stderr/events.
 
         Returns:

{opensandbox_code_interpreter-0.1.0 → opensandbox_code_interpreter-0.1.2}/src/code_interpreter/sync/adapters/code_adapter.py

@@ -19,6 +19,7 @@ Synchronous adapter for code execution service (including SSE streaming).
 
 import json
 import logging
+import time
 
 import httpx
 from opensandbox.adapters.converter.event_node import EventNode
@@ -26,6 +27,7 @@ from opensandbox.adapters.converter.exception_converter import (
     ExceptionConverter,
 )
 from opensandbox.adapters.converter.response_handler import (
+    extract_request_id,
     handle_api_error,
     require_parsed,
 )
@@ -44,6 +46,22 @@ from code_interpreter.sync.services.code import CodesSync
 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 CodesAdapterSync(CodesSync):
     """
     Synchronous adapter for code execution service.
@@ -63,7 +81,9 @@ class CodesAdapterSync(CodesSync):
     RUN_CODE_PATH = "/code"
     CREATE_CONTEXT_PATH = "/code/context"
 
-    def __init__(self, execd_endpoint: SandboxEndpoint, connection_config: ConnectionConfigSync) -> None:
+    def __init__(
+        self, execd_endpoint: SandboxEndpoint, connection_config: ConnectionConfigSync
+    ) -> None:
         """
         Initialize the code service adapter (sync).
 
@@ -78,7 +98,11 @@ class CodesAdapterSync(CodesSync):
         base_url = f"{self.connection_config.protocol}://{self.execd_endpoint.endpoint}"
         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 = {
+            "User-Agent": self.connection_config.user_agent,
+            **self.connection_config.headers,
+            **(self.execd_endpoint.headers or {}),
+        }
 
         self._client = Client(base_url=base_url, timeout=timeout)
         self._httpx_client = httpx.Client(
@@ -89,16 +113,24 @@ class CodesAdapterSync(CodesSync):
         )
         self._client.set_httpx_client(self._httpx_client)
 
-        sse_headers = {**headers, "Accept": "text/event-stream", "Cache-Control": "no-cache"}
+        sse_headers = {
+            **headers,
+            "Accept": "text/event-stream",
+            "Cache-Control": "no-cache",
+        }
         self._sse_client = httpx.Client(
             headers=sse_headers,
-            timeout=httpx.Timeout(connect=timeout_seconds, read=None, write=timeout_seconds, pool=None),
+            timeout=httpx.Timeout(
+                connect=timeout_seconds, read=None, write=timeout_seconds, pool=None
+            ),
             transport=self.connection_config.transport,
         )
 
     def _get_execd_url(self, path: str) -> str:
         """Build URL for execd endpoint."""
-        return f"{self.connection_config.protocol}://{self.execd_endpoint.endpoint}{path}"
+        return (
+            f"{self.connection_config.protocol}://{self.execd_endpoint.endpoint}{path}"
+        )
 
     def create_context(self, language: str) -> CodeContextSync:
         """
@@ -114,7 +146,7 @@ class CodesAdapterSync(CodesSync):
             from opensandbox.api.execd.models.code_context_request import (
                 CodeContextRequest,
             )
-            from opensandbox.api.execd.types import UNSET
+            from opensandbox.api.execd.types import Unset
 
             response_obj = create_code_context.sync_detailed(
                 client=self._client,
@@ -122,16 +154,86 @@ class CodesAdapterSync(CodesSync):
             )
             handle_api_error(response_obj, "Create code context")
             parsed = require_parsed(response_obj, ApiCodeContext, "Create code context")
-            context_id = parsed.id if parsed.id is not UNSET else None
+            context_id = None if isinstance(parsed.id, Unset) else parsed.id
             return CodeContextSync(id=context_id, language=parsed.language)
         except Exception as e:
             logger.error("Failed to create context", exc_info=e)
             raise ExceptionConverter.to_sandbox_exception(e) from e
 
+    def get_context(self, context_id: str) -> CodeContextSync:
+        try:
+            from opensandbox.api.execd.api.code_interpreting import get_context
+            from opensandbox.api.execd.models.code_context import (
+                CodeContext as ApiCodeContext,
+            )
+            from opensandbox.api.execd.types import Unset
+
+            response_obj = get_context.sync_detailed(
+                client=self._client,
+                context_id=context_id,
+            )
+            handle_api_error(response_obj, "Get code context")
+            parsed = require_parsed(response_obj, ApiCodeContext, "Get code context")
+            context_id_val = None if isinstance(parsed.id, Unset) else parsed.id
+            return CodeContextSync(id=context_id_val, language=parsed.language)
+        except Exception as e:
+            logger.error("Failed to get context", exc_info=e)
+            raise ExceptionConverter.to_sandbox_exception(e) from e
+
+    def list_contexts(self, language: str) -> list[CodeContextSync]:
+        try:
+            from opensandbox.api.execd.api.code_interpreting import list_contexts
+            from opensandbox.api.execd.types import UNSET
+
+            response_obj = list_contexts.sync_detailed(
+                client=self._client,
+                language=language,
+            )
+            handle_api_error(response_obj, "List code contexts")
+            parsed_list = require_parsed(response_obj, list, "List code contexts")
+            result: list[CodeContextSync] = []
+            for c in parsed_list:
+                # c is an API CodeContext model
+                context_id_val = c.id if c.id is not UNSET else None
+                result.append(CodeContextSync(id=context_id_val, language=c.language))
+            return result
+        except Exception as e:
+            logger.error("Failed to list contexts", exc_info=e)
+            raise ExceptionConverter.to_sandbox_exception(e) from e
+
+    def delete_context(self, context_id: str) -> None:
+        try:
+            from opensandbox.api.execd.api.code_interpreting import delete_context
+
+            response_obj = delete_context.sync_detailed(
+                client=self._client,
+                context_id=context_id,
+            )
+            handle_api_error(response_obj, "Delete code context")
+        except Exception as e:
+            logger.error("Failed to delete context", exc_info=e)
+            raise ExceptionConverter.to_sandbox_exception(e) from e
+
+    def delete_contexts(self, language: str) -> None:
+        try:
+            from opensandbox.api.execd.api.code_interpreting import (
+                delete_contexts_by_language,
+            )
+
+            response_obj = delete_contexts_by_language.sync_detailed(
+                client=self._client,
+                language=language,
+            )
+            handle_api_error(response_obj, "Delete code contexts by language")
+        except Exception as e:
+            logger.error("Failed to delete contexts", exc_info=e)
+            raise ExceptionConverter.to_sandbox_exception(e) from e
+
     def run(
         self,
         code: str,
         *,
+        language: str | None = None,
         context: CodeContextSync | None = None,
         handlers: ExecutionHandlersSync | None = None,
     ) -> Execution:
@@ -155,7 +257,21 @@ class CodesAdapterSync(CodesSync):
             raise InvalidArgumentException("Code cannot be empty")
 
         try:
-            context = context or CodeContextSync(language=SupportedLanguageSync.PYTHON)
+            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}'"
+                )
+
+            if context is None:
+                # Default context: language default context (server-side behavior).
+                # When context.id is omitted, execd will create/reuse a default session per language.
+                context = CodeContextSync(
+                    language=language or SupportedLanguageSync.PYTHON
+                )
             api_request = {
                 "code": code,
                 "context": {
@@ -174,6 +290,7 @@ class CodesAdapterSync(CodesSync):
                     raise SandboxApiException(
                         message=f"Failed to run code. Status code: {response.status_code}",
                         status_code=response.status_code,
+                        request_id=extract_request_id(response.headers),
                     )
 
                 for line in response.iter_lines():
@@ -183,7 +300,7 @@ class CodesAdapterSync(CodesSync):
                     if data.startswith("data:"):
                         data = data[5:].strip()
                     try:
-                        event_dict = json.loads(data)
+                        event_dict = _normalize_sse_event(json.loads(data))
                         event_node = EventNode(**event_dict)
                         dispatcher.dispatch(event_node)
                     except json.JSONDecodeError:
@@ -208,7 +325,9 @@ class CodesAdapterSync(CodesSync):
         try:
             from opensandbox.api.execd.api.code_interpreting import interrupt_code
 
-            response_obj = interrupt_code.sync_detailed(client=self._client, id=execution_id)
+            response_obj = interrupt_code.sync_detailed(
+                client=self._client, id=execution_id
+            )
             handle_api_error(response_obj, "Interrupt code execution")
         except Exception as e:
             logger.error("Failed to interrupt code execution", exc_info=e)

{opensandbox_code_interpreter-0.1.0 → opensandbox_code_interpreter-0.1.2}/src/code_interpreter/sync/code_interpreter.py

@@ -18,8 +18,6 @@ Synchronous Code Interpreter SDK.
 """
 
 import logging
-from datetime import datetime, timedelta, timezone
-from uuid import UUID
 
 from opensandbox.constants import DEFAULT_EXECD_PORT
 from opensandbox.exceptions import (
@@ -27,11 +25,6 @@ from opensandbox.exceptions import (
     SandboxException,
     SandboxInternalException,
 )
-from opensandbox.models.sandboxes import (
-    SandboxEndpoint,
-    SandboxInfo,
-    SandboxMetrics,
-)
 from opensandbox.sync.sandbox import SandboxSync
 
 from code_interpreter.sync.adapters.factory import AdapterFactorySync
@@ -54,8 +47,8 @@ class CodeInterpreterSync:
 
     - **Blocking**: Do not call these methods directly from an asyncio event loop thread.
       If you need non-blocking behavior, prefer the async :class:`~code_interpreter.code_interpreter.CodeInterpreter`.
-    - **Lifecycle**: Remote lifecycle is owned by the underlying sandbox. This class delegates
-      pause/resume/kill/renew/metrics to the sandbox.
+    - **Lifecycle**: Remote lifecycle is owned by the underlying sandbox; call methods on
+      ``interpreter.sandbox`` for pause/resume/kill/renew/metrics/info/endpoints.
 
     Usage Example:
 
@@ -99,12 +92,12 @@ class CodeInterpreterSync:
         return self._sandbox
 
     @property
-    def id(self) -> UUID:
+    def id(self) -> str:
         """
         Gets the unique identifier of this code interpreter (same as underlying sandbox ID).
 
         Returns:
-            UUID of the code interpreter/sandbox
+            ID of the code interpreter/sandbox
         """
         return self._sandbox.id
 
@@ -153,107 +146,6 @@ class CodeInterpreterSync:
         """
         return self._code_service
 
-    def get_endpoint(self, port: int) -> SandboxEndpoint:
-        """
-        Gets a specific network endpoint for the underlying sandbox.
-
-        Args:
-            port: The port number to get the endpoint for
-
-        Returns:
-            Endpoint information including host, port, and connection details
-
-        Raises:
-            SandboxException: If endpoint cannot be retrieved
-        """
-        return self._sandbox.get_endpoint(port)
-
-    def get_info(self) -> SandboxInfo:
-        """
-        Gets the current status of this sandbox.
-
-        Returns:
-            Current sandbox status including state and metadata
-
-        Raises:
-            SandboxException: If status cannot be retrieved
-        """
-        return self._sandbox.get_info()
-
-    def get_metrics(self) -> SandboxMetrics:
-        """
-        Gets the current resource usage metrics for the underlying sandbox.
-
-        Returns:
-            Current sandbox metrics including CPU, memory, and I/O statistics
-
-        Raises:
-            SandboxException: If metrics cannot be retrieved
-        """
-        return self._sandbox.get_metrics()
-
-    def renew(self, timeout: timedelta | int) -> None:
-        """
-        Renew the sandbox expiration time to delay automatic termination.
-
-        Args:
-            timeout: Duration to add to the current time to set the new expiration.
-                Can be timedelta or seconds as int.
-
-        Raises:
-            SandboxException: If the operation fails
-        """
-        if isinstance(timeout, int):
-            timeout = timedelta(seconds=timeout)
-        logger.info(
-            "Renew code interpreter %s timeout, estimated expiration to %s",
-            self.id,
-            datetime.now(timezone.utc) + timeout,
-        )
-        self._sandbox.renew(timeout)
-
-    def pause(self) -> None:
-        """
-        Pauses the sandbox while preserving its state.
-
-        Raises:
-            SandboxException: If pause operation fails
-        """
-        logger.info("Pausing code interpreter: %s", self.id)
-        self._sandbox.pause()
-
-    def resume(self) -> None:
-        """
-        Resumes a previously paused sandbox.
-
-        Raises:
-            SandboxException: If resume operation fails
-        """
-        logger.info("Resuming code interpreter: %s", self.id)
-        self._sandbox.resume()
-
-    def kill(self) -> None:
-        """
-        Terminate the remote sandbox instance (irreversible).
-
-        Note: This method does NOT close the local `SandboxSync` object resources (like connection pools).
-        You should call `sandbox().close()` or use the sync context manager on the sandbox to clean up.
-
-        Raises:
-            SandboxException: If termination fails
-        """
-        logger.info("Killing code interpreter: %s", self.id)
-        self._sandbox.kill()
-
-    def is_healthy(self) -> bool:
-        """
-        Checks if the code interpreter and its underlying sandbox are healthy and responsive.
-
-        Returns:
-            True if sandbox is healthy, False otherwise
-        """
-        return self._sandbox.is_healthy()
-
     @classmethod
     def create(cls, sandbox: SandboxSync) -> "CodeInterpreterSync":
         """

{opensandbox_code_interpreter-0.1.0 → opensandbox_code_interpreter-0.1.2}/src/code_interpreter/sync/services/code.py

@@ -22,7 +22,7 @@ session persistence, and real-time execution capabilities (SSE streaming), **in
 This is the sync counterpart of :mod:`code_interpreter.services.code`.
 """
 
-from typing import Protocol
+from typing import Protocol, overload
 
 from opensandbox.models.execd import Execution
 from opensandbox.models.execd_sync import ExecutionHandlersSync
@@ -73,10 +73,45 @@ class CodesSync(Protocol):
         """
         ...
 
+    def get_context(self, context_id: str) -> CodeContextSync:
+        """Get an existing execution context by id (blocking)."""
+        ...
+
+    def list_contexts(self, language: str) -> list[CodeContextSync]:
+        """List active contexts under a given language/runtime (blocking)."""
+        ...
+
+    def delete_context(self, context_id: str) -> None:
+        """Delete an execution context by id (blocking)."""
+        ...
+
+    def delete_contexts(self, language: str) -> None:
+        """Delete all contexts under a language/runtime (blocking)."""
+        ...
+
+    @overload
+    def run(
+        self,
+        code: str,
+        *,
+        context: CodeContextSync,
+        handlers: ExecutionHandlersSync | None = None,
+    ) -> Execution: ...
+
+    @overload
+    def run(
+        self,
+        code: str,
+        *,
+        language: str,
+        handlers: ExecutionHandlersSync | None = None,
+    ) -> Execution: ...
+
     def run(
         self,
         code: str,
         *,
+        language: str | None = None,
         context: CodeContextSync | None = None,
         handlers: ExecutionHandlersSync | None = None,
     ) -> Execution:
@@ -95,7 +130,11 @@ class CodesSync(Protocol):
 
         Args:
             code: Source code to execute.
-            context: Execution context (language + optional id). If None, a temporary Python context is used.
+            language: Convenience language selector for this run. If provided and ``context`` is None,
+                a **default context for this language** is used (execd will create/reuse a default
+                session when ``context.id`` is omitted). If both ``language`` and ``context`` are
+                provided, they must match.
+            context: Execution context (language + optional id). If None, the default Python context is used.
             handlers: Optional streaming handlers for stdout/stderr/events.
 
         Returns: