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

nat/builder/component_utils.py

@@ -174,7 +174,7 @@ def update_dependency_graph(config: "Config", instance_config: TypedBaseModel,
         nx.DiGraph: An dependency graph that has been updated with the provided runtime instance.
     """
 
-    for field_name, field_info in instance_config.model_fields.items():
+    for field_name, field_info in type(instance_config).model_fields.items():
 
         for instance_id, value_node in recursive_componentref_discovery(
                 instance_config,

nat/cli/commands/info/list_mcp.py

@@ -22,8 +22,16 @@ from typing import Any
 import click
 from pydantic import BaseModel
 
-from nat.tool.mcp.exceptions import MCPError
-from nat.utils.exception_handlers.mcp import format_mcp_error
+try:
+    from nat.plugins.mcp.exception_handler import format_mcp_error
+    from nat.plugins.mcp.exceptions import MCPError
+except ImportError:
+    # Fallback for when MCP client package is not installed
+    MCPError = Exception
+
+    def format_mcp_error(error, include_traceback=False):
+        click.echo(f"Error: {error}", err=True)
+
 
 # Suppress verbose logs from mcp.client.sse and httpx
 logging.getLogger("mcp.client.sse").setLevel(logging.WARNING)
@@ -145,9 +153,15 @@ async def list_tools_and_schemas(command, url, tool_name=None, transport='sse',
     Raises:
         MCPError: Caught internally and logged, returns empty list instead
     """
-    from nat.tool.mcp.mcp_client_base import MCPSSEClient
-    from nat.tool.mcp.mcp_client_base import MCPStdioClient
-    from nat.tool.mcp.mcp_client_base import MCPStreamableHTTPClient
+    try:
+        from nat.plugins.mcp.client_base import MCPSSEClient
+        from nat.plugins.mcp.client_base import MCPStdioClient
+        from nat.plugins.mcp.client_base import MCPStreamableHTTPClient
+    except ImportError:
+        click.echo(
+            "MCP client functionality requires nvidia-nat-mcp package. Install with: uv pip install nvidia-nat-mcp",
+            err=True)
+        return []
 
     if args is None:
         args = []
@@ -239,8 +253,16 @@ async def list_tools_direct(command, url, tool_name=None, transport='sse', args=
         return tools
     except Exception as e:
         # Convert raw exceptions to structured MCPError for consistency
-        from nat.utils.exception_handlers.mcp import convert_to_mcp_error
-        from nat.utils.exception_handlers.mcp import extract_primary_exception
+        try:
+            from nat.plugins.mcp.exception_handler import convert_to_mcp_error
+            from nat.plugins.mcp.exception_handler import extract_primary_exception
+        except ImportError:
+            # Fallback when MCP client package is not installed
+            def convert_to_mcp_error(exception, url):
+                return Exception(f"Error connecting to {url}: {exception}")
+
+            def extract_primary_exception(exceptions):
+                return exceptions[0] if exceptions else Exception("Unknown error")
 
         if isinstance(e, ExceptionGroup):  # noqa: F821
             primary_exception = extract_primary_exception(list(e.exceptions))

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/data_models/common.py

@@ -160,7 +160,7 @@ class TypedBaseModel(BaseModel):
 
     @staticmethod
     def discriminator(v: typing.Any) -> str | None:
-        # If its serialized, then we use the alias
+        # If it's serialized, then we use the alias
         if isinstance(v, dict):
             return v.get("_type", v.get("type"))
 

nat/data_models/thinking_mixin.py

@@ -20,9 +20,9 @@ from pydantic import Field
 
 from nat.data_models.gated_field_mixin import GatedFieldMixin
 
-# The system prompt format for thinking is different for these, so we need to distinguish them here with two separate
-# regex patterns
+# Currently the control logic for thinking is only implemented for Nemotron models
 _NEMOTRON_REGEX = re.compile(r"^nvidia/(llama|nvidia).*nemotron", re.IGNORECASE)
+# The keys are the fields that are used to determine if the model supports thinking
 _MODEL_KEYS = ("model_name", "model", "azure_deployment")
 
 
@@ -43,7 +43,6 @@ class ThinkingMixin(
     thinking: bool | None = Field(
         default=None,
         description="Whether to enable thinking. Defaults to None when supported on the model.",
-        exclude=True,
     )
 
     @property

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.")