Merge remote-tracking branch 'upstream/release/1.4' into ak-per-user-a2a

AnuradhaKaruppiah · AnuradhaKaruppiah · commit 6aa1ed6a865a · 2025-12-18T08:24:03.000-08:00
diff --git a/.coderabbit.yaml b/.coderabbit.yaml
@@ -129,7 +129,7 @@ reviews:
           digit version (ex: `~=1.0`).
         - Not all packages contain Python code, if they do they should also contain their own set of tests, in a
           `tests/` directory at the same level as the `pyproject.toml` file.
-        - When adding a new package, that new package name (as defined in the `pyproject.toml` file) should 
+        - When adding a new package, that new package name (as defined in the `pyproject.toml` file) should
           be added as a dependency to the nvidia-nat-all package in `packages/nvidia_nat_all/pyproject.toml`
 
     - path: "tests/**/*.py"
@@ -142,6 +142,8 @@ reviews:
             @pytest.fixture(name="my_fixture")
             def fixture_my_fixture():
                 pass
+        - Do NOT add `@pytest.mark.asyncio` to any test. Async tests are automatically detected and run by the
+          async runner - the decorator is unnecessary clutter.
 
   auto_apply_labels: true
   suggested_labels: true
diff --git a/.cursor/rules/documentation/capitalization.mdc b/.cursor/rules/documentation/capitalization.mdc
@@ -1,5 +1,5 @@
 ---
-description: 
+description:
 globs: **/*.md
 alwaysApply: false
 ---
@@ -105,11 +105,14 @@ Don't capitalize:
 - **Commands**: Usually lowercase unless they're proper names
 
 ### Product Names
-- **Use official capitalization**: 
-  - NVIDIA NeMo Agent toolkit (first use)
-  - Agent toolkit (subsequent uses)
+- **Use official capitalization**:
+  - NVIDIA NeMo Agent toolkit (first use in body text)
+  - NVIDIA NeMo Agent Toolkit (first use in titles/headings where all words are capitalized)
+  - NeMo Agent toolkit or "the toolkit" (subsequent uses in body text)
+  - NeMo Agent Toolkit (subsequent uses in titles/headings)
   - CUDA, TensorRT, PyTorch
 - **Don't capitalize** generic terms: database, server, application (unless part of proper name)
+- **Never use** "NAT" or "nat" as an abbreviation for the toolkit in documentation
 
 ### Feature Names
 - **Capitalize** official feature names: Smart Search, Auto-Save, Real-time Analytics
@@ -136,7 +139,7 @@ Don't capitalize:
 - **Example**: "application programming interface" → "API"
 
 #### Version Numbers
-- **Follow product conventions**: 
+- **Follow product conventions**:
   - "version 2.1" (lowercase version)
   - "Python 3.9" (capitalize language name)
   - "CUDA 11.8" (follow product style)
diff --git a/.cursor/rules/documentation/general.mdc b/.cursor/rules/documentation/general.mdc
@@ -31,17 +31,23 @@ Follow these rules when working with any documentation in the NeMo Agent toolkit
 
 ### Terminology and Naming
 - Make sure to follow this naming convention for all the documentation. If there is any documentation not following this rule, you MUST update it.
-- **Full name on first use**: "NVIDIA NeMo Agent toolkit"
-- **Subsequent references**: "NeMo Agent toolkit"
-- **Abbreviations**: "NAT" or "nat"
-  - "nat" for the API namespace and CLI tool
-  - "nvidia-nat" for the package name
-  - "NAT" for environment variable prefixes, and informal usage in comments
-  - This should be used for all abbreviations in the comments in the code.
-  - This should NEVER be used in the documentation.
+- **Full name (first use)**: "NVIDIA NeMo Agent toolkit" — use for document titles, webpage headers, and any public descriptions
+- **Short name (subsequent references)**: "NeMo Agent toolkit" or "the toolkit"
+- **Capitalization rules**:
+  - In document titles, headings, or any context where all words are capitalized, use "Toolkit" (capital T): e.g., "NVIDIA NeMo Agent Toolkit" or "NeMo Agent Toolkit"
+  - In all other contexts (body text, descriptions), use "toolkit" (lowercase t): e.g., "NVIDIA NeMo Agent toolkit" or "NeMo Agent toolkit"
+- **Technical identifiers** (code, CLI, packages, URLs):
+  - `nat` for the API namespace and CLI tool
+  - `nvidia-nat` for the package name
+  - `NAT_` prefix for environment variables
+  - `NeMo-Agent-Toolkit` for URLs, directory names, and contexts where capitalization is preserved (no underscores or spaces)
+- **"NAT" abbreviation**:
+  - OK in code comments
+  - NEVER use "NAT" or "nat" to refer to the toolkit in documentation
 - Examples:
   - "In the NeMo Agent toolkit, you can…"
   - "Change directory to the NeMo Agent toolkit repo root…"
+  - Heading: "# Getting Started with NeMo Agent Toolkit"
 - Consistently use this terminology throughout all documentation
 - NeMo Agent toolkit was previously known as the Agent Intelligence toolkit, and AgentIQ. You should NEVER use the deprecated names, including Agent Intelligence toolkit, aiqtoolkit, AgentIQ, or AIQ/aiq. If you see any of these names in the documentation, you MUST update it based on the latest naming convention above, unless those names are intentionally used to refer to the deprecated names, or implementing a compatibility layer for the deprecated names.
 
diff --git a/.cursor/rules/documentation/punctuation.mdc b/.cursor/rules/documentation/punctuation.mdc
@@ -1,5 +1,5 @@
 ---
-description: 
+description:
 globs: **/*.md
 alwaysApply: false
 ---
