pyproject.toml

# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

################################################
# Project
################################################

[project]
name = "nemo-gym"
dynamic = [
    "version",
    "readme",
]
description = "NeMo Gym is a library for building reinforcement learning environments"
license = {file = "LICENSE"}
requires-python = ">=3.12"
authors = [{ name = "NVIDIA" }]
maintainers = [{ name = "NVIDIA" }]

keywords = [
    "reinforcement-learning",
    "RL",
    "agent",
    "agentic",
    "LLM",
    "large-language-models",
    "training-data",
    "rollout",
    "trajectory",
    "verification",
    "verifier",
    "reward",
    "tool-calling",
    "function-calling",
    "data-collection",
    "NeMo",
    "NVIDIA",
]
classifiers = [
    "Development Status :: 4 - Beta",
    "Environment :: Console",
    "Intended Audience :: Developers",
    "Intended Audience :: Science/Research",
    "License :: OSI Approved :: Apache Software License",
    "Natural Language :: English",
    "Operating System :: OS Independent",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.12",
    "Topic :: Scientific/Engineering",
    "Topic :: Scientific/Engineering :: Artificial Intelligence",
    "Topic :: Scientific/Engineering :: Mathematics",
    "Topic :: Software Development :: Libraries",
    "Topic :: Software Development :: Libraries :: Python Modules",
]
dependencies = [
    ########################################
    # Every dependency listed here contains the following information:
    # 1. Why this dependency is here in NeMo Gym
    # 2. When this dependency was last updated
    # 3. The license of the dependencies.
    #
    # If you are adding or removing dependencies, please do your due diligence to update this information. PRs to main that modify dependencies will not be accepted unless this information is provided.
    # The licenses of the below dependencies include: Apache 2.0, MIT, and BSD 3-Clause
    #
    # By design, most (if not all) dependencies are unfrozen here to be easier to consume. The core pieces we need are server infra like FastAPI, etc.
    #
    # Dependency management philosophy:
    # - pyproject.toml: Specifies minimum version requirements (e.g., "mlflow>=3.5.0" means "we need at least 3.5.0 for security/features")
    # - uv.lock: Locks exact versions for reproducibility (e.g., "mlflow==3.9.0" means "we're currently using exactly 3.9.0")
    # This ensures both flexibility for consumers and reproducibility for developers.
    ########################################

    # OpenAI: We leverage OpenAI Responses, Chat Completions, and Completions schemas for Nemo Gym abstractions. It may also be used to directly query endpoints.
    # We specifically upper bound this OpenAI dependency since the version bumps so frequently.
    # Updated Wed Feb 17, 2026 with openai<=2.7.2
    # License: Apache 2.0 https://github.com/openai/openai-python/blob/a8258744cbecf51321587fc870e8920bd2c07809/LICENSE
    "openai<=2.7.2",

    # tqdm: Used for progress tracking on batch operations.
    # Updated Fri Jul 25, 2025 with tqdm==4.67.1
    # License: MIT https://github.com/tqdm/tqdm/blob/0ed5d7f18fa3153834cbac0aa57e8092b217cc16/LICENCE
    "tqdm",

    # Pydantic: Used for typing and import/export.
    # Updated Fri Jul 25, 2025 with pydantic==2.11.7 and pydantic_core==2.33.2
    # pydantic license: MIT https://github.com/pydantic/pydantic/blob/1c79f0e4d3fbdb8b93e837175d7098e016117237/LICENSE
    # pydantic_core license: MIT https://github.com/pydantic/pydantic-core/blob/17cbe988de187701dd21d5cd2306086ced5a8872/LICENSE
    # devtools license: MIT https://github.com/samuelcolvin/python-devtools/blob/5022f1f6f1c55d871b1db208c9c1b2ab0df488fe/LICENSE
    "pydantic",
    "pydantic_core",
    "devtools",

    # FastAPI: Used for server infrastructure
    # Updated Thu Mar 26, 2026 with fastapi==0.135.2
    # License: MIT https://github.com/fastapi/fastapi/blob/25a3697cedc6e7dfb84e93c8ff965801486f00f4/LICENSE
    "fastapi",

    # itsdangerous: Requirement for Starlette SessionMiddleware
    # Updated Tue Feb 17, 2026 with itsdangerous==2.2.0
    # License: BSD 3-Clause https://github.com/pallets/itsdangerous/blob/672971d66a2ef9f85151e53283113f33d642dabd/LICENSE.txt
    "itsdangerous",

    # Uvicorn: Used to serve FastAPI apps
    # Updated Mon Jul 28, 2025 with uvicorn==0.35.0
    # License: BSD 3-Clause https://github.com/encode/uvicorn/blob/c1144fd4f130388cffc05ee17b08747ce8c1be11/LICENSE.md
    "uvicorn",

    # UVLoop: a faster async event loop than Python's native asyncio. Used automatically by Uvicorn as an async loop backend.
    # Updated Fri Aug 01, 2025 with uvloop==0.21.0
    # License: Apache 2.0 and MIT https://github.com/MagicStack/uvloop/blob/96b7ed31afaf02800d779a395591da6a2c8c50e1/LICENSE-APACHE https://github.com/MagicStack/uvloop/blob/96b7ed31afaf02800d779a395591da6a2c8c50e1/LICENSE-MIT
    "uvloop",

    # Hydra and OmegaConf: CLI Configuration utilities
    # Updated Tue Jul 29, 2025 with hydra-core==1.3.2 and omegaconf==2.3.0
    # hydra-core license: MIT https://github.com/facebookresearch/hydra/blob/737fc3349ef3a4031035645f7e8c80be66a57042/LICENSE
    # omegaconf license: BSD 3-Clause https://github.com/omry/omegaconf/blob/117f7de07285e4d1324b9229eaf873de15279457/LICENSE
    "hydra-core",
    "omegaconf",

    # rich: used for nicer terminal content displays
    # Updated Tue Feb 17, 2026 with rich==14.3.2
    # License: MIT https://github.com/Textualize/rich/blob/27701029082052c6541031b6f139097230253900/LICENSE
    "rich",

    # mlflow-skinny: used for interacting with the Gitlab model registry. We use the "skinny" version that does not have unnecessary dependencies.
    # mlflow dependency is necessary for importing. However, all of mlflow's dependencies that don't overlap with mlflow-skinny are excluded below.
    # Updated Tue Feb 17, 2026 with mlflow-skinny==3.9.0
    # License: Apache 2.0 https://github.com/mlflow/mlflow/blob/c6ce84e817897e1a0461632f8a06d4e5e4ac3726/LICENSE.txt
    "mlflow-skinny",
    "mlflow",

    # aiohttp: async http backend
    # Updated Mon Feb 10, 2026 with aiohttp>=3.13.3
    # License: Apache 2.0 https://github.com/aio-libs/aiohttp/blob/9a2f146a12e3525b43e96723ef41584bf9cf784e/LICENSE.txt
    "aiohttp>=3.13.3",

    # yappi: profiling tool
    # Updated Mon Sep 22, 2025 with yappi==1.6.10
    # License: MIT https://github.com/sumerc/yappi/blob/1d3f7501701e1f050b6dcd6a86fd36aec08185c7/LICENSE
    "yappi",

    # Ray: Used for distributed processing
    # Updated Mon Feb 10, 2026 with ray[default]==2.52.1 in uv.lock
    # Security: Requires ray>=2.52.0 (currently resolves to 2.52.1 naturally)
    # License: Apache 2.0 https://github.com/ray-project/ray/blob/master/LICENSE
    "ray[default]",

    # psutil: Cross-platform process and system utilities
    # Updated: Fri Nov 07, 2025 with psutil==6.1.1
    # License: BSD 3-Clause https://github.com/giampaolo/psutil/blob/master/LICENSE
    "psutil",

    # HuggingFace datasets: for loading and converting parquet datasets
    # Updated Thu Dec 04, 2025 with datasets==4.4.1
    # License: Apache 2.0 https://github.com/huggingface/datasets/blob/main/LICENSE
    "datasets",

    # orjson: JSON library for faster serialization/deserialization
    # Updated: Thu Jan 08, 2026 with orjson==3.11.3
    # License: Apache 2.0 https://github.com/ijl/orjson/blob/fb3eb1f729c7e7b019f780af5695722c99c7c695/LICENSE-APACHE
    "orjson",

    # urllib3: HTTP client library (transitive dependency, pinned for security)
    # Updated: Mon Feb 10, 2026 with urllib3>=2.6.3
    # License: MIT https://github.com/urllib3/urllib3/blob/main/LICENSE.txt
    "urllib3>=2.6.3",

    # fonttools: Library to manipulate font files (transitive dependency, pinned for security)
    # Updated: Mon Feb 10, 2026 with fonttools>=4.60.2
    # License: MIT https://github.com/fonttools/fonttools/blob/main/LICENSE
    "fonttools>=4.60.2",

    # python-multipart: Streaming multipart parser (transitive dependency, pinned for security)
    # Updated: Mon Feb 10, 2026 with python-multipart>=0.0.22
    # License: Apache 2.0 https://github.com/andrew-d/python-multipart/blob/master/LICENSE.txt
    "python-multipart>=0.0.22",

    # wandb: E2E rollout collection data and metrics upload
    # Updated: Tue Feb 17, 2026 with wandb==0.25.0
    # License: MIT https://github.com/wandb/wandb/blob/f8acf479342b6aa8217dd0833bb32190b11c14bc/LICENSE
    "wandb",

    # gprof2dot and pydot: Used for outputting dot graphs for profiling.
    # Updated: Wed Feb 25, 2026 with gprof2dot==2025.4.14 and pydot==4.0.1
    # gprof2dot License: GNU Lesser General Public License v3.0 https://github.com/jamielennox/requests-mock/blob/9742d02a8cad17276dbeba7b300b6d27ae1b6fb1/LICENSE
    # pydot License: MIT https://github.com/pydot/pydot/blob/a2bee1e770698867332516fb2878fac262b4ffc5/LICENSES/MIT.txt
    "gprof2dot",
    "pydot",
]

