nvidia-nat 1.4.0a20251112__py3-none-any.whl → 1.4.0a20251120__py3-none-any.whl

nat/cli/type_registry.py

@@ -64,6 +64,8 @@ from nat.data_models.logging import LoggingBaseConfig
 from nat.data_models.logging import LoggingMethodConfigT
 from nat.data_models.memory import MemoryBaseConfig
 from nat.data_models.memory import MemoryBaseConfigT
+from nat.data_models.middleware import MiddlewareBaseConfig
+from nat.data_models.middleware import MiddlewareBaseConfigT
 from nat.data_models.object_store import ObjectStoreBaseConfig
 from nat.data_models.object_store import ObjectStoreBaseConfigT
 from nat.data_models.registry_handler import RegistryHandlerBaseConfig
@@ -76,6 +78,7 @@ from nat.data_models.ttc_strategy import TTCStrategyBaseConfig
 from nat.data_models.ttc_strategy import TTCStrategyBaseConfigT
 from nat.experimental.test_time_compute.models.strategy_base import StrategyBase
 from nat.memory.interfaces import MemoryEditor
+from nat.middleware.middleware import Middleware
 from nat.object_store.interfaces import ObjectStore
 from nat.observability.exporter.base_exporter import BaseExporter
 from nat.registry_handlers.registry_handler_base import AbstractRegistryHandler
