nemo-platform 0.1.0__py3-none-any.whl

calculator_agent/calculator-agent.yml

@@ -0,0 +1,44 @@
+# calculator-agent.yml
+#
+# A ReAct agent with a calculator and datetime tool.
+#
+# The ``calculator`` function group matches NeMo-Agent-Toolkit's simple_calculator
+# example (add/subtract/multiply/divide/compare). Install the sibling package so NAT
+# loads its ``nat.components`` entry point:
+#
+#   uv pip install -e plugins/nemo-agents/examples/calculator-agent
+#
+# Platform-managed deployment:
+#   nemo agents create --name calculator-agent \
+#     --agent-config plugins/nemo-agents/examples/calculator-agent/src/calculator_agent/calculator-agent.yml
+#   nemo agents deploy  --agent calculator-agent
+#   nemo agents invoke  --agent calculator-agent --input "What is 12 * 8?"
+
+function_groups:
+  calculator:
+    _type: calculator            # requires nemo-agents-example-calculator (pip install this dir)
+
+functions:
+  current_datetime:
+    _type: current_datetime
+
+llms:
+  llm:
+    _type: openai
+    # base_url is injected by the platform controller at deploy time.
+    # For local runs, override: --override llms.llm.base_url https://integrate.api.nvidia.com/v1
+    api_key: not-used
+    model_name: ${NEMO_DEFAULT_MODEL}
+    temperature: 0.0
+
+workflow:
+  _type: react_agent
+  tool_names: [calculator, current_datetime]
+  llm_name: llm
+  verbose: false
+  parse_agent_response_max_retries: 3
+  # Use the LLM's native tool-calling API (bind_tools) instead of NAT's text-mode
+  # ReAct regex parser. The text parser in nvidia-nat-core>=1.7 rejects tool-call
+  # output where JSON args are followed by trailing prose (e.g. Nemotron-3 emits
+  # `{"numbers":[50,35]}\n\nThen we get ...`).
+  use_native_tool_calling: true

calculator_agent/calculator-eval-data.json

@@ -0,0 +1,17 @@
+[
+    {
+        "id": 1,
+        "question": "What is the product of 3 and 7, and is it greater than the current hour?",
+        "answer": "Answer must contain the product of 3 and 7 (21) and a comparison to the current hour"
+    },
+    {
+        "id": 2,
+        "question": "Is the sum of 12 and 8 greater than the current day of the week in number form?",
+        "answer": "Answer must contain the sum of 12 and 8 (20) and a comparison to the current day of the week"
+    },
+    {
+        "id": 3,
+        "question": "What is the difference between 50 and 35, and is it smaller than the current minute of the hour?",
+        "answer": "Answer must contain the difference between 50 and 35 (15) and a comparison to the current minute"
+    }
+]

calculator_agent/calculator-eval.yml

@@ -0,0 +1,61 @@
+# calculator-eval.yml
+#
+# Evaluation config for the calculator agent.
+#
+# This config only contains the eval section — not the agent workflow.
+# The agent runs remotely (already deployed), and its endpoint is passed via
+# the CLI:
+#
+#   nemo agents evaluate run \
+#       --eval-config examples/calculator-agent/calculator-eval.yml \
+#       --endpoint http://localhost:8080/generate
+#
+# Or, if the agent is platform-managed:
+#
+#   nemo agents evaluate run \
+#       --eval-config examples/calculator-agent/calculator-eval.yml \
+#       --agent calculator-agent
+#
+# The judge LLM evaluates the agent's answers against the expected answers in
+# calculator-eval-data.json.  Set base_url to your inference endpoint.
+
+llms:
+  judge_llm:
+    _type: openai
+    # base_url and api_key are injected automatically by the platform
+    # (routes through the Inference Gateway).  For local runs without the
+    # platform, override via --base-url or NEMO_BASE_URL.
+    #
+    # ${NEMO_DEFAULT_MODEL} resolves to the model configured on the SDK
+    # context (``nemo_platform.config.get_context().default_model``) so the
+    # example works against whichever model your platform has registered as
+    # a VirtualModel.  To pin a different judge, replace this with a
+    # specific entity name (see `nemo inference virtual-models list
+    # --workspace <ws>`).
+    model_name: ${NEMO_DEFAULT_MODEL}
+    temperature: 0.0
+    max_tokens: 1024
+
+eval:
+  general:
+    max_concurrency: 1
+    output_dir: eval/calculator
+    dataset:
+      _type: json
+      file_path: calculator-eval-data.json
+  evaluators:
+    accuracy:
+      _type: tunable_rag_evaluator
+      llm_name: judge_llm
+      default_scoring: true
+      default_score_weights:
+        coverage: 0.5
+        correctness: 0.3
+        relevance: 0.2
+      judge_llm_prompt: >
+        You are an evaluator. Score whether the generated answer correctly
+        addresses the question compared to the expected answer description.
+        Rules:
+        - Score is a float between 0.0 and 1.0.
+        - 1.0 means the answer fully satisfies the expected answer criteria.
+        - Provide a 1-2 sentence reasoning.

