AReaL AGENTS.md

AGENTS.md -- AReaL Agent Operations Guide

Quick reference

Tech stack: Python 3.12+ | PyTorch | FSDP2 / Megatron / Archon | SGLang / vLLM

# Environment
uv sync --extra cuda            # CUDA + SGLang inference (default); for vLLM: cp pyproject.vllm.toml pyproject.toml && cp uv.vllm.lock uv.lock && uv sync --extra cuda
uv sync --extra sandbox         # Daytona cloud sandbox backend (optional)
source .venv/bin/activate        # activate venv BEFORE pre-commit or git commit if venv exists
pre-commit install --install-hooks  # hooks: Ruff, clang-format, mdformat, nbstripout, conventional-commits
pre-commit run --all-files       # lint + format everything

# Tests
uv run pytest tests/test_<topic>.py

# CLI docs
uv run python docs/generate_cli_docs.py

# Docs build (canonical, release-aligned)
./docs/build_all.sh
# Do NOT use `jupyter-book build docs/en|docs/zh` directly for final preview/release,
# because it skips AReaL-specific static setup and output packaging.

Hard rules -- never violate:

• No wildcard imports (from x import *).
• No hardcoded secrets, paths, or endpoints.
• No skipping pre-commit hooks.
• No guessing cluster configs or rebuilding CUDA/driver stacks.
• Integration tests require multi-node hardware -- explain skips explicitly.

Always do:

• Read relevant files before modifying code.
• Run pre-commit run --all-files before committing.
• Follow existing code patterns in the same module.
• Add tests for new functionality.
• Ask for decisions and clarifications with short, structured options instead of broad open-ended questions. Use the platform's native question/clarification tool if available.

Ask first before:

• Modifying config structures in areal/api/cli_args.py.
• Adding new dependencies.
• Changing launcher or scheduler logic.
• Deleting or renaming public APIs.

When unsure, leave a TODO(agent) comment and note the constraint in your response.