solari-e2b-compat 0.1.0__tar.gz

solari_e2b_compat-0.1.0/.gitignore

@@ -0,0 +1,71 @@
+# build artifacts
+dist/
+**/dist/
+**/node_modules/
+**/target/
+*.log
+
+# VM images / snapshots / kernels — large binaries, never committed
+*.img
+*.ext4
+*.qcow2
+*.raw
+*.snapshot
+/snapshots/build/
+/guest/rootfs/build/
+/guest/kernel/build/
+vmlinux
+bzImage
+
+# terraform state
+*.tfstate
+*.tfstate.*
+.terraform/
+*.tfvars.local
+
+# secrets / env
+.env
+.env.*
+*.pem
+
+# Python
+__pycache__/
+*.pyc
+.venv/
+
+# NOTE: tests/sdk/ts-request-fixtures.json is deliberately NOT ignored.
+#
+# It was, and that quietly disabled two gates at once:
+#
+#  1. ci.yml's "Committed fixture must match what the SDK emits today" step runs
+#     `git diff --exit-code tests/sdk/ts-request-fixtures.json`. On an ignored,
+#     never-tracked file that command can only ever succeed — it had never once
+#     been able to fail.
+#  2. The Go/Rust/C++/Python contract suites now assert against that fixture from
+#     inside their OWN CI jobs, none of which run the TypeScript half. If the file
+#     is not committed, it is simply absent there.
+#
+# It is generated, but it is generated from the REFERENCE SDK and checked in as
+# the baseline the other four bindings are held to — regenerating it and diffing
+# is exactly how a wire change is made to announce itself.
+
+# Built guest-agent binaries (produced by go build / build-rootfs staging)
+guest/agent/agent
+guest/rootfs/guest-agent
+
+# build-rootfs.sh template staging + generated Dockerfile (regenerated each run)
+guest/rootfs/guest-agent.service
+guest/rootfs/template.packages
+guest/rootfs/template-files/
+guest/rootfs/.Dockerfile.gen
+guest/rootfs/out/
+
+# local test artifacts
+staging-desktop.png
+desktop.png
+infra/terraform/snapshots-volumes/.build/
+
+# deploy-e2e scratch state: holds a presigned REPO_URL with live STS creds
+# (ASIA... + X-Amz-Security-Token). Never commit. Also stale PHASE_* here makes
+# a bare re-run skip bake+verify and exit 0 with zero assertions.
+infra/.deploy-e2e/

solari_e2b_compat-0.1.0/COMPAT.md