calculator_agent/calculator-optimize.yml

@@ -0,0 +1,110 @@
+# calculator-optimize.yml
+#
+# Optimization config for the calculator agent.
+#
+# This config tunes the agent's LLM hyperparameters (temperature, top_p) using
+# Optuna-based numeric optimization to maximise eval accuracy.  The eval section
+# reuses the same dataset and judge LLM as calculator-eval.yml.
+#
+# Usage:
+#
+#   nemo agents optimize run \
+#       --optimize-config examples/calculator-agent/calculator-optimize.yml \
+#       --agent calculator-agent
+#
+# A literal HTTP URL is still accepted for non-platform agent servers, but
+# the parameter sweep is local-only in that mode and won't reach the remote
+# agent — prefer the named-agent form whenever the agent is platform-managed:
+#
+#   nemo agents optimize run \
+#       --optimize-config examples/calculator-agent/calculator-optimize.yml \
+#       --agent http://localhost:8080
+#
+# See the NAT Optimizer Guide for full documentation on search spaces,
+# prompt GA, and multi-objective tuning:
+#   https://docs.nvidia.com/nemo/agent-toolkit/latest/improve-workflows/optimizer.html
+
+llms:
+  # LLM used by the agent workflow — its hyperparameters are optimised.
+  # base_url and api_key are injected automatically by the platform
+  # (routes through the Inference Gateway).  For local runs without the
+  # platform, override via --base-url or NEMO_BASE_URL.
+  #
+  # ${NEMO_DEFAULT_MODEL} resolves to the model configured on the SDK
+  # context (``nemo_platform.config.get_context().default_model``) so the
+  # example works against whichever model your platform has registered as
+  # a VirtualModel.  To pin a specific model, replace this with the entity
+  # name (see `nemo inference virtual-models list --workspace <ws>`).
+  llm:
+    _type: openai
+    model_name: ${NEMO_DEFAULT_MODEL}
+    temperature: 0.0
+    # Mark temperature and top_p as optimizable so the optimizer tunes them.
+    optimizable_params:
+      - temperature
+      - top_p
+    search_space:
+      temperature:
+        low: 0.0
+        high: 0.8
+        step: 0.2
+      top_p:
+        low: 0.5
+        high: 1.0
+        step: 0.1
+
+  # Judge LLM used by the evaluator — not optimised.
+  judge_llm:
+    _type: openai
+    model_name: ${NEMO_DEFAULT_MODEL}
+    temperature: 0.0
+    max_tokens: 1024
+
+# Evaluation section — used by the optimizer to score each trial.
+eval:
+  general:
+    max_concurrency: 4
+    output_dir: eval/calculator
+    dataset:
+      _type: json
+      file_path: calculator-eval-data.json
+  evaluators:
+    accuracy:
+      _type: tunable_rag_evaluator
+      llm_name: judge_llm
+      default_scoring: true
+      default_score_weights:
+        coverage: 0.5
+        correctness: 0.3
+        relevance: 0.2
+      judge_llm_prompt: >
+        You are an evaluator. Score whether the generated answer correctly
+        addresses the question compared to the expected answer description.
+        Rules:
+        - Score is a float between 0.0 and 1.0.
+        - 1.0 means the answer fully satisfies the expected answer criteria.
+        - Provide a 1-2 sentence reasoning.
+
+# Optimizer section — controls the tuning strategy.
+optimizer:
+  output_path: optimizer_results/calculator
+
+  # Numeric (Optuna) hyperparameter search over temperature and top_p.
+  numeric:
+    enabled: true
+    n_trials: 3
+
+  # Prompt GA is disabled for this example; enable and add
+  # prompt-type search spaces to optimise system prompts.
+  prompt:
+    enabled: false
+
+  # Run the workflow 3 times per parameter set for stable scoring.
+  reps_per_param_set: 3
+
+  # Metrics the optimizer tries to maximise / minimise.
+  eval_metrics:
+    accuracy:
+      evaluator_name: accuracy
+      direction: maximize
+      weight: 1.0

calculator_agent/register.py

