Metadata-Version: 2.5
Name: ppio-sandbox
Version: 2.1.2
Summary: PPIO Sandbox SDK - Python library for PPIO Agent Sandbox
Project-URL: Homepage, https://ppio.com/
Project-URL: Documentation, https://ppio-sandbox-sdk-python.readthedocs.io/
Project-URL: Repository, https://github.com/ppio/ppio-sandbox-sdk-python
Project-URL: Bug Tracker, https://github.com/ppio/ppio-sandbox-sdk-python/issues
Project-URL: Changelog, https://github.com/ppio/ppio-sandbox-sdk-python/blob/main/CHANGELOG.md
Author-email: PPIO <viktor@pplabs.org>
Maintainer-email: PPIO <viktor@pplabs.org>
License: MIT
Keywords: agent,ai,code-interpreter,desktop-automation,ppio,sandbox,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Operating System
Requires-Python: >=3.10
Requires-Dist: attrs>=23.2.0
Requires-Dist: dockerfile-parse>=2.0.1
Requires-Dist: httpcore>=1.0.5
Requires-Dist: httpx[socks]<0.29.0,>=0.28.1
Requires-Dist: packaging>=24.1
Requires-Dist: protobuf>=4.21.0
Requires-Dist: pydantic<3.0.0,>=2.13.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: rich>=14.0.0
Requires-Dist: starlette>=0.46.2
Requires-Dist: typing-extensions>=4.1.0
Requires-Dist: uvicorn>=0.34.2
Requires-Dist: wcmatch>=10.1
Provides-Extra: all
Requires-Dist: matplotlib>=3.6.0; extra == 'all'
Requires-Dist: numpy>=1.21.0; extra == 'all'
Requires-Dist: opencv-python>=4.7.0; extra == 'all'
Requires-Dist: pandas>=1.5.0; extra == 'all'
Requires-Dist: pillow>=9.0.0; extra == 'all'
Requires-Dist: plotly>=5.0.0; extra == 'all'
Requires-Dist: pyautogui>=0.9.54; extra == 'all'
Requires-Dist: pynput>=1.7.6; extra == 'all'
Requires-Dist: python-dateutil>=2.8.2; extra == 'all'
Description-Content-Type: text/markdown

# PPIO Sandbox SDK for Python

Python SDK for PPIO Sandbox environments, providing code execution, desktop automation, and cloud computing capabilities, which is compatible with e2b.

Please read the [documentation](https://ppio.com/docs/sandbox/overview) for more information.

## Installation

```bash
pip install ppio-sandbox
```

## Features

- 🚀 **Code Interpreter**: Execute Python, JavaScript, and other languages in isolated environments
- 🖥️ **Desktop Automation**: Control desktop applications and GUI interactions
- ☁️ **Cloud Computing**: Scalable sandbox environments for various computing tasks
- 📊 **Data Visualization**: Built-in charting and visualization capabilities
- 🔧 **File System Operations**: Complete file system management and monitoring

## Quick Start

### Authentication

You can get the PPIO API key by refer to this [documentation](https://ppio.com/docs/sandbox/get-start).

### Core

The basic package provides a way to interact with the sandbox environment.

```python
from ppio_sandbox.core import Sandbox
import os

# Using the official template `base` by default
sandbox = Sandbox.create(
    template="base",
    api_key=os.getenv("PPIO_API_KEY", "")
)

# File operations
sandbox.files.write('/tmp/test.txt', 'Hello, World!')
content = sandbox.files.read('/tmp/test.txt')

# Command execution
result = sandbox.commands.run('ls -la /tmp')
print(result.stdout)

sandbox.kill()
```

### Code Interpreter

The Code Interpreter sandbox provides a Jupyter-like environment for executing code using the official `code-interpreter-v1` template.

```python
from ppio_sandbox.code_interpreter import Sandbox
import os

sandbox = Sandbox.create(
    api_key=os.getenv("PPIO_API_KEY", "")
)

# Execute Python code
result = sandbox.run_code('print("Hello, World!")')
print(result.logs)

sandbox.kill()
```

### Desktop

The Desktop sandbox allows you to control desktop environments programmatically using the official `desktop` template.

```python
from ppio_sandbox.desktop import Sandbox
import os

desktop = Sandbox.create(
    api_key=os.getenv("PPIO_API_KEY", "")
)

# Take a screenshot
screenshot = desktop.screenshot()

# Automate mouse and keyboard
desktop.left_click(100, 200)
desktop.press('Return')
desktop.write('Hello, World!')

desktop.kill()
```

## Development

### Install

```bash
poetry install --with dev --extras "all" 
```

### Test

```bash
make test
make test-core
make test-code-interpreter
make test-desktop
```

### Template environment scope

`set_envs({...})` adds build-only variables. Use `set_envs({...}, runtime=True)`
when the resolved values must also be available in the sandbox. Dockerfile `ENV`
is persisted at runtime; Dockerfile `ARG` remains build-only. Declaration order
is preserved, and values in one declaration group read the preceding environment.
Image ENV values are literals; inherited WORKDIR applies before caller steps.

```python
template = Template().from_image("python:3.12-slim")
template.set_envs({"BUILD_MODE": "release"})
template.set_envs({"PATH": "/app/bin:$PATH", "APP_MODE": "worker"}, runtime=True)
```

Mutable image tags are refreshed for each serialization/build. Only successful
digest-pinned registry reads are cached; failed reads can be retried on the same
builder. Explicit caller commands and settings take precedence over image defaults.
