Improve new workflow template

[zhongxuanwang-nv]

Description

Closes AIQ-1957

• Made the default workflow a react-based workflow
• Used python_safe_workflow_name instead for the module name
• Edited workflow_commands.py by replacing workflow_name with package_name, to ensure imports work (because package_name doesn't have -)

By Submitting this PR I confirm:

• I am familiar with the Contributing Guidelines.
• 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

• New Features

  • Added an echo tool (configurable prefix) and a current_datetime tool to workflows.
  • Introduced a default NIM LLM using meta/llama-3.1-70b-instruct (temperature 0.0).
  • Workflows gain LangChain wrapper support and parse-agent response retry set to 3.

• Refactor

  • Workflow templates now use a ReAct agent type and reference the NIM LLM and tools.
  • Generated workflow names/exports now use Python-safe naming conventions.

[coderabbitai]

Walkthrough

Switches the workflow template to a react_agent, adds a Nim LLM and two tools/functions (current_datetime and a generated python-safe function), updates workflow registration to use a python-safe name, and changes the generated workflow filename to use the python-safe workflow name.

Changes

Cohort / File(s)	Summary
Workflow config template src/nat/cli/commands/workflow/templates/config.yml.j2	_type changed to react_agent; adds llms.nim_llm (type nim, model_name: meta/llama-3.1-70b-instruct, temperature: 0.0); adds functions.current_datetime and functions.{{python_safe_workflow_name}} (prefix "Hello:"); adds llm_name: nim_llm, tool_names: [current_datetime, {{python_safe_workflow_name}}], and parse_agent_response_max_retries: 3; removes prior parameter: default_value.
Workflow implementation template src/nat/cli/commands/workflow/templates/workflow.py.j2	Adds import of LLMFrameworkEnum; adds public prefix: str Field (default "Echo:") on the config class; replaces previous inlined workflow with a registered async function that defines an internal async _echo(text) and yields FunctionInfo.from_fn(_echo, ...) registered with framework_wrappers=[LLMFrameworkEnum.LANGCHAIN]; removes previous response-handling try/except/finally flow.
Registration template src/nat/cli/commands/workflow/templates/register.py.j2	Changes the imported symbol to the python-safe name: from {{package_name}} import {{workflow_name}}_function → from {{package_name}} import {{python_safe_workflow_name}}_function.
CLI command output path src/nat/cli/commands/workflow/workflow_commands.py	Introduces python_safe_workflow_name (hyphens → underscores) and uses it for generated filenames and rendering context instead of the original workflow_name.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User
  participant GenFile as Generated function file
  participant Agent as react_agent runtime
  participant LLM as nim_llm
  participant ToolTime as current_datetime
  participant ToolEcho as {{python_safe_workflow_name}}

  User->>GenFile: invoke workflow function
  GenFile->>Agent: start react_agent (llm_name=nim_llm, tool_names)
  Agent->>LLM: request reasoning / actions
  alt LLM requests current time
    LLM->>ToolTime: current_datetime()
    ToolTime-->>LLM: timestamp
  end
  alt LLM requests echo
    LLM->>ToolEcho: call echo(input)
    ToolEcho-->>LLM: prefixed text
  end
  LLM-->>Agent: final response
  Agent-->>GenFile: return/stream result
  GenFile-->>User: deliver result

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title ‘Improve new workflow template’ succinctly summarizes the primary change of enhancing the workflow scaffolding. It is written in imperative mood and stays well under the recommended character limit. The wording directly relates to the updates in the templates and reflects the pull request objectives.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing touches

• 📝 Generate Docstrings

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/nat/cli/commands/workflow/workflow_commands.py (1)

236-238: Reuse package_name when populating the safe identifier.

package_name already carries the fully sanitized value from _get_module_name; manually reapplying only the hyphen replacement risks the two values diverging if we ever evolve _get_module_name. Please just reuse package_name for the Jinja context.

-            'python_safe_workflow_name': workflow_name.replace("-", "_"),
+            'python_safe_workflow_name': package_name,

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1ae72cf and b64ead9.

📒 Files selected for processing (4)

• src/nat/cli/commands/workflow/templates/config.yml.j2 (1 hunks)
• src/nat/cli/commands/workflow/templates/register.py.j2 (1 hunks)
• src/nat/cli/commands/workflow/templates/workflow.py.j2 (1 hunks)
• src/nat/cli/commands/workflow/workflow_commands.py (1 hunks)

🧰 Additional context used

📓 Path-based instructions (6)

**/*.{py,yaml,yml}

📄 CodeRabbit inference engine (.cursor/rules/nat-test-llm.mdc)

**/*.{py,yaml,yml}: Configure response_seq as a list of strings; values cycle per call, and [] yields an empty string.
Configure delay_ms to inject per-call artificial latency in milliseconds for nat_test_llm.

Files:

• src/nat/cli/commands/workflow/workflow_commands.py

**/*.py

📄 CodeRabbit inference engine (.cursor/rules/nat-test-llm.mdc)

**/*.py: Programmatic use: create TestLLMConfig(response_seq=[...], delay_ms=...), add with builder.add_llm("", cfg).
When retrieving the test LLM wrapper, use builder.get_llm(name, wrapper_type=LLMFrameworkEnum.) and call the framework’s method (e.g., ainvoke, achat, call).

**/*.py: In code comments/identifiers use NAT abbreviations as specified: nat for API namespace/CLI, nvidia-nat for package name, NAT for env var prefixes; do not use these abbreviations in documentation
Follow PEP 20 and PEP 8; run yapf with column_limit=120; use 4-space indentation; end files with a single trailing newline
Run ruff check --fix as linter (not formatter) using pyproject.toml config; fix warnings unless explicitly ignored
Respect naming: snake_case for functions/variables, PascalCase for classes, UPPER_CASE for constants
Treat pyright warnings as errors during development
Exception handling: use bare raise to re-raise; log with logger.error() when re-raising to avoid duplicate stack traces; use logger.exception() when catching without re-raising
Provide Google-style docstrings for every public module, class, function, and CLI command; first line concise and ending with a period; surround code entities with backticks
Validate and sanitize all user input, especially in web or CLI interfaces
Prefer httpx with SSL verification enabled by default and follow OWASP Top-10 recommendations
Use async/await for I/O-bound work; profile CPU-heavy paths with cProfile or mprof before optimizing; cache expensive computations with functools.lru_cache or external cache; leverage NumPy vectorized operations when beneficial

Files:

• src/nat/cli/commands/workflow/workflow_commands.py

src/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/general.mdc)

All importable Python code must live under src/ (or packages//src/)

Files:

• src/nat/cli/commands/workflow/workflow_commands.py

src/nat/**/*

📄 CodeRabbit inference engine (.cursor/rules/general.mdc)

Changes in src/nat should prioritize backward compatibility

Files:

• src/nat/cli/commands/workflow/workflow_commands.py
• src/nat/cli/commands/workflow/templates/config.yml.j2
• src/nat/cli/commands/workflow/templates/workflow.py.j2
• src/nat/cli/commands/workflow/templates/register.py.j2

---

⚙️ CodeRabbit configuration file

This directory contains the core functionality of the toolkit. Changes should prioritize backward compatibility.

Files:

• src/nat/cli/commands/workflow/workflow_commands.py
• src/nat/cli/commands/workflow/templates/config.yml.j2
• src/nat/cli/commands/workflow/templates/workflow.py.j2
• src/nat/cli/commands/workflow/templates/register.py.j2

{src/**/*.py,packages/*/src/**/*.py}

📄 CodeRabbit inference engine (.cursor/rules/general.mdc)

All public APIs must have Python 3.11+ type hints on parameters and return values; prefer typing/collections.abc abstractions; use typing.Annotated when useful

Files:

• src/nat/cli/commands/workflow/workflow_commands.py

**/*

⚙️ CodeRabbit configuration file

**/*: # Code Review Instructions

• Ensure the code follows best practices and coding standards. - For Python code, follow
  PEP 20 and
  PEP 8 for style guidelines.
• Check for security vulnerabilities and potential issues. - Python methods should use type hints for all parameters and return values.
  Example:

  def my_function(param1: int, param2: str) -> bool:
      pass

• For Python exception handling, ensure proper stack trace preservation:
  • When re-raising exceptions: use bare raise statements to maintain the original stack trace,
    and use logger.error() (not logger.exception()) to avoid duplicate stack trace output.
  • When catching and logging exceptions without re-raising: always use logger.exception()
    to capture the full stack trace information.

Documentation Review Instructions - Verify that documentation and comments are clear and comprehensive. - Verify that the documentation doesn't contain any TODOs, FIXMEs or placeholder text like "lorem ipsum". - Verify that the documentation doesn't contain any offensive or outdated terms. - Verify that documentation and comments are free of spelling mistakes, ensure the documentation doesn't contain any

words listed in the ci/vale/styles/config/vocabularies/nat/reject.txt file, words that might appear to be
spelling mistakes but are listed in the ci/vale/styles/config/vocabularies/nat/accept.txt file are OK.

Misc. - All code (except .mdc files that contain Cursor rules) should be licensed under the Apache License 2.0,

and should contain an Apache License 2.0 header comment at the top of each file.

• Confirm that copyright years are up-to date whenever a file is changed.

Files:

• src/nat/cli/commands/workflow/workflow_commands.py
• src/nat/cli/commands/workflow/templates/config.yml.j2
• src/nat/cli/commands/workflow/templates/workflow.py.j2
• src/nat/cli/commands/workflow/templates/register.py.j2

🔇 Additional comments (2)

src/nat/cli/commands/workflow/templates/register.py.j2 (1)

3-4: LGTM on the sanitized import path.

Thanks for aligning the registration import with the Python-safe workflow name—this avoids the hyphenated module pitfall.

src/nat/cli/commands/workflow/templates/config.yml.j2 (1)

13-28: Configuration updates look good.

The added function/tool and Nim LLM defaults align with the new ReAct workflow template.

[willkill07]

The only issue here is now users have no "simple" example of a Function 😅. I wonder if we could add a greet function which accepted a name and include that in the default config + code.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[zhongxuanwang-nv]

The only issue here is now users have no "simple" example of a Function 😅. I wonder if we could add a greet function which accepted a name and include that in the default config + code.

Thanks Will! I just implemented the echo function that does this :)

