ap-sandbox 0.1.2__tar.gz

ap_sandbox-0.1.2/.gitignore

@@ -0,0 +1,5 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+dist/

ap_sandbox-0.1.2/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: ap-sandbox
+Version: 0.1.2
+Summary: A Client for Agent Platform Sandbox.
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: e2b-code-interpreter>=2.4.1
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+A Client for Agent Platform Sandbox.

ap_sandbox-0.1.2/ap_sandbox/__init__.py

@@ -0,0 +1,14 @@
+"""ap-sandbox — E2B sandbox lifecycle management for ACS environments."""
+
+from ap_sandbox.config import SandboxConfig
+from ap_sandbox.errors import SandboxError, SandboxErrorCode
+from ap_sandbox.manager import SandboxManager
+
+__all__ = [
+    "SandboxManager",
+    "SandboxConfig",
+    "SandboxError",
+    "SandboxErrorCode",
+]
+
+__version__ = "0.1.1"

ap_sandbox-0.1.2/ap_sandbox/client.py

@@ -0,0 +1,180 @@
+"""E2B SDK wrapper for ap-sandbox.
+
+All SDK interactions are funnelled through this module so that the rest
+of the package never touches ``e2b`` directly.  Every public function
+accepts a ``SandboxConfig`` and raises ``SandboxError`` on failure.
+"""
+
+from __future__ import annotations
+
+import logging
+import uuid
+from typing import Any
+
+from e2b_code_interpreter import Sandbox
+
+from ap_sandbox.config import SandboxConfig
+from ap_sandbox.errors import SandboxError, SandboxErrorCode
+
+logger = logging.getLogger("ap_sandbox.client")
+
+
+def make_request_id(biz_id: str) -> str:
+    """Generate a unique request ID with *biz_id* as prefix.
+
+    Format: ``{biz_id}-{8-char-hex}``
+    """
+    return f"{biz_id}-{uuid.uuid4().hex[:8]}"
+
+
+def _classify_and_raise(
+    action: str, error: Exception, default_code: SandboxErrorCode
+) -> None:
+    """Inspect *error* and raise a ``SandboxError`` with the best-fit code."""
+    message = str(error)
+    lowered = message.lower()
+
+    if ("api" in lowered and "key" in lowered) or "unauthor" in lowered:
+        raise SandboxError(
+            SandboxErrorCode.AUTH_FAILED,
+            f"Failed to {action}: credentials rejected. Check E2B_API_KEY. "
+            f"Original: {message}",
+            cause=error,
+        ) from error
+
+    if "template" in lowered and (
+        "not found" in lowered or "unknown" in lowered
+    ):
+        raise SandboxError(
+            SandboxErrorCode.TEMPLATE_NOT_FOUND,
+            f"Failed to {action}: template not found. Check SANDBOX_TEMPLATE. "
+            f"Original: {message}",
+            cause=error,
+        ) from error
+
+    if "quota" in lowered or "limit" in lowered:
+        raise SandboxError(
+            SandboxErrorCode.QUOTA_EXCEEDED,
+            f"Failed to {action}: quota exceeded. Original: {message}",
+            cause=error,
+        ) from error
+
+    raise SandboxError(
+        default_code,
+        f"Failed to {action}: {message}",
+        cause=error,
+    ) from error
+
+
+def _build_request_headers(config: SandboxConfig) -> dict[str, str]:
+    """Build X-Request-ID header from config for API-layer calls."""
+    if config.ap_sandbox_metadata and "ap-job-id" in config.ap_sandbox_metadata:
+        biz_id = config.ap_sandbox_metadata["ap-job-id"]
+    else:
+        biz_id = config.sandbox_template
+    return {"X-Request-ID": make_request_id(biz_id)}
+
+
+def build_metadata(config: SandboxConfig) -> dict[str, str]:
+    """Build sandbox metadata by merging defaults with user-supplied extras."""
+    metadata = {
+        "e2b.agents.kruise.io/skip-init-runtime": "true",
+        "e2b.agents.kruise.io/create-on-no-stock": "true",
+        "e2b.agents.kruise.io/claim-timeout-seconds": str(
+            config.sandbox_create_timeout
+        ),
+        "e2b.agents.kruise.io/wait-ready-timeout-seconds": str(
+            config.wait_ready_timeout_sec
+        ),
+        "e2b.agents.kruise.io/reserve-failed-sandbox-for": config.reserve_failed_sandbox_for,
+        "e2b.agents.kruise.io/return-sandbox-ip": "true",
+    }
+    if config.ap_sandbox_metadata:
+        metadata.update(config.ap_sandbox_metadata)
+    return metadata
+
+
+def create_sandbox(config: SandboxConfig, **kwargs: Any) -> Sandbox:
+    """Create and return an E2B ``Sandbox`` instance.
+
+    Extra *kwargs* are forwarded directly to ``Sandbox.create()``, allowing
+    callers to customise parameters such as ``envs``, ``secure``,
+    ``network``, ``lifecycle``, etc.
+
+    The ``metadata`` key is treated specially: caller-supplied metadata is
+    **merged** into the built-in metadata (caller values win on conflict).
+    All other *kwargs* fully override the corresponding defaults.
+    """
+    try:
+        config.validate_required()
+    except ValueError as value_error:
+        raise SandboxError(
+            SandboxErrorCode.CONFIG_MISSING,
+            str(value_error),
+            cause=value_error,
+        ) from value_error
+
+    metadata = build_metadata(config)
+    # Merge caller-supplied metadata into built-in metadata (caller wins)
+    if "metadata" in kwargs:
+        metadata.update(kwargs.pop("metadata"))
+
+    # Build X-Request-ID header for tracing
+    headers = _build_request_headers(config)
+    # Merge caller-supplied headers (caller wins)
+    if "headers" in kwargs:
+        headers.update(kwargs.pop("headers"))
+
+    create_params: dict[str, Any] = {
+        "template": config.sandbox_template,
+        "timeout": config.sandbox_timeout_sec,
+        "metadata": metadata,
+        "domain": config.e2b_domain,
+        "api_key": config.e2b_api_key,
+        "request_timeout": config.sandbox_create_timeout,
+        "headers": headers,
+    }
+    # Remaining kwargs override defaults
+    create_params.update(kwargs)
+
+    try:
+        return Sandbox.create(**create_params)
+    except Exception as error:
+        _classify_and_raise("create sandbox", error, SandboxErrorCode.CREATE_FAILED)
+
+
+def kill_sandbox(sandbox: Any, config: SandboxConfig | None = None) -> None:
+    """Kill a running sandbox instance.
+
+    If *config* is provided, an ``X-Request-ID`` header is injected for
+    API-layer tracing.
+    """
+    opts: dict[str, Any] = {}
+    if config is not None:
+        opts["headers"] = _build_request_headers(config)
+
+    try:
+        sandbox.kill(**opts)
+    except AttributeError as attribute_error:
+        raise SandboxError(
+            SandboxErrorCode.KILL_FAILED,
+            "Sandbox object has no kill() method",
+            cause=attribute_error,
+        ) from attribute_error
+    except Exception as error:
+        _classify_and_raise("kill sandbox", error, SandboxErrorCode.KILL_FAILED)
+
+
+def get_sandbox_ip(sandbox: Any, config: SandboxConfig | None = None) -> str:
+    """Query the sandbox for its VM IP address.
+
+    If *config* is provided, an ``X-Request-ID`` header is injected for
+    API-layer tracing.
+    """
+    opts: dict[str, Any] = {}
+    if config is not None:
+        opts["headers"] = _build_request_headers(config)
+
+    info = sandbox.get_info(**opts)
+    metadata = info.metadata or {}
+    return metadata.get("e2b.agents.kruise.io/sandbox-ip", "")

