smolagents-briq 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,5 @@
1
+ .venv/
2
+ __pycache__/
3
+ .ruff_cache/
4
+ dist/
5
+ *.egg-info/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 briq
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,76 @@
1
+ Metadata-Version: 2.5
2
+ Name: smolagents-briq
3
+ Version: 0.1.0
4
+ Summary: Persistent briq sandbox executor for smolagents
5
+ Project-URL: Homepage, https://briq.cloud
6
+ Project-URL: Repository, https://github.com/briq-cloud/smolagents-briq
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Requires-Python: <4,>=3.11
10
+ Requires-Dist: briq-cloud<0.2,>=0.1.1
11
+ Requires-Dist: smolagents<1.27,>=1.26.0
12
+ Description-Content-Type: text/markdown
13
+
14
+ # smolagents-briq
15
+
16
+ ```python
17
+ from smolagents import CodeAgent
18
+ from smolagents_briq import BriqExecutor
19
+
20
+ # Set BRIQ_API_KEY. Supply your configured smolagents Model instance.
21
+ with BriqExecutor() as executor:
22
+ agent = CodeAgent(tools=[], model=model, executor=executor)
23
+ result = agent.run("Calculate the first 20 Fibonacci numbers.")
24
+ ```
25
+
26
+ Install with `pip install smolagents-briq`. The package targets
27
+ smolagents 1.26.x and briq-cloud 0.1.x (minimum 0.1.1). Direct `executor=` injection
28
+ works in released smolagents; no plugin discovery or upstream patch is required.
29
+ The model is configured separately; no model credentials are sent by this adapter.
30
+
31
+ Each executor creates and owns a briq sandbox. Python state survives across
32
+ agent actions. Tools and variables use smolagents' remote-executor protocol;
33
+ tools execute inside the sandbox and must have serializable source and dependencies.
34
+ No host tool callback is provided. Expression outputs use Jupyter's text representation.
35
+ Final answers use smolagents' safe serialization, with pickle always disabled.
36
+ Return arrays as lists and images as bytes. Rich array and image reconstruction
37
+ on the host is rejected, including nested values.
38
+
39
+ The default image is `python:3.12-slim`. Cold setup installs smolagents 1.26.0,
40
+ NumPy 1.26/2.x, ipykernel 6/7 and jupyter-client 8 with pip, requiring outbound package access.
41
+ A custom image must provide `python3` and pip. Initial installation has a 60-second
42
+ command deadline and can fail on slow networks; setup failures destroy the sandbox.
43
+ There is no prebuilt integration image.
44
+
45
+ The kernel listens on loopback inside the sandbox. No port is exposed. Commands
46
+ and results travel through the briq SDK. Code is uploaded as a file, so long actions
47
+ do not become long shell commands. Logs and text results share a 65,536-character
48
+ budget per action; rich display formats are not returned. Final answers are limited
49
+ to 65,536 characters of serialized data. No remote text is evaluated on the host.
50
+
51
+ `execution_timeout` defaults to 30 seconds (maximum 40). Timeout interrupts the
52
+ kernel and marks the executor unusable. A transport failure or malformed response
53
+ also makes it unusable: create a new executor rather than replaying uncertain code.
54
+ The adapter serializes execution calls; use one executor per agent.
55
+
56
+ Use the context manager or call `cleanup()`/`delete()` explicitly. Cleanup destroys
57
+ the sandbox, propagates failures and can be retried. An injected `client=Briq(...)`
58
+ stays open. There is no destructor that performs network calls. `size` is passed
59
+ through when supplied; otherwise the API chooses its default. `sleep` defaults to
60
+ `30m`. Sleeping or restarting a sandbox loses the live kernel session.
61
+
62
+ ## Verify
63
+
64
+ ```sh
65
+ uv sync --group test
66
+ uv run pytest
67
+ uv run ruff check .
68
+ uv run python -m build
69
+ uv run twine check dist/*
70
+ ```
71
+
72
+ Offline contract tests run a real Jupyter kernel and the shipped bridge through a
73
+ local subprocess SDK double, plus a deterministic real CodeAgent. They do not call
74
+ briq or a model API. The 0.1.0 release candidate also passed a live lifecycle smoke against staging and
75
+ production on 2026-11-09: persistent state, final answers, timeout, refusal to reuse
76
+ an uncertain executor, and confirmed destruction. No model API was called.
@@ -0,0 +1,63 @@
1
+ # smolagents-briq
2
+
3
+ ```python
4
+ from smolagents import CodeAgent
5
+ from smolagents_briq import BriqExecutor
6
+
7
+ # Set BRIQ_API_KEY. Supply your configured smolagents Model instance.
8
+ with BriqExecutor() as executor:
9
+ agent = CodeAgent(tools=[], model=model, executor=executor)
10
+ result = agent.run("Calculate the first 20 Fibonacci numbers.")
11
+ ```
12
+
13
+ Install with `pip install smolagents-briq`. The package targets
14
+ smolagents 1.26.x and briq-cloud 0.1.x (minimum 0.1.1). Direct `executor=` injection
15
+ works in released smolagents; no plugin discovery or upstream patch is required.
16
+ The model is configured separately; no model credentials are sent by this adapter.
17
+
18
+ Each executor creates and owns a briq sandbox. Python state survives across
19
+ agent actions. Tools and variables use smolagents' remote-executor protocol;
20
+ tools execute inside the sandbox and must have serializable source and dependencies.
21
+ No host tool callback is provided. Expression outputs use Jupyter's text representation.
22
+ Final answers use smolagents' safe serialization, with pickle always disabled.
23
+ Return arrays as lists and images as bytes. Rich array and image reconstruction
24
+ on the host is rejected, including nested values.
25
+
26
+ The default image is `python:3.12-slim`. Cold setup installs smolagents 1.26.0,
27
+ NumPy 1.26/2.x, ipykernel 6/7 and jupyter-client 8 with pip, requiring outbound package access.
28
+ A custom image must provide `python3` and pip. Initial installation has a 60-second
29
+ command deadline and can fail on slow networks; setup failures destroy the sandbox.
30
+ There is no prebuilt integration image.
31
+
32
+ The kernel listens on loopback inside the sandbox. No port is exposed. Commands
33
+ and results travel through the briq SDK. Code is uploaded as a file, so long actions
34
+ do not become long shell commands. Logs and text results share a 65,536-character
35
+ budget per action; rich display formats are not returned. Final answers are limited
36
+ to 65,536 characters of serialized data. No remote text is evaluated on the host.
37
+
38
+ `execution_timeout` defaults to 30 seconds (maximum 40). Timeout interrupts the
39
+ kernel and marks the executor unusable. A transport failure or malformed response
40
+ also makes it unusable: create a new executor rather than replaying uncertain code.
41
+ The adapter serializes execution calls; use one executor per agent.
42
+
43
+ Use the context manager or call `cleanup()`/`delete()` explicitly. Cleanup destroys
44
+ the sandbox, propagates failures and can be retried. An injected `client=Briq(...)`
45
+ stays open. There is no destructor that performs network calls. `size` is passed
46
+ through when supplied; otherwise the API chooses its default. `sleep` defaults to
47
+ `30m`. Sleeping or restarting a sandbox loses the live kernel session.
48
+
49
+ ## Verify
50
+
51
+ ```sh
52
+ uv sync --group test
53
+ uv run pytest
54
+ uv run ruff check .
55
+ uv run python -m build
56
+ uv run twine check dist/*
57
+ ```
58
+
59
+ Offline contract tests run a real Jupyter kernel and the shipped bridge through a
60
+ local subprocess SDK double, plus a deterministic real CodeAgent. They do not call
61
+ briq or a model API. The 0.1.0 release candidate also passed a live lifecycle smoke against staging and
62
+ production on 2026-11-09: persistent state, final answers, timeout, refusal to reuse
63
+ an uncertain executor, and confirmed destruction. No model API was called.
@@ -0,0 +1,37 @@
1
+ [build-system]
2
+ requires = ["hatchling>=1.25"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "smolagents-briq"
7
+ version = "0.1.0"
8
+ description = "Persistent briq sandbox executor for smolagents"
9
+ readme = "README.md"
10
+ requires-python = ">=3.11,<4"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ dependencies = ["briq-cloud>=0.1.1,<0.2", "smolagents>=1.26.0,<1.27"]
14
+
15
+ [project.urls]
16
+ Homepage = "https://briq.cloud"
17
+ Repository = "https://github.com/briq-cloud/smolagents-briq"
18
+
19
+ [dependency-groups]
20
+ test = ["numpy>=1.26,<3", "pytest>=8", "ipykernel>=6,<8", "jupyter-client>=8,<9", "ruff>=0.6", "build>=1", "twine>=6"]
21
+
22
+ [tool.hatch.build.targets.wheel]
23
+ packages = ["smolagents_briq"]
24
+
25
+ [tool.hatch.build.targets.sdist]
26
+ include = ["smolagents_briq", "tests", "scripts", "README.md", "LICENSE", "pyproject.toml"]
27
+
28
+ [tool.pytest.ini_options]
29
+ testpaths = ["tests"]
30
+ addopts = "-p no:cacheprovider"
31
+
32
+ [tool.ruff]
33
+ line-length = 100
34
+ target-version = "py311"
35
+
36
+ [tool.ruff.lint]
37
+ select = ["E", "F", "I", "UP", "B"]
@@ -0,0 +1,49 @@
1
+ """One-sandbox live contract check. Requires explicit briq API configuration."""
2
+
3
+ import os
4
+
5
+ from briq_cloud import Briq, BriqError
6
+ from smolagents.default_tools import FinalAnswerTool
7
+
8
+ from smolagents_briq import BriqExecutor
9
+
10
+
11
+ def main() -> None:
12
+ # Require an explicit endpoint rather than falling back to production.
13
+ base_url = os.environ["BRIQ_API_URL"]
14
+ with Briq(base_url=base_url) as client:
15
+ with BriqExecutor(client=client, execution_timeout=1) as executor:
16
+ sandbox_id = executor.sandbox.id
17
+ executor.send_variables({"number": 21})
18
+ executor("answer = number * 2")
19
+ if executor("answer").output != "42":
20
+ raise RuntimeError("Persistent state check failed")
21
+ executor.send_tools({"final_answer": FinalAnswerTool()})
22
+ result = executor("final_answer(answer)")
23
+ if not result.is_final_answer or result.output != 42:
24
+ raise RuntimeError("Final answer check failed")
25
+ try:
26
+ executor("import time; time.sleep(10)")
27
+ except TimeoutError:
28
+ pass
29
+ else:
30
+ raise RuntimeError("Timeout check failed")
31
+ try:
32
+ executor("1")
33
+ except RuntimeError:
34
+ pass
35
+ else:
36
+ raise RuntimeError("Uncertain executor was reused")
37
+ try:
38
+ deleted = client.sandbox(sandbox_id)
39
+ except BriqError as error:
40
+ if error.code != "not_found":
41
+ raise
42
+ else:
43
+ if deleted.info.state != "destroyed":
44
+ raise RuntimeError("Sandbox is not destroyed after cleanup")
45
+ print("Live checks passed: persistent state, final answer, timeout, reuse refusal, deletion")
46
+
47
+
48
+ if __name__ == "__main__":
49
+ main()
@@ -0,0 +1,6 @@
1
+ """briq sandbox executor for smolagents."""
2
+
3
+ from .executor import BriqExecutor
4
+
5
+ __all__ = ["BriqExecutor"]
6
+ __version__ = "0.1.0"
@@ -0,0 +1,95 @@
1
+ """Runs inside the sandbox only; Jupyter messages leave as bounded JSON."""
2
+
3
+ import json
4
+ import os
5
+ import signal
6
+ import subprocess
7
+ import sys
8
+ import time
9
+ from pathlib import Path
10
+ from queue import Empty
11
+
12
+ from jupyter_client import BlockingKernelClient
13
+
14
+ LIMIT = 65536
15
+
16
+
17
+ def main():
18
+ root, action = Path(sys.argv[1]), sys.argv[2]
19
+ connection = root / "kernel.json"
20
+ if action == "boot":
21
+ with open(os.devnull, "wb") as null:
22
+ process = subprocess.Popen(
23
+ [
24
+ sys.executable,
25
+ "-m",
26
+ "ipykernel_launcher",
27
+ "-f",
28
+ str(connection),
29
+ "--IPKernelApp.ip=127.0.0.1",
30
+ ],
31
+ stdin=subprocess.DEVNULL,
32
+ stdout=null,
33
+ stderr=null,
34
+ start_new_session=True,
35
+ )
36
+ (root / "pid").write_text(str(process.pid))
37
+ deadline = time.monotonic() + 15
38
+ while not connection.exists():
39
+ if time.monotonic() >= deadline or process.poll() is not None:
40
+ raise RuntimeError("Kernel did not start")
41
+ time.sleep(0.05)
42
+ client = BlockingKernelClient(connection_file=str(connection))
43
+ client.load_connection_file()
44
+ client.start_channels()
45
+ try:
46
+ client.wait_for_ready(timeout=15 if action == "boot" else 5)
47
+ if action == "boot":
48
+ print("{}")
49
+ return
50
+ timeout = float(sys.argv[4])
51
+ message_id = client.execute(Path(sys.argv[3]).read_text())
52
+ deadline = time.monotonic() + timeout
53
+ result = {"logs": "", "output": None, "error": None, "timed_out": False}
54
+ budget = LIMIT
55
+ while True:
56
+ remaining = deadline - time.monotonic()
57
+ if remaining <= 0:
58
+ os.kill(int((root / "pid").read_text()), signal.SIGINT)
59
+ result["timed_out"] = True
60
+ break
61
+ try:
62
+ message = client.get_iopub_msg(timeout=min(remaining, 1))
63
+ except Empty:
64
+ continue
65
+ if message.get("parent_header", {}).get("msg_id") != message_id:
66
+ continue
67
+ kind, content = message["msg_type"], message["content"]
68
+ if kind == "status" and content["execution_state"] == "idle":
69
+ break
70
+ if kind == "stream":
71
+ text = content["text"]
72
+ result["logs"] += text[:budget]
73
+ budget -= min(budget, len(text))
74
+ elif kind in ("execute_result", "display_data"):
75
+ text = content["data"].get("text/plain", "")
76
+ result["output"] = text[:budget]
77
+ budget -= min(budget, len(text))
78
+ elif kind == "error":
79
+ if len(content["evalue"]) > LIMIT:
80
+ result["error"] = {
81
+ "name": "OutputLimitError",
82
+ "value": "Error or final answer exceeds 65536 characters",
83
+ }
84
+ continue
85
+ result["error"] = {
86
+ "name": content["ename"][:256],
87
+ "value": content["evalue"][:LIMIT],
88
+ }
89
+ print(json.dumps(result))
90
+ finally:
91
+ client.stop_channels()
92
+
93
+
94
+ if __name__ == "__main__":
95
+ main()
@@ -0,0 +1,226 @@
1
+ """Persistent smolagents execution through the briq Python SDK."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import math
7
+ import uuid
8
+ from importlib.resources import files
9
+ from threading import RLock
10
+ from typing import Any
11
+
12
+ from briq_cloud import Briq
13
+ from smolagents.local_python_executor import CodeOutput
14
+ from smolagents.monitoring import AgentLogger
15
+ from smolagents.remote_executors import RemotePythonExecutor
16
+
17
+
18
+ class BriqExecutor(RemotePythonExecutor):
19
+ """One persistent Python kernel in an owned briq sandbox.
20
+
21
+ Use as a context manager. An injected client stays open. Each executor owns
22
+ and destroys its sandbox, including after a failed initialization. Calls are
23
+ serialized; an uncertain execution outcome requires a new executor.
24
+ """
25
+
26
+ def __init__(
27
+ self,
28
+ additional_imports: list[str] | None = None,
29
+ logger: AgentLogger | None = None,
30
+ *,
31
+ client: Briq | None = None,
32
+ image: str = "python:3.12-slim",
33
+ size: str | None = None,
34
+ sleep: str = "30m",
35
+ execution_timeout: float = 30,
36
+ ) -> None:
37
+ if not math.isfinite(execution_timeout) or not 0 < execution_timeout <= 40:
38
+ raise ValueError("execution_timeout must be finite and in (0, 40]")
39
+ super().__init__(additional_imports or [], logger or AgentLogger(), allow_pickle=False)
40
+ self._lock = RLock()
41
+ self._owned_client = client is None
42
+ self._client = client if client is not None else Briq()
43
+ self.sandbox = None
44
+ self._closed = False
45
+ self._poisoned = False
46
+ self.execution_timeout = execution_timeout
47
+ self._root = f"/tmp/smolagents-briq-{uuid.uuid4().hex}"
48
+ try:
49
+ self.sandbox = self._client.create_sandbox(image=image, size=size, sleep=sleep)
50
+ self._check(
51
+ self.sandbox.exec(
52
+ [
53
+ "python3",
54
+ "-m",
55
+ "pip",
56
+ "install",
57
+ "--disable-pip-version-check",
58
+ "smolagents==1.26.0",
59
+ "numpy>=1.26,<3",
60
+ "ipykernel>=6,<8",
61
+ "jupyter-client>=8,<9",
62
+ ],
63
+ timeout=60,
64
+ )
65
+ )
66
+ self.sandbox.write_file(
67
+ self._root + "/bridge.py",
68
+ files("smolagents_briq").joinpath("_bridge.py").read_bytes(),
69
+ )
70
+ self._check(
71
+ self.sandbox.exec(
72
+ ["python3", self._root + "/bridge.py", self._root, "boot"], timeout=25
73
+ )
74
+ )
75
+ self.installed_packages = [
76
+ "smolagents",
77
+ "PIL",
78
+ "pillow",
79
+ "numpy",
80
+ "ipykernel",
81
+ "jupyter_client",
82
+ ]
83
+ self.installed_packages += self.install_packages(self.additional_imports)
84
+ except BaseException as original:
85
+ try:
86
+ self.cleanup()
87
+ except BaseException as cleanup_error:
88
+ raise BaseExceptionGroup(
89
+ "Executor initialization and cleanup failed", [original, cleanup_error]
90
+ ) from None
91
+ raise
92
+
93
+ @staticmethod
94
+ def _check(result: Any) -> str:
95
+ if result.timed_out:
96
+ raise TimeoutError("briq command timed out")
97
+ if result.exit_code != 0:
98
+ raise RuntimeError("briq command failed: " + result.stderr[:4096])
99
+ return result.stdout
100
+
101
+ def run_code_raise_errors(self, code: str) -> CodeOutput:
102
+ with self._lock:
103
+ if self._closed or self._poisoned:
104
+ raise RuntimeError("Executor is closed or unusable; create a new executor")
105
+ assert self.sandbox is not None
106
+ path = self._root + "/action.py"
107
+ self.sandbox.write_file(path, code.encode())
108
+ try:
109
+ raw = self._check(
110
+ self.sandbox.exec(
111
+ [
112
+ "python3",
113
+ self._root + "/bridge.py",
114
+ self._root,
115
+ "run",
116
+ path,
117
+ str(self.execution_timeout),
118
+ ],
119
+ timeout=self.execution_timeout + 15,
120
+ )
121
+ )
122
+ # JSON is the only host-side wire format. Never evaluate text/plain.
123
+ if len(raw) > 1024 * 1024:
124
+ raise RuntimeError("Kernel response exceeds limit")
125
+ result = json.loads(raw)
126
+ if result["timed_out"]:
127
+ raise TimeoutError("Kernel execution timed out; executor is unusable")
128
+ error = result["error"]
129
+ logs = result["logs"]
130
+ output = result["output"]
131
+ if not isinstance(logs, str) or not (output is None or isinstance(output, str)):
132
+ raise ValueError("Malformed kernel response")
133
+ except BaseException:
134
+ self._poisoned = True
135
+ raise
136
+ if error:
137
+ if not (
138
+ isinstance(error, dict)
139
+ and isinstance(error.get("name"), str)
140
+ and isinstance(error.get("value"), str)
141
+ ):
142
+ self._poisoned = True
143
+ raise ValueError("Malformed kernel error")
144
+ if error["name"] == self.FINAL_ANSWER_EXCEPTION:
145
+ value = error["value"]
146
+ try:
147
+ if not value.startswith("safe:"):
148
+ raise ValueError("Only JSON final answers are supported")
149
+ answer = self._deserialize_final_answer(value, allow_pickle=False)
150
+ except Exception:
151
+ self._poisoned = True
152
+ raise
153
+ return CodeOutput(
154
+ output=answer,
155
+ logs=logs,
156
+ is_final_answer=True,
157
+ )
158
+ raise RuntimeError(f"{logs}\n{error['name']}: {error['value']}")
159
+ return CodeOutput(output=output, logs=logs, is_final_answer=False)
160
+
161
+ def install_packages(self, additional_imports: list[str]) -> list[str]:
162
+ if additional_imports:
163
+ # Specifications are argv values, never shell commands.
164
+ self.run_code_raise_errors(
165
+ "import subprocess, sys\nsubprocess.run([sys.executable, '-m', 'pip', 'install', "
166
+ + ", ".join(repr(item) for item in additional_imports)
167
+ + "], check=True)"
168
+ )
169
+ return list(additional_imports)
170
+
171
+ def _patch_final_answer_with_exception(self, final_answer_tool: Any) -> None:
172
+ # CodeAgent registers its tools on every run. Upstream's patch wraps the
173
+ # existing forward method and must be applied only once to each tool.
174
+ if not getattr(final_answer_tool, "_briq_final_answer_patched", False):
175
+ super()._patch_final_answer_with_exception(final_answer_tool)
176
+ final_answer_tool._briq_final_answer_patched = True
177
+
178
+ @staticmethod
179
+ def _deserialize_final_answer(encoded_value: str, allow_pickle: bool = False) -> Any:
180
+ if allow_pickle or not encoded_value.startswith("safe:"):
181
+ raise ValueError("Only JSON final answers are supported")
182
+ pending = [json.loads(encoded_value[5:])]
183
+ while pending:
184
+ value = pending.pop()
185
+ if isinstance(value, dict):
186
+ # These upstream decoders can expand small wire values into
187
+ # large host allocations. Keep rich objects in the sandbox.
188
+ if value.get("__type__") in ("ndarray", "PIL.Image"):
189
+ raise ValueError("Return arrays as lists and images as bytes")
190
+ pending.extend(value.values())
191
+ elif isinstance(value, list):
192
+ pending.extend(value)
193
+ return RemotePythonExecutor._deserialize_final_answer(encoded_value, allow_pickle=False)
194
+
195
+ def cleanup(self) -> None:
196
+ """Destroy owned resources. Failures propagate and can be retried."""
197
+ with self._lock:
198
+ self._poisoned = True
199
+ if self.sandbox is not None:
200
+ try:
201
+ self.sandbox.destroy()
202
+ except BaseException as error:
203
+ error.add_note(
204
+ f"Sandbox cleanup failed; retry destruction for {self.sandbox.id}"
205
+ )
206
+ raise
207
+ self.sandbox = None
208
+ if self._owned_client and not self._closed:
209
+ self._client.close()
210
+ self._closed = True
211
+
212
+ def delete(self) -> None:
213
+ self.cleanup()
214
+
215
+ def __enter__(self) -> BriqExecutor:
216
+ return self
217
+
218
+ def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
219
+ try:
220
+ self.cleanup()
221
+ except BaseException as cleanup_error:
222
+ if exc is not None:
223
+ raise BaseExceptionGroup(
224
+ "Execution and cleanup failed", [exc, cleanup_error]
225
+ ) from None
226
+ raise
@@ -0,0 +1,292 @@
1
+ """Offline contracts: actual ipykernel and bridge, trusted test code only."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import os
7
+ import signal
8
+ import subprocess
9
+ import sys
10
+ from pathlib import Path
11
+ from types import SimpleNamespace
12
+
13
+ import pytest
14
+ from smolagents import CodeAgent, Model, tool
15
+ from smolagents.default_tools import FinalAnswerTool
16
+ from smolagents.models import ChatMessage
17
+
18
+ from smolagents_briq import BriqExecutor
19
+
20
+
21
+ class LocalSandbox:
22
+ def __init__(self, tmp_path):
23
+ self.id = "bq_local_test"
24
+ self.root = tmp_path
25
+ self.paths = {}
26
+ self.commands = []
27
+ self.destroy_calls = 0
28
+ self.destroy_failure = False
29
+ self.fail_install = False
30
+
31
+ def local(self, path):
32
+ return str(self.root / path.lstrip("/"))
33
+
34
+ def write_file(self, path, data):
35
+ local = Path(self.local(path))
36
+ local.parent.mkdir(parents=True, exist_ok=True)
37
+ local.write_bytes(data)
38
+ self.paths[path] = local
39
+
40
+ def exec(self, command, *, timeout):
41
+ self.commands.append(command)
42
+ if command[1:3] == ["-m", "pip"]:
43
+ return SimpleNamespace(
44
+ stdout="",
45
+ stderr="install failed" if self.fail_install else "",
46
+ exit_code=1 if self.fail_install else 0,
47
+ timed_out=False,
48
+ )
49
+ args = [sys.executable] + [
50
+ self.local(x) if x.startswith("/tmp/") else x for x in command[1:]
51
+ ]
52
+ result = subprocess.run(args, capture_output=True, text=True, timeout=timeout)
53
+ return SimpleNamespace(
54
+ stdout=result.stdout, stderr=result.stderr, exit_code=result.returncode, timed_out=False
55
+ )
56
+
57
+ def destroy(self):
58
+ self.destroy_calls += 1
59
+ if self.destroy_failure:
60
+ raise RuntimeError("destroy failed")
61
+ for pid_file in self.root.rglob("pid"):
62
+ try:
63
+ os.kill(int(pid_file.read_text()), signal.SIGTERM)
64
+ except ProcessLookupError:
65
+ pass
66
+
67
+
68
+ class LocalClient:
69
+ def __init__(self, sandbox):
70
+ self.sandbox = sandbox
71
+ self.closed = False
72
+ self.create_kwargs = None
73
+
74
+ def create_sandbox(self, **kwargs):
75
+ self.create_kwargs = kwargs
76
+ return self.sandbox
77
+
78
+ def close(self):
79
+ self.closed = True
80
+
81
+
82
+ @pytest.fixture
83
+ def local(tmp_path):
84
+ client = LocalClient(LocalSandbox(tmp_path))
85
+ yield client
86
+ client.sandbox.destroy_failure = False
87
+ client.sandbox.destroy()
88
+
89
+
90
+ @pytest.fixture
91
+ def executor(local):
92
+ with BriqExecutor(client=local) as executor:
93
+ yield executor
94
+
95
+
96
+ def test_persistent_kernel_variables_logs_and_expression(executor):
97
+ executor.send_variables({"items": [2, 3]})
98
+ assert executor('total = sum(items)\nprint("first")').logs == "first\n"
99
+ assert executor("total + 4").output == "9"
100
+ assert not executor("total").is_final_answer
101
+
102
+
103
+ def test_final_answer_and_safe_types(executor):
104
+ executor.send_tools({"final_answer": FinalAnswerTool()})
105
+ result = executor('final_answer({"answer": (42, b"ok")})')
106
+ assert result.output == {"answer": (42, b"ok")}
107
+ assert result.is_final_answer
108
+
109
+
110
+ def test_python_error_preserves_kernel(executor):
111
+ with pytest.raises(RuntimeError, match="ZeroDivisionError"):
112
+ executor("marker = 9\n1 / 0")
113
+ assert executor("marker").output == "9"
114
+
115
+
116
+ def test_large_code_uses_file(executor, local):
117
+ assert executor("#" + "x" * 12000 + "\n6 * 7").output == "42"
118
+ assert all(len(json.dumps(command)) < 8192 for command in local.sandbox.commands)
119
+
120
+
121
+ def test_output_is_bounded(executor):
122
+ result = executor('print("x" * 100000)')
123
+ assert len(result.logs) <= 65536
124
+
125
+
126
+ def test_timeout_poison(executor):
127
+ executor.execution_timeout = 0.1
128
+ with pytest.raises(TimeoutError):
129
+ executor("import time\ntime.sleep(10)")
130
+ with pytest.raises(RuntimeError, match="unusable"):
131
+ executor("1")
132
+
133
+
134
+ def test_cleanup_retry_and_borrowed_client(local):
135
+ executor = BriqExecutor(client=local)
136
+ local.sandbox.destroy_failure = True
137
+ with pytest.raises(RuntimeError, match="destroy failed"):
138
+ executor.cleanup()
139
+ local.sandbox.destroy_failure = False
140
+ executor.cleanup()
141
+ executor.cleanup()
142
+ assert local.sandbox.destroy_calls == 2
143
+ assert not local.closed
144
+
145
+
146
+ def test_init_failure_cleanup(local):
147
+ local.sandbox.fail_install = True
148
+ with pytest.raises(RuntimeError, match="install failed"):
149
+ BriqExecutor(client=local)
150
+ assert local.sandbox.destroy_calls == 1
151
+
152
+
153
+ @pytest.mark.parametrize("timeout", [0, -1, 41, float("nan"), float("inf")])
154
+ def test_invalid_timeout_before_create(local, timeout):
155
+ with pytest.raises(ValueError, match="execution_timeout"):
156
+ BriqExecutor(client=local, execution_timeout=timeout)
157
+ assert local.create_kwargs is None
158
+
159
+
160
+ @tool
161
+ def double(value: int) -> int:
162
+ """Double a number.
163
+
164
+ Args:
165
+ value: Number to double.
166
+ """
167
+ return value * 2
168
+
169
+
170
+ class FixedModel(Model):
171
+ def __init__(self):
172
+ super().__init__()
173
+ self.actions = iter(["answer = double(number)\nprint(answer)", "final_answer(answer)"])
174
+
175
+ def generate(self, messages, **kwargs):
176
+ return ChatMessage(role="assistant", content="<code>" + next(self.actions) + "</code>")
177
+
178
+
179
+ def test_released_codeagent_direct_injection(executor):
180
+ agent = CodeAgent(
181
+ tools=[double], model=FixedModel(), executor=executor, max_steps=2, verbosity_level=0
182
+ )
183
+ for _ in range(2):
184
+ agent.model.actions = iter(
185
+ ["answer = double(number)\nprint(answer)", "final_answer(answer)"]
186
+ )
187
+ assert agent.run("Double the number", additional_args={"number": 21}) == 42
188
+
189
+
190
+ @pytest.mark.parametrize("kind", ["ndarray", "PIL.Image"])
191
+ def test_rich_final_answer_rejected_before_decoder(executor, monkeypatch, kind):
192
+ from smolagents.serialization import SafeSerializer
193
+
194
+ def must_not_decode(_value):
195
+ raise AssertionError("Rich object reached the host decoder")
196
+
197
+ monkeypatch.setattr(SafeSerializer, "from_json_safe", must_not_decode)
198
+ payload = {"nested": [{"__type__": kind, "data": ["x"], "dtype": "S1000000000"}]}
199
+ with pytest.raises(ValueError, match="arrays as lists"):
200
+ executor._deserialize_final_answer("safe:" + json.dumps(payload))
201
+
202
+
203
+ def test_guest_package_failure_propagates(executor):
204
+ with pytest.raises(RuntimeError, match="CalledProcessError"):
205
+ executor.install_packages(["--definitely-not-a-pip-option"])
206
+
207
+
208
+ @pytest.mark.parametrize("options", [{}, {"size": None}, {"size": "small"}])
209
+ def test_sdk_emitted_create_request(options):
210
+ import httpx
211
+ from briq_cloud import Briq, BriqError
212
+
213
+ captured = []
214
+
215
+ def receive(request):
216
+ captured.append(request)
217
+ return httpx.Response(400, json={"error": {"code": "invalid_argument", "message": "test"}})
218
+
219
+ with Briq(
220
+ api_key="test-key", base_url="http://localhost:3001", transport=httpx.MockTransport(receive)
221
+ ) as client:
222
+ with pytest.raises(BriqError):
223
+ BriqExecutor(client=client, **options)
224
+ assert len(captured) == 1
225
+ request = captured[0]
226
+ assert request.method == "POST"
227
+ assert request.url.path == "/v1/briqs"
228
+ expected = {
229
+ "recipe": "sandbox",
230
+ "wait": True,
231
+ "waitTimeoutMs": 120000,
232
+ "image": "python:3.12-slim",
233
+ "sleep": "30m",
234
+ }
235
+ if options.get("size") is not None:
236
+ expected["size"] = options["size"]
237
+ assert json.loads(request.content) == expected
238
+ assert request.headers.get("idempotency-key")
239
+
240
+
241
+ def test_owned_client_closed_on_setup_failure(local, monkeypatch):
242
+ monkeypatch.setattr("smolagents_briq.executor.Briq", lambda: local)
243
+ local.sandbox.fail_install = True
244
+ with pytest.raises(RuntimeError):
245
+ BriqExecutor()
246
+ assert local.closed
247
+
248
+
249
+ def test_setup_and_cleanup_failures_both_visible(local):
250
+ local.sandbox.fail_install = True
251
+ local.sandbox.destroy_failure = True
252
+ with pytest.raises(ExceptionGroup) as caught:
253
+ BriqExecutor(client=local)
254
+ assert len(caught.value.exceptions) == 2
255
+ assert "install failed" in str(caught.value.exceptions[0])
256
+ assert "destroy failed" in str(caught.value.exceptions[1])
257
+
258
+
259
+ def test_context_and_cleanup_failures_both_visible(local):
260
+ with pytest.raises(ExceptionGroup) as caught:
261
+ with BriqExecutor(client=local):
262
+ local.sandbox.destroy_failure = True
263
+ raise ValueError("body failed")
264
+ assert [type(error) for error in caught.value.exceptions] == [ValueError, RuntimeError]
265
+
266
+
267
+ def test_explicit_size_image_and_sleep(local):
268
+ with BriqExecutor(client=local, size="small", image="python:3.13-slim", sleep="3h"):
269
+ assert local.create_kwargs == {"size": "small", "image": "python:3.13-slim", "sleep": "3h"}
270
+
271
+
272
+ def test_pickle_final_answer_rejected(executor):
273
+ executor.send_tools({"final_answer": FinalAnswerTool()})
274
+ with pytest.raises(ValueError, match="Only JSON"):
275
+ executor(
276
+ "class FinalAnswerException(BaseException): pass\n"
277
+ "raise FinalAnswerException('pickle:AA==')"
278
+ )
279
+
280
+
281
+ def test_final_answer_limit_is_explicit(executor):
282
+ executor.send_tools({"final_answer": FinalAnswerTool()})
283
+ with pytest.raises(RuntimeError, match="OutputLimitError"):
284
+ executor("final_answer('x' * 70000)")
285
+
286
+
287
+ def test_remote_text_is_data(executor, tmp_path):
288
+ sentinel = tmp_path / "host-must-not-execute"
289
+ payload = f"__import__('pathlib').Path({str(sentinel)!r}).touch()"
290
+ executor.send_tools({"final_answer": FinalAnswerTool()})
291
+ assert executor(f"final_answer({payload!r})").output == payload
292
+ assert not sentinel.exists()