Add Python host SDK

.gitignore

@@ -13,6 +13,14 @@ index.d.ts
 # npm pack tarballs
 *.tgz
 
+# Python
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+python/**/*.so
+
 # Compiled binaries
 guest-examples/hello-c
 guest-examples/hello-cpp

Cargo.toml

@@ -14,9 +14,14 @@ libc = "0.2.178"
 napi = { version = "3.5.0", optional = true, features = ["async", "serde-json"] }
 napi-derive = { version = "3.3.0", optional = true }
 
+# Python bindings (optional)
+pyo3 = { version = "0.20", optional = true, features = ["extension-module", "abi3-py38"] }
+pyo3-asyncio = { version = "0.20", optional = true, features = ["tokio-runtime"] }
+
 [features]
 default = []
 napi = ["dep:napi", "dep:napi-derive", "dep:napi-build"]
+python = ["dep:pyo3", "dep:pyo3-asyncio"]
 
 [lib]
 crate-type = ["cdylib", "rlib"]

README.md

@@ -28,6 +28,29 @@ npm run build
 node examples/napi.js
 ```
 
+### Python
+
+
+> **Setup (one-time):**
+> ```bash
+> pipx install maturin # to install, see: https://pipx.pypa.io/stable/
+>
+> pipx ensurepath  # adds ~/.local/bin to PATH
+>
+> # Restart your terminal or run: export PATH="$HOME/.local/bin:$PATH"
+> ```
+
+Run from Python:
+```bash
+# Create and activate venv
+python3 -m venv .venv
+source .venv/bin/activate
+
+# Build the Rust extension and install it in venv then run example
+maturin develop --features python
+python examples/python_sdk_example.py
+```
+
 ### C & C++ Programs
 
 For compiled languages, you'll need to compile first, then run.
@@ -120,6 +143,26 @@ if (result.success) {
 }
 ```
 
+### Python
+
+```python
+import asyncio
+from hyperlight_nanvix import NanvixSandbox, SandboxConfig
+
+async def main():
+    config = SandboxConfig(
+        log_directory="/tmp/hyperlight-nanvix",
+        tmp_directory="/tmp/hyperlight-nanvix"
+    )
+    sandbox = NanvixSandbox(config)
+
+    result = await sandbox.run('guest-examples/hello.js')
+    if result.success:
+        print('Execution completed')
+
+asyncio.run(main())
+```
+
 To embed in your own project:
 
 ```bash

examples/python_sdk_example.py

@@ -0,0 +1,20 @@
+import asyncio
+from hyperlight_nanvix import NanvixSandbox
+
+async def main():
+    print("Running guest-examples/hello.js...")
+
+    try:
+        sandbox = NanvixSandbox()
+        result = await sandbox.run("guest-examples/hello.js")
+
+        if result.success:
+            print("Workload completed successfully!")
+        else:
+            print(f"Error: {result.error}")
+            exit(1)
+    except Exception as error:
+        print(f"Error: {error}")
+        exit(1)
+
+asyncio.run(main())

pyproject.toml

@@ -0,0 +1,13 @@
+[build-system]
+requires = ["maturin>=1.0,<2.0"]
+build-backend = "maturin"
+
+[project]
+name = "hyperlight-nanvix"
+version = "0.1.0"
+requires-python = ">=3.8"
+
+[tool.maturin]
+features = ["python"]
+module-name = "hyperlight_nanvix.hyperlight_nanvix"
+python-source = "python"

python/hyperlight_nanvix/__init__.py

@@ -0,0 +1,12 @@
+"""
+hyperlight-nanvix: Python bindings for running sandboxed workloads
+
+This module provides a Python interface to the Nanvix microkernel-based
+sandbox system, allowing you to run JavaScript, Python, C, and C++
+workloads in isolated environments.
+"""
+
+from .hyperlight_nanvix import NanvixSandbox, SandboxConfig, WorkloadResult
+
+__version__ = "0.1.0"
+__all__ = ["NanvixSandbox", "SandboxConfig", "WorkloadResult"]

python/hyperlight_nanvix/__init__.pyi

@@ -0,0 +1,17 @@
+from typing import Optional
+
+class SandboxConfig:
+    log_directory: Optional[str]
+    tmp_directory: Optional[str]
+    def __init__(self, log_directory: Optional[str] = None, tmp_directory: Optional[str] = None) -> None: ...
+
+class WorkloadResult:
+    success: bool
+    error: Optional[str]
+
+class NanvixSandbox:
+    def __init__(self, config: Optional[SandboxConfig] = None) -> None: ...
+    async def run(self, workload_path: str) -> WorkloadResult: ...
+    async def clear_cache(self) -> bool: ...
+
+__all__ = ["NanvixSandbox", "SandboxConfig", "WorkloadResult"]