smolagents-groundbox 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,6 @@
1
+ node_modules/
2
+ dist/
3
+ __pycache__/
4
+ *.egg-info/
5
+ .venv/
6
+ .env
@@ -0,0 +1,9 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Groundbox
4
+
5
+ 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:
6
+
7
+ The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
8
+
9
+ 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.
@@ -0,0 +1,126 @@
1
+ Metadata-Version: 2.5
2
+ Name: smolagents-groundbox
3
+ Version: 0.1.0
4
+ Summary: A Groundbox sandbox executor for smolagents' CodeAgent: run agent code in a Firecracker microVM.
5
+ Project-URL: Homepage, https://groundbox.dev
6
+ Project-URL: Documentation, https://groundbox.dev/docs/sandboxes
7
+ Project-URL: Source, https://github.com/Ground-box/groundbox-integrations/tree/main/python/smolagents
8
+ Author-email: Groundbox <kurtis@groundbox.dev>
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: agents,code-execution,firecracker,groundbox,sandbox,smolagents
12
+ Classifier: Operating System :: OS Independent
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: Software Development :: Libraries
15
+ Requires-Python: >=3.10
16
+ Requires-Dist: groundbox>=0.4.2
17
+ Requires-Dist: smolagents>=1.25.0
18
+ Provides-Extra: test
19
+ Requires-Dist: numpy; extra == 'test'
20
+ Requires-Dist: pytest>=7; extra == 'test'
21
+ Description-Content-Type: text/markdown
22
+
23
+ # smolagents-groundbox
24
+
25
+ Run [smolagents](https://github.com/huggingface/smolagents)' `CodeAgent` code in a
26
+ [Groundbox](https://groundbox.dev) sandbox: a Linux microVM (Firecracker) per agent, started in
27
+ about a second.
28
+
29
+ `GroundboxExecutor` is a remote Python executor, built like smolagents' own E2B, Modal, Docker and
30
+ Blaxel executors. Pass it to `CodeAgent(executor=...)`.
31
+
32
+ Needs smolagents 1.25.0 or newer. `executor=` arrived in 1.23.0, but 1.25.0 moved remote
33
+ executors from pickle to safe JSON serialization (`allow_pickle`), and this package uses that.
34
+
35
+ ## Install
36
+
37
+ ```
38
+ pip install smolagents-groundbox
39
+ ```
40
+
41
+ Set `GROUNDBOX_API_KEY` (create one at https://app.groundbox.dev/keys), or pass `api_key=`.
42
+
43
+ ## Use
44
+
45
+ ```python
46
+ from smolagents import CodeAgent, InferenceClientModel
47
+ from smolagents_groundbox import GroundboxExecutor
48
+
49
+ with CodeAgent(
50
+ tools=[],
51
+ model=InferenceClientModel(),
52
+ executor=GroundboxExecutor(additional_imports=["numpy"]),
53
+ ) as agent:
54
+ agent.run("Compute the 20th Fibonacci number with numpy.")
55
+ # Leaving the block deletes the sandbox.
56
+ ```
57
+
58
+ Without the `with` block, call `agent.cleanup()` (or `executor.cleanup()`) when you are done. A
59
+ sandbox the executor created also ends on its own after `timeout_minutes` (60 unless you set it).
60
+
61
+ ## Options
62
+
63
+ ```python
64
+ GroundboxExecutor(
65
+ additional_imports=["pandas"], # pip installed in the sandbox before the first step
66
+ create_kwargs={ # passed to Groundbox.create_sandbox
67
+ "cpus": 2,
68
+ "memory_gb": 4,
69
+ "image": "python:3.12-slim", # any public Docker image, or a template=...
70
+ "allow_hosts": ["pypi.org", "files.pythonhosted.org"],
71
+ "timeout_minutes": 30,
72
+ },
73
+ timeout_seconds=300, # longest one code action may run (default 300)
74
+ sandbox_id=None, # reuse a running sandbox; it is not deleted on cleanup
75
+ allow_pickle=False, # same meaning as in smolagents' built-in executors
76
+ )
77
+ ```
78
+
79
+ `logger` is optional: `CodeAgent` does not hand its logger to an executor you build yourself, so
80
+ by default the executor logs to a new `AgentLogger`. Pass `logger=agent.logger` to share one.
81
+
82
+ ## How it works
83
+
84
+ The executor starts the sandbox, uploads a small kernel (standard library only), and starts it as
85
+ a background command. Each code action is sent to that one Python process, so variables, imports,
86
+ functions and tools stay from step to step, the way the built-in executors keep them in a Jupyter
87
+ kernel. Tools and `final_answer` go through smolagents' own `send_tools`, `send_variables` and
88
+ final-answer handling.
89
+
90
+ - Output: the value of the last expression, as its `repr` (a PIL image comes back as an image),
91
+ like the text result of the Jupyter-based executors.
92
+ - Logs: everything printed to stdout and stderr during the step, including subprocesses.
93
+ - Errors: raised as `AgentError` with the exception name, message and traceback.
94
+ - Timeouts: past `timeout_seconds`, the step is interrupted with `ExecutionTimeout`; the namespace
95
+ is kept.
96
+ - A step that kills the Python process (`os._exit`, running out of memory) restarts the kernel and
97
+ says so; earlier variables are gone.
98
+
99
+ The default image is Ubuntu with Python 3.12, running as the user `runner` (with sudo); packages
100
+ are installed with `pip --user`. With `image=`, commands run as root.
101
+
102
+ When the agent starts, smolagents pip installs each tool's requirements in the sandbox. Its own
103
+ `final_answer` tool asks for `numpy` and `pillow`, so the first run in a fresh sandbox spends a few
104
+ seconds installing them (the same happens with the built-in executors). To skip that, start from a
105
+ [template](https://groundbox.dev/docs/templates) that has them: `create_kwargs={"template": "..."}`.
106
+
107
+ ## Limits
108
+
109
+ - No Jupyter: IPython syntax such as `!pip install` or `%magic` lines is not supported in agent
110
+ code (the built-in executors run on Jupyter and accept it). Use `subprocess` or
111
+ `additional_imports` instead.
112
+ - Rich outputs other than PIL images (HTML, charts) come back as their `repr`.
113
+ - One code action at a time per executor; each step makes one API call (about 0.2 s overhead).
114
+ - Not built into smolagents: use `executor=GroundboxExecutor()`, not `executor_type="groundbox"`.
115
+
116
+ ## Tests
117
+
118
+ ```
119
+ pip install -e '.[test]'
120
+ pytest # unit tests, with a local stand-in for the sandbox
121
+ GROUNDBOX_API_KEY=gbx_... pytest tests/test_live.py # against Groundbox itself
122
+ ```
123
+
124
+ ## License
125
+
126
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,104 @@
1
+ # smolagents-groundbox
2
+
3
+ Run [smolagents](https://github.com/huggingface/smolagents)' `CodeAgent` code in a
4
+ [Groundbox](https://groundbox.dev) sandbox: a Linux microVM (Firecracker) per agent, started in
5
+ about a second.
6
+
7
+ `GroundboxExecutor` is a remote Python executor, built like smolagents' own E2B, Modal, Docker and
8
+ Blaxel executors. Pass it to `CodeAgent(executor=...)`.
9
+
10
+ Needs smolagents 1.25.0 or newer. `executor=` arrived in 1.23.0, but 1.25.0 moved remote
11
+ executors from pickle to safe JSON serialization (`allow_pickle`), and this package uses that.
12
+
13
+ ## Install
14
+
15
+ ```
16
+ pip install smolagents-groundbox
17
+ ```
18
+
19
+ Set `GROUNDBOX_API_KEY` (create one at https://app.groundbox.dev/keys), or pass `api_key=`.
20
+
21
+ ## Use
22
+
23
+ ```python
24
+ from smolagents import CodeAgent, InferenceClientModel
25
+ from smolagents_groundbox import GroundboxExecutor
26
+
27
+ with CodeAgent(
28
+ tools=[],
29
+ model=InferenceClientModel(),
30
+ executor=GroundboxExecutor(additional_imports=["numpy"]),
31
+ ) as agent:
32
+ agent.run("Compute the 20th Fibonacci number with numpy.")
33
+ # Leaving the block deletes the sandbox.
34
+ ```
35
+
36
+ Without the `with` block, call `agent.cleanup()` (or `executor.cleanup()`) when you are done. A
37
+ sandbox the executor created also ends on its own after `timeout_minutes` (60 unless you set it).
38
+
39
+ ## Options
40
+
41
+ ```python
42
+ GroundboxExecutor(
43
+ additional_imports=["pandas"], # pip installed in the sandbox before the first step
44
+ create_kwargs={ # passed to Groundbox.create_sandbox
45
+ "cpus": 2,
46
+ "memory_gb": 4,
47
+ "image": "python:3.12-slim", # any public Docker image, or a template=...
48
+ "allow_hosts": ["pypi.org", "files.pythonhosted.org"],
49
+ "timeout_minutes": 30,
50
+ },
51
+ timeout_seconds=300, # longest one code action may run (default 300)
52
+ sandbox_id=None, # reuse a running sandbox; it is not deleted on cleanup
53
+ allow_pickle=False, # same meaning as in smolagents' built-in executors
54
+ )
55
+ ```
56
+
57
+ `logger` is optional: `CodeAgent` does not hand its logger to an executor you build yourself, so
58
+ by default the executor logs to a new `AgentLogger`. Pass `logger=agent.logger` to share one.
59
+
60
+ ## How it works
61
+
62
+ The executor starts the sandbox, uploads a small kernel (standard library only), and starts it as
63
+ a background command. Each code action is sent to that one Python process, so variables, imports,
64
+ functions and tools stay from step to step, the way the built-in executors keep them in a Jupyter
65
+ kernel. Tools and `final_answer` go through smolagents' own `send_tools`, `send_variables` and
66
+ final-answer handling.
67
+
68
+ - Output: the value of the last expression, as its `repr` (a PIL image comes back as an image),
69
+ like the text result of the Jupyter-based executors.
70
+ - Logs: everything printed to stdout and stderr during the step, including subprocesses.
71
+ - Errors: raised as `AgentError` with the exception name, message and traceback.
72
+ - Timeouts: past `timeout_seconds`, the step is interrupted with `ExecutionTimeout`; the namespace
73
+ is kept.
74
+ - A step that kills the Python process (`os._exit`, running out of memory) restarts the kernel and
75
+ says so; earlier variables are gone.
76
+
77
+ The default image is Ubuntu with Python 3.12, running as the user `runner` (with sudo); packages
78
+ are installed with `pip --user`. With `image=`, commands run as root.
79
+
80
+ When the agent starts, smolagents pip installs each tool's requirements in the sandbox. Its own
81
+ `final_answer` tool asks for `numpy` and `pillow`, so the first run in a fresh sandbox spends a few
82
+ seconds installing them (the same happens with the built-in executors). To skip that, start from a
83
+ [template](https://groundbox.dev/docs/templates) that has them: `create_kwargs={"template": "..."}`.
84
+
85
+ ## Limits
86
+
87
+ - No Jupyter: IPython syntax such as `!pip install` or `%magic` lines is not supported in agent
88
+ code (the built-in executors run on Jupyter and accept it). Use `subprocess` or
89
+ `additional_imports` instead.
90
+ - Rich outputs other than PIL images (HTML, charts) come back as their `repr`.
91
+ - One code action at a time per executor; each step makes one API call (about 0.2 s overhead).
92
+ - Not built into smolagents: use `executor=GroundboxExecutor()`, not `executor_type="groundbox"`.
93
+
94
+ ## Tests
95
+
96
+ ```
97
+ pip install -e '.[test]'
98
+ pytest # unit tests, with a local stand-in for the sandbox
99
+ GROUNDBOX_API_KEY=gbx_... pytest tests/test_live.py # against Groundbox itself
100
+ ```
101
+
102
+ ## License
103
+
104
+ MIT. See [LICENSE](LICENSE).
@@ -0,0 +1,35 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "smolagents-groundbox"
7
+ version = "0.1.0"
8
+ description = "A Groundbox sandbox executor for smolagents' CodeAgent: run agent code in a Firecracker microVM."
9
+ readme = "README.md"
10
+ license = "MIT"
11
+ license-files = ["LICENSE"]
12
+ requires-python = ">=3.10"
13
+ authors = [{ name = "Groundbox", email = "kurtis@groundbox.dev" }]
14
+ keywords = ["smolagents", "groundbox", "sandbox", "code-execution", "agents", "firecracker"]
15
+ classifiers = [
16
+ "Programming Language :: Python :: 3",
17
+ "Operating System :: OS Independent",
18
+ "Topic :: Software Development :: Libraries",
19
+ ]
20
+ dependencies = ["smolagents>=1.25.0", "groundbox>=0.4.2"]
21
+
22
+ [project.optional-dependencies]
23
+ # numpy: smolagents' final_answer tool imports it, and the local stand-in skips pip.
24
+ test = ["pytest>=7", "numpy"]
25
+
26
+ [project.urls]
27
+ Homepage = "https://groundbox.dev"
28
+ Documentation = "https://groundbox.dev/docs/sandboxes"
29
+ Source = "https://github.com/Ground-box/groundbox-integrations/tree/main/python/smolagents"
30
+
31
+ [tool.hatch.build.targets.wheel]
32
+ packages = ["src/smolagents_groundbox"]
33
+
34
+ [tool.pytest.ini_options]
35
+ testpaths = ["tests"]
@@ -0,0 +1,6 @@
1
+ """Run smolagents' CodeAgent code in Groundbox sandboxes."""
2
+
3
+ from .executor import GroundboxExecutor
4
+
5
+ __all__ = ["GroundboxExecutor"]
6
+ __version__ = "0.1.0"
@@ -0,0 +1,233 @@
1
+ """A small Python kernel that runs inside the Groundbox sandbox.
2
+
3
+ This file is uploaded to the sandbox as it is and needs only the standard library
4
+ (Python 3.8 or newer). It has two modes:
5
+
6
+ python3 _kernel.py serve SOCKET keep one Python namespace alive and run code sent to SOCKET
7
+ python3 _kernel.py run SOCKET read a request (JSON) on stdin, send it to the server and
8
+ print the answer (JSON) on stdout
9
+
10
+ The executor starts `serve` once as a background command, then runs `run` for each code
11
+ action with Groundbox's exec call. Variables, imports and functions stay in the server's
12
+ namespace between actions, the way a Jupyter kernel keeps them for the built-in executors.
13
+ """
14
+
15
+ import ast
16
+ import base64
17
+ import io
18
+ import json
19
+ import linecache
20
+ import os
21
+ import signal
22
+ import site
23
+ import socket
24
+ import struct
25
+ import sys
26
+ import tempfile
27
+ import time
28
+ import traceback
29
+
30
+ FINAL_ANSWER_EXCEPTION = "FinalAnswerException"
31
+
32
+
33
+ class ExecutionTimeout(BaseException):
34
+ """Raised inside running code when it runs past its time limit."""
35
+
36
+
37
+ def _send(conn, payload):
38
+ data = json.dumps(payload).encode("utf-8")
39
+ conn.sendall(struct.pack(">I", len(data)) + data)
40
+
41
+
42
+ def _recv(conn):
43
+ header = _recv_exact(conn, 4)
44
+ if header is None:
45
+ return None
46
+ (size,) = struct.unpack(">I", header)
47
+ body = _recv_exact(conn, size)
48
+ if body is None:
49
+ return None
50
+ return json.loads(body.decode("utf-8"))
51
+
52
+
53
+ def _recv_exact(conn, size):
54
+ chunks = []
55
+ while size > 0:
56
+ chunk = conn.recv(min(size, 1 << 20))
57
+ if not chunk:
58
+ return None
59
+ chunks.append(chunk)
60
+ size -= len(chunk)
61
+ return b"".join(chunks)
62
+
63
+
64
+ def _image_png(value):
65
+ """PNG bytes for a PIL image, or None for anything else (PIL is not imported here)."""
66
+ module = type(value).__module__ or ""
67
+ if not module.startswith("PIL.") or not hasattr(value, "save"):
68
+ return None
69
+ buffer = io.BytesIO()
70
+ value.save(buffer, format="PNG")
71
+ return buffer.getvalue()
72
+
73
+
74
+ class Kernel:
75
+ def __init__(self):
76
+ self.namespace = {"__name__": "__main__", "__builtins__": __builtins__}
77
+ self.count = 0
78
+
79
+ def _refresh_paths(self):
80
+ # Packages installed with `pip install --user` after this process started live in a
81
+ # folder that was not on sys.path at start-up if it did not exist yet.
82
+ try:
83
+ user_site = site.getusersitepackages()
84
+ if os.path.isdir(user_site) and user_site not in sys.path:
85
+ site.addsitedir(user_site)
86
+ except Exception:
87
+ pass
88
+ try:
89
+ import importlib
90
+
91
+ importlib.invalidate_caches()
92
+ except Exception:
93
+ pass
94
+
95
+ def _compile(self, code, filename):
96
+ tree = ast.parse(code, filename=filename, mode="exec")
97
+ last = None
98
+ if tree.body and isinstance(tree.body[-1], ast.Expr):
99
+ last = ast.Expression(body=tree.body.pop().value)
100
+ body = compile(tree, filename, "exec")
101
+ expr = compile(last, filename, "eval") if last is not None else None
102
+ return body, expr
103
+
104
+ def execute(self, code, timeout_s=None):
105
+ self.count += 1
106
+ filename = "<code-%d>" % self.count
107
+ linecache.cache[filename] = (len(code), None, code.splitlines(True), filename)
108
+ self._refresh_paths()
109
+
110
+ # Capture output at the file-descriptor level, so subprocesses and C extensions
111
+ # are captured along with print().
112
+ sys.stdout.flush()
113
+ sys.stderr.flush()
114
+ capture = tempfile.TemporaryFile()
115
+ saved_out, saved_err = os.dup(1), os.dup(2)
116
+ os.dup2(capture.fileno(), 1)
117
+ os.dup2(capture.fileno(), 2)
118
+
119
+ result = {"output": None, "output_type": None, "final_answer": None, "error": None}
120
+ previous_handler = None
121
+ if timeout_s:
122
+ def on_alarm(signum, frame):
123
+ raise ExecutionTimeout("Code execution ran past %s seconds" % timeout_s)
124
+
125
+ previous_handler = signal.signal(signal.SIGALRM, on_alarm)
126
+ signal.setitimer(signal.ITIMER_REAL, float(timeout_s))
127
+ try:
128
+ body, expr = self._compile(code, filename)
129
+ exec(body, self.namespace, self.namespace)
130
+ if expr is not None:
131
+ value = eval(expr, self.namespace, self.namespace)
132
+ if value is not None:
133
+ png = _image_png(value)
134
+ if png is not None:
135
+ result["output"] = base64.b64encode(png).decode("ascii")
136
+ result["output_type"] = "image/png"
137
+ else:
138
+ result["output"] = repr(value)
139
+ result["output_type"] = "text/plain"
140
+ except BaseException as error: # noqa: B036 - code may raise anything, SystemExit included
141
+ if type(error).__name__ == FINAL_ANSWER_EXCEPTION:
142
+ value = getattr(error, "value", None)
143
+ result["final_answer"] = value if isinstance(value, str) else str(error)
144
+ else:
145
+ result["error"] = {
146
+ "name": type(error).__name__,
147
+ "value": str(error),
148
+ "traceback": "".join(traceback.format_exception(type(error), error, error.__traceback__)),
149
+ }
150
+ finally:
151
+ if timeout_s:
152
+ signal.setitimer(signal.ITIMER_REAL, 0)
153
+ signal.signal(signal.SIGALRM, previous_handler or signal.SIG_DFL)
154
+ try:
155
+ sys.stdout.flush()
156
+ sys.stderr.flush()
157
+ except Exception:
158
+ pass
159
+ os.dup2(saved_out, 1)
160
+ os.dup2(saved_err, 2)
161
+ os.close(saved_out)
162
+ os.close(saved_err)
163
+ capture.seek(0)
164
+ result["logs"] = capture.read().decode("utf-8", errors="replace")
165
+ capture.close()
166
+ return result
167
+
168
+
169
+ def serve(path):
170
+ # Line-buffered, so print() output and subprocess output land in the order they happen.
171
+ try:
172
+ sys.stdout.reconfigure(line_buffering=True)
173
+ sys.stderr.reconfigure(line_buffering=True)
174
+ except Exception:
175
+ pass
176
+ signal.signal(signal.SIGINT, signal.default_int_handler)
177
+ if os.path.exists(path):
178
+ os.unlink(path)
179
+ server = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
180
+ server.bind(path)
181
+ os.chmod(path, 0o600)
182
+ server.listen(4)
183
+ kernel = Kernel()
184
+ while True:
185
+ conn, _ = server.accept()
186
+ try:
187
+ request = _recv(conn)
188
+ if request is None:
189
+ continue
190
+ if request.get("ping"):
191
+ _send(conn, {"pong": True, "python": sys.version.split()[0], "pid": os.getpid()})
192
+ continue
193
+ _send(conn, kernel.execute(request["code"], request.get("timeout_s")))
194
+ except Exception as error: # keep serving whatever one connection did
195
+ try:
196
+ _send(conn, {"error": {"name": type(error).__name__, "value": str(error), "traceback": ""}})
197
+ except Exception:
198
+ pass
199
+ finally:
200
+ conn.close()
201
+
202
+
203
+ def run(path, wait_s=30.0):
204
+ request = json.loads(sys.stdin.read())
205
+ start = time.monotonic()
206
+ while True:
207
+ conn = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
208
+ try:
209
+ conn.connect(path)
210
+ break
211
+ except (FileNotFoundError, ConnectionRefusedError) as error:
212
+ conn.close()
213
+ # No socket yet: the server may still be starting. A socket nobody listens on:
214
+ # the server has ended, so give up after a moment.
215
+ limit = wait_s if isinstance(error, FileNotFoundError) else 1.0
216
+ if time.monotonic() - start >= limit:
217
+ print(json.dumps({"kernel_unavailable": True}))
218
+ return
219
+ time.sleep(0.05)
220
+ with conn:
221
+ _send(conn, request)
222
+ answer = _recv(conn)
223
+ print(json.dumps(answer if answer is not None else {"kernel_unavailable": True}))
224
+
225
+
226
+ if __name__ == "__main__":
227
+ mode, socket_path = sys.argv[1], sys.argv[2]
228
+ if mode == "serve":
229
+ serve(socket_path)
230
+ elif mode == "run":
231
+ run(socket_path)
232
+ else:
233
+ raise SystemExit("usage: _kernel.py serve|run SOCKET")
@@ -0,0 +1,283 @@
1
+ """GroundboxExecutor: run smolagents' CodeAgent code in a Groundbox sandbox."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import base64
6
+ import json
7
+ import uuid
8
+ from importlib import resources
9
+ from io import BytesIO
10
+ from typing import Any, Optional
11
+
12
+ from smolagents.local_python_executor import CodeOutput
13
+ from smolagents.monitoring import AgentLogger, LogLevel
14
+ from smolagents.remote_executors import RemotePythonExecutor
15
+ from smolagents.utils import AgentError
16
+
17
+ __all__ = ["GroundboxExecutor"]
18
+
19
+ KERNEL_DIR = "/tmp/smolagents-groundbox"
20
+ DEFAULT_TIMEOUT_MINUTES = 60
21
+ # POST /exec waits for a command for up to 60 minutes.
22
+ MAX_EXEC_SECONDS = 3600
23
+
24
+
25
+ def _kernel_source() -> str:
26
+ return resources.files("smolagents_groundbox").joinpath("_kernel.py").read_text(encoding="utf-8")
27
+
28
+
29
+ class GroundboxExecutor(RemotePythonExecutor):
30
+ """
31
+ Remote Python code executor in a Groundbox sandbox (a Firecracker microVM).
32
+
33
+ Pass it to `CodeAgent(..., executor=GroundboxExecutor())`. Each code action runs in one
34
+ long-lived Python process in the sandbox, so variables, imports and functions carry over
35
+ from one step to the next, as with smolagents' built-in E2B, Modal, Docker and Blaxel
36
+ executors.
37
+
38
+ Args:
39
+ additional_imports (`list[str]`, *optional*): Python packages to pip install in the sandbox
40
+ before the first step.
41
+ logger (`AgentLogger`, *optional*): Logger for output and errors. Defaults to a new
42
+ `AgentLogger(level=LogLevel.INFO)`.
43
+ allow_pickle (`bool`, default `False`): Whether to allow pickle serialization for objects that
44
+ cannot be safely serialized to JSON (variables sent in and final answers sent back).
45
+ **Security Warning:** pickle deserialization can execute arbitrary code. Leave it off unless you
46
+ trust the sandbox and need custom types.
47
+ api_key (`str`, *optional*): A Groundbox API key. Defaults to the `GROUNDBOX_API_KEY` environment variable.
48
+ base_url (`str`, *optional*): The API's base URL. Defaults to `GROUNDBOX_API_URL`, then
49
+ `https://api.groundbox.dev/v1`.
50
+ create_kwargs (`dict`, *optional*): Keyword arguments for `Groundbox.create_sandbox`, such as
51
+ `cpus`, `memory_gb`, `image="python:3.12-slim"`, `template`, `env`, `allow_hosts`, `secrets`
52
+ or `timeout_minutes` (60 unless you set it).
53
+ sandbox_id (`str`, *optional*): Use this running sandbox instead of creating one. It is left
54
+ running on cleanup unless `delete_on_cleanup=True`.
55
+ timeout_seconds (`int`, *optional*, default `300`): Longest one code action may run. Past it the
56
+ code is interrupted with an `ExecutionTimeout` error and the namespace is kept. `None` waits
57
+ for up to an hour.
58
+ python (`str`, default `"python3"`): The Python interpreter in the sandbox.
59
+ delete_on_cleanup (`bool`, *optional*): Delete the sandbox on `cleanup()`. Defaults to `True` for a
60
+ sandbox this executor created and `False` for one passed as `sandbox_id`.
61
+ client (`groundbox.Groundbox`, *optional*): A ready Groundbox client; `api_key` and `base_url` are
62
+ then ignored.
63
+ """
64
+
65
+ def __init__(
66
+ self,
67
+ additional_imports: Optional[list[str]] = None,
68
+ logger: Optional[AgentLogger] = None,
69
+ allow_pickle: bool = False,
70
+ *,
71
+ api_key: Optional[str] = None,
72
+ base_url: Optional[str] = None,
73
+ create_kwargs: Optional[dict[str, Any]] = None,
74
+ sandbox_id: Optional[str] = None,
75
+ timeout_seconds: Optional[int] = 300,
76
+ python: str = "python3",
77
+ delete_on_cleanup: Optional[bool] = None,
78
+ client: Any = None,
79
+ ):
80
+ super().__init__(additional_imports or [], logger or AgentLogger(level=LogLevel.INFO), allow_pickle)
81
+ if client is None:
82
+ try:
83
+ from groundbox import Groundbox
84
+ except ModuleNotFoundError:
85
+ raise ModuleNotFoundError(
86
+ "Please install the Groundbox SDK to use GroundboxExecutor: `pip install groundbox`"
87
+ )
88
+ client = Groundbox(api_key=api_key, base_url=base_url)
89
+ self.client = client
90
+ self.timeout_seconds = timeout_seconds
91
+ self.python = python
92
+ self._cleaned_up = False
93
+ self._kernel_command_id: Optional[str] = None
94
+ self._kernel_path = f"{KERNEL_DIR}/kernel.py"
95
+ self._socket_path = f"{KERNEL_DIR}/kernel-{uuid.uuid4().hex[:12]}.sock"
96
+ self._owns_sandbox = sandbox_id is None
97
+ self.delete_on_cleanup = self._owns_sandbox if delete_on_cleanup is None else delete_on_cleanup
98
+
99
+ try:
100
+ if sandbox_id is None:
101
+ options: dict[str, Any] = {
102
+ "timeout_minutes": DEFAULT_TIMEOUT_MINUTES,
103
+ "metadata": {"created_by": "smolagents-groundbox"},
104
+ **(create_kwargs or {}),
105
+ }
106
+ sandbox = self.client.create_sandbox(**options)
107
+ self.sandbox_id = sandbox["id"]
108
+ self.logger.log(f"Started Groundbox sandbox {self.sandbox_id}", level=LogLevel.INFO)
109
+ else:
110
+ sandbox = self.client.get_sandbox(sandbox_id)
111
+ self.sandbox_id = sandbox_id
112
+ if sandbox.get("status") != "running":
113
+ sandbox = self.client.wait_for_sandbox(self.sandbox_id)
114
+ if sandbox.get("status") not in ("running", "paused"):
115
+ # A paused sandbox wakes on the next command if it was paused with wake_on_request.
116
+ raise RuntimeError(
117
+ f"Sandbox {self.sandbox_id} is {sandbox.get('status')}: {sandbox.get('error') or 'not running'}"
118
+ )
119
+ self._start_kernel()
120
+ self.installed_packages = self.install_packages(self.additional_imports)
121
+ self.logger.log("Groundbox is running", level=LogLevel.INFO)
122
+ except Exception as e:
123
+ self.cleanup()
124
+ raise RuntimeError(f"Failed to initialize Groundbox sandbox: {e}") from e
125
+
126
+ # ------------------------------------------------------------------
127
+ # The kernel in the sandbox
128
+ # ------------------------------------------------------------------
129
+
130
+ def _start_kernel(self) -> None:
131
+ self.client.write_file(self.sandbox_id, self._kernel_path, _kernel_source())
132
+ command = self.client.start_command(
133
+ self.sandbox_id, [self.python, "-u", self._kernel_path, "serve", self._socket_path]
134
+ )
135
+ self._kernel_command_id = command.get("id")
136
+ answer = self._request({"ping": True}, exec_timeout=60)
137
+ if not answer.get("pong"):
138
+ raise RuntimeError(f"The Python kernel did not start in the sandbox: {self._kernel_failure()}")
139
+ self.logger.log(f"Python {answer.get('python')} kernel ready", level=LogLevel.DEBUG)
140
+
141
+ def _kernel_failure(self) -> str:
142
+ """What the kernel printed before it ended, to explain a failed start."""
143
+ if not self._kernel_command_id:
144
+ return "no command id"
145
+ try:
146
+ out = self.client.get_command_output(self.sandbox_id, self._kernel_command_id)
147
+ return (out.get("stderr") or out.get("stdout") or "no output").strip()[-2000:]
148
+ except Exception as e: # pragma: no cover - best effort
149
+ return str(e)
150
+
151
+ def _request(self, payload: dict[str, Any], exec_timeout: Optional[int] = None) -> dict[str, Any]:
152
+ if exec_timeout is None:
153
+ exec_timeout = MAX_EXEC_SECONDS
154
+ if self.timeout_seconds:
155
+ exec_timeout = min(MAX_EXEC_SECONDS, int(self.timeout_seconds) + 60)
156
+ result = self.client.run_command(
157
+ self.sandbox_id,
158
+ [self.python, self._kernel_path, "run", self._socket_path],
159
+ stdin=json.dumps(payload),
160
+ timeout_s=exec_timeout,
161
+ )
162
+ stdout = (result.get("stdout") or "").strip()
163
+ if result.get("exit_code") != 0 or not stdout:
164
+ if result.get("timed_out"):
165
+ raise AgentError(f"Code execution did not finish within {exec_timeout} seconds", self.logger)
166
+ raise AgentError(
167
+ f"Could not reach the Python kernel in the sandbox (exit code {result.get('exit_code')}):\n"
168
+ f"{result.get('stderr') or stdout}",
169
+ self.logger,
170
+ )
171
+ return json.loads(stdout.splitlines()[-1])
172
+
173
+ def _restart_kernel(self) -> None:
174
+ if self._kernel_command_id:
175
+ try:
176
+ self.client.kill_command(self.sandbox_id, self._kernel_command_id)
177
+ except Exception:
178
+ pass
179
+ self._socket_path = f"{KERNEL_DIR}/kernel-{uuid.uuid4().hex[:12]}.sock"
180
+ self._start_kernel()
181
+
182
+ # ------------------------------------------------------------------
183
+ # RemotePythonExecutor
184
+ # ------------------------------------------------------------------
185
+
186
+ def run_code_raise_errors(self, code: str) -> CodeOutput:
187
+ """
188
+ Execute Python code in the Groundbox sandbox and return the result.
189
+
190
+ Args:
191
+ code (`str`): Python code to execute.
192
+
193
+ Returns:
194
+ `CodeOutput`: Code output containing the result, logs, and whether it is the final answer.
195
+ """
196
+ answer = self._request({"code": code, "timeout_s": self.timeout_seconds})
197
+
198
+ if answer.get("kernel_unavailable"):
199
+ self._restart_kernel()
200
+ raise AgentError(
201
+ "The Python process in the sandbox ended (os._exit, a crash or out of memory) and was "
202
+ "restarted: variables, imports and tools from earlier steps are gone.",
203
+ self.logger,
204
+ )
205
+
206
+ logs = answer.get("logs") or ""
207
+
208
+ if answer.get("final_answer") is not None:
209
+ final_answer = self._deserialize_final_answer(answer["final_answer"], self.allow_pickle)
210
+ return CodeOutput(output=final_answer, logs=logs, is_final_answer=True)
211
+
212
+ error = answer.get("error")
213
+ if error:
214
+ error_message = (
215
+ f"{logs}\n"
216
+ f"Executing code yielded an error:\n"
217
+ f"{error.get('name')}\n"
218
+ f"{error.get('value')}\n"
219
+ f"{error.get('traceback')}"
220
+ )
221
+ raise AgentError(error_message, self.logger)
222
+
223
+ output = answer.get("output")
224
+ if output is not None and answer.get("output_type") == "image/png":
225
+ import PIL.Image
226
+
227
+ output = PIL.Image.open(BytesIO(base64.b64decode(output)))
228
+ return CodeOutput(output=output, logs=logs, is_final_answer=False)
229
+
230
+ def install_packages(self, additional_imports: list[str]) -> list[str]:
231
+ """Pip install packages in the sandbox. Returns the ones installed, or [] if pip failed."""
232
+ if not additional_imports:
233
+ return []
234
+ self.logger.log(f"Installing packages: {', '.join(additional_imports)}", level=LogLevel.INFO)
235
+ base = [self.python, "-m", "pip", "install", "--quiet", "--disable-pip-version-check"]
236
+ # Debian and Ubuntu mark the system Python as externally managed (PEP 668).
237
+ result = self.client.run_command(
238
+ self.sandbox_id, base + ["--break-system-packages", *additional_imports], timeout_s=900
239
+ )
240
+ if result.get("exit_code") != 0 and "--break-system-packages" in (result.get("stderr") or ""):
241
+ # pip older than 23.0.1 does not know the flag.
242
+ result = self.client.run_command(self.sandbox_id, base + list(additional_imports), timeout_s=900)
243
+ if result.get("exit_code") != 0:
244
+ self.logger.log_error(
245
+ f"Failed to install packages (exit code {result.get('exit_code')}): {result.get('stderr')}"
246
+ )
247
+ return []
248
+ self.logger.log(f"Successfully installed packages: {', '.join(additional_imports)}", level=LogLevel.INFO)
249
+ return list(additional_imports)
250
+
251
+ def cleanup(self):
252
+ """Stop the kernel and delete the sandbox (if this executor created it)."""
253
+ if self._cleaned_up:
254
+ return
255
+ self._cleaned_up = True
256
+ sandbox_id = getattr(self, "sandbox_id", None)
257
+ if sandbox_id is None:
258
+ return
259
+ try:
260
+ if self.delete_on_cleanup:
261
+ self.logger.log(f"Deleting Groundbox sandbox {sandbox_id}...", level=LogLevel.INFO)
262
+ self.client.delete_sandbox(sandbox_id)
263
+ self.logger.log("Sandbox cleanup completed", level=LogLevel.INFO)
264
+ elif self._kernel_command_id:
265
+ self.client.kill_command(sandbox_id, self._kernel_command_id)
266
+ except Exception as e:
267
+ self.logger.log_error(f"Error during cleanup: {e}")
268
+
269
+ def delete(self):
270
+ """Ensure cleanup on deletion."""
271
+ self.cleanup()
272
+
273
+ def __enter__(self):
274
+ return self
275
+
276
+ def __exit__(self, exc_type, exc_value, traceback):
277
+ self.cleanup()
278
+
279
+ def __del__(self):
280
+ try:
281
+ self.cleanup()
282
+ except Exception:
283
+ pass
@@ -0,0 +1,121 @@
1
+ """Fakes for the Groundbox client.
2
+
3
+ LocalGroundbox stands in for a sandbox by running commands on this machine, with the
4
+ sandbox's /tmp/smolagents-groundbox folder mapped to a local temporary folder. It runs the
5
+ real kernel, so the unit tests cover the whole code path except the network.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import os
11
+ import shutil
12
+ import subprocess
13
+ import sys
14
+ import tempfile
15
+
16
+ import pytest
17
+ from smolagents.models import ChatMessage, MessageRole, Model
18
+ from smolagents.monitoring import AgentLogger, LogLevel
19
+
20
+ from smolagents_groundbox.executor import KERNEL_DIR
21
+
22
+
23
+ class LocalGroundbox:
24
+ def __init__(self, status: str = "running"):
25
+ # Short path: Unix socket paths are limited to about 100 characters.
26
+ self.root = tempfile.mkdtemp(prefix="gbx", dir="/tmp")
27
+ self.status = status
28
+ self.calls: list[tuple] = []
29
+ self.processes: dict[str, subprocess.Popen] = {}
30
+ self.deleted: list[str] = []
31
+ self.created_with: dict | None = None
32
+
33
+ def _map(self, value):
34
+ if isinstance(value, str):
35
+ return value.replace(KERNEL_DIR, self.root)
36
+ return [self._map(v) for v in value]
37
+
38
+ def create_sandbox(self, **kwargs):
39
+ self.calls.append(("create_sandbox", kwargs))
40
+ self.created_with = kwargs
41
+ return {"id": "sbx_local", "status": self.status}
42
+
43
+ def get_sandbox(self, sandbox_id):
44
+ self.calls.append(("get_sandbox", sandbox_id))
45
+ return {"id": sandbox_id, "status": self.status}
46
+
47
+ def wait_for_sandbox(self, sandbox_id):
48
+ self.calls.append(("wait_for_sandbox", sandbox_id))
49
+ return {"id": sandbox_id, "status": self.status, "error": "image not found"}
50
+
51
+ def write_file(self, sandbox_id, path, content):
52
+ self.calls.append(("write_file", path))
53
+ local = self._map(path)
54
+ os.makedirs(os.path.dirname(local), exist_ok=True)
55
+ with open(local, "w", encoding="utf-8") as f:
56
+ f.write(content)
57
+ return {}
58
+
59
+ def start_command(self, sandbox_id, cmd):
60
+ self.calls.append(("start_command", cmd))
61
+ args = [sys.executable if a == "python3" else a for a in self._map(cmd)]
62
+ proc = subprocess.Popen(args, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
63
+ exec_id = f"ex_{len(self.processes)}"
64
+ self.processes[exec_id] = proc
65
+ return {"id": exec_id}
66
+
67
+ def run_command(self, sandbox_id, cmd, stdin=None, timeout_s=None):
68
+ self.calls.append(("run_command", cmd))
69
+ if cmd[1:3] == ["-m", "pip"]:
70
+ return {"exit_code": 0, "stdout": "", "stderr": "", "timed_out": False}
71
+ args = [sys.executable if a == "python3" else a for a in self._map(cmd)]
72
+ done = subprocess.run(args, input=stdin, capture_output=True, text=True, timeout=timeout_s)
73
+ return {"exit_code": done.returncode, "stdout": done.stdout, "stderr": done.stderr, "timed_out": False}
74
+
75
+ def get_command_output(self, sandbox_id, exec_id):
76
+ return {"stdout": "", "stderr": ""}
77
+
78
+ def kill_command(self, sandbox_id, exec_id):
79
+ self.calls.append(("kill_command", exec_id))
80
+ proc = self.processes.get(exec_id)
81
+ if proc and proc.poll() is None:
82
+ proc.kill()
83
+ proc.wait()
84
+ return {}
85
+
86
+ def delete_sandbox(self, sandbox_id):
87
+ self.calls.append(("delete_sandbox", sandbox_id))
88
+ self.deleted.append(sandbox_id)
89
+ self.close()
90
+ return {}
91
+
92
+ def close(self):
93
+ for proc in self.processes.values():
94
+ if proc.poll() is None:
95
+ proc.kill()
96
+ proc.wait()
97
+ shutil.rmtree(self.root, ignore_errors=True)
98
+
99
+
100
+ @pytest.fixture
101
+ def logger():
102
+ return AgentLogger(level=LogLevel.OFF)
103
+
104
+
105
+ @pytest.fixture
106
+ def local_client():
107
+ client = LocalGroundbox()
108
+ yield client
109
+ client.close()
110
+
111
+
112
+ class ScriptedModel(Model):
113
+ """A model that answers with fixed code actions, for running CodeAgent with no LLM."""
114
+
115
+ def __init__(self, actions: list[str]):
116
+ super().__init__(model_id="scripted")
117
+ self.actions = list(actions)
118
+
119
+ def generate(self, messages, stop_sequences=None, response_format=None, tools_to_call_from=None, **kwargs):
120
+ code = self.actions.pop(0)
121
+ return ChatMessage(role=MessageRole.ASSISTANT, content=f"Thought: next step.\n<code>\n{code}\n</code>")
@@ -0,0 +1,165 @@
1
+ from __future__ import annotations
2
+
3
+ import pytest
4
+ from conftest import LocalGroundbox, ScriptedModel
5
+ from smolagents import CodeAgent
6
+ from smolagents.default_tools import FinalAnswerTool
7
+ from smolagents.tools import Tool
8
+ from smolagents.utils import AgentError
9
+
10
+ from smolagents_groundbox import GroundboxExecutor
11
+
12
+
13
+ class AddTool(Tool):
14
+ name = "add"
15
+ description = "Adds two integers."
16
+ inputs = {
17
+ "a": {"type": "integer", "description": "first"},
18
+ "b": {"type": "integer", "description": "second"},
19
+ }
20
+ output_type = "integer"
21
+
22
+ def forward(self, a: int, b: int) -> int:
23
+ return a + b
24
+
25
+
26
+ @pytest.fixture
27
+ def executor(local_client, logger):
28
+ ex = GroundboxExecutor(logger=logger, client=local_client, timeout_seconds=5)
29
+ yield ex
30
+ ex.cleanup()
31
+
32
+
33
+ def test_creates_sandbox_with_defaults_and_overrides(local_client, logger):
34
+ ex = GroundboxExecutor(logger=logger, client=local_client, create_kwargs={"cpus": 2, "timeout_minutes": 10})
35
+ assert local_client.created_with["cpus"] == 2
36
+ assert local_client.created_with["timeout_minutes"] == 10
37
+ assert local_client.created_with["metadata"] == {"created_by": "smolagents-groundbox"}
38
+ ex.cleanup()
39
+ assert local_client.deleted == ["sbx_local"]
40
+
41
+
42
+ def test_state_is_kept_between_calls(executor):
43
+ assert executor("x = 41").output is None
44
+ out = executor("x += 1\nprint('x is', x)\nx")
45
+ assert out.output == "42"
46
+ assert out.logs == "x is 42\n"
47
+ assert out.is_final_answer is False
48
+ executor("def double(n):\n return n * 2")
49
+ assert executor("double(x)").output == "84"
50
+
51
+
52
+ def test_captures_subprocess_output(executor):
53
+ out = executor("import subprocess\nsubprocess.run(['echo', 'from a child'])\nprint('after')")
54
+ assert out.logs == "from a child\nafter\n"
55
+
56
+
57
+ def test_error_raises_agent_error_and_keeps_state(executor):
58
+ executor("y = 'kept'")
59
+ with pytest.raises(AgentError) as info:
60
+ executor("print('before')\n1 / 0")
61
+ message = str(info.value)
62
+ assert "before" in message
63
+ assert "Executing code yielded an error:\nZeroDivisionError" in message
64
+ assert "1 / 0" in message # the traceback shows the line
65
+ assert executor("y").output == "'kept'"
66
+
67
+
68
+ def test_syntax_error(executor):
69
+ with pytest.raises(AgentError, match="SyntaxError"):
70
+ executor("def broken(:")
71
+
72
+
73
+ def test_sys_exit_does_not_end_the_kernel(executor):
74
+ executor("z = 5")
75
+ with pytest.raises(AgentError, match="SystemExit"):
76
+ executor("import sys\nsys.exit(3)")
77
+ assert executor("z").output == "5"
78
+
79
+
80
+ def test_timeout_interrupts_and_keeps_state(local_client, logger):
81
+ ex = GroundboxExecutor(logger=logger, client=local_client, timeout_seconds=1)
82
+ try:
83
+ ex("w = 'still here'")
84
+ with pytest.raises(AgentError, match="ExecutionTimeout"):
85
+ ex("import time\ntime.sleep(10)")
86
+ assert ex("w").output == "'still here'"
87
+ finally:
88
+ ex.cleanup()
89
+
90
+
91
+ def test_kernel_crash_is_restarted(executor):
92
+ executor("v = 1")
93
+ with pytest.raises(AgentError, match="was restarted"):
94
+ executor("import os\nos._exit(1)")
95
+ with pytest.raises(AgentError, match="NameError"):
96
+ executor("v")
97
+ assert executor("1 + 1").output == "2"
98
+
99
+
100
+ def test_send_variables(executor):
101
+ executor.send_variables({"numbers": [1, 2, 3], "name": "box", "pair": (1, "a")})
102
+ assert executor("sum(numbers), name, pair").output == "(6, 'box', (1, 'a'))"
103
+
104
+
105
+ def test_final_answer_and_tools(executor):
106
+ executor.send_tools({"add": AddTool(), "final_answer": FinalAnswerTool()})
107
+ assert executor("add(2, 3)").output == "5"
108
+ out = executor("total = add(20, 22)\nprint('done')\nfinal_answer({'total': total, 'items': (1, 2)})")
109
+ assert out.is_final_answer is True
110
+ assert out.output == {"total": 42, "items": (1, 2)}
111
+ assert out.logs == "done\n"
112
+
113
+
114
+ def test_attached_sandbox_is_not_deleted(local_client, logger):
115
+ ex = GroundboxExecutor(logger=logger, client=local_client, sandbox_id="sbx_mine")
116
+ assert ex("2 * 21").output == "42"
117
+ ex.cleanup()
118
+ assert local_client.deleted == []
119
+ assert ("kill_command", "ex_0") in local_client.calls
120
+ assert not any(call[0] == "create_sandbox" for call in local_client.calls)
121
+
122
+
123
+ def test_failed_sandbox_is_cleaned_up(logger):
124
+ client = LocalGroundbox(status="failed")
125
+ try:
126
+ with pytest.raises(RuntimeError, match="image not found"):
127
+ GroundboxExecutor(logger=logger, client=client)
128
+ assert client.deleted == ["sbx_local"]
129
+ finally:
130
+ client.close()
131
+
132
+
133
+ def test_install_packages_retries_without_break_system_packages(local_client, logger):
134
+ ex = GroundboxExecutor(logger=logger, client=local_client)
135
+ pip_calls = []
136
+
137
+ def fake_run(sandbox_id, cmd, stdin=None, timeout_s=None):
138
+ pip_calls.append(cmd)
139
+ if "--break-system-packages" in cmd:
140
+ return {"exit_code": 2, "stdout": "", "stderr": "no such option: --break-system-packages"}
141
+ return {"exit_code": 0, "stdout": "", "stderr": ""}
142
+
143
+ real_run = local_client.run_command
144
+ local_client.run_command = fake_run
145
+ try:
146
+ assert ex.install_packages(["requests"]) == ["requests"]
147
+ assert len(pip_calls) == 2 and "--break-system-packages" not in pip_calls[1]
148
+ finally:
149
+ local_client.run_command = real_run
150
+ ex.cleanup()
151
+
152
+
153
+ def test_code_agent_end_to_end_with_scripted_model(local_client, logger):
154
+ model = ScriptedModel(
155
+ [
156
+ "base = add(40, 1)\nprint('base', base)",
157
+ "final_answer(base + 1)",
158
+ ]
159
+ )
160
+ ex = GroundboxExecutor(logger=logger, client=local_client)
161
+ with CodeAgent(tools=[AddTool()], model=model, executor=ex, verbosity_level=-1) as agent:
162
+ assert agent.run("What is 40 + 1 + 1?") == 42
163
+ observations = [getattr(step, "observations", None) for step in agent.memory.steps]
164
+ assert any(o and "base 41" in o for o in observations)
165
+ assert local_client.deleted == ["sbx_local"]
@@ -0,0 +1,86 @@
1
+ """Against Groundbox itself. Runs only with GROUNDBOX_API_KEY set; creates and deletes one sandbox per test."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import os
6
+
7
+ import pytest
8
+ from conftest import ScriptedModel
9
+ from smolagents import CodeAgent
10
+ from smolagents.default_tools import FinalAnswerTool
11
+ from smolagents.tools import Tool
12
+ from smolagents.utils import AgentError
13
+
14
+ from smolagents_groundbox import GroundboxExecutor
15
+
16
+ pytestmark = pytest.mark.skipif(not os.environ.get("GROUNDBOX_API_KEY"), reason="GROUNDBOX_API_KEY is not set")
17
+
18
+
19
+ class AddTool(Tool):
20
+ name = "add"
21
+ description = "Adds two integers."
22
+ inputs = {
23
+ "a": {"type": "integer", "description": "first"},
24
+ "b": {"type": "integer", "description": "second"},
25
+ }
26
+ output_type = "integer"
27
+
28
+ def forward(self, a: int, b: int) -> int:
29
+ return a + b
30
+
31
+
32
+ def _assert_gone(executor):
33
+ status = executor.client.get_sandbox(executor.sandbox_id).get("status")
34
+ assert status not in ("running", "queued", "starting", "paused"), status
35
+
36
+
37
+ def test_live_executor(logger):
38
+ ex = GroundboxExecutor(
39
+ additional_imports=["pillow"],
40
+ logger=logger,
41
+ timeout_seconds=5,
42
+ create_kwargs={"cpus": 1, "timeout_minutes": 15, "metadata": {"test": "smolagents-groundbox"}},
43
+ )
44
+ try:
45
+ # State between calls.
46
+ ex("import platform\ncount = 1")
47
+ out = ex("count += 1\nprint('running on', platform.system())\ncount")
48
+ assert out.output == "2"
49
+ assert out.logs == "running on Linux\n"
50
+
51
+ # Errors, with state kept.
52
+ with pytest.raises(AgentError, match="ZeroDivisionError"):
53
+ ex("1 / 0")
54
+ assert ex("count").output == "2"
55
+
56
+ # A step past timeout_seconds is interrupted, state kept.
57
+ with pytest.raises(AgentError, match="ExecutionTimeout"):
58
+ ex("import time\ntime.sleep(30)")
59
+ assert ex("count").output == "2"
60
+
61
+ # A package from additional_imports, and an image result.
62
+ img = ex("from PIL import Image\nImage.new('RGB', (4, 3), 'red')").output
63
+ assert img.size == (4, 3)
64
+
65
+ # Variables, tools and final_answer, as CodeAgent sends them.
66
+ ex.send_variables({"numbers": [1, 2, 3]})
67
+ ex.send_tools({"add": AddTool(), "final_answer": FinalAnswerTool()})
68
+ out = ex("final_answer({'sum': add(sum(numbers), 36), 'count': count})")
69
+ assert out.is_final_answer is True
70
+ assert out.output == {"sum": 42, "count": 2}
71
+ finally:
72
+ ex.cleanup()
73
+ _assert_gone(ex)
74
+
75
+
76
+ def test_live_code_agent_with_scripted_model(logger):
77
+ model = ScriptedModel(
78
+ [
79
+ "import os\nwho = os.popen('id -un').read().strip()\nprint('user', who)\nbase = add(40, 1)",
80
+ "final_answer(f'{who}:{base + 1}')",
81
+ ]
82
+ )
83
+ ex = GroundboxExecutor(logger=logger, create_kwargs={"cpus": 1, "timeout_minutes": 15})
84
+ with CodeAgent(tools=[AddTool()], model=model, executor=ex, verbosity_level=-1) as agent:
85
+ assert agent.run("Add one to forty, then one more.") == "runner:42"
86
+ _assert_gone(ex)