@@ -0,0 +1,86 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Vendored from NeMo-Agent-Toolkit:
+# examples/getting_started/simple_calculator/src/nat_simple_calculator/register.py
+# Install this package (``uv pip install -e plugins/nemo-agents/examples/calculator-agent``)
+# so NAT discovers the ``nat.components`` entry point and ``_type: calculator`` works.
+
+from collections.abc import AsyncGenerator
+
+from nat.builder.builder import Builder  # type: ignore
+from nat.builder.function import FunctionGroup  # type: ignore
+from nat.cli.register_workflow import register_function_group  # type: ignore
+from nat.data_models.function import FunctionGroupBaseConfig  # type: ignore
+from pydantic import Field
+
+
+class CalculatorToolConfig(FunctionGroupBaseConfig, name="calculator"):
+    include: list[str] = Field(
+        default_factory=lambda: ["add", "subtract", "multiply", "divide", "compare"],
+        description="The list of functions to include in the calculator function group.",
+    )
+
+
+@register_function_group(config_type=CalculatorToolConfig)
+async def calculator(_config: CalculatorToolConfig, _builder: Builder) -> AsyncGenerator[FunctionGroup, None]:
+    """Create and register the calculator function group.
+
+    Args:
+        _config: Calculator function group configuration (unused).
+        _builder: Workflow builder (unused).
+
+    Yields:
+        FunctionGroup: The configured calculator function group with add, subtract,
+        multiply, divide, and compare operations.
+    """
+    import math
+
+    group = FunctionGroup(config=_config)
+
+    async def _add(numbers: list[float]) -> float:
+        """Add two or more numbers together."""
+        if len(numbers) < 2:
+            raise ValueError("This tool only supports addition between two or more numbers.")
+        return sum(numbers)
+
+    async def _subtract(numbers: list[float]) -> float:
+        """Subtract one number from another."""
+        if len(numbers) != 2:
+            raise ValueError("This tool only supports subtraction between two numbers.")
+        a, b = numbers
+        return a - b
+
+    async def _multiply(numbers: list[float]) -> float:
+        """Multiply two or more numbers together."""
+        if len(numbers) < 2:
+            raise ValueError("This tool only supports multiplication between two or more numbers.")
+        return math.prod(numbers)
+
+    async def _divide(numbers: list[float]) -> float:
+        """Divide one number by another."""
+        if len(numbers) != 2:
+            raise ValueError("This tool only supports division between two numbers.")
+        a, b = numbers
+        if b == 0:
+            raise ValueError("Cannot divide by zero.")
+        return a / b
+
+    async def _compare(numbers: list[float]) -> str:
+        """Compare two numbers."""
+        if len(numbers) != 2:
+            raise ValueError("This tool only supports comparison between two numbers.")
+        a, b = numbers
+        if a > b:
+            return f"{a} is greater than {b}"
+        if a < b:
+            return f"{a} is less than {b}"
+        return f"{a} is equal to {b}"
+
+    group.add_function(name="add", fn=_add, description=_add.__doc__)
+    group.add_function(name="subtract", fn=_subtract, description=_subtract.__doc__)
+    group.add_function(name="multiply", fn=_multiply, description=_multiply.__doc__)
+    group.add_function(name="divide", fn=_divide, description=_divide.__doc__)
+    group.add_function(name="compare", fn=_compare, description=_compare.__doc__)
+
+    yield group

data_designer_nemo/context.py

