Metadata-Version: 2.5
Name: novita-sandbox
Version: 1.2.7b2
Summary: Novita Agent Sandbox SDK - Python library for Novita Agent Sandbox
Project-URL: Homepage, https://novita.ai
Project-URL: Documentation, https://novita.ai/docs/guides/sandbox-overview
Project-URL: Bug Tracker, https://novita.ai
Project-URL: Changelog, https://novita.ai/docs/changelog
Author-email: Novita <support@novita.ai>
Maintainer-email: Novita <support@novita.ai>
License: MIT
Keywords: Novita,agent,ai,code-interpreter,desktop-automation,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.9
Requires-Dist: attrs>=23.2.0
Requires-Dist: httpcore>=1.0.5
Requires-Dist: httpx<1.0.0,>=0.27.0
Requires-Dist: packaging>=24.1
Requires-Dist: protobuf>=5.26.1
Requires-Dist: pydantic<3.0.0,>=2.12.4
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: typing-extensions>=4.1.0
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'
Requires-Dist: starlette<0.51.0,>=0.48.0; extra == 'all'
Requires-Dist: uvicorn<0.41.0,>=0.38.0; extra == 'all'
Provides-Extra: runtime
Requires-Dist: starlette<0.51.0,>=0.48.0; extra == 'runtime'
Requires-Dist: uvicorn<0.41.0,>=0.38.0; extra == 'runtime'
Description-Content-Type: text/markdown

# Novita Agent Sandbox SDK for Python

A Python SDK for Novita Agent Sandbox environments that provides code execution, desktop automation, and cloud computing capabilities. Compatible with e2b.

[📖 Documentation](https://novita.ai/docs/guides/sandbox-overview) • [🔑 Get API Key](https://novita.ai/settings/key-management) 

## 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


## Installation

```bash
pip install novita-sandbox
```

## Quick Start

### Authentication

Get your Novita API key from the [key management page](https://novita.ai/settings/key-management).

### Core Sandbox

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

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

# Using the official template `base` by default
sandbox = Sandbox.create(
    template="base",
    api_key=os.getenv("NOVITA_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()
```

### Security on legacy clusters

This beta package targets legacy clusters. `Sandbox.create()` and
`Sandbox.beta_create()` keep `secure=False` as their default; explicitly passing
`None` uses the same default. Pass `secure=True` to require an access token for
system communication. The SDK stores the returned envd token and sends it with
system requests.

Public access to sandbox URLs is controlled separately:

```python
from novita_sandbox.core import Sandbox

sandbox = Sandbox.create(
    "base",
    domain="sandbox.novita.ai",
    secure=True,
    network={"allow_public_traffic": False},
)

# Connect resumes a paused sandbox and refreshes its traffic token.
sandbox.connect(secure=True, allow_public_traffic=False)
traffic_token = sandbox.traffic_access_token

if sandbox.reset(resume=True, secure=True, allow_public_traffic=False):
    traffic_token = sandbox.traffic_access_token
```

Creation uses `network={"allow_public_traffic": ...}`. Connect and reset accept
the top-level `allow_public_traffic` argument, which takes precedence over the
older `network` argument. Omitting `secure` or `allow_public_traffic` on connect
and reset leaves those settings to the server. Only `allow_public_traffic` is
supported in legacy network configuration.

Instance connect and reset reuse the API key, domain, and request settings from
the sandbox. Connect replaces or clears `traffic_access_token` from its response;
reset updates it only when a token is returned. Empty reset responses and
conflicts preserve the existing token. Reset still returns a boolean, with
`False` indicating a conflict. Cloned sandboxes also retain their returned
traffic tokens and legacy composite sandbox IDs.

The same options are supported by `AsyncSandbox` with `await`. Class calls such
as `Sandbox.connect(sandbox_id, ...)` and `Sandbox.reset(sandbox_id, ...)` remain
available.

### Code Interpreter

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

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

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

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

sandbox.kill()
```

### Desktop Automation

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

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

desktop = Sandbox.create(
    api_key=os.getenv("NOVITA_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()
```

## Documentation

For comprehensive guides, API references, and examples, visit our [official documentation](https://novita.ai/docs/guides/sandbox-overview).

## Development

### Install

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

### Test

```bash
make test
make test-unit  # offline; no API key needed
make test-core
make test-code-interpreter
make test-desktop
```
