Merge pull request #103 from A3S-Lab/feat/e2b-sdks

feat(sdk): add Python and TypeScript E2B clients

Author: ZhiXiao-Lin

.github/workflows/ci.yml

@@ -111,10 +111,39 @@ jobs:
           python3 compat/e2b/fixtures/official-clients/run_fixtures.py verify
           --rust-server-bin src/target/debug/a3s-box-e2b-fixture-server
 
+  # ── Native Python and TypeScript SDK package gate ─────────────
+  sdk-packages:
+    name: SDK Packages
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: sdk/typescript/package-lock.json
+      - name: Build and test Python package
+        run: |
+          python -m pip install build
+          python -m build sdk/python
+          python -m venv /tmp/a3s-box-python-sdk
+          /tmp/a3s-box-python-sdk/bin/pip install sdk/python/dist/*.whl
+          /tmp/a3s-box-python-sdk/bin/python -m unittest discover -s sdk/python/tests
+      - name: Build and test TypeScript package
+        working-directory: sdk/typescript
+        run: |
+          npm ci
+          npm run build
+          npm test
+          npm pack --dry-run
+
   # ── Build check (compile only, no artifacts) ────────────────────
   build-check:
     name: Build Check (${{ matrix.target }})
-    needs: [fmt, clippy, test, e2b-contract, e2b-official-clients]
+    needs: [fmt, clippy, test, e2b-contract, e2b-official-clients, sdk-packages]
     strategy:
       matrix:
         include:
@@ -160,7 +189,7 @@ jobs:
   # ── Windows native WHPX build check ────────────────────────────
   build-windows:
     name: Build Windows WHPX
-    needs: [fmt, clippy, test, e2b-contract, e2b-official-clients]
+    needs: [fmt, clippy, test, e2b-contract, e2b-official-clients, sdk-packages]
     runs-on: windows-latest
     steps:
       - uses: actions/checkout@v5
@@ -202,7 +231,7 @@ jobs:
   # Until both are done this job is SKIPPED (inert) and never blocks a PR.
   integration-kvm:
     name: Integration (real microVM, KVM)
-    needs: [fmt, clippy, test, e2b-contract, e2b-official-clients]
+    needs: [fmt, clippy, test, e2b-contract, e2b-official-clients, sdk-packages]
     if: vars.KVM_CI == 'true'
     runs-on: [self-hosted, linux, kvm]
     timeout-minutes: 75

.github/workflows/release.yml

@@ -37,6 +37,41 @@ jobs:
           workspaces: src
       - run: cd src && cargo test --workspace --lib
 
+  # ── Build native SDK release assets ───────────────────────────
+  sdk:
+    name: Build SDK packages
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - uses: actions/setup-node@v7
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: sdk/typescript/package-lock.json
+      - name: Build and verify Python package
+        run: |
+          mkdir -p sdk-artifacts
+          python -m pip install build
+          python -m build sdk/python --outdir "$GITHUB_WORKSPACE/sdk-artifacts"
+          python -m venv /tmp/a3s-box-python-sdk
+          /tmp/a3s-box-python-sdk/bin/pip install sdk-artifacts/*.whl
+          /tmp/a3s-box-python-sdk/bin/python -m unittest discover -s sdk/python/tests
+      - name: Build and verify TypeScript package
+        working-directory: sdk/typescript
+        run: |
+          npm ci
+          npm run build
+          npm test
+          npm pack --pack-destination "$GITHUB_WORKSPACE/sdk-artifacts"
+      - uses: actions/upload-artifact@v6
+        with:
+          name: sdk-packages
+          path: sdk-artifacts/*
+
   # ── Build matrix ───────────────────────────────────────────────
   build:
     name: Build (${{ matrix.target }})
@@ -171,7 +206,7 @@ jobs:
   # ── Create GitHub Release ──────────────────────────────────────
   release:
     name: GitHub Release
-    needs: build
+    needs: [build, sdk]
     runs-on: ubuntu-latest
     steps:
       - uses: actions/download-artifact@v7
@@ -188,6 +223,8 @@ jobs:
           generate_release_notes: true
           files: |
             artifacts/**/*.tar.gz
+            artifacts/**/*.whl
+            artifacts/**/*.tgz
 
   # ── Publish to crates.io ───────────────────────────────────────
   publish-crates:

sdk/python/README.md

@@ -0,0 +1,27 @@
+# A3S Box Python SDK
+
+`a3s-box` is a typed convenience package around the checksum-pinned official
+E2B Python clients used by A3S Box compatibility tests. It re-exports the
+official `e2b` 2.32.0 API instead of maintaining a fork, so existing E2B code
+can keep the same classes and method signatures.
+
+```python
+from a3s_box import A3SConnectionConfig, Sandbox
+
+connection = A3SConnectionConfig.from_environment()
+
+with Sandbox.create(
+    "code-interpreter-v1",
+    **connection.python_options(),
+) as sandbox:
+    result = sandbox.commands.run("python -c 'print(6 * 7)'")
+    print(result.stdout)
+```
+
+The synchronous and asynchronous Code Interpreter exports are available from
+`a3s_box.code_interpreter`.
+
+`A3SConnectionConfig` reads `E2B_API_URL`, `E2B_DOMAIN`, and `E2B_API_KEY`
+without changing process-global environment variables. The A3S endpoint still
+decides the execution template and isolation policy; the SDK never invokes a
+local runtime.

