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.
- smolagents_groundbox-0.1.0/.gitignore +6 -0
- smolagents_groundbox-0.1.0/LICENSE +9 -0
- smolagents_groundbox-0.1.0/PKG-INFO +126 -0
- smolagents_groundbox-0.1.0/README.md +104 -0
- smolagents_groundbox-0.1.0/pyproject.toml +35 -0
- smolagents_groundbox-0.1.0/src/smolagents_groundbox/__init__.py +6 -0
- smolagents_groundbox-0.1.0/src/smolagents_groundbox/_kernel.py +233 -0
- smolagents_groundbox-0.1.0/src/smolagents_groundbox/executor.py +283 -0
- smolagents_groundbox-0.1.0/src/smolagents_groundbox/py.typed +0 -0
- smolagents_groundbox-0.1.0/tests/conftest.py +121 -0
- smolagents_groundbox-0.1.0/tests/test_executor.py +165 -0
- smolagents_groundbox-0.1.0/tests/test_live.py +86 -0
|
@@ -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,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
|
|
File without changes
|
|
@@ -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)
|