@@ -0,0 +1,148 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Protocol
+
+import data_designer.config as dd
+from data_designer.config.utils.constants import MANAGED_ASSETS_PATH
+from data_designer.engine.resources.person_reader import PersonReader, create_person_reader
+from data_designer.engine.resources.seed_reader import (
+    AgentRolloutSeedReader,
+    DataFrameSeedReader,
+    DirectorySeedReader,
+    FileContentsSeedReader,
+    HuggingFaceSeedReader,
+    LocalFileSeedReader,
+    SeedReader,
+)
+from data_designer.engine.secret_resolver import (
+    CompositeResolver,
+    EnvironmentResolver,
+    PlaintextResolver,
+    SecretResolver,
+)
+from data_designer_nemo.fileset_file_seed_reader import FilesetFileSeedReader
+from data_designer_nemo.model_provider import (
+    make_local_first_model_provider_registry,
+    make_model_provider_registry,
+    make_noop_provider,
+)
+from data_designer_nemo.person_reader import FilesetsPersonReader
+from data_designer_nemo.person_sampling import ensure_nemotron_personas_filesets
+from data_designer_nemo.sdk_translation import sync_to_async_sdk
+from data_designer_nemo.secret_resolver import NMPSecretResolver
+from data_designer_nemo.seed import validate_seed
+from data_designer_nemo.unsupported_features import (
+    validate_no_tool_configs,
+    validate_seed_config_for_execution_context,
+)
+from nemo_platform import AsyncNeMoPlatform, NeMoPlatform
+
+
+class DataDesignerContext(Protocol):
+    async def validate(self, config: dd.DataDesignerConfig) -> None: ...
+
+    def get_secret_resolver(self) -> SecretResolver: ...
+
+    def get_seed_readers(self) -> list[SeedReader]: ...
+
+    def get_person_reader(self) -> PersonReader: ...
+
+    async def get_model_providers(self, model_configs: list[dd.ModelConfig]) -> list[dd.ModelProvider]: ...
+
+
+class LocalDataDesignerContext:
+    def __init__(self, sdk: AsyncNeMoPlatform | NeMoPlatform, workspace: str):
+        self._sdk = sdk
+        self._workspace = workspace
+
+    def get_secret_resolver(self) -> SecretResolver:
+        return CompositeResolver(
+            resolvers=[
+                EnvironmentResolver(),
+                NMPSecretResolver(self._sdk, self._workspace),
+                PlaintextResolver(),
+            ]
+        )
+
+    async def validate(self, config: dd.DataDesignerConfig) -> None:
+        validate_seed_config_for_execution_context(config, is_local=True)
+
+    def get_seed_readers(self) -> list[SeedReader]:
+        return [
+            HuggingFaceSeedReader(),
+            LocalFileSeedReader(),
+            DataFrameSeedReader(),
+            DirectorySeedReader(),
+            FileContentsSeedReader(),
+            AgentRolloutSeedReader(),
+            FilesetFileSeedReader(self._sdk),
+        ]
+
+    def get_person_reader(self) -> PersonReader:
+        return create_person_reader(str(MANAGED_ASSETS_PATH))
+
+    async def get_model_providers(self, model_configs: list[dd.ModelConfig]) -> list[dd.ModelProvider]:
+        if (
+            local_first_registry := await make_local_first_model_provider_registry(
+                model_configs,
+                sdk=self._sdk,
+                default_workspace=self._workspace,
+            )
+        ) is not None:
+            return local_first_registry.providers
+
+        return [make_noop_provider()]
+
+
+class RemoteDataDesignerContext:
+    def __init__(self, sdk: AsyncNeMoPlatform | NeMoPlatform, workspace: str):
+        self._sdk = sdk
+        self._workspace = workspace
+
+    def get_secret_resolver(self) -> SecretResolver:
+        return NMPSecretResolver(self._sdk, self._workspace)
+
+    async def validate(self, config: dd.DataDesignerConfig) -> None:
+        sdk = self._async_sdk()
+        validate_no_tool_configs(config)
+        validate_seed_config_for_execution_context(config, is_local=False)
+        await validate_seed(config, self._workspace, sdk)
+        await ensure_nemotron_personas_filesets(config, sdk)
+
+    def get_seed_readers(self) -> list[SeedReader]:
+        return [
+            HuggingFaceSeedReader(),
+            FilesetFileSeedReader(self._sdk),
+        ]
+
+    def get_person_reader(self) -> PersonReader:
+        return FilesetsPersonReader(self._sdk)
+
+    async def get_model_providers(self, model_configs: list[dd.ModelConfig]) -> list[dd.ModelProvider]:
+        sdk = self._async_sdk()
+
+        if (
+            igw_registry := await make_model_provider_registry(
+                model_configs,
+                sdk=sdk,
+                default_workspace=self._workspace,
+            )
+        ) is not None:
+            return igw_registry.providers
+
+        return [make_noop_provider()]
+
+    def _async_sdk(self) -> AsyncNeMoPlatform:
+        if isinstance(self._sdk, NeMoPlatform):
+            return sync_to_async_sdk(self._sdk)
+        return self._sdk
+
+
+def create_data_designer_context(
+    is_local: bool, sdk: AsyncNeMoPlatform | NeMoPlatform, workspace: str
+) -> DataDesignerContext:
+    if is_local:
+        return LocalDataDesignerContext(sdk, workspace)
+    else:
+        return RemoteDataDesignerContext(sdk, workspace)

data_designer_nemo/errors.py

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+
+class NDDInternalError(Exception): ...
+
+
+class NDDInvalidConfigError(Exception): ...

data_designer_nemo/fileset_file_seed_reader.py

