drums-sdk 0.2.5__tar.gz

drums_sdk-0.2.5/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`.

drums_sdk-0.2.5/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.

drums_sdk-0.2.5/MANIFEST.in

@@ -0,0 +1,5 @@
+include LICENSE
+include README.md
+include CHANGELOG.md
+include RELEASE.md
+recursive-include tests *.py

drums_sdk-0.2.5/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: drums-sdk
+Version: 0.2.5
+Summary: Drums SDK: isolated desktop environments for computer-use RL. Create a desktop, act, screenshot, fork, verify.
+Author: Drums Labs
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://drums.run
+Project-URL: Documentation, https://console.drums.run/docs
+Project-URL: SDK reference, https://console.drums.run/docs/reference/python-sdk
+Project-URL: Repository, https://github.com/Drums-Labs/drums-python-sdk
+Project-URL: Changelog, https://github.com/Drums-Labs/drums-python-sdk/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Drums-Labs/drums-python-sdk/issues
+Keywords: drums,computer-use,reinforcement-learning,rl,desktop,environment,osworld,agents,sandbox
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# 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.

drums_sdk-0.2.5/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.

drums_sdk-0.2.5/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`.