[zhongxuanwang-nv]

/ok to test e11dffd

[willkill07]

Sorry for another round of feedback. We just want to be super clear

[zhongxuanwang-nv]

/ok to test 7905f3c

[coderabbitai]

Actionable comments posted: 1

♻️ Duplicate comments (3)

src/nat/cli/commands/workflow/workflow_commands.py (1)

223-229: Consider aligning the generated filename with the function name.

The generated function is named {{ python_safe_workflow_name }}_function (as seen in workflow.py.j2 line 22), but the output file is named {python_safe_workflow_name}.py without the _function suffix. A previous review comment suggested matching the filename to the function name for clarity.

For consistency, consider this change:

-            'workflow.py.j2': base_dir / f'{python_safe_workflow_name}.py',
+            'workflow.py.j2': base_dir / f'{python_safe_workflow_name}_function.py',

Note: This is primarily a clarity improvement since imports go through __init__.py, so the actual filename doesn't affect functionality. Based on learnings

src/nat/cli/commands/workflow/templates/workflow.py.j2 (2)

1-2: Add required typing imports for return type annotation.

The async generator function on line 22 requires explicit return type hints per coding guidelines. Import the necessary types at the top of the file.

Apply this diff:

 import logging
+from collections.abc import AsyncIterator
+from typing import Any
 
 from pydantic import Field