[dependency-groups]
docs = [
    "sphinx>=8.2.3",
    "sphinx-autobuild>=2025.8.25",    # For live doc serving while editing docs
    "sphinx-autodoc2>=0.5.0",         # For documenting Python API
    "sphinx-copybutton>=0.5.2",       # Adds a copy button for code blocks
    "myst-parser>=4.0.1",             # For our markdown docs
    "nvidia-sphinx-theme>=0.0.8",     # Our NVIDIA theme
    "sphinxcontrib-mermaid>=1.0.0",   # For mermaid diagrams
    "sphinx-design>=0.6.1",           # For our design elements
    "swagger-plugin-for-sphinx>=6.0.0", # For Swagger API documentation
    "sphinx-reredirects>=0.1.6",      # For URL redirects when pages move
]

[project.optional-dependencies]
# We include dev dependencies as an extra since technically each server module is a consumer (which means we cannot use dependency groups, which are intended to be within a project).
dev = [
    # Pre-commit: Used for pre-commit hooks.
    # Updated: Thu Sep 04, 2025 with pre-commit==4.3.0
    # License: MIT https://github.com/pre-commit/pre-commit/blob/e70b313c8017b2b6d7844e91795c9d41b9ceb9fb/LICENSE
    "pre-commit>=3.6.0",

    # Mypy: Used for Python type checking.
    # Updated: Thu Sep 04, 2025 with mypy==1.17.1
    # License: MIT https://github.com/python/mypy/blob/645b421fa23a3f0d63f651059fa1e8318a6f214a/LICENSE
    "mypy>=1.8.0",

    # Ruff: Used for Python code formatting and linting.
    # Updated: Fri Jul 25, 2025 with ruff==0.12.5
    # License: MIT https://github.com/astral-sh/ruff/blob/21ac16db85452c2c196d3b9cc61fb27b7b81f3f7/LICENSE
    "ruff",

    # Coverage: Used for Python code coverage.
    # Updated: Fri Jul 25, 2025 with coverage[toml]==7.10.0
    # License: Apache 2.0 https://github.com/nedbat/coveragepy/blob/a2baa66b55ca71ea6b35009f2b4a51ff8fda1753/LICENSE.txt
    "coverage[toml]",

    # Pytest: Used for Python test orchestration.
    # Updated: Fri Jul 25, 2025 with pytest-cov==5.0.0, pytest-xdist==3.6.1, pytest==7.4.3, and pytest-asyncio==0.21.1
    # pytest-cov license: MIT https://github.com/pytest-dev/pytest-cov/blob/9d6d57c78627d4811fc473610d61a0b7225e4b40/LICENSE
    # pytest-xdist license: MIT https://github.com/pytest-dev/pytest-xdist/blob/2f1d80cb9d83ea2d91bba741ef5deffa9f8f85bf/LICENSE
    # pytest license: MIT https://github.com/pytest-dev/pytest/blob/5989efe3efec31a9d14f550d89903b6311dfc828/LICENSE
    # pytest-asyncio: Apache 2.0 https://github.com/pytest-dev/pytest-asyncio/blob/66b9f8e31f5f3c3bcf124a52f316516e70c90b46/LICENSE
    "pytest-cov",
    "pytest-xdist",
    "pytest",
    "pytest-asyncio",

    # Requests-mock: Used for mocking HTTP requests in tests
    # Updated: Fri Jul 25, 2025 and requests-mock==1.12.1
    # License: Apache 2.0 https://github.com/jamielennox/requests-mock/blob/9742d02a8cad17276dbeba7b300b6d27ae1b6fb1/LICENSE
    "requests-mock",
]

[build-system]
requires = ["setuptools>=61", "setuptools-scm"]
build-backend = "setuptools.build_meta"

[tool.uv]
managed = true
required-version = ">=0.9.30"
exclude-dependencies = [
    # Exclude unwanted dependencies from mlflow
    "alembic",
    "blinker",
    "cffi",
    "contourpy",
    "cryptography",
    "cycler",
    "flask",
    "flask-cors",
    "graphene",
    "graphql-core",
    "graphql-relay",
    "gunicorn",
    "huey",
    "joblib",
    "kiwisolver",
    "matplotlib",
    "pillow",
    "prettytable",
    "scikit-learn",
    "scipy",
    "skops",
    "sqlalchemy",
    "threadpoolctl",
    "wcwidth",
    "werkzeug",
    "waitress",
]

[tool.setuptools.dynamic]
version = {attr = "nemo_gym.__version__"}
readme = {file = "README.md", content-type = "text/markdown"}

[tool.distutils.egg_info]
egg_base = "cache"

[project.urls]
Download = "https://github.com/NVIDIA-NeMo/Gym/releases"
Homepage = "https://github.com/NVIDIA-NeMo/Gym"

[project.scripts]
# Run/test scripts for servers.
nemo_gym_run = "nemo_gym.cli:run"
ng_run = "nemo_gym.cli:run"
nemo_gym_test = "nemo_gym.cli:test"
ng_test = "nemo_gym.cli:test"
nemo_gym_test_all = "nemo_gym.cli:test_all"
ng_test_all = "nemo_gym.cli:test_all"

