Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
107 lines (78 loc) · 5.03 KB

CONTRIBUTING.md

File metadata and controls

107 lines (78 loc) · 5.03 KB

Contributing Guidelines

The NeMo Agent Toolkit Examples repository is a collection of examples that demonstrate how to use the NeMo Agent Toolkit. We welcome contributions from the community to add new examples, improve existing examples, and fix bugs.

To ensure your contribution is accepted, please follow the guidelines below.

What to Contribute

New Examples

If you have an idea for a new example, or would like to contribute an example you have created, please ensure that your example follows these general guidelines:

  1. Examples should demonstrate a specific use case or feature of the NeMo Agent Toolkit.
  2. Examples should be unique and not already covered by an existing example.
    1. If your example is a variation of an existing example, consider updating the existing example instead of creating a new one.
  3. Examples should be reliable and reproducible.
  4. Examples should adhere to the Example Requirements below.

If you are unsure about whether your example is a good fit for the repository, please open up an issue to discuss your idea before submitting a pull request.

Example Updates

Examples can be updated to include new features, improve documentation, or fix bugs. If you are updating an example, please ensure that your changes follow these general guidelines:

  1. Examples should be updated to reflect the latest version of the NeMo Agent Toolkit.
  2. All new features should be documented and tested.
  3. Examples should continue to adhere to the Example Requirements below.

Bug Fixes

If you have found a bug in an example, please open up an issue to report the bug or submit a pull request to fix the bug. Bug fixes do not need to update the example to reflect the latest version of the NeMo Agent Toolkit.

Example Requirements

Dependencies

The example should specify all its dependencies in the pyproject.toml file. The versions of all dependencies, including NeMo Agent toolkit, should specify at least 2 digit (for example nvidia-nat~=1.2, not nvidia-nat==1 or nvidia-nat>=1). Each dependency should have a license that is compatible with the Apache 2.0 License used by this repository.

Organization

Examples should follow a specified structure to maintain consistency across the repository, the nat workflow create command should be used to generate the example directory structure. The recommended structure is:

examples/
  $EXAMPLE_NAME/
    configs/ # Symlink to `src/nat_$EXAMPLE_NAME/configs/`
    data/ # [Optional] Symlink to `src/nat_$EXAMPLE_NAME/data/`
    scripts/ # [Optional] Directory for scripts needed to setup the example
    src/
      nat_$EXAMPLE_NAME/ # All example modules must start with the prefix `nat_`
        configs/
          config.yml # At least one config file for the example
        data/ # [Optional] Directory for data files needed to run the example
          ... # [Optional] Data files needed to run the example
        __init__.py
        register.py
    README.md or README.ipynb # Documentation for the example
    pyproject.toml # Must register the example with `nat`

Documentation

Each example must include clear documentation on how to run it. This can be provided in either:

  • A README.md file at the top level of the example directory, the examples/.template/README.md file can be copied into the example directory and used as a starting point.
  • A README.ipynb Jupyter notebook that walks through the example

In both cases, the documentation should include:

  • A description of the example
  • Key features of the example
  • Setup instructions
  • How to run the example
  • Expected results
  • [Optional] Troubleshooting tips

Testing

To ensure examples remain functional, each example must include unit tests written using pytest. Tests should verify the core functionality of the example and help catch issues when dependencies are updated.

Code Style

All code should be compatible with the linting rules defined in the root pyproject.toml file. To ensure your code is compatible, run the following command:

# Ensure all development dependencies are installed
uv sync --dev

./ci/scripts/checks.sh

License

All contributions must be made under the Apache 2.0 License.

Code of Conduct

All contributors must follow the Code of Conduct.