As per coding guidelines

---

21-22: Add missing return type annotation.

The generated public function lacks a return type annotation, violating the coding guidelines requirement that all public APIs must have Python 3.11+ type hints on parameters and return values.

Apply this diff after adding the imports:

 @register_function(config_type={{ workflow_class_name }}, framework_wrappers=[LLMFrameworkEnum.LANGCHAIN])
-async def {{ python_safe_workflow_name }}_function(config: {{ workflow_class_name }}, builder: Builder):
+async def {{ python_safe_workflow_name }}_function(
+    config: {{ workflow_class_name }}, builder: Builder
+) -> AsyncIterator[Any]:

As per coding guidelines

🧹 Nitpick comments (1)

src/nat/cli/commands/workflow/templates/workflow.py.j2 (1)

24-32: Enhance template documentation to guide users.

The template would benefit from clearer inline documentation explaining the overall structure and how users should modify it. The current comments are minimal and a previous review suggested including more guidance about where function logic should go and what each part does.

Consider adding more comprehensive comments:

 @register_function(config_type={{ workflow_class_name }}, framework_wrappers=[LLMFrameworkEnum.LANGCHAIN])
 async def {{ python_safe_workflow_name }}_function(config: {{ workflow_class_name }}, builder: Builder):
-
+    """
+    Main workflow function that registers the tool/function with the builder.
+    
+    This template demonstrates a simple echo function. In a real workflow, you would:
+    1. Define helper functions that implement your business logic
+    2. Register them using FunctionInfo.from_fn() with appropriate descriptions
+    3. Optionally yield multiple functions if your workflow needs multiple tools
+    """
+
     async def _echo(text: str) -> str:
         """
-        This is the part where all the logic for the function goes.
+        Example tool function that echoes input text with a configurable prefix.
+        
+        Replace this with your own business logic. This function will be callable
+        by the agent/workflow as a tool.
+        
+        Args:
+            text: The input text to echo
+            
+        Returns:
+            The prefixed echo string
         """
         return f"{config.prefix} {text}"
 
