# vndee/llm-sandbox architecture

> Architecture diagram of the GitHub repository vndee/llm-sandbox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/vndee/llm-sandbox
- Repository: https://github.com/vndee/llm-sandbox

## Overview

##### Project type and purpose
- LLM Sandbox is an open‑source Python library (not a web app) whose goal is to let developers and AI frameworks safely run arbitrary code generated by large language models inside isolated container sandboxes (Docker, Kubernetes, Podman).

##### File structure
- Top‑level modules under llm_sandbox/:
- base.py – defines the abstract SandboxSession interface and lifecycle
- factory.py – selects and instantiates the correct backend implementation
- session.py – implements the context‑manager that orchestrates open/run/close
- docker.py, kubernetes.py, podman.py, micromamba.py – concrete backends for each container runtime
- security.py, utils.py, const.py, exceptions.py – supporting utilities, constants, and error classes
- examples/ shows how clients and AI frameworks (Langchain, LlamaIndex) integrate by calling SandboxSession
- tests/ exercise each backend to validate session open/run/close

##### README for additional insights
- Emphasizes four lifecycle steps (init → open → run → close)
- Lists supported languages (py, js, java, go, cpp, ruby)
- Mentions optional features (custom Dockerfiles, remote Docker host, Kubernetes manifests, Podman)

a. Main components (group into logical tiers)
- Client Layer:
– User application code (including examples or LLM‑agent code)
– AI Frameworks (Langchain, LlamaIndex) that invoke run_code()
- Library Core:
– SandboxSession (context manager)
– Factory module (decides backend)
– Abstract base session (defines open/run/close)
– Backend implementations: DockerBackend, K8sBackend, PodmanBackend, MicromambaBackend
– Utilities: security scanners, helpers, exception handlers
- Container Platform Layer:
– Docker daemon (local or remote via TLS)
– Kubernetes cluster (CoreV1Api client + pod_manifest)
– Podman service
- Sandbox Runtime Environment (ephemeral container or pod)
– Container image (official or custom Dockerfile)
– Mounted volumes, network namespace, exec calls
- Host OS / Underlying infrastructure (actual nodes, file system)

b. Relationships and interactions
1. Client → SandboxSession.open(): calls Factory → selects appropriate backend
2. Backend.open():
– builds/pulls image → starts container/pod
3. Client → SandboxSession.run(code, libs):
– backend.exec() → sends code to container’s shell/entrypoint → returns stdout/stderr
4. Client → SandboxSession.close():
– backend.clean(): stops & removes container (and image if keep_template=False)
5. Optional: Client ↔ session.copy_to_runtime()/copy_from_runtime() for file transfers

c. Architectural patterns & design principles
- Factory pattern: decouple core API from container runtime implementations
- Strategy pattern: each backend implements a common interface
- Context manager for deterministic resource cleanup
- Single Responsibility: separate modules for orchestration (session), platform adapters, security, and utilities

