nvidia-nat 1.3.0a20250910__py3-none-any.whl → 1.3.0a20250922__py3-none-any.whl

nat/front_ends/fastapi/main.py

@@ -13,19 +13,24 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-import importlib
 import logging
 import os
+import typing
 
 from nat.front_ends.fastapi.fastapi_front_end_plugin_worker import FastApiFrontEndPluginWorkerBase
+from nat.front_ends.fastapi.utils import get_config_file_path
+from nat.front_ends.fastapi.utils import import_class_from_string
 from nat.runtime.loader import load_config
 
+if typing.TYPE_CHECKING:
+    from fastapi import FastAPI
+
 logger = logging.getLogger(__name__)
 
 
-def get_app():
+def get_app() -> "FastAPI":
 
-    config_file_path = os.getenv("NAT_CONFIG_FILE")
+    config_file_path = get_config_file_path()
     front_end_worker_full_name = os.getenv("NAT_FRONT_END_WORKER")
 
     if (not config_file_path):
@@ -36,28 +41,15 @@ def get_app():
 
     # Try to import the front end worker class
     try:
-        # Split the package from the class
-        front_end_worker_parts = front_end_worker_full_name.split(".")
-
-        front_end_worker_module_name = ".".join(front_end_worker_parts[:-1])
-        front_end_worker_class_name = front_end_worker_parts[-1]
-
-        front_end_worker_module = importlib.import_module(front_end_worker_module_name)
-
-        if not hasattr(front_end_worker_module, front_end_worker_class_name):
-            raise ValueError(f"Front end worker {front_end_worker_full_name} not found.")
-
-        front_end_worker_class: type[FastApiFrontEndPluginWorkerBase] = getattr(front_end_worker_module,
-                                                                                front_end_worker_class_name)
+        front_end_worker_class: type[FastApiFrontEndPluginWorkerBase] = import_class_from_string(
+            front_end_worker_full_name)
 
         if (not issubclass(front_end_worker_class, FastApiFrontEndPluginWorkerBase)):
             raise ValueError(
                 f"Front end worker {front_end_worker_full_name} is not a subclass of FastApiFrontEndPluginWorker.")
 
         # Load the config
-        abs_config_file_path = os.path.abspath(config_file_path)
-
-        config = load_config(abs_config_file_path)
+        config = load_config(config_file_path)
 
         # Create an instance of the front end worker class
         front_end_worker = front_end_worker_class(config)

nat/front_ends/fastapi/utils.py

@@ -0,0 +1,57 @@
+# 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 importlib
+import os
+
+
+def get_config_file_path() -> str:
+    """
+    Get the path to the NAT configuration file from the environment variable NAT_CONFIG_FILE.
+    Raises ValueError if the environment variable is not set.
+    """
+    config_file_path = os.getenv("NAT_CONFIG_FILE")
+    if (not config_file_path):
+        raise ValueError("Config file not found in environment variable NAT_CONFIG_FILE.")
+
+    return os.path.abspath(config_file_path)
+
+
+def import_class_from_string(class_full_name: str) -> type:
+    """
+    Import a class from a string in the format 'module.submodule.ClassName'.
+    Raises ImportError if the class cannot be imported.
+    """
+    try:
+        class_name_parts = class_full_name.split(".")
+
+        module_name = ".".join(class_name_parts[:-1])
+        class_name = class_name_parts[-1]
+
+        module = importlib.import_module(module_name)
+
+        if not hasattr(module, class_name):
+            raise ValueError(f"Class '{class_full_name}' not found.")
+
+        return getattr(module, class_name)
+    except (ImportError, AttributeError) as e:
+        raise ImportError(f"Could not import {class_full_name}.") from e
+
+
+def get_class_name(cls: type) -> str:
+    """
+    Get the full class name including the module.
+    """
+    return f"{cls.__module__}.{cls.__qualname__}"

nat/front_ends/mcp/introspection_token_verifier.py

