Metadata-Version: 2.5
Name: isle-sdk
Version: 0.1.0
Summary: Python SDK for Isle — application environments for AI agents
Project-URL: Homepage, https://www.tryisle.com
Project-URL: Documentation, https://www.tryisle.com/docs
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.9
Requires-Dist: httpx>=0.25.0
Description-Content-Type: text/markdown

# Isle Python SDK

Application environments for AI agents.

## Install

Requires Python 3.9 or later.

```bash
python -m pip install isle-sdk
```

The package is named `isle-sdk` on PyPI and imported as `isle`. Get an API key
from the [Isle dashboard](https://www.tryisle.com/api-keys).

The SDK automatically generates an idempotency key and reuses it for one
transport retry. Pass `idempotency_key=` when the same create operation may be
retried by a different process.

## Quickstart

```python
from isle import Client, IsleAPIError

isle = Client(api_key="isle_...")

# Create a KiCad sandbox
sandbox = isle.sandboxes.create(
    "kicad",
    name="Power supply board",
    idempotency_key="power-supply-board-v1",
)
sandbox.wait_until_ready()

# Upload a file
sandbox.files.upload("schematic.kicad_sch")

# Take a screenshot
image = sandbox.screen.screenshot()

# Control the mouse and keyboard
sandbox.mouse.click(500, 300)
sandbox.keyboard.type("100nF")
sandbox.keyboard.keypress(["CTRL", "S"])

# Download results
sandbox.files.download("/home/user/work/board.kicad_pcb")

# Stop (archives the sandbox, can be resumed later)
sandbox.stop()
sandbox.wait_until_stopped()

# Resume a stopped sandbox
sandbox.resume()

# Lifecycle failures are returned by the API and retained on the environment
sandbox.refresh()
if sandbox.last_error:
    print(sandbox.last_error, sandbox.last_error_at)

# Retrieve timestamped error history (newest first)
for error in sandbox.errors():
    print(error["source"], error["message"], error["created_at"])

# Recording metadata distinguishes a complete recording from the bounded
# 512 MiB / six-hour / low-disk partial recording policy.
recording = sandbox.recording_info()
print(recording["url"], recording["truncated"], recording["truncation_reason"])

# Permanently delete a stopped sandbox and its retained data
sandbox.stop()
sandbox.wait_until_stopped()
sandbox.destroy(timeout=120)
```

API failures raise `IsleAPIError`. Its `status_code`, `error`, and `metadata`
attributes can be used to handle failures without parsing an exception string.
For example, a provisioning failure includes its recoverable
`metadata["environment_id"]` when the API created a record before the remote
environment failed to start.

## Environments

- `kicad` - EDA environment with KiCad
- `freecad` - CAD environment with FreeCAD

## Development

From an authorized Isle repository checkout:

```bash
python -m pip install -e ./sdk/python
python -m unittest discover -s sdk/python/tests
```
