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.
@@ -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,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -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"
@@ -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,2 @@
1
+ smolagents==1.26.0
2
+ plimsoll-client==0.28.0