@@ -32,6 +32,10 @@ Use apostrophes for:
 - Possessive form of "it" → use `its`
 - Possessive pronouns → `yours`, `theirs`
 - Plural nouns → `devices` not `device's`
+- Inanimate objects (use alternative phrasing instead)
+  - **Incorrect**: "NeMo Agent toolkit's evaluation system can be used..."
+  - **Correct**: "The NeMo Agent toolkit evaluation system can be used..."
+  - **Also correct**: "The evaluation system included in NeMo Agent toolkit can be used..."
 
 ### Brackets
 
@@ -121,7 +125,7 @@ Use apostrophes for:
   - `History is stained with blood spilled in the name of "civilization."`
 - **Colons and semicolons**: Always outside quotation marks
   - `Three elements of her "Olympic journey": family, commitment, coaching`
-- **Question marks and exclamation points**: 
+- **Question marks and exclamation points**:
   - Inside if they apply to the quotation
   - Outside if they apply to the whole sentence
 
diff --git a/.cursor/rules/general.mdc b/.cursor/rules/general.mdc
@@ -13,18 +13,23 @@ These are the overarching standards that every **source, test, documentation and
 ## Terminology and Naming
 
 - Make sure to follow this naming convention for all the documentation. If there is any documentation not following this rule, you MUST update it.
-- **Full name on first use**: "NVIDIA NeMo Agent toolkit"
-- **Subsequent references**: "NeMo Agent toolkit"
-  - If the name is part of a heading, use "NeMo Agent Toolkit" in the heading. Capitalize the "T" in "Toolkit".
-- **Abbreviations**: "NAT" or "nat"
-  - "nat" for the API namespace and CLI tool
-  - "nvidia-nat" for the package name
-  - "NAT" for environment variable prefixes, and informal usage in comments
-  - This should be used for all abbreviations in the comments in the code.
-  - This should NEVER be used in the documentation.
+- **Full name (first use)**: "NVIDIA NeMo Agent toolkit" — use for document titles, webpage headers, and any public descriptions
+- **Short name (subsequent references)**: "NeMo Agent toolkit" or "the toolkit"
+- **Capitalization rules**:
+  - In document titles, headings, or any context where all words are capitalized, use "Toolkit" (capital T): e.g., "NVIDIA NeMo Agent Toolkit" or "NeMo Agent Toolkit"
+  - In all other contexts (body text, descriptions), use "toolkit" (lowercase t): e.g., "NVIDIA NeMo Agent toolkit" or "NeMo Agent toolkit"
+- **Technical identifiers** (code, CLI, packages, URLs):
+  - `nat` for the API namespace and CLI tool
+  - `nvidia-nat` for the package name
+  - `NAT_` prefix for environment variables
+  - `NeMo-Agent-Toolkit` for URLs, directory names, and contexts where capitalization is preserved (no underscores or spaces)
+- **"NAT" abbreviation**:
+  - OK in code comments
+  - NEVER use "NAT" or "nat" to refer to the toolkit in documentation
 - Examples:
   - "In the NeMo Agent toolkit, you can…"
   - "Change directory to the NeMo Agent toolkit repo root…"
