nvidia-nat 1.3.0a20250904__py3-none-any.whl → 1.3.0a20250906__py3-none-any.whl

nat/cli/commands/workflow/templates/pyproject.toml.j2

@@ -14,7 +14,7 @@ name = "{{ package_name }}"
 dependencies = [
   "{{ nat_dependency }}",
 ]
-requires-python = ">=3.11,<3.13"
+requires-python = ">=3.11,<3.14"
 description = "Custom NeMo Agent Toolkit Workflow"
 classifiers = ["Programming Language :: Python"]
 

nat/eval/utils/weave_eval.py

@@ -44,11 +44,9 @@ class WeaveEvaluationIntegration:
         self.eval_trace_context = eval_trace_context
 
         try:
-            from weave.flow.eval_imperative import EvaluationLogger
-            from weave.flow.eval_imperative import ScoreLogger
+            from weave import EvaluationLogger
             from weave.trace.context import weave_client_context
             self.evaluation_logger_cls = EvaluationLogger
-            self.score_logger_cls = ScoreLogger
             self.weave_client_context = weave_client_context
             self.available = True
         except ImportError:
@@ -94,7 +92,10 @@ class WeaveEvaluationIntegration:
             weave_dataset = self._get_weave_dataset(eval_input)
             config_dict = config.model_dump(mode="json")
             config_dict["name"] = workflow_alias
-            self.eval_logger = self.evaluation_logger_cls(model=config_dict, dataset=weave_dataset)
+            self.eval_logger = self.evaluation_logger_cls(model=config_dict,
+                                                          dataset=weave_dataset,
+                                                          name=workflow_alias,
+                                                          eval_attributes={})
             self.pred_loggers = {}
 
             # Capture the current evaluation call for context propagation
@@ -189,3 +190,4 @@ class WeaveEvaluationIntegration:
         # Log the summary to finish the evaluation, disable auto-summarize
         # as we will be adding profiler metrics to the summary
         self.eval_logger.log_summary(summary, auto_summarize=False)
+        logger.info("Logged Evaluation Summary to Weave")

nat/front_ends/fastapi/fastapi_front_end_config.py

@@ -14,6 +14,8 @@
 # limitations under the License.
 
 import logging
+import os
+import sys
 import typing
 from datetime import datetime
 from pathlib import Path
@@ -31,6 +33,20 @@ logger = logging.getLogger(__name__)
 YAML_EXTENSIONS = (".yaml", ".yml")
 
 
+def _is_reserved(path: Path) -> bool:
+    """
+    Check if a path is reserved in the current Python version and platform.
+
+    On Windows, this function checks if the path is reserved in the current Python version.
+    On other platforms, returns False
+    """
+    if sys.platform != "win32":
+        return False
+    if sys.version_info >= (3, 13):
+        return os.path.isreserved(path)
+    return path.is_reserved()
+
+
 class EvaluateRequest(BaseModel):
     """Request model for the evaluate endpoint."""
     config_file: str = Field(description="Path to the configuration file for evaluation")
@@ -51,7 +67,7 @@ class EvaluateRequest(BaseModel):
                 f"Job ID '{job_id}' contains invalid characters. Only alphanumeric characters and underscores are"
                 " allowed.")
 
-        if job_id_path.is_reserved():
+        if _is_reserved(job_id_path):
             # reserved names is Windows specific
             raise ValueError(f"Job ID '{job_id}' is a reserved name. Please choose a different name.")
 
@@ -68,7 +84,7 @@ class EvaluateRequest(BaseModel):
             raise ValueError(f"Config file '{config_file}' must be a YAML file with one of the following extensions: "
                              f"{', '.join(YAML_EXTENSIONS)}")
 
-        if config_file_path.is_reserved():
+        if _is_reserved(config_file_path):
             # reserved names is Windows specific
             raise ValueError(f"Config file '{config_file}' is a reserved name. Please choose a different name.")
 

nat/observability/exporter/processing_exporter.py