@@ -0,0 +1,73 @@
+# 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.
+"""OAuth 2.0 Token Introspection verifier implementation for MCP servers."""
+
+import logging
+
+from mcp.server.auth.provider import AccessToken
+from mcp.server.auth.provider import TokenVerifier
+
+from nat.authentication.credential_validator.bearer_token_validator import BearerTokenValidator
+from nat.authentication.oauth2.oauth2_resource_server_config import OAuth2ResourceServerConfig
+
+logger = logging.getLogger(__name__)
+
+
+class IntrospectionTokenVerifier(TokenVerifier):
+    """Token verifier that delegates token verification to BearerTokenValidator."""
+
+    def __init__(self, config: OAuth2ResourceServerConfig):
+        """Create IntrospectionTokenVerifier from OAuth2ResourceServerConfig.
+
+        Args:
+            config: OAuth2ResourceServerConfig
+        """
+        issuer = config.issuer_url
+        scopes = config.scopes or []
+        audience = config.audience
+        jwks_uri = config.jwks_uri
+        introspection_endpoint = config.introspection_endpoint
+        discovery_url = config.discovery_url
+        client_id = config.client_id
+        client_secret = config.client_secret
+
+        self._bearer_token_validator = BearerTokenValidator(
+            issuer=issuer,
+            audience=audience,
+            scopes=scopes,
+            jwks_uri=jwks_uri,
+            introspection_endpoint=introspection_endpoint,
+            discovery_url=discovery_url,
+            client_id=client_id,
+            client_secret=client_secret,
+        )
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify token by delegating to BearerTokenValidator.
+
+        Args:
+            token: The Bearer token to verify
+
+        Returns:
+            AccessToken | None: AccessToken if valid, None if invalid
+        """
+        validation_result = await self._bearer_token_validator.verify(token)
+
+        if validation_result.active:
+            return AccessToken(token=token,
+                               expires_at=validation_result.expires_at,
+                               scopes=validation_result.scopes or [],
+                               client_id=validation_result.client_id or "")
+        return None

nat/front_ends/mcp/mcp_front_end_config.py

@@ -17,13 +17,14 @@ from typing import Literal
 
 from pydantic import Field
 
+from nat.authentication.oauth2.oauth2_resource_server_config import OAuth2ResourceServerConfig
 from nat.data_models.front_end import FrontEndBaseConfig
 
 
 class MCPFrontEndConfig(FrontEndBaseConfig, name="mcp"):
     """MCP front end configuration.
 