@@ -89,6 +92,7 @@ EvaluatorBuildCallableT = Callable[[EvaluatorBaseConfigT, EvalBuilder], AsyncIte
 FrontEndBuildCallableT = Callable[[FrontEndConfigT, Config], AsyncIterator[FrontEndBase]]
 FunctionBuildCallableT = Callable[[FunctionConfigT, Builder], AsyncIterator[FunctionInfo | Callable | FunctionBase]]
 FunctionGroupBuildCallableT = Callable[[FunctionGroupConfigT, Builder], AsyncIterator[FunctionGroup]]
+MiddlewareBuildCallableT = Callable[[MiddlewareBaseConfigT, Builder], AsyncIterator[Middleware]]
 TTCStrategyBuildCallableT = Callable[[TTCStrategyBaseConfigT, Builder], AsyncIterator[StrategyBase]]
 LLMClientBuildCallableT = Callable[[LLMBaseConfigT, Builder], AsyncIterator[typing.Any]]
 LLMProviderBuildCallableT = Callable[[LLMBaseConfigT, Builder], AsyncIterator[LLMProviderInfo]]
@@ -111,6 +115,7 @@ FrontEndRegisteredCallableT = Callable[[FrontEndConfigT, Config], AbstractAsyncC
 FunctionRegisteredCallableT = Callable[[FunctionConfigT, Builder],
                                        AbstractAsyncContextManager[FunctionInfo | Callable | FunctionBase]]
 FunctionGroupRegisteredCallableT = Callable[[FunctionGroupConfigT, Builder], AbstractAsyncContextManager[FunctionGroup]]
+MiddlewareRegisteredCallableT = Callable[[MiddlewareBaseConfigT, Builder], AbstractAsyncContextManager[Middleware]]
 TTCStrategyRegisterCallableT = Callable[[TTCStrategyBaseConfigT, Builder], AbstractAsyncContextManager[StrategyBase]]
 LLMClientRegisteredCallableT = Callable[[LLMBaseConfigT, Builder], AbstractAsyncContextManager[typing.Any]]
 LLMProviderRegisteredCallableT = Callable[[LLMBaseConfigT, Builder], AbstractAsyncContextManager[LLMProviderInfo]]
@@ -179,6 +184,8 @@ class RegisteredFunctionInfo(RegisteredInfo[FunctionBaseConfig]):
     and a description.
     """
 
+    model_config = ConfigDict(frozen=True, arbitrary_types_allowed=True)
+
     build_fn: FunctionRegisteredCallableT = Field(repr=False)
     framework_wrappers: list[str] = Field(default_factory=list)
 
@@ -193,6 +200,15 @@ class RegisteredFunctionGroupInfo(RegisteredInfo[FunctionGroupBaseConfig]):
     framework_wrappers: list[str] = Field(default_factory=list)
 
 
+class RegisteredMiddlewareInfo(RegisteredInfo[MiddlewareBaseConfig]):
+    """
+    Represents registered middleware. Middleware provides middleware-style wrapping of
+    calls with preprocessing and postprocessing logic.
+    """
+
+    build_fn: MiddlewareRegisteredCallableT = Field(repr=False)
+
+
 class RegisteredLLMProviderInfo(RegisteredInfo[LLMBaseConfig]):
     """
     Represents a registered LLM provider. LLM Providers are the operators of the LLMs. i.e. NIMs, OpenAI, Anthropic,
@@ -331,6 +347,9 @@ class TypeRegistry:
         # Function Groups
         self._registered_function_groups: dict[type[FunctionGroupBaseConfig], RegisteredFunctionGroupInfo] = {}
 
+        # Middleware
+        self._registered_middleware: dict[type[MiddlewareBaseConfig], RegisteredMiddlewareInfo] = {}
+
         # LLMs
         self._registered_llm_provider_infos: dict[type[LLMBaseConfig], RegisteredLLMProviderInfo] = {}
         self._llm_client_provider_to_framework: dict[type[LLMBaseConfig], dict[str, RegisteredLLMClientInfo]] = {}
@@ -540,6 +559,49 @@ class TypeRegistry:
         """
         return list(self._registered_function_groups.values())
 
+    def register_middleware(self, registration: RegisteredMiddlewareInfo):
+        """Register middleware with the type registry.
+
+        Args:
+            registration: The middleware registration information
+
+        Raises:
+            ValueError: If middleware with the same config type is already registered
+        """
+        if (registration.config_type in self._registered_middleware):
+            raise ValueError(f"Middleware with the same config type `{registration.config_type}` has already been "
+                             "registered.")
+
+        self._registered_middleware[registration.config_type] = registration
+
+        self._registration_changed()
+
+    def get_middleware(self, config_type: type[MiddlewareBaseConfig]) -> RegisteredMiddlewareInfo:
+        """Get registered middleware by its config type.
+
+        Args:
+            config_type: The middleware configuration type
+
+        Returns:
+            RegisteredMiddlewareInfo: The registered middleware information
+
+        Raises:
+            KeyError: If no middleware is registered for the given config type
+        """
+        try:
+            return self._registered_middleware[config_type]
+        except KeyError as err:
+            raise KeyError(f"Could not find registered middleware for config `{config_type}`. "
+                           f"Registered configs: {set(self._registered_middleware.keys())}") from err
+
+    def get_registered_middleware(self) -> list[RegisteredInfo[MiddlewareBaseConfig]]:
+        """Get all registered middleware.
+
+        Returns:
+            list[RegisteredInfo[MiddlewareBaseConfig]]: List of all registered middleware
+        """
+        return list(self._registered_middleware.values())
+
     def register_llm_provider(self, info: RegisteredLLMProviderInfo):
 
         if (info.config_type in self._registered_llm_provider_infos):
@@ -912,6 +974,9 @@ class TypeRegistry:
         if component_type == ComponentEnum.TTC_STRATEGY:
             return self._registered_ttc_strategies
 
+        if component_type == ComponentEnum.MIDDLEWARE:
+            return self._registered_middleware
+
         raise ValueError(f"Supplied an unsupported component type {component_type}")
 
     def get_registered_types_by_component_type(self, component_type: ComponentEnum) -> list[str]:
@@ -1038,6 +1103,9 @@ class TypeRegistry:
         if issubclass(cls, TTCStrategyBaseConfig):
             return self._do_compute_annotation(cls, self.get_registered_ttc_strategies())
 
+        if issubclass(cls, MiddlewareBaseConfig):
+            return self._do_compute_annotation(cls, self.get_registered_middleware())
+
         raise ValueError(f"Supplied an unsupported component type {cls}")
 
 

nat/data_models/component.py

@@ -28,6 +28,7 @@ class ComponentEnum(StrEnum):
     FRONT_END = "front_end"
     FUNCTION = "function"
     FUNCTION_GROUP = "function_group"
+    MIDDLEWARE = "middleware"
     TTC_STRATEGY = "ttc_strategy"
     LLM_CLIENT = "llm_client"
     LLM_PROVIDER = "llm_provider"
@@ -49,6 +50,7 @@ class ComponentGroup(StrEnum):
     EMBEDDERS = "embedders"
     FUNCTIONS = "functions"
     FUNCTION_GROUPS = "function_groups"
+    MIDDLEWARE = "middleware"
     TTC_STRATEGIES = "ttc_strategies"
     LLMS = "llms"
     MEMORY = "memory"

nat/data_models/component_ref.py

@@ -177,3 +177,14 @@ class TTCStrategyRef(ComponentRef):
     @override
     def component_group(self):
         return ComponentGroup.TTC_STRATEGIES
+
+
+class MiddlewareRef(ComponentRef):
+    """
+    A reference to middleware in a NAT configuration object.
+    """
+
+    @property
+    @override
+    def component_group(self):
+        return ComponentGroup.MIDDLEWARE

nat/data_models/config.py

@@ -43,6 +43,7 @@ from .common import TypedBaseModel
 from .embedder import EmbedderBaseConfig
 from .llm import LLMBaseConfig
 from .memory import MemoryBaseConfig
+from .middleware import FunctionMiddlewareBaseConfig
 from .object_store import ObjectStoreBaseConfig
 from .retriever import RetrieverBaseConfig
 
@@ -86,6 +87,8 @@ def _process_validation_error(err: ValidationError, handler: ValidatorFunctionWr
                 registered_keys = GlobalTypeRegistry.get().get_registered_front_ends()
             elif (info.field_name == "ttc_strategies"):
                 registered_keys = GlobalTypeRegistry.get().get_registered_ttc_strategies()
+            elif (info.field_name == "middleware"):
+                registered_keys = GlobalTypeRegistry.get().get_registered_middleware()
 
             else:
                 assert False, f"Unknown field name {info.field_name} in validator"
@@ -253,6 +256,9 @@ class Config(HashableBaseModel):
     # Function Groups Configuration
     function_groups: dict[str, FunctionGroupBaseConfig] = Field(default_factory=dict)
 
+    # Middleware Configuration
+    middleware: dict[str, FunctionMiddlewareBaseConfig] = Field(default_factory=dict)
+
     # LLMs Configuration
     llms: dict[str, LLMBaseConfig] = Field(default_factory=dict)
 
@@ -303,6 +309,7 @@ class Config(HashableBaseModel):
 
     @field_validator("functions",
                      "function_groups",
+                     "middleware",
                      "llms",
                      "embedders",
                      "memory",
@@ -348,6 +355,10 @@ class Config(HashableBaseModel):
                                         typing.Annotated[type_registry.compute_annotation(FunctionGroupBaseConfig),
                                                          Discriminator(TypedBaseModel.discriminator)]]
 
+        MiddlewareAnnotation = dict[str,
+                                    typing.Annotated[type_registry.compute_annotation(FunctionMiddlewareBaseConfig),
+                                                     Discriminator(TypedBaseModel.discriminator)]]
+
         MemoryAnnotation = dict[str,
                                 typing.Annotated[type_registry.compute_annotation(MemoryBaseConfig),
                                                  Discriminator(TypedBaseModel.discriminator)]]
@@ -393,6 +404,11 @@ class Config(HashableBaseModel):
             function_groups_field.annotation = FunctionGroupsAnnotation
             should_rebuild = True
 
+        middleware_field = cls.model_fields.get("middleware")
+        if (middleware_field is not None and middleware_field.annotation != MiddlewareAnnotation):
+            middleware_field.annotation = MiddlewareAnnotation
+            should_rebuild = True
+
         memory_field = cls.model_fields.get("memory")
         if memory_field is not None and memory_field.annotation != MemoryAnnotation:
             memory_field.annotation = MemoryAnnotation

nat/data_models/function.py

@@ -24,7 +24,16 @@ from .common import TypedBaseModel
 
 
 class FunctionBaseConfig(TypedBaseModel, BaseModelRegistryTag):
-    pass
+    """Base configuration for functions.
+
+    Attributes:
+        middleware: List of function middleware names to apply to this function.
+            These must match names defined in the `middleware` section of the YAML configuration.
+    """
+    middleware: list[str] = Field(
+        default_factory=list,
+        description="List of function middleware names to apply to this function in order",
+    )
 
 
 class FunctionGroupBaseConfig(TypedBaseModel, BaseModelRegistryTag):
@@ -40,6 +49,10 @@ class FunctionGroupBaseConfig(TypedBaseModel, BaseModelRegistryTag):
         default_factory=list,
         description="The list of function names which should be excluded from default access to the group",
     )
+    middleware: list[str] = Field(
+        default_factory=list,
+        description="List of function middleware names to apply to all functions in this group",
+    )
 
     @field_validator("include", "exclude")
     @classmethod

nat/data_models/middleware.py

@@ -0,0 +1,35 @@
+# 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 .common import BaseModelRegistryTag
+from .common import TypedBaseModel
+
+
+class MiddlewareBaseConfig(TypedBaseModel, BaseModelRegistryTag):
+    """The base level config object for middleware.
+
+    Middleware provides middleware-style wrapping of calls with
+    preprocessing and postprocessing logic.
+    """
+    pass
+
+
+MiddlewareBaseConfigT = typing.TypeVar("MiddlewareBaseConfigT", bound=MiddlewareBaseConfig)
+
+# Specialized type for function-specific middleware
+FunctionMiddlewareBaseConfig = MiddlewareBaseConfig
+FunctionMiddlewareBaseConfigT = MiddlewareBaseConfigT

nat/data_models/runtime_enum.py

@@ -0,0 +1,26 @@
+# 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 enum
+
+
+class RuntimeTypeEnum(str, enum.Enum):
+    """
+    Enum representing different runtime types.
+    """
+
+    RUN_OR_SERVE = "run_or_serve"
+    EVALUATE = "evaluate"
+    OTHER = "other"

nat/eval/evaluate.py

@@ -16,6 +16,7 @@
 import asyncio
 import logging
 import shutil
+import warnings
 from pathlib import Path
 from typing import Any
 from uuid import uuid4
@@ -25,6 +26,7 @@ from tqdm import tqdm
 
 from nat.data_models.evaluate import EvalConfig
 from nat.data_models.evaluate import JobEvictionPolicy
+from nat.data_models.runtime_enum import RuntimeTypeEnum
 from nat.eval.config import EvaluationRunConfig
 from nat.eval.config import EvaluationRunOutput
 from nat.eval.dataset_handler.dataset_handler import DatasetHandler
@@ -67,7 +69,13 @@ class EvaluationRun:
         # Create evaluation trace context
         try:
             from nat.eval.utils.eval_trace_ctx import WeaveEvalTraceContext
-            self.eval_trace_context = WeaveEvalTraceContext()
+            with warnings.catch_warnings():
+                # Ignore deprecation warnings being triggered by weave. https://github.com/wandb/weave/issues/3666
+                warnings.filterwarnings("ignore",
+                                        category=DeprecationWarning,
+                                        message=r"`sentry_sdk\.Hub` is deprecated")
+
+                self.eval_trace_context = WeaveEvalTraceContext()
         except Exception:
             from nat.eval.utils.eval_trace_ctx import EvalTraceContext
             self.eval_trace_context = EvalTraceContext()
@@ -161,7 +169,7 @@ class EvaluationRun:
             if stop_event.is_set():
                 return "", []
 
-            async with session_manager.run(item.input_obj) as runner:
+            async with session_manager.run(item.input_obj, runtime_type=RuntimeTypeEnum.EVALUATE) as runner:
                 if not session_manager.workflow.has_single_output:
                     # raise an error if the workflow has multiple outputs
                     raise NotImplementedError("Multiple outputs are not supported")

nat/front_ends/fastapi/fastapi_front_end_config.py

@@ -27,6 +27,8 @@ from pydantic import field_validator
 from nat.data_models.component_ref import ObjectStoreRef
 from nat.data_models.front_end import FrontEndBaseConfig
 from nat.data_models.step_adaptor import StepAdaptorConfig
+from nat.eval.evaluator.evaluator_model import EvalInputItem
+from nat.eval.evaluator.evaluator_model import EvalOutputItem
 
 logger = logging.getLogger(__name__)
 
@@ -133,6 +135,19 @@ class AsyncGenerationStatusResponse(BaseAsyncStatusResponse):
         description="Output of the generate request, this is only available if the job completed successfully.")
 
 
+class EvaluateItemRequest(BaseModel):
+    """Request model for single-item evaluation endpoint."""
+    item: EvalInputItem = Field(description="Single evaluation input item to evaluate")
+    evaluator_name: str = Field(description="Name of the evaluator to use (must match config)")
+
+
+class EvaluateItemResponse(BaseModel):
+    """Response model for single-item evaluation endpoint."""
+    success: bool = Field(description="Whether the evaluation completed successfully")
+    result: EvalOutputItem | None = Field(default=None, description="Evaluation result if successful")
+    error: str | None = Field(default=None, description="Error message if evaluation failed")
+
+
 class FastApiFrontEndConfig(FrontEndBaseConfig, name="fastapi"):
     """
     A FastAPI based front end that allows a NAT workflow to be served as a microservice.
@@ -239,6 +254,13 @@ class FastApiFrontEndConfig(FrontEndBaseConfig, name="fastapi"):
         description="Evaluates the performance and accuracy of the workflow on a dataset",
     )
 
+    evaluate_item: typing.Annotated[EndpointBase,
+                                    Field(description="Endpoint for evaluating a single item.")] = EndpointBase(
+                                        method="POST",
+                                        path="/evaluate/item",
+                                        description="Evaluate a single item with a specified evaluator",
+                                    )
+
     oauth2_callback_path: str | None = Field(
         default="/auth/redirect",
         description="OAuth2.0 authentication callback endpoint. If None, no OAuth2 callback endpoint is created.")

nat/front_ends/fastapi/fastapi_front_end_plugin_worker.py

@@ -39,6 +39,8 @@ from pydantic import BaseModel
 from pydantic import Field
 from starlette.websockets import WebSocket
 
+from nat.builder.eval_builder import WorkflowEvalBuilder
+from nat.builder.evaluator import EvaluatorInfo
 from nat.builder.function import Function
 from nat.builder.workflow_builder import WorkflowBuilder
 from nat.data_models.api_server import ChatRequest
@@ -51,11 +53,14 @@ from nat.data_models.object_store import NoSuchKeyError
 from nat.eval.config import EvaluationRunOutput
 from nat.eval.evaluate import EvaluationRun
 from nat.eval.evaluate import EvaluationRunConfig
+from nat.eval.evaluator.evaluator_model import EvalInput
 from nat.front_ends.fastapi.auth_flow_handlers.http_flow_handler import HTTPAuthenticationFlowHandler
 from nat.front_ends.fastapi.auth_flow_handlers.websocket_flow_handler import FlowState
 from nat.front_ends.fastapi.auth_flow_handlers.websocket_flow_handler import WebSocketAuthenticationFlowHandler
 from nat.front_ends.fastapi.fastapi_front_end_config import AsyncGenerateResponse
 from nat.front_ends.fastapi.fastapi_front_end_config import AsyncGenerationStatusResponse
+from nat.front_ends.fastapi.fastapi_front_end_config import EvaluateItemRequest
+from nat.front_ends.fastapi.fastapi_front_end_config import EvaluateItemResponse
 from nat.front_ends.fastapi.fastapi_front_end_config import EvaluateRequest
 from nat.front_ends.fastapi.fastapi_front_end_config import EvaluateResponse
 from nat.front_ends.fastapi.fastapi_front_end_config import EvaluateStatusResponse
@@ -227,6 +232,54 @@ class FastApiFrontEndPluginWorker(FastApiFrontEndPluginWorkerBase):
         self._outstanding_flows: dict[str, FlowState] = {}
         self._outstanding_flows_lock = asyncio.Lock()
 
+        # Evaluator storage for single-item evaluation
+        self._evaluators: dict[str, EvaluatorInfo] = {}
+        self._eval_builder: WorkflowEvalBuilder | None = None
+
+    async def initialize_evaluators(self, config: Config):
+        """Initialize and store evaluators from config for single-item evaluation."""
+        if not config.eval or not config.eval.evaluators:
+            logger.info("No evaluators configured, skipping evaluator initialization")
+            return
+
+        try:
+            # Build evaluators using WorkflowEvalBuilder (same pattern as nat eval)
+            # Start with registry=None and let populate_builder set everything up
+            self._eval_builder = WorkflowEvalBuilder(general_config=config.general,
+                                                     eval_general_config=config.eval.general,
+                                                     registry=None)
+
+            # Enter the async context and keep it alive
+            await self._eval_builder.__aenter__()
+
+            # Populate builder with config (this sets up LLMs, functions, etc.)
+            # Skip workflow build since we already have it from the main builder
+            await self._eval_builder.populate_builder(config, skip_workflow=True)
+
+            # Now evaluators should be populated by populate_builder
+            for name in config.eval.evaluators.keys():
+                self._evaluators[name] = self._eval_builder.get_evaluator(name)
+                logger.info(f"Initialized evaluator: {name}")
+
+            logger.info(f"Successfully initialized {len(self._evaluators)} evaluators")
+
+        except Exception as e:
+            logger.error(f"Failed to initialize evaluators: {e}")
+            # Don't fail startup, just log the error
+            self._evaluators = {}
+
+    async def cleanup_evaluators(self):
+        """Clean up evaluator resources on shutdown."""
+        if self._eval_builder:
+            try:
+                await self._eval_builder.__aexit__(None, None, None)
+                logger.info("Evaluator builder context cleaned up")
+            except Exception as e:
+                logger.error(f"Error cleaning up evaluator builder: {e}")
+            finally:
+                self._eval_builder = None
+                self._evaluators.clear()
+
     def get_step_adaptor(self) -> StepAdaptor:
 
         return StepAdaptor(self.front_end_config.step_adaptor)
@@ -236,12 +289,20 @@ class FastApiFrontEndPluginWorker(FastApiFrontEndPluginWorkerBase):
         # Do things like setting the base URL and global configuration options
         app.root_path = self.front_end_config.root_path
 
+        # Initialize evaluators for single-item evaluation
+        # TODO: we need config control over this as it's not always needed
+        await self.initialize_evaluators(self._config)
+
+        # Ensure evaluator resources are cleaned up when the app shuts down
+        app.add_event_handler("shutdown", self.cleanup_evaluators)
+
         await self.add_routes(app, builder)
 
     async def add_routes(self, app: FastAPI, builder: WorkflowBuilder):
 
         await self.add_default_route(app, SessionManager(await builder.build()))
         await self.add_evaluate_route(app, SessionManager(await builder.build()))
+        await self.add_evaluate_item_route(app, SessionManager(await builder.build()))
         await self.add_static_files_route(app, builder)
         await self.add_authorization_route(app)
         await self.add_mcp_client_tool_list_route(app, builder)
@@ -439,6 +500,69 @@ class FastApiFrontEndPluginWorker(FastApiFrontEndPluginWorkerBase):
             else:
                 logger.warning("Dask is not available, evaluation endpoints will not be added.")
 
+    async def add_evaluate_item_route(self, app: FastAPI, session_manager: SessionManager):
+        """Add the single-item evaluation endpoint to the FastAPI app."""
+
+        async def evaluate_single_item(request: EvaluateItemRequest, http_request: Request) -> EvaluateItemResponse:
+            """Handle single-item evaluation requests."""
+
+            async with session_manager.session(http_connection=http_request):
+
+                # Check if evaluator exists
+                if request.evaluator_name not in self._evaluators:
+                    raise HTTPException(status_code=404,
+                                        detail=f"Evaluator '{request.evaluator_name}' not found. "
+                                        f"Available evaluators: {list(self._evaluators.keys())}")
+
+                try:
+                    # Get the evaluator
+                    evaluator = self._evaluators[request.evaluator_name]
+
+                    # Run evaluation on single item
+                    result = await evaluator.evaluate_fn(EvalInput(eval_input_items=[request.item]))
+
+                    # Extract the single output item
+                    if result.eval_output_items:
+                        output_item = result.eval_output_items[0]
+                        return EvaluateItemResponse(success=True, result=output_item, error=None)
+                    else:
+                        return EvaluateItemResponse(success=False, result=None, error="Evaluator returned no results")
+
+                except Exception as e:
+                    logger.exception(f"Error evaluating item with {request.evaluator_name}")
+                    return EvaluateItemResponse(success=False, result=None, error=f"Evaluation failed: {str(e)}")
+
+        # Register the route
+        if self.front_end_config.evaluate_item.path:
+            app.add_api_route(path=self.front_end_config.evaluate_item.path,
+                              endpoint=evaluate_single_item,
+                              methods=[self.front_end_config.evaluate_item.method],
+                              response_model=EvaluateItemResponse,
+                              description=self.front_end_config.evaluate_item.description,
+                              responses={
+                                  404: {
+                                      "description": "Evaluator not found",
+                                      "content": {
+                                          "application/json": {
+                                              "example": {
+                                                  "detail": "Evaluator 'unknown' not found"
+                                              }
+                                          }
+                                      }
+                                  },
+                                  500: {
+                                      "description": "Internal Server Error",
+                                      "content": {
+                                          "application/json": {
+                                              "example": {
+                                                  "detail": "Internal server error occurred"
+                                              }
+                                          }
+                                      }
+                                  }
+                              })
+            logger.info(f"Added evaluate_item route at {self.front_end_config.evaluate_item.path}")
+
     async def add_static_files_route(self, app: FastAPI, builder: WorkflowBuilder):
 
         if not self.front_end_config.object_store:

nat/front_ends/mcp/mcp_front_end_plugin.py

@@ -140,6 +140,10 @@ class MCPFrontEndPlugin(FrontEndBase[MCPFrontEndConfig]):
         # Mount the MCP server's ASGI app at the configured base_path
         app.mount(self.front_end_config.base_path, mcp.streamable_http_app())
 
+        # Allow plugins to add routes to the wrapper app (e.g., OAuth discovery endpoints)
+        worker = self._get_worker_instance()
+        await worker.add_root_level_routes(app, mcp)
+
         # Configure and start uvicorn server
         config = uvicorn.Config(
             app,

nat/front_ends/mcp/mcp_front_end_plugin_worker.py

@@ -17,12 +17,16 @@ import logging
 from abc import ABC
 from abc import abstractmethod
 from collections.abc import Mapping
+from typing import TYPE_CHECKING
 from typing import Any
 
 from mcp.server.fastmcp import FastMCP
 from starlette.exceptions import HTTPException
 from starlette.requests import Request
 
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
 from nat.builder.function import Function
 from nat.builder.function_base import FunctionBase
 from nat.builder.workflow import Workflow
@@ -192,6 +196,28 @@ class MCPFrontEndPluginWorkerBase(ABC):
 
         return functions
 
+    async def add_root_level_routes(self, wrapper_app: "FastAPI", mcp: FastMCP) -> None:
+        """Add routes to the wrapper FastAPI app (optional extension point).
+
+        This method is called when base_path is configured and a wrapper
+        FastAPI app is created to mount the MCP server. Plugins can override
+        this to add routes to the wrapper app at the root level, outside the
+        mounted MCP server path.
+
+        Common use cases:
+        - OAuth discovery endpoints (e.g., /.well-known/oauth-protected-resource)
+        - Health checks at root level
+        - Static file serving
+        - Custom authentication/authorization endpoints
+
+        Default implementation does nothing, making this an optional extension point.
+
+        Args:
+            wrapper_app: The FastAPI wrapper application that mounts the MCP server
+            mcp: The FastMCP server instance (already mounted at base_path)
+        """
+        pass  # Default: no additional root-level routes
+
     def _setup_debug_endpoints(self, mcp: FastMCP, functions: Mapping[str, FunctionBase]) -> None:
         """Set up HTTP debug endpoints for introspecting tools and schemas.
 

nat/middleware/__init__.py

@@ -0,0 +1,35 @@
+# 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.
+"""Middleware implementations for NeMo Agent Toolkit."""
+
+from nat.middleware.cache_middleware import CacheMiddleware
+from nat.middleware.function_middleware import FunctionMiddleware
+from nat.middleware.function_middleware import FunctionMiddlewareChain
+from nat.middleware.function_middleware import validate_middleware
+from nat.middleware.middleware import CallNext
+from nat.middleware.middleware import CallNextStream
+from nat.middleware.middleware import FunctionMiddlewareContext
+from nat.middleware.middleware import Middleware
+
+__all__ = [
+    "CacheMiddleware",
+    "CallNext",
+    "CallNextStream",
+    "FunctionMiddlewareContext",
+    "Middleware",
+    "FunctionMiddleware",
+    "FunctionMiddlewareChain",
+    "validate_middleware",
+]