pyproject.toml

[build-system]
requires = ["uv_build>=0.9.18,<0.10.0"]
build-backend = "uv_build"

[project]
name = "areal"
description = "AReaL: A Large-Scale Asynchronous Reinforcement Learning System"
readme = "README.md"
license = {text = "Apache-2.0"}
requires-python = ">=3.11,<3.13"
version = "1.0.3"
authors = [
    {name = "AReaL Team"},
]
maintainers = [
    {name = "AReaL Team"},
]
keywords = [
    "distributed-systems",
    "reinforcement-learning",
    "large-language-models",
    "llm-training",
    "llm-agent",
    "agentic-rl",
]
classifiers = [
    #   3 - Alpha
    #   4 - Beta
    #   5 - Production/Stable
    "Development Status :: 2 - Pre-Alpha",
    "Environment :: GPU :: NVIDIA CUDA :: 12",
    "Intended Audience :: Developers",
    "Intended Audience :: Science/Research",
    "License :: OSI Approved :: Apache Software License",
    "Operating System :: POSIX :: Linux",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.11",
    "Programming Language :: Python :: 3.12",
    "Topic :: Scientific/Engineering :: Artificial Intelligence",
    "Topic :: System :: Distributed Computing",
]

dependencies = [
    # Core ML/AI libraries
    "torch>=2.9.1,<2.11; sys_platform != 'darwin' or platform_machine != 'x86_64'",
    "torch<2.9.1; sys_platform == 'darwin' and platform_machine == 'x86_64'",
    "torchaudio",
    "torchvision",
    "torchdata",
    "huggingface_hub",
    "datasets>=3.0.0",
    "transformers==4.57.1",
    "peft",
    "qwen_agent",
    "openai-agents",
    "anthropic",
    "claude-agent-sdk",
    "litellm[proxy]>=1.81.3",
    "openhands",
    "langchain",
    "langchain-openai",

    # Visualization
    "pandas",
    "matplotlib",
    "seaborn",

    # Utilities and data processing
    "pillow>=12.1.1",
    "pylatexenc",
    "zstandard",
    "setproctitle",
    "nltk",
    "sentencepiece",
    "einops",
    "orjson",
    "tqdm",
    "rich",
    "pydantic",
    "PyYAML",
    "omegaconf==2.4.0.dev2",
    "hydra-core==1.4.0.dev1",
    "packaging",
    "lark",
    "tabulate",
    "pybase64",
    "msgspec",
    "math-verify==0.8.0",
    "python-dotenv",
    "json5",
    "psutil",
    "nvidia-ml-py; sys_platform == 'linux'",
    "ninja",
    "numba",
    "blosc",
    "pybind11>=2.10.0",
    "networkx==3.3",
    "aiofiles",
    "aiohttp>=3.13.3,<4",
    "httpx>=0.28.1",
    "pyzmq",
    "regex",
    "python_dateutil",
    "word2number",
    "pebble",
    "timeout-decorator",
    "prettytable",
    "h5py",
    "mathruler==0.1.0",

    # Monitoring and logging
    "wandb",
    "tensorboardx",
    "trackio",
    "colorama",
    "colorlog",
    "swanboard==0.1.9b1",
    "swanlab[dashboard]==0.6.12",

    # Distributed computing
    "ray[default]",
    "redis",

    # Web frameworks
    "fastapi>=0.115.12",
    "uvicorn",
    "uvloop>=0.21.0",
    "flask",
    "tenacity",

    # Build and packaging tools
    "build>=1.2.1",
    "wheel>=0.43.0",
    "cookiecutter>2.1.1",
    "distro-info>=1.0",
    "python-debian>=0.1.49",
]

[project.optional-dependencies]
# CUDA-dependent extras - these packages only have Linux x86_64 wheels
# Platform markers ensure they're skipped on unsupported platforms
#
# NOTE: vLLM has a separate pyproject file (pyproject.vllm.toml) because
# sglang and vllm pin mutually-incompatible torch / torchao versions.
# See pyproject.vllm.toml for the vLLM variant.
sglang = [
    "sglang[tracing]==0.5.9; sys_platform == 'linux' and platform_machine == 'x86_64'",
    "nvidia-cudnn-cu12==9.16.0.29; sys_platform == 'linux' and platform_machine == 'x86_64'",
    "torch; sys_platform == 'linux' and platform_machine == 'x86_64'",
    "torchaudio; sys_platform == 'linux' and platform_machine == 'x86_64'",
    "torchvision; sys_platform == 'linux' and platform_machine == 'x86_64'",
]
tms = [
    "torch_memory_saver==0.0.9; sys_platform == 'linux'",
]
flash-attn = [
    "flash-attn==2.8.3; sys_platform == 'linux' and platform_machine == 'x86_64'",
]
kernels = [
    "kernels==0.12.2",
]
megatron = [
    "megatron-core==0.16.0; sys_platform == 'linux' and platform_machine == 'x86_64'",
    "mbridge==0.15.1; sys_platform == 'linux' and platform_machine == 'x86_64'",
    "megatron-bridge==0.3.0; sys_platform == 'linux' and platform_machine == 'x86_64'",
]
# Convenience extra for CUDA training packages (no inference backend)
cuda-train = [
    "areal[tms]",
    "areal[megatron]",
    "areal[kernels]",
]
# Full CUDA setup: training packages + SGLang inference + flash-attn
cuda = [
    "areal[cuda-train]",
    "areal[sglang]",
    "areal[flash-attn]",
    "torch; sys_platform == 'linux' and platform_machine == 'x86_64'",
    "torchaudio; sys_platform == 'linux' and platform_machine == 'x86_64'",
    "torchvision; sys_platform == 'linux' and platform_machine == 'x86_64'",
]

