diff --git a/.github/workflows/docs-build.yaml b/.github/workflows/docs-build.yaml new file mode 100644 index 000000000..5285fcade --- /dev/null +++ b/.github/workflows/docs-build.yaml @@ -0,0 +1,147 @@ +name: docs-build + +on: + pull_request: + branches: [develop] + types: [opened, synchronize] + paths: + - "docs/**" + - "**/*.md" + - "**/*.rst" + push: + branches: [develop] + tags: + - docs-v* + - v* + workflow_dispatch: + +defaults: + run: + shell: bash + +env: + PYTHON_VERSION: "3.10" + POETRY_VERSION: "1.8.2" + +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +jobs: + build-docs: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Set up Python ${{ env.PYTHON_VERSION }} + uses: actions/setup-python@v5 + with: + python-version: ${{ env.PYTHON_VERSION }} + - name: Bootstrap poetry (Linux and macOS) + run: | + curl -sSL https://install.python-poetry.org | POETRY_VERSION=${{ env.POETRY_VERSION }} python - + - name: Update PATH + run: echo "$HOME/.local/bin" >> $GITHUB_PATH + - name: Configure poetry + run: poetry config virtualenvs.in-project true + - name: Install dependencies + run: poetry install --only docs + - name: Build documentation + run: make docs + - name: Delete unnecessary files + run: | + sudo find _build -name .doctrees -prune -exec rm -rf {} \; + sudo find _build -name .buildinfo -exec rm {} \; + - name: Upload HTML + uses: actions/upload-artifact@v4 + with: + name: html-build-artifact + path: _build/docs + if-no-files-found: error + retention-days: 1 + - name: Store PR information + if: github.event_name == 'pull_request' + run: | + mkdir ./pr + echo ${{ github.event.number }} > ./pr/pr.txt + echo ${{ github.event.pull_request.merged }} > ./pr/merged.txt + echo ${{ github.event.action }} > ./pr/action.txt + - name: Upload PR information + if: github.event_name == 'pull_request' + uses: actions/upload-artifact@v4 + with: + name: pr + path: pr/ + + store-html: + if: github.event_name == 'push' + needs: [build-docs] + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + ref: "gh-pages" + - name: Initialize Git configuration + run: | + git config user.name docs-build + git config user.email do-not-send@github.com + - name: Download artifacts + uses: actions/download-artifact@v4 + with: + name: html-build-artifact + - name: Copy HTML directories + run: | + ls -asl + for i in `ls -d *` + do + echo "Git adding ${i}" + git add "${i}" + done + - name: Check or create dot-no-jekyll file + run: | + if [ -f ".nojekyll" ]; then + echo "The dot-no-jekyll file already exists." + exit 0 + fi + touch .nojekyll + git add .nojekyll + - name: Check or create redirect page + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + resp=$(grep 'http-equiv="refresh"' index.html 2>/dev/null) || true + if [ -n "${resp}" ]; then + echo "The redirect file already exists." + exit 0 + fi + # If any of these commands fail, fail the build. + def_branch=$(gh api "repos/${GITHUB_REPOSITORY}" --jq ".default_branch") + html_url=$(gh api "repos/${GITHUB_REPOSITORY}/pages" --jq ".html_url") + # Beware ugly quotation mark avoidance in the foll lines. + echo '' > index.html + echo '' >> index.html + echo ' ' >> index.html + echo ' Redirect to documentation' >> index.html + echo ' ' >> index.html + echo ' ' >> index.html + echo ' ' >> index.html + echo ' ' >> index.html + echo ' ' >> index.html + echo ' ' >> index.html + echo '

Please follow the link to the ' >> index.html + echo ${def_branch}' branch documentation.