-    A simple MCP (Modular Communication Protocol) front end for NeMo Agent toolkit.
+    A simple MCP (Model Context Protocol) front end for NeMo Agent toolkit.
     """
 
     name: str = Field(default="NeMo Agent Toolkit MCP",
@@ -39,3 +40,6 @@ class MCPFrontEndConfig(FrontEndBaseConfig, name="mcp"):
         description="Transport type for the MCP server (default: streamable-http, backwards compatible with sse)")
     runner_class: str | None = Field(
         default=None, description="Custom worker class for handling MCP routes (default: built-in worker)")
+
+    server_auth: OAuth2ResourceServerConfig | None = Field(
+        default=None, description=("OAuth 2.0 Resource Server configuration for token verification."))

nat/front_ends/mcp/mcp_front_end_plugin.py

@@ -16,6 +16,7 @@
 import logging
 import typing
 
+from nat.authentication.oauth2.oauth2_resource_server_config import OAuth2ResourceServerConfig
 from nat.builder.front_end import FrontEndBase
 from nat.builder.workflow_builder import WorkflowBuilder
 from nat.front_ends.mcp.mcp_front_end_config import MCPFrontEndConfig
@@ -55,25 +56,50 @@ class MCPFrontEndPlugin(FrontEndBase[MCPFrontEndConfig]):
 
         return worker_class(self.full_config)
 
+    async def _create_token_verifier(self, token_verifier_config: OAuth2ResourceServerConfig):
+        """Create a token verifier based on configuration."""
+        from nat.front_ends.mcp.introspection_token_verifier import IntrospectionTokenVerifier
+
+        if not self.front_end_config.server_auth:
+            return None
+
+        return IntrospectionTokenVerifier(token_verifier_config)
+
     async def run(self) -> None:
         """Run the MCP server."""
         # Import FastMCP
         from mcp.server.fastmcp import FastMCP
 
-        # Create an MCP server with the configured parameters
-        mcp = FastMCP(
-            self.front_end_config.name,
-            host=self.front_end_config.host,
-            port=self.front_end_config.port,
-            debug=self.front_end_config.debug,
-            log_level=self.front_end_config.log_level,
-        )
-
-        # Get the worker instance and set up routes
-        worker = self._get_worker_instance()
+        # Create auth settings and token verifier if auth is required
+        auth_settings = None
+        token_verifier = None
 
         # Build the workflow and add routes using the worker
         async with WorkflowBuilder.from_config(config=self.full_config) as builder:
+
+            if self.front_end_config.server_auth:
+                from mcp.server.auth.settings import AuthSettings
+                from pydantic import AnyHttpUrl
+
+                server_url = f"http://{self.front_end_config.host}:{self.front_end_config.port}"
+
+                auth_settings = AuthSettings(issuer_url=AnyHttpUrl(self.front_end_config.server_auth.issuer_url),
+                                             required_scopes=self.front_end_config.server_auth.scopes,
+                                             resource_server_url=AnyHttpUrl(server_url))
+
+                token_verifier = await self._create_token_verifier(self.front_end_config.server_auth)
+
+            # Create an MCP server with the configured parameters
+            mcp = FastMCP(name=self.front_end_config.name,
+                          host=self.front_end_config.host,
+                          port=self.front_end_config.port,
+                          debug=self.front_end_config.debug,
+                          auth=auth_settings,
+                          token_verifier=token_verifier)
+
+            # Get the worker instance and set up routes
+            worker = self._get_worker_instance()
+
             # Add routes through the worker (includes health endpoint and function registration)
             await worker.add_routes(mcp, builder)
 

nat/front_ends/mcp/mcp_front_end_plugin_worker.py

@@ -16,11 +16,15 @@
 import logging
 from abc import ABC
 from abc import abstractmethod
+from collections.abc import Mapping
+from typing import Any
 
 from mcp.server.fastmcp import FastMCP
+from starlette.exceptions import HTTPException
 from starlette.requests import Request
 
 from nat.builder.function import Function
+from nat.builder.function_base import FunctionBase
 from nat.builder.workflow import Workflow
 from nat.builder.workflow_builder import WorkflowBuilder
 from nat.data_models.config import Config
@@ -94,13 +98,114 @@ class MCPFrontEndPluginWorkerBase(ABC):
         functions: dict[str, Function] = {}
 
         # Extract all functions from the workflow
-        for function_name, function in workflow.functions.items():
-            functions[function_name] = function
+        functions.update(workflow.functions)
+        for function_group in workflow.function_groups.values():
+            functions.update(function_group.get_accessible_functions())
 
-        functions[workflow.config.workflow.type] = workflow
+        if workflow.config.workflow.workflow_alias:
+            functions[workflow.config.workflow.workflow_alias] = workflow
+        else:
+            functions[workflow.config.workflow.type] = workflow
 
         return functions
 
+    def _setup_debug_endpoints(self, mcp: FastMCP, functions: Mapping[str, FunctionBase]) -> None:
+        """Set up HTTP debug endpoints for introspecting tools and schemas.
+
+        Exposes:
+          - GET /debug/tools/list: List tools. Optional query param `name` (one or more, repeatable or comma separated)
+            selects a subset and returns details for those tools.
+        """
+
+        @mcp.custom_route("/debug/tools/list", methods=["GET"])
+        async def list_tools(request: Request):
+            """HTTP list tools endpoint."""
+
+            from starlette.responses import JSONResponse
+
+            from nat.front_ends.mcp.tool_converter import get_function_description
+
+            # Query params
+            # Support repeated names and comma-separated lists
+            names_param_list = set(request.query_params.getlist("name"))
+            names: list[str] = []
+            for raw in names_param_list:
+                # if p.strip() is empty, it won't be included in the list!
+                parts = [p.strip() for p in raw.split(",") if p.strip()]
+                names.extend(parts)
+            detail_raw = request.query_params.get("detail")
+
+            def _parse_detail_param(detail_param: str | None, has_names: bool) -> bool:
+                if detail_param is None:
+                    if has_names:
+                        return True
+                    return False
+                v = detail_param.strip().lower()
+                if v in ("0", "false", "no", "off"):
+                    return False
+                if v in ("1", "true", "yes", "on"):
+                    return True
+                # For invalid values, default based on whether names are present
+                return has_names
+
+            # Helper function to build the input schema info
+            def _build_schema_info(fn: FunctionBase) -> dict[str, Any] | None:
+                schema = getattr(fn, "input_schema", None)
+                if schema is None:
+                    return None
+
+                # check if schema is a ChatRequest
+                schema_name = getattr(schema, "__name__", "")
+                schema_qualname = getattr(schema, "__qualname__", "")
+                if "ChatRequest" in schema_name or "ChatRequest" in schema_qualname:
+                    # Simplified interface used by MCP wrapper for ChatRequest
+                    return {
+                        "type": "object",
+                        "properties": {
+                            "query": {
+                                "type": "string", "description": "User query string"
+                            }
+                        },
+                        "required": ["query"],
+                        "title": "ChatRequestQuery",
+                    }
+
+                # Pydantic models provide model_json_schema
+                if schema is not None and hasattr(schema, "model_json_schema"):
+                    return schema.model_json_schema()
+
+                return None
+
+            def _build_final_json(functions_to_include: Mapping[str, FunctionBase],
+                                  include_schemas: bool = False) -> dict[str, Any]:
+                tools = []
+                for name, fn in functions_to_include.items():
+                    list_entry: dict[str, Any] = {
+                        "name": name, "description": get_function_description(fn), "is_workflow": hasattr(fn, "run")
+                    }
+                    if include_schemas:
+                        list_entry["schema"] = _build_schema_info(fn)
+                    tools.append(list_entry)
+
+                return {
+                    "count": len(tools),
+                    "tools": tools,
+                    "server_name": mcp.name,
+                }
+
+            if names:
+                # Return selected tools
+                try:
+                    functions_to_include = {n: functions[n] for n in names}
+                except KeyError as e:
+                    raise HTTPException(status_code=404, detail=f"Tool \"{e.args[0]}\" not found.") from e
+            else:
+                functions_to_include = functions
+
+            # Default for listing all: detail defaults to False unless explicitly set true
+            return JSONResponse(
+                _build_final_json(functions_to_include, _parse_detail_param(detail_raw, has_names=bool(names))))
+
 
 class MCPFrontEndPluginWorker(MCPFrontEndPluginWorkerBase):
     """Default MCP front end plugin worker implementation."""
@@ -141,3 +246,6 @@ class MCPFrontEndPluginWorker(MCPFrontEndPluginWorkerBase):
         # Add a simple fallback function if no functions were found
         if not functions:
             raise RuntimeError("No functions found in workflow. Please check your configuration.")
+
+        # After registration, expose debug endpoints for tool/schema inspection
+        self._setup_debug_endpoints(mcp, functions)

nat/front_ends/mcp/tool_converter.py

@@ -229,6 +229,9 @@ def get_function_description(function: FunctionBase) -> str:
         # Try to get anything that might be a description
         elif hasattr(config, "topic") and config.topic:
             function_description = config.topic
+        # Try to get description from the workflow config
+        elif hasattr(config, "workflow") and hasattr(config.workflow, "description") and config.workflow.description:
+            function_description = config.workflow.description
 
     elif isinstance(function, Function):
         function_description = function.description

nat/llm/aws_bedrock_llm.py

@@ -21,22 +21,33 @@ from nat.builder.builder import Builder
 from nat.builder.llm import LLMProviderInfo
 from nat.cli.register_workflow import register_llm_provider
 from nat.data_models.llm import LLMBaseConfig
+from nat.data_models.optimizable import OptimizableField
+from nat.data_models.optimizable import OptimizableMixin
+from nat.data_models.optimizable import SearchSpace
 from nat.data_models.retry_mixin import RetryMixin
 from nat.data_models.temperature_mixin import TemperatureMixin
 from nat.data_models.thinking_mixin import ThinkingMixin
 from nat.data_models.top_p_mixin import TopPMixin
 
 
-class AWSBedrockModelConfig(LLMBaseConfig, RetryMixin, TemperatureMixin, TopPMixin, ThinkingMixin, name="aws_bedrock"):
+class AWSBedrockModelConfig(LLMBaseConfig,
+                            RetryMixin,
+                            OptimizableMixin,
+                            TemperatureMixin,
+                            TopPMixin,
+                            ThinkingMixin,
+                            name="aws_bedrock"):
     """An AWS Bedrock llm provider to be used with an LLM client."""
 
-    model_config = ConfigDict(protected_namespaces=())
+    model_config = ConfigDict(protected_namespaces=(), extra="allow")
 
     # Completion parameters
     model_name: str = Field(validation_alias=AliasChoices("model_name", "model"),
                             serialization_alias="model",
                             description="The model name for the hosted AWS Bedrock.")
-    max_tokens: int | None = Field(default=1024, gt=0, description="Maximum number of tokens to generate.")
+    max_tokens: int = OptimizableField(default=300,
+                                       description="Maximum number of tokens to generate.",
+                                       space=SearchSpace(high=2176, low=128, step=512))
     context_size: int | None = Field(
         default=1024,
         gt=0,

nat/llm/nim_llm.py

@@ -22,23 +22,34 @@ from nat.builder.builder import Builder
 from nat.builder.llm import LLMProviderInfo
 from nat.cli.register_workflow import register_llm_provider
 from nat.data_models.llm import LLMBaseConfig
+from nat.data_models.optimizable import OptimizableField
+from nat.data_models.optimizable import OptimizableMixin
+from nat.data_models.optimizable import SearchSpace
 from nat.data_models.retry_mixin import RetryMixin
 from nat.data_models.temperature_mixin import TemperatureMixin
 from nat.data_models.thinking_mixin import ThinkingMixin
 from nat.data_models.top_p_mixin import TopPMixin
 
 
-class NIMModelConfig(LLMBaseConfig, RetryMixin, TemperatureMixin, TopPMixin, ThinkingMixin, name="nim"):
+class NIMModelConfig(LLMBaseConfig,
+                     RetryMixin,
+                     OptimizableMixin,
+                     TemperatureMixin,
+                     TopPMixin,
+                     ThinkingMixin,
+                     name="nim"):
     """An NVIDIA Inference Microservice (NIM) llm provider to be used with an LLM client."""
 
-    model_config = ConfigDict(protected_namespaces=())
+    model_config = ConfigDict(protected_namespaces=(), extra="allow")
 
     api_key: str | None = Field(default=None, description="NVIDIA API key to interact with hosted NIM.")
     base_url: str | None = Field(default=None, description="Base url to the hosted NIM.")
     model_name: str = Field(validation_alias=AliasChoices("model_name", "model"),
                             serialization_alias="model",
                             description="The model name for the hosted NIM.")
-    max_tokens: PositiveInt = Field(default=300, description="Maximum number of tokens to generate.")
+    max_tokens: PositiveInt = OptimizableField(default=300,
+                                               description="Maximum number of tokens to generate.",
+                                               space=SearchSpace(high=2176, low=128, step=512))
 
 
 @register_llm_provider(config_type=NIMModelConfig)

nat/llm/openai_llm.py

@@ -21,13 +21,20 @@ from nat.builder.builder import Builder
 from nat.builder.llm import LLMProviderInfo
 from nat.cli.register_workflow import register_llm_provider
 from nat.data_models.llm import LLMBaseConfig
+from nat.data_models.optimizable import OptimizableMixin
 from nat.data_models.retry_mixin import RetryMixin
 from nat.data_models.temperature_mixin import TemperatureMixin
 from nat.data_models.thinking_mixin import ThinkingMixin
 from nat.data_models.top_p_mixin import TopPMixin
 
 
-class OpenAIModelConfig(LLMBaseConfig, RetryMixin, TemperatureMixin, TopPMixin, ThinkingMixin, name="openai"):
+class OpenAIModelConfig(LLMBaseConfig,
+                        RetryMixin,
+                        OptimizableMixin,
+                        TemperatureMixin,
+                        TopPMixin,
+                        ThinkingMixin,
+                        name="openai"):
     """An OpenAI LLM provider to be used with an LLM client."""
 
     model_config = ConfigDict(protected_namespaces=(), extra="allow")