aury-agent 0.0.4__py3-none-any.whl

aury/agents/sandbox/__init__.py

@@ -0,0 +1,23 @@
+"""Sandbox module for isolated code execution environments.
+
+Provides abstracted sandbox interfaces supporting:
+- Local Docker-based sandboxes for CLI/development
+- Remote API-based sandboxes for SaaS deployment
+"""
+from .types import ExecutionResult, SandboxConfig, Sandbox, SandboxProvider
+from .local import LocalSandbox, LocalSandboxProvider
+from .remote import RemoteSandbox, RemoteSandboxProvider
+
+__all__ = [
+    # Types
+    "ExecutionResult",
+    "SandboxConfig",
+    "Sandbox",
+    "SandboxProvider",
+    # Local
+    "LocalSandbox",
+    "LocalSandboxProvider",
+    # Remote
+    "RemoteSandbox",
+    "RemoteSandboxProvider",
+]

aury/agents/sandbox/local.py

@@ -0,0 +1,239 @@
+"""Local Docker-based sandbox implementation."""
+from __future__ import annotations
+
+import asyncio
+import os
+import tarfile
+import time
+from io import BytesIO
+from pathlib import Path
+from typing import Any, Literal
+
+from .types import ExecutionResult, SandboxConfig
+
+
+class LocalSandbox:
+    """Local Docker-based sandbox implementation.
+    
+    Uses Docker containers for isolation. Requires Docker to be installed
+    and accessible via the Docker socket.
+    """
+    
+    def __init__(self, container: Any, config: SandboxConfig) -> None:
+        self._container = container
+        self._config = config
+        self._status: Literal["creating", "running", "stopped", "failed"] = "running"
+    
+    @property
+    def id(self) -> str:
+        return self._container.id
+    
+    @property
+    def status(self) -> Literal["creating", "running", "stopped", "failed"]:
+        return self._status
+    
+    async def execute(
+        self,
+        command: str | list[str],
+        *,
+        timeout: int | None = None,
+        stdin: str | None = None,
+        env: dict[str, str] | None = None,
+        workdir: str | None = None,
+    ) -> ExecutionResult:
+        """Execute command in Docker container."""
+        if isinstance(command, list):
+            cmd = command
+        else:
+            cmd = ["/bin/sh", "-c", command]
+        
+        work_dir = workdir or self._config.workdir
+        effective_timeout = timeout or self._config.timeout
+        start_time = time.time()
+        
+        def _exec() -> tuple[int, bytes]:
+            exec_result = self._container.exec_run(
+                cmd=cmd,
+                environment=env,
+                workdir=work_dir,
+                stdin=stdin is not None,
+                demux=True,
+            )
+            return exec_result.exit_code, exec_result.output
+        
+        try:
+            loop = asyncio.get_event_loop()
+            exit_code, output = await asyncio.wait_for(
+                loop.run_in_executor(None, _exec),
+                timeout=effective_timeout,
+            )
+            
+            stdout = ""
+            stderr = ""
+            if output:
+                if isinstance(output, tuple):
+                    stdout = (output[0] or b"").decode("utf-8", errors="replace")
+                    stderr = (output[1] or b"").decode("utf-8", errors="replace")
+                else:
+                    stdout = output.decode("utf-8", errors="replace")
+            
+            return ExecutionResult(
+                exit_code=exit_code or 0,
+                stdout=stdout,
+                stderr=stderr,
+                duration_ms=int((time.time() - start_time) * 1000),
+            )
+            
+        except asyncio.TimeoutError:
+            return ExecutionResult(
+                exit_code=-1,
+                stdout="",
+                stderr=f"Command timed out after {effective_timeout}s",
+                duration_ms=effective_timeout * 1000,
+                timed_out=True,
+            )
+    
+    async def write_file(self, path: str, content: str | bytes) -> None:
+        """Write file to container using tar archive."""
+        if isinstance(content, str):
+            content = content.encode("utf-8")
+        
+        def _write() -> None:
+            tar_stream = BytesIO()
+            with tarfile.open(fileobj=tar_stream, mode="w") as tar:
+                file_info = tarfile.TarInfo(name=os.path.basename(path))
+                file_info.size = len(content)
+                tar.addfile(file_info, BytesIO(content))
+            tar_stream.seek(0)
+            self._container.put_archive(os.path.dirname(path) or "/", tar_stream)
+        
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, _write)
+    
+    async def read_file(self, path: str) -> bytes:
+        """Read file from container using tar archive."""
+        def _read() -> bytes:
+            bits, _ = self._container.get_archive(path)
+            tar_stream = BytesIO()
+            for chunk in bits:
+                tar_stream.write(chunk)
+            tar_stream.seek(0)
+            
+            with tarfile.open(fileobj=tar_stream, mode="r") as tar:
+                member = tar.getmembers()[0]
+                f = tar.extractfile(member)
+                if f:
+                    return f.read()
+                return b""
+        
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(None, _read)
+    
+    async def upload(self, local_path: Path, remote_path: str) -> None:
+        """Upload file/directory to container."""
+        def _upload() -> None:
+            tar_stream = BytesIO()
+            with tarfile.open(fileobj=tar_stream, mode="w") as tar:
+                tar.add(str(local_path), arcname=os.path.basename(remote_path))
+            tar_stream.seek(0)
+            dest_dir = os.path.dirname(remote_path) or "/"
+            self._container.put_archive(dest_dir, tar_stream)
+        
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, _upload)
+    
+    async def download(self, remote_path: str, local_path: Path) -> None:
+        """Download file/directory from container."""
+        def _download() -> None:
+            bits, _ = self._container.get_archive(remote_path)
+            tar_stream = BytesIO()
+            for chunk in bits:
+                tar_stream.write(chunk)
+            tar_stream.seek(0)
+            with tarfile.open(fileobj=tar_stream, mode="r") as tar:
+                tar.extractall(str(local_path.parent))
+        
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, _download)
+    
+    async def stop(self) -> None:
+        """Stop container."""
+        def _stop() -> None:
+            self._container.stop()
+        
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, _stop)
+        self._status = "stopped"
+    
+    async def destroy(self) -> None:
+        """Remove container."""
+        def _remove() -> None:
+            self._container.remove(force=True)
+        
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(None, _remove)
+        self._status = "stopped"
+
+
+class LocalSandboxProvider:
+    """Local Docker-based sandbox provider.
+    
+    Creates sandboxes using local Docker installation.
+    Suitable for CLI usage and development.
+    
+    Requires: docker package (`pip install docker`)
+    """
+    
+    def __init__(
+        self,
+        docker_socket: str = "unix:///var/run/docker.sock",
+        default_config: SandboxConfig | None = None,
+    ) -> None:
+        self.docker_socket = docker_socket
+        self.default_config = default_config or SandboxConfig()
+        self._client: Any = None
+    
+    def _get_client(self) -> Any:
+        """Lazy-load Docker client."""
+        if self._client is None:
+            try:
+                import docker
+                self._client = docker.DockerClient(base_url=self.docker_socket)
+            except ImportError:
+                raise ImportError(
+                    "docker package required for LocalSandboxProvider. "
+                    "Install with: pip install docker"
+                )
+        return self._client
+    
+    async def create(self, config: SandboxConfig | None = None) -> LocalSandbox:
+        """Create a new Docker-based sandbox."""
+        cfg = config or self.default_config
+        client = self._get_client()
+        
+        def _create() -> Any:
+            volumes = {}
+            for host, container in cfg.volumes.items():
+                volumes[host] = {"bind": container, "mode": "rw"}
+            
+            container = client.containers.run(
+                image=cfg.image,
+                detach=True,
+                mem_limit=cfg.memory_limit,
+                cpu_period=100000,
+                cpu_quota=int(cfg.cpu_limit * 100000),
+                network_disabled=not cfg.network,
+                volumes=volumes or None,
+                environment=cfg.env or None,
+                working_dir=cfg.workdir,
+                command="sleep infinity",
+            )
+            return container
+        
+        loop = asyncio.get_event_loop()
+        container = await loop.run_in_executor(None, _create)
+        
+        return LocalSandbox(container, cfg)
+
+
+__all__ = ["LocalSandbox", "LocalSandboxProvider"]

