From 175d2b66a99fd224dd4c8e25b4623087259c2982 Mon Sep 17 00:00:00 2001 From: Mike McKiernan Date: Mon, 27 Jan 2025 11:07:43 -0500 Subject: [PATCH 1/3] Build docs in GitHub for review Signed-off-by: Mike McKiernan --- .github/workflows/docs-build-pr.yaml | 54 ++ .github/workflows/docs-build.yaml | 198 ++++ .github/workflows/docs-preview-pr.yaml | 18 + .../workflows/docs-remove-stale-reviews.yaml | 11 + README.md | 6 +- docs/Dockerfile | 33 + docs/README.md | 93 +- docs/conf.py | 86 ++ docs/index.md | 117 +++ docs/index.rst | 102 --- docs/poetry.lock | 851 ++++++++++++++++++ docs/project.json | 1 + docs/pyproject.toml | 16 + ...lbreak-detection-heuristics-deployment.md} | 0 docs/versions1.json | 7 + 15 files changed, 1413 insertions(+), 180 deletions(-) create mode 100644 .github/workflows/docs-build-pr.yaml create mode 100644 .github/workflows/docs-build.yaml create mode 100644 .github/workflows/docs-preview-pr.yaml create mode 100644 .github/workflows/docs-remove-stale-reviews.yaml create mode 100644 docs/Dockerfile create mode 100644 docs/conf.py create mode 100644 docs/index.md delete mode 100644 docs/index.rst create mode 100644 docs/poetry.lock create mode 100644 docs/project.json create mode 100644 docs/pyproject.toml rename docs/user-guides/advanced/{jailbreak-detection-deployment.md => jailbreak-detection-heuristics-deployment.md} (100%) create mode 100644 docs/versions1.json diff --git a/.github/workflows/docs-build-pr.yaml b/.github/workflows/docs-build-pr.yaml new file mode 100644 index 000000000..216511cd8 --- /dev/null +++ b/.github/workflows/docs-build-pr.yaml @@ -0,0 +1,54 @@ +name: docs-build-pr + +on: + pull_request: + branches: [develop] + types: [opened, synchronize] + +env: + GH_TOKEN: ${{ github.token }} + +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 Docker Buildx + uses: docker/setup-buildx-action@v3 + - name: Build image + uses: docker/build-push-action@v6 + with: + context: docs + file: docs/Dockerfile + load: true + tags: pr-image:${{ github.sha }} + - name: Build docs + run: | + docker run -v $(pwd):/work -w /work pr-image:${{ github.sha }} sphinx-build -b html docs _build/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 + 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 + uses: actions/upload-artifact@v4 + with: + name: pr + path: pr/ diff --git a/.github/workflows/docs-build.yaml b/.github/workflows/docs-build.yaml new file mode 100644 index 000000000..0da8ddcb7 --- /dev/null +++ b/.github/workflows/docs-build.yaml @@ -0,0 +1,198 @@ +name: docs-build + +on: + push: + branches: [develop] + tags: + - docs-v* + - v* + workflow_dispatch: + +env: + REGISTRY: ghcr.io + IMAGE_NAME: ${{ github.repository }}-docs + TAG: 0.1.0 + GH_TOKEN: ${{ github.token }} + +concurrency: + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +jobs: + dockerfile-changed: + runs-on: ubuntu-latest + permissions: + contents: read + packages: read + outputs: + changed: ${{ steps.change.outputs.changed }} + image: ${{ steps.change.outputs.image }} + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Log in to Container Registry + uses: docker/login-action@v3 + with: + registry: ${{ env.REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + - name: Detect change + id: change + shell: bash + run: | + export COMMIT_SHORT_SHA="${GITHUB_SHA:0:8}" + if ! docker manifest inspect "${REGISTRY}/${IMAGE_NAME,,}:${TAG}" 2>&1 > /dev/null ; then + echo "image not found...${REGISTRY}/${IMAGE_NAME,,}:${TAG}" + export NEEDS_IMAGE=true + fi + def_branch=$(gh api "repos/${GITHUB_REPOSITORY}" -q '.default_branch') + git fetch origin "${def_branch}" + files=$(git diff --name-only "${GITHUB_SHA}" FETCH_HEAD | tr '\n' ' ') + echo "${files}" + if echo "${files}" | grep -q "docs/poetry.lock/\|docs/Dockerfile"; then export NEEDS_IMAGE=true ; fi + if [[ "${NEEDS_IMAGE}" ]]; then + echo "changed=true" >> "$GITHUB_OUTPUT" + if [[ "${{ github.event_name }}" == 'pull_request' ]]; then + echo "image=${REGISTRY}/${IMAGE_NAME,,}:${COMMIT_SHORT_SHA}" >> "$GITHUB_OUTPUT" + else + echo "image=${REGISTRY}/${IMAGE_NAME,,}:${TAG}" >> "$GITHUB_OUTPUT" + fi + else + echo "changed=false" >> "$GITHUB_OUTPUT" + echo "image=${REGISTRY}/${IMAGE_NAME,,}:${TAG}" >> "$GITHUB_OUTPUT" + fi + + build-and-push-image: + needs: dockerfile-changed + if: needs.dockerfile-changed.outputs.changed == 'true' + runs-on: ubuntu-latest + permissions: + contents: read + packages: write + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + - name: Log in to Container Registry + uses: docker/login-action@v3 + with: + registry: ${{ env.REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + - name: Build and push + uses: docker/build-push-action@v6 + with: + context: docs + file: docker/Dockerfile + push: true + tags: ${{ needs.dockerfile-changed.outputs.image }} + + build-docs: + needs: [dockerfile-changed, build-and-push-image] + container: + image: ${{ needs.dockerfile-changed.outputs.image }} + if: ${{ always() }} + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + - name: Build docs + run: | + sphinx-build -b html docs _build/docs + - name: Delete unnecessary files + run: | + find _build -name .doctrees -prune -exec rm -rf {} \; + 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: + 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..f26c830cd --- /dev/null +++ b/.github/workflows/docs-preview-pr.yaml @@ -0,0 +1,18 @@ +name: docs-preview-pr + +on: + workflow_run: + workflows: [ docs-build-pr ] + types: [ completed ] + branches-ignore: [ main ] + +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..8b758c37a --- /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/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/Dockerfile b/docs/Dockerfile new file mode 100644 index 000000000..3d2a80d3f --- /dev/null +++ b/docs/Dockerfile @@ -0,0 +1,33 @@ +# Copyright (c) 2019, NVIDIA CORPORATION. All rights reserved. +# +# 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. + +FROM python:3.10 + +ARG UID=1000 + +ENV POETRY_VERSION=1.8.2 +ENV POETRY_HOME=/opt/poetry +ENV PATH="${PATH}:${POETRY_HOME}/bin" + +RUN apt-get update && DEBIAN_FRONTEND=noninteractive \ + && apt-get install --no-install-recommends -y \ + curl \ + python3-pip \ + jq \ + lsb-release + +RUN curl -sSL https://install.python-poetry.org | POETRY_VERSION="${POETRY_VERSION}" POETRY_HOME="${POETRY_HOME}" python - + +RUN useradd -u "${UID}" -ms /bin/bash nvs +RUN --mount=type=bind,target=/work poetry config virtualenvs.create false && poetry install -C /work --with docs --no-interaction --no-ansi diff --git a/docs/README.md b/docs/README.md index 5f618fd60..32a90bce2 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. Build the container: -* [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. + ```console + docker build -t guard-tk-docs:dev --build-arg UID=$(id -u) docs + ``` -## Examples +1. Start the container: -The [examples folder](https://github.com/NVIDIA/NeMo-Guardrails/tree/develop/examples) contains multiple examples that showcase a particular aspect of using NeMo Guardrails. + ```console + docker run --rm -it -v $(pwd):/work -w /work -u $(id -u) guard-tk-docs:dev bash + ``` -* [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. +1. Build the documentation: - -```{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) + ```console + sphinx-build -b html docs _build/docs + ``` 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: