opensandbox-code-interpreter 0.1.0__py3-none-any.whl

code_interpreter/code_interpreter.py

@@ -0,0 +1,343 @@
+#
+# Copyright 2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""
+Code Interpreter SDK providing secure, isolated code execution capabilities.
+
+This module provides the main CodeInterpreter class that extends basic Sandbox
+functionality with specialized code execution features, including multi-language
+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
+from code_interpreter.services.code import Codes
+
+logger = logging.getLogger(__name__)
+
+
+class CodeInterpreter:
+    """
+    Code Interpreter SDK providing secure, isolated code execution capabilities.
+
+    This class extends the basic Sandbox functionality with specialized code execution features,
+    including multi-language support, session management, and variable persistence.
+
+    Key Features:
+
+    - Multi-language Code Execution: Support for Python, JavaScript, Bash, Java, Kotlin
+    - 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
+    - Variable Inspection: Access to execution variables and state
+
+    Usage Example:
+
+    ```python
+    # First create a sandbox instance
+
+    sandbox = await Sandbox.create(
+        "python:3.11",
+        resource={"cpu": "1", "memory": "2Gi"}
+    )
+
+    # Then create a code interpreter wrapping the sandbox
+    interpreter = await CodeInterpreter.create(sandbox=sandbox)
+
+    # Execute code with context
+    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
+
+    # Access underlying sandbox for file operations
+    await interpreter.sandbox.files.write_files([
+        WriteEntry(path="data.txt", data="Hello")
+    ])
+    file_result = await interpreter.codes.run(
+        "with open('data.txt') as f: print(f.read())",
+        context=context,
+    )
+
+    # Always clean up resources
+    await interpreter.kill()
+    await interpreter.sandbox.close()
+    ```
+    """
+
+    def __init__(self, sandbox: Sandbox, code_service: Codes) -> None:
+        """
+        Initialize CodeInterpreter with sandbox and code service.
+
+        Note: This constructor is for internal use. Use CodeInterpreter.create() instead.
+
+        Args:
+            sandbox: Underlying sandbox instance
+            code_service: Code execution implementation
+        """
+        self._sandbox = sandbox
+        self._code_service = code_service
+
+    @property
+    def sandbox(self) -> Sandbox:
+        """
+        Provides access to the underlying sandbox instance.
+
+        Returns:
+            The underlying sandbox instance
+        """
+        return self._sandbox
+
+    @property
+    def id(self) -> UUID:
+        """
+        Gets the unique identifier of this code interpreter (same as underlying sandbox ID).
+
+        Returns:
+            UUID of the code interpreter/sandbox
+        """
+        return self._sandbox.id
+
+    @property
+    def files(self):
+        """
+        Provides access to file system operations within the sandbox.
+
+        Allows writing, reading, listing, and deleting files and directories.
+
+        Returns:
+            Service for filesystem manipulation
+        """
+        return self._sandbox.files
+
+    @property
+    def commands(self):
+        """
+        Provides access to command execution operations.
+
+        Allows running shell commands, capturing output, and managing processes.
+
+        Returns:
+            Service for command execution
+        """
+        return self._sandbox.commands
+
+    @property
+    def metrics(self):
+        """
+        Provides access to sandbox metrics and monitoring.
+
+        Allows retrieving resource usage statistics (CPU, memory) and other performance metrics.
+
+        Returns:
+            Service for metrics retrieval
+        """
+        return self._sandbox.metrics
+
+    @property
+    def codes(self) -> Codes:
+        """
+        Provides access to code execution operations.
+
+        This service enables:
+        - Multi-language code execution (Python, JavaScript, Bash, etc.)
+        - Execution context management with persistent variables
+        - Real-time output streaming and interruption capabilities
+
+        Returns:
+            Service for advanced code execution with session support
+        """
+        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":
+        """
+        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.
+
+        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)
+        - CodeInterpreter adds code execution capabilities on top
+
+        Args:
+            sandbox: Existing sandbox instance to wrap with code execution capabilities
+
+        Returns:
+            CodeInterpreter instance wrapping the sandbox
+
+        Raises:
+            InvalidArgumentException: If sandbox is not provided
+            SandboxException: If creation fails
+            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)
+
+        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)
+
+            logger.info("Code interpreter %s created successfully", sandbox.id)
+
+            return cls(sandbox, code_execution_service)
+        except Exception as e:
+            if isinstance(e, SandboxException):
+                raise
+            raise SandboxInternalException(
+                f"Failed to create code interpreter: {e}", cause=e
+            ) from e

code_interpreter/models/__init__.py

@@ -0,0 +1,28 @@
+#
+# Copyright 2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""
+Data models for code execution and interpretation.
+"""
+
+from code_interpreter.models.code import (
+    CodeContext,
+    SupportedLanguage,
+)
+
+__all__ = [
+    "CodeContext",
+    "SupportedLanguage",
+]