' >> index.html + echo ' ' >> index.html + echo '' >> index.html + git add index.html + - name: Commit changes to the GitHub Pages branch + run: | + git status + if git commit -m 'Pushing changes to GitHub Pages.'; then + git push -f + else + echo "Nothing changed." + fi diff --git a/.github/workflows/docs-preview-pr.yaml b/.github/workflows/docs-preview-pr.yaml new file mode 100644 index 000000000..a91065b4a --- /dev/null +++ b/.github/workflows/docs-preview-pr.yaml @@ -0,0 +1,18 @@ +name: docs-preview-pr + +on: + workflow_run: + workflows: [docs-build] + types: [completed] + branches-ignore: [develop] + +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +env: + WF_ID: ${{ github.event.workflow_run.id }} + +jobs: + preview: + uses: nvidia-merlin/.github/.github/workflows/docs-preview-pr-common.yaml@main diff --git a/.github/workflows/docs-remove-stale-reviews.yaml b/.github/workflows/docs-remove-stale-reviews.yaml new file mode 100644 index 000000000..eb1ee61d3 --- /dev/null +++ b/.github/workflows/docs-remove-stale-reviews.yaml @@ -0,0 +1,11 @@ +name: docs-remove-stale-reviews + +on: + schedule: + # 42 minutes after 0:00 UTC on Sundays + - cron: "42 0 * * 0" + workflow_dispatch: + +jobs: + remove: + uses: nvidia-merlin/.github/.github/workflows/docs-remove-stale-reviews-common.yaml@main diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 9d0fd759c..34386d4c2 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -6,89 +6,93 @@ # Note that environment variables can be set in several places # See https://docs.gitlab.com/ee/ci/variables/#cicd-variable-precedence stages: - - tests - - build - - docker-test + - tests + - build + - docker-test + - deploy sast: - stage: tests + stage: tests include: - - template: Security/SAST.gitlab-ci.yml + - template: Security/SAST.gitlab-ci.yml + - project: "sw-gpu-doctools/docs-ci" + ref: main + file: "nemo-guardrails-toolkit/docs-ci.yaml" variables: - PIP_CACHE_DIR: "${CI_PROJECT_DIR}/.cache/pip" - POETRY_VERSION: "1.8.2" - IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG - LATEST_TAG: $CI_REGISTRY_IMAGE:latest + PIP_CACHE_DIR: "${CI_PROJECT_DIR}/.cache/pip" + POETRY_VERSION: "1.8.2" + IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_TAG + LATEST_TAG: $CI_REGISTRY_IMAGE:latest cache: - key: "${CI_JOB_NAME}-${CI_COMMIT_REF_SLUG}" - paths: - - .venv/ - - .cache/pip - - poetry.lock - - pyproject.toml + key: "${CI_JOB_NAME}-${CI_COMMIT_REF_SLUG}" + paths: + - .venv/ + - .cache/pip + - poetry.lock + - pyproject.toml # Jobs templates .install-deps-template: &install-deps - before_script: - - pip install poetry==$POETRY_VERSION - - poetry --version - - poetry config virtualenvs.in-project true - - poetry install --extras all --with dev + before_script: + - pip install poetry==$POETRY_VERSION + - poetry --version + - poetry config virtualenvs.in-project true + - poetry install --extras all --with dev .test-template: &test - <<: *install-deps - stage: tests - coverage: /(?i)total.*? (100(?:\.0+)?\%|[1-9]?\d(?:\.\d+)?\%)$/ - script: make test + <<: *install-deps + stage: tests + coverage: /(?i)total.*? (100(?:\.0+)?\%|[1-9]?\d(?:\.\d+)?\%)$/ + script: make test # Tests jobs python3.9: - <<: *test - image: python:3.9 + <<: *test + image: python:3.9 python3.10: - <<: *test - image: python:3.10 + <<: *test + image: python:3.10 python3.11: - <<: *test - image: python:3.11 + <<: *test + image: python:3.11 # Build job build: - stage: build - image: docker:19.03.12 - services: - - docker:19.03.12-dind - variables: - DOCKER_DRIVER: overlay2 - DOCKER_TLS_CERTDIR: "/certs" - before_script: - - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - script: - - docker build -t $IMAGE_TAG -f ./qa/Dockerfile.qa . - - docker push $IMAGE_TAG - only: - - tags - tags: - - gitlab-runner-bignlp-api + stage: build + image: docker:19.03.12 + services: + - docker:19.03.12-dind + variables: + DOCKER_DRIVER: overlay2 + DOCKER_TLS_CERTDIR: "/certs" + before_script: + - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY + script: + - docker build -t $IMAGE_TAG -f ./qa/Dockerfile.qa . + - docker push $IMAGE_TAG + only: + - tags + tags: + - gitlab-runner-bignlp-api # Docker test job docker-test: - stage: docker-test - image: docker:19.03.12 - services: - - docker:19.03.12-dind - before_script: - - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY - script: - - docker pull $IMAGE_TAG - - docker run --rm $IMAGE_TAG pytest || (docker rmi $IMAGE_TAG && exit 1) - only: - - tags + stage: docker-test + image: docker:19.03.12 + services: + - docker:19.03.12-dind + before_script: + - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY + script: + - docker pull $IMAGE_TAG + - docker run --rm $IMAGE_TAG pytest || (docker rmi $IMAGE_TAG && exit 1) + only: + - tags - tags: - - gitlab-runner-bignlp-api + tags: + - gitlab-runner-bignlp-api diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e8ea31ebd..0ce93049d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -135,7 +135,7 @@ To get started quickly, follow the steps below. Ensure you have `poetry` installed: ```bash - poetry -- version + poetry --version ``` 6. Install the dev dependencies: @@ -144,7 +144,8 @@ To get started quickly, follow the steps below. poetry install --with dev ``` - This will install pre-commit, pytest, and other development tools. + The preceding command installs pre-commit, pytest, and other development tools. + Specify `--with dev,docs` to add the dependencies for building the documentation. 7. If needed, you can install extra dependencies as below: @@ -159,7 +160,6 @@ To get started quickly, follow the steps below. ```bash poetry install --all-extras - ``` > **Note**: `dev` is not part of the extras but it is an optional dependency group, so you need to install it as instructed above. @@ -168,7 +168,6 @@ To get started quickly, follow the steps below. ``` pre-commit install - ``` This will ensure that the pre-commit checks, including Black, are run before each commit. diff --git a/Makefile b/Makefile index cdde5d43e..22906914c 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: all test tests test_watch test_coverage test_profile pre_commit help +.PHONY: all test tests test_watch test_coverage test_profile docs pre_commit help # Default target executed when no specific target is provided to make. all: help @@ -21,6 +21,9 @@ test_coverage: test_profile: poetry run pytest -vv tests/ --profile-svg +docs: + poetry run sphinx-build -b html docs _build/docs + pre_commit: pre-commit install pre-commit run --all-files @@ -35,4 +38,5 @@ help: @echo 'test TEST_FILE= - run all tests in given file' @echo 'test_watch - run unit tests in watch mode' @echo 'test_coverage - run unit tests with coverage' + @echo 'docs - build docs, if you installed the docs dependencies' @echo 'pre_commit - run pre-commit hooks' diff --git a/README.md b/README.md index b3ac96786..0dd5fbd06 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ ✨✨✨ -📌 **The official NeMo Guardrails documentation has moved to [docs.nvidia.com/nemo-guardrails](https://docs.nvidia.com/nemo-guardrails).** +📌 **The official NeMo Guardrails documentation has moved to [docs.nvidia.com/nemo/guardrails](https://docs.nvidia.com/nemo/guardrails).** ✨✨✨ @@ -40,6 +40,8 @@ For more detailed instructions, see the [Installation Guide](https://docs.nvidia ## Overview + + NeMo Guardrails enables developers building LLM-based applications to easily add **programmable guardrails** between the application code and the LLM.
@@ -54,6 +56,8 @@ Key benefits of adding *programmable guardrails* include: - **Controllable dialog**: you can steer the LLM to follow pre-defined conversational paths, allowing you to design the interaction following conversation design best practices and enforce standard operating procedures (e.g., authentication, support). + + ### Protecting against LLM Vulnerabilities NeMo Guardrails provides several mechanisms for protecting an LLM-powered chat application against common LLM vulnerabilities, such as jailbreaks and prompt injections. Below is a sample overview of the protection offered by different guardrails configuration for the example [ABC Bot](./examples/bots/abc) included in this repository. For more details, please refer to the [LLM Vulnerability Scanning](https://docs.nvidia.com/nemo/guardrails/evaluation/llm-vulnerability-scanning.html) page. diff --git a/docs/README.md b/docs/README.md index 5f618fd60..574ccc16f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,87 +1,26 @@ # Documentation -The documentation is divided into the following sections: +## Product Documentation -- [Getting Started](#getting-started) -- [Examples](#examples) -- [User Guides](#user-guides) -- [Evaluation Tools](#evaluation-tools) -- [Security](#security) -- [Advanced Guides](#advanced-guides) +Product documentation for the toolkit is available at +. -## Getting Started +## Building the Documentation -This section will help you get started quickly with NeMo Guardrails. +1. Make sure you installed the `docs` dependencies. + Refer to [CONTRIBUTING.md](../CONTRIBUTING.md) for more information about Poetry and dependencies. -* [Installation guide](getting-started/installation-guide.md): This guide walks you through the process of setting up your environment and installing NeMo Guardrails -* [Getting Started guides](./getting-started): A series of guides that will help you understand the core concepts and build your first guardrails configurations. These guides include Jupyter notebooks that you can experiment with. +1. Build the documentation: -## Examples + ```console + make docs + ``` -The [examples folder](https://github.com/NVIDIA/NeMo-Guardrails/tree/develop/examples) contains multiple examples that showcase a particular aspect of using NeMo Guardrails. + The HTML is created in the `_build/docs` directory. -* [Bots](https://github.com/NVIDIA/NeMo-Guardrails/tree/develop/examples/bots): This section includes two example configurations. - * [HelloWorldBot](https://github.com/NVIDIA/NeMo-Guardrails/tree/develop/examples/bots/hello_world): This basic configuration instructs the bot to greet the user using "Hello World!" and to not talk about politics or the stock market. - * [ABCBot](https://github.com/NVIDIA/NeMo-Guardrails/tree/develop/examples/bots/abc): This more complex configuration includes topical rails, input and output moderation and retrieval augmented generation. -* [Configs](https://github.com/NVIDIA/NeMo-Guardrails/tree/develop/examples/configs): These example configurations showcase specific NeMo Guardrails features, e.g., how to use various LLM providers, Retrieval Augmented Generation, streaming, red-teaming, authentication, etc. -* [Scripts](https://github.com/NVIDIA/NeMo-Guardrails/tree/develop/examples/scripts): These short scripts showcase various aspects of the main Python API. +## Publishing the Documentation +Tag the commit to publish with `docs-v`. +Push the tag to GitHub. -```{note} -These examples are meant to showcase the process of building rails, not as out-of-the-box safety features. Customization and strengthening of the rails is highly recommended. -``` - -## User Guides - -The user guides cover the core details of the NeMo Guardrails toolkit and how to configure and use different features to make your own rails. - -* [Guardrails Configuration Guide](user-guides/configuration-guide.md): The complete guide to all the configuration options available in the `config.yml` file. -* [Guardrails Library](user-guides/guardrails-library.md): An overview of the starter built-in rails that NeMo Guardrails provide. -* [Guardrails Process](user-guides/guardrails-process.md): A detailed description of the guardrails process, i.e., the categories of rails and how they are called. -* [Colang Language Guide](user-guides/colang-language-syntax-guide.md): Learn the syntax and core concepts of Colang. -* [LLM Support for Guardrails](user-guides/llm-support.md): An easy to grasp summary of the current LLM support. -* [Python API](user-guides/python-api.md): Learn about the Python API, e.g., the `RailsConfig` and `LLMRails` classes. -* [CLI](user-guides/cli.md): Learn about the NeMo Guardrails CLI that can help you use the Chat CLI or start a server. -* [Server Guide](user-guides/server-guide.md): Learn how to use the NeMo Guardrails server. -* [Integration with LangChain](user-guides/langchain/langchain-integration.md): Integrate guardrails in your existing LangChain-powered app. -* [Detailed Logging](user-guides/detailed-logging/README.md): Learn how to get detailed logging information. - -## Security - -* [Security Guidelines](./security/guidelines.md): Learn about some of the best practices for securely integrating an LLM into your application. -* [Red-teaming](./security/red-teaming.md): Learn how you can use the experimental NeMo Guardrails red-teaming interface. - -## Evaluation Tools - -NeMo Guardrails provides a set of CLI evaluation tools and experimental results for topical and execution rails. -There are also detailed guides on how to reproduce results and create datasets for the evaluation of each type of rail. - -* [Evaluation Tools and Results](https://github.com/NVIDIA/NeMo-Guardrails/tree/develop/nemoguardrails/eval): General explanation for the CLI evaluation tools and experimental results. -* [Topical Rail Evaluation - Dataset Tools](https://github.com/NVIDIA/NeMo-Guardrails/blob/develop/nemoguardrails/evaluate/data/topical/README.md): Dataset tools and details to run experiments for topical rails. -* [Fact-checking Rail Evaluation - Dataset Tools](https://github.com/NVIDIA/NeMo-Guardrails/blob/develop/nemoguardrails/evaluate/data/factchecking/README.md): Dataset tools and details to run experiments for fact-checking execution rail. -* [Moderation Rail Evaluation - Dataset Tools](https://github.com/NVIDIA/NeMo-Guardrails/blob/develop/nemoguardrails/evaluate/data/moderation/README.md): Dataset tools and details to run experiments for moderation execution rail. - -## Advanced Guides - -The following guides explain in more details various specific topics: - -* [Generation Options](user-guides/advanced/generation-options.md): Learn how to have to use advanced generation options. -* [Prompt Customization](user-guides/advanced/prompt-customization.md): Learn how to customize the prompts for a new (or existing) type of LLM. -* [Embedding Search Providers](user-guides/advanced/embedding-search-providers.md): Learn about the core embedding search interface that NeMo guardrails uses for some of the core features. -* [Using Docker](user-guides/advanced/using-docker.md): Learn how to deploy NeMo Guardrails using Docker. -* [Streaming](user-guides/advanced/streaming.md): Learn about the streaming support in NeMo Guardrails. -* [AlignScore deployment](user-guides/advanced/align-score-deployment.md): Learn how to deploy an AlignScore server either directly or using Docker. -* [Extract User-provided Values](user-guides/advanced/extract-user-provided-values.md): Learn how to extract user-provided values like a name, a date or a query. -* [Bot Message Instructions](user-guides/advanced/bot-message-instructions.md): Learn how to further tweak the bot messages with specific instructions at runtime. -* [Event-based API](user-guides/advanced/event-based-api.md): Learn about the generic event-based interface that you can use to process additional information in your guardrails configuration. -* [Jailbreak Detection Heuristics Deployment](user-guides/advanced/jailbreak-detection-deployment.md): Learn how to deploy the jailbreak detection heuristics server. -* [Llama Guard Deployment](user-guides/advanced/llama-guard-deployment.md): Learn how to deploy Llama Guard using vLLM. -* [Nested AsyncIO Loop](user-guides/advanced/nested-async-loop.md): Understand some of the low level issues regarding `asyncio` and how they are handled in NeMo Guardrails. -* [Vertex AI Setup](user-guides/advanced/vertexai-setup.md): Learn how to setup a Vertex AI account. - - -## Other - -* [Architecture](./architecture/README.md#the-guardrails-process): Learn how the Guardrails runtime works under the hood. -* [Glossary](./glossary.md) -* [FAQs](./faqs.md) +To avoid publishing the documentation as the latest, ensure the commit has `/not-latest` on a single line, tag that commit, and push to GitHub. diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 000000000..ec3f73374 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,86 @@ +# SPDX-FileCopyrightText: Copyright (c) 2023 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. + +# Copyright (c) 2024, NVIDIA CORPORATION. + +from datetime import date + +from toml import load + +project = "NVIDIA NeMo Guardrails" +this_year = date.today().year +copyright = f"2023-{this_year}, NVIDIA Corporation" +author = "NVIDIA Corporation" +release = "0.0.0" +with open("../pyproject.toml") as f: + t = load(f) + release = t.get("tool").get("poetry").get("version") + +extensions = [ + "myst_parser", + "sphinx.ext.intersphinx", + "sphinx_copybutton", + "sphinx_reredirects", +] + +redirects = { + "introduction": "index.html", + "documentation": "index.html", +} + +copybutton_exclude = ".linenos, .gp, .go" + +myst_linkify_fuzzy_links = False +myst_heading_anchors = 3 +myst_enable_extensions = [ + "deflist", + "dollarmath", + "fieldlist", + "substitution", +] + +myst_substitutions = { + "version": release, +} + +exclude_patterns = [ + "_build/**", +] + +# intersphinx_mapping = { +# 'gpu-op': ('https://docs.nvidia.com/datacenter/cloud-native/gpu-operator/latest', None), +# } + +# suppress_warnings = ["etoc.toctree", "myst.header", "misc.highlighting_failure"] + +html_theme = "nvidia_sphinx_theme" +html_copy_source = False +html_show_sourcelink = False +html_show_sphinx = False + +html_domain_indices = False +html_use_index = False +html_extra_path = ["project.json", "versions1.json"] +highlight_language = "console" + +html_theme_options = { + "icon_links": [], + "switcher": { + "json_url": "../versions1.json", + "version_match": release, + }, +} + +html_baseurl = "https://docs.nvidia.com/nemo/guardrails/latest/" diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..9f8339f6c --- /dev/null +++ b/docs/index.md @@ -0,0 +1,117 @@ + + +# About NeMo Guardrails + +```{include} ../README.md +:start-after: +:end-before: