diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..01633cc --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,29 @@ +name: ci + +on: + push: + branches: [main] + pull_request: + +permissions: + contents: read + +jobs: + test: + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + python: ["3.9", "3.12", "3.13"] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python }} + - run: python -m unittest discover -s tests -v + - name: Build and check the package + if: matrix.python == '3.12' + run: | + python -m pip install --upgrade pip build twine + python -m build + python -m twine check --strict dist/* diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..644a30a --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,132 @@ +# Build, check and publish the `drums-sdk` package (import name: drums). +# +# push of a tag v* -> build, test, publish to PyPI (environment "pypi", Trusted Publishing) +# workflow_dispatch -> build, test, publish to TestPyPI (environment "testpypi", Trusted Publishing) +# +# No tokens live in this repository. Publishing uses PyPI Trusted Publishing (OIDC): the job requests an id-token, +# pypi.org checks it against the publisher registered for the project. Fallback: if a PYPI_API_TOKEN (or +# TEST_PYPI_API_TOKEN) repository secret exists, the publish action uses it instead of OIDC. See RELEASE.md. +name: release + +on: + push: + tags: ["v*"] + workflow_dispatch: + +permissions: + contents: read + +jobs: + build: + name: build sdist and wheel + runs-on: ubuntu-latest + outputs: + version: ${{ steps.meta.outputs.version }} + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + - name: Read the version + id: meta + run: | + v=$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])') + echo "version=$v" >> "$GITHUB_OUTPUT" + echo "package version: $v" + - name: Release gates + run: | + set -e + grep -Eq '^license = "' pyproject.toml \ + || { echo 'pyproject.toml: the license line is still commented out (RELEASE.md step 0)'; exit 1; } + grep -q 'PLACEHOLDER' LICENSE && { echo 'LICENSE is still a placeholder'; exit 1; } + python - <<'PY' + import re, tomllib + v = tomllib.load(open("pyproject.toml", "rb"))["project"]["version"] + src = open("drums/__init__.py").read() + m = re.search(r'^__version__ = "([^"]+)"', src, re.M) + assert m and m.group(1) == v, f"drums.__version__ {m and m.group(1)} != pyproject {v}" + print("version in sync:", v) + PY + if [ "${GITHUB_REF_TYPE}" = "tag" ]; then + [ "${GITHUB_REF_NAME}" = "v${{ steps.meta.outputs.version }}" ] \ + || { echo "tag ${GITHUB_REF_NAME} does not match version v${{ steps.meta.outputs.version }}"; exit 1; } + fi + - name: Build + run: | + python -m pip install --upgrade pip build twine + python -m build + python -m twine check --strict dist/* + - uses: actions/upload-artifact@v4 + with: + name: dist + path: dist/ + if-no-files-found: error + + test: + name: test the wheel on ${{ matrix.python }} + needs: build + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + python: ["3.9", "3.10", "3.11", "3.12", "3.13"] + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python }} + - uses: actions/download-artifact@v4 + with: + name: dist + path: dist/ + - name: Install the wheel into a clean venv and run the tests against it + run: | + python -m venv v + v/bin/pip install --quiet dist/*.whl + v/bin/python -c 'import drums; assert drums.Client; print("drums", drums.__version__)' + # The tests must import the installed wheel, not the checkout: run them from another directory. + mkdir -p run && cp -r tests run/tests && cd run + ../v/bin/python -m unittest discover -s tests -v + + publish-testpypi: + name: publish to TestPyPI + if: github.event_name == 'workflow_dispatch' + needs: [build, test] + runs-on: ubuntu-latest + environment: + name: testpypi + url: https://test.pypi.org/project/drums-sdk/${{ needs.build.outputs.version }}/ + permissions: + id-token: write + steps: + - uses: actions/download-artifact@v4 + with: + name: dist + path: dist/ + - uses: pypa/gh-action-pypi-publish@release/v1 + with: + repository-url: https://test.pypi.org/legacy/ + # Empty when the secret does not exist: the action then uses Trusted Publishing (OIDC). + password: ${{ secrets.TEST_PYPI_API_TOKEN }} + print-hash: true + + publish-pypi: + name: publish to PyPI + if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') + needs: [build, test] + runs-on: ubuntu-latest + environment: + name: pypi + url: https://pypi.org/project/drums-sdk/${{ needs.build.outputs.version }}/ + permissions: + id-token: write + steps: + - uses: actions/download-artifact@v4 + with: + name: dist + path: dist/ + - uses: pypa/gh-action-pypi-publish@release/v1 + with: + # Empty when the secret does not exist: the action then uses Trusted Publishing (OIDC). + password: ${{ secrets.PYPI_API_TOKEN }} + print-hash: true diff --git a/.gitignore b/.gitignore index a5f38aa..39b1744 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,5 @@ __pycache__/ *.pyc .venv/ *.egg-info/ +dist/ +build/ diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..d89df46 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,72 @@ +# Changelog + +All notable changes to the `drums` Python SDK. The SDK talks to drumsd over its HTTP API; the drumsd version each +SDK version was built against is noted where it matters. + +## 0.2.5 - first release on PyPI + +The first version published on PyPI, as `drums-sdk` (`pip install drums-sdk`; the import name stays `drums`). Versions 0.2.0 to 0.2.4 shipped as wheels sent with invites. +Everything below in the 0.2.x entries is included. + +Packaging and release: + +- Package metadata for PyPI: readme, classifiers, project URLs, `requires-python >= 3.9`, no runtime dependencies. +- `LICENSE`, `CHANGELOG.md`, `RELEASE.md`, and a GitHub Actions release workflow (PyPI Trusted Publishing, TestPyPI + on demand). +- Docstrings no longer point at documents that live in other repositories. + +Since 0.2.4 (drumsd 0.4.2 and later): + +- `Env.prefork()`: prepare a fork right after an action, so a later `fork()` from that point is fast. +- `Reward.audit`, `Reward.audit_flags`, `Reward.trusted`: the per-rollout reward audit drumsd returns (recheck, + redundant checker, scope, checker timeout or crash). `trusted` is `True` only for a valid episode with a score and + no audit flag; an older drumsd sends no audit, so `trusted` is `None`, never `True`. +- `drums.hybrid`: GUI, shell, file and app-API tools over one desktop (`HybridTools`, and `TOOLS` as JSON schema). +- `drums.mcp`: an MCP stdio server exposing the hybrid tools plus `verify`; `python -m drums.mcp --env ID` or + `--create [--task task.json]`. Token from `DRUMS_TOKEN`, else the file in `DRUMS_TOKEN_FILE`, else + `/etc/drums/token`. A bound env is never closed on exit; a created one is. +- `TaskUnsupported` (422 `task_unsupported`): the task needs the agent itself to act as root, which this execution + profile does not allow. Setup steps that need root are run by drumsd as provisioning and are supported. + +## 0.2.4 + +- `EnvGone` (410, and the older 409 "slot is destroyed"); `close()` is a no-op on a gone env. +- `fork()` returns `ForkResult`: the list of children plus `.state`, the saved state the fork made. + `keep_state=False` deletes it when the children close. `last_state` and `last_fork` are deprecated. +- Leases on `create`, `fork` and `save` (`idle_timeout=`, `ttl=`; default: reaped after 30 minutes unused). +- The client closes the envs it created at process exit, on SIGTERM/SIGHUP (when their handlers were the default) + and when used as a context manager; `connect(..., close_on_exit=False)` turns that off. +- `Reward.invalid_reasons`. +- The legacy `env()` entry point defaults to the installed image. + +## 0.2.3 + +- `client.env_records()` pages through env records (destroyed ones opt-in). +- `CheckpointStale` for a saved state made from an installed image that has since changed. + +## 0.2.2 + +- `step()` raises `ActionFailed` when the action ran and exited non-zero; `check=False` returns the result as is. +- `Overloaded` (429): create, save and fork are refused near the host's memory limit. +- `drums.aio` runs calls on its own thread pool (`max_threads`, default 1024), not the event loop's default + executor, so N envs driven with `asyncio.gather` really run N calls at once. + +## 0.2.1 + +- `NotQuiescent` (a `Conflict`), `env.wait_quiescent(timeout, window)`, and `quiesce_timeout=` on `fork` and `save`. +- `client.delete_state()`, `env.from_state`. +- `Client()` takes the token from `DRUMS_TOKEN` when none is given. +- `env.wait_valid()` blocks until the episode's alive gate resolves and raises `GateFailed` if it is invalid. + +## 0.2.0 + +- New client: `connect(url, token)`, `client.create(image, task, from_state)`, and on an env `step`, `observe`, + `fork`, `save`, `verify`, `reset`, `close`. +- Typed errors carrying the server's status, message and body; errors about an env carry its record and gate report. +- GET-only retries while the daemon is unreachable; POST and DELETE are never retried. +- Batch and asyncio variants; `client.metrics()`. +- Unit tests against a fake daemon (no network). + +## 0.1.0 + +- Thin client: `env`, `reset`, `step`, `branch`, `save`, `from_state`, `valid`. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..d645695 --- /dev/null +++ b/LICENSE @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/MANIFEST.in b/MANIFEST.in new file mode 100644 index 0000000..669d191 --- /dev/null +++ b/MANIFEST.in @@ -0,0 +1,5 @@ +include LICENSE +include README.md +include CHANGELOG.md +include RELEASE.md +recursive-include tests *.py diff --git a/README.md b/README.md new file mode 100644 index 0000000..aa4644e --- /dev/null +++ b/README.md @@ -0,0 +1,110 @@ +# drums-sdk + +Python SDK for [Drums](https://drums.run): isolated desktop environments for computer-use agents and RL. +Create a desktop, act in it, take screenshots, fork it into copies of the same state, and score it with a task's +checker. Standard library only; Python 3.9 or later. + +Full documentation: **[console.drums.run/docs](https://console.drums.run/docs)** + +## Five-minute start + +### 1. Install + +```bash +python3 -m venv drums-venv +drums-venv/bin/pip install drums-sdk +``` + +The package on PyPI is `drums-sdk`; the import name is `drums`. + +```python +import drums +``` + +### 2. Point it at your Drums + +The SDK reads two environment variables. Your API key comes from **API Keys** in the +[console](https://console.drums.run); it starts with `drums_sk_` and is shown once. + +```bash +export DRUMS_URL=https://beta.drums.run/gw # Drums Cloud gateway; or http://127.0.0.1:7070 for a local drumsd +export DRUMS_TOKEN=drums_sk_... # your API key +``` + +Check the connection: + +```python +import drums + +client = drums.connect() # reads DRUMS_URL and DRUMS_TOKEN +print(client.health()["version"]) +``` + +A `401` raises `drums.AuthError`: the key is mistyped, revoked or expired. + +### 3. Create a computer, screenshot, act, verify, destroy + +Save as `quickstart.py` and run `drums-venv/bin/python quickstart.py`. It starts a desktop with OSWorld task +`e0df059f` (rename a folder on the Desktop), waits until every gate of the episode has passed, saves a screenshot, +performs the task with one action, runs the task's checker and closes the desktop. + +```python +import drums + +with drums.connect() as client: # closes every desktop it created when the block ends + with client.create(task="e0df059f", ttl=900) as env: # OSWorld task id; ttl: lifetime in seconds + env.wait_valid() # every gate of this episode passed + obs = env.observe() # PNG screenshot plus metadata + open("screen.png", "wb").write(obs.png) + print("task:", obs.meta["instruction"]) + env.step({"type": "execute", "shell": True, + "command": "mv ~/Desktop/todo_list_Jan_1 ~/Desktop/todo_list_Jan_2"}) + reward = env.verify(strict=False) # the task's checker, with the episode's validity + print("score", reward.score, "valid", reward.valid, reward.invalid_reasons) + print("computers left:", len(client.envs())) # 0: the with-block destroyed it +``` + +Expected output (ids and sizes differ): + +```text +task: I have a directory named "todo_list_Jan_1". Can you help me change its name into "todo_list_Jan_2"? +score 1 valid True [] +computers left: 0 +``` + +A GUI agent acts with pyautogui instead of a shell command: `env.step("pyautogui.click(960, 540)")`. +Use a score only when `valid` is `True`; with the default `strict=True`, `verify()` raises `InvalidEpisode` +for an invalid episode instead of returning a reward. + +### 4. Go further + +- Fork one desktop into N copies of the same state for group rollouts: `with env.fork(8) as kids: ...` + ([guide](https://console.drums.run/docs/guides/group-rollouts-with-fork)) +- Run a policy over many tasks: [Evaluate on OSWorld](https://console.drums.run/docs/guides/evaluate-on-osworld) +- `drums.aio` is the asyncio variant of the same calls; `drums.hybrid` adds shell, file and app-API tools over one + desktop; `python -m drums.mcp` serves them to an agent over MCP (stdio). +- Every method: [Python SDK reference](https://console.drums.run/docs/reference/python-sdk). + Every endpoint: [HTTP API](https://console.drums.run/docs/reference/http-api). + If something fails: [Errors](https://console.drums.run/docs/reference/errors). + +## How it behaves + +- **Cleanup.** `with drums.connect() as client:` closes every desktop the client created when the block ends, and so + do process exit and SIGTERM/SIGHUP. Desktops and saved states also have server-side leases (default: reaped after + 30 minutes unused), so a crashed trainer does not hold a host. +- **Validity.** Every episode starts with a gate report (isolation, mounts, network, limits, state hash, processes + alive after resume). `Reward.valid` is `True` only when every gate passed and the desktop was never quarantined. +- **Retries.** GET requests are retried while the server is unreachable (up to `retry_s`, default 60 s). POST and + DELETE are never retried: after a lost reply the outcome is unknown, so check `client.envs()` before trying again. +- **Errors.** Every failure is a typed exception under `drums.DrumsError` carrying the server's status, message and + body; errors about a desktop carry its record and gate report. + +## Development + +```bash +git clone https://github.com/Drums-Labs/drums-python-sdk.git +cd drums-python-sdk +python3 -m unittest discover -s tests -v # runs against a fake daemon; no network +``` + +See [CHANGELOG.md](CHANGELOG.md) for what changed in each version and [RELEASE.md](RELEASE.md) for how a release is cut. diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 0000000..5f2de49 --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,113 @@ +# Releasing `drums-sdk` to PyPI + +The distribution on PyPI is `drums-sdk`; the import name stays `drums`. (PyPI rejected the name `drums` as +too similar to the existing project `drum`.) + +The release is automated by `.github/workflows/release.yml`. A pushed tag `vX.Y.Z` builds, checks and tests the +package and publishes it to PyPI; a manual run of the workflow publishes to TestPyPI first. No tokens are stored in +the repository: publishing uses PyPI Trusted Publishing (OIDC). The commands below are everything the owner runs. + +## 0. One-time decisions and setup (owner) + +### 0.1 License + +Apache License 2.0 (`LICENSE`, `license = "Apache-2.0"` in `pyproject.toml`, confirmed 2026-11-12). The workflow +refuses to publish if the line is removed or `LICENSE` is a placeholder. + +### 0.2 Register the Trusted Publisher on PyPI + +The `drums-sdk` project does not exist on PyPI yet, so register a **pending** publisher (it becomes the project's +publisher on the first upload). Signed in to pypi.org as the account that will own the project: + +1. Open https://pypi.org/manage/account/publishing/ +2. Under "Add a new pending publisher", choose **GitHub** and enter exactly: + + | Field | Value | + |---|---| + | PyPI project name | `drums-sdk` | + | Owner | `Drums-Labs` | + | Repository name | `drums-python-sdk` | + | Workflow name | `release.yml` | + | Environment name | `pypi` | + +3. Do the same on TestPyPI at https://test.pypi.org/manage/account/publishing/ with the environment name + `testpypi` (the other four fields identical). TestPyPI is a separate account; create one if needed. + +### 0.3 Create the GitHub environments + +In the repository: Settings -> Environments -> New environment. Create `pypi` and `testpypi`. For `pypi`, add +yourself as a required reviewer so a tag push cannot publish without a click from you. (Trusted Publishing is bound +to these environment names; the names must match the table above.) + +### 0.4 Fallback: an API token instead of OIDC + +Only if Trusted Publishing cannot be used: create a project-scoped API token on pypi.org and add it as the +repository secret `PYPI_API_TOKEN` (and `TEST_PYPI_API_TOKEN` for TestPyPI). The workflow uses a token when the secret +exists and OIDC otherwise. Never paste a token into a file, a command line or a chat. + +## 1. Merge the release PR + +Merge `pypi-release` into `main`. Confirm `main` is what you want +to ship: + +```bash +git checkout main && git pull --ff-only +python3 -m unittest discover -s tests +python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])' +``` + +The printed version is the release version; `drums/__init__.py` must say the same (`__version__`). + +## 2. TestPyPI first + +Run the workflow by hand; it publishes to TestPyPI only: + +```bash +gh workflow run release.yml --ref main +gh run watch +``` + +Then verify the TestPyPI package in a clean venv. `--extra-index-url` is not needed (the package has no +dependencies), and `--no-deps` makes sure nothing is pulled from anywhere else: + +```bash +cd "$(mktemp -d)" +python3 -m venv v && v/bin/pip install --no-deps -i https://test.pypi.org/simple/ drums-sdk +v/bin/python -c 'import drums; print(drums.__version__); drums.Client' +``` + +Check https://test.pypi.org/project/drums-sdk/ : the README renders, the links are right, the license shows. + +## 3. Tag and publish to PyPI + +```bash +V=$(python3 -c 'import tomllib; print(tomllib.load(open("pyproject.toml","rb"))["project"]["version"])') +git tag -a "v$V" -m "drums $V" +git push origin "v$V" +gh run watch +``` + +The `publish to PyPI` job waits for your approval on the `pypi` environment (step 0.3); approve it in the Actions +tab. The job prints the SHA256 of every file it uploads. + +## 4. Verify the public package + +```bash +cd "$(mktemp -d)" +python3 -m venv v && v/bin/pip install drums-sdk +v/bin/python -c 'import drums; print(drums.__version__); drums.Client' +``` + +Then check https://pypi.org/project/drums-sdk/ and create the GitHub release from the tag: + +```bash +gh release create "v$V" --title "drums $V" --notes-file <(awk "/^## $V/{f=1;next} /^## /{f=0} f" CHANGELOG.md) +``` + +## 5. After the first release + +- Later releases: bump `version` in `pyproject.toml` and `__version__` in `drums/__init__.py` together, add a + `CHANGELOG.md` entry, merge, then steps 2 to 4. The workflow fails if the tag and the version disagree. +- A version can be uploaded to PyPI exactly once. A broken release gets a new patch version, never a re-upload. +- Update the install instructions in the docs (`console.drums.run/docs/quickstart` and + `/docs/reference/python-sdk` still describe installing from a wheel file) to `pip install drums-sdk`. diff --git a/drums/__init__.py b/drums/__init__.py index feae5aa..e76adc3 100644 --- a/drums/__init__.py +++ b/drums/__init__.py @@ -422,7 +422,7 @@ def __init__(self, d: dict): self.checker_skipped = d.get("checker_skipped") # e.g. "quarantined: client": the checker did not run self.gates = d.get("gates") self.seconds = d.get("seconds") - # the reward audit (drumsd >= sota/t6): recheck, redundant checker, scope (reward-hacking signal), checker + # the reward audit (drumsd 0.4.2 and later): recheck, redundant checker, scope (reward-hacking signal), checker # timeout/crash. `trusted` is True only for a valid episode with a score and no audit flag; an older drumsd # sends no audit, so `trusted` is None (unknown), never True. self.audit = d.get("audit") or {} @@ -499,7 +499,7 @@ def step(self, action, screenshot: bool = False, check: bool = True) -> StepResu """pyautogui code (str) or an action dict: {"type": "pyautogui", "code"}, {"type": "execute", "command", "shell"}, {"type": "launch", "command", "shell"}, {"type": "sleep", "seconds"}. Screen 1920x1080, origin top left, pixels. pyautogui and execute run inside the env as its desktop user `user` (not root), with OSWorld's prefix - (`import pyautogui, time`). See docs/actions-and-observations.md. + (`import pyautogui, time`). See https://console.drums.run/docs/concepts/computers-and-templates#actions. check=True (default): an action that ran and exited non-zero raises ActionFailed with its exit status, output and error; check=False returns the result as is. A guest that does not answer or times out (120 s) raises GuestError either way.""" @@ -707,7 +707,7 @@ def __repr__(self): class GuestClient: - """The GuestClient protocol of drums-lab rlbackends (execute/launch/screenshot/screen_size/platform), through drumsd.""" + """The GuestClient protocol (execute/launch/screenshot/screen_size/platform) that RL backends use, through drumsd.""" def __init__(self, env: Env): self.env, self.base, self.timeout = env, f"{env.client.url}/v1/slots/{env.id}", env.client.timeout diff --git a/drums/errors.py b/drums/errors.py index 24d23e4..0ae730e 100644 --- a/drums/errors.py +++ b/drums/errors.py @@ -20,7 +20,7 @@ class BadRequest(DrumsError): class TaskUnsupported(BadRequest): """422 `task_unsupported`: the task needs the agent itself to act as root, and agents get no privilege escalation - in this execution profile (docs/custom-tasks.md). Nothing was started. `task_id` and `reason` say which and why. + in this execution profile (https://console.drums.run/docs/concepts/tasks-and-verifiers). Nothing was started. `task_id` and `reason` say which and why. A task whose setup alone needs root is supported: drumsd runs that step as trusted provisioning.""" def __init__(self, status: int, message: str, body=None): diff --git a/pyproject.toml b/pyproject.toml index 7cae9e7..d617a55 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,10 +1,45 @@ +[build-system] +requires = ["setuptools>=77"] +build-backend = "setuptools.build_meta" + [project] -name = "drums" +name = "drums-sdk" version = "0.2.5" -description = "Drums SDK: isolated desktop environments for computer-use RL (client for drumsd)" +# Distribution name drums-sdk (PyPI rejects "drums" as too similar to an existing project); import name: drums. +description = "Drums SDK: isolated desktop environments for computer-use RL. Create a desktop, act, screenshot, fork, verify." +readme = "README.md" requires-python = ">=3.9" -license = {text = "Apache-2.0"} +# SPDX expression (PEP 639); setuptools forbids a "License ::" classifier next to it. The release workflow checks +# that this line is set and that LICENSE holds the license text. +license = "Apache-2.0" +license-files = ["LICENSE"] +authors = [{name = "Drums Labs"}] +keywords = ["drums", "computer-use", "reinforcement-learning", "rl", "desktop", "environment", "osworld", "agents", "sandbox"] +classifiers = [ + "Development Status :: 3 - Alpha", + "Intended Audience :: Developers", + "Intended Audience :: Science/Research", + "Operating System :: OS Independent", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3 :: Only", + "Programming Language :: Python :: 3.9", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", + "Topic :: Scientific/Engineering :: Artificial Intelligence", + "Topic :: Software Development :: Libraries :: Python Modules", +] +# Standard library only: no runtime dependencies. +dependencies = [] -[build-system] -requires = ["setuptools>=61"] -build-backend = "setuptools.build_meta" +[project.urls] +Homepage = "https://drums.run" +Documentation = "https://console.drums.run/docs" +"SDK reference" = "https://console.drums.run/docs/reference/python-sdk" +Repository = "https://github.com/Drums-Labs/drums-python-sdk" +Changelog = "https://github.com/Drums-Labs/drums-python-sdk/blob/main/CHANGELOG.md" +Issues = "https://github.com/Drums-Labs/drums-python-sdk/issues" + +[tool.setuptools] +packages = ["drums"]