code_interpreter/models/code.py

@@ -0,0 +1,67 @@
+#
+# Copyright 2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""
+Code execution models.
+
+Models for code contexts, execution requests, and language support.
+"""
+
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class SupportedLanguage:
+    """
+    Supported programming languages for code execution.
+
+    This class defines the languages that are officially supported by the code interpreter.
+    When adding new languages, ensure corresponding execution environments are available.
+    """
+    PYTHON = "python"
+    JAVA = "java"
+    GO = "go"
+    TYPESCRIPT = "typescript"
+    BASH = "bash"
+
+
+class CodeContext(BaseModel):
+    """
+    Represents an execution context for code interpretation.
+
+    A CodeContext maintains the execution environment for a specific programming
+    language, including the working directory, language configuration, and
+    persistent state across multiple code executions.
+
+    Context Lifecycle:
+
+    1. Creation: Context is created with language and working directory
+    2. Execution: Code runs within this context, building up state
+    3. Persistence: Variables, imports, and functions persist between executions
+    4. Cleanup: Context can be explicitly destroyed or garbage collected
+    """
+
+    id: str | None = Field(default=None, description="Unique identifier for this execution context")
+    language: str = Field(description="Programming language for this context (e.g., 'python', 'javascript')")
+
+    @field_validator('language')
+    @classmethod
+    def language_must_not_be_empty(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("Language cannot be blank")
+        return v
+
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)

code_interpreter/models/code_sync.py

@@ -0,0 +1,41 @@
+#
+# Copyright 2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""
+Synchronous code execution models for Code Interpreter SDK.
+"""
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class SupportedLanguageSync:
+    # kept for symmetry; values match SupportedLanguage
+    PYTHON = "python"
+    JAVA = "java"
+    GO = "go"
+    TYPESCRIPT = "typescript"
+    BASH = "bash"
+
+
+class CodeContextSync(BaseModel):
+    id: str | None = Field(default=None)
+    language: str = Field(description="Programming language for this context")
+
+    @field_validator("language")
+    @classmethod
+    def language_must_not_be_empty(cls, v: str) -> str:
+        if not v.strip():
+            raise ValueError("Language cannot be blank")
+        return v

code_interpreter/services/__init__.py

@@ -0,0 +1,24 @@
+#
+# Copyright 2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""
+Services for code execution and interpretation.
+"""
+
+from code_interpreter.services.code import Codes
+
+__all__ = [
+    "Codes",
+]

code_interpreter/services/code.py

@@ -0,0 +1,149 @@
+#
+# Copyright 2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+"""
+Code execution service interface.
+
+Defines the contract for multi-language code interpretation with context management,
+session persistence, and real-time execution capabilities.
+"""
+
+from typing import Protocol
+
+from opensandbox.models.execd import Execution, ExecutionHandlers
+
+from code_interpreter.models.code import CodeContext
+
+
+class Codes(Protocol):
+    """
+    Code execution service for multi-language code interpretation.
+
+    This service provides advanced code execution capabilities with context management,
+    session persistence, and multi-language support. It extends basic command execution
+    with interpreter-specific features like variable inspection and execution history.
+
+    Supported Languages:
+
+    - Python: Full Python 3.x support with package management
+    - JavaScript/Node.js: ES6+ with npm package support
+    - Bash: Shell scripting with full system access
+    - Java: Compilation and execution with classpath management
+    - Kotlin: Script and compiled Kotlin execution
+
+    Key Features:
+
+    - Execution Contexts: Isolated environments with persistent state
+    - Variable Persistence: Variables and imports persist across executions
+    - Real-time Interruption: Stop long-running code execution safely
+    - Output Streaming: Real-time stdout/stderr with proper buffering
+    - Error Handling: Language-specific error parsing and reporting
+
+    Usage Example:
+
+    ```python
+    # Create execution context
+    context = await code_service.create_context(SupportedLanguage.PYTHON)
+
+    # Execute code with persistent state
+    result1 = await code_service.run(
+        "import numpy as np; x = 42",
+        context=context,
+    )
+
+    result2 = await code_service.run(
+        "print(f'Value: {x}, NumPy version: {np.__version__}')",
+        context=context,
+    )
+    # Variables 'x' and 'np' persist between executions
+    ```
+    """
+
+    async def create_context(self, language: str) -> CodeContext:
+        """
+        Creates a new execution context for code interpretation.
+
+        An execution context maintains the state of variables, imports, and working
+        directory across multiple code executions. This allows for interactive
+        programming sessions where subsequent code can reference previously
+        defined variables and functions.
+
+        Args:
+            language: The programming language for this context (e.g., "python", "javascript")
+
+        Returns:
+            A new CodeContext with the specified configuration
+
+        Raises:
+            SandboxException: If the language is not supported or context creation fails
+        """
+        ...
+
+    async def run(
+        self,
+        code: str,
+        *,
+        context: CodeContext | None = None,
+        handlers: ExecutionHandlers | None = None,
+    ) -> Execution:
+        """
+        Executes code within the specified context.
+
+        This method runs the provided code string in the language interpreter,
+        capturing all output, errors, and execution metadata. The execution
+        happens within the context's environment, preserving variable state
+        and working directory.
+
+        Execution Behavior:
+
+        - Asynchronous: Non-blocking execution with proper async handling
+        - Stateful: Variables and imports persist in the context
+        - Streaming: Output is captured in real-time as it's produced
+        - Interruptible: Can be stopped using interrupt() method
+
+        Args:
+            code: Source code to execute.
+            context: Execution context (language + optional id). If None, a temporary Python context is used.
+            handlers: Optional streaming handlers for stdout/stderr/events.
+
+        Returns:
+            Execution with stdout, stderr, exit code, and execution metadata
+
+        Raises:
+            SandboxException: If execution fails or times out
+        """
+        ...
+
+    async def interrupt(self, execution_id: str) -> None:
+        """
+        Interrupts a currently running code execution.
+
+        This method safely terminates a running code execution, cleaning up
+        resources and ensuring the interpreter remains in a consistent state.
+        The interruption is cooperative and may take some time to complete.
+
+        Interruption Behavior:
+
+        - Safe: Preserves interpreter state and doesn't corrupt the context
+        - Cooperative: Respects language-specific interruption mechanisms
+        - Timeout: Will force-kill after a reasonable timeout if needed
+
+        Args:
+            execution_id: The unique identifier of the execution to interrupt
+
+        Raises:
+            SandboxException: If interruption fails
+        """
+        ...

code_interpreter/sync/__init__.py

@@ -0,0 +1,18 @@
+#
+# Copyright 2025 Alibaba Group Holding Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+from code_interpreter.sync.code_interpreter import CodeInterpreterSync
+
+__all__ = ["CodeInterpreterSync"]