roche-sandbox 0.1.0__tar.gz

roche_sandbox-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+src/roche_sandbox/generated/
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+.venv/

roche_sandbox-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: roche-sandbox
+Version: 0.1.0
+Summary: Universal sandbox orchestrator for AI agents — Python SDK
+Project-URL: Homepage, https://github.com/substratum-labs/roche
+Project-URL: Repository, https://github.com/substratum-labs/roche
+Author: Substratum Labs
+License: Apache-2.0
+Keywords: agent,ai,docker,orchestrator,sandbox,wasm
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Emulators
+Requires-Python: >=3.10
+Requires-Dist: grpcio>=1.60.0
+Requires-Dist: protobuf>=4.25.0
+Provides-Extra: dev
+Requires-Dist: grpcio-tools>=1.60.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# roche-sandbox
+
+Python SDK for [Roche](https://github.com/substratum-labs/roche) -- universal sandbox orchestrator for AI agents.
+
+## Requirements
+
+- Python >= 3.10
+- Roche CLI on `PATH` (or Roche daemon running)
+
+## Install
+
+```bash
+pip install roche-sandbox
+```
+
+## Quick Start
+
+```python
+from roche_sandbox import Roche
+
+roche = Roche()
+sandbox = roche.create(image="python:3.12-slim")
+output = sandbox.exec(["python3", "-c", "print('Hello from Roche!')"])
+print(output.stdout)  # Hello from Roche!
+sandbox.destroy()
+```
+
+### Context Manager (auto-cleanup)
+
+```python
+with roche.create(image="python:3.12-slim") as sandbox:
+    output = sandbox.exec(["echo", "hello"])
+```
+
+### Async API
+
+```python
+import asyncio
+from roche_sandbox import AsyncRoche
+
+async def main():
+    roche = AsyncRoche()
+    sandbox = await roche.create(image="python:3.12-slim")
+    output = await sandbox.exec(["echo", "hello"])
+    await sandbox.destroy()
+
+asyncio.run(main())
+```
+
+## Configuration
+
+```python
+sandbox = roche.create(
+    image="python:3.12-slim",
+    memory="512m",
+    cpus=1.0,
+    timeout_secs=600,
+    network=False,    # default: AI-safe
+    writable=False,   # default: AI-safe
+    env={"API_KEY": "secret"},
+)
+```
+
+## Transport
+
+The SDK auto-detects whether the Roche gRPC daemon is running and connects to it. If the daemon is unavailable, it falls back to invoking the Roche CLI as a subprocess.
+
+You can force CLI mode explicitly:
+
+```python
+roche = Roche(mode="direct")
+```
+
+## API Styles
+
+The SDK provides two API styles:
+
+- **Async-first**: `AsyncRoche` and `AsyncSandbox` -- native `async`/`await` support.
+- **Sync wrapper**: `Roche` and `Sandbox` -- blocking equivalents for scripts and notebooks.
+
+## Public Exports
+
+```python
+from roche_sandbox import (
+    Roche, AsyncRoche,
+    Sandbox, AsyncSandbox,
+    SandboxConfig, ExecOutput, SandboxInfo,
+    Mount, SandboxStatus,
+    RocheError, SandboxNotFound, SandboxPaused,
+    ProviderUnavailable, TimeoutError, UnsupportedOperation,
+)
+```
+
+## License
+
+Apache-2.0 -- see [LICENSE](https://github.com/substratum-labs/roche/blob/main/LICENSE).

roche_sandbox-0.1.0/README.md

@@ -0,0 +1,96 @@
+# roche-sandbox
+
+Python SDK for [Roche](https://github.com/substratum-labs/roche) -- universal sandbox orchestrator for AI agents.
+
+## Requirements
+
+- Python >= 3.10
+- Roche CLI on `PATH` (or Roche daemon running)
+
+## Install
+
+```bash
+pip install roche-sandbox
+```
+
+## Quick Start
+
+```python
+from roche_sandbox import Roche
+
+roche = Roche()
+sandbox = roche.create(image="python:3.12-slim")
+output = sandbox.exec(["python3", "-c", "print('Hello from Roche!')"])
+print(output.stdout)  # Hello from Roche!
+sandbox.destroy()
+```
+
+### Context Manager (auto-cleanup)
+
+```python
+with roche.create(image="python:3.12-slim") as sandbox:
+    output = sandbox.exec(["echo", "hello"])
+```
+
+### Async API
+
+```python
+import asyncio
+from roche_sandbox import AsyncRoche
+
+async def main():
+    roche = AsyncRoche()
+    sandbox = await roche.create(image="python:3.12-slim")
+    output = await sandbox.exec(["echo", "hello"])
+    await sandbox.destroy()
+
+asyncio.run(main())
+```
+
+## Configuration
+
+```python
+sandbox = roche.create(
+    image="python:3.12-slim",
+    memory="512m",
+    cpus=1.0,
+    timeout_secs=600,
+    network=False,    # default: AI-safe
+    writable=False,   # default: AI-safe
+    env={"API_KEY": "secret"},
+)
+```
+
+## Transport
+
+The SDK auto-detects whether the Roche gRPC daemon is running and connects to it. If the daemon is unavailable, it falls back to invoking the Roche CLI as a subprocess.
+
+You can force CLI mode explicitly:
+
+```python
+roche = Roche(mode="direct")
+```
+
+## API Styles
+
+The SDK provides two API styles:
+
+- **Async-first**: `AsyncRoche` and `AsyncSandbox` -- native `async`/`await` support.
+- **Sync wrapper**: `Roche` and `Sandbox` -- blocking equivalents for scripts and notebooks.
+
+## Public Exports
+
+```python
+from roche_sandbox import (
+    Roche, AsyncRoche,
+    Sandbox, AsyncSandbox,
+    SandboxConfig, ExecOutput, SandboxInfo,
+    Mount, SandboxStatus,
+    RocheError, SandboxNotFound, SandboxPaused,
+    ProviderUnavailable, TimeoutError, UnsupportedOperation,
+)
+```
+
+## License
+
+Apache-2.0 -- see [LICENSE](https://github.com/substratum-labs/roche/blob/main/LICENSE).

roche_sandbox-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "roche-sandbox"
+version = "0.1.0"
+description = "Universal sandbox orchestrator for AI agents — Python SDK"
+license = {text = "Apache-2.0"}
+requires-python = ">=3.10"
+readme = "README.md"
+keywords = ["sandbox", "docker", "ai", "agent", "wasm", "orchestrator"]
+authors = [{name = "Substratum Labs"}]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+    "Topic :: System :: Emulators",
+]
+dependencies = [
+    "grpcio>=1.60.0",
+    "protobuf>=4.25.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/roche_sandbox"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-asyncio>=0.23.0",
+    "grpcio-tools>=1.60.0",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "strict"
+testpaths = ["tests"]
+
+[project.urls]
+Homepage = "https://github.com/substratum-labs/roche"
+Repository = "https://github.com/substratum-labs/roche"

roche_sandbox-0.1.0/scripts/proto-gen.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PROTO_DIR="$(cd "$(dirname "$0")/../../.." && pwd)/proto"
+OUT_DIR="$(cd "$(dirname "$0")/.." && pwd)/src/roche_sandbox/generated"
+
+rm -rf "$OUT_DIR"
+mkdir -p "$OUT_DIR/roche/v1"
+touch "$OUT_DIR/__init__.py"
+touch "$OUT_DIR/roche/__init__.py"
+touch "$OUT_DIR/roche/v1/__init__.py"
+
+python -m grpc_tools.protoc \
+  -I "$PROTO_DIR" \
+  --python_out="$OUT_DIR" \
+  --grpc_python_out="$OUT_DIR" \
+  --pyi_out="$OUT_DIR" \
+  "$PROTO_DIR/roche/v1/sandbox.proto"

roche_sandbox-0.1.0/src/roche_sandbox/__init__.py

@@ -0,0 +1,33 @@
+"""Roche — Universal sandbox orchestrator for AI agents (Python SDK)."""
+
+__version__ = "0.1.0"
+
+from roche_sandbox.client import AsyncRoche, Roche
+from roche_sandbox.errors import (
+    ProviderUnavailable,
+    RocheError,
+    SandboxNotFound,
+    SandboxPaused,
+    TimeoutError,
+    UnsupportedOperation,
+)
+from roche_sandbox.sandbox import AsyncSandbox, Sandbox
+from roche_sandbox.types import ExecOutput, Mount, SandboxConfig, SandboxInfo, SandboxStatus
+
+__all__ = [
+    "AsyncRoche",
+    "Roche",
+    "AsyncSandbox",
+    "Sandbox",
+    "RocheError",
+    "SandboxNotFound",
+    "SandboxPaused",
+    "ProviderUnavailable",
+    "TimeoutError",
+    "UnsupportedOperation",
+    "SandboxConfig",
+    "ExecOutput",
+    "SandboxInfo",
+    "SandboxStatus",
+    "Mount",
+]

roche_sandbox-0.1.0/src/roche_sandbox/client.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from roche_sandbox.daemon import detect_daemon
+from roche_sandbox.sandbox import AsyncSandbox, Sandbox
+from roche_sandbox.transport.cli import CliTransport
+from roche_sandbox.transport.grpc import GrpcTransport
+from roche_sandbox.types import ExecOutput, SandboxConfig, SandboxInfo
+
+if TYPE_CHECKING:
+    from roche_sandbox.transport import Transport
+
+
+class AsyncRoche:
+    def __init__(
+        self,
+        *,
+        mode: str = "auto",
+        daemon_port: int | None = None,
+        provider: str = "docker",
+        binary: str = "roche",
+        transport: Transport | None = None,
+    ):
+        self._provider = provider
+        if transport is not None:
+            self._transport = transport
+        elif mode == "direct":
+            self._transport = CliTransport(binary=binary)
+        elif daemon_port is not None:
+            self._transport = GrpcTransport(port=daemon_port)
+        else:
+            daemon = detect_daemon()
+            if daemon is not None:
+                self._transport = GrpcTransport(port=daemon["port"])
+            else:
+                self._transport = CliTransport(binary=binary)
+
+    @property
+    def transport(self) -> Transport:
+        return self._transport
+
+    async def create(
+        self,
+        *,
+        provider: str | None = None,
+        image: str = "python:3.12-slim",
+        memory: str | None = None,
+        cpus: float | None = None,
+        timeout_secs: int = 300,
+        network: bool = False,
+        writable: bool = False,
+        env: dict[str, str] | None = None,
+        mounts: list | None = None,
+        kernel: str | None = None,
+        rootfs: str | None = None,
+    ) -> AsyncSandbox:
+        effective_provider = provider or self._provider
+        config = SandboxConfig(
+            provider=effective_provider,
+            image=image,
+            memory=memory,
+            cpus=cpus,
+            timeout_secs=timeout_secs,
+            network=network,
+            writable=writable,
+            env=env or {},
+            mounts=mounts or [],
+            kernel=kernel,
+            rootfs=rootfs,
+        )
+        sandbox_id = await self._transport.create(config, effective_provider)
+        return AsyncSandbox(sandbox_id, effective_provider, self._transport)
+
+    async def create_id(self, **kwargs) -> str:
+        sb = await self.create(**kwargs)
+        return sb.id
+
+    async def exec(
+        self, sandbox_id: str, command: list[str], timeout_secs: int | None = None
+    ) -> ExecOutput:
+        return await self._transport.exec(sandbox_id, command, self._provider, timeout_secs)
+
+    async def destroy(self, sandbox_id: str) -> None:
+        await self._transport.destroy([sandbox_id], self._provider)
+
+    async def list(self) -> list[SandboxInfo]:
+        return await self._transport.list(self._provider)
+
+    async def gc(self, dry_run: bool = False, all: bool = False) -> list[str]:
+        return await self._transport.gc(self._provider, dry_run, all)
+
+
+class Roche:
+    def __init__(self, **kwargs):
+        self._async = AsyncRoche(**kwargs)
+
+    def create(self, **kwargs) -> Sandbox:
+        sb = asyncio.run(self._async.create(**kwargs))
+        return Sandbox(sb.id, sb.provider, self._async.transport)
+
+    def create_id(self, **kwargs) -> str:
+        return asyncio.run(self._async.create_id(**kwargs))
+
+    def exec(
+        self, sandbox_id: str, command: list[str], timeout_secs: int | None = None
+    ) -> ExecOutput:
+        return asyncio.run(self._async.exec(sandbox_id, command, timeout_secs))
+
+    def destroy(self, sandbox_id: str) -> None:
+        asyncio.run(self._async.destroy(sandbox_id))
+
+    def list(self) -> list[SandboxInfo]:
+        return asyncio.run(self._async.list())
+
+    def gc(self, dry_run: bool = False, all: bool = False) -> list[str]:
+        return asyncio.run(self._async.gc(dry_run, all))

roche_sandbox-0.1.0/src/roche_sandbox/daemon.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import TypedDict
+
+
+class DaemonInfo(TypedDict):
+    pid: int
+    port: int
+
+
+def daemon_json_path() -> Path:
+    return Path.home() / ".roche" / "daemon.json"
+
+
+def detect_daemon() -> DaemonInfo | None:
+    path = daemon_json_path()
+    if not path.exists():
+        return None
+    try:
+        data = json.loads(path.read_text())
+    except (json.JSONDecodeError, OSError):
+        return None
+    pid = data.get("pid")
+    port = data.get("port")
+    if not isinstance(pid, int) or not isinstance(port, int):
+        return None
+    if not _is_process_alive(pid):
+        return None
+    return DaemonInfo(pid=pid, port=port)
+
+
+def _is_process_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+        return True
+    except (OSError, ProcessLookupError):
+        return False

roche_sandbox-0.1.0/src/roche_sandbox/errors.py

@@ -0,0 +1,28 @@
+class RocheError(Exception):
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+class SandboxNotFound(RocheError):
+    def __init__(self, detail: str):
+        super().__init__(f"Sandbox not found: {detail}")
+
+
+class SandboxPaused(RocheError):
+    def __init__(self, detail: str):
+        super().__init__(f"Sandbox is paused: {detail}")
+
+
+class ProviderUnavailable(RocheError):
+    def __init__(self, detail: str):
+        super().__init__(f"Provider unavailable: {detail}")
+
+
+class TimeoutError(RocheError):
+    def __init__(self, detail: str):
+        super().__init__(f"Operation timed out: {detail}")
+
+
+class UnsupportedOperation(RocheError):
+    def __init__(self, detail: str):
+        super().__init__(f"Unsupported operation: {detail}")

roche_sandbox-0.1.0/src/roche_sandbox/sandbox.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+from roche_sandbox.types import ExecOutput
+
+if TYPE_CHECKING:
+    from roche_sandbox.transport import Transport
+
+
+class AsyncSandbox:
+    def __init__(self, id: str, provider: str, transport: Transport):
+        self._id = id
+        self._provider = provider
+        self._transport = transport
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    @property
+    def provider(self) -> str:
+        return self._provider
+
+    async def exec(self, command: list[str], timeout_secs: int | None = None) -> ExecOutput:
+        return await self._transport.exec(self._id, command, self._provider, timeout_secs)
+
+    async def pause(self) -> None:
+        await self._transport.pause(self._id, self._provider)
+
+    async def unpause(self) -> None:
+        await self._transport.unpause(self._id, self._provider)
+
+    async def destroy(self) -> None:
+        await self._transport.destroy([self._id], self._provider)
+
+    async def copy_to(self, host_path: str, sandbox_path: str) -> None:
+        await self._transport.copy_to(self._id, host_path, sandbox_path, self._provider)
+
+    async def copy_from(self, sandbox_path: str, host_path: str) -> None:
+        await self._transport.copy_from(self._id, sandbox_path, host_path, self._provider)
+
+    async def __aenter__(self) -> AsyncSandbox:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.destroy()
+
+
+class Sandbox:
+    def __init__(self, id: str, provider: str, transport: Transport):
+        self._inner = AsyncSandbox(id, provider, transport)
+
+    @property
+    def id(self) -> str:
+        return self._inner.id
+
+    @property
+    def provider(self) -> str:
+        return self._inner.provider
+
+    def exec(self, command: list[str], timeout_secs: int | None = None) -> ExecOutput:
+        return asyncio.run(self._inner.exec(command, timeout_secs))
+
+    def pause(self) -> None:
+        asyncio.run(self._inner.pause())
+
+    def unpause(self) -> None:
+        asyncio.run(self._inner.unpause())
+
+    def destroy(self) -> None:
+        asyncio.run(self._inner.destroy())
+
+    def copy_to(self, host_path: str, sandbox_path: str) -> None:
+        asyncio.run(self._inner.copy_to(host_path, sandbox_path))
+
+    def copy_from(self, sandbox_path: str, host_path: str) -> None:
+        asyncio.run(self._inner.copy_from(sandbox_path, host_path))
+
+    def __enter__(self) -> Sandbox:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.destroy()

roche_sandbox-0.1.0/src/roche_sandbox/transport/__init__.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from roche_sandbox.types import ExecOutput, SandboxConfig, SandboxInfo
+
+
+class Transport(Protocol):
+    async def create(self, config: SandboxConfig, provider: str) -> str: ...
+    async def exec(self, sandbox_id: str, command: list[str], provider: str, timeout_secs: int | None = None) -> ExecOutput: ...
+    async def destroy(self, sandbox_ids: list[str], provider: str, all: bool = False) -> list[str]: ...
+    async def list(self, provider: str) -> list[SandboxInfo]: ...
+    async def pause(self, sandbox_id: str, provider: str) -> None: ...
+    async def unpause(self, sandbox_id: str, provider: str) -> None: ...
+    async def gc(self, provider: str, dry_run: bool = False, all: bool = False) -> list[str]: ...
+    async def copy_to(self, sandbox_id: str, host_path: str, sandbox_path: str, provider: str) -> None: ...
+    async def copy_from(self, sandbox_id: str, sandbox_path: str, host_path: str, provider: str) -> None: ...