Perform vale spelling checks on notebooks (#896)

* Exports notebooks to markdown files in a temporary directory, and then runs vale on those
* Remove out of date exclusion of the `nv_internal` directory

## 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
  - Polished example notebooks: corrected wording/capitalization, standardized terminology (e.g., LlamaIndex, FastAPI), improved code/reference formatting, and clarified the GPU sizing notebook intro and notes.
  - Removed certain in-notebook execution snippets to streamline guidance.
  - Expanded documentation vocabulary to reduce linting false positives.

- Chores
  - Documentation linting now includes converted notebooks for more comprehensive checks.
  - Improved robustness of docs checks with clearer error handling and temporary file management.
  - Added nbconvert to development dependencies to support notebook conversion.

Authors:
  - David Gardner (https://github.com/dagardner-nv)

Approvers:
  - Will Killian (https://github.com/willkill07)
  - https://github.com/Salonijain27

URL: #896

Author: dagardner-nv

ci/scripts/documentation_checks.sh

@@ -17,8 +17,37 @@
 set +e
 
 # Intentionally excluding CHANGELOG.md as it immutable
-DOC_FILES=$(git ls-files "*.md" "*.rst" | grep -v -E '^(CHANGELOG|LICENSE)\.md$' | grep -v -E '^nv_internal/')
+DOC_FILES=$(git ls-files "*.md" "*.rst" | grep -v -E '^(CHANGELOG|LICENSE)\.md$')
+NOTEBOOK_FILES=$(git ls-files "*.ipynb")
 
-vale ${DOC_FILES}
+if [[ -v ${WORKSPACE_TMP} ]]; then
+    MKTEMP_ARGS=""
+else
+    MKTEMP_ARGS="--tmpdir=${WORKSPACE_TMP}"
+fi
+
+EXPORT_DIR=$(mktemp -d ${MKTEMP_ARGS} nat_converted_notebooks.XXXXXX)
+if [[ ! -d "${EXPORT_DIR}" ]]; then
+    echo "ERROR: Failed to create temporary directory" >&2
+    exit 1
+fi
+
+jupyter nbconvert -y --log-level=WARN --to markdown --output-dir ${EXPORT_DIR} ${NOTEBOOK_FILES}
+if [[ $? -ne 0 ]]; then
+    echo "ERROR: Failed to convert notebooks" >&2
+    rm -rf "${EXPORT_DIR}"
+    exit 1
+fi
+
+CONVERTED_NOTEBOOK_FILES=$(find ${EXPORT_DIR} -type f  -name "*.md")
+
+vale ${DOC_FILES} ${CONVERTED_NOTEBOOK_FILES}
 RETVAL=$?
+
+if [[ "${PRESERVE_TMP}" == "1" ]]; then
+    echo "Preserving temporary directory: ${EXPORT_DIR}"
+else
+    rm -rf "${EXPORT_DIR}"
+fi
+
 exit $RETVAL

ci/vale/styles/config/vocabularies/nat/accept.txt

@@ -31,7 +31,7 @@ CMake
 Conda
 concurrencies
 config
-Configurability
+[Cc]onfigurability
 [Cc]oroutine(s?)
 CPython
 [Cc]ryptocurrenc[y|ies]
@@ -114,6 +114,7 @@ Pydantic
 PyPI
 pytest
 [Rr]edis
+[Rr]eimplement(ing)?
 [Rr]einstall(s?)
 [Rr]eplatform(ing)?
 [Rr]epo
@@ -135,6 +136,7 @@ Tavily
 [Tt]okenization
 [Tt]okenizer(s?)
 triages
+[Uu]ncomment
 [Uu]nencrypted
 [Uu]nittest(s?)
 [Uu]nprocessable
@@ -150,4 +152,4 @@ zsh
 Zep
 Optuna
 [Oo]ptimizable
-[Cc]heckpointed
+[Cc]heckpointed

examples/notebooks/1_getting_started.ipynb

@@ -60,7 +60,7 @@
     "\n",
     "We'll walk you through how to achieve this.\n",
     "\n",
-    "To demonstrate this, let's say that you have the following simple LangChain/LangGraph agent that answers generic user queries about current events by performing a web search using Tavily. We will show you how to bring this agent into the NeMo-Agent-Toolkit and benefit from the configurability, resuability, and easy user experience.\n",
+    "To demonstrate this, let's say that you have the following simple LangChain/LangGraph agent that answers generic user queries about current events by performing a web search using Tavily. We will show you how to bring this agent into the NeMo-Agent-Toolkit and benefit from the configurability, reusability, and easy user experience.\n",
     "\n",
     "Run the following two cells to create the LangChain/LangGraph agent and run it with an example input."
    ]
@@ -182,11 +182,11 @@
     "\n",
     "The NeMo Agent toolkit provides several ways to run/host an workflow. These are called `front_end` plugins. Some examples are:\n",
     "\n",
-    "console: `nat run` (or long version nat start console …). This is useful when performing local testing and debugging. It allows you to pass inputs defined as arguments directly into the workflow. This is show already in the notebook.\n",
+    "console: `nat run` (or long version `nat start console …`). This is useful when performing local testing and debugging. It allows you to pass inputs defined as arguments directly into the workflow. This is show already in the notebook.\n",
     "\n",
-    "Fastapi: `nat serve`(or long version nat start fastapi …). This is useful when hosting your workflow as a REST and websockets endpoint.\n",
+    "FastAPI: `nat serve`(or long version `nat start fastapi …`). This is useful when hosting your workflow as a REST and WebSockets endpoint.\n",
     "\n",
-    "MCP: `nat mcp` (or long version nat start mcp …). This is useful when hosting the workflow and/or any function as an MCP server\n",
+    "MCP: `nat mcp` (or long version `nat start mcp …`). This is useful when hosting the workflow and/or any function as an MCP server\n",
     "\n",
     "While these are the built in front-end components, the system is extensible with new user defined front-end plugins.\n",
     "\n",
@@ -256,9 +256,9 @@
     "```python\n",
     "tools = await builder.get_tools(config.tool_names, wrapper_type=LLMFrameworkEnum.LANGCHAIN)\n",
     "```\n",
-    "> **Note**: This allows you to bring in tools from other frameworks like llama index as well and wrap them with langchain since you are implementing your agent in langchain.\n",
+    "> **Note**: This allows you to bring in tools from other frameworks like LlamaIndex as well and wrap them with LangChain since you are implementing your agent in LangChain.\n",
     "\n",
-    "In a similar way, you can initialize your llm by utilizing the parameters from the configuration object in the following way:\n",
+    "In a similar way, you can initialize your LLM by utilizing the parameters from the configuration object in the following way:\n",
     "```python\n",
     "llm = await builder.get_llm(config.llm_name, wrapper_type=LLMFrameworkEnum.LANGCHAIN)\n",
     "```"
@@ -268,7 +268,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "For each tool or reusable plugin, there are potentially multiple optional parameters with default values that can be overridden. The `nat info components` command can be used to list all available parameters. For example, to list all available parameters for the LLM nim type run:\n",
+    "For each tool or reusable plugin, there are potentially multiple optional parameters with default values that can be overridden. The `nat info components` command can be used to list all available parameters. For example, to list all available parameters for the LLM NIM type run:\n",
     "\n",
     "```bash\n",
     "nat info components -t llm_provider -q nim\n",
@@ -281,7 +281,7 @@
    "source": [
     "#### Reusing the Inbuilt Tavily Search Function\n",
     "\n",
-    "We can also make use of some of many example functions that the toolkit provides for common use cases. In this agent example, rather than reimplementing the tavily search, we will use the inbuilt function for internet search which is built on top of LangChain/LangGraph's tavily search API. You can list available functions using the following:"
+    "We can also make use of some of many example functions that the toolkit provides for common use cases. In this agent example, rather than reimplementing the Tavily search, we will use the inbuilt function for internet search which is built on top of LangChain/LangGraph's Tavily search API. You can list available functions using the following:"
    ]
   },
   {

examples/notebooks/2_add_tools_and_agents.ipynb

@@ -31,7 +31,7 @@
    "metadata": {},
    "source": [
     "> **Note**: \n",
-    "> All source code for this example can be found at [./retail_sales_agent](./retail_sales_agent/)"
+    "> All source code for this example can be found at [`./retail_sales_agent`](./retail_sales_agent/)"
    ]
   },
   {
@@ -68,7 +68,7 @@
     "\n",
     "All new functions (tools and agents) that you want to be a part of this agent system can be created inside this directory for easier grouping of plugins. The only necessity for discovery by the toolkit is to import all new files/functions or simply define them in the `register.py` function.\n",
     "\n",
-    "The example referenced in this notebook has already been created in the [retail_sales_agent](./retail_sales_agent/) uisng the following command:\n",
+    "The example referenced in this notebook has already been created in the [`retail_sales_agent`](./retail_sales_agent/) using the following command:\n",
     "```bash\n",
     "nat workflow create --workflow-dir . retail_sales_agent\n",
     "```"
@@ -116,7 +116,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Adding a Retrieval Tool using Llamaindex"
+    "### Adding a Retrieval Tool using LlamaIndex"
    ]
   },
   {
@@ -127,7 +127,7 @@
     "\n",
     "Refer to the code for the `product_catalog_rag` tool in [llama_index_rag_tool.py](./retail_sales_agent/src/nat_retail_sales_agent/llama_index_rag_tool.py). This can use a Milvus vector store for GPU-accelerated indexing. \n",
     "\n",
-    "It requires the addition of an embedder section the [config_with_rag.yml](./retail_sales_agent/configs/config_with_rag.yml). This section follows a the same structure as the llms section and serves as a way to separate the embedding models from the LLM models. In our example, we are using the `nvidia/nv-embedqa-e5-v5` model.\n",
+    "It requires the addition of an embedder section the [config_with_rag.yml](./retail_sales_agent/configs/config_with_rag.yml). This section follows a the same structure as the `llms` section and serves as a way to separate the embedding models from the LLM models. In our example, we are using the `nvidia/nv-embedqa-e5-v5` model.\n",
     "\n",
     "\n",
     "You can test this workflow with the following command:"
@@ -217,17 +217,17 @@
    "source": [
     "Besides using inbuilt agents in the workflows, we can also create custom agents using LangGraph or any other framework and bring them into a workflow. We demonstrate this by swapping out the `react_agent` used by the data visualization expert for a custom agent that has human-in-the-loop capability (utilizing a reusable plugin for HITL in the NeMo-Agent-Toolkit). The agent will ask the user whether they would like a summary of graph content.\n",
     "\n",
-    "The code can be found in [data_visualization_agent.py](examples/retail_sales_agent/src/nat_retail_sales_agent/data_visualization_agent.py)\n",
+    "The code can be found in [`data_visualization_agent.py`](examples/retail_sales_agent/src/nat_retail_sales_agent/data_visualization_agent.py)\n",
     "\n",
     "This agent has an agent node, a tools node, a node to accept human input and a summarizer node.\n",
     "\n",
-    "Agent → generates tool calls → conditional_edge routes to tools\n",
+    "Agent → generates tool calls → `conditional_edge` routes to tools\n",
     "\n",
-    "Tools → execute → edge routes back to data_visualization_agent\n",
+    "Tools → execute → edge routes back to `data_visualization_agent`\n",
     "\n",
-    "Agent → detects ToolMessage → creates summary AIMessage → conditional_edge routes to check_hitl_approval\n",
+    "Agent → detects ToolMessage → creates summary `AIMessage` → `conditional_edge` routes to `check_hitl_approval`\n",
     "\n",
-    "HITL → approval → conditional_edge routes to summarize or end\n",
+    "HITL → approval → `conditional_edge` routes to summarize or end\n",
     "\n",
     "\n",
     "#### Human-in-the-Loop Plugin\n",
@@ -258,7 +258,7 @@
     "        # Rest of the function\n",
     "```\n",
     "\n",
-    "As we see above, requesting user input using NeMo Agent toolkit is straightforward. We can use the user_input_manager to prompt the user for input. The user's response is then processed to determine the next steps in the workflow. This can occur in any tool or function in the workflow, allowing for dynamic interaction with the user as needed."
+    "As we see above, requesting user input using NeMo Agent toolkit is straightforward. We can use the `user_input_manager` to prompt the user for input. The user's response is then processed to determine the next steps in the workflow. This can occur in any tool or function in the workflow, allowing for dynamic interaction with the user as needed."
    ]
   },
   {

examples/notebooks/3_observability_evaluation_and_profiling.ipynb

@@ -185,9 +185,9 @@
     "\n",
     "- `prompt_caching_prefixes`: Identify common prompt prefixes. This is helpful for identifying if you have commonly repeated prompts that can be pre-populated in KV caches\n",
     "\n",
-    "- `bottleneck_analysis`: Analyze workflow performance measures such as bottlenecks, latency, and concurrency spikes. This can be set to simple_stack for a simpler analysis. Nested stack will provide a more detailed analysis identifying nested bottlenecks like tool calls inside other tools calls.\n",
+    "- `bottleneck_analysis`: Analyze workflow performance measures such as bottlenecks, latency, and concurrency spikes. This can be set to `simple_stack` for a simpler analysis. Nested stack will provide a more detailed analysis identifying nested bottlenecks like tool calls inside other tools calls.\n",
     "\n",
-    "- `concurrency_spike_analysis`: Analyze concurrency spikes. This will identify if there are any spikes in the number of concurrent tool calls. At a spike_threshold of 7, the profiler will identify any spikes where the number of concurrent running functions is greater than or equal to 7. Those are surfaced to the user in a dedicated section of the workflow profiling report."
+    "- `concurrency_spike_analysis`: Analyze concurrency spikes. This will identify if there are any spikes in the number of concurrent tool calls. At a `spike_threshold` of `7`, the profiler will identify any spikes where the number of concurrent running functions is greater than or equal to `7`. Those are surfaced to the user in a dedicated section of the workflow profiling report."
    ]
   },
   {
@@ -210,7 +210,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "This will, based on the above configuration, produce the following files in the output_dir specified in the configuration file:\n",
+    "This will, based on the above configuration, produce the following files in the `output_dir` specified in the configuration file:\n",
     "\n",
     "- `all_requests_profiler_traces.json`: This file contains the raw usage statistics collected by the profiler. Includes raw traces of LLM and tool input, runtimes, and other metadata.\n",
     "\n",

examples/notebooks/launchables/GPU_Cluster_Sizing_with_NeMo_Agent_Toolkit.ipynb

@@ -6,7 +6,7 @@
    "source": [
     "# Size a GPU Cluster With NVIDIA NeMo Agent Toolkit\n",
     "\n",
-    "This notebook demonstrates how to use the NVIDIA NeMo Agent toolkit's sizing calculator to estimate the GPU cluster size required to accommodate a target number of users with a target response time. The estimation is based on the performance of the workflow at different concurrency levels.\n",
+    "This notebook demonstrates how to use the sizing calculator example to estimate the GPU cluster size required to accommodate a target number of users with a target response time. The estimation is based on the performance of the workflow at different concurrency levels.\n",
     "\n",
     "The sizing calculator uses the [evaluation](https://docs.nvidia.com/nemo/agent-toolkit/latest/workflows/evaluate.html) and [profiling](https://docs.nvidia.com/nemo/agent-toolkit/latest/workflows/profiler.html) systems in the NeMo Agent toolkit.\n",
     "\n",
@@ -420,9 +420,7 @@
     "\n",
     "The configuration should include a `base_url` parameter for your cluster. You can edit the file manually yourself, or use the below interactive configuration editor.\n",
     "\n",
-    "<div class=\"alert alert-block alert-success\">\n",
-    "    <b>NOTE:</b> You can bring your own config file! Simply replace <b>source_config</b> below with a path to your uploaded config file in the <b>NeMo-Agent-Toolkit</b> repo. \n",
-    "</div>"
+    "> **NOTE:** You can bring your own config file! Simply replace `source_config` below with a path to your uploaded config file in the *NeMo-Agent-Toolkit* repo. \n"
    ]
   },
   {

pyproject.toml

@@ -221,6 +221,7 @@ dev = [
   "httpx-sse~=0.4",
   "ipython~=8.31",
   "myst-parser~=4.0",
+  "nbconvert", # Version determined by jupyter
   "nbsphinx~=0.9",
   "nvidia-nat_test",
   "nvidia-sphinx-theme>=0.0.7",