isle-sdk 0.1.0__tar.gz

isle_sdk-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# generated test and benchmark output
+/artifacts/
+
+# python
+__pycache__/
+/sdk/python/dist/
+/sdk/python/.venv/
+*.egg-info/
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files
+.env
+.env.local
+.env*.local
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# supabase
+supabase/.temp/
+.env*

isle_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Isle contributors
+
+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.

isle_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+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
+```

isle_sdk-0.1.0/README.md

@@ -0,0 +1,94 @@
+# 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
+```

isle_sdk-0.1.0/isle/__init__.py

@@ -0,0 +1,5 @@
+from isle.client import Client, IsleAPIError
+from isle.sandbox import Environment, Sandbox
+
+__all__ = ["Client", "Environment", "IsleAPIError", "Sandbox"]
+__version__ = "0.1.0"

isle_sdk-0.1.0/isle/client.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+from typing import Any
+import time
+import uuid
+
+import httpx
+
+from isle.sandbox import Environment, Sandbox, validate_environment
+
+
+class IsleAPIError(Exception):
+    """An error response returned by the Isle API."""
+
+    def __init__(self, response: httpx.Response) -> None:
+        self.status_code = response.status_code
+        self.response = response
+        self.method = response.request.method
+        self.url = str(response.request.url)
+
+        try:
+            payload: Any = response.json()
+        except ValueError:
+            payload = None
+
+        self.payload = payload
+        self.metadata = payload if isinstance(payload, dict) else {}
+        self.error = self.metadata.get("error")
+
+        if self.error is not None:
+            detail = str(self.error)
+        elif payload is not None:
+            detail = str(payload)
+        else:
+            detail = response.text or response.reason_phrase
+
+        super().__init__(f"Isle API error {self.status_code}: {detail}")
+
+
+class _SandboxManager:
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def create(
+        self,
+        environment: Environment,
+        *,
+        name: str | None = None,
+        retain: bool = True,
+        timeout: float = 360.0,
+        idempotency_key: str | None = None,
+    ) -> Sandbox:
+        environment = validate_environment(environment)
+        body: dict = {"environment": environment, "retain": retain}
+        if name is not None:
+            body["name"] = name
+        resolved_idempotency_key = (
+            idempotency_key or f"isle-sdk-{uuid.uuid4().hex}"
+        )
+        headers = {"Idempotency-Key": resolved_idempotency_key}
+        deadline = time.monotonic() + timeout
+        for attempt in range(2):
+            try:
+                resp = self._client._request(
+                    "POST",
+                    "/api/sandboxes",
+                    json=body,
+                    headers=headers,
+                    timeout=(
+                        timeout
+                        if attempt == 0
+                        else max(deadline - time.monotonic(), 0.001)
+                    ),
+                )
+                break
+            except httpx.TransportError:
+                if attempt == 1 or time.monotonic() >= deadline:
+                    raise
+        return Sandbox(self._client, resp)
+
+    def list(self) -> list[Sandbox]:
+        resp = self._client._request("GET", "/api/sandboxes")
+        return [Sandbox(self._client, sandbox) for sandbox in resp]
+
+    def get(self, sandbox_id: str) -> Sandbox:
+        resp = self._client._request("GET", f"/api/sandboxes/{sandbox_id}")
+        return Sandbox(self._client, resp)
+
+
+class _ProviderDeletionManager:
+    def __init__(self, client: Client) -> None:
+        self._client = client
+
+    def get(self, tracking_id: str) -> dict:
+        return self._client._request(
+            "GET", f"/api/provider-deletions/{tracking_id}"
+        )
+
+    def wait(
+        self,
+        tracking_id: str,
+        *,
+        timeout: float = 120.0,
+        poll: float = 1.0,
+    ) -> dict:
+        if timeout < 0:
+            raise ValueError("timeout must be non-negative")
+        if poll <= 0:
+            raise ValueError("poll must be greater than zero")
+
+        deadline = time.monotonic() + timeout
+        last: dict | None = None
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            last = self._client._request(
+                "GET",
+                f"/api/provider-deletions/{tracking_id}",
+                timeout=remaining,
+            )
+            if (
+                last.get("provider_deletion_complete") is True
+                or last.get("requires_manual_verification") is True
+                or last.get("provider_operation_status") == "failed"
+            ):
+                return last
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                break
+            time.sleep(min(poll, remaining))
+
+        status = (
+            last.get("provider_operation_status", "unknown")
+            if last is not None
+            else "unknown"
+        )
+        raise TimeoutError(
+            f"Provider deletion {tracking_id} did not finish in {timeout}s "
+            f"(last status: {status})"
+        )
+
+class Client:
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = "https://www.tryisle.com",
+    ) -> None:
+        import os
+
+        self.api_key = api_key or os.environ.get("ISLE_API_KEY", "")
+        if not self.api_key:
+            raise ValueError(
+                "api_key is required. Pass it directly or set ISLE_API_KEY."
+            )
+
+        self.base_url = base_url.rstrip("/")
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            headers={"Authorization": f"Bearer {self.api_key}"},
+            timeout=30.0,
+            # Follow same-host routing redirects. The default uses the
+            # canonical host directly because HTTP clients intentionally strip
+            # Authorization when a redirect changes hosts.
+            follow_redirects=True,
+        )
+        self.sandboxes = _SandboxManager(self)
+        self.provider_deletions = _ProviderDeletionManager(self)
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict | None = None,
+        params: dict | None = None,
+        headers: dict[str, str] | None = None,
+        timeout: float | None = None,
+    ) -> dict | list:
+        request_options: dict[str, Any] = {
+            "json": json,
+            "params": params,
+            "headers": headers,
+        }
+        if timeout is not None:
+            request_options["timeout"] = timeout
+        resp = self._http.request(method, path, **request_options)
+        if resp.status_code >= 400:
+            raise IsleAPIError(resp)
+        return resp.json()
+
+    def _request_raw(
+        self,
+        method: str,
+        path: str,
+        *,
+        timeout: float | None = None,
+        **kwargs,
+    ) -> httpx.Response:
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+        resp = self._http.request(method, path, **kwargs)
+        if resp.status_code >= 400:
+            raise IsleAPIError(resp)
+        return resp
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Client:
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()