aury/agents/sandbox/remote.py

@@ -0,0 +1,200 @@
+"""Remote API-based sandbox implementation."""
+from __future__ import annotations
+
+import base64
+from pathlib import Path
+from typing import Any, Literal
+
+from .types import ExecutionResult, SandboxConfig
+
+
+class RemoteSandbox:
+    """Remote sandbox accessed via HTTP API.
+    
+    Connects to a sandbox service for SaaS deployments.
+    """
+    
+    def __init__(
+        self,
+        client: Any,  # httpx.AsyncClient
+        api_url: str,
+        sandbox_id: str,
+        api_key: str,
+        config: SandboxConfig,
+    ) -> None:
+        self._client = client
+        self._api_url = api_url
+        self._sandbox_id = sandbox_id
+        self._api_key = api_key
+        self._config = config
+        self._status: Literal["creating", "running", "stopped", "failed"] = "running"
+    
+    @property
+    def id(self) -> str:
+        return self._sandbox_id
+    
+    @property
+    def status(self) -> Literal["creating", "running", "stopped", "failed"]:
+        return self._status
+    
+    def _headers(self) -> dict[str, str]:
+        return {"Authorization": f"Bearer {self._api_key}"}
+    
+    async def execute(
+        self,
+        command: str | list[str],
+        *,
+        timeout: int | None = None,
+        stdin: str | None = None,
+        env: dict[str, str] | None = None,
+        workdir: str | None = None,
+    ) -> ExecutionResult:
+        """Execute command via API."""
+        response = await self._client.post(
+            f"{self._api_url}/sandboxes/{self._sandbox_id}/exec",
+            headers=self._headers(),
+            json={
+                "command": command if isinstance(command, str) else " ".join(command),
+                "timeout": timeout or self._config.timeout,
+                "stdin": stdin,
+                "env": env,
+                "workdir": workdir or self._config.workdir,
+            },
+            timeout=timeout or self._config.timeout + 10,
+        )
+        response.raise_for_status()
+        data = response.json()
+        
+        return ExecutionResult(
+            exit_code=data.get("exit_code", 0),
+            stdout=data.get("stdout", ""),
+            stderr=data.get("stderr", ""),
+            duration_ms=data.get("duration_ms", 0),
+            timed_out=data.get("timed_out", False),
+        )
+    
+    async def write_file(self, path: str, content: str | bytes) -> None:
+        """Write file via API."""
+        if isinstance(content, str):
+            content = content.encode("utf-8")
+        
+        response = await self._client.post(
+            f"{self._api_url}/sandboxes/{self._sandbox_id}/files",
+            headers=self._headers(),
+            json={
+                "path": path,
+                "content": base64.b64encode(content).decode("ascii"),
+            },
+        )
+        response.raise_for_status()
+    
+    async def read_file(self, path: str) -> bytes:
+        """Read file via API."""
+        response = await self._client.get(
+            f"{self._api_url}/sandboxes/{self._sandbox_id}/files",
+            headers=self._headers(),
+            params={"path": path},
+        )
+        response.raise_for_status()
+        data = response.json()
+        return base64.b64decode(data.get("content", ""))
+    
+    async def upload(self, local_path: Path, remote_path: str) -> None:
+        """Upload file via API."""
+        content = local_path.read_bytes()
+        await self.write_file(remote_path, content)
+    
+    async def download(self, remote_path: str, local_path: Path) -> None:
+        """Download file via API."""
+        content = await self.read_file(remote_path)
+        local_path.write_bytes(content)
+    
+    async def stop(self) -> None:
+        """Stop sandbox via API."""
+        response = await self._client.post(
+            f"{self._api_url}/sandboxes/{self._sandbox_id}/stop",
+            headers=self._headers(),
+        )
+        response.raise_for_status()
+        self._status = "stopped"
+    
+    async def destroy(self) -> None:
+        """Destroy sandbox via API."""
+        response = await self._client.delete(
+            f"{self._api_url}/sandboxes/{self._sandbox_id}",
+            headers=self._headers(),
+        )
+        response.raise_for_status()
+        self._status = "stopped"
+
+
+class RemoteSandboxProvider:
+    """Remote sandbox provider via HTTP API.
+    
+    Creates sandboxes by calling a remote sandbox service.
+    Suitable for SaaS deployments with multi-tenancy.
+    
+    Requires: httpx package (`pip install httpx`)
+    """
+    
+    def __init__(
+        self,
+        api_url: str,
+        api_key: str,
+        default_config: SandboxConfig | None = None,
+    ) -> None:
+        self.api_url = api_url.rstrip("/")
+        self.api_key = api_key
+        self.default_config = default_config or SandboxConfig()
+        self._client: Any = None
+    
+    async def _get_client(self) -> Any:
+        """Lazy-load httpx client."""
+        if self._client is None:
+            try:
+                import httpx
+                self._client = httpx.AsyncClient()
+            except ImportError:
+                raise ImportError(
+                    "httpx package required for RemoteSandboxProvider. "
+                    "Install with: pip install httpx"
+                )
+        return self._client
+    
+    async def create(self, config: SandboxConfig | None = None) -> RemoteSandbox:
+        """Create a new remote sandbox."""
+        cfg = config or self.default_config
+        client = await self._get_client()
+        
+        response = await client.post(
+            f"{self.api_url}/sandboxes",
+            headers={"Authorization": f"Bearer {self.api_key}"},
+            json={
+                "image": cfg.image,
+                "timeout": cfg.timeout,
+                "memory_limit": cfg.memory_limit,
+                "cpu_limit": cfg.cpu_limit,
+                "network": cfg.network,
+                "env": cfg.env,
+                "workdir": cfg.workdir,
+            },
+        )
+        response.raise_for_status()
+        data = response.json()
+        
+        return RemoteSandbox(
+            client=client,
+            api_url=self.api_url,
+            sandbox_id=data["id"],
+            api_key=self.api_key,
+            config=cfg,
+        )
+    
+    async def close(self) -> None:
+        """Close the HTTP client."""
+        if self._client:
+            await self._client.aclose()
+            self._client = None
+
+
+__all__ = ["RemoteSandbox", "RemoteSandboxProvider"]

