llm-sandbox 0.1.0__tar.gz

llm_sandbox-0.1.0/LICENSE

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

llm_sandbox-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.1
+Name: llm-sandbox
+Version: 0.1.0
+Summary: Lightweight and portable LLM sandbox runtime (code interpreter) Python library
+Home-page: https://github.com/vndee/llm-sandbox
+License: MIT
+Author: Duy Huynh
+Author-email: vndee.huynh@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: docker (>=7.1.0,<8.0.0)
+Requires-Dist: kubernetes (>=30.1.0,<31.0.0)
+Project-URL: Repository, https://github.com/vndee/llm-sandbox
+Description-Content-Type: text/markdown
+
+## LLM Sandbox
+
+*The easiest way to run large language model (LLM) generated code (code interpreter) in a safe and isolated environment.*
+
+LLM Sandbox is a lightweight and portable sandbox environment designed to run large language model (LLM) generated code in a safe and isolated manner using Docker containers. This project aims to provide an easy-to-use interface for setting up, managing, and executing code in a controlled Docker environment, simplifying the process of running code generated by LLMs.
+
+### Features
+
+- **Easy Setup:** Quickly create sandbox environments with minimal configuration.
+- **Isolation:** Run your code in isolated Docker containers to prevent interference with your host system.
+- **Flexibility:** Support for multiple programming languages.
+- **Portability:** Use predefined Docker images or custom Dockerfiles.
+- **Scalability:** Support Kubernetes and remote Docker host.
+
+### Installation
+
+#### Using Poetry
+
+1. Ensure you have [Poetry](https://python-poetry.org/docs/#installation) installed.
+2. Add the package to your project:
+
+```sh
+poetry add llm-sandbox
+```
+
+#### Using pip
+
+1. Ensure you have [pip](https://pip.pypa.io/en/stable/installation/) installed.
+2. Install the package:
+
+```sh
+pip install llm-sandbox
+```
+
+### Usage
+
+#### Session Lifecycle
+
+The `SandboxSession` class manages the lifecycle of the sandbox environment, including the creation and destruction of Docker containers. Here’s a typical lifecycle:
+
+1. **Initialization:** Create a `SandboxSession` object with the desired configuration.
+2. **Open Session:** Call the `open()` method to build/pull the Docker image and start the Docker container.
+3. **Run Code:** Use the `run()` method to execute code inside the sandbox. Currently, it supports Python, Java, JavaScript, C++, Go, and Ruby. See [examples](examples) for more details.
+4. **Close Session:** Call the `close()` method to stop and remove the Docker container. If the `keep_template` flag is set to `True`, the Docker image will not be removed, and the last container state will be committed to the image.
+
+### Example
+
+Here's a simple example to demonstrate how to use LLM Sandbox:
+
+```python
+from llm_sandbox import SandboxSession
+
+# Create a new sandbox session
+with SandboxSession(image="python:3.9.19-bullseye", keep_template=True, lang="python") as session:
+    result = session.run("print('Hello, World!')")
+    print(result)
+
+# With custom Dockerfile
+with SandboxSession(dockerfile="Dockerfile", keep_template=True, lang="python") as session:
+    result = session.run("print('Hello, World!')")
+    print(result)
+
+# Or default image
+with SandboxSession(lang="python", keep_template=True) as session:
+    result = session.run("print('Hello, World!')")
+    print(result)
+```
+
+
+LLM Sandbox also supports copying files between the host and the sandbox:
+
+```python
+from llm_sandbox import SandboxSession
+
+with SandboxSession(lang="python", keep_template=True) as session:
+    # Copy a file from the host to the sandbox
+    session.copy_to_runtime("test.py", "/sandbox/test.py")
+
+    # Run the copied Python code in the sandbox
+    result = session.run("python /sandbox/test.py")
+    print(result)
+
+    # Copy a file from the sandbox to the host
+    session.copy_from_runtime("/sandbox/output.txt", "output.txt")
+```
+
+For other languages usage, please refer to the [examples](examples/code_runner_docker.py).
+
+You can also use [remote Docker host](https://docs.docker.com/config/daemon/remote-access/) as below:
+
+```python
+import docker
+from llm_sandbox import SandboxSession
+
+tls_config = docker.tls.TLSConfig(
+    client_cert=("path/to/cert.pem", "path/to/key.pem"),
+    ca_cert="path/to/ca.pem",
+    verify=True
+)
+docker_client = docker.DockerClient(base_url="tcp://<your_host>:<port>", tls=tls_config)
+
+with SandboxSession(
+    client=docker_client,
+    mage="python:3.9.19-bullseye",
+    keep_template=True,
+    lang="python",
+) as session:
+    result = session.run("print('Hello, World!')")
+    print(result)
+```
+
+For Kubernetes usage, please refer to the examples. Essentially, you just need to set the use_kubernetes flag to True and provide the Kubernetes client, or leave it as the default for the local context.
+
+### API Reference
+
+#### `SandboxSession`
+
+##### Initialization
+
+```python
+SandboxSession(
+    image: Optional[str] = None,
+    dockerfile: Optional[str] = None,
+    lang: str = SupportedLanguage.PYTHON,
+    keep_template: bool = False,
+    verbose: bool = True
+)
+```
+
+- **`image`**: Docker image to use.
+- **`dockerfile`**: Path to the Dockerfile, if an image is not provided.
+- **`lang`**: Language of the code (default: `SupportedLanguage.PYTHON`).
+- **`keep_template`**: If `True`, the image and container will not be removed after the session ends.
+- **`verbose`**: If `True`, print messages.
+
+##### Methods
+
+- **`open()`**: Start the Docker container.
+- **`close()`**: Stop and remove the Docker container.
+- **`run(code: str, libraries: Optional[List] = None)`**: Execute code inside the sandbox.
+- **`copy_from_runtime(src: str, dest: str)`**: Copy a file from the sandbox to the host.
+- **`copy_to_runtime(src: str, dest: str)`**: Copy a file from the host to the sandbox.
+- **`execute_command(command: str)`**: Execute a command inside the sandbox.
+
+### Contributing
+
+We welcome contributions to improve LLM Sandbox! Since I am a Python developer, I am not familiar with other languages. If you are interested in adding better support for other languages, please feel free to submit a pull request.
+
+Here is a list of things you can do to contribute:
+- [ ] Add Java maven support.
+- [x] Add support for JavaScript.
+- [x] Add support for C++.
+- [x] Add support for Go.
+- [ ] Add support for Ruby.
+- [x] Add remote Docker host support.
+- [x] Add remote Kubernetes cluster support.
+- [ ] Commit the last container state to the image before closing kubernetes session.
+- [ ] Release version 1.0.0.
+
+### License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+

llm_sandbox-0.1.0/README.md

@@ -0,0 +1,162 @@
+## LLM Sandbox
+
+*The easiest way to run large language model (LLM) generated code (code interpreter) in a safe and isolated environment.*
+
+LLM Sandbox is a lightweight and portable sandbox environment designed to run large language model (LLM) generated code in a safe and isolated manner using Docker containers. This project aims to provide an easy-to-use interface for setting up, managing, and executing code in a controlled Docker environment, simplifying the process of running code generated by LLMs.
+
+### Features
+
+- **Easy Setup:** Quickly create sandbox environments with minimal configuration.
+- **Isolation:** Run your code in isolated Docker containers to prevent interference with your host system.
+- **Flexibility:** Support for multiple programming languages.
+- **Portability:** Use predefined Docker images or custom Dockerfiles.
+- **Scalability:** Support Kubernetes and remote Docker host.
+
+### Installation
+
+#### Using Poetry
+
+1. Ensure you have [Poetry](https://python-poetry.org/docs/#installation) installed.
+2. Add the package to your project:
+
+```sh
+poetry add llm-sandbox
+```
+
+#### Using pip
+
+1. Ensure you have [pip](https://pip.pypa.io/en/stable/installation/) installed.
+2. Install the package:
+
+```sh
+pip install llm-sandbox
+```
+
+### Usage
+
+#### Session Lifecycle
+
+The `SandboxSession` class manages the lifecycle of the sandbox environment, including the creation and destruction of Docker containers. Here’s a typical lifecycle:
+
+1. **Initialization:** Create a `SandboxSession` object with the desired configuration.
+2. **Open Session:** Call the `open()` method to build/pull the Docker image and start the Docker container.
+3. **Run Code:** Use the `run()` method to execute code inside the sandbox. Currently, it supports Python, Java, JavaScript, C++, Go, and Ruby. See [examples](examples) for more details.
+4. **Close Session:** Call the `close()` method to stop and remove the Docker container. If the `keep_template` flag is set to `True`, the Docker image will not be removed, and the last container state will be committed to the image.
+
+### Example
+
+Here's a simple example to demonstrate how to use LLM Sandbox:
+
+```python
+from llm_sandbox import SandboxSession
+
+# Create a new sandbox session
+with SandboxSession(image="python:3.9.19-bullseye", keep_template=True, lang="python") as session:
+    result = session.run("print('Hello, World!')")
+    print(result)
+
+# With custom Dockerfile
+with SandboxSession(dockerfile="Dockerfile", keep_template=True, lang="python") as session:
+    result = session.run("print('Hello, World!')")
+    print(result)
+
+# Or default image
+with SandboxSession(lang="python", keep_template=True) as session:
+    result = session.run("print('Hello, World!')")
+    print(result)
+```
+
+
+LLM Sandbox also supports copying files between the host and the sandbox:
+
+```python
+from llm_sandbox import SandboxSession
+
+with SandboxSession(lang="python", keep_template=True) as session:
+    # Copy a file from the host to the sandbox
+    session.copy_to_runtime("test.py", "/sandbox/test.py")
+
+    # Run the copied Python code in the sandbox
+    result = session.run("python /sandbox/test.py")
+    print(result)
+
+    # Copy a file from the sandbox to the host
+    session.copy_from_runtime("/sandbox/output.txt", "output.txt")
+```
+
+For other languages usage, please refer to the [examples](examples/code_runner_docker.py).
+
+You can also use [remote Docker host](https://docs.docker.com/config/daemon/remote-access/) as below:
+
+```python
+import docker
+from llm_sandbox import SandboxSession
+
+tls_config = docker.tls.TLSConfig(
+    client_cert=("path/to/cert.pem", "path/to/key.pem"),
+    ca_cert="path/to/ca.pem",
+    verify=True
+)
+docker_client = docker.DockerClient(base_url="tcp://<your_host>:<port>", tls=tls_config)
+
+with SandboxSession(
+    client=docker_client,
+    mage="python:3.9.19-bullseye",
+    keep_template=True,
+    lang="python",
+) as session:
+    result = session.run("print('Hello, World!')")
+    print(result)
+```
+
+For Kubernetes usage, please refer to the examples. Essentially, you just need to set the use_kubernetes flag to True and provide the Kubernetes client, or leave it as the default for the local context.
+
+### API Reference
+
+#### `SandboxSession`
+
+##### Initialization
+
+```python
+SandboxSession(
+    image: Optional[str] = None,
+    dockerfile: Optional[str] = None,
+    lang: str = SupportedLanguage.PYTHON,
+    keep_template: bool = False,
+    verbose: bool = True
+)
+```
+
+- **`image`**: Docker image to use.
+- **`dockerfile`**: Path to the Dockerfile, if an image is not provided.
+- **`lang`**: Language of the code (default: `SupportedLanguage.PYTHON`).
+- **`keep_template`**: If `True`, the image and container will not be removed after the session ends.
+- **`verbose`**: If `True`, print messages.
+
+##### Methods
+
+- **`open()`**: Start the Docker container.
+- **`close()`**: Stop and remove the Docker container.
+- **`run(code: str, libraries: Optional[List] = None)`**: Execute code inside the sandbox.
+- **`copy_from_runtime(src: str, dest: str)`**: Copy a file from the sandbox to the host.
+- **`copy_to_runtime(src: str, dest: str)`**: Copy a file from the host to the sandbox.
+- **`execute_command(command: str)`**: Execute a command inside the sandbox.
+
+### Contributing
+
+We welcome contributions to improve LLM Sandbox! Since I am a Python developer, I am not familiar with other languages. If you are interested in adding better support for other languages, please feel free to submit a pull request.
+
+Here is a list of things you can do to contribute:
+- [ ] Add Java maven support.
+- [x] Add support for JavaScript.
+- [x] Add support for C++.
+- [x] Add support for Go.
+- [ ] Add support for Ruby.
+- [x] Add remote Docker host support.
+- [x] Add remote Kubernetes cluster support.
+- [ ] Commit the last container state to the image before closing kubernetes session.
+- [ ] Release version 1.0.0.
+
+### License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

llm_sandbox-0.1.0/llm_sandbox/__init__.py

@@ -0,0 +1 @@
+from .session import SandboxSession  # noqa: F401

llm_sandbox-0.1.0/llm_sandbox/base.py

@@ -0,0 +1,61 @@
+from abc import ABC, abstractmethod
+from typing import Optional, List
+
+
+class ConsoleOutput:
+    def __init__(self, text: str):
+        self._text = text
+
+    @property
+    def text(self):
+        return self._text
+
+    def __str__(self):
+        return f"ConsoleOutput(text={self.text})"
+
+
+class KubernetesConsoleOutput(ConsoleOutput):
+    def __init__(self, exit_code: int, text: str):
+        super().__init__(text)
+        self.exit_code = exit_code
+
+    def __str__(self):
+        return f"KubernetesConsoleOutput(text={self.text}, exit_code={self.exit_code})"
+
+
+class Session(ABC):
+    def __init__(self, lang: str, verbose: bool = True, *args, **kwargs):
+        self.lang = lang
+        self.verbose = verbose
+        super().__init__(*args, **kwargs)
+
+    @abstractmethod
+    def open(self):
+        raise NotImplementedError
+
+    @abstractmethod
+    def close(self):
+        raise NotImplementedError
+
+    @abstractmethod
+    def run(self, code: str, libraries: Optional[List] = None) -> ConsoleOutput:
+        raise NotImplementedError
+
+    @abstractmethod
+    def copy_to_runtime(self, src: str, dest: str):
+        raise NotImplementedError
+
+    @abstractmethod
+    def copy_from_runtime(self, src: str, dest: str):
+        raise NotImplementedError
+
+    @abstractmethod
+    def execute_command(self, command: str):
+        raise NotImplementedError
+
+    def __enter__(self):
+        self.open()
+        return self
+
+    def __exit__(self, *args, **kwargs):
+        self.close()

llm_sandbox-0.1.0/llm_sandbox/const.py

@@ -0,0 +1,27 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class SupportedLanguage:
+    PYTHON = "python"
+    JAVA = "java"
+    JAVASCRIPT = "javascript"
+    CPP = "cpp"
+    GO = "go"
+    RUBY = "ruby"
+
+
+@dataclass
+class DefaultImage:
+    PYTHON = "python:3.9.19-bullseye"
+    JAVA = "openjdk:11.0.12-jdk-bullseye"
+    JAVASCRIPT = "node:22-bullseye"
+    CPP = "gcc:11.2.0-bullseye"
+    GO = "golang:1.17.0-bullseye"
+    RUBY = "ruby:3.0.2-bullseye"
+
+
+NotSupportedLibraryInstallation = ["JAVA"]
+SupportedLanguageValues = [
+    v for k, v in SupportedLanguage.__dict__.items() if not k.startswith("__")
+]

llm_sandbox-0.1.0/llm_sandbox/docker.py

@@ -0,0 +1,260 @@
+import io
+import os
+import docker
+import tarfile
+from typing import List, Optional, Union
+
+from docker.models.images import Image
+from docker.models.containers import Container
+from llm_sandbox.utils import (
+    image_exists,
+    get_libraries_installation_command,
+    get_code_file_extension,
+    get_code_execution_command,
+)
+from llm_sandbox.base import Session, ConsoleOutput
+from llm_sandbox.const import (
+    SupportedLanguage,
+    SupportedLanguageValues,
+    DefaultImage,
+    NotSupportedLibraryInstallation,
+)
+
+
+class SandboxDockerSession(Session):
+    def __init__(
+        self,
+        client: Optional[docker.DockerClient] = None,
+        image: Optional[str] = None,
+        dockerfile: Optional[str] = None,
+        lang: str = SupportedLanguage.PYTHON,
+        keep_template: bool = False,
+        verbose: bool = True,
+    ):
+        """
+        Create a new sandbox session
+        :param client: Docker client, if not provided, a new client will be created based on local Docker context
+        :param image: Docker image to use
+        :param dockerfile: Path to the Dockerfile, if image is not provided
+        :param lang: Language of the code
+        :param keep_template: if True, the image and container will not be removed after the session ends
+        :param verbose: if True, print messages
+        """
+        super().__init__(lang, verbose)
+        if image and dockerfile:
+            raise ValueError("Only one of image or dockerfile should be provided")
+
+        if lang not in SupportedLanguageValues:
+            raise ValueError(
+                f"Language {lang} is not supported. Must be one of {SupportedLanguageValues}"
+            )
+
+        if not image and not dockerfile:
+            image = DefaultImage.__dict__[lang.upper()]
+
+        self.lang: str = lang
+        self.client: Optional[docker.DockerClient] = None
+
+        if not client:
+            print("Using local Docker context since client is not provided..")
+            self.client = docker.from_env()
+        else:
+            self.client = client
+
+        self.image: Union[Image, str] = image
+        self.dockerfile: Optional[str] = dockerfile
+        self.container: Optional[Container] = None
+        self.path = None
+        self.keep_template = keep_template
+        self.is_create_template: bool = False
+        self.verbose = verbose
+
+    def open(self):
+        warning_str = (
+            "Since the `keep_template` flag is set to True the docker image will not be removed after the session ends "
+            "and remains for future use."
+        )
+        if self.dockerfile:
+            self.path = os.path.dirname(self.dockerfile)
+            if self.verbose:
+                f_str = f"Building docker image from {self.dockerfile}"
+                f_str = f"{f_str}\n{warning_str}" if self.keep_template else f_str
+                print(f_str)
+
+            self.image, _ = self.client.images.build(
+                path=self.path,
+                dockerfile=os.path.basename(self.dockerfile),
+                tag=f"sandbox-{self.lang.lower()}-{os.path.basename(self.path)}",
+            )
+            self.is_create_template = True
+
+        if isinstance(self.image, str):
+            if not image_exists(self.client, self.image):
+                if self.verbose:
+                    f_str = f"Pulling image {self.image}.."
+                    f_str = f"{f_str}\n{warning_str}" if self.keep_template else f_str
+                    print(f_str)
+
+                self.image = self.client.images.pull(self.image)
+                self.is_create_template = True
+            else:
+                self.image = self.client.images.get(self.image)
+                if self.verbose:
+                    print(f"Using image {self.image.tags[-1]}")
+
+        self.container = self.client.containers.run(self.image, detach=True, tty=True)
+
+    def close(self):
+        if self.container:
+            if isinstance(self.image, Image):
+                self.container.commit(self.image.tags[-1])
+
+            self.container.remove(force=True)
+            self.container = None
+
+        if self.is_create_template and not self.keep_template:
+            # check if the image is used by any other container
+            containers = self.client.containers.list(all=True)
+            image_id = (
+                self.image.id
+                if isinstance(self.image, Image)
+                else self.client.images.get(self.image).id
+            )
+            image_in_use = any(
+                container.image.id == image_id for container in containers
+            )
+
+            if not image_in_use:
+                if isinstance(self.image, str):
+                    self.client.images.remove(self.image)
+                elif isinstance(self.image, Image):
+                    self.image.remove(force=True)
+                else:
+                    raise ValueError("Invalid image type")
+            else:
+                if self.verbose:
+                    print(
+                        f"Image {self.image.tags[-1]} is in use by other containers. Skipping removal.."
+                    )
+
+    def run(self, code: str, libraries: Optional[List] = None) -> ConsoleOutput:
+        if not self.container:
+            raise RuntimeError(
+                "Session is not open. Please call open() method before running code."
+            )
+
+        if libraries:
+            if self.lang.upper() in NotSupportedLibraryInstallation:
+                raise ValueError(
+                    f"Library installation has not been supported for {self.lang} yet!"
+                )
+
+            if self.lang == SupportedLanguage.GO:
+                self.execute_command("mkdir -p /example")
+                self.execute_command("go mod init example", workdir="/example")
+                self.execute_command("go mod tidy", workdir="/example")
+
+                for library in libraries:
+                    command = get_libraries_installation_command(self.lang, library)
+                    _ = self.execute_command(command, workdir="/example")
+            else:
+                for library in libraries:
+                    command = get_libraries_installation_command(self.lang, library)
+                    _ = self.execute_command(command)
+
+        code_file = f"/tmp/code.{get_code_file_extension(self.lang)}"
+        if self.lang == SupportedLanguage.GO:
+            code_dest_file = "/example/code.go"
+        else:
+            code_dest_file = code_file
+
+        with open(code_file, "w") as f:
+            f.write(code)
+
+        self.copy_to_runtime(code_file, code_dest_file)
+
+        output = ConsoleOutput("")
+        commands = get_code_execution_command(self.lang, code_dest_file)
+        for command in commands:
+            if self.lang == SupportedLanguage.GO:
+                output = self.execute_command(command, workdir="/example")
+            else:
+                output = self.execute_command(command)
+
+        return output
+
+    def copy_from_runtime(self, src: str, dest: str):
+        if not self.container:
+            raise RuntimeError(
+                "Session is not open. Please call open() method before copying files."
+            )
+
+        if self.verbose:
+            print(f"Copying {self.container.short_id}:{src} to {dest}..")
+
+        bits, stat = self.container.get_archive(src)
+        if stat["size"] == 0:
+            raise FileNotFoundError(f"File {src} not found in the container")
+
+        tarstream = io.BytesIO(b"".join(bits))
+        with tarfile.open(fileobj=tarstream, mode="r") as tar:
+            tar.extractall(os.path.dirname(dest))
+
+    def copy_to_runtime(self, src: str, dest: str):
+        if not self.container:
+            raise RuntimeError(
+                "Session is not open. Please call open() method before copying files."
+            )
+
+        is_created_dir = False
+        directory = os.path.dirname(dest)
+        if directory and not self.container.exec_run(f"test -d {directory}")[0] == 0:
+            self.container.exec_run(f"mkdir -p {directory}")
+            is_created_dir = True
+
+        if self.verbose:
+            if is_created_dir:
+                print(f"Creating directory {self.container.short_id}:{directory}")
+            print(f"Copying {src} to {self.container.short_id}:{dest}..")
+
+        tarstream = io.BytesIO()
+        with tarfile.open(fileobj=tarstream, mode="w") as tar:
+            tar.add(src, arcname=os.path.basename(src))
+
+        tarstream.seek(0)
+        self.container.put_archive(os.path.dirname(dest), tarstream)
+
+    def execute_command(
+        self, command: Optional[str], workdir: Optional[str] = None
+    ) -> ConsoleOutput:
+        if not command:
+            raise ValueError("Command cannot be empty")
+
+        if not self.container:
+            raise RuntimeError(
+                "Session is not open. Please call open() method before executing commands."
+            )
+
+        if self.verbose:
+            print(f"Executing command: {command}")
+
+        if workdir:
+            exit_code, exec_log = self.container.exec_run(
+                command, stream=True, tty=True, workdir=workdir
+            )
+        else:
+            exit_code, exec_log = self.container.exec_run(
+                command, stream=True, tty=True
+            )
+
+        output = ""
+        if self.verbose:
+            print("Output:", end=" ")
+
+        for chunk in exec_log:
+            chunk_str = chunk.decode("utf-8")
+            output += chunk_str
+            if self.verbose:
+                print(chunk_str, end="")
+
+        return ConsoleOutput(output)

llm_sandbox-0.1.0/llm_sandbox/kubernetes.py

@@ -0,0 +1,284 @@
+import io
+import os
+import time
+import uuid
+import tarfile
+from typing import List, Optional
+
+from kubernetes import client as k8s_client, config
+from kubernetes.stream import stream
+from llm_sandbox.base import Session, ConsoleOutput, KubernetesConsoleOutput
+from llm_sandbox.utils import (
+    get_libraries_installation_command,
+    get_code_file_extension,
+    get_code_execution_command,
+)
+from llm_sandbox.const import SupportedLanguage, SupportedLanguageValues, DefaultImage
+
+
+class SandboxKubernetesSession(Session):
+    def __init__(
+        self,
+        client: Optional[k8s_client.CoreV1Api] = None,
+        image: Optional[str] = None,
+        lang: str = SupportedLanguage.PYTHON,
+        keep_template: bool = False,
+        verbose: bool = True,
+        kube_namespace: str = "default",
+    ):
+        """
+        Create a new sandbox session
+        :param client: Kubernetes client, if not provided, a new client will be created based on local Kubernetes context
+        :param image: Docker image to use
+        :param lang: Language of the code
+        :param keep_template: if True, the image and container will not be removed after the session ends
+        :param verbose: if True, print messages
+        :param kube_namespace: Kubernetes namespace to use, default is 'default'
+        """
+        super().__init__(lang, verbose)
+        if lang not in SupportedLanguageValues:
+            raise ValueError(
+                f"Language {lang} is not supported. Must be one of {SupportedLanguageValues}"
+            )
+
+        if not image:
+            image = DefaultImage.__dict__[lang.upper()]
+
+        if not client:
+            print("Using local Kubernetes context since client is not provided..")
+            config.load_kube_config()
+            self.client = k8s_client.CoreV1Api()
+        else:
+            self.client = client
+
+        self.image = image
+        self.kube_namespace = kube_namespace
+        self.pod_name = f"sandbox-{lang.lower()}-{uuid.uuid4().hex}"
+        self.keep_template = keep_template
+        self.container = None
+
+    def open(self):
+        self._create_kubernetes_pod()
+
+    def _create_kubernetes_pod(self):
+        pod_manifest = {
+            "apiVersion": "v1",
+            "kind": "Pod",
+            "metadata": {
+                "name": self.pod_name,
+                "namespace": self.kube_namespace,
+                "labels": {"app": "sandbox"},
+            },
+            "spec": {
+                "containers": [
+                    {"name": "sandbox-container", "image": self.image, "tty": True}
+                ]
+            },
+        }
+        self.client.create_namespaced_pod(
+            namespace=self.kube_namespace, body=pod_manifest
+        )
+
+        while True:
+            pod = self.client.read_namespaced_pod(
+                name=self.pod_name, namespace=self.kube_namespace
+            )
+            if pod.status.phase == "Running":
+                break
+            time.sleep(1)
+
+        self.container = self.pod_name
+
+    def close(self):
+        self._delete_kubernetes_pod()
+
+    def _delete_kubernetes_pod(self):
+        self.client.delete_namespaced_pod(
+            name=self.pod_name,
+            namespace=self.kube_namespace,
+            body=k8s_client.V1DeleteOptions(),
+        )
+
+    def run(self, code: str, libraries: Optional[List] = None) -> ConsoleOutput:
+        if not self.container:
+            raise RuntimeError(
+                "Session is not open. Please call open() method before running code."
+            )
+
+        if libraries:
+            if self.lang == SupportedLanguage.GO:
+                self.execute_command("mkdir -p /example")
+                self.execute_command("go mod init example", workdir="/example")
+                self.execute_command("go mod tidy", workdir="/example")
+
+                for library in libraries:
+                    install_command = get_libraries_installation_command(
+                        self.lang, library
+                    )
+                    output = self.execute_command(install_command, workdir="/example")
+                    if output.exit_code != 0:
+                        raise RuntimeError(
+                            f"Failed to install library {library}: {output}"
+                        )
+            else:
+                for library in libraries:
+                    install_command = get_libraries_installation_command(
+                        self.lang, library
+                    )
+                    output = self.execute_command(install_command)
+                    if output.exit_code != 0:
+                        raise RuntimeError(
+                            f"Failed to install library {library}: {output}"
+                        )
+
+        code_file = f"/tmp/code.{get_code_file_extension(self.lang)}"
+        if self.lang == SupportedLanguage.GO:
+            code_dest_file = "/example/code.go"
+        else:
+            code_dest_file = code_file
+
+        with open(code_file, "w") as f:
+            f.write(code)
+
+        self.copy_to_runtime(code_file, code_dest_file)
+        commands = get_code_execution_command(self.lang, code_dest_file)
+
+        output = KubernetesConsoleOutput(0, "")
+        for command in commands:
+            if self.lang == SupportedLanguage.GO:
+                output = self.execute_command(command, workdir="/example")
+            else:
+                output = self.execute_command(command)
+
+            if output.exit_code != 0:
+                break
+
+        return ConsoleOutput(output.text)
+
+    def copy_to_runtime(self, src: str, dest: str):
+        if not self.container:
+            raise RuntimeError(
+                "Session is not open. Please call open() method before copying files."
+            )
+
+        start_time = time.time()
+        if self.verbose:
+            print(f"Copying {src} to {self.container}:{dest}..")
+
+        dest_dir = os.path.dirname(dest)
+        dest_file = os.path.basename(dest)
+
+        if dest_dir:
+            self.execute_command(f"mkdir -p {dest_dir}")
+
+        with open(src, "rb") as f:
+            tarstream = io.BytesIO()
+            with tarfile.open(fileobj=tarstream, mode="w") as tar:
+                tarinfo = tarfile.TarInfo(name=dest_file)
+                tarinfo.size = os.path.getsize(src)
+                tar.addfile(tarinfo, f)
+            tarstream.seek(0)
+
+            exec_command = ["tar", "xvf", "-", "-C", dest_dir]
+            resp = stream(
+                self.client.connect_get_namespaced_pod_exec,
+                self.container,
+                self.kube_namespace,
+                command=exec_command,
+                stderr=True,
+                stdin=True,
+                stdout=True,
+                tty=False,
+                _preload_content=False,
+            )
+            while resp.is_open():
+                resp.update(timeout=1)
+                if resp.peek_stdout():
+                    print(resp.read_stdout())
+                if resp.peek_stderr():
+                    print(resp.read_stderr())
+                resp.write_stdin(tarstream.read(4096))
+            resp.close()
+
+        end_time = time.time()
+        if self.verbose:
+            print(
+                f"Copied {src} to {self.container}:{dest} in {end_time - start_time:.2f} seconds"
+            )
+
+    def copy_from_runtime(self, src: str, dest: str):
+        if not self.container:
+            raise RuntimeError(
+                "Session is not open. Please call open() method before copying files."
+            )
+
+        if self.verbose:
+            print(f"Copying {self.container}:{src} to {dest}..")
+
+        exec_command = ["tar", "cf", "-", src]
+        resp = stream(
+            self.client.connect_get_namespaced_pod_exec,
+            self.container,
+            self.kube_namespace,
+            command=exec_command,
+            stderr=True,
+            stdin=False,
+            stdout=True,
+            tty=False,
+            _preload_content=False,
+        )
+        with open(dest, "wb") as f:
+            while resp.is_open():
+                resp.update(timeout=1)
+                if resp.peek_stdout():
+                    f.write(resp.read_stdout())
+                if resp.peek_stderr():
+                    print(resp.read_stderr())
+
+    def execute_command(
+        self, command: str, workdir: Optional[str] = None
+    ) -> KubernetesConsoleOutput:
+        if not self.container:
+            raise RuntimeError(
+                "Session is not open. Please call open() method before executing commands."
+            )
+
+        if self.verbose:
+            print(f"Executing command: {command}")
+
+        if workdir:
+            exec_command = ["sh", "-c", f"cd {workdir} && {command}"]
+        else:
+            exec_command = ["/bin/sh", "-c", command]
+
+        resp = stream(
+            self.client.connect_get_namespaced_pod_exec,
+            self.container,
+            self.kube_namespace,
+            command=exec_command,
+            stderr=True,
+            stdin=False,
+            stdout=True,
+            tty=False,
+            _preload_content=False,
+        )
+
+        output = ""
+        if self.verbose:
+            print("Output:", end=" ")
+
+        while resp.is_open():
+            resp.update(timeout=1)
+            if resp.peek_stdout():
+                chunk = resp.read_stdout()
+                output += chunk
+                if self.verbose:
+                    print(chunk, end="")
+            if resp.peek_stderr():
+                chunk = resp.read_stderr()
+                output += chunk
+                if self.verbose:
+                    print(chunk, end="")
+
+        exit_code = resp.returncode
+        return KubernetesConsoleOutput(exit_code, output)

llm_sandbox-0.1.0/llm_sandbox/session.py

@@ -0,0 +1,10 @@
+from llm_sandbox.docker import SandboxDockerSession
+from llm_sandbox.kubernetes import SandboxKubernetesSession
+
+
+class SandboxSession:
+    def __new__(cls, use_kubernetes: bool = False, *args, **kwargs):
+        if use_kubernetes:
+            return SandboxKubernetesSession(*args, **kwargs)
+
+        return SandboxDockerSession(*args, **kwargs)

llm_sandbox-0.1.0/llm_sandbox/utils.py

@@ -0,0 +1,90 @@
+import docker
+import docker.errors
+from typing import Optional
+
+from docker import DockerClient
+from llm_sandbox.const import SupportedLanguage
+
+
+def image_exists(client: DockerClient, image: str) -> bool:
+    """
+    Check if a Docker image exists
+    :param client: Docker client
+    :param image: Docker image
+    :return: True if the image exists, False otherwise
+    """
+    try:
+        client.images.get(image)
+        return True
+    except docker.errors.ImageNotFound:
+        return False
+    except Exception as e:
+        raise e
+
+
+def get_libraries_installation_command(lang: str, library: str) -> Optional[str]:
+    """
+    Get the command to install libraries for the given language
+    :param lang: Programming language
+    :param library: List of libraries
+    :return: Installation command
+    """
+    if lang == SupportedLanguage.PYTHON:
+        return f"pip install {library}"
+    elif lang == SupportedLanguage.JAVA:
+        return f"mvn install:install-file -Dfile={library}"
+    elif lang == SupportedLanguage.JAVASCRIPT:
+        return f"yarn add {library}"
+    elif lang == SupportedLanguage.CPP:
+        return f"apt-get install {library}"
+    elif lang == SupportedLanguage.GO:
+        return f"go get -u {library}"
+    elif lang == SupportedLanguage.RUBY:
+        return f"gem install {library}"
+    else:
+        raise ValueError(f"Language {lang} is not supported")
+
+
+def get_code_file_extension(lang: str) -> str:
+    """
+    Get the file extension for the given language
+    :param lang: Programming language
+    :return: File extension
+    """
+    if lang == SupportedLanguage.PYTHON:
+        return "py"
+    elif lang == SupportedLanguage.JAVA:
+        return "java"
+    elif lang == SupportedLanguage.JAVASCRIPT:
+        return "js"
+    elif lang == SupportedLanguage.CPP:
+        return "cpp"
+    elif lang == SupportedLanguage.GO:
+        return "go"
+    elif lang == SupportedLanguage.RUBY:
+        return "rb"
+    else:
+        raise ValueError(f"Language {lang} is not supported")
+
+
+def get_code_execution_command(lang: str, code_file: str) -> list:
+    """
+    Return the execution command for the given language and code file.
+    :param lang: Language of the code
+    :param code_file: Path to the code file
+    :return: List of execution commands
+    """
+    if lang == SupportedLanguage.PYTHON:
+        return [f"python {code_file}"]
+    elif lang == SupportedLanguage.JAVA:
+        return [f"java {code_file}"]
+    elif lang == SupportedLanguage.JAVASCRIPT:
+        return [f"node {code_file}"]
+    elif lang == SupportedLanguage.CPP:
+        return [f"g++ -o a.out {code_file}", "./a.out"]
+    elif lang == SupportedLanguage.GO:
+        return [f"go run {code_file}"]
+    elif lang == SupportedLanguage.RUBY:
+        return [f"ruby {code_file}"]
+    else:
+        raise ValueError(f"Language {lang} is not supported")

llm_sandbox-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[tool.poetry]
+name = "llm-sandbox"
+version = "0.1.0"
+description = "Lightweight and portable LLM sandbox runtime (code interpreter) Python library"
+authors = ["Duy Huynh <vndee.huynh@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+homepage = "https://github.com/vndee/llm-sandbox"
+repository = "https://github.com/vndee/llm-sandbox"
+packages = [
+    { include = "llm_sandbox" }
+]
+
+[tool.poetry.dependencies]
+python = "^3.11"
+docker = "^7.1.0"
+kubernetes = "^30.1.0"
+
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.2.2"
+pre-commit = "^3.7.1"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"