ap_sandbox-0.1.2/ap_sandbox/config.py

@@ -0,0 +1,100 @@
+"""Pydantic-based configuration for ap-sandbox.
+
+All sandbox settings are loaded from environment variables with sensible
+defaults.  Aliases are supported so that both legacy names
+(``E2B_DOMAIN``) and new names (``AP_SANDBOX_PROVIDER_ENDPOINT``) work.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+from pydantic import model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class SandboxConfig(BaseSettings):
+    """Sandbox configuration backed by environment variables."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="",
+        case_sensitive=False,
+    )
+
+    # --- E2B / ACS connection ---
+    e2b_domain: str = ""
+    e2b_api_key: str = ""
+
+    # --- Sandbox template & lifecycle ---
+    sandbox_template: str = ""
+    sandbox_timeout_sec: int = 3600
+    wait_ready_timeout_sec: int = 120
+    reserve_failed_sandbox_for: str = "never"
+
+    @property
+    def sandbox_create_timeout(self) -> int:
+        """Request timeout for the sandbox create API call (seconds)."""
+        return self.wait_ready_timeout_sec + 15
+
+    # --- Optional extra metadata (JSON string from env) ---
+    ap_sandbox_metadata: dict[str, str] | None = None
+
+    # ------------------------------------------------------------------
+    # Alias support: legacy env vars mapped to canonical fields
+    # ------------------------------------------------------------------
+    @model_validator(mode="before")
+    @classmethod
+    def apply_aliases(cls, values: dict[str, Any]) -> dict[str, Any]:
+        """Map alternative environment variable names to canonical fields."""
+        alias_map: dict[str, list[str]] = {
+            "e2b_domain": ["AP_SANDBOX_PROVIDER_ENDPOINT"],
+            "e2b_api_key": ["AP_SANDBOX_PROVIDER_CREDENTIAL"],
+            "sandbox_template": ["SANDBOX_TEMPLATE", "SANDBOX_TEMPLATE_ID"],
+            "sandbox_timeout_sec": ["SANDBOX_TIMEOUT_SEC"],
+            "wait_ready_timeout_sec": ["SANDBOX_READY_TIMEOUT_SEC"],
+            "reserve_failed_sandbox_for": ["SANDBOX_RESERVE_FAILED_FOR"],
+        }
+        for canonical, aliases in alias_map.items():
+            if values.get(canonical):
+                continue
+            for alias in aliases:
+                env_value = os.environ.get(alias, "")
+                if env_value:
+                    values[canonical] = env_value
+                    break
+
+        # Parse AP_SANDBOX_METADATA from JSON string
+        raw_metadata = values.get("ap_sandbox_metadata") or values.get(
+            "AP_SANDBOX_METADATA"
+        )
+        if isinstance(raw_metadata, str):
+            try:
+                parsed = json.loads(raw_metadata)
+                if isinstance(parsed, dict):
+                    values["ap_sandbox_metadata"] = parsed
+                else:
+                    values["ap_sandbox_metadata"] = None
+            except (json.JSONDecodeError, TypeError):
+                values["ap_sandbox_metadata"] = None
+        elif raw_metadata is not None and not isinstance(raw_metadata, dict):
+            # pydantic-settings may have already parsed JSON into a non-dict type
+            values["ap_sandbox_metadata"] = None
+
+        return values
+
+    def validate_required(self) -> None:
+        """Raise ``ValueError`` if critical fields are empty."""
+        missing: list[str] = []
+        if not self.e2b_domain:
+            missing.append("E2B_DOMAIN / AP_SANDBOX_PROVIDER_ENDPOINT")
+        if not self.e2b_api_key:
+            missing.append("E2B_API_KEY / AP_SANDBOX_PROVIDER_CREDENTIAL")
+        if not self.sandbox_template:
+            missing.append("SANDBOX_TEMPLATE / SANDBOX_TEMPLATE_ID")
+        if missing:
+            raise ValueError(
+                f"Missing required sandbox configuration: {', '.join(missing)}. "
+                "Set these environment variables before creating a sandbox."
+            )