aury/agents/sandbox/types.py

@@ -0,0 +1,115 @@
+"""Sandbox types and protocols."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal, Protocol, runtime_checkable
+
+
+@dataclass
+class ExecutionResult:
+    """Result of command execution in sandbox."""
+    exit_code: int
+    stdout: str
+    stderr: str
+    duration_ms: int
+    timed_out: bool = False
+    
+    @property
+    def success(self) -> bool:
+        return self.exit_code == 0 and not self.timed_out
+    
+    @property
+    def output(self) -> str:
+        """Combined output for display."""
+        if self.success:
+            return self.stdout
+        return f"{self.stdout}\n{self.stderr}".strip()
+
+
+@dataclass
+class SandboxConfig:
+    """Configuration for sandbox creation."""
+    image: str = "python:3.11-slim"
+    timeout: int = 300  # seconds
+    memory_limit: str = "512m"
+    cpu_limit: float = 1.0
+    network: bool = False
+    volumes: dict[str, str] = field(default_factory=dict)
+    env: dict[str, str] = field(default_factory=dict)
+    workdir: str = "/workspace"
+
+
+@runtime_checkable
+class Sandbox(Protocol):
+    """Protocol for sandbox instances.
+    
+    A sandbox provides an isolated environment for executing
+    commands and managing files safely.
+    """
+    
+    @property
+    def id(self) -> str:
+        """Unique sandbox identifier."""
+        ...
+    
+    @property
+    def status(self) -> Literal["creating", "running", "stopped", "failed"]:
+        """Current sandbox status."""
+        ...
+    
+    async def execute(
+        self,
+        command: str | list[str],
+        *,
+        timeout: int | None = None,
+        stdin: str | None = None,
+        env: dict[str, str] | None = None,
+        workdir: str | None = None,
+    ) -> ExecutionResult:
+        """Execute a command in the sandbox."""
+        ...
+    
+    async def write_file(self, path: str, content: str | bytes) -> None:
+        """Write a file to the sandbox."""
+        ...
+    
+    async def read_file(self, path: str) -> bytes:
+        """Read a file from the sandbox."""
+        ...
+    
+    async def upload(self, local_path: Path, remote_path: str) -> None:
+        """Upload a file or directory to the sandbox."""
+        ...
+    
+    async def download(self, remote_path: str, local_path: Path) -> None:
+        """Download a file or directory from the sandbox."""
+        ...
+    
+    async def stop(self) -> None:
+        """Stop the sandbox (can be restarted)."""
+        ...
+    
+    async def destroy(self) -> None:
+        """Destroy the sandbox permanently."""
+        ...
+
+
+@runtime_checkable
+class SandboxProvider(Protocol):
+    """Protocol for sandbox providers.
+    
+    Creates and manages sandbox instances.
+    """
+    
+    async def create(self, config: SandboxConfig | None = None) -> Sandbox:
+        """Create a new sandbox instance."""
+        ...
+
+
+__all__ = [
+    "ExecutionResult",
+    "SandboxConfig",
+    "Sandbox",
+    "SandboxProvider",
+]

aury/agents/skill/__init__.py

@@ -0,0 +1,16 @@
+"""Skill module for agent capabilities.
+
+Skills are reusable capability bundles that can be loaded and injected
+into agent context. Each skill contains instructions, scripts, and references.
+
+Usage:
+    Use SkillProvider (from providers module) to inject skills into agent context.
+"""
+from .types import Skill
+from .loader import SkillLoader
+
+
+__all__ = [
+    "Skill",
+    "SkillLoader",
+]