Creating initial readme contributing guide (#3)

mdemoret-nv · web-flow · commit e2087de9d0d4 · 2025-09-22T20:29:23.000Z
- Creates the contributing guide, template and updates the readme with information guiding users to commit examples ## By Submitting this PR I confirm: - I am familiar with the [Contributing Guidelines](https://github.com/NVIDIA/NeMo-Agent-Toolkit/blob/develop/docs/source/resources/contributing.md). - We require that all contributors "sign-off" on their commits. This certifies that the contribution is your original work, or you have rights to submit it under the same license, or a compatible license. - Any contribution which contains commits that are not Signed-Off will not be accepted. - When the PR is ready for review, new or existing tests cover these changes. - When the PR is ready for review, the documentation is up to date with these changes. ## Summary by CodeRabbit - Documentation - Added a comprehensive CONTRIBUTING guide with requirements for examples, testing, licensing, and code style. - Revamped README with clearer community-focused setup steps, Python version guidance, and LFS data instructions. - Added an example README template to streamline creating new examples. - Chores - Configured Git LFS for images and example data while exempting Markdown files. - Updated tooling defaults and ignore paths for the examples template. - Enhanced CI to include doc/license checks, simplified GitHub checks, and changed default target branch to main. Authors: - Michael Demoret (https://github.com/mdemoret-nv) - Will Killian (https://github.com/willkill07) - David Gardner (https://github.com/dagardner-nv) Approvers: - David Gardner (https://github.com/dagardner-nv) - Anuradha Karuppiah (https://github.com/AnuradhaKaruppiah) URL: #3
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1,7 @@
+docs/source/_static/*.png filter=lfs diff=lfs merge=lfs -text
+
+# Add all data files to LFS
+examples/**/data/** filter=lfs diff=lfs merge=lfs -text
+
+# Exclude Markdown files from LFS in the data directory
+examples/**/data/*.md -filter=lfs -diff=lfs -merge=lfs text
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,107 @@
+<!--
+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.
+-->
+
+
+# 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](#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](#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](https://www.apache.org/licenses/LICENSE-2.0) 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:
+```bash
+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:
+
+```bash
+# 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](https://www.apache.org/licenses/LICENSE-2.0).
+
+## Code of Conduct
+All contributors must follow the [Code of Conduct](CODE-OF-CONDUCT.md).
diff --git a/README.md b/README.md
@@ -15,6 +15,58 @@ See the License for the specific language governing permissions and
 limitations under the License.
 -->
 
+![NVIDIA NeMo Agent Toolkit Examples](./docs/source/_static/banner.png "NVIDIA NeMo Agent Toolkit Examples")
+
 # NVIDIA NeMo Agent Toolkit Examples
 
-This repository contains examples for the [NVIDIA NeMo Agent toolkit](https://github.com/NVIDIA/NeMo-Agent-Toolkit).
+This repository contains community examples for the [NVIDIA NeMo Agent Toolkit](https://github.com/NVIDIA/NeMo-Agent-Toolkit). Whether you're new to using the toolkit, an experienced user looking for inspiration, or hoping to share your own examples with the community, this repository will help you get started.
+
+
+> [!NOTE]
+> Both the NeMo Agent Toolkit [repository](https://github.com/NVIDIA/NeMo-Agent-Toolkit) and this repository contain examples. However, there are some differences in the examples between the two repositories:
+>
+> | Repository | Example Focus | Update Cadence |
+> |------------|--------------|----------------|
+> | NeMo Agent Toolkit | Examples focused on toolkit features and capabilities | Updated each release to work with latest version |
+> | NeMo Agent Toolkit Examples | Examples driven by community use cases and scenarios | Bound to specific toolkit versions, updated as needed |
+
+
+## Getting Started
+
+Each example is a self-contained directory that contains a README with instructions for running the example.
+
+All examples require a local clone of this repository, uv, and a Python 3.11+ environment. Please follow the instructions below to get started.
+
+1. Clone the repository
+
+   ```bash
+   git clone https://github.com/NVIDIA/NeMo-Agent-Toolkit-Examples.git
+   cd NeMo-Agent-Toolkit-Examples
+   ```
+
+1. Fetch the data sets by downloading the LFS files.
+   ```bash
+   git lfs install
+   git lfs fetch
+   git lfs pull
+   ```
+
+1. Install uv using the instructions [here](https://docs.astral.sh/uv/getting-started/installation/).
+
+1. Create a new environment using the following command:
+
+   ```bash
+   uv venv --python 3.13 --seed .venv
+   source .venv/bin/activate
+
+   uv sync --dev
+   ```
+
+   > [!NOTE]
+   > Python 3.11 & 3.12 are also supported simply replace `3.13` with `3.11` or `3.12` in the `uv` command above.
+
+To run an example, navigate to the example directory and follow the instructions in the README.
+
+## Contributing
+
+We welcome contributions to the repository! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information about how to contribute to the repository, requirements, and how to submit an example.
diff --git a/ci/scripts/checks.sh b/ci/scripts/checks.sh
@@ -26,7 +26,27 @@ PRE_COMMIT_RETVAL=$?
 ${SCRIPT_DIR}/python_checks.sh
 PY_CHECKS_RETVAL=$?
 
-if [[ ${PRE_COMMIT_RETVAL} -ne 0 || ${PY_CHECKS_RETVAL} -ne 0 ]]; then
+echo "Checking copyright headers"
+python ${SCRIPT_DIR}/copyright.py --verify-apache-v2
+COPYRIGHT_RETVAL=$?
+if [[ ${COPYRIGHT_RETVAL} -eq 0 ]]; then
+   echo -e "\n\n>>>> PASSED: copyright check\n\n"
+else
+   echo -e "\n\n>>>> FAILED: copyright check\n\n"
+fi
+
+
+echo "Running Documentation checks"
+${SCRIPT_DIR}/documentation_checks.sh
+DOCUMENTATION_RETVAL=$?
+if [[ ${DOCUMENTATION_RETVAL} -eq 0 ]]; then
+   echo -e "\n\n>>>> PASSED: documentation check\n\n"
+else
+   echo -e "\n\n>>>> FAILED: documentation check\n\n"
+fi
+
+
+if [[ ${PRE_COMMIT_RETVAL} -ne 0 || ${PY_CHECKS_RETVAL} -ne 0 || ${COPYRIGHT_RETVAL} -ne 0 || ${DOCUMENTATION_RETVAL} -ne 0 ]]; then
    echo ">>>> FAILED: checks"
    exit 1
 fi
diff --git a/ci/scripts/common.sh b/ci/scripts/common.sh
@@ -24,7 +24,7 @@ export PY_DIRS="${PY_ROOT} ${PROJECT_ROOT}/packages ${PROJECT_ROOT}/tests ${PROJ
 
 # Determine the commits to compare against. If running in CI, these will be set. Otherwise, diff with main
 export AIQ_LOG_LEVEL=WARN
-export CI_MERGE_REQUEST_TARGET_BRANCH_NAME=${CI_MERGE_REQUEST_TARGET_BRANCH_NAME:-"develop"}
+export CI_MERGE_REQUEST_TARGET_BRANCH_NAME=${CI_MERGE_REQUEST_TARGET_BRANCH_NAME:-"main"}
 
 if [[ "${GITLAB_CI}" == "true" ]]; then
    export BASE_SHA=${BASE_SHA:-${CI_MERGE_REQUEST_TARGET_BRANCH_SHA:-${CI_MERGE_REQUEST_DIFF_BASE_SHA:-$(${SCRIPT_DIR}/gitutils.py get_merge_target --current-branch=${CURRENT_BRANCH})}}}
diff --git a/ci/scripts/github/checks.sh b/ci/scripts/github/checks.sh
@@ -24,10 +24,3 @@ create_env group:dev
 
 rapids-logger "Running checks"
 ${SCRIPT_DIR}/checks.sh
-
-rapids-logger "Checking copyright headers"
-python ${SCRIPT_DIR}/copyright.py --verify-apache-v2
-
-
-rapids-logger "Runing Documentation checks"
-${SCRIPT_DIR}/documentation_checks.sh
diff --git a/docs/source/_static/banner.png b/docs/source/_static/banner.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:98e27002e89080c1b13b8b86f7bfde484a4b5d2e04dfc8d75c6dd194a48953e9
+size 829560
diff --git a/examples/.template/README.md b/examples/.template/README.md
@@ -0,0 +1,151 @@
+<!--
+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.
+-->
+
+# EXAMPLE_TITLE
+
+<!-- Replace with a brief description of what your example demonstrates -->
+This example demonstrates [DESCRIPTION_OF_WHAT_YOUR_EXAMPLE_DOES] using the NVIDIA NeMo Agent toolkit, fully configured through a YAML file. It showcases [SPECIFIC_FEATURES_YOUR_EXAMPLE_HIGHLIGHTS].
+
+## Table of Contents
+
+- [EXAMPLE\_TITLE](#example_title)
+  - [Table of Contents](#table-of-contents)
+  - [Key Features](#key-features)
+  - [Installation and Setup](#installation-and-setup)
+    - [Install this Workflow:](#install-this-workflow)
+    - [Set Up API Keys](#set-up-api-keys)
+    - [Run the Workflow](#run-the-workflow)
+  - [Deployment-Oriented Setup](#deployment-oriented-setup)
+    - [Build the Docker Image](#build-the-docker-image)
+    - [Run the Docker Container](#run-the-docker-container)
+    - [Test the API](#test-the-api)
+    - [Expected API Output](#expected-api-output)
+  - [Customization Guide](#customization-guide)
+    - [Adding New Functions](#adding-new-functions)
+    - [Modifying the Agent](#modifying-the-agent)
+    - [Using Different Models](#using-different-models)
+
+---
+
+## Key Features
+
+<!-- Replace with your specific features -->
+- **Custom Functions:** Demonstrates [DESCRIBE_YOUR_CUSTOM_FUNCTIONS]
+- **Agent Integration:** Uses a [AGENT_TYPE] that [DESCRIBE_WHAT_THE_AGENT_DOES]
+- **Multi-step Problem Solving:** Shows how an agent can [DESCRIBE_COMPLEX_WORKFLOWS]
+- **Custom Function Registration:** Demonstrates the NeMo Agent toolkit plugin system for [DESCRIBE_PLUGIN_FUNCTIONALITY]
+- **YAML-based Configuration:** Fully configurable workflow that showcases [DESCRIBE_CONFIGURATION_BENEFITS]
+
+---
+
+## Installation and Setup
+
+### Install this Workflow:
+
+From the root directory of the NeMo Agent toolkit library, run the following commands:
+
+```bash
+uv pip install -e examples/EXAMPLE_CATEGORY/EXAMPLE_NAME
+```
+
+### Set Up API Keys
+Depending on which workflows you are running, you may need to obtain API keys from the respective services. Most NeMo Agent toolkit workflows require an NVIDIA API key defined with the `NVIDIA_API_KEY` environment variable. An API key can be obtained by visiting [`build.nvidia.com`](https://build.nvidia.com/) and creating an account.
+
+Some workflows may also require an OpenAI API key. Visit [OpenAI](https://openai.com/) and create an account. Navigate to your account settings to obtain your OpenAI API key.
+
+```bash
+export NVIDIA_API_KEY=<YOUR_API_KEY>
+export OPENAI_API_KEY=<YOUR_API_KEY>  # OPTIONAL
+```
+
+### Run the Workflow
+
+Return to your original terminal, and run the following command from the root of the NeMo Agent toolkit repo to execute this workflow with the specified input:
+
+```bash
+nat run --config_file examples/EXAMPLE_CATEGORY/EXAMPLE_NAME/configs/config.yml --input "YOUR_EXAMPLE_INPUT_PROMPT"
+```
+
+**Expected Workflow Output**
+<!-- Replace with your expected output -->
+```
+YOUR_EXPECTED_OUTPUT_HERE
+```
+
+## Deployment-Oriented Setup
+
+For a production deployment, use Docker:
+
+### Build the Docker Image
+
+Prior to building the Docker image ensure that you have followed the steps in the [Installation and Setup](#installation-and-setup) section, and you are currently in the NeMo Agent toolkit virtual environment.
+
+From the root directory of the NeMo Agent toolkit repository, build the Docker image:
+
+```bash
+docker build --build-arg NAT_VERSION=$(python -m setuptools_scm) -t EXAMPLE_NAME -f examples/EXAMPLE_CATEGORY/EXAMPLE_NAME/Dockerfile .
+```
+
+### Run the Docker Container
+Deploy the container:
+
+```bash
+docker run -p 8000:8000 -p 6006:6006 -e NVIDIA_API_KEY -e OPENAI_API_KEY EXAMPLE_NAME
+```
+
+Note, a phoenix telemetry service will be exposed at port 6006.
+
+### Test the API
+Use the following curl command to test the deployed API:
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/generate' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{"input_message": "YOUR_EXAMPLE_INPUT_PROMPT"}'
+```
+
+### Expected API Output
+The API response should be similar to the following:
+
+```bash
+{
+  "input": "YOUR_EXAMPLE_INPUT_PROMPT",
+  "value": "YOUR_EXPECTED_OUTPUT_HERE"
+}
+```
+
+## Customization Guide
+
+<!-- Add any specific customization instructions for your example -->
+
+### Adding New Functions
+1. Define a new config class in `register.py` that inherits from `FunctionBaseConfig`
+2. Create a function decorated with `@register_function`
+3. Add the function to your `config.yml` file
+4. Update the workflow's `tool_names` list
+
+### Modifying the Agent
+- Change the `_type` in the workflow section to use different agent types
+- Adjust `max_iterations`, `temperature`, or other parameters as needed
+- Add custom system prompts or modify the agent behavior
+
+### Using Different Models
+- Update the `model_name` in the LLM configuration
+- Adjust parameters such as `temperature` and `max_tokens`
+- Switch between different LLM providers (OpenAI, NIM, and so on)
diff --git a/pyproject.toml b/pyproject.toml