+  - Heading: "# Getting Started with NeMo Agent Toolkit"
 - Consistently use this terminology throughout all documentation
 - NeMo Agent toolkit was previously known as the Agent Intelligence toolkit, and AgentIQ. You should NEVER use the deprecated names, including Agent Intelligence toolkit, aiqtoolkit, AgentIQ, or AIQ/aiq. If you see any of these names in the documentation, you should update it based on the latest naming convention above, unless those names are intentionally used to refer to the deprecated names, or implementing a compatibility layer for the deprecated names.
 - DO NOT change the content of `CHANGELOG.md`
diff --git a/.cursor/rules/nat-tests/general.mdc b/.cursor/rules/nat-tests/general.mdc
@@ -26,6 +26,7 @@ All tests in NeMo Agent toolkit use pytest. See the general coding guidelines fo
 - Use `@pytest.fixture(name="fixture_name")` decorator pattern
 - Mock external services with `pytest_httpserver` or `unittest.mock`
 - Maintain ≥ 80% code coverage
+- Do NOT add `@pytest.mark.asyncio` to any test - async tests are automatically detected and run by the async runner
 
 ### Integration Tests
 
diff --git a/.cursor/rules/nat-tests/integration-tests.mdc b/.cursor/rules/nat-tests/integration-tests.mdc
@@ -175,6 +175,7 @@ Key practices:
 - Import third-party service libraries at module level in fixtures
 - Use function scope for service fixtures (use session scope)
 - Fail tests when services are unavailable (skip them instead)
+- Add `@pytest.mark.asyncio` decorator - async tests are automatically detected and run by the async runner
 
 ## Running Integration Tests
 
diff --git a/docs/source/get-started/tutorials/build-a-demo-agent-workflow-using-cursor-rules.md b/docs/source/get-started/tutorials/build-a-demo-agent-workflow-using-cursor-rules.md
@@ -28,10 +28,6 @@ Cursor rules in NeMo Agent toolkit act as an intelligent development that offers
 
 ## Common Prompts
 
-:::{note}
-For optimal Cursor rules experience, avoid using the `Auto` mode for LLM model selection. Instead, manually choose a model from the selection menu, such as `claude-4-sonnet`.
-:::
-
 The following are frequently used prompts to begin development:
 
 **Installing NeMo Agent Toolkit:**
diff --git a/src/nat/cli/commands/evaluate.py b/src/nat/cli/commands/evaluate.py
@@ -195,16 +195,19 @@ def process_nat_eval(
                                "have a partially completed dataset.")
 
     # Create the configuration object
-    config = EvaluationRunConfig(
-        config_file=config_file,
-        dataset=str(dataset) if dataset else None,
-        result_json_path=result_json_path,
-        skip_workflow=skip_workflow,
-        skip_completed_entries=skip_completed_entries,
-        endpoint=endpoint,
-        endpoint_timeout=endpoint_timeout,
-        reps=reps,
-        override=override,
-        user_id=user_id,
-    )
+    # Only include user_id if explicitly provided via CLI, otherwise use the default
+    config_kwargs = {
+        "config_file": config_file,
+        "dataset": str(dataset) if dataset else None,
+        "result_json_path": result_json_path,
+        "skip_workflow": skip_workflow,
+        "skip_completed_entries": skip_completed_entries,
+        "endpoint": endpoint,
+        "endpoint_timeout": endpoint_timeout,
+        "reps": reps,
+        "override": override,
+    }
+    if user_id is not None:
+        config_kwargs["user_id"] = user_id
+    config = EvaluationRunConfig(**config_kwargs)
     asyncio.run(run_and_evaluate(config))