# Development convenience aliases.
nemo_gym_dev_test = "nemo_gym.cli:dev_test"
ng_dev_test = "nemo_gym.cli:dev_test"
nemo_gym_init_resources_server = "nemo_gym.cli:init_resources_server"
ng_init_resources_server = "nemo_gym.cli:init_resources_server"

# Benchmarks
nemo_gym_list_benchmarks = "nemo_gym.benchmarks:list_benchmarks"
ng_list_benchmarks = "nemo_gym.benchmarks:list_benchmarks"
nemo_gym_prepare_benchmark = "nemo_gym.benchmarks:prepare_benchmark"
ng_prepare_benchmark = "nemo_gym.benchmarks:prepare_benchmark"

# Rollout collection
nemo_gym_collect_rollouts = "nemo_gym.rollout_collection:collect_rollouts"
ng_collect_rollouts = "nemo_gym.rollout_collection:collect_rollouts"
nemo_gym_e2e_collect_rollouts = "nemo_gym.cli:e2e_rollout_collection"
ng_e2e_collect_rollouts = "nemo_gym.cli:e2e_rollout_collection"

# Prompt materialization
nemo_gym_materialize_prompts = "nemo_gym.prompt:materialize_prompts_cli"
ng_materialize_prompts = "nemo_gym.prompt:materialize_prompts_cli"