ap_sandbox-0.1.2/ap_sandbox/errors.py

@@ -0,0 +1,41 @@
+"""Unified error codes and exception hierarchy for ap-sandbox."""
+
+from __future__ import annotations
+
+from enum import IntEnum
+
+
+class SandboxErrorCode(IntEnum):
+    """Numeric error codes for programmatic branching."""
+
+    UNKNOWN = 1000
+    CONFIG_MISSING = 1001
+    AUTH_FAILED = 1002
+    TEMPLATE_NOT_FOUND = 1003
+    QUOTA_EXCEEDED = 1004
+    CREATE_FAILED = 1005
+    CONNECT_FAILED = 1006
+    KILL_FAILED = 1007
+    IP_QUERY_FAILED = 1008
+    TIMEOUT = 1009
+
+
+class SandboxError(Exception):
+    """Base exception for all sandbox operations.
+
+    Attributes:
+        code: A ``SandboxErrorCode`` identifying the failure category.
+        message: Human-readable description of what went wrong.
+        cause: Optional underlying exception that triggered this error.
+    """
+
+    def __init__(
+        self,
+        code: SandboxErrorCode,
+        message: str,
+        cause: Exception | None = None,
+    ) -> None:
+        self.code = code
+        self.message = message
+        self.cause = cause
+        super().__init__(f"[{code.name}({code.value})] {message}")

