Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -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/*
132 changes: 132 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -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
2 changes: 2 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -2,3 +2,5 @@ __pycache__/
*.pyc
.venv/
*.egg-info/
dist/
build/
72 changes: 72 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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`.
Loading
Loading