@@ -50,46 +50,74 @@ class ProcessingExporter(Generic[PipelineInputT, PipelineOutputT], BaseExporter,
     - Processor pipeline management (add, remove, clear)
     - Type compatibility validation between processors
     - Pipeline processing with error handling
+    - Configurable None filtering: processors returning None can drop items from pipeline
     - Automatic type validation before export
     """
 
-    def __init__(self, context_state: ContextState | None = None):
+    def __init__(self, context_state: ContextState | None = None, drop_nones: bool = True):
         """Initialize the processing exporter.
 
         Args:
-            context_state: The context state to use for the exporter.
+            context_state (ContextState | None): The context state to use for the exporter.
+            drop_nones (bool): Whether to drop items when processors return None (default: True).
         """
         super().__init__(context_state)
         self._processors: list[Processor] = []  # List of processors that implement process(item) -> item
-
-    def add_processor(self, processor: Processor) -> None:
+        self._processor_names: dict[str, int] = {}  # Maps processor names to their positions
+        self._pipeline_locked: bool = False  # Prevents modifications after startup
+        self._drop_nones: bool = drop_nones  # Whether to drop None values between processors
+
+    def add_processor(self,
+                      processor: Processor,
+                      name: str | None = None,
+                      position: int | None = None,
+                      before: str | None = None,
+                      after: str | None = None) -> None:
         """Add a processor to the processing pipeline.
 
-        Processors are executed in the order they are added.
-        Processors can transform between any types (T -> U).
+        Processors are executed in the order they are added. Processes can transform between any types (T -> U).
+        Supports flexible positioning using names, positions, or relative placement.
 
         Args:
-            processor: The processor to add to the pipeline
+            processor (Processor): The processor to add to the pipeline
+            name (str | None): Name for the processor (for later reference). Must be unique.
+            position (int | None): Specific position to insert at (0-based index, -1 for append)
+            before (str | None): Insert before the named processor
+            after (str | None): Insert after the named processor
+
+        Raises:
+            RuntimeError: If pipeline is locked (after startup)
+            ValueError: If positioning arguments conflict or named processor not found
         """
+        self._check_pipeline_locked()
 
-        # Check if the processor is compatible with the last processor in the pipeline
-        if len(self._processors) > 0:
-            try:
-                if not issubclass(processor.input_class, self._processors[-1].output_class):
-                    raise ValueError(f"Processor {processor.__class__.__name__} input type {processor.input_type} "
-                                     f"is not compatible with the {self._processors[-1].__class__.__name__} "
-                                     f"output type {self._processors[-1].output_type}")
-            except TypeError:
-                # Handle cases where input_class or output_class are generic types that can't be used with issubclass
-                # Fall back to type comparison for generic types
-                logger.warning(
-                    "Cannot use issubclass() for type compatibility check between "
-                    "%s (%s) and %s (%s). Skipping compatibility check.",
-                    processor.__class__.__name__,
-                    processor.input_type,
-                    self._processors[-1].__class__.__name__,
-                    self._processors[-1].output_type)
-        self._processors.append(processor)
+        # Determine insertion position
+        insert_position = self._calculate_insertion_position(position, before, after)
+
+        # Validate type compatibility at insertion point
+        self._validate_insertion_compatibility(processor, insert_position)
+
+        # Pre-validate name (no side effects yet)
+        if name is not None:
+            if not isinstance(name, str):
+                raise TypeError(f"Processor name must be a string, got {type(name).__name__}")
+            if name in self._processor_names:
+                raise ValueError(f"Processor name '{name}' already exists")
+
+        # Shift existing name positions (do this before list mutation)
+        for proc_name, pos in list(self._processor_names.items()):
+            if pos >= insert_position:
+                self._processor_names[proc_name] = pos + 1
+
+        # Insert the processor
+        if insert_position == len(self._processors):
+            self._processors.append(processor)
+        else:
+            self._processors.insert(insert_position, processor)
+
+        # Record the new processor name, if provided
+        if name is not None:
+            self._processor_names[name] = insert_position
 
         # Set up pipeline continuation callback for processors that support it
         if isinstance(processor, CallbackProcessor):
@@ -99,27 +127,231 @@ class ProcessingExporter(Generic[PipelineInputT, PipelineOutputT], BaseExporter,
 
             processor.set_done_callback(pipeline_callback)
 
-    def remove_processor(self, processor: Processor) -> None:
+    def remove_processor(self, processor: Processor | str | int) -> None:
         """Remove a processor from the processing pipeline.
 
         Args:
-            processor: The processor to remove from the pipeline
+            processor (Processor | str | int): The processor to remove (by name, position, or object).
+
+        Raises:
+            RuntimeError: If pipeline is locked (after startup)
+            ValueError: If named processor or position not found
+            TypeError: If processor argument has invalid type
         """
-        if processor in self._processors:
-            self._processors.remove(processor)
+        self._check_pipeline_locked()
+
+        # Determine processor and position to remove
+        if isinstance(processor, str):
+            # Remove by name
+            if processor not in self._processor_names:
+                raise ValueError(f"Processor '{processor}' not found in pipeline")
+            position = self._processor_names[processor]
+            processor_obj = self._processors[position]
+        elif isinstance(processor, int):
+            # Remove by position
+            if not (0 <= processor < len(self._processors)):
+                raise ValueError(f"Position {processor} is out of range [0, {len(self._processors) - 1}]")
+            position = processor
+            processor_obj = self._processors[position]
+        elif isinstance(processor, Processor):
+            # Remove by object (existing behavior)
+            if processor not in self._processors:
+                return  # Silently ignore if not found (existing behavior)
+            position = self._processors.index(processor)
+            processor_obj = processor
+        else:
+            raise TypeError(f"Processor must be a Processor object, string name, or int position, "
+                            f"got {type(processor).__name__}")
+
+        # Remove the processor
+        self._processors.remove(processor_obj)
+
+        # Remove from name mapping and update positions
+        name_to_remove = None
+        for name, pos in self._processor_names.items():
+            if pos == position:
+                name_to_remove = name
+                break
+
+        if name_to_remove:
+            del self._processor_names[name_to_remove]
+
+        # Update positions for processors that shifted
+        for name, pos in self._processor_names.items():
+            if pos > position:
+                self._processor_names[name] = pos - 1
 
     def clear_processors(self) -> None:
         """Clear all processors from the pipeline."""
+        self._check_pipeline_locked()
         self._processors.clear()
+        self._processor_names.clear()
+
+    def reset_pipeline(self) -> None:
+        """Reset the pipeline to allow modifications.
+
+        This unlocks the pipeline and clears all processors, allowing
+        the pipeline to be reconfigured. Can only be called when the
+        exporter is stopped.
+
+        Raises:
+            RuntimeError: If exporter is currently running
+        """
+        if self._running:
+            raise RuntimeError("Cannot reset pipeline while exporter is running. "
+                               "Call stop() first, then reset_pipeline().")
+
+        self._pipeline_locked = False
+        self._processors.clear()
+        self._processor_names.clear()
+        logger.debug("Pipeline reset - unlocked and cleared all processors")
+
+    def get_processor_by_name(self, name: str) -> Processor | None:
+        """Get a processor by its name.
+
+        Args:
+            name (str): The name of the processor to retrieve
+
+        Returns:
+            Processor | None: The processor with the given name, or None if not found
+        """
+        if not isinstance(name, str):
+            raise TypeError(f"Processor name must be a string, got {type(name).__name__}")
+        if name in self._processor_names:
+            position = self._processor_names[name]
+            return self._processors[position]
+        logger.debug("Processor '%s' not found in pipeline", name)
+        return None
+
+    def _check_pipeline_locked(self) -> None:
+        """Check if pipeline is locked and raise error if it is."""
+        if self._pipeline_locked:
+            raise RuntimeError("Cannot modify processor pipeline after exporter has started. "
+                               "Pipeline must be fully configured before calling start().")
+
+    def _calculate_insertion_position(self, position: int | None, before: str | None, after: str | None) -> int:
+        """Calculate the insertion position based on provided arguments.
+
+        Args:
+            position (int | None): Explicit position (0-based index, -1 for append)
+            before (str | None): Insert before this named processor
+            after (str | None): Insert after this named processor
+
+        Returns:
+            int: The calculated insertion position
+
+        Raises:
+            ValueError: If arguments conflict or named processor not found
+        """
+        # Check for conflicting arguments
+        args_provided = sum(x is not None for x in [position, before, after])
+        if args_provided > 1:
+            raise ValueError("Only one of position, before, or after can be specified")
+
+        # Default to append
+        if args_provided == 0:
+            return len(self._processors)
+
+        # Handle explicit position
+        if position is not None:
+            if position == -1:
+                return len(self._processors)
+            if 0 <= position <= len(self._processors):
+                return position
+            raise ValueError(f"Position {position} is out of range [0, {len(self._processors)}]")
+
+        # Handle before/after named processors
+        if before is not None:
+            if not isinstance(before, str):
+                raise TypeError(f"'before' parameter must be a string, got {type(before).__name__}")
+            if before not in self._processor_names:
+                raise ValueError(f"Processor '{before}' not found in pipeline")
+            return self._processor_names[before]
+
+        if after is not None:
+            if not isinstance(after, str):
+                raise TypeError(f"'after' parameter must be a string, got {type(after).__name__}")
+            if after not in self._processor_names:
+                raise ValueError(f"Processor '{after}' not found in pipeline")
+            return self._processor_names[after] + 1
+
+        # Should never reach here
+        return len(self._processors)
+
+    def _validate_insertion_compatibility(self, processor: Processor, position: int) -> None:
+        """Validate type compatibility for processor insertion.
+
+        Args:
+            processor (Processor): The processor to insert
+            position (int): The position where it will be inserted
+
+        Raises:
+            ValueError: If processor is not compatible with neighbors
+        """
+        # Check compatibility with neighbors
+        if position > 0:
+            predecessor = self._processors[position - 1]
+            self._check_processor_compatibility(predecessor,
+                                                processor,
+                                                "predecessor",
+                                                predecessor.output_class,
+                                                processor.input_class,
+                                                str(predecessor.output_type),
+                                                str(processor.input_type))
+
+        if position < len(self._processors):
+            successor = self._processors[position]
+            self._check_processor_compatibility(processor,
+                                                successor,
+                                                "successor",
+                                                processor.output_class,
+                                                successor.input_class,
+                                                str(processor.output_type),
+                                                str(successor.input_type))
+
+    def _check_processor_compatibility(self,
+                                       source_processor: Processor,
+                                       target_processor: Processor,
+                                       relationship: str,
+                                       source_class: type,
+                                       target_class: type,
+                                       source_type: str,
+                                       target_type: str) -> None:
+        """Check type compatibility between two processors.
+
+        Args:
+            source_processor (Processor): The processor providing output
+            target_processor (Processor): The processor receiving input
+            relationship (str): Description of relationship ("predecessor" or "successor")
+            source_class (type): The output class of source processor
+            target_class (type): The input class of target processor
+            source_type (str): String representation of source type
+            target_type (str): String representation of target type
+        """
+        try:
+            if not issubclass(source_class, target_class):
+                raise ValueError(f"Processor {target_processor.__class__.__name__} input type {target_type} "
+                                 f"is not compatible with {relationship} {source_processor.__class__.__name__} "
+                                 f"output type {source_type}")
+        except TypeError:
+            logger.warning(
+                "Cannot use issubclass() for type compatibility check between "
+                "%s (%s) and %s (%s). Skipping compatibility check.",
+                source_processor.__class__.__name__,
+                source_type,
+                target_processor.__class__.__name__,
+                target_type)
 
     async def _pre_start(self) -> None:
+
+        # Validate that the pipeline is compatible with the exporter
         if len(self._processors) > 0:
             first_processor = self._processors[0]
             last_processor = self._processors[-1]
 
             # validate that the first processor's input type is compatible with the exporter's input type
             try:
-                if not issubclass(first_processor.input_class, self.input_class):
+                if not issubclass(self.input_class, first_processor.input_class):
                     raise ValueError(f"Processor {first_processor.__class__.__name__} input type "
                                      f"{first_processor.input_type} is not compatible with the "
                                      f"{self.input_type} input type")
@@ -149,14 +381,17 @@ class ProcessingExporter(Generic[PipelineInputT, PipelineOutputT], BaseExporter,
                     self.output_type,
                     e)
 
-    async def _process_pipeline(self, item: PipelineInputT) -> PipelineOutputT:
+        # Lock the pipeline to prevent further modifications
+        self._pipeline_locked = True
+
+    async def _process_pipeline(self, item: PipelineInputT) -> PipelineOutputT | None:
         """Process item through all registered processors.
 
         Args:
             item (PipelineInputT): The item to process (starts as PipelineInputT, can transform to PipelineOutputT)
 
         Returns:
-            PipelineOutputT: The processed item after running through all processors
+            PipelineOutputT | None: The processed item after running through all processors
         """
         return await self._process_through_processors(self._processors, item)  # type: ignore
 
@@ -168,12 +403,18 @@ class ProcessingExporter(Generic[PipelineInputT, PipelineOutputT], BaseExporter,
             item (Any): The item to process
 
         Returns:
-            The processed item after running through all processors
+            Any: The processed item after running through all processors, or None if
+                drop_nones is True and any processor returned None
         """
         processed_item = item
         for processor in processors:
             try:
                 processed_item = await processor.process(processed_item)
+                # Drop None values between processors if configured to do so
+                if self._drop_nones and processed_item is None:
+                    logger.debug("Processor %s returned None, dropping item from pipeline",
+                                 processor.__class__.__name__)
+                    return None
             except Exception as e:
                 logger.exception("Error in processor %s: %s", processor.__class__.__name__, e)
                 # Continue with unprocessed item rather than failing
@@ -221,6 +462,11 @@ class ProcessingExporter(Generic[PipelineInputT, PipelineOutputT], BaseExporter,
             remaining_processors = self._processors[source_index + 1:]
             processed_item = await self._process_through_processors(remaining_processors, item)
 
+            # Skip export if remaining pipeline dropped the item (returned None)
+            if processed_item is None:
+                logger.debug("Item was dropped by remaining processor pipeline, skipping export")
+                return
+
             # Export the final result
             await self._export_final_item(processed_item)
 
@@ -233,11 +479,16 @@ class ProcessingExporter(Generic[PipelineInputT, PipelineOutputT], BaseExporter,
         """Export an item after processing it through the pipeline.
 
         Args:
-            item: The item to export
+            item (PipelineInputT): The item to export
         """
         try:
             # Then, run through the processor pipeline
-            final_item: PipelineOutputT = await self._process_pipeline(item)
+            final_item: PipelineOutputT | None = await self._process_pipeline(item)
+
+            # Skip export if pipeline dropped the item (returned None)
+            if final_item is None:
+                logger.debug("Item was dropped by processor pipeline, skipping export")
+                return
 
             # Handle different output types from batch processors
             if isinstance(final_item, list) and len(final_item) == 0:
@@ -276,12 +527,16 @@ class ProcessingExporter(Generic[PipelineInputT, PipelineOutputT], BaseExporter,
         the actual export logic after the item has been processed through the pipeline.
 
         Args:
-            item: The processed item to export (PipelineOutputT type)
+            item (PipelineOutputT | list[PipelineOutputT]): The processed item to export (PipelineOutputT type)
         """
         pass
 
-    def _create_export_task(self, coro: Coroutine):
-        """Create task with minimal overhead but proper tracking."""
+    def _create_export_task(self, coro: Coroutine) -> None:
+        """Create task with minimal overhead but proper tracking.
+
+        Args:
+            coro: The coroutine to create a task for
+        """
         if not self._running:
             logger.warning("%s: Attempted to create export task while not running", self.name)
             return
@@ -296,7 +551,7 @@ class ProcessingExporter(Generic[PipelineInputT, PipelineOutputT], BaseExporter,
             raise
 
     @override
-    async def _cleanup(self):
+    async def _cleanup(self) -> None:
         """Enhanced cleanup that shuts down all shutdown-aware processors.
 
         Each processor is responsible for its own cleanup, including routing

nat/observability/mixin/redaction_config_mixin.py

@@ -0,0 +1,41 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-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.
+
+from pydantic import BaseModel
+from pydantic import Field
+
+
+class RedactionConfigMixin(BaseModel):
+    """Mixin for basic redaction configuration.
+
+    Provides core redaction functionality that can be used standalone
+    or inherited by specialized redaction mixins.
+    """
+    redaction_enabled: bool = Field(default=False, description="Whether to enable redaction processing.")
+    redaction_value: str = Field(default="[REDACTED]", description="Value to replace redacted attributes with.")
+    redaction_attributes: list[str] = Field(default_factory=lambda: ["input.value", "output.value", "metadata"],
+                                            description="Span attributes to redact when redaction is triggered.")
+    force_redaction: bool = Field(default=False, description="Always redact regardless of other conditions.")
+
+
+class HeaderRedactionConfigMixin(RedactionConfigMixin):
+    """Mixin for header-based redaction configuration.
+
+    Inherits core redaction fields (redaction_enabled, redaction_attributes, force_redaction)
+    and adds header-specific configuration for authentication-based redaction decisions.
+
+    Note: The callback function must be provided directly to the processor at runtime.
+    """
+    redaction_header: str = Field(default="x-redaction-key", description="Header to check for redaction decisions.")

nat/observability/mixin/tagging_config_mixin.py

@@ -0,0 +1,50 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-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.
+
+from enum import Enum
+from typing import Generic
+from typing import TypeVar
+
+from pydantic import BaseModel
+from pydantic import Field
+
+TagValueT = TypeVar("TagValueT")
+
+
+class PrivacyLevel(str, Enum):
+    """Privacy level for the traces."""
+    NONE = "none"
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+
+
+class TaggingConfigMixin(BaseModel, Generic[TagValueT]):
+    """Generic mixin for tagging spans with typed values.
+
+    This mixin provides a flexible tagging system where both the tag key
+    and value type can be customized for different use cases.
+    """
+    tag_key: str | None = Field(default=None, description="Key to use when tagging traces.")
+    tag_value: TagValueT | None = Field(default=None, description="Value to tag the traces with.")
+
+
+class PrivacyTaggingConfigMixin(TaggingConfigMixin[PrivacyLevel]):
+    """Mixin for privacy level tagging on spans.
+
+    Specializes TaggingConfigMixin to work with PrivacyLevel enum values,
+    providing a typed interface for privacy-related span tagging.
+    """
+    pass

nat/observability/processor/header_redaction_processor.py

@@ -0,0 +1,123 @@
+# 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 logging
+from collections.abc import Callable
+from functools import lru_cache
+
+from starlette.datastructures import Headers
+
+from nat.builder.context import Context
+from nat.data_models.span import Span
+from nat.observability.processor.redaction_processor import SpanRedactionProcessor
+from nat.utils.type_utils import override
+
+logger = logging.getLogger(__name__)
+
+
+def default_callback(_auth_key: str) -> bool:
+    """Default callback that always returns False."""
+    return False
+
+
+class HeaderRedactionProcessor(SpanRedactionProcessor):
+    """Processor that redacts the span based on auth key, span attributes, and callback.
+
+    Uses an LRU cache to avoid redundant callback executions for the same auth keys,
+    providing bounded memory usage and automatic eviction of least recently used entries.
+
+    Args:
+        attributes: List of span attribute keys to redact.
+        header: The header key to check for authentication.
+        callback: Function to determine if the auth key should trigger redaction.
+        enabled: Whether the processor is enabled (default: True).
+        force_redact: If True, always redact regardless of header checks (default: False).
+        redaction_value: The value to replace redacted attributes with (default: "[REDACTED]").
+    """
+
+    def __init__(self,
+                 attributes: list[str] | None = None,
+                 header: str | None = None,
+                 callback: Callable[[str], bool] | None = None,
+                 enabled: bool = True,
+                 force_redact: bool = False,
+                 redaction_value: str = "[REDACTED]"):
+        self.attributes = attributes or []
+        self.header = header
+        self.callback = callback or default_callback
+        self.enabled = enabled
+        self.force_redact = force_redact
+        self.redaction_value = redaction_value
+
+    @override
+    def should_redact(self, item: Span, context: Context) -> bool:
+        """Determine if this span should be redacted based on header auth.
+
+        Args:
+            item (Span): The span to check.
+            context (Context): The current context.
+
+        Returns:
+            bool: True if the span should be redacted, False otherwise.
+        """
+        # If force_redact is enabled, always redact regardless of other conditions
+        if self.force_redact:
+            return True
+
+        if not self.enabled:
+            return False
+
+        headers: Headers | None = context.metadata.headers
+
+        if headers is None or self.header is None:
+            return False
+
+        auth_key = headers.get(self.header, None)
+
+        if not auth_key:
+            return False
+
+        # Use LRU cached method to determine if redaction is needed
+        return self._should_redact_impl(auth_key)
+
+    @lru_cache(maxsize=128)
+    def _should_redact_impl(self, auth_key: str) -> bool:
+        """Implementation method for checking if redaction should occur.
+
+        This method uses lru_cache to avoid redundant callback executions.
+
+        Args:
+            auth_key (str): The authentication key to check.
+
+        Returns:
+            bool: True if the span should be redacted, False otherwise.
+        """
+        return self.callback(auth_key)
+
+    @override
+    def redact_item(self, item: Span) -> Span:
+        """Redact the span.
+
+        Args:
+            item (Span): The span to redact.
+
+        Returns:
+            Span: The redacted span.
+        """
+        for key in self.attributes:
+            if key in item.attributes:
+                item.attributes[key] = self.redaction_value
+
+        return item

nat/observability/processor/redaction_processor.py

@@ -0,0 +1,77 @@
+# 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 logging
+from abc import ABC
+from abc import abstractmethod
+from typing import TypeVar
+
+from nat.builder.context import Context
+from nat.data_models.span import Span
+from nat.observability.processor.processor import Processor
+from nat.utils.type_utils import override
+
+RedactionItemT = TypeVar('RedactionItemT')
+
+logger = logging.getLogger(__name__)
+
+
+class RedactionProcessor(Processor[RedactionItemT, RedactionItemT], ABC):
+    """Abstract base class for redaction processors."""
+
+    @abstractmethod
+    def should_redact(self, item: RedactionItemT, context: Context) -> bool:
+        """Determine if this item should be redacted.
+
+        Args:
+            item (RedactionItemT): The item to check.
+            context (Context): The current context.
+
+        Returns:
+            bool: True if the item should be redacted, False otherwise.
+        """
+        pass
+
+    @abstractmethod
+    def redact_item(self, item: RedactionItemT) -> RedactionItemT:
+        """Redact the item.
+
+        Args:
+            item (RedactionItemT): The item to redact.
+
+        Returns:
+            RedactionItemT: The redacted item.
+        """
+        pass
+
+    @override
+    async def process(self, item: RedactionItemT) -> RedactionItemT:
+        """Perform redaction on the item if it should be redacted.
+
+        Args:
+            item (RedactionItemT): The item to process.
+
+        Returns:
+            RedactionItemT: The processed item.
+        """
+        context = Context.get()
+        if self.should_redact(item, context):
+            return self.redact_item(item)
+        return item
+
+
+class SpanRedactionProcessor(RedactionProcessor[Span]):
+    """Abstract base class for span redaction processors."""
+    pass

nat/observability/processor/span_tagging_processor.py

@@ -0,0 +1,61 @@
+# 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 logging
+import os
+
+from nat.data_models.span import Span
+from nat.observability.processor.processor import Processor
+from nat.utils.type_utils import override
+
+logger = logging.getLogger(__name__)
+
+
+class SpanTaggingProcessor(Processor[Span, Span]):
+    """Processor that tags spans with key-value metadata attributes.
+
+    This processor adds custom tags to spans by setting attributes with a configurable prefix.
+    Tags are only applied when both tag_key and tag_value are provided. The processor uses
+    a span prefix (configurable via NAT_SPAN_PREFIX environment variable) to namespace
+    the tag attributes.
+
+    Args:
+        tag_key: The key name for the tag to add to spans.
+        tag_value: The value for the tag to add to spans.
+        span_prefix: The prefix to use for tag attributes (default: from NAT_SPAN_PREFIX env var or "nat").
+    """
+
+    def __init__(self, tag_key: str | None = None, tag_value: str | None = None, span_prefix: str | None = None):
+        self.tag_key = tag_key
+        self.tag_value = tag_value
+
+        if span_prefix is None:
+            span_prefix = os.getenv("NAT_SPAN_PREFIX", "nat").strip() or "nat"
+
+        self._span_prefix = span_prefix
+
+    @override
+    async def process(self, item: Span) -> Span:
+        """Tag the span with a tag if both tag_key and tag_value are provided.
+
+        Args:
+            item (Span): The span to tag.
+
+        Returns:
+            Span: The tagged span.
+        """
+        if self.tag_key and self.tag_value:
+            item.set_attribute(f"{self._span_prefix}.{self.tag_key}", self.tag_value)
+        return item

{nvidia_nat-1.3.0a20250904.dist-info → nvidia_nat-1.3.0a20250906.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nvidia-nat
-Version: 1.3.0a20250904
+Version: 1.3.0a20250906
 Summary: NVIDIA NeMo Agent toolkit
 Author: NVIDIA Corporation
 Maintainer: NVIDIA Corporation
@@ -207,7 +207,10 @@ License:                                  Apache License
            limitations under the License.
 Keywords: ai,rag,agents
 Classifier: Programming Language :: Python
-Requires-Python: <3.13,>=3.11
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE-3rd-party.txt
 License-File: LICENSE.md

{nvidia_nat-1.3.0a20250904.dist-info → nvidia_nat-1.3.0a20250906.dist-info}/RECORD

@@ -92,7 +92,7 @@ nat/cli/commands/workflow/workflow.py,sha256=40nIOehOX-4xI-qJqJraBX3XVz3l2VtFsZk
 nat/cli/commands/workflow/workflow_commands.py,sha256=jk0Nm27hhyb0Nj7WzVdQa_w2HP9yEZTzb6U_O7llg0c,13032
 nat/cli/commands/workflow/templates/__init__.py.j2,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nat/cli/commands/workflow/templates/config.yml.j2,sha256=KkZl1fOMVQVFBW-BD_d0Lu8kQgNBtjNpfojhSCPu4uA,222
-nat/cli/commands/workflow/templates/pyproject.toml.j2,sha256=-DQwYsLHyNsTSkQydVRR8WDq7-0FB8YG2TtvluDeLFI,1035
+nat/cli/commands/workflow/templates/pyproject.toml.j2,sha256=lDBC4exHYutXa_skuJj176yMEuZr-DsdzrqQHPZoKpk,1035
 nat/cli/commands/workflow/templates/register.py.j2,sha256=txA-qBpWhxRc0GUcVRCIqVI6gGSh-TJijemrUqnb38s,138
 nat/cli/commands/workflow/templates/workflow.py.j2,sha256=Z4uZPG9rtf1nxF74dF4DqDtrF3uYmYUmWowDFbQBjao,1241
 nat/data_models/__init__.py,sha256=Xs1JQ16L9btwreh4pdGKwskffAw1YFO48jKrU4ib_7c,685
@@ -170,7 +170,7 @@ nat/eval/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nat/eval/utils/eval_trace_ctx.py,sha256=hN0YZ0wMOPzh9I-iSav-cGdxY3RWQWoE_tk5BxUf1mc,3264
 nat/eval/utils/output_uploader.py,sha256=27-aKIejV-6DGNErR6iTioNE5rN_lEeiNoBTS1qIVVM,5579
 nat/eval/utils/tqdm_position_registry.py,sha256=9CtpCk1wtYCSyieHPaSp8nlZu6EcNUOaUz2RTqfekrA,1286
-nat/eval/utils/weave_eval.py,sha256=nKLUa17qcLydZMWXy545iincrvgAMNGFsD73Qd2nhTU,7578
+nat/eval/utils/weave_eval.py,sha256=fma5x9JbWpWrfQbfMHcjMovlRVR0v35yfNt1Avt6Vro,7719
 nat/experimental/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nat/experimental/decorators/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 nat/experimental/decorators/experimental_warning_decorator.py,sha256=ji9fITsDF5N5ps5Y9jwb1sqc1e_3TvkUUUBBiJC76CE,5020
@@ -217,7 +217,7 @@ nat/front_ends/console/console_front_end_plugin.py,sha256=BJ1o2IflZeFKC2gGfL_gI2
 nat/front_ends/console/register.py,sha256=2Kf6Mthx6jzWzU8YdhYIR1iABmZDvs1UXM_20npXWXs,1153
 nat/front_ends/cron/__init__.py,sha256=Xs1JQ16L9btwreh4pdGKwskffAw1YFO48jKrU4ib_7c,685
 nat/front_ends/fastapi/__init__.py,sha256=Xs1JQ16L9btwreh4pdGKwskffAw1YFO48jKrU4ib_7c,685
-nat/front_ends/fastapi/fastapi_front_end_config.py,sha256=-fkA7sJ2sBHmCvxdTyd-JJSLc1inVnT_pXa6kmmuGI4,10849
+nat/front_ends/fastapi/fastapi_front_end_config.py,sha256=AV0yY86MjCGrB9VIcvykWvfu5WcnMcrti6rXxUdk9co,11292
 nat/front_ends/fastapi/fastapi_front_end_controller.py,sha256=ei-34KCMpyaeAgeAN4gVvSGFjewjjRhHZPN0FqAfhDY,2548
 nat/front_ends/fastapi/fastapi_front_end_plugin.py,sha256=t_kpMG6S9SIdBKz4Igy0rzrZ9xFz9DUbCBc0eowaixk,4432
 nat/front_ends/fastapi/fastapi_front_end_plugin_worker.py,sha256=1FS1GC_lsQEMP64cPuXrF5MW4B8dMEyBxudJWz9XqPw,51852
@@ -268,7 +268,7 @@ nat/observability/exporter/__init__.py,sha256=Xs1JQ16L9btwreh4pdGKwskffAw1YFO48j
 nat/observability/exporter/base_exporter.py,sha256=tP7c5O-gQnHB_1TwIJJUib1xmtUhX4f4Mf_bmpejtkI,16612
 nat/observability/exporter/exporter.py,sha256=fqF0GYuhZRQEq0skq_FK2nlnsaUAzLpQi-OciaOkRno,2391
 nat/observability/exporter/file_exporter.py,sha256=XYsFjF8ob4Ag-SyGtKEh6wRU9lBx3lbdu7Uo85NvVyo,1465
-nat/observability/exporter/processing_exporter.py,sha256=4YG5YyWMdALZYoTbXzIofWHY9K17YiVWHHz_CFCngUI,14412
+nat/observability/exporter/processing_exporter.py,sha256=lfSURNc03kkAYFFnzcStSgC2EEYoFY0JgnvOvh05n3E,26212
 nat/observability/exporter/raw_exporter.py,sha256=0ROEd-DlLP6pIxl4u2zJ6PMVrDrQa0DMHFDRsdGQMIk,1859
 nat/observability/exporter/span_exporter.py,sha256=p2rugOIyubBk_Frg1c-x-THzvFZt8q8HhYssKUp8Hdg,13250
 nat/observability/mixin/__init__.py,sha256=Xs1JQ16L9btwreh4pdGKwskffAw1YFO48jKrU4ib_7c,685
@@ -276,16 +276,21 @@ nat/observability/mixin/batch_config_mixin.py,sha256=DixQq-jRhBFJvpOX-gq7GvPmZCP
 nat/observability/mixin/collector_config_mixin.py,sha256=3iptkRH9N6JgcsPq7GyjjJVAoxjd-l42UKE7iSF4Hq8,1087
 nat/observability/mixin/file_mixin.py,sha256=J5kC70O3hoU86IDOoQtdk7caRD28nlIZL3igXcRSNBE,12306
 nat/observability/mixin/file_mode.py,sha256=Rq7l8UegECub5QCyCAYwhyL_Jul386gW-ANmtMmv2G4,837
+nat/observability/mixin/redaction_config_mixin.py,sha256=aizfK6nI8_bAJF2lrxSzcxjz8Er9o7itGNa-hDyRhr0,2028
 nat/observability/mixin/resource_conflict_mixin.py,sha256=mcUp3Qinmhiepq3DyRvp9IaKGYtJfDgQVB-MuyVkWvk,5243
 nat/observability/mixin/serialize_mixin.py,sha256=DgRHJpXCz9qHFYzhlTTx8Dkj297EylCKK3ydGrH5zOw,2478
+nat/observability/mixin/tagging_config_mixin.py,sha256=_LLC2fZYM3CzMr2E1Kcy_-UXbjRb8fP1Yd8kcgTNozk,1731
 nat/observability/mixin/type_introspection_mixin.py,sha256=VCb68SY_hitWrWLaK2UHQLkjn2jsgxSn9593T2N3zC0,6637
 nat/observability/processor/__init__.py,sha256=Xs1JQ16L9btwreh4pdGKwskffAw1YFO48jKrU4ib_7c,685
 nat/observability/processor/batching_processor.py,sha256=R0Qy3bHmf-QBM6FJmjmccdsf60JuvYLU-tV4kvy2hBA,13762
 nat/observability/processor/callback_processor.py,sha256=T5DsEm4HCUOi1VL29XCpaK04sYQvJ75KZLH-mlJGQgk,1547
 nat/observability/processor/falsy_batch_filter_processor.py,sha256=CInyZ1eIjtD1W6imPbuqwUeoWOMQ_0J0M9nPL6XwhTo,1778
+nat/observability/processor/header_redaction_processor.py,sha256=cUmsVjHepddFHZu80zvdugG2eOUaGQr6cqxKyVS8fi4,4284
 nat/observability/processor/intermediate_step_serializer.py,sha256=aHeCmixyop7uxNnKmrUZ8SIFeBNS05gYohKLepqbrcQ,1249
 nat/observability/processor/processor.py,sha256=kTqOsus5Ycu5aFnxCTH1EkCP23uRBZ4xNhXmj3DP5OE,2593
 nat/observability/processor/processor_factory.py,sha256=1Ak4OWwmbimc5PKWwqPYq4fJqJifFm6MiI8vcafeErY,2408
+nat/observability/processor/redaction_processor.py,sha256=Mg4zIShjQwX3GCKgXgrx7VaHhoGG3JrFY_QkoDUNtEk,2401
+nat/observability/processor/span_tagging_processor.py,sha256=w5DqWrNU0US1afjVifMAq1_wCjNobwzxo9wAovDMKos,2298
 nat/observability/utils/__init__.py,sha256=Xs1JQ16L9btwreh4pdGKwskffAw1YFO48jKrU4ib_7c,685
 nat/observability/utils/dict_utils.py,sha256=DcNhZ0mgcJ-QQfsCl9QSGL-m_jTuHhr1N-v43ZCAMik,7371
 nat/observability/utils/time_utils.py,sha256=V8m-e3ldUgwv031B17y29yLXIowdlTH4QW8xDw9WKvk,1071
@@ -439,10 +444,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.3.0a20250904.dist-info/licenses/LICENSE-3rd-party.txt,sha256=fOk5jMmCX9YoKWyYzTtfgl-SUy477audFC5hNY4oP7Q,284609
-nvidia_nat-1.3.0a20250904.dist-info/licenses/LICENSE.md,sha256=QwcOLU5TJoTeUhuIXzhdCEEDDvorGiC6-3YTOl4TecE,11356
-nvidia_nat-1.3.0a20250904.dist-info/METADATA,sha256=9HdvGhtE8HFgl2Sk2i2jeLzGUH1cuDfkSCTdvVtGjU0,21933
-nvidia_nat-1.3.0a20250904.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-nvidia_nat-1.3.0a20250904.dist-info/entry_points.txt,sha256=FNh4pZVSe_61s29zdks66lmXBPtsnko8KSZ4ffv7WVE,653
-nvidia_nat-1.3.0a20250904.dist-info/top_level.txt,sha256=lgJWLkigiVZuZ_O1nxVnD_ziYBwgpE2OStdaCduMEGc,8
-nvidia_nat-1.3.0a20250904.dist-info/RECORD,,
+nvidia_nat-1.3.0a20250906.dist-info/licenses/LICENSE-3rd-party.txt,sha256=fOk5jMmCX9YoKWyYzTtfgl-SUy477audFC5hNY4oP7Q,284609
+nvidia_nat-1.3.0a20250906.dist-info/licenses/LICENSE.md,sha256=QwcOLU5TJoTeUhuIXzhdCEEDDvorGiC6-3YTOl4TecE,11356
+nvidia_nat-1.3.0a20250906.dist-info/METADATA,sha256=qVb103Cu_wifrnyZGQACLnhWOJLB2JuT5sZbfHhdPV0,22086
+nvidia_nat-1.3.0a20250906.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+nvidia_nat-1.3.0a20250906.dist-info/entry_points.txt,sha256=FNh4pZVSe_61s29zdks66lmXBPtsnko8KSZ4ffv7WVE,653
+nvidia_nat-1.3.0a20250906.dist-info/top_level.txt,sha256=lgJWLkigiVZuZ_O1nxVnD_ziYBwgpE2OStdaCduMEGc,8
+nvidia_nat-1.3.0a20250906.dist-info/RECORD,,