nvidia-nat 1.4.0a20251023__py3-none-any.whl → 1.4.0a20251024__py3-none-any.whl

nat/data_models/optimizable.py

@@ -18,6 +18,7 @@ from typing import Any
 from typing import Generic
 from typing import TypeVar
 
+import numpy as np
 from optuna import Trial
 from pydantic import BaseModel
 from pydantic import ConfigDict
@@ -45,13 +46,34 @@ class SearchSpace(BaseModel, Generic[T]):
 
     @model_validator(mode="after")
     def validate_search_space_parameters(self):
-        """Validate that either values is provided, or both high and low."""
+        """Validate SearchSpace configuration."""
+        # 1. Prompt-specific validation
+        if self.is_prompt:
+            # When optimizing prompts, numeric parameters don't make sense
+            if self.low is not None or self.high is not None:
+                raise ValueError("SearchSpace with 'is_prompt=True' cannot have 'low' or 'high' parameters")
+            if self.log:
+                raise ValueError("SearchSpace with 'is_prompt=True' cannot have 'log=True'")
+            if self.step is not None:
+                raise ValueError("SearchSpace with 'is_prompt=True' cannot have 'step' parameter")
+            return self
+
+        # 2. Values-based validation
         if self.values is not None:
             # If values is provided, we don't need high/low
             if self.high is not None or self.low is not None:
                 raise ValueError("SearchSpace 'values' is mutually exclusive with 'high' and 'low'")
+            # Ensure values is not empty
+            if len(self.values) == 0:
+                raise ValueError("SearchSpace 'values' must not be empty")
             return self
 
+        # 3. Range-based validation
+        if (self.low is None) != (self.high is None):  # XOR using !=
+            raise ValueError(f"SearchSpace range requires both 'low' and 'high'; got low={self.low}, high={self.high}")
+        if self.low is not None and self.high is not None and self.low >= self.high:
+            raise ValueError(f"SearchSpace 'low' must be less than 'high'; got low={self.low}, high={self.high}")
+
         return self
 
     # Helper for Optuna Trials
@@ -65,6 +87,72 @@ class SearchSpace(BaseModel, Generic[T]):
             return trial.suggest_int(name, self.low, self.high, log=self.log, step=self.step)
         return trial.suggest_float(name, self.low, self.high, log=self.log, step=self.step)
 