d. Key technologies, frameworks & libraries
- Docker SDK for Python
- Kubernetes Python client (CoreV1Api)
- Podman Python bindings
- Micromamba for language‑specific environment management (optional)
- Python typing, exceptions, utils (JSON, logging)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        Example["Example Integrations"]:::client
        AI["AI Frameworks\n(Langchain, LlamaIndex)"]:::client
    end

    %% Library Core
    subgraph "Library Core"
        direction TB
        Session["SandboxSession\n(context manager)"]:::core
        Base["SandboxSession Interface\n(base.py)"]:::core
        Factory["Factory Module\n(factory.py)"]:::core
        subgraph "Backend Implementations"
            direction TB
            Docker["DockerBackend"]:::core
            K8s["KubernetesBackend"]:::core
            Podman["PodmanBackend"]:::core
            Micromamba["MicromambaBackend"]:::core
        end
        Security["Security Scanning\n(security.py)"]:::core
        Utils["Helper Utilities\n(utils.py)"]:::core
        Const["Constants\n(const.py)"]:::core
        Exceptions["Exceptions\n(exceptions.py)"]:::core
    end

    %% Container Platform Layer
    subgraph "Container Platform"
        direction TB
        DockerDaemon["Docker Daemon"]:::platform
        K8sCluster["Kubernetes Cluster\n(CoreV1Api)"]:::platform
        PodmanService["Podman Service"]:::platform
    end

    %% Sandbox Runtime Environment
    subgraph "Sandbox Runtime Environment"
        direction TB
        Container["Ephemeral Container/Pod"]:::runtime
    end

    %% Host OS / Infrastructure
    Host["Host OS / Infrastructure"]:::host

    %% Connections
    Example -->|"calls open()/run_code()"| Session
    AI -->|"invokes run_code()"| Session

    Session -->|"open() calls"| Factory
    Factory -->|"selects DockerBackend"| Docker
    Factory -->|"selects KubernetesBackend"| K8s
    Factory -->|"selects PodmanBackend"| Podman
    Factory -->|"selects MicromambaBackend"| Micromamba

    Docker -->|"open(): build/pull & start"| DockerDaemon
    K8s -->|"open(): create pod"| K8sCluster
    Podman -->|"open(): start container"| PodmanService

    DockerDaemon -->|"manages container"| Container
    K8sCluster -->|"manages pod"| Container
    PodmanService -->|"manages container"| Container

    Docker -->|"exec() runs code"| Container
    K8s -->|"exec() runs code"| Container
    Podman -->|"exec() runs code"| Container
    Micromamba -->|"exec() runs code"| Container

    Container -->|"stdout/stderr returned"| Session

    Session -->|"close(): cleanup"| Docker
    Session -->|"close(): cleanup"| K8s
    Session -->|"close(): cleanup"| Podman
    Session -->|"close(): cleanup"| Micromamba

    Host -->|"provides nodes & filesystem"| DockerDaemon
    Host -->|"provides nodes & filesystem"| K8sCluster
    Host -->|"provides nodes & filesystem"| PodmanService

    %% Click Events
    click Example "https://github.com/vndee/llm-sandbox/tree/main/examples/"
    click Session "https://github.com/vndee/llm-sandbox/blob/main/llm_sandbox/session.py"
    click Base "https://github.com/vndee/llm-sandbox/blob/main/llm_sandbox/base.py"
    click Factory "https://github.com/vndee/llm-sandbox/blob/main/llm_sandbox/factory.py"
    click Docker "https://github.com/vndee/llm-sandbox/blob/main/llm_sandbox/docker.py"
    click K8s "https://github.com/vndee/llm-sandbox/blob/main/llm_sandbox/kubernetes.py"
    click Podman "https://github.com/vndee/llm-sandbox/blob/main/llm_sandbox/podman.py"
    click Micromamba "https://github.com/vndee/llm-sandbox/blob/main/llm_sandbox/micromamba.py"
    click Security "https://github.com/vndee/llm-sandbox/blob/main/llm_sandbox/security.py"
    click Utils "https://github.com/vndee/llm-sandbox/blob/main/llm_sandbox/utils.py"
    click Const "https://github.com/vndee/llm-sandbox/blob/main/llm_sandbox/const.py"
    click Exceptions "https://github.com/vndee/llm-sandbox/blob/main/llm_sandbox/exceptions.py"
    click Host "https://github.com/vndee/llm-sandbox/tree/main/tests/"
    click Host "https://github.com/vndee/llm-sandbox/blob/main/tests/test_session.py"
    click Host "https://github.com/vndee/llm-sandbox/blob/main/tests/test_session_kubernetes.py"
    click Host "https://github.com/vndee/llm-sandbox/blob/main/tests/test_session_podman.py"

    %% Styles
    classDef client fill:#cfe2ff,stroke:#0366d6,color:#0366d6;
    classDef core fill:#d1e7dd,stroke:#198754,color:#198754;
    classDef platform fill:#fce5cd,stroke:#d65a00,color:#d65a00;
    classDef runtime fill:#fff2cc,stroke:#c79200,color:#c79200;
    classDef host fill:#f2f2f2,stroke:#6c757d,color:#6c757d;
```