diff --git a/src/nat/data_models/config.py b/src/nat/data_models/config.py
@@ -215,12 +215,6 @@ class GeneralConfig(BaseModel):
 
     telemetry: TelemetryConfig = TelemetryConfig()
 
-    default_user_id: str = Field(
-        default="default_user_id",
-        description="Default user ID for per-user workflows when "
-        "no session is available (for example, when using 'nat run'). This value identifies "
-        "the workflow instances. For multi-user deployments with 'nat serve', the 'nat-session' "
-        "cookie overrides this value. Must be a non-empty string when used as a fallback user ID.")
     per_user_workflow_timeout: timedelta = Field(
         default=timedelta(minutes=30),
         description="Time after which inactive per-user workflows are cleaned up. "
diff --git a/src/nat/eval/config.py b/src/nat/eval/config.py
@@ -46,8 +46,8 @@ class EvaluationRunConfig(BaseModel):
     num_passes: int = 0
     # timeout for waiting for trace export tasks to complete
     export_timeout: float = 60.0
-    # User ID to use for workflow session
-    user_id: str | None = None
+    # User ID to use for workflow session. Defaults to 'nat_eval_user_id'.
+    user_id: str = "nat_eval_user_id"
 
 
 class EvaluationRunOutput(BaseModel):
diff --git a/src/nat/front_ends/console/console_front_end_config.py b/src/nat/front_ends/console/console_front_end_config.py
@@ -30,4 +30,6 @@ class ConsoleFrontEndConfig(FrontEndBaseConfig, name="console"):
                                           description="A single input to submit the the workflow.")
     input_file: Path | None = Field(default=None,
                                     description="Path to a json file of inputs to submit to the workflow.")
-    user_id: str | None = Field(default=None, description="User ID to use for the workflow session.")
+    user_id: str = Field(default="nat_run_user_id",
+                         description="User ID to use for the workflow session. "
+                         "Defaults to 'nat_run_user_id' for single-user CLI execution.")
diff --git a/src/nat/runtime/session.py b/src/nat/runtime/session.py
@@ -438,17 +438,12 @@ async def session(self,
         builder_info: PerUserBuilderInfo | None = None
 
         if self._is_workflow_per_user:
-            # Resolve user_id: explicit param > context > default
+            # Resolve user_id: explicit param > context
             if user_id is None:
                 user_id = self._get_user_id_from_context()
-            if user_id is None:
-                user_id = self._config.general.default_user_id
-                if user_id:
-                    logger.info(f"Using default_user_id='{user_id}' for per-user workflow")
             if user_id is None:
                 raise ValueError("user_id is required for per-user workflow but could not be determined. "
-                                 "Ensure 'nat-session' cookie is set, pass user_id explicitly, or set "
-                                 "'general.default_user_id' in config.")
+                                 "Ensure 'nat-session' cookie is set or pass user_id explicitly.")
 
             # Get or create per-user builder
             logger.debug(f"Getting or creating per-user builder for user {user_id}")
diff --git a/tests/nat/runtime/test_session_manager.py b/tests/nat/runtime/test_session_manager.py
@@ -116,7 +116,6 @@ def create_mock_config(is_per_user: bool = False) -> Config:
     config.general = MagicMock(spec=GeneralConfig)
     config.general.per_user_workflow_timeout = timedelta(minutes=30)
     config.general.per_user_workflow_cleanup_interval = timedelta(minutes=5)
-    config.general.default_user_id = None
     config.workflow = MagicMock()
     return config
 
@@ -361,7 +360,7 @@ async def test_session_per_user_requires_user_id(self, mock_registry):
                             entry_function=None,
                             shared_workflow=None)
 
-        with pytest.raises(ValueError, match="user_id is required for per-user workflow"):
+        with pytest.raises(ValueError, match="user_id is required for per-user workflow but could not be determined"):
             async with sm.session():
                 pass
 