sdk/python/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=77,<81"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "a3s-box"
+version = "0.1.0"
+description = "Typed Python convenience package for the A3S Box E2B-compatible endpoint"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [{ name = "A3S Lab" }]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Typing :: Typed",
+]
+dependencies = [
+  "e2b==2.32.0",
+  "e2b-code-interpreter==2.8.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/A3S-Lab/Box"
+Repository = "https://github.com/A3S-Lab/Box"
+Issues = "https://github.com/A3S-Lab/Box/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+a3s_box = ["py.typed"]

sdk/python/src/a3s_box/__init__.py

@@ -0,0 +1,8 @@
+"""A3S Box SDK with the official E2B Python surface re-exported unchanged."""
+
+from e2b import *  # noqa: F403
+from e2b import __all__ as _e2b_all
+
+from .connection import A3SConnectionConfig
+
+__all__ = [*_e2b_all, "A3SConnectionConfig"]

sdk/python/src/a3s_box/code_interpreter.py

@@ -0,0 +1,3 @@
+"""Official E2B Code Interpreter exports configured for A3S endpoints."""
+
+from e2b_code_interpreter import *  # noqa: F401,F403

sdk/python/src/a3s_box/connection.py

@@ -0,0 +1,52 @@
+"""Typed A3S endpoint configuration helpers."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Mapping
+
+
+@dataclass(frozen=True, slots=True)
+class A3SConnectionConfig:
+    """Connection values accepted by the pinned official E2B Python SDK."""
+
+    api_url: str
+    domain: str
+    api_key: str | None = None
+
+    def __post_init__(self) -> None:
+        if not self.api_url.strip():
+            raise ValueError("api_url cannot be empty")
+        if not self.domain.strip():
+            raise ValueError("domain cannot be empty")
+        if self.api_key is not None and not self.api_key.strip():
+            raise ValueError("api_key cannot be empty when provided")
+
+    @classmethod
+    def from_environment(
+        cls,
+        environment: Mapping[str, str] | None = None,
+    ) -> A3SConnectionConfig:
+        """Read standard E2B endpoint variables without mutating the process."""
+
+        values = os.environ if environment is None else environment
+        api_url = values.get("E2B_API_URL")
+        domain = values.get("E2B_DOMAIN")
+        if not api_url:
+            raise ValueError("E2B_API_URL is required")
+        if not domain:
+            raise ValueError("E2B_DOMAIN is required")
+        return cls(
+            api_url=api_url,
+            domain=domain,
+            api_key=values.get("E2B_API_KEY"),
+        )
+
+    def python_options(self) -> dict[str, str]:
+        """Return keyword arguments for Python Sandbox create/connect calls."""
+
+        options = {"api_url": self.api_url, "domain": self.domain}
+        if self.api_key is not None:
+            options["api_key"] = self.api_key
+        return options

sdk/python/src/a3s_box/py.typed

@@ -0,0 +1 @@
+

sdk/python/tests/test_sdk.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import unittest
+
+import e2b
+import e2b_code_interpreter
+
+import a3s_box
+from a3s_box import A3SConnectionConfig
+from a3s_box import code_interpreter
+
+
+class SdkTests(unittest.TestCase):
+    def test_reexports_pinned_official_clients(self) -> None:
+        self.assertIs(a3s_box.Sandbox, e2b.Sandbox)
+        self.assertIs(a3s_box.AsyncSandbox, e2b.AsyncSandbox)
+        self.assertIs(code_interpreter.Sandbox, e2b_code_interpreter.Sandbox)
+        self.assertIs(
+            code_interpreter.AsyncSandbox,
+            e2b_code_interpreter.AsyncSandbox,
+        )
+
+    def test_connection_options_use_standard_e2b_names(self) -> None:
+        connection = A3SConnectionConfig.from_environment(
+            {
+                "E2B_API_URL": "https://api.box.example.com",
+                "E2B_DOMAIN": "box.example.com",
+                "E2B_API_KEY": "e2b_a1b2c3",
+            }
+        )
+        self.assertEqual(
+            connection.python_options(),
+            {
+                "api_url": "https://api.box.example.com",
+                "domain": "box.example.com",
+                "api_key": "e2b_a1b2c3",
+            },
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

sdk/typescript/README.md

@@ -0,0 +1,26 @@
+# A3S Box TypeScript SDK
+
+`@a3s-lab/box` re-exports the official `e2b` 2.33.0 TypeScript API and the
+pinned `@e2b/code-interpreter` 2.6.1 package. It does not fork or translate the
+public protocol.
+
+```typescript
+import { A3SConnectionConfig, Sandbox } from '@a3s-lab/box'
+
+const connection = A3SConnectionConfig.fromEnvironment(process.env)
+const sandbox = await Sandbox.create('code-interpreter-v1', {
+  ...connection.typescriptOptions(),
+  timeoutMs: 60_000,
+})
+
+try {
+  const result = await sandbox.commands.run('node -e "console.log(6 * 7)"')
+  console.log(result.stdout)
+} finally {
+  await sandbox.kill()
+}
+```
+
+Code Interpreter exports are available from `@a3s-lab/box/code-interpreter`.
+The A3S service owns template and isolation selection; this package never
+starts a local container or runtime.