@@ -0,0 +1,54 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from contextvars import ContextVar
+
+import duckdb
+from data_designer.engine.resources.seed_reader import SeedReader
+from data_designer_nemo.fileset_file_seed_source import FilesetFileSeedSource
+from data_designer_nemo.sdk_translation import async_to_sync_sdk
+from nemo_platform import AsyncNeMoPlatform, NeMoPlatform
+from nemo_platform.filesets import FilesetFileSystem
+
+workspace_cvar = ContextVar[str | None]("workspace_cvar", default=None)
+
+
+class FilesetFileSeedReader(SeedReader[FilesetFileSeedSource]):
+    # The Data Designer library discovers seed-reader plugins by instantiating them with no args.
+    # Within this plugin we always inject an SDK and pass a collection of readers that replaces
+    # any library-produced default collection of readers.
+    def __init__(self, sdk: NeMoPlatform | AsyncNeMoPlatform | None = None):
+        if isinstance(sdk, AsyncNeMoPlatform):
+            sdk = async_to_sync_sdk(sdk)
+        self._sdk: NeMoPlatform | None = sdk
+
+    def create_duckdb_connection(self) -> duckdb.DuckDBPyConnection:
+        if self._sdk is None:
+            raise RuntimeError("FilesetFileSeedReader requires an injected NeMo Platform SDK")
+
+        filesystem = FilesetFileSystem(self._sdk)
+
+        conn = duckdb.connect()
+        conn.register_filesystem(filesystem)
+        return conn
+
+    def get_dataset_uri(self) -> str:
+        path = self.source.path
+        if self._requires_workspace_prefix(path):
+            path = f"{self._get_workspace()}/{path}"
+
+        return f"fileset://{path}"
+
+    def _requires_workspace_prefix(self, path: str) -> bool:
+        user_provided_fileset = path.split("#")[0]
+        components = user_provided_fileset.split("/")
+        return len(components) == 1
+
+    def _get_workspace(self) -> str:
+        workspace = workspace_cvar.get()
+        if workspace is None:
+            raise ValueError(
+                "FilesetFileSeedSource path does not include a workspace and "
+                "a workspace could not be inferred from the current context"
+            )
+        return workspace

data_designer_nemo/fileset_file_seed_source.py

@@ -0,0 +1,38 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+from typing import Literal
+
+from data_designer.config.seed_source import SeedSource
+from pydantic import field_validator
+
+FILESET_TOO_MANY_SLASHES = "Path fileset cannot contain more than one slash (/)"
+MISSING_FRAGMENT_DELIMITER = "Path should contain a fragment delimiter (#)"
+EMPTY_FILESET = "Fileset cannot be empty"
+EMPTY_PATH_FRAGMENT = "Path fragment cannot be empty"
+
+
+class FilesetFileSeedSource(SeedSource):
+    seed_type: Literal["nmp"] = "nmp"
+
+    path: str
+
+    @field_validator("path", mode="after")
+    def validate_path(cls, value: str) -> str:
+        components = value.split("#", 1)
+        if len(components) == 1:
+            raise ValueError(MISSING_FRAGMENT_DELIMITER)
+
+        fileset = components[0]
+        if len(fileset) == 0:
+            raise ValueError(EMPTY_FILESET)
+
+        fileset_components = fileset.split("/")
+        if len(fileset_components) > 2:
+            raise ValueError(FILESET_TOO_MANY_SLASHES)
+
+        path_fragment = components[1]
+        if len(path_fragment) == 0:
+            raise ValueError(EMPTY_PATH_FRAGMENT)
+
+        return value

data_designer_nemo/model_configs.py

@@ -0,0 +1,31 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import data_designer.config as dd
+from data_designer_nemo.errors import NDDInvalidConfigError
+
+
+def get_model_configs(dd_config: dd.DataDesignerConfig) -> list[dd.ModelConfig]:
+    """Returns the list of model configs required by the given DataDesignerConfig.
+
+    Returns:
+        A list of model configs
+
+    Raises:
+        NDDInvalidConfigError if a column or profiler references an unrecognized alias
+    """
+    all_known_model_configs = {mc.alias: mc for mc in dd_config.model_configs or []}
+
+    used_aliases = set[str]()
+    for column_config in dd_config.columns:
+        model_alias = getattr(column_config, "model_alias", None)
+        if isinstance(model_alias, str):
+            used_aliases.add(model_alias)
+    for profiler in dd_config.profilers or []:
+        used_aliases.add(profiler.model_alias)
+
+    unrecognized_aliases = [alias for alias in used_aliases if alias not in all_known_model_configs]
+    if len(unrecognized_aliases) > 0:
+        raise NDDInvalidConfigError(f"Unrecognized model aliases in config: {','.join(unrecognized_aliases)}")
+
+    return [all_known_model_configs[alias] for alias in used_aliases]