inspect-briq 0.1.0__tar.gz

inspect_briq-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.venv/
+dist/
+__pycache__/
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/

inspect_briq-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 briq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

inspect_briq-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.5
+Name: inspect-briq
+Version: 0.1.0
+Summary: Run Inspect AI sandboxes on briq: one microVM per sample.
+Project-URL: Homepage, https://briq.cloud
+Project-URL: Repository, https://github.com/briq-cloud/inspect-briq
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,briq,evals,inspect,inspect-ai,sandbox
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: briq-cloud<0.2,>=0.1.1
+Requires-Dist: inspect-ai>=0.3.287
+Requires-Dist: pydantic>=2
+Requires-Dist: typing-extensions>=4.5
+Description-Content-Type: text/markdown
+
+# inspect-briq
+
+[![ci](https://github.com/briq-cloud/inspect-briq/actions/workflows/ci.yml/badge.svg)](https://github.com/briq-cloud/inspect-briq/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/inspect-briq)](https://pypi.org/project/inspect-briq/) [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Run [Inspect AI](https://inspect.aisi.org.uk/) sandboxes on [briq](https://briq.cloud). Each sample gets its own microVM, destroyed when the sample ends.
+
+```python
+from inspect_ai import Task, task
+from inspect_ai.dataset import Sample
+from inspect_ai.scorer import includes
+from inspect_ai.solver import generate, use_tools
+from inspect_ai.tool import bash
+from inspect_ai.util import SandboxEnvironmentSpec
+from inspect_briq import BriqSandboxEnvironmentConfig
+
+
+@task
+def kernel():
+    return Task(
+        dataset=[
+            Sample(
+                input="Run `uname -s` with the bash tool and tell me its output.",
+                target="Linux",
+                files={"notes.txt": "one file per sample, copied in before the first message"},
+            )
+        ],
+        solver=[use_tools(bash(timeout=30)), generate()],
+        scorer=includes(),
+        sandbox=SandboxEnvironmentSpec("briq", BriqSandboxEnvironmentConfig(size="medium")),
+    )
+```
+
+```sh
+pip install inspect-briq
+export BRIQ_API_KEY=...
+inspect eval kernel.py --model anthropic/claude-sonnet-4-5
+```
+
+`sandbox="briq"` uses the defaults. Python 3.11 or later (what Inspect needs), asyncio backend.
+
+## Configure
+
+`BriqSandboxEnvironmentConfig`, or a JSON file with the same fields: `sandbox=("briq", "briq.json")`.
+
+| Field                  | Default                  | Means                                                                     |
+| ---------------------- | ------------------------ | ------------------------------------------------------------------------- |
+| `size`                 | the API's default        | `small`, `medium`, `large` or `xlarge`. Anything else fails `unsupported`. |
+| `image`                | briq's sandbox image     | An OCI image.                                                             |
+| `sleep`                | `30m`                    | Idle time before the sandbox sleeps: `30m`, `3h`, `7d`, `never`.          |
+| `working_dir`          | `/work`                  | Where commands run and relative paths resolve.                            |
+| `env`                  | none                     | Variables of the sandbox. They show in its status and in the eval log.    |
+| `secret_env`           | none                     | Names of variables of the eval process, sent write-only. Needs API support. |
+| `default_exec_timeout` | `600`                    | Seconds for a command that has no timeout. It raises `TimeoutError`.      |
+| `wait_timeout`         | `120`                    | Seconds to wait for a sandbox to start.                                   |
+| `base_url`             | `BRIQ_API_URL`, or the public API | The briq API.                                                    |
+
+The API key is read from `BRIQ_API_KEY` only: a key in the configuration would end up in the eval log.
+
+```python
+BriqSandboxEnvironmentConfig(
+    size="large",
+    env={"MODE": "test"},
+    secret_env=["GITHUB_TOKEN"],  # read from os.environ, never stored in the log
+)
+```
+
+`secret_env` fails with `unsupported` when the API cannot keep a value write-only. It never falls back to a plain variable.
+
+## What is supported
+
+| Inspect                                | On briq                                                                   |
+| -------------------------------------- | ------------------------------------------------------------------------- |
+| `exec` with `cwd`, `env`, `timeout`, `input` | Yes. `input` is text: bytes that are not UTF-8 fail `unsupported`.  |
+| `exec(user=...)`, `read_file(user=...)`, `write_file(user=...)` | No: `SandboxUserUnsupportedError`. Commands run as the sandbox's own user. |
+| `read_file`, `write_file`              | Yes. Missing directories are created. A file over 100 MiB fails.          |
+| Sample `files` and `setup`             | Yes, through `write_file` and `exec`.                                     |
+| One sandbox per sample                 | Yes, named `default`.                                                     |
+| Several named sandboxes per sample     | No.                                                                       |
+| `connection()` (`inspect sandbox shell`) | No.                                                                     |
+| Docker `compose.yaml` and `Dockerfile` | No. Use `image`.                                                          |
+
+`timeout_retry` and `concurrency` have no effect: a command that outlives its timeout is stopped and raises `TimeoutError` at once. Limit parallel sandboxes with `--max-sandboxes`.
+
+Errors:
+
+| Raised                       | When                                                         |
+| ---------------------------- | ------------------------------------------------------------ |
+| `FileNotFoundError`          | The file does not exist.                                     |
+| `TimeoutError`               | A command or a call outlived its timeout.                    |
+| `SandboxUnavailableError`    | The sandbox is gone or briq could not take the call.         |
+| `OutputLimitExceededError`   | Output or a file is over Inspect's limit.                    |
+| `briq_cloud.BriqError`       | Anything else: quota, credits, plan, a wrong key. It has a stable `code`. |
+
+A command whose end is not known raises `BriqError` with `code="outcome_unknown"`. It is never repeated.
+
+## Clean up
+
+A sample's sandbox is destroyed when the sample ends, also when it fails or is cancelled. If the evaluation is killed, its sandboxes stay: they sleep after `sleep` and are not billed while asleep. Destroy them from the dashboard, or with `briq_cloud`: `AsyncBriq().sandbox(id).destroy()`.
+
+## Develop
+
+Needs [uv](https://docs.astral.sh/uv/).
+
+```sh
+uv sync
+uv run pytest          # offline, the briq client is faked
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+```
+
+## License
+
+MIT

inspect_briq-0.1.0/README.md

@@ -0,0 +1,113 @@
+# inspect-briq
+
+[![ci](https://github.com/briq-cloud/inspect-briq/actions/workflows/ci.yml/badge.svg)](https://github.com/briq-cloud/inspect-briq/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/inspect-briq)](https://pypi.org/project/inspect-briq/) [![license: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+Run [Inspect AI](https://inspect.aisi.org.uk/) sandboxes on [briq](https://briq.cloud). Each sample gets its own microVM, destroyed when the sample ends.
+
+```python
+from inspect_ai import Task, task
+from inspect_ai.dataset import Sample
+from inspect_ai.scorer import includes
+from inspect_ai.solver import generate, use_tools
+from inspect_ai.tool import bash
+from inspect_ai.util import SandboxEnvironmentSpec
+from inspect_briq import BriqSandboxEnvironmentConfig
+
+
+@task
+def kernel():
+    return Task(
+        dataset=[
+            Sample(
+                input="Run `uname -s` with the bash tool and tell me its output.",
+                target="Linux",
+                files={"notes.txt": "one file per sample, copied in before the first message"},
+            )
+        ],
+        solver=[use_tools(bash(timeout=30)), generate()],
+        scorer=includes(),
+        sandbox=SandboxEnvironmentSpec("briq", BriqSandboxEnvironmentConfig(size="medium")),
+    )
+```
+
+```sh
+pip install inspect-briq
+export BRIQ_API_KEY=...
+inspect eval kernel.py --model anthropic/claude-sonnet-4-5
+```
+
+`sandbox="briq"` uses the defaults. Python 3.11 or later (what Inspect needs), asyncio backend.
+
+## Configure
+
+`BriqSandboxEnvironmentConfig`, or a JSON file with the same fields: `sandbox=("briq", "briq.json")`.
+
+| Field                  | Default                  | Means                                                                     |
+| ---------------------- | ------------------------ | ------------------------------------------------------------------------- |
+| `size`                 | the API's default        | `small`, `medium`, `large` or `xlarge`. Anything else fails `unsupported`. |
+| `image`                | briq's sandbox image     | An OCI image.                                                             |
+| `sleep`                | `30m`                    | Idle time before the sandbox sleeps: `30m`, `3h`, `7d`, `never`.          |
+| `working_dir`          | `/work`                  | Where commands run and relative paths resolve.                            |
+| `env`                  | none                     | Variables of the sandbox. They show in its status and in the eval log.    |
+| `secret_env`           | none                     | Names of variables of the eval process, sent write-only. Needs API support. |
+| `default_exec_timeout` | `600`                    | Seconds for a command that has no timeout. It raises `TimeoutError`.      |
+| `wait_timeout`         | `120`                    | Seconds to wait for a sandbox to start.                                   |
+| `base_url`             | `BRIQ_API_URL`, or the public API | The briq API.                                                    |
+
+The API key is read from `BRIQ_API_KEY` only: a key in the configuration would end up in the eval log.
+
+```python
+BriqSandboxEnvironmentConfig(
+    size="large",
+    env={"MODE": "test"},
+    secret_env=["GITHUB_TOKEN"],  # read from os.environ, never stored in the log
+)
+```
+
+`secret_env` fails with `unsupported` when the API cannot keep a value write-only. It never falls back to a plain variable.
+
+## What is supported
+
+| Inspect                                | On briq                                                                   |
+| -------------------------------------- | ------------------------------------------------------------------------- |
+| `exec` with `cwd`, `env`, `timeout`, `input` | Yes. `input` is text: bytes that are not UTF-8 fail `unsupported`.  |
+| `exec(user=...)`, `read_file(user=...)`, `write_file(user=...)` | No: `SandboxUserUnsupportedError`. Commands run as the sandbox's own user. |
+| `read_file`, `write_file`              | Yes. Missing directories are created. A file over 100 MiB fails.          |
+| Sample `files` and `setup`             | Yes, through `write_file` and `exec`.                                     |
+| One sandbox per sample                 | Yes, named `default`.                                                     |
+| Several named sandboxes per sample     | No.                                                                       |
+| `connection()` (`inspect sandbox shell`) | No.                                                                     |
+| Docker `compose.yaml` and `Dockerfile` | No. Use `image`.                                                          |
+
+`timeout_retry` and `concurrency` have no effect: a command that outlives its timeout is stopped and raises `TimeoutError` at once. Limit parallel sandboxes with `--max-sandboxes`.
+
+Errors:
+
+| Raised                       | When                                                         |
+| ---------------------------- | ------------------------------------------------------------ |
+| `FileNotFoundError`          | The file does not exist.                                     |
+| `TimeoutError`               | A command or a call outlived its timeout.                    |
+| `SandboxUnavailableError`    | The sandbox is gone or briq could not take the call.         |
+| `OutputLimitExceededError`   | Output or a file is over Inspect's limit.                    |
+| `briq_cloud.BriqError`       | Anything else: quota, credits, plan, a wrong key. It has a stable `code`. |
+
+A command whose end is not known raises `BriqError` with `code="outcome_unknown"`. It is never repeated.
+
+## Clean up
+
+A sample's sandbox is destroyed when the sample ends, also when it fails or is cancelled. If the evaluation is killed, its sandboxes stay: they sleep after `sleep` and are not billed while asleep. Destroy them from the dashboard, or with `briq_cloud`: `AsyncBriq().sandbox(id).destroy()`.
+
+## Develop
+
+Needs [uv](https://docs.astral.sh/uv/).
+
+```sh
+uv sync
+uv run pytest          # offline, the briq client is faked
+uv run ruff check . && uv run ruff format --check .
+uv run mypy
+```
+
+## License
+
+MIT

inspect_briq-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "inspect-briq"
+dynamic = ["version"]
+description = "Run Inspect AI sandboxes on briq: one microVM per sample."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["inspect", "inspect-ai", "evals", "sandbox", "briq", "agents"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = ["inspect-ai>=0.3.287", "briq-cloud>=0.1.1,<0.2", "pydantic>=2", "typing-extensions>=4.5"]
+
+[project.urls]
+Homepage = "https://briq.cloud"
+Repository = "https://github.com/briq-cloud/inspect-briq"
+
+# Inspect loads this module at startup, which registers the "briq" sandbox type.
+[project.entry-points.inspect_ai]
+inspect_briq = "inspect_briq._registry"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "mypy>=1.11", "ruff>=0.6"]
+
+[tool.hatch.version]
+path = "src/inspect_briq/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/inspect_briq"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-p no:cacheprovider"
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "RUF", "C4", "PT"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+files = ["src", "tests"]

inspect_briq-0.1.0/src/inspect_briq/__init__.py

@@ -0,0 +1,7 @@
+"""Inspect AI sandbox environment on briq: one microVM per sample."""
+
+from ._config import BriqSandboxEnvironmentConfig
+from ._environment import BriqSandboxEnvironment
+from ._version import __version__
+
+__all__ = ["BriqSandboxEnvironment", "BriqSandboxEnvironmentConfig", "__version__"]

inspect_briq-0.1.0/src/inspect_briq/_config.py

@@ -0,0 +1,94 @@
+"""The configuration of a ``briq`` sandbox: a typed object, or a JSON file that holds one."""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+from briq_cloud import BriqError
+from pydantic import BaseModel, ConfigDict, Field
+
+SIZES = ("small", "medium", "large", "xlarge")
+
+_SLEEP = re.compile(r"\d+[mhd]|never")
+_ENV_NAME = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
+
+
+class BriqSandboxEnvironmentConfig(BaseModel):
+    """How each sample's sandbox is made.
+
+    The API key is never part of the configuration (it would end up in the eval log): set
+    ``BRIQ_API_KEY``.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    base_url: str | None = None
+    """The briq API. Default: ``BRIQ_API_URL``, then ``https://api.briq.cloud``."""
+
+    size: str | None = None
+    """``small``, ``medium``, ``large`` or ``xlarge``. Default: the API's default (``small``)."""
+
+    image: str | None = None
+    """An OCI image for the sandbox. Default: briq's sandbox image."""
+
+    sleep: str = "30m"
+    """Idle time before the sandbox sleeps (``30m``, ``3h``, ``7d`` or ``never``). A killed
+    evaluation leaves its sandboxes to sleep, which is not billed."""
+
+    working_dir: str = "/work"
+    """Where commands run and relative paths resolve."""
+
+    env: dict[str, str] = Field(default_factory=dict)
+    """Environment variables of the sandbox. They show in the sandbox's status and in the eval
+    log: no secrets here."""
+
+    secret_env: list[str] = Field(default_factory=list)
+    """Names of variables of *this* process whose values go to the sandbox write-only. The values
+    are not stored in the configuration or the log. The API must support it: if it does not,
+    creating the sandbox fails with ``unsupported``."""
+
+    default_exec_timeout: int = 600
+    """Seconds a command may run when ``exec`` is given no timeout. Longer commands are stopped
+    and raise ``TimeoutError``. 1 second to 24 hours."""
+
+    wait_timeout: int = 120
+    """Seconds to wait for a sandbox to start."""
+
+    def __hash__(self) -> int:
+        # Inspect keeps configurations in dicts, and the dict and list fields are not hashable.
+        return hash(self.model_dump_json())
+
+    def check(self) -> None:
+        """Fail with ``unsupported`` or ``invalid_argument`` before any request is made."""
+        if self.size is not None and self.size not in SIZES:
+            raise BriqError("unsupported", f"size is one of {', '.join(SIZES)}, not {self.size!r}")
+        if not _SLEEP.fullmatch(self.sleep):
+            raise BriqError("invalid_argument", "sleep is like '30m', '3h', '7d' or 'never'")
+        if not self.working_dir.startswith("/"):
+            raise BriqError("invalid_argument", "working_dir is an absolute path")
+        if not 1 <= self.default_exec_timeout <= 86_400:
+            raise BriqError("invalid_argument", "default_exec_timeout is 1 second to 24 hours")
+        for name in self.secret_env:
+            if not _ENV_NAME.fullmatch(name):
+                raise BriqError("invalid_argument", f"{name!r} is not a variable name")
+        if set(self.env) & set(self.secret_env):
+            raise BriqError("invalid_argument", "A variable is in both env and secret_env")
+
+
+def resolve_config(config: object) -> BriqSandboxEnvironmentConfig:
+    """What Inspect passes as ``config``: nothing, our object, or the path of a JSON file."""
+    if config is None:
+        resolved = BriqSandboxEnvironmentConfig()
+    elif isinstance(config, BriqSandboxEnvironmentConfig):
+        resolved = config
+    elif isinstance(config, str):
+        resolved = BriqSandboxEnvironmentConfig.model_validate(json.loads(Path(config).read_text()))
+    else:
+        raise TypeError(
+            "The briq sandbox takes a BriqSandboxEnvironmentConfig or the path of a JSON file, "
+            f"not {type(config).__name__}"
+        )
+    resolved.check()
+    return resolved

inspect_briq-0.1.0/src/inspect_briq/_environment.py

@@ -0,0 +1,239 @@
+"""The ``briq`` sandbox environment: one briq sandbox per sample."""
+
+from __future__ import annotations
+
+import errno
+import logging
+import os
+import posixpath
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any, Literal, overload
+
+from briq_cloud import AsyncBriq, AsyncSandbox, BriqError
+from inspect_ai.util import (
+    ExecResult,
+    OutputLimitExceededError,
+    SandboxEnvironment,
+    SandboxEnvironmentConfigType,
+    SandboxEnvironmentLimits,
+    SandboxUnavailableError,
+    SandboxUserUnsupportedError,
+    sandboxenv,
+)
+from pydantic import BaseModel
+from typing_extensions import override
+
+from ._config import BriqSandboxEnvironmentConfig, resolve_config
+
+logger = logging.getLogger(__name__)
+
+
+@sandboxenv(name="briq")
+class BriqSandboxEnvironment(SandboxEnvironment):
+    """A sample's sandbox, a briq microVM that is destroyed when the sample ends.
+
+    Not supported, and refused instead of ignored: ``user`` (commands run as the sandbox's own
+    user), ``input`` that is not UTF-8, several sandboxes per sample, ``connection()``.
+    """
+
+    def __init__(
+        self, client: AsyncBriq, sandbox: AsyncSandbox, config: BriqSandboxEnvironmentConfig
+    ) -> None:
+        super().__init__()
+        self._client = client
+        self._sandbox = sandbox
+        self._config = config
+
+    @property
+    def sandbox_id(self) -> str:
+        return self._sandbox.id
+
+    # --- the sandbox ---
+
+    @override
+    async def exec(
+        self,
+        cmd: list[str],
+        input: str | bytes | None = None,
+        cwd: str | None = None,
+        env: dict[str, str] | None = None,
+        user: str | None = None,
+        timeout: int | None = None,
+        timeout_retry: bool = True,
+        concurrency: bool = True,
+    ) -> ExecResult[str]:
+        _refuse_user(user)
+        stdin = _text(input) if input is not None else None
+        with _inspect_errors():
+            result = await self._sandbox.exec(
+                cmd,
+                cwd=self._path(cwd) if cwd is not None else self._config.working_dir,
+                env=env or None,
+                stdin=stdin,
+                timeout=float(timeout or self._config.default_exec_timeout),
+            )
+        if result.timed_out:
+            raise TimeoutError(
+                f"The command did not end within {timeout or self._config.default_exec_timeout} s"
+            )
+        if result.exit_code is None:
+            raise RuntimeError("briq did not report how the command ended")
+        for stream in (result.stdout, result.stderr):
+            if len(stream.encode()) > SandboxEnvironmentLimits.MAX_EXEC_OUTPUT_SIZE:
+                raise OutputLimitExceededError(
+                    SandboxEnvironmentLimits.MAX_EXEC_OUTPUT_SIZE_STR, stream[-4096:]
+                )
+        return ExecResult(
+            success=result.exit_code == 0,
+            returncode=result.exit_code,
+            stdout=result.stdout,
+            stderr=result.stderr,
+        )
+
+    @override
+    async def write_file(
+        self, file: str, contents: str | bytes, *, user: str | None = None
+    ) -> None:
+        _refuse_user(user)
+        data = contents.encode() if isinstance(contents, str) else contents
+        with _inspect_errors(file):
+            await self._sandbox.write_file(self._path(file), data)
+
+    @overload
+    async def read_file(
+        self, file: str, text: Literal[True] = True, *, user: str | None = None
+    ) -> str: ...
+
+    @overload
+    async def read_file(
+        self, file: str, text: Literal[False], *, user: str | None = None
+    ) -> bytes: ...
+
+    @override
+    async def read_file(
+        self, file: str, text: bool = True, *, user: str | None = None
+    ) -> str | bytes:
+        _refuse_user(user)
+        with _inspect_errors(file):
+            data = await self._sandbox.read_file(self._path(file))
+        if len(data) > SandboxEnvironmentLimits.MAX_READ_FILE_SIZE:
+            raise OutputLimitExceededError(SandboxEnvironmentLimits.MAX_READ_FILE_SIZE_STR, None)
+        return data.decode("utf-8") if text else data
+
+    def _path(self, path: str) -> str:
+        """Relative paths resolve against ``working_dir``, as the Inspect contract says."""
+        return posixpath.join(self._config.working_dir, path)
+
+    # --- the lifecycle ---
+
+    @override
+    @classmethod
+    async def task_init(cls, task_name: str, config: SandboxEnvironmentConfigType | None) -> None:
+        """Fail before the first sample when the configuration or the API key is wrong."""
+        resolved = resolve_config(config)
+        client = AsyncBriq(base_url=resolved.base_url)  # no key, or a bad one: raises here
+        await client.close()
+        _secrets(resolved)
+
+    @override
+    @classmethod
+    async def sample_init(
+        cls,
+        task_name: str,
+        config: SandboxEnvironmentConfigType | None,
+        metadata: dict[str, str],
+    ) -> dict[str, SandboxEnvironment]:
+        resolved = resolve_config(config)
+        secrets = _secrets(resolved)
+        client = AsyncBriq(base_url=resolved.base_url)
+        try:
+            sandbox = await client.create_sandbox(
+                size=resolved.size,
+                image=resolved.image,
+                env=resolved.env or None,
+                secret_env=secrets or None,
+                sleep=resolved.sleep,
+                wait_timeout=resolved.wait_timeout,
+            )
+        except BaseException:
+            await _close(client)
+            raise
+        return {"default": cls(client, sandbox, resolved)}
+
+    @override
+    @classmethod
+    async def sample_cleanup(
+        cls,
+        task_name: str,
+        config: SandboxEnvironmentConfigType | None,
+        environments: dict[str, SandboxEnvironment],
+        interrupted: bool,
+    ) -> None:
+        for environment in environments.values():
+            if not isinstance(environment, BriqSandboxEnvironment):
+                continue
+            try:
+                await environment._sandbox.destroy()
+            except Exception as error:
+                # A failed cleanup must not fail the sample. An idle sandbox sleeps, unbilled.
+                logger.warning(
+                    "Could not destroy briq sandbox %s: %s", environment.sandbox_id, error
+                )
+            finally:
+                await _close(environment._client)
+
+    @override
+    @classmethod
+    def config_deserialize(cls, config: dict[str, Any]) -> BaseModel:
+        return BriqSandboxEnvironmentConfig.model_validate(config)
+
+
+def _secrets(config: BriqSandboxEnvironmentConfig) -> dict[str, str]:
+    """The values of ``secret_env``, read from this process."""
+    missing = [name for name in config.secret_env if name not in os.environ]
+    if missing:
+        raise BriqError(
+            "invalid_argument", f"secret_env names variables that are not set: {', '.join(missing)}"
+        )
+    return {name: os.environ[name] for name in config.secret_env}
+
+
+def _refuse_user(user: str | None) -> None:
+    if user is not None:
+        raise SandboxUserUnsupportedError(
+            "briq runs commands as the sandbox's own user: it cannot run them as another"
+        )
+
+
+def _text(value: str | bytes) -> str:
+    if isinstance(value, str):
+        return value
+    try:
+        return value.decode("utf-8")
+    except UnicodeDecodeError:
+        raise BriqError(
+            "unsupported", "briq takes text for stdin: the input is not UTF-8"
+        ) from None
+
+
+async def _close(client: AsyncBriq) -> None:
+    try:
+        await client.close()
+    except Exception:
+        logger.debug("Could not close the briq client", exc_info=True)
+
+
+@contextmanager
+def _inspect_errors(file: str | None = None) -> Iterator[None]:
+    """A ``BriqError`` as the exception Inspect's contract names, where there is one."""
+    try:
+        yield
+    except BriqError as error:
+        if error.code == "file_not_found":
+            raise FileNotFoundError(errno.ENOENT, "No such file or directory.", file) from error
+        if error.code in ("unavailable", "not_found"):
+            raise SandboxUnavailableError(str(error)) from error
+        if error.code == "timeout":
+            raise TimeoutError(str(error)) from error
+        raise

inspect_briq-0.1.0/src/inspect_briq/_registry.py

@@ -0,0 +1,5 @@
+"""The module Inspect loads (entry point group ``inspect_ai``): importing it registers ``briq``."""
+
+from ._environment import BriqSandboxEnvironment
+
+__all__ = ["BriqSandboxEnvironment"]

inspect_briq-0.1.0/src/inspect_briq/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"