# Reward profiling
nemo_gym_reward_profile = "nemo_gym.reward_profile:reward_profile"
ng_reward_profile = "nemo_gym.reward_profile:reward_profile"

# Dataset management
nemo_gym_upload_dataset_to_gitlab = "nemo_gym.gitlab_utils:upload_jsonl_dataset_cli"
ng_upload_dataset_to_gitlab = "nemo_gym.gitlab_utils:upload_jsonl_dataset_cli"
nemo_gym_download_dataset_from_gitlab = "nemo_gym.gitlab_utils:download_jsonl_dataset_cli"
ng_download_dataset_from_gitlab = "nemo_gym.gitlab_utils:download_jsonl_dataset_cli"
nemo_gym_prepare_data = "nemo_gym.train_data_utils:prepare_data"
ng_prepare_data = "nemo_gym.train_data_utils:prepare_data"

# HF dataset upload and download
nemo_gym_upload_dataset_to_hf = "nemo_gym.dataset_orchestrator:upload_jsonl_dataset_to_hf_cli"
ng_upload_dataset_to_hf = "nemo_gym.dataset_orchestrator:upload_jsonl_dataset_to_hf_cli"
nemo_gym_download_dataset_from_hf = "nemo_gym.dataset_orchestrator:download_jsonl_dataset_from_hf_cli"
ng_download_dataset_from_hf = "nemo_gym.dataset_orchestrator:download_jsonl_dataset_from_hf_cli"

# Gitlab -> HF (upload then delete)
nemo_gym_gitlab_to_hf_dataset = "nemo_gym.dataset_orchestrator:upload_jsonl_dataset_to_hf_and_delete_gitlab_cli"
ng_gitlab_to_hf_dataset = "nemo_gym.dataset_orchestrator:upload_jsonl_dataset_to_hf_and_delete_gitlab_cli"

# Manually delete from Gitlab
nemo_gym_delete_dataset_from_gitlab = "nemo_gym.dataset_orchestrator:delete_jsonl_dataset_from_gitlab_cli"
ng_delete_dataset_from_gitlab = "nemo_gym.dataset_orchestrator:delete_jsonl_dataset_from_gitlab_cli"

# Configuration utils
nemo_gym_dump_config = "nemo_gym.cli:dump_config"
ng_dump_config = "nemo_gym.cli:dump_config"

# Display help
nemo_gym_help = "nemo_gym.cli:display_help"
ng_help = "nemo_gym.cli:display_help"

# Server status
nemo_gym_status = "nemo_gym.cli:status"
ng_status = "nemo_gym.cli:status"

# Environment-specific uv pip list
nemo_gym_pip_list = "nemo_gym.cli:pip_list"
ng_pip_list = "nemo_gym.cli:pip_list"

# Display version
nemo_gym_version = "nemo_gym.cli:version"
ng_version = "nemo_gym.cli:version"

# Re-install Gym and dependencies
nemo_gym_reinstall = "nemo_gym.cli:reinstall"
ng_reinstall = "nemo_gym.cli:reinstall"

[tool.setuptools.packages.find]
where = ["."]
include = ["benchmarks", "resources_servers", "responses_api_agents", "responses_api_models", "nemo_gym"]

################################################
# Testing
################################################

