Development

Setup#

git submodule update --init --recursive
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]" -e ./third_party/reef-client
pip install --no-deps --group runtime
pre-commit install

The dependency group installs the reviewed training-runtime commit. --no-deps is intentional: GPU-side development uses the container environment's CUDA-matched dependency stack.

Package boundaries#

• The reef distribution includes concrete integrations under reef/train/, but its backend-agnostic core must not import them.
• The slime extra adds the Python-side dependencies used by reef/train/slime_runtime/; the runtime dependency group pins the runtime itself.
• Each reef/train/<backend>/ directory owns one concrete integration: its backend-specific source, extensions, adapters or bridges, dependencies, tests, and deployment configuration.
• Dependencies point from concrete integrations toward backend-neutral Reef contracts, never from core Reef modules toward a concrete backend.
• Keep Reef-specific glue out of shared or vendored backend code. Put it in a backend-owned adapter or plugin layer, such as reef/train/slime_runtime/reef_adapters/.
• Add new training backends as siblings under reef/train/; see the training layout guide.
• reef-client is a separate distribution (Human-Agent-Society/reef-client): the stdlib-only client of Reef's wire protocol. It never imports reef, gains no dependencies, and never ships in the reef wheel. The harness in examples/basic/ talks to Reef only through it — never the reef package.

Run entry points as modules / scripts:

python -m reef.service.deploy --help
examples/basic/run.sh

Layout policy#

The reef package's top level is frozen at the packages that exist today. A new top-level package — or a new bundled method beyond the six in the README's recipe table — starts as an RFC in docs/rfcs/, not as a directory.

Checks#

pre-commit run --all-files
PYTHONPATH=.:third_party/reef-client uv run \
  --with pytest \
  --with aiohttp \
  --with huggingface_hub \
  pytest tests/reef_service -q

Keep provider request bodies unchanged, preserve scenario isolation, and add a contract test when changing a public interface. See testing for focused commands.