-    # This is the part where the function is registered. The description parameter is used to describe the function.
+    # Register the function as a tool. The description helps the LLM understand when to use it.
     yield FunctionInfo.from_fn(
         _echo, description="This is a function that takes an input and echos back with a pre-defined prefix.")

Based on learnings

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e6d807c and 7905f3c.

📒 Files selected for processing (4)

• src/nat/cli/commands/workflow/templates/config.yml.j2 (1 hunks)
• src/nat/cli/commands/workflow/templates/register.py.j2 (1 hunks)
• src/nat/cli/commands/workflow/templates/workflow.py.j2 (2 hunks)
• src/nat/cli/commands/workflow/workflow_commands.py (2 hunks)

🚧 Files skipped from review as they are similar to previous changes (1)

• src/nat/cli/commands/workflow/templates/config.yml.j2

🧰 Additional context used

📓 Path-based instructions (6)

src/nat/**/*

📄 CodeRabbit inference engine (.cursor/rules/general.mdc)

Changes in src/nat should prioritize backward compatibility

Files:

• src/nat/cli/commands/workflow/templates/workflow.py.j2
• src/nat/cli/commands/workflow/templates/register.py.j2
• src/nat/cli/commands/workflow/workflow_commands.py

---

⚙️ CodeRabbit configuration file

This directory contains the core functionality of the toolkit. Changes should prioritize backward compatibility.

Files:

• src/nat/cli/commands/workflow/templates/workflow.py.j2
• src/nat/cli/commands/workflow/templates/register.py.j2
• src/nat/cli/commands/workflow/workflow_commands.py

**/*

⚙️ CodeRabbit configuration file

**/*: # Code Review Instructions

• Ensure the code follows best practices and coding standards. - For Python code, follow
  PEP 20 and
  PEP 8 for style guidelines.
• Check for security vulnerabilities and potential issues. - Python methods should use type hints for all parameters and return values.
  Example:

  def my_function(param1: int, param2: str) -> bool:
      pass

• For Python exception handling, ensure proper stack trace preservation:
  • When re-raising exceptions: use bare raise statements to maintain the original stack trace,
    and use logger.error() (not logger.exception()) to avoid duplicate stack trace output.
  • When catching and logging exceptions without re-raising: always use logger.exception()
    to capture the full stack trace information.

Documentation Review Instructions - Verify that documentation and comments are clear and comprehensive. - Verify that the documentation doesn't contain any TODOs, FIXMEs or placeholder text like "lorem ipsum". - Verify that the documentation doesn't contain any offensive or outdated terms. - Verify that documentation and comments are free of spelling mistakes, ensure the documentation doesn't contain any

