Metadata-Version: 2.4
Name: inspect_tool_support
Version: 1.1.1
Summary: Sandbox container tool code for inspect_ai
Author: UK AI Security Institute
License: MIT License
Project-URL: CHANGELOG, https://raw.githubusercontent.com/UKGovernmentBEIS/inspect_ai/refs/heads/feature/tool-support-fast-follow/src/inspect_tool_support/CHANGELOG.md
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: aiohttp
Requires-Dist: httpx
Requires-Dist: jsonrpcserver
Requires-Dist: mcp
Requires-Dist: packaging
Requires-Dist: pydantic
Requires-Dist: returns
Requires-Dist: semver
Requires-Dist: tenacity
Requires-Dist: playwright
Requires-Dist: psutil
Provides-Extra: dev
Requires-Dist: bump2version; extra == "dev"
Requires-Dist: ruff==0.9.6; extra == "dev"
Requires-Dist: towncrier; extra == "dev"
Requires-Dist: types-psutil; extra == "dev"
Provides-Extra: dist
Requires-Dist: twine; extra == "dist"
Requires-Dist: build; extra == "dist"

# Design

![diagram](https://raw.githubusercontent.com/UKGovernmentBEIS/inspect_ai/refs/heads/main/src/inspect_tool_support/shared_tool_container_design.svg)

Inspect calls into the sandboxed image are done statelessly via `docker exec inspect-tool-support`.

Some tools can be implemented without the need for any in-process state. For those tools, the tool code will be executed within the `inspect-tool-support` process.

For tools that require the maintenance of state over the lifetime of and sandbox, this image marshals tool calls into a long running process via JSON RPC to an http server process. That server then dispatches tool calls to tool specific `@method` handlers.

### Stateful Tool Design Pattern

Each stateful tool should have its own subdirectory that contains the following files:

- `json_rpc_methods.py`

  This module contains all of the JSON RPC `@method` functions — one for each tool (e.g. the web browser tool is actually a set of distinct tools). It is responsible for unpacking the JSON RPC request and forwarding the call to a transport-agnostic, strongly typed, stateful controller.

- `tool_types.py`

  This module includes the `pydantic` models representing the types for tool call parameters and results.

- `controller.py`

  This is transport-agnostic, strongly typed code that manages the tool specific in-process state and performs requested commands.

## Release Process

### Overview

The release process for this project separates code commits from package publishing. While developers can make frequent commits to the repository, package releases are performed on a different tempo, typically when enough meaningful changes have accumulated. This approach allows for continuous development while providing stable, well-documented releases.

Pending changelog items in the `unreleased_changes/` directory serve two key purposes:

1. They document all changes that will be included in the next release
2. They determine what type of semantic version bump (major, minor, or patch) will be needed when publishing these pending changes

This system ensures that version numbers accurately reflect the nature of changes between releases according to semantic versioning principles.

### Documenting Changes

All changes should be documented using [`towncrier`](https://towncrier.readthedocs.io/). When making changes to the codebase, developers should create pending changelog items that will be used to update the changelog at release time:

1. Use `towncrier create` to create a new pending changelog item:

   This will interactively prompt you for:

   - The (optional) related issue
   - The type of semantic version change (major, minor, or patch)
   - A description of your change (supporting markdown)

   Alternatively, all options can be provided directly on the command line:

   ```
   towncrier create <issue-number>.[major|minor|patch].md
   ```

   For more details on `towncrier`'s command line options, refer to the [`towncrier` documentation](https://towncrier.readthedocs.io/en/latest/cli.html).

2. Pending changelog items are stored in the `unreleased_changes/` directory and accumulate until the next release.

### Creating a Release

When it's time to make a release:

1. Ensure all changes are committed.

2. Run the `make-release-commit` script:

3. The script automatically:
   - Determines the version bump type (major, minor, or patch) based on the pending changelog items
   - Runs `towncrier build` to incorporate all pending changelog items into `CHANGELOG.md`
   - Updates the version in `pyproject.toml` using `bump2version`
   - Commits the changes into a commit with a message like `Bump inspect-tool-support version: 1.0.2 → 1.1.0`
   - Tags the commit with the new version number `inspect-tool-support-1.1.0`

All changelog items are consumed during the release process and converted into entries in the `CHANGELOG.md` file. After the release, the `unreleased_changes/` directory will be empty, ready to collect changes for the next release cycle.
