Metadata-Version: 2.4
Name: swerl
Version: 0.0.1
Summary: Swarm Engine RL — a reinforcement learning framework for training LLM agent swarms.
Project-URL: Homepage, https://github.com/alexngai/swerl
Project-URL: Repository, https://github.com/alexngai/swerl
Project-URL: Issues, https://github.com/alexngai/swerl/issues
Project-URL: Changelog, https://github.com/alexngai/swerl/blob/main/CHANGELOG.md
Author-email: Alex Ngai <alexander.s.ngai@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: llm,multi-agent,post-training,reinforcement-learning,rlhf,swarm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
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: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: typing-extensions>=4.10
Provides-Extra: all
Requires-Dist: accelerate>=0.34; extra == 'all'
Requires-Dist: datasets>=2.20; extra == 'all'
Requires-Dist: ray[default]>=2.35; extra == 'all'
Requires-Dist: tensorboard>=2.17; extra == 'all'
Requires-Dist: torch>=2.4; extra == 'all'
Requires-Dist: transformers>=4.45; extra == 'all'
Requires-Dist: vllm>=0.6; extra == 'all'
Requires-Dist: wandb>=0.17; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: ray
Requires-Dist: ray[default]>=2.35; extra == 'ray'
Provides-Extra: torch
Requires-Dist: accelerate>=0.34; extra == 'torch'
Requires-Dist: datasets>=2.20; extra == 'torch'
Requires-Dist: torch>=2.4; extra == 'torch'
Requires-Dist: transformers>=4.45; extra == 'torch'
Provides-Extra: tracking
Requires-Dist: tensorboard>=2.17; extra == 'tracking'
Requires-Dist: wandb>=0.17; extra == 'tracking'
Provides-Extra: vllm
Requires-Dist: vllm>=0.6; extra == 'vllm'
Description-Content-Type: text/markdown

# swerl

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

[![PyPI](https://img.shields.io/pypi/v/swerl.svg)](https://pypi.org/project/swerl/)
[![Python](https://img.shields.io/pypi/pyversions/swerl.svg)](https://pypi.org/project/swerl/)
[![License](https://img.shields.io/pypi/l/swerl.svg)](LICENSE)

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

## Install

```bash
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:

```bash
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

```bash
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](https://docs.astral.sh/uv/):

```bash
uv sync --extra dev
```

Then:

```bash
uv run pytest
```

```bash
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`](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](.github/workflows/publish.yml) 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:

```bash
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:

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

## License

Apache-2.0. See [LICENSE](LICENSE).