words listed in the ci/vale/styles/config/vocabularies/nat/reject.txt file, words that might appear to be
spelling mistakes but are listed in the ci/vale/styles/config/vocabularies/nat/accept.txt file are OK.

Misc. - All code (except .mdc files that contain Cursor rules) should be licensed under the Apache License 2.0,

and should contain an Apache License 2.0 header comment at the top of each file.

• Confirm that copyright years are up-to date whenever a file is changed.

Files:

• src/nat/cli/commands/workflow/templates/workflow.py.j2
• src/nat/cli/commands/workflow/templates/register.py.j2
• src/nat/cli/commands/workflow/workflow_commands.py

**/*.{py,yaml,yml}

📄 CodeRabbit inference engine (.cursor/rules/nat-test-llm.mdc)

**/*.{py,yaml,yml}: Configure response_seq as a list of strings; values cycle per call, and [] yields an empty string.
Configure delay_ms to inject per-call artificial latency in milliseconds for nat_test_llm.

Files:

• src/nat/cli/commands/workflow/workflow_commands.py

**/*.py

📄 CodeRabbit inference engine (.cursor/rules/nat-test-llm.mdc)

**/*.py: Programmatic use: create TestLLMConfig(response_seq=[...], delay_ms=...), add with builder.add_llm("", cfg).
When retrieving the test LLM wrapper, use builder.get_llm(name, wrapper_type=LLMFrameworkEnum.) and call the framework’s method (e.g., ainvoke, achat, call).

**/*.py: In code comments/identifiers use NAT abbreviations as specified: nat for API namespace/CLI, nvidia-nat for package name, NAT for env var prefixes; do not use these abbreviations in documentation
Follow PEP 20 and PEP 8; run yapf with column_limit=120; use 4-space indentation; end files with a single trailing newline
Run ruff check --fix as linter (not formatter) using pyproject.toml config; fix warnings unless explicitly ignored
Respect naming: snake_case for functions/variables, PascalCase for classes, UPPER_CASE for constants
Treat pyright warnings as errors during development
Exception handling: use bare raise to re-raise; log with logger.error() when re-raising to avoid duplicate stack traces; use logger.exception() when catching without re-raising
Provide Google-style docstrings for every public module, class, function, and CLI command; first line concise and ending with a period; surround code entities with backticks
Validate and sanitize all user input, especially in web or CLI interfaces
Prefer httpx with SSL verification enabled by default and follow OWASP Top-10 recommendations
Use async/await for I/O-bound work; profile CPU-heavy paths with cProfile or mprof before optimizing; cache expensive computations with functools.lru_cache or external cache; leverage NumPy vectorized operations when beneficial

Files:

• src/nat/cli/commands/workflow/workflow_commands.py

src/**/*.py

📄 CodeRabbit inference engine (.cursor/rules/general.mdc)

All importable Python code must live under src/ (or packages//src/)

Files:

• src/nat/cli/commands/workflow/workflow_commands.py

{src/**/*.py,packages/*/src/**/*.py}

📄 CodeRabbit inference engine (.cursor/rules/general.mdc)

All public APIs must have Python 3.11+ type hints on parameters and return values; prefer typing/collections.abc abstractions; use typing.Annotated when useful

Files:

• src/nat/cli/commands/workflow/workflow_commands.py

🔇 Additional comments (5)

src/nat/cli/commands/workflow/workflow_commands.py (2)

223-223: LGTM: Python-safe name generation is correct.

The logic to replace hyphens with underscores properly creates valid Python identifiers from workflow names.

---

238-238: LGTM: Context variable addition is correct.

The python_safe_workflow_name is properly added to the template rendering context for use across all templates.

src/nat/cli/commands/workflow/templates/workflow.py.j2 (3)

18-18: LGTM: Prefix field addition provides a good configurable example.

The addition of a prefix field with a clear default value and description demonstrates configuration capabilities well for template users.

---

24-28: LGTM: Echo function is a clear, simple example.

The _echo helper function is properly typed and provides a straightforward example that users can understand and modify easily.

---

6-6: LGTM: Required import for framework wrapper specification.

The LLMFrameworkEnum import is necessary for the @register_function decorator's framework_wrappers parameter.