@@ -0,0 +1,98 @@
+# COMPAT.md: E2B Python SDK compatibility (target: e2b 2.59 and e2b-code-interpreter 2.11)
+
+Legend: **OK** works and is tested; **DIFF** works with a behaviour difference (explained); **NO** raises
+`SolariCompatUnsupported` naming the feature. "Live" means `tests/test_live_staging.py` runs it against staging.
+The matrix is the same as the TypeScript package's (`sdk/packages/e2b-compat/COMPAT.md`); this file lists the Python names
+and the differences that are specific to Python.
+
+## At a glance
+- **Works**: sandbox create / connect / list / info / kill / timeout / pause / resume / metrics, snapshots and fork,
+  commands (foreground, background, stdin, list, kill), PTY, the filesystem API (read as text, bytes or stream; write one or
+  many; list with depth; info; exists; make_dir; rename; remove; watch_dir; signed upload and download URLs), the code
+  interpreter (`run_code` with state, callbacks, errors, bash, contexts, rich results), the template builder and
+  `Template.build`. Blocking (`Sandbox`) and async (`AsyncSandbox`) flavours.
+- **Not available** (raises): egress network rules, MCP gateway, IAM tokens, E2B Volumes and Secrets APIs, template tags,
+  `set_start_cmd` / `set_ready_cmd`, `set_user`, Dockerfile input, private registries, start-time and template filters on
+  `Sandbox.list`, `on_resume='reboot'`, JavaScript/TypeScript/R/Java in `run_code`.
+
+## Setup and configuration
+| E2B | Here |
+|---|---|
+| `E2B_API_KEY`, `api_key=` | Only `slr_…` keys are used; see README. |
+| `E2B_DOMAIN`, `E2B_API_URL`, `domain=`, `api_url=` | Honoured only when they point at Solari or loopback. |
+| `headers=`, `api_headers=`, `proxy=` | NO. |
+| `request_timeout=`, `debug=`, `logger=`, `validate_api_key=`, `retries=`, `http_version=`, `sandbox_url=` | Accepted, ignored (Solari's transport has its own retry policy). Every option that is accepted but ignored is marked "ignored" in this file; any other option either works or throws. |
+| `timeout=` arguments | Seconds, as in E2B. |
+| `E2B` client object, `Volume`, `Secret` | NO. `solari_e2b.Volume` / `Secret` raise on any call. |
+| Context manager | `with Sandbox.create() as s:` / `async with await AsyncSandbox.create() as s:` kill the sandbox on exit. |
+
+## Sandbox
+| Call | Status | Notes |
+|---|---|---|
+| `Sandbox.create(template, timeout, metadata, envs, lifecycle, volume_mounts, ...)` | OK, live | `template`: `base`, a name from `Template.build`, or a `tpl_…` id. Default `base` (`code-interpreter-v1` in `solari_e2b.code_interpreter`). |
+| `timeout` | DIFF | E2B's is a lifetime; Solari's is a rolling idle window that resets on use. Default 300 s as in E2B. The per-plan deadline still bounds total life. |
+| `lifecycle={'on_timeout': ..., 'auto_resume': ...}` | OK | `{'action': 'pause', 'mode': 'filesystem'}` pauses with RAM too (a superset). |
+| `volume_mounts={path: 'vol_…' or name}` | DIFF | Solari persistent volumes by id or name. `Volume` objects: NO. |
+| `secure`, `sandbox_url` | Accepted, ignored (sandboxes are always access-controlled). |
+| `allow_internet_access=False`, `network`, `iam`, `mcp` | NO. |
+| `Sandbox.connect(id, timeout)`, `sbx.connect()` | OK, live | Resumes a paused or stopped sandbox. `on_resume='reboot'`: NO. |
+| `Sandbox.list(query=SandboxQuery(...), limit, next_token, order)` | DIFF | Paginator with `has_next`, `next_token`, `next_items()`. Filters: `metadata`, `state`. `started_after` and `template`: NO. `template_id` in each `SandboxInfo` is empty. Solari `starting` counts as running, `stopped` as paused. |
+| `get_info`, `is_running`, `kill`, `set_timeout` | OK, live | Usable on the class with an id (`Sandbox.kill(id)`) or on an instance. `kill` returns `False` for a sandbox that is already gone. |
+| `get_metrics()` | DIFF | One current sample (no history); `mem_cache` is 0. |
+| `pause()` | OK, live | Keeps RAM and disk. `mode='filesystem'`, `keep_memory=False`: treated as a full pause. |
+| `create_snapshot(name=)`, `list_snapshots(...)`, `Sandbox.delete_snapshot(id)` | OK, live | Snapshots are RAM + disk. `mode='filesystem'` is ignored. A name lookup reads at most 1000 snapshots. `sbx.list_snapshots()` lists snapshots taken of that sandbox. Class-level listing over every sandbox is `Sandbox.list_all_snapshots(name=)` (extension). |
+| `fork(count=)` | DIFF, live | Checkpoint then `count` new sandboxes from it; the checkpoint is deleted afterwards (waiting at most 20 s for the gateway to finish the delete). Returns a sandbox or an exception per copy. |
+| `get_host(port)` | NO | E2B returns the host synchronously; Solari mints preview URLs on the gateway. Use the extension `sbx.get_preview_url(port)` (returns `{'url': ..., 'token': ...}`). |
+| `upload_url`, `download_url` | OK | `user=`: NO. |
+| `update_network`, `get_mcp_url`, `get_mcp_token` (returns `None`), `git` | NO | `git` is deprecated in E2B; use `commands.run('git …')`. |
+| Lifecycle events API, webhooks, OTel export, sandbox logs API | NO | |
+
+## Commands and PTY
+| Call | Status | Notes |
+|---|---|---|
+| `commands.run(cmd, ...)` | OK, live | Runs `bash -lc` (a POSIX `sh` on images without bash) from the home directory. A non-zero exit raises `CommandExitException` (`stdout`, `stderr`, `exit_code`, `error`). `timeout` default 60 s (0 disables) raises `TimeoutException`. `on_stdout` / `on_stderr` (sync or async callables), `envs`, `cwd`, `user`: OK. |
+| `commands.run(cmd, background=True)` | OK, live | Returns a command handle: `pid`, `stdout`, `stderr`, `exit_code`, `wait()`, `kill()`, `send_stdin()`, `disconnect()`. It is not iterable (E2B's handles are). |
+| `commands.list`, `kill(pid)`, `send_stdin(pid)`, `connect(pid)`, `stream_input(pid)` | DIFF | `pid` is a number this package hands out; Solari keeps the process on the control channel that started it. These work for commands started by **this process**; another process gets `NotFoundException`. |
+| `close_stdin` | NO | Solari cannot close a command's stdin. End the program another way (for example a sentinel line). |
+| `pty.create(PtySize(rows, cols), on_data)`, `send_stdin`, `resize`, `kill`, `stream_input` | OK, live | `connect(pid)`: this process only. `handle.wait()` resolves when `kill` is called; a shell that exits by itself is not observed. `user=`: NO. |
+
+## Filesystem
+| Call | Status | Notes |
+|---|---|---|
+| `read(path, format='text' \| 'bytes' \| 'stream')` | OK, live | Relative paths resolve against the guest's `$HOME`. `bytes` returns a `bytearray`. `stream` returns an async-iterable reader with one chunk (async API only; with the blocking API read with `format='bytes'`). A missing file raises `FileNotFoundException`. |
+| `write(path, data)`, `write_files(entries)` | OK, live | `str`, `bytes` or a file-like object. Parent directories are created. `metadata=`: NO. `gzip`, `use_octet_stream`: accepted, ignored. |
+| `list(path, depth)`, `get_info` | DIFF, live | `owner` and `group` are empty; `symlink_target` is not reported (symlinks are followed: a link lists as its target file). |
+| `exists`, `make_dir`, `rename`, `remove` | OK, live | |
+| `watch_dir(path, on_event, recursive=)` | DIFF, live | `FilesystemEvent.name` is relative to the watched path. Solari reports creates as `write`. `include_entry`: not offered. A watch ends after `timeout` seconds (default 60; 0 disables) and calls `on_exit(None)`. |
+| `user=` on any filesystem call | NO | |
+
+## Code interpreter (`solari_e2b.code_interpreter`)
+| Call | Status | Notes |
+|---|---|---|
+| `run_code(code, language=None, context=None, ...)` | OK, live | Python (and `bash`). Passing both `language` and `context` raises `InvalidArgumentException`. Python state persists across calls in the default context. |
+| Other languages | NO | The guest ships a Python kernel only: `javascript`, `typescript`, `r`, `java` raise. `bash` runs each call as a fresh shell (no state between calls). |
+| `on_stdout`, `on_stderr`, `on_result`, `on_error` | DIFF | Called after the run finishes, not while it runs (Solari returns the result in one reply). Sync or async callables. |
+| `Execution` (`results`, `logs`, `error`, `text`) | DIFF | `execution_count` is `None`. `error` is `ExecutionError(name, value, traceback)`. The last result with a text repr is `is_main_result`. |
+| `Result` formats | DIFF | `text`, `html`, `markdown`, `svg`, `png`, `jpeg`, `latex`, `json` (as given by the kernel), `chart`. `pdf`, `javascript`, `data` and `extra` are not produced. `chart` is a generic `Chart(type, title, elements, ...)` (not E2B's per-type classes) and appears when the guest kernel extracts a structured chart (not for every figure). |
+| `envs=` per run | NO | |
+| `timeout=` | DIFF | Stops waiting and raises `TimeoutException`; the kernel keeps running the code. No default timeout. |
+| `create_code_context(cwd, language)` | OK, live | Python only. |
+| `list_code_contexts`, `remove_code_context`, `restart_code_context` | DIFF, live | Solari cannot list or destroy kernels. `list` returns contexts created by this process; `remove` forgets the context (the kernel stays until the sandbox ends); `restart` clears the context's variables and working directory without restarting the process. |
+| Default template | DIFF | `code-interpreter-v1` is built into your org on first `Sandbox.create()` without a template: about 80 seconds, billed as a template build, and two processes that both find it missing each start a build. `build_code_interpreter_template()` (async) / `build_code_interpreter_template_sync()` prebuild it. |
+
+## Templates
+| Call | Status | Notes |
+|---|---|---|
+| `Template().from_base_image / from_image / from_python_image / from_node_image / from_ubuntu_image / from_debian_image / from_alpine_image / from_fedora_image / from_arch_image / from_bun_image / from_template` | OK, live | `from_base_image()` is Solari's base image. The others are public registry images. Credentials, `from_aws_registry`, `from_gcp_registry`, `from_dockerfile`: NO. |
+| `apt_install`, `pip_install`, `npm_install`, `bun_install`, `run_cmd`, `copy`, `copy_items`, `make_dir`, `remove`, `rename`, `make_symlink`, `git_clone`, `set_workdir`, `set_envs` | OK, live | Compiled onto Solari's image steps. `set_envs` persists in the template (E2B: build time only). `user=` other than `root`: NO. `copy` reads from `file_context_path` (default: the current directory). Quoting uses `shlex`, so simple words are not quoted. |
+| `set_user`, `set_start_cmd`, `set_ready_cmd`, `add_mcp_server`, dev containers | NO | Solari templates run no start command. Start processes after `Sandbox.create` with `commands.run(..., background=True)`. |
+| `skip_cache()` | Accepted, ignored. |
+| `Template.build(template, name)`, `build_in_background`, `get_build_status`, `exists`, `alias_exists` | OK, live | `name:latest` is accepted; any other tag, and `tags=`: NO. `on_build_logs` receives start and end entries. `Template.build` blocks (the `AsyncTemplate` twin is awaitable). |
+| `Template.assign_tags`, `remove_tags`, `get_tags`, `to_json`, `to_dockerfile` | NO | |
+
+## Python-specific differences
+- The Python SDK's `GET /sandboxes/:id` view drops the creation time and the native-image marker, so this package reads that
+  route directly. `SandboxInfo.started_at` is the creation time when the gateway reports it, else the epoch.
+- The blocking API runs the async client on one daemon thread. Calling it from one of your own callbacks (which run on that
+  thread) raises `RuntimeError`; use `AsyncSandbox` there.
+- Tested on Python 3.14; the code avoids syntax newer than 3.9 but only 3.14 is exercised here.

solari_e2b_compat-0.1.0/LICENSE-E2B

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025 FOUNDRYLABS, INC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

solari_e2b_compat-0.1.0/NOTICE

@@ -0,0 +1,13 @@
+solari-e2b-compat
+
+The public API shapes (class, method, option and exception names, and the result types) follow the `e2b` and
+`e2b-code-interpreter` Python SDKs (e2b 2.59, e2b-code-interpreter 2.11), which are distributed under the MIT
+licence:
+
+  Copyright (c) 2025 FOUNDRYLABS, INC.
+
+The licence text is reproduced in LICENSE-E2B. No E2B source code is bundled; the implementation is written against the
+Solari SDKs (solari-core, solari-sandbox).
+
+This package is not affiliated with, endorsed by, or sponsored by E2B or FOUNDRYLABS, INC. "E2B" is the name of their
+product; it appears here only to describe API compatibility.

solari_e2b_compat-0.1.0/PKG-INFO

@@ -0,0 +1,89 @@
+Metadata-Version: 2.5
+Name: solari-e2b-compat
+Version: 0.1.0
+Summary: E2B-compatible Python interface (sandboxes and code interpreter) over Solari Sandboxes. Not affiliated with E2B.
+Project-URL: Homepage, https://getsolari.com
+Author: Solari
+License: MIT
+License-File: LICENSE-E2B
+License-File: NOTICE
+Keywords: code-interpreter,compatibility,e2b,sandbox,solari
+Requires-Python: >=3.9
+Requires-Dist: solari-core>=0.4.0
+Requires-Dist: solari-sandbox>=0.3.0
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# solari-e2b-compat
+
+An E2B-compatible Python API on top of [Solari Sandbox](https://getsolari.com). Change the import, keep your sandbox code.
+
+> **Not affiliated with, endorsed by, or sponsored by E2B.** "E2B" is E2B's product name; it appears here only to
+> describe API compatibility. The API shapes follow the MIT-licensed `e2b` and `e2b-code-interpreter` SDKs, see
+> [NOTICE](./NOTICE). Do not look for this package under `e2b*`.
+
+```python
+# before: from e2b_code_interpreter import Sandbox
+from solari_e2b.code_interpreter import Sandbox
+
+sbx = Sandbox.create()                      # SOLARI_API_KEY in the environment
+execution = sbx.run_code("x = 1\nx + 1")
+print(execution.text)                       # "2"
+print(sbx.commands.run("echo hello").stdout)
+sbx.files.write("/tmp/a.txt", "hi")
+sbx.kill()
+```
+
+The plain `e2b` package maps to `solari_e2b`:
+
+```python
+# before: from e2b import Sandbox, AsyncSandbox, Template
+from solari_e2b import Sandbox, AsyncSandbox, Template
+```
+
+Exports: `Sandbox` (blocking) and `AsyncSandbox` (create, connect, list, kill, pause, snapshots, fork, `commands`, `files`,
+`pty`), `Template` / `AsyncTemplate` and the template builder, the E2B exception classes (`SandboxException`,
+`TimeoutException`, `NotFoundException`, `FileNotFoundException`, `CommandExitException`, `AuthenticationException`, ...),
+`SolariCompatUnsupported`, and from `solari_e2b.code_interpreter`: `Sandbox` / `AsyncSandbox` with `run_code` and code
+contexts, `Execution`, `Result`, `Context`.
+
+The blocking API runs the async client on one background thread; callbacks you pass (`on_stdout`, ...) run on that thread.
+Do not call the blocking API from inside such a callback; use `AsyncSandbox` there.
+
+## Configuration
+
+| | Order |
+|---|---|
+| API key | `api_key=` option, `SOLARI_API_KEY`, `E2B_API_KEY`: only an `slr_…` Solari key is ever used. A non-`slr_` value (for example a real E2B key) is skipped with a warning (the key is never printed or sent); with no Solari key the call raises |
+| Base URL | `api_url=` / `domain=` option (Solari or loopback only, anything else raises), `SOLARI_BASE_URL`, `E2B_API_URL` / `E2B_DOMAIN` (only if they point at getsolari.com or loopback; otherwise ignored with a warning), default `https://api.getsolari.com` |
+
+An E2B key does not work here: use a Solari API key.
+
+## The code-interpreter template
+
+`e2b_code_interpreter` runs in a template with a data-analysis stack (pandas, numpy, scipy, scikit-learn, seaborn,
+plotly, ...). Solari builds the equivalent, `code-interpreter-v1`, into your org the first time `Sandbox.create()` is
+called without a template (about 80 seconds, once). To do it ahead of time:
+
+```python
+from solari_e2b.code_interpreter import build_code_interpreter_template_sync
+build_code_interpreter_template_sync()      # or: await build_code_interpreter_template()
+```
+
+`SOLARI_CODE_INTERPRETER_TEMPLATE` overrides the template (a name or `tpl_…` id). The package list is
+`CODE_INTERPRETER_PACKAGES`; the very large audio, NLP and computer-vision wheels E2B ships (spacy, librosa, opencv,
+numba, gensim) are not included.
+
+## What works, what does not
+
+[COMPAT.md](./COMPAT.md) is the support matrix. Anything Solari cannot do raises `SolariCompatUnsupported`
+(a `SandboxException`) naming the feature; nothing is silently ignored. The sibling TypeScript package is
+`sdk/packages/e2b-compat` (`@solarisdk/e2b-compat`) and follows the same rules.
+
+## Tests
+
+- `python -m pytest`: offline unit tests, a fake gateway.
+- `SOLARI_API_KEY=… SOLARI_BASE_URL=https://api-sta.getsolari.com python -m pytest -m live tests/test_live_staging.py`:
+  live tests against staging. They create their own sandboxes, snapshots and templates and delete only those.

solari_e2b_compat-0.1.0/README.md

@@ -0,0 +1,71 @@
+# solari-e2b-compat
+
+An E2B-compatible Python API on top of [Solari Sandbox](https://getsolari.com). Change the import, keep your sandbox code.
+
+> **Not affiliated with, endorsed by, or sponsored by E2B.** "E2B" is E2B's product name; it appears here only to
+> describe API compatibility. The API shapes follow the MIT-licensed `e2b` and `e2b-code-interpreter` SDKs, see
+> [NOTICE](./NOTICE). Do not look for this package under `e2b*`.
+
+```python
+# before: from e2b_code_interpreter import Sandbox
+from solari_e2b.code_interpreter import Sandbox
+
+sbx = Sandbox.create()                      # SOLARI_API_KEY in the environment
+execution = sbx.run_code("x = 1\nx + 1")
+print(execution.text)                       # "2"
+print(sbx.commands.run("echo hello").stdout)
+sbx.files.write("/tmp/a.txt", "hi")
+sbx.kill()
+```
+
+The plain `e2b` package maps to `solari_e2b`:
+
+```python
+# before: from e2b import Sandbox, AsyncSandbox, Template
+from solari_e2b import Sandbox, AsyncSandbox, Template
+```
+
+Exports: `Sandbox` (blocking) and `AsyncSandbox` (create, connect, list, kill, pause, snapshots, fork, `commands`, `files`,
+`pty`), `Template` / `AsyncTemplate` and the template builder, the E2B exception classes (`SandboxException`,
+`TimeoutException`, `NotFoundException`, `FileNotFoundException`, `CommandExitException`, `AuthenticationException`, ...),
+`SolariCompatUnsupported`, and from `solari_e2b.code_interpreter`: `Sandbox` / `AsyncSandbox` with `run_code` and code
+contexts, `Execution`, `Result`, `Context`.
+
+The blocking API runs the async client on one background thread; callbacks you pass (`on_stdout`, ...) run on that thread.
+Do not call the blocking API from inside such a callback; use `AsyncSandbox` there.
+
+## Configuration
+
+| | Order |
+|---|---|
+| API key | `api_key=` option, `SOLARI_API_KEY`, `E2B_API_KEY`: only an `slr_…` Solari key is ever used. A non-`slr_` value (for example a real E2B key) is skipped with a warning (the key is never printed or sent); with no Solari key the call raises |
+| Base URL | `api_url=` / `domain=` option (Solari or loopback only, anything else raises), `SOLARI_BASE_URL`, `E2B_API_URL` / `E2B_DOMAIN` (only if they point at getsolari.com or loopback; otherwise ignored with a warning), default `https://api.getsolari.com` |
+
+An E2B key does not work here: use a Solari API key.
+
+## The code-interpreter template
+
+`e2b_code_interpreter` runs in a template with a data-analysis stack (pandas, numpy, scipy, scikit-learn, seaborn,
+plotly, ...). Solari builds the equivalent, `code-interpreter-v1`, into your org the first time `Sandbox.create()` is
+called without a template (about 80 seconds, once). To do it ahead of time:
+
+```python
+from solari_e2b.code_interpreter import build_code_interpreter_template_sync
+build_code_interpreter_template_sync()      # or: await build_code_interpreter_template()
+```
+
+`SOLARI_CODE_INTERPRETER_TEMPLATE` overrides the template (a name or `tpl_…` id). The package list is
+`CODE_INTERPRETER_PACKAGES`; the very large audio, NLP and computer-vision wheels E2B ships (spacy, librosa, opencv,
+numba, gensim) are not included.
+
+## What works, what does not
+
+[COMPAT.md](./COMPAT.md) is the support matrix. Anything Solari cannot do raises `SolariCompatUnsupported`
+(a `SandboxException`) naming the feature; nothing is silently ignored. The sibling TypeScript package is
+`sdk/packages/e2b-compat` (`@solarisdk/e2b-compat`) and follows the same rules.
+
+## Tests
+
+- `python -m pytest`: offline unit tests, a fake gateway.
+- `SOLARI_API_KEY=… SOLARI_BASE_URL=https://api-sta.getsolari.com python -m pytest -m live tests/test_live_staging.py`:
+  live tests against staging. They create their own sandboxes, snapshots and templates and delete only those.

solari_e2b_compat-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "solari-e2b-compat"
+version = "0.1.0"
+description = "E2B-compatible Python interface (sandboxes and code interpreter) over Solari Sandboxes. Not affiliated with E2B."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "Solari" }]
+keywords = ["solari", "sandbox", "e2b", "code-interpreter", "compatibility"]
+dependencies = ["solari-sandbox>=0.3.0", "solari-core>=0.4.0"]
+
+[project.optional-dependencies]
+test = ["pytest>=7", "pytest-asyncio>=0.23"]
+
+[project.urls]
+Homepage = "https://getsolari.com"
+
+[tool.hatch.build.targets.wheel]
+packages = ["solari_e2b"]
+
+[tool.hatch.build.targets.sdist]
+include = ["solari_e2b", "README.md", "COMPAT.md", "NOTICE", "LICENSE-E2B"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = ["live: runs against a real Solari gateway (needs SOLARI_API_KEY + SOLARI_BASE_URL)"]
+addopts = "-m 'not live'"

solari_e2b_compat-0.1.0/solari_e2b/__init__.py

@@ -0,0 +1,39 @@
+# ruff: noqa: F401
+"""solari_e2b: an E2B-compatible Python API on Solari Sandbox. Not affiliated with E2B. See README.md, COMPAT.md, NOTICE.
+
+``from solari_e2b import Sandbox`` (blocking) or ``AsyncSandbox``; ``from solari_e2b.code_interpreter import Sandbox`` for
+``run_code``."""
+
+from __future__ import annotations
+
+from ._commands import AsyncCommandHandle, AsyncCommandInputHandle, AsyncCommands, AsyncPty
+from ._config import DEFAULT_BASE_URL, is_solari_base_url
+from ._filesystem import AsyncFileStreamReader, AsyncFilesystem, AsyncWatchHandle
+from ._sandbox import AsyncSandbox, AsyncSandboxPaginator, AsyncSnapshotPaginator
+from ._sync import Sandbox
+from ._template import (
+    AsyncTemplate,
+    BuildInfo,
+    LogEntry,
+    LogEntryEnd,
+    LogEntryStart,
+    ReadyCmd,
+    Template,
+    TemplateBase,
+    TemplateBuildStatusResponse,
+    default_build_logger,
+    wait_for_file,
+    wait_for_port,
+    wait_for_process,
+    wait_for_timeout,
+    wait_for_url,
+)
+from .exceptions import *  # noqa: F401,F403
+from .exceptions import _Unsupported
+from .models import *  # noqa: F401,F403
+
+#: E2B's Volume and Secret APIs have no Solari equivalent yet: every call raises SolariCompatUnsupported.
+Volume = _Unsupported("Volume")
+Secret = _Unsupported("Secret")
+
+__version__ = "0.1.0"

solari_e2b_compat-0.1.0/solari_e2b/_box.py

@@ -0,0 +1,155 @@
+"""Per-sandbox plumbing shared by Sandbox, Commands, Filesystem and Pty: the live control handle (reconnecting after a
+resume), the guest's $HOME, and the shell wrapper E2B-style ``commands.run`` needs."""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+from typing import Any, Awaitable, Callable, List, Optional, Tuple, TypeVar
+from urllib.parse import quote
+
+from solari_core.errors import ConnectionError as SolariConnection, GatewayError, SolariError
+
+from ._config import Conn
+from .exceptions import translate
+
+T = TypeVar("T")
+DEFAULT_HOME = "/home/user"
+
+#: Native image sandboxes: a bash when the image has one, else sh. The command is "$1", so it is never re-parsed.
+NATIVE_SHELL_SCRIPT = 'if [ -x /bin/bash ]; then exec /bin/bash -c "$1"; else exec /bin/sh -c "$1"; fi'
+
+
+def shell_args(native: bool, command: str) -> Tuple[str, List[str]]:
+    """``(program, args)`` for an E2B-style shell string: ``bash -lc`` normally, native-image safe otherwise."""
+    if native:
+        return "/bin/sh", ["-c", NATIVE_SHELL_SCRIPT, "sh", command]
+    return "/bin/bash", ["-lc", command]
+
+
+async def get_view(conn: Conn, sandbox_id: str) -> dict:
+    """Raw ``GET /sandboxes/:id`` (the Python SDK view drops ``fromImage`` and the creation time)."""
+    return await conn.http.request("GET", f"/sandboxes/{quote(sandbox_id, safe='')}")
+
+
+def fire(cb: Optional[Callable[..., Any]], *args: Any) -> None:
+    """Invoke a user callback now if it is sync, or schedule it if it is async; an exception in it never breaks the stream."""
+    if cb is None:
+        return
+    try:
+        r = cb(*args)
+        if inspect.isawaitable(r):
+            asyncio.ensure_future(r)
+    except Exception:  # noqa: BLE001
+        pass
+
+
+async def call_cb(cb: Optional[Callable[..., Any]], *args: Any) -> None:
+    """Invoke a user callback (sync or async); an exception in it never breaks the stream."""
+    if cb is None:
+        return
+    try:
+        r = cb(*args)
+        if inspect.isawaitable(r):
+            await r
+    except Exception:  # noqa: BLE001
+        pass
+
+
+class Box:
+    def __init__(self, conn: Conn, sandbox_id: str, initial: Any = None) -> None:
+        self.conn = conn
+        self.id = sandbox_id
+        self._h: Optional["asyncio.Future[Any]"] = None
+        self._initial = initial
+        self._native: Optional["asyncio.Future[bool]"] = None
+        self._home: Optional["asyncio.Future[str]"] = None
+
+    async def handle(self) -> Any:
+        """The connected control handle, cached."""
+        if self._h is None:
+            self._h = asyncio.ensure_future(self._attach())
+        try:
+            return await asyncio.shield(self._h)
+        except BaseException:
+            if self._h is not None and self._h.done():
+                self._h = None
+            raise
+
+    async def _attach(self) -> Any:
+        sb = self._initial if self._initial is not None else await self.conn.solari.connect(self.id)
+        self._initial = None
+        await sb.connect()
+        return sb
+
+    def drop(self) -> None:
+        self._h = None
+        self._initial = None
+
+    async def close(self) -> None:
+        """Close this process's control channel to the sandbox (if one is open) and forget it."""
+        h, self._h = self._h, None
+        initial, self._initial = self._initial, None
+        sb = initial
+        if h is not None and h.done() and not h.cancelled() and h.exception() is None:
+            sb = h.result()
+        if sb is not None:
+            try:
+                await sb.close()
+            except Exception:  # noqa: BLE001
+                pass
+
+    async def on(self, fn: Callable[[Any], Awaitable[T]], what: str = "other") -> T:
+        """Run ``fn`` on the live handle; if the channel was closed under us (first call after a resume), reconnect and retry."""
+        attempt = 0
+        while True:
+            try:
+                return await fn(await self.handle())
+            except Exception as e:  # noqa: BLE001
+                closed = isinstance(e, SolariError) and not isinstance(e, GatewayError) and (
+                    isinstance(e, SolariConnection) or any(w in str(e).lower() for w in ("closed", "not connected", "disconnect", "websocket"))
+                )
+                if not closed or attempt >= 2:
+                    raise translate(e, what) from (e if translate(e, what) is not e else None)
+                self.drop()
+                attempt += 1
+                await asyncio.sleep(0.5 * attempt)
+
+    async def is_native(self) -> bool:
+        if self._native is None:
+            self._native = asyncio.ensure_future(self._fetch_native())
+        try:
+            return await asyncio.shield(self._native)
+        except BaseException:
+            self._native = None
+            raise
+
+    async def _fetch_native(self) -> bool:
+        return bool((await get_view(self.conn, self.id)).get("fromImage"))
+
+    async def home(self) -> str:
+        """The guest's $HOME (E2B's default cwd and relative-path base), created if missing."""
+        if self._home is None:
+            self._home = asyncio.ensure_future(self._fetch_home())
+        try:
+            return await asyncio.shield(self._home)
+        except BaseException:
+            self._home = None
+            raise
+
+    async def _fetch_home(self) -> str:
+        prog, args = shell_args(await self.is_native(), 'printf %s "$HOME"')
+        r = await self.on(lambda sb: sb.commands.run(prog, args=args))
+        home = r.stdout.strip() or DEFAULT_HOME
+        await self.on(lambda sb: sb.commands.run("/bin/mkdir", args=["-p", home]))
+        return home
+
+    async def abs(self, path: str) -> str:
+        if path.startswith("/"):
+            return path
+        home = await self.home()
+        if path == "~":
+            return home
+        if path.startswith("~/"):
+            return f"{home}/{path[2:]}"
+        return f"{home}/{path}"