[tool.pytest.ini_options]
# durations=0 will display all tests execution time, sorted in ascending order starting from the slowest one.
# -vv will also display tests with duration = 0.00s
addopts = "--verbose --pyargs --durations=0 --strict-markers"  # always add these arguments to pytest
testpaths = ["tests"]
# directories to ignore when discovering tests
norecursedirs = [
    "nemo_gym",
    "external",
    "examples",
    "docs",
    "scripts",
    "tools",
    "tutorials",
    "*.egg",
    ".*",
    "_darcs",
    "build",
    "CVS",
    "dist",
    "venv",
    "{arch}"
]
log_cli = true
log_cli_level = "INFO"
cache_dir = "cache/.pytest_cache"
filterwarnings = "ignore::DeprecationWarning"
asyncio_mode = "auto"
# markers to select tests, use `pytest --markers` to see all available markers, `pytest -m "<marker>"` to select tests
markers = [
    "unit: marks unit test, i.e. testing a single, well isolated functionality (deselect with '-m \"not unit\"')",
    "integration: marks test checking the elements when integrated into subsystems (deselect with '-m \"not integration\"')",
    "system: marks test working at the highest integration level (deselect with '-m \"not system\"')",
    "acceptance: marks test checking whether the developed product/model passes the user defined acceptance criteria (deselect with '-m \"not acceptance\"')",
    "docs: mark tests related to documentation (deselect with '-m \"not docs\"')",
    "skipduringci: marks tests that are skipped during ci as they are addressed by Jenkins jobs but should be run to test user setups",
    "pleasefixme: marks tests that are broken and need fixing",
]

[tool.coverage.run]
command_line = "-m pytest --durations=10"
omit = [
    "tests/*",
    "temp*",
    "results/*",
    "/tmp/*",
    "benchmarks/*",
]
data_file = "results/.coverage"
concurrency = ["thread", "multiprocessing"]

[tool.coverage.paths]
source = ["nemo_gym/", "/workspace/nemo_gym"]

[tool.coverage.html]
directory = "results/htmlcov"

[tool.coverage.report]
skip_covered = true
sort = "miss"
fail_under = 96.0
exclude_also = [
    "def __repr__",
    "if self.debug:",
    "if settings.DEBUG",
    "raise AssertionError",
    "raise NotImplementedError",
    "if 0:",
    "if __name__ == .__main__.:",
    "if TYPE_CHECKING:",
    "class .*\\bProtocol\\):",
    "@(abc\\.)?abstractmethod",
    "pass",
]

################################################
# Linting, formatting, and QOL (using ruff)
################################################
[tool.ruff]
# Line length configuration
line-length = 119
target-version = "py312"

cache-dir = "cache/.ruff_cache"
# Exclude common directories that shouldn't be linted
exclude = [
    "resources",
    ".git",
    ".github",
    ".venv",
    "venv",
    "__pycache__",
    "*.egg",
    "build",
    "dist",
    "docs/source/conf.py",
    "setup.py",
]
# Files to completely ignore
extend-exclude = [
    "*.ipynb",
]
[tool.ruff.lint]
# Configure linting rules
select = [
    "F541",  # f-string without any placeholders
    "F841",  # local variable assigned but never used
    "F401",  # imported but unused
    "E741",  # ambiguous variable name
    "F821",  # undefined name
    "E266",  # too many leading '#' for block comment
    "I",     # isort
]

# Additional rules can be added here
ignore = [
    "E501",  # Line too long - handled by formatter
]
[tool.ruff.lint.isort]
known-first-party = ["nemo_gym"]
known-third-party = ["examples", "scripts"]
section-order = ["future", "standard-library", "third-party", "first-party", "local-folder"]
lines-after-imports = 2

[tool.ruff.lint.per-file-ignores]
# Ignore import violations in __init__ files
"__init__.py" = ["F401", "F403"]
# Ignore docstring requirements in test files
"test_*.py" = ["D101", "D103"]
"*_test.py" = ["D101", "D103"]
"tests/*.py" = ["D101", "D103"]

[tool.ruff.format]
# Code formatting configuration
quote-style = "double"
skip-magic-trailing-comma = false
line-ending = "auto"