ap_sandbox-0.1.2/ap_sandbox/manager.py

@@ -0,0 +1,166 @@
+"""SandboxManager — the primary public interface for ap-sandbox.
+
+Lifecycle management with signal handling, context-manager support,
+and ``atexit`` safety net.
+"""
+
+from __future__ import annotations
+
+import atexit
+import logging
+import signal
+from types import FrameType
+from typing import Any
+from e2b_code_interpreter import Sandbox
+
+from ap_sandbox.client import create_sandbox, get_sandbox_ip, kill_sandbox
+from ap_sandbox.config import SandboxConfig
+from ap_sandbox.errors import SandboxError, SandboxErrorCode
+
+logger = logging.getLogger("ap_sandbox.manager")
+
+
+class SandboxManager:
+    """Create, use, and automatically clean up E2B sandboxes.
+
+    Features:
+    - **Signal handling**: ``SIGINT`` / ``SIGTERM`` trigger automatic cleanup.
+    - **Context manager**: ``with SandboxManager() as mgr: ...``
+    - **atexit**: registered as a last-resort cleanup.
+
+    Example::
+
+        from ap_sandbox import SandboxManager
+
+        with SandboxManager() as mgr:
+            mgr.create()
+            print(mgr.sandbox_ip)
+    """
+
+    def __init__(self, config: SandboxConfig | None = None) -> None:
+        self.config = config or SandboxConfig()
+        self._sandbox: Sandbox | None = None
+        self._sandbox_ip: str | None = None
+
+        self._prev_sigint: Any = None
+        self._prev_sigterm: Any = None
+        self._killed = False
+
+        self._install_signal_handlers()
+        atexit.register(self.kill)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def create(self, **kwargs: Any) -> "SandboxManager":
+        """Create a sandbox and query its Sandbox IP.  Returns *self* for chaining.
+
+        Extra *kwargs* are forwarded to ``Sandbox.create()``.  This allows
+        callers to pass E2B-supported parameters like ``envs``, ``secure``,
+        ``network``, ``lifecycle``, ``volume_mounts``, etc.
+
+        Example::
+
+            mgr.create(envs={"MY_VAR": "value"}, secure=False)
+        """
+        self._sandbox = create_sandbox(self.config, **kwargs)
+        sandbox_id = self._get_sandbox_id()
+        logger.info("Sandbox %s created", sandbox_id)
+
+        self._sandbox_ip = get_sandbox_ip(self._sandbox, self.config)
+        logger.info("Sandbox %s IP: %s", sandbox_id, self._sandbox_ip)
+        return self
+
+    def kill(self) -> None:
+        """Idempotently destroy the sandbox and clean up internal state."""
+        if self._killed or self._sandbox is None:
+            return
+        sandbox_id = self._get_sandbox_id()
+        try:
+            kill_sandbox(self._sandbox, self.config)
+            logger.info("Sandbox %s killed", sandbox_id)
+        except Exception as error:
+            logger.error("Failed to kill sandbox %s: %s", sandbox_id, error)
+        finally:
+            self._sandbox = None
+            self._sandbox_ip = None
+            self._killed = True
+
+    @property
+    def sandbox(self) -> Sandbox | None:
+        """The underlying E2B sandbox object, or ``None`` if not created."""
+        return self._sandbox
+
+    @property
+    def sandbox_id(self) -> str | None:
+        """The sandbox ID string, or ``None`` if not created."""
+        if self._sandbox is None:
+            return None
+        return self._get_sandbox_id()
+    
+    @property
+    def sandbox_ip(self) -> str | None:
+        """The sandbox IP string, or ``None`` if not created."""
+        if self._sandbox is None:
+            return None
+        return self._sandbox_ip
+
+    # ------------------------------------------------------------------
+    # Context manager
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> "SandboxManager":
+        return self
+
+    def __exit__(self, *_exc: object) -> None:
+        self.kill()
+
+    # ------------------------------------------------------------------
+    # Signal handling
+    # ------------------------------------------------------------------
+
+    def _install_signal_handlers(self) -> None:
+        """Register ``SIGINT`` / ``SIGTERM`` handlers that clean up the sandbox."""
+        try:
+            self._prev_sigint = signal.getsignal(signal.SIGINT)
+            self._prev_sigterm = signal.getsignal(signal.SIGTERM)
+            signal.signal(signal.SIGINT, self._signal_handler)
+            signal.signal(signal.SIGTERM, self._signal_handler)
+        except (OSError, ValueError):
+            # Not on main thread or signals not supported — skip silently.
+            pass
+
+    def _signal_handler(self, signum: int, frame: FrameType | None) -> None:
+        logger.warning("Signal %s received, cleaning up sandbox", signum)
+        self.kill()
+        self._restore_signal_handlers()
+
+        if signum == signal.SIGINT:
+            if callable(self._prev_sigint):
+                self._prev_sigint(signum, frame)
+            raise KeyboardInterrupt
+        if callable(self._prev_sigterm):
+            self._prev_sigterm(signum, frame)
+        raise SystemExit(0)
+
+    def _restore_signal_handlers(self) -> None:
+        try:
+            if self._prev_sigint is not None:
+                signal.signal(signal.SIGINT, self._prev_sigint)
+            if self._prev_sigterm is not None:
+                signal.signal(signal.SIGTERM, self._prev_sigterm)
+        except (OSError, ValueError):
+            pass
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _get_sandbox_id(self) -> str:
+        sandbox_id = getattr(self._sandbox, "id", None) or getattr(
+            self._sandbox, "sandbox_id", None
+        )
+        if not sandbox_id:
+            return "<unknown>"
+        return str(sandbox_id)

ap_sandbox-0.1.2/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ap-sandbox"
+version = "0.1.2"
+description = "A Client for Agent Platform Sandbox."
+readme = { text = "A Client for Agent Platform Sandbox.", content-type = "text/markdown" }
+requires-python = ">=3.10"
+license = {text = "MIT"}
+dependencies = [
+    "e2b-code-interpreter>=2.4.1",
+    "pydantic>=2.0",
+    "pydantic-settings>=2.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "mypy>=1.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v --tb=short"
+
+[tool.hatch.build.targets.sdist]
+only-include = [
+    "/ap_sandbox",
+    "/pyproject.toml",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["ap_sandbox"]