+    def to_grid_values(self) -> list[Any]:
+        """
+        Convert SearchSpace to a list of values for GridSampler.
+
+        Grid search requires explicit values. This can be provided in two ways:
+        1. Explicit values: SearchSpace(values=[0.1, 0.5, 0.9])
+        2. Range with step: SearchSpace(low=0.1, high=0.9, step=0.2)
+
+        For ranges, step is required (no default will be applied) to avoid
+        unintentional combinatorial explosion.
+        """
+
+        if self.is_prompt:
+            raise ValueError("Prompt optimization not currently supported using Optuna. "
+                             "Use the genetic algorithm implementation instead.")
+
+        # Option 1: Explicit values provided
+        if self.values is not None:
+            return list(self.values)
+
+        # Option 2: Range with required step
+        if self.low is None or self.high is None:
+            raise ValueError("Grid search requires either 'values' or both 'low' and 'high' to be defined")
+
+        if self.step is None:
+            raise ValueError(
+                f"Grid search with range (low={self.low}, high={self.high}) requires 'step' to be specified. "
+                "Please define the step size to discretize the range, for example: step=0.1")
+
+        # Validate step is positive
+        step_float = float(self.step)
+        if step_float <= 0:
+            raise ValueError(f"Grid search step must be positive; got step={self.step}")
+
+        # Generate grid values from range with step
+        # Use integer range only if low, high, and step are all integral
+        if (isinstance(self.low, int) and isinstance(self.high, int) and step_float.is_integer()):
+            step = int(step_float)
+
+            if self.log:
+                raise ValueError("Log scale is not supported for integer ranges in grid search. "
+                                 "Please use linear scale or provide explicit values.")
+            values = list(range(self.low, self.high + 1, step))
+            if values and values[-1] != self.high:
+                values.append(self.high)
+            return values
+
+        # Float range (including integer low/high with float step)
+        low_val = float(self.low)
+        high_val = float(self.high)
+        step_val = step_float
+
+        if self.log:
+            raise ValueError("Log scale is not yet supported for grid search with ranges. "
+                             "Please provide explicit values using the 'values' field.")
+
+        # Use arange to respect step size
+        values = np.arange(low_val, high_val, step_val).tolist()
+
+        # Always include the high endpoint if not already present (within tolerance)
+        # This ensures the full range is explored in grid search
+        if not values or abs(values[-1] - high_val) > 1e-9:
+            values.append(high_val)
+
+        return values
+
 
 def OptimizableField(
     default: Any = PydanticUndefined,

nat/data_models/optimizer.py

@@ -13,6 +13,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+from enum import Enum
 from pathlib import Path
 
 from pydantic import BaseModel
@@ -28,12 +29,23 @@ class OptimizerMetric(BaseModel):
     weight: float = Field(description="Weight of the metric in the optimization process.", default=1.0)
 
 
+class SamplerType(str, Enum):
+    BAYESIAN = "bayesian"
+    GRID = "grid"
+
+
 class NumericOptimizationConfig(BaseModel):
     """
     Configuration for numeric/enum optimization (Optuna).
     """
     enabled: bool = Field(default=True, description="Enable numeric optimization")
     n_trials: int = Field(description="Number of trials for numeric optimization.", default=20)
+    sampler: SamplerType | None = Field(
+        default=None,
+        description="Sampling strategy for numeric optimization. Options: None or 'bayesian' uses \
+            the Optuna default (TPE for single-objective, NSGA-II for multi-objective) or 'grid' performs \
+            exhaustive grid search over parameter combinations. Defaults to None.",
+    )
 
 
 class PromptGAOptimizationConfig(BaseModel):

nat/front_ends/mcp/mcp_front_end_config.py

@@ -37,8 +37,11 @@ class MCPFrontEndConfig(FrontEndBaseConfig, name="mcp"):
     port: int = Field(default=9901, description="Port to bind the server to (default: 9901)", ge=0, le=65535)
     debug: bool = Field(default=False, description="Enable debug mode (default: False)")
     log_level: str = Field(default="INFO", description="Log level for the MCP server (default: INFO)")
-    tool_names: list[str] = Field(default_factory=list,
-                                  description="The list of tools MCP server will expose (default: all tools)")
+    tool_names: list[str] = Field(
+        default_factory=list,
+        description="The list of tools MCP server will expose (default: all tools)."
+        "Tool names can be functions or function groups",
+    )
     transport: Literal["sse", "streamable-http"] = Field(
         default="streamable-http",
         description="Transport type for the MCP server (default: streamable-http, backwards compatible with sse)")

nat/front_ends/mcp/mcp_front_end_plugin_worker.py

@@ -251,6 +251,10 @@ class MCPFrontEndPluginWorker(MCPFrontEndPluginWorkerBase):
             filtered_functions: dict[str, Function] = {}
             for function_name, function in functions.items():
                 if function_name in self.front_end_config.tool_names:
+                    # Treat current tool_names as function names, so check if the function name is in the list
+                    filtered_functions[function_name] = function
+                elif any(function_name.startswith(f"{group_name}.") for group_name in self.front_end_config.tool_names):
+                    # Treat tool_names as function group names, so check if the function name starts with the group name
                     filtered_functions[function_name] = function
                 else:
                     logger.debug("Skipping function %s as it's not in tool_names", function_name)

nat/profiler/parameter_optimization/parameter_optimizer.py

@@ -24,6 +24,7 @@ from nat.data_models.config import Config
 from nat.data_models.optimizable import SearchSpace
 from nat.data_models.optimizer import OptimizerConfig
 from nat.data_models.optimizer import OptimizerRunConfig
+from nat.data_models.optimizer import SamplerType
 from nat.eval.evaluate import EvaluationRun
 from nat.eval.evaluate import EvaluationRunConfig
 from nat.experimental.decorators.experimental_warning_decorator import experimental
@@ -59,7 +60,21 @@ def optimize_parameters(
     eval_metrics = [v.evaluator_name for v in metric_cfg.values()]
     weights = [v.weight for v in metric_cfg.values()]
 
-    study = optuna.create_study(directions=directions)
+    # Create appropriate sampler based on configuration
+    sampler_type = optimizer_config.numeric.sampler
+
+    if sampler_type == SamplerType.GRID:
+        # For grid search, convert the existing space to value sequences
+        grid_search_space = {param_name: search_space.to_grid_values() for param_name, search_space in space.items()}
+        sampler = optuna.samplers.GridSampler(grid_search_space)
+        logger.info("Using Grid sampler for numeric optimization")
+    else:
+        # None or BAYESIAN: let Optuna choose defaults
+        sampler = None
+        logger.info(
+            "Using Optuna default sampler types: TPESampler for single-objective, NSGAIISampler for multi-objective")
+
+    study = optuna.create_study(directions=directions, sampler=sampler)
 
     # Create output directory for intermediate files
     out_dir = optimizer_config.output_path

nat/utils/__init__.py

@@ -0,0 +1,72 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025, 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.
+
+import typing
+from pathlib import Path
+
+if typing.TYPE_CHECKING:
+
+    from nat.data_models.config import Config
+
+    from .type_utils import StrPath
+
+_T = typing.TypeVar("_T")
+
+
+async def run_workflow(*,
+                       config: "Config | None" = None,
+                       config_file: "StrPath | None" = None,
+                       prompt: str,
+                       to_type: type[_T] = str) -> _T:
+    """
+    Wrapper to run a workflow given either a config or a config file path and a prompt, returning the result in the
+    type specified by the `to_type`.
+
+    Parameters
+    ----------
+    config : Config | None
+        The configuration object to use for the workflow. If None, config_file must be provided.
+    config_file : StrPath | None
+        The path to the configuration file. If None, config must be provided. Can be either a str or a Path object.
+    prompt : str
+        The prompt to run the workflow with.
+    to_type : type[_T]
+        The type to convert the result to. Default is str.
+
+    Returns
+    -------
+    _T
+        The result of the workflow converted to the specified type.
+    """
+    from nat.builder.workflow_builder import WorkflowBuilder
+    from nat.runtime.loader import load_config
+    from nat.runtime.session import SessionManager
+
+    if config is not None and config_file is not None:
+        raise ValueError("Only one of config or config_file should be provided")
+
+    if config is None:
+        if config_file is None:
+            raise ValueError("Either config_file or config must be provided")
+
+        if not Path(config_file).exists():
+            raise ValueError(f"Config file {config_file} does not exist")
+
+        config = load_config(config_file)
+
+    async with WorkflowBuilder.from_config(config=config) as workflow_builder:
+        workflow = SessionManager(await workflow_builder.build())
+        async with workflow.run(prompt) as runner:
+            return await runner.result(to_type=to_type)

{nvidia_nat-1.4.0a20251023.dist-info → nvidia_nat-1.4.0a20251024.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nvidia-nat
-Version: 1.4.0a20251023
+Version: 1.4.0a20251024
 Summary: NVIDIA NeMo Agent toolkit
 Author: NVIDIA Corporation
 Maintainer: NVIDIA Corporation

{nvidia_nat-1.4.0a20251023.dist-info → nvidia_nat-1.4.0a20251024.dist-info}/RECORD

@@ -137,8 +137,8 @@ nat/data_models/logging.py,sha256=1QtVjIQ99PgMYUuzw4h1FAoPRteZY7uf3oFTqV3ONgA,94
 nat/data_models/memory.py,sha256=IKwe7CflCto30j4yI5yQtq8DXfMilAJ17S5NcsSDrOQ,1052
 nat/data_models/object_store.py,sha256=S8YY6i8ALgRPuggUI1FCG-xbvwPWuaCg1lJnZOx5scM,1515
 nat/data_models/openai_mcp.py,sha256=UkAalZE0my8a_sq-GynjsfDoSOw2NWLNZM9hcV23TzY,1911
-nat/data_models/optimizable.py,sha256=hhBd2msp-Q8b__tHGizy5saLgGB_oyeQ6LTvgjfRBP0,4925
-nat/data_models/optimizer.py,sha256=Zs4-w_Ek08iSLulsbb-4c1gK8zQB67UeRK1gHoqS1X4,5291
+nat/data_models/optimizable.py,sha256=dG9YGM6MwAReLXimk31CzzOlbknGwsk0znfAiDuOeuI,8981
+nat/data_models/optimizer.py,sha256=kKj74zYBjoTV51owkIHqfPefzXFY2OwB93OCORwJCOQ,5750
 nat/data_models/profiler.py,sha256=z3IlEhj-veB4Yz85271bTkScSUkVwK50tR3dwlDRgcE,1781
 nat/data_models/registry_handler.py,sha256=g1rFaz4uSydMJn7qpdX-DNHJd_rNf8tXYN49dLDYHPo,968
 nat/data_models/retriever.py,sha256=IJAIaeEXM8zj_towrvZ30Uoxt8e4WvOXrQwqGloS1qI,1202
@@ -262,9 +262,9 @@ nat/front_ends/fastapi/html_snippets/__init__.py,sha256=GUJrgGtpvyMUCjUBvR3faAdv
 nat/front_ends/fastapi/html_snippets/auth_code_grant_success.py,sha256=BNpWwzmA58UM0GK4kZXG4PHJy_5K9ihaVHu8SgCs5JA,1131
 nat/front_ends/mcp/__init__.py,sha256=Xs1JQ16L9btwreh4pdGKwskffAw1YFO48jKrU4ib_7c,685
 nat/front_ends/mcp/introspection_token_verifier.py,sha256=s7Q4Q6rWZJ0ZVujSxxpvVI6Bnhkg1LJQ3RLkvhzFIGE,2836
-nat/front_ends/mcp/mcp_front_end_config.py,sha256=Wk06mDRt4MiZzmwJM1vcG_ddHJtDTgWM9bhWXa3xGig,4872
+nat/front_ends/mcp/mcp_front_end_config.py,sha256=dnNsf487XZtoipU3DcmCAZ9eqtyF5a2p_1huQ_4uwPI,4919
 nat/front_ends/mcp/mcp_front_end_plugin.py,sha256=4u_kpen_T-_Uh62V5M7dfW9KyzbqXI7tGBG4AxJXWm0,5231
-nat/front_ends/mcp/mcp_front_end_plugin_worker.py,sha256=NUYu2FFrHat_U4VBAm3c9YMpWSyVr2pKUYyseSFw2pM,11208
+nat/front_ends/mcp/mcp_front_end_plugin_worker.py,sha256=IuwCcrBYmN6hyVra5vnwVVEjCuj2YO9ZUs-mhJnNNSQ,11626
 nat/front_ends/mcp/memory_profiler.py,sha256=OpcpLBAGCdQwYSFZbtAqdfncrnGYVjDcMpWydB71hjY,12811
 nat/front_ends/mcp/register.py,sha256=3aJtgG5VaiqujoeU1-Eq7Hl5pWslIlIwGFU2ASLTXgM,1173
 nat/front_ends/mcp/tool_converter.py,sha256=14NweQN3cPFBw7ZNiGyUHO4VhMGHrtfLGgvu4_H38oU,12426
@@ -371,7 +371,7 @@ nat/profiler/inference_optimization/experimental/prefix_span_analysis.py,sha256=
 nat/profiler/parameter_optimization/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nat/profiler/parameter_optimization/optimizable_utils.py,sha256=93Pl8A14Zq_f3XsxSH-yFnEJ6B7W5hp7doPnPoLlRB4,3714
 nat/profiler/parameter_optimization/optimizer_runtime.py,sha256=rXmCOq81o7ZorQOUYociVjuO3NO9CIjFBbwql2u_4H4,2715
-nat/profiler/parameter_optimization/parameter_optimizer.py,sha256=LA2gTBTuezWg5tdqyPA2VjIPkXylgwU9EHpVyaQqBxM,6951
+nat/profiler/parameter_optimization/parameter_optimizer.py,sha256=vxUvso4RnSwoUF5rJkJJGaIOJojebrvYcA79WA0ZP7c,7719
 nat/profiler/parameter_optimization/parameter_selection.py,sha256=pfnNQIx1evNICgChsOJXIFQHoL1R_kmh_vNDsVMC9kg,3982
 nat/profiler/parameter_optimization/pareto_visualizer.py,sha256=QclLZmmsWINIAh4n0XAKmnIZOqGHTMr-iggZS0kxj-Y,17055
 nat/profiler/parameter_optimization/prompt_optimizer.py,sha256=_AmdeB1jRamd93qR5UqRy5LweYR3bjnD7zoLxzXYE0k,17658
@@ -441,7 +441,7 @@ nat/tool/memory_tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3h
 nat/tool/memory_tools/add_memory_tool.py,sha256=N400PPvI37NUCMh5KcuoAL8khK8ecUQyfenahfjzbHQ,3368
 nat/tool/memory_tools/delete_memory_tool.py,sha256=zMllkpC0of9qFPNuG9vkVOoydRblOViCQf0uSbqz0sE,2461
 nat/tool/memory_tools/get_memory_tool.py,sha256=fcW6QE7bMZrpNK62et3sTw_QZ8cV9lXfEuDsm1-05bE,2768
-nat/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+nat/utils/__init__.py,sha256=WRO5RDryn6mChA2gwDVERclaei7LGPwrEMCUSliZI7k,2653
 nat/utils/callable_utils.py,sha256=EIao6NhHRFEoBqYRC7aWoFqhlr2LeFT0XK-ac0coF9E,2475
 nat/utils/debugging_utils.py,sha256=6M4JhbHDNDnfmSRGmHvT5IgEeWSHBore3VngdE_PMqc,1332
 nat/utils/decorators.py,sha256=AoMip9zmqrZm5wovZQytNvzFfIlS3PQxSYcgYeoLhxA,8240
@@ -475,10 +475,10 @@ nat/utils/reactive/base/observer_base.py,sha256=6BiQfx26EMumotJ3KoVcdmFBYR_fnAss
 nat/utils/reactive/base/subject_base.py,sha256=UQOxlkZTIeeyYmG5qLtDpNf_63Y7p-doEeUA08_R8ME,2521
 nat/utils/settings/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nat/utils/settings/global_settings.py,sha256=9JaO6pxKT_Pjw6rxJRsRlFCXdVKCl_xUKU2QHZQWWNM,7294
-nvidia_nat-1.4.0a20251023.dist-info/licenses/LICENSE-3rd-party.txt,sha256=fOk5jMmCX9YoKWyYzTtfgl-SUy477audFC5hNY4oP7Q,284609
-nvidia_nat-1.4.0a20251023.dist-info/licenses/LICENSE.md,sha256=QwcOLU5TJoTeUhuIXzhdCEEDDvorGiC6-3YTOl4TecE,11356
-nvidia_nat-1.4.0a20251023.dist-info/METADATA,sha256=MMZ-DFHfnYlCQnt2lGODZr64QXxzis2i-Dz6skRoTtM,10248
-nvidia_nat-1.4.0a20251023.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-nvidia_nat-1.4.0a20251023.dist-info/entry_points.txt,sha256=4jCqjyETMpyoWbCBf4GalZU8I_wbstpzwQNezdAVbbo,698
-nvidia_nat-1.4.0a20251023.dist-info/top_level.txt,sha256=lgJWLkigiVZuZ_O1nxVnD_ziYBwgpE2OStdaCduMEGc,8
-nvidia_nat-1.4.0a20251023.dist-info/RECORD,,
+nvidia_nat-1.4.0a20251024.dist-info/licenses/LICENSE-3rd-party.txt,sha256=fOk5jMmCX9YoKWyYzTtfgl-SUy477audFC5hNY4oP7Q,284609
+nvidia_nat-1.4.0a20251024.dist-info/licenses/LICENSE.md,sha256=QwcOLU5TJoTeUhuIXzhdCEEDDvorGiC6-3YTOl4TecE,11356
+nvidia_nat-1.4.0a20251024.dist-info/METADATA,sha256=GpP4M0PgVcHAhPCR9BR5TN7UpPUHZ9KqZbLv3TiVuMk,10248
+nvidia_nat-1.4.0a20251024.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+nvidia_nat-1.4.0a20251024.dist-info/entry_points.txt,sha256=4jCqjyETMpyoWbCBf4GalZU8I_wbstpzwQNezdAVbbo,698
+nvidia_nat-1.4.0a20251024.dist-info/top_level.txt,sha256=lgJWLkigiVZuZ_O1nxVnD_ziYBwgpE2OStdaCduMEGc,8
+nvidia_nat-1.4.0a20251024.dist-info/RECORD,,