swerl

Swarm Engine RL — a reinforcement learning framework for training LLM agent swarms.

⚠️ Early alpha. The package is published so the API can stabilize in the open; expect breaking changes before 0.1.0.

Install

pip install swerl

The base install is deliberately light — it pulls no CUDA wheels, so it stays importable on a laptop or a CI runner. The training stack lives behind extras:

pip install "swerl[torch]"     # torch + transformers + datasets + accelerate
pip install "swerl[ray]"       # distributed swarm orchestration
pip install "swerl[vllm]"      # fast rollout backend
pip install "swerl[all]"       # everything a training node needs

Quick check

swerl info

Prints swerl's version plus the torch / ray / vllm versions it can see — the first thing to paste into a bug report.

Development

The repo uses uv:

uv sync --extra dev

Then:

uv run pytest

uv run ruff check . && uv run mypy

Releasing

One-time setup: create a PyPI API token and store it as the PYPI_API_TOKEN secret in the repo's pypi environment (and TEST_PYPI_API_TOKEN in a testpypi environment if you want dry runs).

1. Bump __version__ in src/swerl/__init__.py and add a CHANGELOG.md entry.
2. Tag and push: git tag v0.0.1 && git push --tags.
3. Publish a GitHub Release for that tag — the publish workflow builds and uploads to PyPI.

To rehearse without cutting a release, run the publish workflow manually; it defaults to TestPyPI.

Publishing by hand

The workflow just runs uv publish, so you can do the same thing locally. The publish targets are named in pyproject.toml, so no URLs to remember:

uv build && uv publish --index testpypi --token pypi-YOUR-TOKEN-HERE

--token X is shorthand for --username __token__ --password X. Prefer the UV_PUBLISH_TOKEN environment variable so the token stays out of your shell history, and add --dry-run to see what would be uploaded:

UV_PUBLISH_TOKEN=$(cat ~/.pypi-token) uv publish --index pypi --dry-run

License

Apache-2.0. See LICENSE.