[project.urls]
"Homepage" = "https://github.com/inclusionAI/AReaL"
"Repository" = "https://github.com/inclusionAI/AReaL"
"Documentation" = "https://inclusionai.github.io/AReaL/en/intro.html"
"Bug Tracker" = "https://github.com/inclusionAI/AReaL/issues"

[dependency-groups]
dev = [
    "pytest",
    "pytest-asyncio",
    "ipython",
    "ruff==0.14.9",
    "clang-format==19.1.7",
    "sh",
    "mdformat==0.7.17",
    "mdformat-gfm",
    "mdformat-tables",
    "mdformat-frontmatter",
    "plotly",
    "pre-commit",
    "sphinx",
    "sphinx-nefertiti",
    "jupyter-book==1.0.4.post1",
]

# =============================================================================
# Tool configurations: uv
# =============================================================================

[tool.uv.build-backend]
# Package is in root directory (not src/), so set module-root to empty string
module-root = ""

[tool.uv]
# Restrict lock file resolution to supported environments
# This prevents uv from failing when CUDA-only packages don't have wheels for macOS
environments = [
    "sys_platform == 'linux' and platform_machine == 'x86_64'",
    "sys_platform == 'linux' and platform_machine == 'aarch64'",
    "sys_platform == 'darwin' and platform_machine == 'arm64'",
    "sys_platform == 'darwin' and platform_machine == 'x86_64'",
]
override-dependencies = [
    # litellm[proxy] conflicts with sglang's exact pins:
    # - litellm requires openai>=2.8.0, sglang pins openai==2.6.1
    # - litellm requires soundfile>=0.12.1,<0.13.0, sglang pins soundfile==0.13.1
    # sglang pins torchao==0.9.0, but we require >=0.15.0 for archon fp8
    # nvidia-cudnn-cu12 is required for SGLang Vision Models
    "openai>=2.8.0",
    "soundfile>=0.12.1,<0.13.0",
    "torchao==0.15.0",
    "nvidia-cudnn-cu12==9.16.0.29; sys_platform == 'linux' and platform_machine == 'x86_64'",

    # Required by megatron-bridge but are optional (as per docs) cuda-based installs
    "transformer-engine; sys_platform == 'never'",
    "nv-grouped-gemm; sys_platform == 'never'",
    "mamba-ssm; sys_platform == 'never'",
    "causal-conv1d; sys_platform == 'never'",
    "flash-linear-attention; sys_platform == 'never'",

    # Version conflicts with megatron-bridge (resorting to the existing version)
    "megatron-core==0.16.0; sys_platform == 'linux' and platform_machine == 'x86_64'",
    "hydra-core==1.4.0.dev1",
    "timm==1.0.16",
]

# Static metadata so uv lock resolves flash-attn without downloading or building.
# The actual pre-built wheel (variant-specific) is installed in the Dockerfile.
[[tool.uv.dependency-metadata]]
name = "flash-attn"
version = "2.8.3"
requires-dist = ["torch", "einops"]

[tool.uv.extra-build-dependencies]
flash-attn = [{ requirement = "torch", match-runtime = true }]

[[tool.uv.index]]
name = "pytorch-cu129"
url = "https://download.pytorch.org/whl/cu129"
explicit = true

[tool.uv.sources]
torch = [
    { index = "pytorch-cu129", extra = "sglang" },
    { index = "pytorch-cu129", extra = "cuda" },
]
torchaudio = [
    { index = "pytorch-cu129", extra = "sglang" },
    { index = "pytorch-cu129", extra = "cuda" },
]
torchvision = [
    { index = "pytorch-cu129", extra = "sglang" },
    { index = "pytorch-cu129", extra = "cuda" },
]

# =============================================================================
# Tool configurations: pytest
# =============================================================================

[tool.pytest.ini_options]
pythonpath = ["."]
filterwarnings = [
    "ignore::DeprecationWarning",
    "ignore::PendingDeprecationWarning",
    "ignore::FutureWarning",
    "ignore::UserWarning:torch.*",
    "ignore::UserWarning:transformers.*",
]
markers = [
    "slow: mark test as slow, expected to cost more than 30 seconds and will not run in CI by default.",
    "ci: mark test as must-run in CI (only marked for slow tests).",
    "gpu: mark test that uses a single GPU",
    "multi_gpu: mark test that uses more than one GPU",
    "sglang: mark test that requires the SGLang inference backend",
    "vllm: mark test that requires the vLLM inference backend",
]

# =============================================================================
# Tool configurations: ruff
# =============================================================================

[tool.ruff]
line-length = 88
target-version = "py311"

[tool.ruff.lint]
select = [
    "E",  # pycodestyle errors
    "W",  # pycodestyle warnings
    "F",  # pyflakes
    "I",  # isort
    "UP", # pyupgrade
]
ignore = [
    "E501",  # E501 Line too long
]

[tool.ruff.lint.isort]
section-order = [
    "future",
    "standard-library",
    "third-party",
    "first-party",
    "areal",
    "local-folder",
]
from-first = false

[tool.ruff.lint.isort.sections]
"areal" = ["areal"]