smolagents-plimsoll 0.28.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_plimsoll-0.28.0/LICENSE +201 -0
- smolagents_plimsoll-0.28.0/PKG-INFO +178 -0
- smolagents_plimsoll-0.28.0/README.md +159 -0
- smolagents_plimsoll-0.28.0/pyproject.toml +38 -0
- smolagents_plimsoll-0.28.0/setup.cfg +4 -0
- smolagents_plimsoll-0.28.0/src/smolagents_plimsoll/__init__.py +26 -0
- smolagents_plimsoll-0.28.0/src/smolagents_plimsoll/py.typed +0 -0
- smolagents_plimsoll-0.28.0/src/smolagents_plimsoll.egg-info/PKG-INFO +178 -0
- smolagents_plimsoll-0.28.0/src/smolagents_plimsoll.egg-info/SOURCES.txt +10 -0
- smolagents_plimsoll-0.28.0/src/smolagents_plimsoll.egg-info/dependency_links.txt +1 -0
- smolagents_plimsoll-0.28.0/src/smolagents_plimsoll.egg-info/requires.txt +2 -0
- smolagents_plimsoll-0.28.0/src/smolagents_plimsoll.egg-info/top_level.txt +1 -0
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
Apache License
|
|
2
|
+
Version 2.0, January 2004
|
|
3
|
+
http://www.apache.org/licenses/
|
|
4
|
+
|
|
5
|
+
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
6
|
+
|
|
7
|
+
1. Definitions.
|
|
8
|
+
|
|
9
|
+
"License" shall mean the terms and conditions for use, reproduction,
|
|
10
|
+
and distribution as defined by Sections 1 through 9 of this document.
|
|
11
|
+
|
|
12
|
+
"Licensor" shall mean the copyright owner or entity authorized by
|
|
13
|
+
the copyright owner that is granting the License.
|
|
14
|
+
|
|
15
|
+
"Legal Entity" shall mean the union of the acting entity and all
|
|
16
|
+
other entities that control, are controlled by, or are under common
|
|
17
|
+
control with that entity. For the purposes of this definition,
|
|
18
|
+
"control" means (i) the power, direct or indirect, to cause the
|
|
19
|
+
direction or management of such entity, whether by contract or
|
|
20
|
+
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
|
21
|
+
outstanding shares, or (iii) beneficial ownership of such entity.
|
|
22
|
+
|
|
23
|
+
"You" (or "Your") shall mean an individual or Legal Entity
|
|
24
|
+
exercising permissions granted by this License.
|
|
25
|
+
|
|
26
|
+
"Source" form shall mean the preferred form for making modifications,
|
|
27
|
+
including but not limited to software source code, documentation
|
|
28
|
+
source, and configuration files.
|
|
29
|
+
|
|
30
|
+
"Object" form shall mean any form resulting from mechanical
|
|
31
|
+
transformation or translation of a Source form, including but
|
|
32
|
+
not limited to compiled object code, generated documentation,
|
|
33
|
+
and conversions to other media types.
|
|
34
|
+
|
|
35
|
+
"Work" shall mean the work of authorship, whether in Source or
|
|
36
|
+
Object form, made available under the License, as indicated by a
|
|
37
|
+
copyright notice that is included in or attached to the work
|
|
38
|
+
(an example is provided in the Appendix below).
|
|
39
|
+
|
|
40
|
+
"Derivative Works" shall mean any work, whether in Source or Object
|
|
41
|
+
form, that is based on (or derived from) the Work and for which the
|
|
42
|
+
editorial revisions, annotations, elaborations, or other modifications
|
|
43
|
+
represent, as a whole, an original work of authorship. For the purposes
|
|
44
|
+
of this License, Derivative Works shall not include works that remain
|
|
45
|
+
separable from, or merely link (or bind by name) to the interfaces of,
|
|
46
|
+
the Work and Derivative Works thereof.
|
|
47
|
+
|
|
48
|
+
"Contribution" shall mean any work of authorship, including
|
|
49
|
+
the original version of the Work and any modifications or additions
|
|
50
|
+
to that Work or Derivative Works thereof, that is intentionally
|
|
51
|
+
submitted to Licensor for inclusion in the Work by the copyright owner
|
|
52
|
+
or by an individual or Legal Entity authorized to submit on behalf of
|
|
53
|
+
the copyright owner. For the purposes of this definition, "submitted"
|
|
54
|
+
means any form of electronic, verbal, or written communication sent
|
|
55
|
+
to the Licensor or its representatives, including but not limited to
|
|
56
|
+
communication on electronic mailing lists, source code control systems,
|
|
57
|
+
and issue tracking systems that are managed by, or on behalf of, the
|
|
58
|
+
Licensor for the purpose of discussing and improving the Work, but
|
|
59
|
+
excluding communication that is conspicuously marked or otherwise
|
|
60
|
+
designated in writing by the copyright owner as "Not a Contribution."
|
|
61
|
+
|
|
62
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity
|
|
63
|
+
on behalf of whom a Contribution has been received by Licensor and
|
|
64
|
+
subsequently incorporated within the Work.
|
|
65
|
+
|
|
66
|
+
2. Grant of Copyright License. Subject to the terms and conditions of
|
|
67
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
68
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
69
|
+
copyright license to reproduce, prepare Derivative Works of,
|
|
70
|
+
publicly display, publicly perform, sublicense, and distribute the
|
|
71
|
+
Work and such Derivative Works in Source or Object form.
|
|
72
|
+
|
|
73
|
+
3. Grant of Patent License. Subject to the terms and conditions of
|
|
74
|
+
this License, each Contributor hereby grants to You a perpetual,
|
|
75
|
+
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
|
76
|
+
(except as stated in this section) patent license to make, have made,
|
|
77
|
+
use, offer to sell, sell, import, and otherwise transfer the Work,
|
|
78
|
+
where such license applies only to those patent claims licensable
|
|
79
|
+
by such Contributor that are necessarily infringed by their
|
|
80
|
+
Contribution(s) alone or by combination of their Contribution(s)
|
|
81
|
+
with the Work to which such Contribution(s) was submitted. If You
|
|
82
|
+
institute patent litigation against any entity (including a
|
|
83
|
+
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
|
84
|
+
or a Contribution incorporated within the Work constitutes direct
|
|
85
|
+
or contributory patent infringement, then any patent licenses
|
|
86
|
+
granted to You under this License for that Work shall terminate
|
|
87
|
+
as of the date such litigation is filed.
|
|
88
|
+
|
|
89
|
+
4. Redistribution. You may reproduce and distribute copies of the
|
|
90
|
+
Work or Derivative Works thereof in any medium, with or without
|
|
91
|
+
modifications, and in Source or Object form, provided that You
|
|
92
|
+
meet the following conditions:
|
|
93
|
+
|
|
94
|
+
(a) You must give any other recipients of the Work or
|
|
95
|
+
Derivative Works a copy of this License; and
|
|
96
|
+
|
|
97
|
+
(b) You must cause any modified files to carry prominent notices
|
|
98
|
+
stating that You changed the files; and
|
|
99
|
+
|
|
100
|
+
(c) You must retain, in the Source form of any Derivative Works
|
|
101
|
+
that You distribute, all copyright, patent, trademark, and
|
|
102
|
+
attribution notices from the Source form of the Work,
|
|
103
|
+
excluding those notices that do not pertain to any part of
|
|
104
|
+
the Derivative Works; and
|
|
105
|
+
|
|
106
|
+
(d) If the Work includes a "NOTICE" text file as part of its
|
|
107
|
+
distribution, then any Derivative Works that You distribute must
|
|
108
|
+
include a readable copy of the attribution notices contained
|
|
109
|
+
within such NOTICE file, excluding those notices that do not
|
|
110
|
+
pertain to any part of the Derivative Works, in at least one
|
|
111
|
+
of the following places: within a NOTICE text file distributed
|
|
112
|
+
as part of the Derivative Works; within the Source form or
|
|
113
|
+
documentation, if provided along with the Derivative Works; or,
|
|
114
|
+
within a display generated by the Derivative Works, if and
|
|
115
|
+
wherever such third-party notices normally appear. The contents
|
|
116
|
+
of the NOTICE file are for informational purposes only and
|
|
117
|
+
do not modify the License. You may add Your own attribution
|
|
118
|
+
notices within Derivative Works that You distribute, alongside
|
|
119
|
+
or as an addendum to the NOTICE text from the Work, provided
|
|
120
|
+
that such additional attribution notices cannot be construed
|
|
121
|
+
as modifying the License.
|
|
122
|
+
|
|
123
|
+
You may add Your own copyright statement to Your modifications and
|
|
124
|
+
may provide additional or different license terms and conditions
|
|
125
|
+
for use, reproduction, or distribution of Your modifications, or
|
|
126
|
+
for any such Derivative Works as a whole, provided Your use,
|
|
127
|
+
reproduction, and distribution of the Work otherwise complies with
|
|
128
|
+
the conditions stated in this License.
|
|
129
|
+
|
|
130
|
+
5. Submission of Contributions. Unless You explicitly state otherwise,
|
|
131
|
+
any Contribution intentionally submitted for inclusion in the Work
|
|
132
|
+
by You to the Licensor shall be under the terms and conditions of
|
|
133
|
+
this License, without any additional terms or conditions.
|
|
134
|
+
Notwithstanding the above, nothing herein shall supersede or modify
|
|
135
|
+
the terms of any separate license agreement you may have executed
|
|
136
|
+
with Licensor regarding such Contributions.
|
|
137
|
+
|
|
138
|
+
6. Trademarks. This License does not grant permission to use the trade
|
|
139
|
+
names, trademarks, service marks, or product names of the Licensor,
|
|
140
|
+
except as required for reasonable and customary use in describing the
|
|
141
|
+
origin of the Work and reproducing the content of the NOTICE file.
|
|
142
|
+
|
|
143
|
+
7. Disclaimer of Warranty. Unless required by applicable law or
|
|
144
|
+
agreed to in writing, Licensor provides the Work (and each
|
|
145
|
+
Contributor provides its Contributions) on an "AS IS" BASIS,
|
|
146
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
|
147
|
+
implied, including, without limitation, any warranties or conditions
|
|
148
|
+
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
|
149
|
+
PARTICULAR PURPOSE. You are solely responsible for determining the
|
|
150
|
+
appropriateness of using or redistributing the Work and assume any
|
|
151
|
+
risks associated with Your exercise of permissions under this License.
|
|
152
|
+
|
|
153
|
+
8. Limitation of Liability. In no event and under no legal theory,
|
|
154
|
+
whether in tort (including negligence), contract, or otherwise,
|
|
155
|
+
unless required by applicable law (such as deliberate and grossly
|
|
156
|
+
negligent acts) or agreed to in writing, shall any Contributor be
|
|
157
|
+
liable to You for damages, including any direct, indirect, special,
|
|
158
|
+
incidental, or consequential damages of any character arising as a
|
|
159
|
+
result of this License or out of the use or inability to use the
|
|
160
|
+
Work (including but not limited to damages for loss of goodwill,
|
|
161
|
+
work stoppage, computer failure or malfunction, or any and all
|
|
162
|
+
other commercial damages or losses), even if such Contributor
|
|
163
|
+
has been advised of the possibility of such damages.
|
|
164
|
+
|
|
165
|
+
9. Accepting Warranty or Additional Liability. While redistributing
|
|
166
|
+
the Work or Derivative Works thereof, You may choose to offer,
|
|
167
|
+
and charge a fee for, acceptance of support, warranty, indemnity,
|
|
168
|
+
or other liability obligations and/or rights consistent with this
|
|
169
|
+
License. However, in accepting such obligations, You may act only
|
|
170
|
+
on Your own behalf and on Your sole responsibility, not on behalf
|
|
171
|
+
of any other Contributor, and only if You agree to indemnify,
|
|
172
|
+
defend, and hold each Contributor harmless for any liability
|
|
173
|
+
incurred by, or claims asserted against, such Contributor by reason
|
|
174
|
+
of your accepting any such warranty or additional liability.
|
|
175
|
+
|
|
176
|
+
END OF TERMS AND CONDITIONS
|
|
177
|
+
|
|
178
|
+
APPENDIX: How to apply the Apache License to your work.
|
|
179
|
+
|
|
180
|
+
To apply the Apache License to your work, attach the following
|
|
181
|
+
boilerplate notice, with the fields enclosed by brackets "[]"
|
|
182
|
+
replaced with your own identifying information. (Don't include
|
|
183
|
+
the brackets!) The text should be enclosed in the appropriate
|
|
184
|
+
comment syntax for the file format. We also recommend that a
|
|
185
|
+
file or class name and description of purpose be included on the
|
|
186
|
+
same "printed page" as the copyright notice for easier
|
|
187
|
+
identification within third-party archives.
|
|
188
|
+
|
|
189
|
+
Copyright 2026 Carroll Guertin
|
|
190
|
+
|
|
191
|
+
Licensed under the Apache License, Version 2.0 (the "License");
|
|
192
|
+
you may not use this file except in compliance with the License.
|
|
193
|
+
You may obtain a copy of the License at
|
|
194
|
+
|
|
195
|
+
http://www.apache.org/licenses/LICENSE-2.0
|
|
196
|
+
|
|
197
|
+
Unless required by applicable law or agreed to in writing, software
|
|
198
|
+
distributed under the License is distributed on an "AS IS" BASIS,
|
|
199
|
+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
200
|
+
See the License for the specific language governing permissions and
|
|
201
|
+
limitations under the License.
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: smolagents-plimsoll
|
|
3
|
+
Version: 0.28.0
|
|
4
|
+
Summary: A smolagents CodeAgent executor that runs agent-written code in plimsoll, a self-hosted sandbox that refuses to run below the isolation you require
|
|
5
|
+
License-Expression: Apache-2.0
|
|
6
|
+
Project-URL: Homepage, https://github.com/plimsollmark/plimsoll/tree/main/clients/python/smolagents-plimsoll
|
|
7
|
+
Project-URL: Source, https://github.com/plimsollmark/plimsoll/tree/main/clients/python/smolagents-plimsoll
|
|
8
|
+
Project-URL: Issues, https://github.com/plimsollmark/plimsoll/issues
|
|
9
|
+
Keywords: smolagents,codeagent,sandbox,code execution,agents,gvisor
|
|
10
|
+
Classifier: Programming Language :: Python :: 3
|
|
11
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
12
|
+
Classifier: Typing :: Typed
|
|
13
|
+
Requires-Python: >=3.10
|
|
14
|
+
Description-Content-Type: text/markdown
|
|
15
|
+
License-File: LICENSE
|
|
16
|
+
Requires-Dist: smolagents==1.26.0
|
|
17
|
+
Requires-Dist: plimsoll-client==0.28.0
|
|
18
|
+
Dynamic: license-file
|
|
19
|
+
|
|
20
|
+
# smolagents-plimsoll
|
|
21
|
+
|
|
22
|
+
A smolagents `CodeAgent` acts by writing Python, and its default executor runs that Python in your own process. This
|
|
23
|
+
package runs it in plimsoll instead, a sandbox service you run yourself, possibly somewhere else, and it has no fallback:
|
|
24
|
+
if the sandbox is weaker than you asked for, nothing runs.
|
|
25
|
+
|
|
26
|
+
**`PlimsollExecutor`** is the agent's Python executor over one plimsoll session: each step of the agent is one cell in
|
|
27
|
+
the session's Python interpreter, so the variables, functions and imports one step defines are there in the next.
|
|
28
|
+
**`code_agent`** builds the `CodeAgent` around it, so that a failure of the sandbox stops the run.
|
|
29
|
+
|
|
30
|
+
## Install
|
|
31
|
+
|
|
32
|
+
```sh
|
|
33
|
+
pip install smolagents-plimsoll
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
It needs a running `plimsolld`, the plimsoll daemon, reachable from the agent
|
|
37
|
+
([getting started (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/getting-started.md)).
|
|
38
|
+
The executor needs a provider with sessions: docker (with a project image that has Python, such as `plimsoll/sandbox-python`), E2B or OpenShell today
|
|
39
|
+
([which providers (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/sessions.md#which-providers)).
|
|
40
|
+
Sessions are off until the daemon is started with `SANDBOX_MAX_SESSIONS` set (for example `SANDBOX_MAX_SESSIONS=4`);
|
|
41
|
+
without it building the executor raises plimsoll's `UnsupportedError`, saying the daemon has no sessions.
|
|
42
|
+
On a daemon whose image has no Python, building the executor raises plimsoll's refusal and closes the session.
|
|
43
|
+
Python 3.10 or later, as smolagents requires.
|
|
44
|
+
|
|
45
|
+
## Use
|
|
46
|
+
|
|
47
|
+
```python
|
|
48
|
+
from smolagents import AgentLogger, LogLevel
|
|
49
|
+
from smolagents_plimsoll import Client, PlimsollExecutor, code_agent
|
|
50
|
+
|
|
51
|
+
executor = PlimsollExecutor([], AgentLogger(LogLevel.INFO),
|
|
52
|
+
client=Client("https://plimsoll.internal:8746", token=TOKEN),
|
|
53
|
+
minimum_isolation="kernel")
|
|
54
|
+
with code_agent(executor, tools=[], model=model) as agent: # closes the session after
|
|
55
|
+
print(agent.run("What is the 20th Fibonacci number?"))
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
`model` is any smolagents model, such as `InferenceClientModel` or `LiteLLMModel`. The first argument,
|
|
59
|
+
`additional_imports`, must be empty (nothing is installed, below), and the second is a smolagents logger, as for
|
|
60
|
+
smolagents' own executors. Building the executor opens the session and checks its tier; leaving the `with` block, or
|
|
61
|
+
`agent.cleanup()`, closes it, and the sandbox and its files are gone.
|
|
62
|
+
|
|
63
|
+
## What the executor needs and does
|
|
64
|
+
|
|
65
|
+
- **The floor is yours to set.** `minimum_isolation` (`process`, `container`, `kernel` or `vm`) has no default. When the
|
|
66
|
+
session opens, its tier is checked against the floor before any of the agent's code is sent; below it, the session is
|
|
67
|
+
closed and `InsufficientIsolationError` is raised.
|
|
68
|
+
- **Build the agent with `code_agent`.** smolagents turns every error an executor raises into an error its model is
|
|
69
|
+
shown, and goes on to the next step. So the executor keeps the first error after which the run cannot go on as
|
|
70
|
+
`executor.fatal_error` and sends nothing more, and the agent `code_agent` builds stops at the end of that step: its
|
|
71
|
+
`run` raises that error, plimsoll's own, in place of smolagents' "Agent interrupted.". Those errors are: a cell
|
|
72
|
+
plimsoll refused before anything ran; a cell that may have run without an answer to show for it (any error of the
|
|
73
|
+
session's call that is not a refusal, plimsoll's or not); a cell on a session that has ended (its lifetime ran out, or
|
|
74
|
+
the daemon closed it); and a step that finds the sandbox's interpreter restarted, so the variables and tools of the
|
|
75
|
+
earlier steps are gone. With `stream=True` the steps are handed on as they come and the error is raised in place of
|
|
76
|
+
the final answer. A plain `CodeAgent(executor=executor)` sends nothing more either, but goes on asking its model until
|
|
77
|
+
`max_steps` and then returns the model's own answer, made up after the sandbox failed; check `executor.fatal_error`
|
|
78
|
+
after such a run.
|
|
79
|
+
- **The code's own errors are the model's to fix.** An exception the agent's code raises comes back to the model as
|
|
80
|
+
smolagents' `AgentError`, with what the step printed and the traceback, as smolagents' own remote executors report it.
|
|
81
|
+
- **Each step has a time budget,** `timeout`, 120 seconds unless you set it; the daemon cuts a longer budget to its own
|
|
82
|
+
limit for a call (120 seconds by default on docker). A step past its budget is stopped and the sandbox ends its
|
|
83
|
+
interpreter: the model is told, and the next step finds the interpreter restarted, which ends the run.
|
|
84
|
+
- **A step that prints past the sandbox's output limit** (64 KiB by default on docker) loses its result, which comes at
|
|
85
|
+
the end of its output: the model is shown that the output was cut, and the run goes on.
|
|
86
|
+
- **One session for the run.** `lifetime` (seconds, 3600 unless you set it) may only shorten the daemon's own session
|
|
87
|
+
lifetime (30 minutes by default), and a run that outlasts it ends with `SessionEndedError` at its next step. A session
|
|
88
|
+
with no call for the daemon's idle timeout (5 minutes by default), while the model takes its time, is suspended: on
|
|
89
|
+
docker its interpreter is kept, but on E2B and OpenShell a suspend ends it, so the next step finds it restarted and the
|
|
90
|
+
run ends. A session
|
|
91
|
+
is one trust domain: everything a step does is there for every later step, so use one executor for one agent and one
|
|
92
|
+
user ([who may share a session (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/sessions.md#who-may-share-a-session)).
|
|
93
|
+
`owner` names that user for a daemon's per-owner cap. The executor needs a `plimsoll_client.Client`; an `AsyncClient`
|
|
94
|
+
raises `TypeError`, since smolagents calls its executor synchronously.
|
|
95
|
+
|
|
96
|
+
## Limits, stated plainly
|
|
97
|
+
|
|
98
|
+
- **No pickle, ever.** smolagents' `allow_pickle=True` lets a final answer travel from the sandbox as a pickle, and
|
|
99
|
+
unpickling it in your process runs code the sandbox chose there: code in the sandbox could then run code outside it,
|
|
100
|
+
which is what the sandbox is there to prevent. `PlimsollExecutor(..., allow_pickle=True)` raises `ValueError` before
|
|
101
|
+
a session is opened, and so does setting the attribute later; a final answer that arrives as a pickle anyway is
|
|
102
|
+
refused unread. Variables (`agent.run(..., additional_args=...)`) travel as JSON-safe values only, as smolagents' own
|
|
103
|
+
executors send them without pickle.
|
|
104
|
+
- **The final answer is plain data.** The executor sends its own definition of the `final_answer` tool, which carries
|
|
105
|
+
what smolagents' own carries (JSON values, tuples, sets, bytes, dates and times, decimals, paths, and dataclasses, as
|
|
106
|
+
a dictionary), with no NumPy or Pillow import, because `plimsoll/sandbox-python` has no Pillow. A final answer that
|
|
107
|
+
is an image, a NumPy array or a NumPy number (`numpy.int64(3)`, say) is refused with an error the model is shown, so
|
|
108
|
+
it can answer with a plain value (`value.tolist()`, `value.item()`). One that claims to be an image, an array, or any
|
|
109
|
+
kind the executor's own definition does not write is refused in your process too, with the kind named: smolagents'
|
|
110
|
+
reader runs in your process and learns new kinds with new releases, so it is handed only the kinds listed above and
|
|
111
|
+
Pillow never opens bytes from the sandbox. For the same reason a dictionary with a key named `__type__` is carried
|
|
112
|
+
only when that key holds one of those kinds' own marks.
|
|
113
|
+
- **Nothing is installed.** smolagents asks its executor to install every package a tool's code imports from outside
|
|
114
|
+
Python's standard library, and this executor refuses any install: a plimsoll sandbox has no network by default, and
|
|
115
|
+
packages belong in the image its operator runs. So a tool whose code imports `numpy` makes `agent.run` raise
|
|
116
|
+
`ValueError` when the run starts, before anything is sent, even though `plimsoll/sandbox-python` has NumPy and SciPy.
|
|
117
|
+
The agent's own steps can import whatever the image has.
|
|
118
|
+
- **Tools run in the sandbox, and cannot reach the network.** smolagents sends each tool's code, its class attributes
|
|
119
|
+
included, into the sandbox's interpreter, and the tool runs there, in the step's cell; so anything written into a
|
|
120
|
+
tool's code is visible to the agent's code. A cell carries no grant, the permission that lets a call reach an API
|
|
121
|
+
([capability grants (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/capability-grants.md)),
|
|
122
|
+
so no tool can reach the network from a step, and unlike the other kits' code tools this executor takes no grant. A
|
|
123
|
+
web search tool does not work here.
|
|
124
|
+
- **The record of a step can be forged by the agent's own code, and forges only its own answer.** The executor reads
|
|
125
|
+
each step's value, output and error from a line its own helper in the sandbox's interpreter prints, marked with a
|
|
126
|
+
random value fresh for each step. The agent's code runs in that same interpreter and can read the mark, so it can
|
|
127
|
+
forge what the executor reads back as its step's result; it can forge nothing but the agent's own answer. The run
|
|
128
|
+
record of each cell is plimsoll's: the client checks it and its place in the session's chain.
|
|
129
|
+
- **Text from the sandbox arrives printable.** smolagents' console logger prints what a step printed, a step's value and
|
|
130
|
+
the final answer on your terminal as they are (it escapes its error messages, not these), so code in the sandbox could
|
|
131
|
+
send your terminal escape sequences: a new window title, a cleared screen, or, on a terminal that allows it, the
|
|
132
|
+
clipboard. The executor writes each control character but tab, newline and carriage return as a visible escape
|
|
133
|
+
(`\x1b` for the escape character) in what a step printed, its error, a value or final answer that is text, and a final
|
|
134
|
+
answer that is a path. Text inside a list, a dictionary or another value is handed over as it came, since smolagents
|
|
135
|
+
prints such a value as its `repr`, which escapes it; escape it yourself before you print it.
|
|
136
|
+
- **Not tested:** smolagents' managed agents (an agent another agent calls as a tool, which smolagents sends to the
|
|
137
|
+
executor with the tools); any smolagents release but 1.26.0.
|
|
138
|
+
|
|
139
|
+
## What reaches your application
|
|
140
|
+
|
|
141
|
+
smolagents asks an executor only for each step's output, value or error, and the final answer. What plimsoll states
|
|
142
|
+
about each cell, none of it from what the cell's code printed, is in `executor.records`: a `PlimsollCellRecord` per cell
|
|
143
|
+
the client checked, with the tier the cell ran at (`isolation`), the sentence the provider states beside the tier
|
|
144
|
+
(`isolation_qualification`, empty when it states none), how the cell ended (`outcome`: `completed`, or `timed_out` when
|
|
145
|
+
its budget ended it), the SHA-256 of its run record (`record_sha256`), the record itself (`record`) and the checked
|
|
146
|
+
result (`result`).
|
|
147
|
+
|
|
148
|
+
```python
|
|
149
|
+
for cell in executor.records:
|
|
150
|
+
print(cell.isolation, cell.outcome, cell.record_sha256)
|
|
151
|
+
assert executor.records[-1].record_sha256 == executor.session.last_record_sha256
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
The records are in the order the cells ran: first the executor's own setup cell, then one for each call smolagents made
|
|
155
|
+
(the variables and the tools' definitions at the start of each run, then each step). So they are the session's chain of
|
|
156
|
+
records: each names the one before it, and the last is the end of the chain the client checked. A cell that answered is
|
|
157
|
+
kept whatever its code did (an error, a lost result, a timeout). A call that raised adds none; when its error carries
|
|
158
|
+
the checked record of a call that may have run, that record is `executor.fatal_error.record`.
|
|
159
|
+
|
|
160
|
+
## What it is not
|
|
161
|
+
|
|
162
|
+
- **Not a hosted service.** You run `plimsolld` on your own machine or cluster, with a provider you pick
|
|
163
|
+
([isolation tiers (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/isolation-tiers.md)).
|
|
164
|
+
- **Not attestation.** A reported tier is the daemon's configuration and provider evidence plus a startup check, not
|
|
165
|
+
hardware proof.
|
|
166
|
+
|
|
167
|
+
## Versions
|
|
168
|
+
|
|
169
|
+
This package's version moves with plimsoll's releases, and each version requires the `plimsoll-client` release of the same
|
|
170
|
+
number, which holds the code (`plimsoll_client.smolagents`). `Client`, `PlimsollExecutor`, `PlimsollCellRecord` and
|
|
171
|
+
`code_agent` here are plimsoll-client's own names, gathered so an agent imports from one place. It is tested with, and
|
|
172
|
+
installs with, exactly smolagents 1.26.0 (released 2026-05-29): pip installs that version beside it and refuses another.
|
|
173
|
+
The executor copies smolagents' final-answer protocol to send its own `final_answer` and reaches into parts of smolagents
|
|
174
|
+
that are not its public interface, so its tests pin the parts that protocol lives in, and a smolagents release that changes
|
|
175
|
+
any of them fails them instead of breaking quietly; each new release is tested before the pin moves.
|
|
176
|
+
|
|
177
|
+
Licensed under the Apache License 2.0. Source:
|
|
178
|
+
[plimsoll on GitHub (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/tree/main/clients/python/smolagents-plimsoll).
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
# smolagents-plimsoll
|
|
2
|
+
|
|
3
|
+
A smolagents `CodeAgent` acts by writing Python, and its default executor runs that Python in your own process. This
|
|
4
|
+
package runs it in plimsoll instead, a sandbox service you run yourself, possibly somewhere else, and it has no fallback:
|
|
5
|
+
if the sandbox is weaker than you asked for, nothing runs.
|
|
6
|
+
|
|
7
|
+
**`PlimsollExecutor`** is the agent's Python executor over one plimsoll session: each step of the agent is one cell in
|
|
8
|
+
the session's Python interpreter, so the variables, functions and imports one step defines are there in the next.
|
|
9
|
+
**`code_agent`** builds the `CodeAgent` around it, so that a failure of the sandbox stops the run.
|
|
10
|
+
|
|
11
|
+
## Install
|
|
12
|
+
|
|
13
|
+
```sh
|
|
14
|
+
pip install smolagents-plimsoll
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
It needs a running `plimsolld`, the plimsoll daemon, reachable from the agent
|
|
18
|
+
([getting started (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/getting-started.md)).
|
|
19
|
+
The executor needs a provider with sessions: docker (with a project image that has Python, such as `plimsoll/sandbox-python`), E2B or OpenShell today
|
|
20
|
+
([which providers (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/sessions.md#which-providers)).
|
|
21
|
+
Sessions are off until the daemon is started with `SANDBOX_MAX_SESSIONS` set (for example `SANDBOX_MAX_SESSIONS=4`);
|
|
22
|
+
without it building the executor raises plimsoll's `UnsupportedError`, saying the daemon has no sessions.
|
|
23
|
+
On a daemon whose image has no Python, building the executor raises plimsoll's refusal and closes the session.
|
|
24
|
+
Python 3.10 or later, as smolagents requires.
|
|
25
|
+
|
|
26
|
+
## Use
|
|
27
|
+
|
|
28
|
+
```python
|
|
29
|
+
from smolagents import AgentLogger, LogLevel
|
|
30
|
+
from smolagents_plimsoll import Client, PlimsollExecutor, code_agent
|
|
31
|
+
|
|
32
|
+
executor = PlimsollExecutor([], AgentLogger(LogLevel.INFO),
|
|
33
|
+
client=Client("https://plimsoll.internal:8746", token=TOKEN),
|
|
34
|
+
minimum_isolation="kernel")
|
|
35
|
+
with code_agent(executor, tools=[], model=model) as agent: # closes the session after
|
|
36
|
+
print(agent.run("What is the 20th Fibonacci number?"))
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
`model` is any smolagents model, such as `InferenceClientModel` or `LiteLLMModel`. The first argument,
|
|
40
|
+
`additional_imports`, must be empty (nothing is installed, below), and the second is a smolagents logger, as for
|
|
41
|
+
smolagents' own executors. Building the executor opens the session and checks its tier; leaving the `with` block, or
|
|
42
|
+
`agent.cleanup()`, closes it, and the sandbox and its files are gone.
|
|
43
|
+
|
|
44
|
+
## What the executor needs and does
|
|
45
|
+
|
|
46
|
+
- **The floor is yours to set.** `minimum_isolation` (`process`, `container`, `kernel` or `vm`) has no default. When the
|
|
47
|
+
session opens, its tier is checked against the floor before any of the agent's code is sent; below it, the session is
|
|
48
|
+
closed and `InsufficientIsolationError` is raised.
|
|
49
|
+
- **Build the agent with `code_agent`.** smolagents turns every error an executor raises into an error its model is
|
|
50
|
+
shown, and goes on to the next step. So the executor keeps the first error after which the run cannot go on as
|
|
51
|
+
`executor.fatal_error` and sends nothing more, and the agent `code_agent` builds stops at the end of that step: its
|
|
52
|
+
`run` raises that error, plimsoll's own, in place of smolagents' "Agent interrupted.". Those errors are: a cell
|
|
53
|
+
plimsoll refused before anything ran; a cell that may have run without an answer to show for it (any error of the
|
|
54
|
+
session's call that is not a refusal, plimsoll's or not); a cell on a session that has ended (its lifetime ran out, or
|
|
55
|
+
the daemon closed it); and a step that finds the sandbox's interpreter restarted, so the variables and tools of the
|
|
56
|
+
earlier steps are gone. With `stream=True` the steps are handed on as they come and the error is raised in place of
|
|
57
|
+
the final answer. A plain `CodeAgent(executor=executor)` sends nothing more either, but goes on asking its model until
|
|
58
|
+
`max_steps` and then returns the model's own answer, made up after the sandbox failed; check `executor.fatal_error`
|
|
59
|
+
after such a run.
|
|
60
|
+
- **The code's own errors are the model's to fix.** An exception the agent's code raises comes back to the model as
|
|
61
|
+
smolagents' `AgentError`, with what the step printed and the traceback, as smolagents' own remote executors report it.
|
|
62
|
+
- **Each step has a time budget,** `timeout`, 120 seconds unless you set it; the daemon cuts a longer budget to its own
|
|
63
|
+
limit for a call (120 seconds by default on docker). A step past its budget is stopped and the sandbox ends its
|
|
64
|
+
interpreter: the model is told, and the next step finds the interpreter restarted, which ends the run.
|
|
65
|
+
- **A step that prints past the sandbox's output limit** (64 KiB by default on docker) loses its result, which comes at
|
|
66
|
+
the end of its output: the model is shown that the output was cut, and the run goes on.
|
|
67
|
+
- **One session for the run.** `lifetime` (seconds, 3600 unless you set it) may only shorten the daemon's own session
|
|
68
|
+
lifetime (30 minutes by default), and a run that outlasts it ends with `SessionEndedError` at its next step. A session
|
|
69
|
+
with no call for the daemon's idle timeout (5 minutes by default), while the model takes its time, is suspended: on
|
|
70
|
+
docker its interpreter is kept, but on E2B and OpenShell a suspend ends it, so the next step finds it restarted and the
|
|
71
|
+
run ends. A session
|
|
72
|
+
is one trust domain: everything a step does is there for every later step, so use one executor for one agent and one
|
|
73
|
+
user ([who may share a session (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/sessions.md#who-may-share-a-session)).
|
|
74
|
+
`owner` names that user for a daemon's per-owner cap. The executor needs a `plimsoll_client.Client`; an `AsyncClient`
|
|
75
|
+
raises `TypeError`, since smolagents calls its executor synchronously.
|
|
76
|
+
|
|
77
|
+
## Limits, stated plainly
|
|
78
|
+
|
|
79
|
+
- **No pickle, ever.** smolagents' `allow_pickle=True` lets a final answer travel from the sandbox as a pickle, and
|
|
80
|
+
unpickling it in your process runs code the sandbox chose there: code in the sandbox could then run code outside it,
|
|
81
|
+
which is what the sandbox is there to prevent. `PlimsollExecutor(..., allow_pickle=True)` raises `ValueError` before
|
|
82
|
+
a session is opened, and so does setting the attribute later; a final answer that arrives as a pickle anyway is
|
|
83
|
+
refused unread. Variables (`agent.run(..., additional_args=...)`) travel as JSON-safe values only, as smolagents' own
|
|
84
|
+
executors send them without pickle.
|
|
85
|
+
- **The final answer is plain data.** The executor sends its own definition of the `final_answer` tool, which carries
|
|
86
|
+
what smolagents' own carries (JSON values, tuples, sets, bytes, dates and times, decimals, paths, and dataclasses, as
|
|
87
|
+
a dictionary), with no NumPy or Pillow import, because `plimsoll/sandbox-python` has no Pillow. A final answer that
|
|
88
|
+
is an image, a NumPy array or a NumPy number (`numpy.int64(3)`, say) is refused with an error the model is shown, so
|
|
89
|
+
it can answer with a plain value (`value.tolist()`, `value.item()`). One that claims to be an image, an array, or any
|
|
90
|
+
kind the executor's own definition does not write is refused in your process too, with the kind named: smolagents'
|
|
91
|
+
reader runs in your process and learns new kinds with new releases, so it is handed only the kinds listed above and
|
|
92
|
+
Pillow never opens bytes from the sandbox. For the same reason a dictionary with a key named `__type__` is carried
|
|
93
|
+
only when that key holds one of those kinds' own marks.
|
|
94
|
+
- **Nothing is installed.** smolagents asks its executor to install every package a tool's code imports from outside
|
|
95
|
+
Python's standard library, and this executor refuses any install: a plimsoll sandbox has no network by default, and
|
|
96
|
+
packages belong in the image its operator runs. So a tool whose code imports `numpy` makes `agent.run` raise
|
|
97
|
+
`ValueError` when the run starts, before anything is sent, even though `plimsoll/sandbox-python` has NumPy and SciPy.
|
|
98
|
+
The agent's own steps can import whatever the image has.
|
|
99
|
+
- **Tools run in the sandbox, and cannot reach the network.** smolagents sends each tool's code, its class attributes
|
|
100
|
+
included, into the sandbox's interpreter, and the tool runs there, in the step's cell; so anything written into a
|
|
101
|
+
tool's code is visible to the agent's code. A cell carries no grant, the permission that lets a call reach an API
|
|
102
|
+
([capability grants (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/capability-grants.md)),
|
|
103
|
+
so no tool can reach the network from a step, and unlike the other kits' code tools this executor takes no grant. A
|
|
104
|
+
web search tool does not work here.
|
|
105
|
+
- **The record of a step can be forged by the agent's own code, and forges only its own answer.** The executor reads
|
|
106
|
+
each step's value, output and error from a line its own helper in the sandbox's interpreter prints, marked with a
|
|
107
|
+
random value fresh for each step. The agent's code runs in that same interpreter and can read the mark, so it can
|
|
108
|
+
forge what the executor reads back as its step's result; it can forge nothing but the agent's own answer. The run
|
|
109
|
+
record of each cell is plimsoll's: the client checks it and its place in the session's chain.
|
|
110
|
+
- **Text from the sandbox arrives printable.** smolagents' console logger prints what a step printed, a step's value and
|
|
111
|
+
the final answer on your terminal as they are (it escapes its error messages, not these), so code in the sandbox could
|
|
112
|
+
send your terminal escape sequences: a new window title, a cleared screen, or, on a terminal that allows it, the
|
|
113
|
+
clipboard. The executor writes each control character but tab, newline and carriage return as a visible escape
|
|
114
|
+
(`\x1b` for the escape character) in what a step printed, its error, a value or final answer that is text, and a final
|
|
115
|
+
answer that is a path. Text inside a list, a dictionary or another value is handed over as it came, since smolagents
|
|
116
|
+
prints such a value as its `repr`, which escapes it; escape it yourself before you print it.
|
|
117
|
+
- **Not tested:** smolagents' managed agents (an agent another agent calls as a tool, which smolagents sends to the
|
|
118
|
+
executor with the tools); any smolagents release but 1.26.0.
|
|
119
|
+
|
|
120
|
+
## What reaches your application
|
|
121
|
+
|
|
122
|
+
smolagents asks an executor only for each step's output, value or error, and the final answer. What plimsoll states
|
|
123
|
+
about each cell, none of it from what the cell's code printed, is in `executor.records`: a `PlimsollCellRecord` per cell
|
|
124
|
+
the client checked, with the tier the cell ran at (`isolation`), the sentence the provider states beside the tier
|
|
125
|
+
(`isolation_qualification`, empty when it states none), how the cell ended (`outcome`: `completed`, or `timed_out` when
|
|
126
|
+
its budget ended it), the SHA-256 of its run record (`record_sha256`), the record itself (`record`) and the checked
|
|
127
|
+
result (`result`).
|
|
128
|
+
|
|
129
|
+
```python
|
|
130
|
+
for cell in executor.records:
|
|
131
|
+
print(cell.isolation, cell.outcome, cell.record_sha256)
|
|
132
|
+
assert executor.records[-1].record_sha256 == executor.session.last_record_sha256
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
The records are in the order the cells ran: first the executor's own setup cell, then one for each call smolagents made
|
|
136
|
+
(the variables and the tools' definitions at the start of each run, then each step). So they are the session's chain of
|
|
137
|
+
records: each names the one before it, and the last is the end of the chain the client checked. A cell that answered is
|
|
138
|
+
kept whatever its code did (an error, a lost result, a timeout). A call that raised adds none; when its error carries
|
|
139
|
+
the checked record of a call that may have run, that record is `executor.fatal_error.record`.
|
|
140
|
+
|
|
141
|
+
## What it is not
|
|
142
|
+
|
|
143
|
+
- **Not a hosted service.** You run `plimsolld` on your own machine or cluster, with a provider you pick
|
|
144
|
+
([isolation tiers (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/isolation-tiers.md)).
|
|
145
|
+
- **Not attestation.** A reported tier is the daemon's configuration and provider evidence plus a startup check, not
|
|
146
|
+
hardware proof.
|
|
147
|
+
|
|
148
|
+
## Versions
|
|
149
|
+
|
|
150
|
+
This package's version moves with plimsoll's releases, and each version requires the `plimsoll-client` release of the same
|
|
151
|
+
number, which holds the code (`plimsoll_client.smolagents`). `Client`, `PlimsollExecutor`, `PlimsollCellRecord` and
|
|
152
|
+
`code_agent` here are plimsoll-client's own names, gathered so an agent imports from one place. It is tested with, and
|
|
153
|
+
installs with, exactly smolagents 1.26.0 (released 2026-05-29): pip installs that version beside it and refuses another.
|
|
154
|
+
The executor copies smolagents' final-answer protocol to send its own `final_answer` and reaches into parts of smolagents
|
|
155
|
+
that are not its public interface, so its tests pin the parts that protocol lives in, and a smolagents release that changes
|
|
156
|
+
any of them fails them instead of breaking quietly; each new release is tested before the pin moves.
|
|
157
|
+
|
|
158
|
+
Licensed under the Apache License 2.0. Source:
|
|
159
|
+
[plimsoll on GitHub (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/tree/main/clients/python/smolagents-plimsoll).
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["setuptools>=77"]
|
|
3
|
+
build-backend = "setuptools.build_meta"
|
|
4
|
+
|
|
5
|
+
# A smolagents package: a CodeAgent's Python executor over one plimsoll session. The code is
|
|
6
|
+
# plimsoll_client.smolagents (PlimsollExecutor and code_agent); this package depends on that
|
|
7
|
+
# exact plimsoll-client release, and its version moves with plimsoll's releases
|
|
8
|
+
# (TestClientVersionsAgree in clients/typescript checks both). smolagents supports Python 3.10
|
|
9
|
+
# or later; the suite in clients/python/frameworks/smolagents runs against the version below.
|
|
10
|
+
[project]
|
|
11
|
+
name = "smolagents-plimsoll"
|
|
12
|
+
version = "0.28.0"
|
|
13
|
+
description = "A smolagents CodeAgent executor that runs agent-written code in plimsoll, a self-hosted sandbox that refuses to run below the isolation you require"
|
|
14
|
+
readme = "README.md"
|
|
15
|
+
license = "Apache-2.0"
|
|
16
|
+
license-files = ["LICENSE"]
|
|
17
|
+
requires-python = ">=3.10"
|
|
18
|
+
dependencies = [
|
|
19
|
+
"smolagents==1.26.0",
|
|
20
|
+
"plimsoll-client==0.28.0",
|
|
21
|
+
]
|
|
22
|
+
keywords = ["smolagents", "codeagent", "sandbox", "code execution", "agents", "gvisor"]
|
|
23
|
+
classifiers = [
|
|
24
|
+
"Programming Language :: Python :: 3",
|
|
25
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
26
|
+
"Typing :: Typed",
|
|
27
|
+
]
|
|
28
|
+
|
|
29
|
+
[project.urls]
|
|
30
|
+
Homepage = "https://github.com/plimsollmark/plimsoll/tree/main/clients/python/smolagents-plimsoll"
|
|
31
|
+
Source = "https://github.com/plimsollmark/plimsoll/tree/main/clients/python/smolagents-plimsoll"
|
|
32
|
+
Issues = "https://github.com/plimsollmark/plimsoll/issues"
|
|
33
|
+
|
|
34
|
+
[tool.setuptools.packages.find]
|
|
35
|
+
where = ["src"]
|
|
36
|
+
|
|
37
|
+
[tool.setuptools.package-data]
|
|
38
|
+
smolagents_plimsoll = ["py.typed"]
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
"""Run a smolagents CodeAgent's code in plimsoll.
|
|
2
|
+
|
|
3
|
+
from smolagents import AgentLogger, LogLevel
|
|
4
|
+
from smolagents_plimsoll import Client, PlimsollExecutor, code_agent
|
|
5
|
+
|
|
6
|
+
executor = PlimsollExecutor([], AgentLogger(LogLevel.INFO),
|
|
7
|
+
client=Client("https://plimsoll.internal:8746", token=TOKEN),
|
|
8
|
+
minimum_isolation="kernel")
|
|
9
|
+
with code_agent(executor, tools=[], model=model) as agent: # closes the session after
|
|
10
|
+
print(agent.run("..."))
|
|
11
|
+
|
|
12
|
+
The names are plimsoll-client's own, gathered here so an agent imports from one place:
|
|
13
|
+
PlimsollExecutor is plimsoll_client.smolagents.PlimsollExecutor (one plimsoll session as the
|
|
14
|
+
agent's Python executor), code_agent is plimsoll_client.smolagents.code_agent (a CodeAgent that
|
|
15
|
+
stops at the sandbox's first failure and raises plimsoll's error), PlimsollCellRecord is
|
|
16
|
+
plimsoll_client.smolagents.PlimsollCellRecord (what plimsoll states about each cell, in
|
|
17
|
+
executor.records), and Client is plimsoll_client.Client. The executor's floor,
|
|
18
|
+
minimum_isolation, has no default: it is set in your code and checked before any of the
|
|
19
|
+
agent's code is sent.
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
from plimsoll_client import Client
|
|
23
|
+
from plimsoll_client.smolagents import PlimsollCellRecord, PlimsollExecutor, code_agent
|
|
24
|
+
|
|
25
|
+
__all__ = ["Client", "PlimsollCellRecord", "PlimsollExecutor", "code_agent"]
|
|
26
|
+
__version__ = "0.28.0"
|
|
File without changes
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: smolagents-plimsoll
|
|
3
|
+
Version: 0.28.0
|
|
4
|
+
Summary: A smolagents CodeAgent executor that runs agent-written code in plimsoll, a self-hosted sandbox that refuses to run below the isolation you require
|
|
5
|
+
License-Expression: Apache-2.0
|
|
6
|
+
Project-URL: Homepage, https://github.com/plimsollmark/plimsoll/tree/main/clients/python/smolagents-plimsoll
|
|
7
|
+
Project-URL: Source, https://github.com/plimsollmark/plimsoll/tree/main/clients/python/smolagents-plimsoll
|
|
8
|
+
Project-URL: Issues, https://github.com/plimsollmark/plimsoll/issues
|
|
9
|
+
Keywords: smolagents,codeagent,sandbox,code execution,agents,gvisor
|
|
10
|
+
Classifier: Programming Language :: Python :: 3
|
|
11
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
12
|
+
Classifier: Typing :: Typed
|
|
13
|
+
Requires-Python: >=3.10
|
|
14
|
+
Description-Content-Type: text/markdown
|
|
15
|
+
License-File: LICENSE
|
|
16
|
+
Requires-Dist: smolagents==1.26.0
|
|
17
|
+
Requires-Dist: plimsoll-client==0.28.0
|
|
18
|
+
Dynamic: license-file
|
|
19
|
+
|
|
20
|
+
# smolagents-plimsoll
|
|
21
|
+
|
|
22
|
+
A smolagents `CodeAgent` acts by writing Python, and its default executor runs that Python in your own process. This
|
|
23
|
+
package runs it in plimsoll instead, a sandbox service you run yourself, possibly somewhere else, and it has no fallback:
|
|
24
|
+
if the sandbox is weaker than you asked for, nothing runs.
|
|
25
|
+
|
|
26
|
+
**`PlimsollExecutor`** is the agent's Python executor over one plimsoll session: each step of the agent is one cell in
|
|
27
|
+
the session's Python interpreter, so the variables, functions and imports one step defines are there in the next.
|
|
28
|
+
**`code_agent`** builds the `CodeAgent` around it, so that a failure of the sandbox stops the run.
|
|
29
|
+
|
|
30
|
+
## Install
|
|
31
|
+
|
|
32
|
+
```sh
|
|
33
|
+
pip install smolagents-plimsoll
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
It needs a running `plimsolld`, the plimsoll daemon, reachable from the agent
|
|
37
|
+
([getting started (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/getting-started.md)).
|
|
38
|
+
The executor needs a provider with sessions: docker (with a project image that has Python, such as `plimsoll/sandbox-python`), E2B or OpenShell today
|
|
39
|
+
([which providers (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/sessions.md#which-providers)).
|
|
40
|
+
Sessions are off until the daemon is started with `SANDBOX_MAX_SESSIONS` set (for example `SANDBOX_MAX_SESSIONS=4`);
|
|
41
|
+
without it building the executor raises plimsoll's `UnsupportedError`, saying the daemon has no sessions.
|
|
42
|
+
On a daemon whose image has no Python, building the executor raises plimsoll's refusal and closes the session.
|
|
43
|
+
Python 3.10 or later, as smolagents requires.
|
|
44
|
+
|
|
45
|
+
## Use
|
|
46
|
+
|
|
47
|
+
```python
|
|
48
|
+
from smolagents import AgentLogger, LogLevel
|
|
49
|
+
from smolagents_plimsoll import Client, PlimsollExecutor, code_agent
|
|
50
|
+
|
|
51
|
+
executor = PlimsollExecutor([], AgentLogger(LogLevel.INFO),
|
|
52
|
+
client=Client("https://plimsoll.internal:8746", token=TOKEN),
|
|
53
|
+
minimum_isolation="kernel")
|
|
54
|
+
with code_agent(executor, tools=[], model=model) as agent: # closes the session after
|
|
55
|
+
print(agent.run("What is the 20th Fibonacci number?"))
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
`model` is any smolagents model, such as `InferenceClientModel` or `LiteLLMModel`. The first argument,
|
|
59
|
+
`additional_imports`, must be empty (nothing is installed, below), and the second is a smolagents logger, as for
|
|
60
|
+
smolagents' own executors. Building the executor opens the session and checks its tier; leaving the `with` block, or
|
|
61
|
+
`agent.cleanup()`, closes it, and the sandbox and its files are gone.
|
|
62
|
+
|
|
63
|
+
## What the executor needs and does
|
|
64
|
+
|
|
65
|
+
- **The floor is yours to set.** `minimum_isolation` (`process`, `container`, `kernel` or `vm`) has no default. When the
|
|
66
|
+
session opens, its tier is checked against the floor before any of the agent's code is sent; below it, the session is
|
|
67
|
+
closed and `InsufficientIsolationError` is raised.
|
|
68
|
+
- **Build the agent with `code_agent`.** smolagents turns every error an executor raises into an error its model is
|
|
69
|
+
shown, and goes on to the next step. So the executor keeps the first error after which the run cannot go on as
|
|
70
|
+
`executor.fatal_error` and sends nothing more, and the agent `code_agent` builds stops at the end of that step: its
|
|
71
|
+
`run` raises that error, plimsoll's own, in place of smolagents' "Agent interrupted.". Those errors are: a cell
|
|
72
|
+
plimsoll refused before anything ran; a cell that may have run without an answer to show for it (any error of the
|
|
73
|
+
session's call that is not a refusal, plimsoll's or not); a cell on a session that has ended (its lifetime ran out, or
|
|
74
|
+
the daemon closed it); and a step that finds the sandbox's interpreter restarted, so the variables and tools of the
|
|
75
|
+
earlier steps are gone. With `stream=True` the steps are handed on as they come and the error is raised in place of
|
|
76
|
+
the final answer. A plain `CodeAgent(executor=executor)` sends nothing more either, but goes on asking its model until
|
|
77
|
+
`max_steps` and then returns the model's own answer, made up after the sandbox failed; check `executor.fatal_error`
|
|
78
|
+
after such a run.
|
|
79
|
+
- **The code's own errors are the model's to fix.** An exception the agent's code raises comes back to the model as
|
|
80
|
+
smolagents' `AgentError`, with what the step printed and the traceback, as smolagents' own remote executors report it.
|
|
81
|
+
- **Each step has a time budget,** `timeout`, 120 seconds unless you set it; the daemon cuts a longer budget to its own
|
|
82
|
+
limit for a call (120 seconds by default on docker). A step past its budget is stopped and the sandbox ends its
|
|
83
|
+
interpreter: the model is told, and the next step finds the interpreter restarted, which ends the run.
|
|
84
|
+
- **A step that prints past the sandbox's output limit** (64 KiB by default on docker) loses its result, which comes at
|
|
85
|
+
the end of its output: the model is shown that the output was cut, and the run goes on.
|
|
86
|
+
- **One session for the run.** `lifetime` (seconds, 3600 unless you set it) may only shorten the daemon's own session
|
|
87
|
+
lifetime (30 minutes by default), and a run that outlasts it ends with `SessionEndedError` at its next step. A session
|
|
88
|
+
with no call for the daemon's idle timeout (5 minutes by default), while the model takes its time, is suspended: on
|
|
89
|
+
docker its interpreter is kept, but on E2B and OpenShell a suspend ends it, so the next step finds it restarted and the
|
|
90
|
+
run ends. A session
|
|
91
|
+
is one trust domain: everything a step does is there for every later step, so use one executor for one agent and one
|
|
92
|
+
user ([who may share a session (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/sessions.md#who-may-share-a-session)).
|
|
93
|
+
`owner` names that user for a daemon's per-owner cap. The executor needs a `plimsoll_client.Client`; an `AsyncClient`
|
|
94
|
+
raises `TypeError`, since smolagents calls its executor synchronously.
|
|
95
|
+
|
|
96
|
+
## Limits, stated plainly
|
|
97
|
+
|
|
98
|
+
- **No pickle, ever.** smolagents' `allow_pickle=True` lets a final answer travel from the sandbox as a pickle, and
|
|
99
|
+
unpickling it in your process runs code the sandbox chose there: code in the sandbox could then run code outside it,
|
|
100
|
+
which is what the sandbox is there to prevent. `PlimsollExecutor(..., allow_pickle=True)` raises `ValueError` before
|
|
101
|
+
a session is opened, and so does setting the attribute later; a final answer that arrives as a pickle anyway is
|
|
102
|
+
refused unread. Variables (`agent.run(..., additional_args=...)`) travel as JSON-safe values only, as smolagents' own
|
|
103
|
+
executors send them without pickle.
|
|
104
|
+
- **The final answer is plain data.** The executor sends its own definition of the `final_answer` tool, which carries
|
|
105
|
+
what smolagents' own carries (JSON values, tuples, sets, bytes, dates and times, decimals, paths, and dataclasses, as
|
|
106
|
+
a dictionary), with no NumPy or Pillow import, because `plimsoll/sandbox-python` has no Pillow. A final answer that
|
|
107
|
+
is an image, a NumPy array or a NumPy number (`numpy.int64(3)`, say) is refused with an error the model is shown, so
|
|
108
|
+
it can answer with a plain value (`value.tolist()`, `value.item()`). One that claims to be an image, an array, or any
|
|
109
|
+
kind the executor's own definition does not write is refused in your process too, with the kind named: smolagents'
|
|
110
|
+
reader runs in your process and learns new kinds with new releases, so it is handed only the kinds listed above and
|
|
111
|
+
Pillow never opens bytes from the sandbox. For the same reason a dictionary with a key named `__type__` is carried
|
|
112
|
+
only when that key holds one of those kinds' own marks.
|
|
113
|
+
- **Nothing is installed.** smolagents asks its executor to install every package a tool's code imports from outside
|
|
114
|
+
Python's standard library, and this executor refuses any install: a plimsoll sandbox has no network by default, and
|
|
115
|
+
packages belong in the image its operator runs. So a tool whose code imports `numpy` makes `agent.run` raise
|
|
116
|
+
`ValueError` when the run starts, before anything is sent, even though `plimsoll/sandbox-python` has NumPy and SciPy.
|
|
117
|
+
The agent's own steps can import whatever the image has.
|
|
118
|
+
- **Tools run in the sandbox, and cannot reach the network.** smolagents sends each tool's code, its class attributes
|
|
119
|
+
included, into the sandbox's interpreter, and the tool runs there, in the step's cell; so anything written into a
|
|
120
|
+
tool's code is visible to the agent's code. A cell carries no grant, the permission that lets a call reach an API
|
|
121
|
+
([capability grants (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/capability-grants.md)),
|
|
122
|
+
so no tool can reach the network from a step, and unlike the other kits' code tools this executor takes no grant. A
|
|
123
|
+
web search tool does not work here.
|
|
124
|
+
- **The record of a step can be forged by the agent's own code, and forges only its own answer.** The executor reads
|
|
125
|
+
each step's value, output and error from a line its own helper in the sandbox's interpreter prints, marked with a
|
|
126
|
+
random value fresh for each step. The agent's code runs in that same interpreter and can read the mark, so it can
|
|
127
|
+
forge what the executor reads back as its step's result; it can forge nothing but the agent's own answer. The run
|
|
128
|
+
record of each cell is plimsoll's: the client checks it and its place in the session's chain.
|
|
129
|
+
- **Text from the sandbox arrives printable.** smolagents' console logger prints what a step printed, a step's value and
|
|
130
|
+
the final answer on your terminal as they are (it escapes its error messages, not these), so code in the sandbox could
|
|
131
|
+
send your terminal escape sequences: a new window title, a cleared screen, or, on a terminal that allows it, the
|
|
132
|
+
clipboard. The executor writes each control character but tab, newline and carriage return as a visible escape
|
|
133
|
+
(`\x1b` for the escape character) in what a step printed, its error, a value or final answer that is text, and a final
|
|
134
|
+
answer that is a path. Text inside a list, a dictionary or another value is handed over as it came, since smolagents
|
|
135
|
+
prints such a value as its `repr`, which escapes it; escape it yourself before you print it.
|
|
136
|
+
- **Not tested:** smolagents' managed agents (an agent another agent calls as a tool, which smolagents sends to the
|
|
137
|
+
executor with the tools); any smolagents release but 1.26.0.
|
|
138
|
+
|
|
139
|
+
## What reaches your application
|
|
140
|
+
|
|
141
|
+
smolagents asks an executor only for each step's output, value or error, and the final answer. What plimsoll states
|
|
142
|
+
about each cell, none of it from what the cell's code printed, is in `executor.records`: a `PlimsollCellRecord` per cell
|
|
143
|
+
the client checked, with the tier the cell ran at (`isolation`), the sentence the provider states beside the tier
|
|
144
|
+
(`isolation_qualification`, empty when it states none), how the cell ended (`outcome`: `completed`, or `timed_out` when
|
|
145
|
+
its budget ended it), the SHA-256 of its run record (`record_sha256`), the record itself (`record`) and the checked
|
|
146
|
+
result (`result`).
|
|
147
|
+
|
|
148
|
+
```python
|
|
149
|
+
for cell in executor.records:
|
|
150
|
+
print(cell.isolation, cell.outcome, cell.record_sha256)
|
|
151
|
+
assert executor.records[-1].record_sha256 == executor.session.last_record_sha256
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
The records are in the order the cells ran: first the executor's own setup cell, then one for each call smolagents made
|
|
155
|
+
(the variables and the tools' definitions at the start of each run, then each step). So they are the session's chain of
|
|
156
|
+
records: each names the one before it, and the last is the end of the chain the client checked. A cell that answered is
|
|
157
|
+
kept whatever its code did (an error, a lost result, a timeout). A call that raised adds none; when its error carries
|
|
158
|
+
the checked record of a call that may have run, that record is `executor.fatal_error.record`.
|
|
159
|
+
|
|
160
|
+
## What it is not
|
|
161
|
+
|
|
162
|
+
- **Not a hosted service.** You run `plimsolld` on your own machine or cluster, with a provider you pick
|
|
163
|
+
([isolation tiers (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/blob/main/docs/isolation-tiers.md)).
|
|
164
|
+
- **Not attestation.** A reported tier is the daemon's configuration and provider evidence plus a startup check, not
|
|
165
|
+
hardware proof.
|
|
166
|
+
|
|
167
|
+
## Versions
|
|
168
|
+
|
|
169
|
+
This package's version moves with plimsoll's releases, and each version requires the `plimsoll-client` release of the same
|
|
170
|
+
number, which holds the code (`plimsoll_client.smolagents`). `Client`, `PlimsollExecutor`, `PlimsollCellRecord` and
|
|
171
|
+
`code_agent` here are plimsoll-client's own names, gathered so an agent imports from one place. It is tested with, and
|
|
172
|
+
installs with, exactly smolagents 1.26.0 (released 2026-05-29): pip installs that version beside it and refuses another.
|
|
173
|
+
The executor copies smolagents' final-answer protocol to send its own `final_answer` and reaches into parts of smolagents
|
|
174
|
+
that are not its public interface, so its tests pin the parts that protocol lives in, and a smolagents release that changes
|
|
175
|
+
any of them fails them instead of breaking quietly; each new release is tested before the pin moves.
|
|
176
|
+
|
|
177
|
+
Licensed under the Apache License 2.0. Source:
|
|
178
|
+
[plimsoll on GitHub (EXTERNAL · source repo ↗)](https://github.com/plimsollmark/plimsoll/tree/main/clients/python/smolagents-plimsoll).
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
README.md
|
|
3
|
+
pyproject.toml
|
|
4
|
+
src/smolagents_plimsoll/__init__.py
|
|
5
|
+
src/smolagents_plimsoll/py.typed
|
|
6
|
+
src/smolagents_plimsoll.egg-info/PKG-INFO
|
|
7
|
+
src/smolagents_plimsoll.egg-info/SOURCES.txt
|
|
8
|
+
src/smolagents_plimsoll.egg-info/dependency_links.txt
|
|
9
|
+
src/smolagents_plimsoll.egg-info/requires.txt
|
|
10
|
+
src/smolagents_plimsoll.egg-info/top_level.txt
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
smolagents_plimsoll
|