nv-ingest 2025.8.14.dev20250814__py3-none-any.whl → 2025.8.16.dev20250816__py3-none-any.whl

nv_ingest/framework/orchestration/ray/stages/extractors/html_extractor.py

@@ -4,6 +4,7 @@
 
 
 import logging
+from typing import Optional
 
 import ray
 
@@ -17,6 +18,8 @@ from nv_ingest_api.util.exception_handlers.decorators import (
     nv_ingest_node_failure_try_except,
 )
 
+from nv_ingest.framework.util.flow_control.udf_intercept import udf_intercept_hook
+
 logger = logging.getLogger(__name__)
 
 
@@ -31,8 +34,8 @@ class HtmlExtractorStage(RayActorStage):
       3. Updates the message payload with the extracted text DataFrame.
     """
 
-    def __init__(self, config: HtmlExtractorSchema) -> None:
-        super().__init__(config, log_to_stdout=False)
+    def __init__(self, config: HtmlExtractorSchema, stage_name: Optional[str] = None) -> None:
+        super().__init__(config, log_to_stdout=False, stage_name=stage_name)
         try:
             self.validated_config = config
             self._logger.info("HtmlExtractorStage configuration validated successfully.")
@@ -40,9 +43,10 @@ class HtmlExtractorStage(RayActorStage):
             self._logger.exception(f"Error validating Html Extractor config: {e}")
             raise
 
-    @traceable("html_extractor")
+    @nv_ingest_node_failure_try_except()
+    @traceable()
+    @udf_intercept_hook()
     @filter_by_task(required_tasks=[("extract", {"document_type": "html"})])
-    @nv_ingest_node_failure_try_except(annotation_id="html_extractor", raise_on_failure=False)
     def on_data(self, control_message: IngestControlMessage) -> IngestControlMessage:
         """
         Process the control message by extracting content from html.

nv_ingest/framework/orchestration/ray/stages/extractors/image_extractor.py

@@ -3,6 +3,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import logging
+from typing import Optional
 
 import ray
 
@@ -16,6 +17,8 @@ from nv_ingest_api.util.exception_handlers.decorators import (
     nv_ingest_node_failure_try_except,
 )
 
+from nv_ingest.framework.util.flow_control.udf_intercept import udf_intercept_hook
+
 logger = logging.getLogger(__name__)
 
 
@@ -30,18 +33,19 @@ class ImageExtractorStage(RayActorStage):
       3. Updates the message payload with the extracted primitives DataFrame.
     """
 
-    def __init__(self, config: ImageExtractorSchema) -> None:
-        super().__init__(config)
+    def __init__(self, config: ImageExtractorSchema, stage_name: Optional[str] = None) -> None:
+        super().__init__(config, log_to_stdout=False, stage_name=stage_name)
         try:
             self.validated_config = config
-            logger.info("ImageExtractorStage configuration validated successfully.")
+            self._logger.info("ImageExtractorStage configuration validated successfully.")
         except Exception as e:
-            logger.exception(f"Error validating Image Extractor config: {e}")
+            self._logger.exception(f"Error validating Image Extractor config: {e}")
             raise
 
-    @traceable("image_extraction")
+    @nv_ingest_node_failure_try_except()
+    @traceable()
+    @udf_intercept_hook()
     @filter_by_task(required_tasks=[("extract", {"document_type": "regex:^(png|jpeg|jpg|tiff|bmp)$"})])
-    @nv_ingest_node_failure_try_except(annotation_id="image_extractor", raise_on_failure=False)
     def on_data(self, control_message: IngestControlMessage) -> IngestControlMessage:
         """
         Process the control message by extracting primitives from images.

nv_ingest/framework/orchestration/ray/stages/extractors/infographic_extractor.py

@@ -5,32 +5,44 @@
 import logging
 import ray
 
-from nv_ingest_api.internal.schemas.extract.extract_infographic_schema import InfographicExtractorSchema
 from nv_ingest.framework.orchestration.ray.stages.meta.ray_actor_stage_base import RayActorStage
 from nv_ingest.framework.util.flow_control import filter_by_task
 from nv_ingest_api.internal.extract.image.infographic_extractor import extract_infographic_data_from_image_internal
 from nv_ingest_api.internal.primitives.ingest_control_message import IngestControlMessage, remove_task_by_type
-from nv_ingest_api.internal.primitives.tracing.tagging import traceable
+from nv_ingest_api.internal.primitives.tracing.tagging import traceable, set_trace_timestamps_with_parent_context
+from nv_ingest_api.internal.schemas.extract.extract_infographic_schema import InfographicExtractorSchema
 from nv_ingest_api.util.exception_handlers.decorators import nv_ingest_node_failure_try_except
+from typing import Optional
+
+from nv_ingest.framework.util.flow_control.udf_intercept import udf_intercept_hook
 
 logger = logging.getLogger(__name__)
 
 
 @ray.remote
 class InfographicExtractorStage(RayActorStage):
-    def __init__(self, config: InfographicExtractorSchema) -> None:
-        super().__init__(config)
+    """
+    A Ray actor stage that extracts infographic data from image content.
+
+    It expects an IngestControlMessage containing a DataFrame with image data. It then:
+      1. Removes the "infographic_data_extract" task from the message.
+      2. Calls the infographic extraction logic using a validated configuration.
+      3. Updates the message payload with the extracted infographic DataFrame.
+    """
 
+    def __init__(self, config: InfographicExtractorSchema, stage_name: Optional[str] = None) -> None:
+        super().__init__(config, log_to_stdout=False, stage_name=stage_name)
         try:
             self.validated_config = config
-            logger.info("ImageExtractorStage configuration validated successfully.")
+            self._logger.info("InfographicExtractorStage configuration validated successfully.")
         except Exception as e:
-            logger.exception(f"Error validating Image Extractor config: {e}")
+            self._logger.exception(f"Error validating Infographic extractor config: {e}")
             raise
 
-    @traceable("infographic_extraction")
+    @nv_ingest_node_failure_try_except()
+    @traceable()
+    @udf_intercept_hook()
     @filter_by_task(required_tasks=["infographic_data_extract"])
-    @nv_ingest_node_failure_try_except(annotation_id="infographic_extraction", raise_on_failure=False)
     def on_data(self, control_message: IngestControlMessage) -> IngestControlMessage:
         # Extract DataFrame payload
         df_ledger = control_message.payload()
@@ -51,7 +63,7 @@ class InfographicExtractorStage(RayActorStage):
 
         do_trace_tagging = control_message.get_metadata("config::add_trace_tagging") is True
         if do_trace_tagging and execution_trace_log:
-            for key, ts in execution_trace_log.items():
-                control_message.set_timestamp(key, ts)
+            parent_name = self.stage_name if self.stage_name else "infographic_extractor"
+            set_trace_timestamps_with_parent_context(control_message, execution_trace_log, parent_name, logger)
 
         return control_message

nv_ingest/framework/orchestration/ray/stages/extractors/pdf_extractor.py

@@ -7,16 +7,15 @@ import pandas as pd
 from typing import Any, Dict, Tuple, Optional
 import ray
 
-# Assume these imports come from your project:
-from nv_ingest.framework.orchestration.ray.stages.meta.ray_actor_stage_base import RayActorStage
-from nv_ingest.framework.util.flow_control import filter_by_task
 from nv_ingest_api.internal.extract.pdf.pdf_extractor import extract_primitives_from_pdf_internal
 from nv_ingest_api.internal.primitives.ingest_control_message import remove_task_by_type
-from nv_ingest_api.internal.primitives.tracing.tagging import traceable
 from nv_ingest_api.internal.schemas.extract.extract_pdf_schema import PDFExtractorSchema
-from nv_ingest_api.util.exception_handlers.decorators import (
-    nv_ingest_node_failure_try_except,
-)
+
+from nv_ingest_api.internal.primitives.tracing.tagging import set_trace_timestamps_with_parent_context, traceable
+from nv_ingest.framework.orchestration.ray.stages.meta.ray_actor_stage_base import RayActorStage
+from nv_ingest.framework.util.flow_control import filter_by_task
+from nv_ingest.framework.util.flow_control.udf_intercept import udf_intercept_hook
+from nv_ingest_api.util.exception_handlers.decorators import nv_ingest_node_failure_try_except
 
 logger = logging.getLogger(__name__)
 
@@ -51,19 +50,20 @@ class PDFExtractorStage(RayActorStage):
       4. Optionally, stores additional extraction info in the message metadata.
     """
 
-    def __init__(self, config: PDFExtractorSchema) -> None:
-        super().__init__(config)
+    def __init__(self, config: PDFExtractorSchema, stage_name: Optional[str] = None) -> None:
+        super().__init__(config, stage_name=stage_name)
         try:
             # Validate and store the PDF extractor configuration.
             self.validated_config = config
-            logger.info("PDFExtractorStage configuration validated successfully.")
+            logger.debug("PDFExtractorStage configuration validated successfully.")
         except Exception as e:
             logger.exception(f"Error validating PDF extractor config: {e}")
             raise
 
-    @traceable("pdf_extraction")
+    @nv_ingest_node_failure_try_except()
+    @traceable()
+    @udf_intercept_hook()
     @filter_by_task(required_tasks=[("extract", {"document_type": "pdf"})])
-    @nv_ingest_node_failure_try_except(annotation_id="pdf_extractor", raise_on_failure=False)
     def on_data(self, control_message: Any) -> Any:
         """
         Process the control message by extracting PDF content.
@@ -79,7 +79,7 @@ class PDFExtractorStage(RayActorStage):
             The updated message with the extracted DataFrame and extraction info in metadata.
         """
 
-        logger.info("PDFExtractorStage.on_data: Starting PDF extraction process.")
+        logger.debug("PDFExtractorStage.on_data: Starting PDF extraction process.")
 
         # Extract the DataFrame payload.
         df_extraction_ledger = control_message.payload()
@@ -97,17 +97,18 @@ class PDFExtractorStage(RayActorStage):
             execution_trace_log=execution_trace_log,
             validated_config=self.validated_config,
         )
-        logger.info("PDF extraction completed. Extracted %d rows.", len(new_df))
+        logger.debug("PDF extraction completed. Extracted %d rows.", len(new_df))
 
         # Update the message payload with the extracted DataFrame.
         control_message.payload(new_df)
         # Optionally, annotate the message with extraction info.
         control_message.set_metadata("pdf_extraction_info", extraction_info)
-        logger.info("PDF extraction metadata injected successfully.")
+        logger.debug("PDF extraction metadata injected successfully.")
 
         do_trace_tagging = control_message.get_metadata("config::add_trace_tagging") is True
         if do_trace_tagging and execution_trace_log:
-            for key, ts in execution_trace_log.items():
-                control_message.set_timestamp(key, ts)
+            # Use utility function to set trace timestamps with proper parent-child context
+            parent_name = self.stage_name or "pdf_extractor"
+            set_trace_timestamps_with_parent_context(control_message, execution_trace_log, parent_name, logger)
 
         return control_message

nv_ingest/framework/orchestration/ray/stages/extractors/pptx_extractor.py

@@ -3,8 +3,10 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import logging
+from typing import Optional
 
 import ray
+from nv_ingest.framework.util.flow_control.udf_intercept import udf_intercept_hook
 
 from nv_ingest.framework.orchestration.ray.stages.meta.ray_actor_stage_base import RayActorStage
 from nv_ingest.framework.util.flow_control import filter_by_task
@@ -28,7 +30,7 @@ class PPTXExtractorStage(RayActorStage):
       3. Updates the message payload with the extracted content DataFrame.
     """
 
-    def __init__(self, config: PPTXExtractorSchema) -> None:
+    def __init__(self, config: PPTXExtractorSchema, stage_name: Optional[str] = None) -> None:
         """
         Initializes the PptxExtractorStage.
 
@@ -36,8 +38,10 @@ class PPTXExtractorStage(RayActorStage):
         ----------
         config : PPTXExtractorSchema
             The validated configuration object for PPTX extraction.
+        stage_name : Optional[str]
+            Name of the stage from YAML pipeline configuration.
         """
-        super().__init__(config)
+        super().__init__(config, stage_name=stage_name)
         try:
             # The config passed in should already be validated, but storing it.
             self.validated_config = config
@@ -47,9 +51,10 @@ class PPTXExtractorStage(RayActorStage):
             logger.exception(f"Error initializing or validating PPTX Extractor config: {e}")
             raise
 
-    @traceable("pptx_extractor")
+    @nv_ingest_node_failure_try_except()
+    @traceable()
+    @udf_intercept_hook()
     @filter_by_task(required_tasks=[("extract", {"document_type": "pptx"})])
-    @nv_ingest_node_failure_try_except(annotation_id="pptx_extractor", raise_on_failure=False)
     def on_data(self, control_message: IngestControlMessage) -> IngestControlMessage:
         """
         Process the control message by extracting content from PPTX documents.
@@ -80,6 +85,6 @@ class PPTXExtractorStage(RayActorStage):
 
         # Update the message payload with the extracted PPTX content DataFrame.
         control_message.payload(new_df)
-        control_message.set_metadata("pptx_extraction_info", extraction_info)  # <-- Changed metadata key
+        control_message.set_metadata("pptx_extraction_info", extraction_info)
 
         return control_message

nv_ingest/framework/orchestration/ray/stages/extractors/table_extractor.py

@@ -3,15 +3,15 @@
 # SPDX-License-Identifier: Apache-2.0
 
 import logging
-from typing import Any
+from typing import Any, Optional
 import ray
 
-# These imports are assumed from your project.
 from nv_ingest.framework.orchestration.ray.stages.meta.ray_actor_stage_base import RayActorStage
 from nv_ingest.framework.util.flow_control import filter_by_task
+from nv_ingest.framework.util.flow_control.udf_intercept import udf_intercept_hook
 from nv_ingest_api.internal.extract.image.table_extractor import extract_table_data_from_image_internal
 from nv_ingest_api.internal.primitives.ingest_control_message import remove_task_by_type
-from nv_ingest_api.internal.primitives.tracing.tagging import traceable
+from nv_ingest_api.internal.primitives.tracing.tagging import traceable, set_trace_timestamps_with_parent_context
 from nv_ingest_api.internal.schemas.extract.extract_table_schema import TableExtractorSchema
 from nv_ingest_api.util.exception_handlers.decorators import (
     nv_ingest_node_failure_try_except,
@@ -31,18 +31,19 @@ class TableExtractorStage(RayActorStage):
     and annotates the message metadata with extraction info.
     """
 
-    def __init__(self, config: TableExtractorSchema) -> None:
-        super().__init__(config)
+    def __init__(self, config: TableExtractorSchema, stage_name: Optional[str] = None) -> None:
+        super().__init__(config, stage_name=stage_name)
         try:
             self.validated_config = config
-            logger.info("TableExtractorStage configuration validated successfully.")
+            logger.debug("TableExtractorStage configuration validated successfully.")
         except Exception as e:
             logger.exception("Error validating table extractor config")
             raise e
 
-    @traceable("table_extraction")
+    @nv_ingest_node_failure_try_except()
+    @traceable()
+    @udf_intercept_hook()
     @filter_by_task(required_tasks=["table_data_extract"])
-    @nv_ingest_node_failure_try_except(annotation_id="table_extraction", raise_on_failure=False)
     def on_data(self, control_message: Any) -> Any:
         """
         Process the control message by extracting table data from the PDF payload.
@@ -57,7 +58,7 @@ class TableExtractorStage(RayActorStage):
         IngestControlMessage
             The updated message with the extracted table data and extraction info in metadata.
         """
-        logger.info("TableExtractorStage.on_data: Starting table extraction.")
+        logger.debug("TableExtractorStage.on_data: Starting table extraction.")
         # Extract the DataFrame payload.
         df_payload = control_message.payload()
         logger.debug("Extracted payload with %d rows.", len(df_payload))
@@ -74,17 +75,17 @@ class TableExtractorStage(RayActorStage):
             extraction_config=self.validated_config,
             execution_trace_log=execution_trace_log,
         )
-        logger.info("Table extraction completed. Extracted %d rows.", len(new_df))
+        logger.debug("Table extraction completed. Extracted %d rows.", len(new_df))
 
         # Update the control message with the new DataFrame.
         control_message.payload(new_df)
         # Annotate the message with extraction info.
         control_message.set_metadata("table_extraction_info", extraction_info)
-        logger.info("Table extraction metadata injected successfully.")
+        logger.debug("Table extraction metadata injected successfully.")
 
         do_trace_tagging = control_message.get_metadata("config::add_trace_tagging") is True
         if do_trace_tagging and execution_trace_log:
-            for key, ts in execution_trace_log.items():
-                control_message.set_timestamp(key, ts)
+            parent_name = self.stage_name if self.stage_name else "table_extractor"
+            set_trace_timestamps_with_parent_context(control_message, execution_trace_log, parent_name, logger)
 
         return control_message

nv_ingest/framework/orchestration/ray/stages/injectors/metadata_injector.py

@@ -4,12 +4,14 @@
 
 from datetime import datetime
 import logging
+from typing import Optional
 import pandas as pd
-from typing import Any
 from pydantic import BaseModel
 import ray
 
 from nv_ingest.framework.orchestration.ray.stages.meta.ray_actor_stage_base import RayActorStage
+from nv_ingest_api.internal.primitives.ingest_control_message import IngestControlMessage
+from nv_ingest_api.internal.primitives.tracing.tagging import traceable
 from nv_ingest_api.internal.enums.common import (
     DocumentTypeEnum,
     ContentTypeEnum,
@@ -17,14 +19,13 @@ from nv_ingest_api.internal.enums.common import (
     TextTypeEnum,
     LanguageEnum,
 )
-from nv_ingest_api.internal.primitives.tracing.tagging import traceable
 from nv_ingest_api.internal.schemas.meta.metadata_schema import ContentHierarchySchema
 from nv_ingest_api.util.converters.type_mappings import doc_type_to_content_type
 from nv_ingest_api.util.exception_handlers.decorators import (
     nv_ingest_node_failure_try_except,
 )
+from nv_ingest.framework.util.flow_control.udf_intercept import udf_intercept_hook
 
-# logging.basicConfig(level=logging.DEBUG)
 logger = logging.getLogger(__name__)
 
 
@@ -37,15 +38,16 @@ class MetadataInjectionStage(RayActorStage):
     injection is required, and if so, injects the appropriate metadata.
     """
 
-    def __init__(self, config: BaseModel) -> None:
+    def __init__(self, config: BaseModel, stage_name: Optional[str] = None) -> None:
         # Call the base initializer to set attributes like self._running.
-        super().__init__(config)
+        super().__init__(config, stage_name=stage_name)
         # Additional initialization can be added here if necessary.
-        logger.info("MetadataInjectionStage initialized with config: %s", config)
+        self._logger.debug("MetadataInjectionStage initialized with config: %s", config)
 
-    @traceable("metadata_injector")
-    @nv_ingest_node_failure_try_except(annotation_id="metadata_injector", raise_on_failure=False)
-    def on_data(self, message: Any) -> Any:
+    @nv_ingest_node_failure_try_except()
+    @traceable()
+    @udf_intercept_hook()
+    def on_data(self, message: IngestControlMessage) -> IngestControlMessage:
         """
         Process an incoming IngestControlMessage by injecting metadata into its DataFrame payload.
 
@@ -62,7 +64,7 @@ class MetadataInjectionStage(RayActorStage):
         df = message.payload()
         update_required = False
         rows = []
-        logger.info("Starting metadata injection on DataFrame with %d rows", len(df))
+        logger.debug("Starting metadata injection on DataFrame with %d rows", len(df))
 
         for _, row in df.iterrows():
             try:
@@ -141,7 +143,7 @@ class MetadataInjectionStage(RayActorStage):
                         "source_metadata": default_source_metadata,
                         "text_metadata": default_text_metadata,
                     }
-                    logger.info(
+                    logger.debug(
                         f"METADATA_INJECTOR_DEBUG: Rebuilt metadata for source_id='{row.get('source_id', 'N/A')}'. "
                         f"Metadata keys: {list(row['metadata'].keys())}."
                         f"'content' present: {'content' in row['metadata']}"
@@ -154,8 +156,8 @@ class MetadataInjectionStage(RayActorStage):
         if update_required:
             docs = pd.DataFrame(rows)
             message.payload(docs)
-            logger.info("Metadata injection updated payload with %d rows", len(docs))
+            logger.debug("Metadata injection updated payload with %d rows", len(docs))
         else:
-            logger.info("No metadata update was necessary during metadata injection")
+            logger.debug("No metadata update was necessary during metadata injection")
 
         return message

nv_ingest/framework/orchestration/ray/stages/meta/ray_actor_sink_stage_base.py

@@ -21,6 +21,9 @@ class RayActorSinkStage(RayActorStage, ABC):
     to deliver their final processed messages.
     """
 
+    def __init__(self, config: Any, log_to_stdout=False, stage_name: Optional[str] = None) -> None:
+        super().__init__(config, log_to_stdout=log_to_stdout, stage_name=stage_name)
+
     @ray.method(num_returns=1)
     def set_output_queue(self, queue_handle: any) -> bool:
         raise NotImplementedError("Sink stages do not support an output queue.")

nv_ingest/framework/orchestration/ray/stages/meta/ray_actor_source_stage_base.py

@@ -3,7 +3,7 @@
 # SPDX-License-Identifier: Apache-2.0
 
 from abc import ABC, abstractmethod
-from typing import Any
+from typing import Any, Optional
 import ray
 import logging
 
@@ -19,8 +19,8 @@ class RayActorSourceStage(RayActorStage, ABC):
     Instead, they must implement get_input() to fetch control messages from an external source.
     """
 
-    def __init__(self, config: Any, log_to_stdout=False) -> None:
-        super().__init__(config, log_to_stdout=log_to_stdout)
+    def __init__(self, config: Any, log_to_stdout=False, stage_name: Optional[str] = None) -> None:
+        super().__init__(config, log_to_stdout=log_to_stdout, stage_name=stage_name)
         self.paused = False
 
     def on_data(self, IngestControlMessage):

nv_ingest/framework/orchestration/ray/stages/meta/ray_actor_stage_base.py

@@ -2,6 +2,7 @@
 # All rights reserved.
 # SPDX-License-Identifier: Apache-2.0
 
+import gc
 import sys
 import threading
 import time
@@ -9,12 +10,12 @@ from abc import ABC, abstractmethod
 from typing import Any, Dict, Optional
 import os
 import psutil
-import gc
 
 import ray
 import ray.actor
 from pydantic import BaseModel
 import logging
+import pyarrow as pa
 
 from ray import get_runtime_context
 
@@ -50,6 +51,9 @@ class RayActorStage(ABC):
     ----------
     config : BaseModel
         Configuration object for the stage.
+    stage_name : Optional[str]
+        Name of the stage from YAML pipeline configuration. Used by
+        stage-aware decorators for consistent naming.
     _input_queue : Optional[Any]
         Handle to the Ray queue from which input items are read.
         Expected to be set via `set_input_queue`.
@@ -81,7 +85,7 @@ class RayActorStage(ABC):
         Lock to protect access to shutdown-related state (`_shutting_down`).
     """
 
-    def __init__(self, config: BaseModel, log_to_stdout=False) -> None:
+    def __init__(self, config: BaseModel, stage_name: Optional[str] = None, log_to_stdout=False) -> None:
         """
         Initialize the RayActorStage.
 
@@ -90,8 +94,14 @@ class RayActorStage(ABC):
         config : BaseModel
             Configuration object specific to the stage's behavior. Passed by
             the orchestrator during actor creation.
+        stage_name : Optional[str]
+            Name of the stage from YAML pipeline configuration. Used by
+            stage-aware decorators for consistent naming.
+        log_to_stdout : bool
+            Whether to enable stdout logging.
         """
         self.config: BaseModel = config
+        self.stage_name: Optional[str] = stage_name
         self._input_queue: Optional[Any] = None  # Ray Queue handle expected
         self._output_queue: Optional[Any] = None  # Ray Queue handle expected
         self._running: bool = False
@@ -130,12 +140,13 @@ class RayActorStage(ABC):
 
         self._actor_id_str = self._get_actor_id_str()
 
-        # --- PyArrow memory cleanup configuration/state ---
-        # Allow stages to configure the cleanup interval (seconds) via their config.
-        # Defaults to 5 minutes if not provided.
-        self._memory_cleanup_interval_seconds: int = int(getattr(self.config, "memory_cleanup_interval_seconds", 300))
-        self._last_memory_cleanup_time: float = time.time()
-        self._memory_cleanups_performed: int = 0
+        # --- PyArrow Memory Management ---
+        # Time-based periodic cleanup to prevent long-term memory accumulation
+        self._memory_cleanup_interval_seconds = getattr(
+            config, "memory_cleanup_interval_seconds", 300
+        )  # 5 minutes default
+        self._last_memory_cleanup_time = time.time()
+        self._memory_cleanups_performed = 0
 
     @staticmethod
     def _get_actor_id_str() -> str:
@@ -429,8 +440,6 @@ class RayActorStage(ABC):
             gc.collect()
 
             try:
-                import pyarrow as pa  # Local import to avoid hard dependency at import time
-
                 pool = pa.default_memory_pool()
                 try:
                     before_bytes = getattr(pool, "bytes_allocated", lambda: 0)()
@@ -579,7 +588,7 @@ class RayActorStage(ABC):
             self._logger.warning(f"{self._actor_id_str}: Start called but actor is already running.")
             return False
 
-        self._logger.info(f"{self._actor_id_str}: Starting actor...")
+        self._logger.debug(f"{self._actor_id_str}: Starting actor...")
         # --- Initialize Actor State ---
         self._running = True
         self._shutting_down = False  # Reset shutdown flag on start
@@ -598,14 +607,14 @@ class RayActorStage(ABC):
         )
         self._processing_thread.start()
 
-        self._logger.info(f"{self._actor_id_str}: Actor started successfully.")
+        self._logger.debug(f"{self._actor_id_str}: Actor started successfully.")
 
         return True
 
     @ray.method(num_returns=0)
     def stop(self) -> None:
         """Stops the actor's processing loop by setting the running flag to False."""
-        self._logger.info(f"[{self._actor_id_str}] Stop signal received. Initiating graceful shutdown.")
+        self._logger.debug(f"[{self._actor_id_str}] Stop signal received. Initiating graceful shutdown.")
         self._running = False
 
     def is_shutdown_complete(self) -> bool:

nv_ingest/framework/orchestration/ray/stages/mutate/image_dedup.py

@@ -4,11 +4,13 @@
 
 
 import logging
+from typing import Optional
 
 import ray
 
 from nv_ingest.framework.orchestration.ray.stages.meta.ray_actor_stage_base import RayActorStage
 from nv_ingest.framework.util.flow_control import filter_by_task
+from nv_ingest.framework.util.flow_control.udf_intercept import udf_intercept_hook
 from nv_ingest_api.internal.mutate.deduplicate import deduplicate_images_internal
 from nv_ingest_api.internal.primitives.ingest_control_message import IngestControlMessage, remove_task_by_type
 from nv_ingest_api.internal.primitives.tracing.tagging import traceable
@@ -31,18 +33,19 @@ class ImageDedupStage(RayActorStage):
       3. Updates the message payload with the deduplicated DataFrame.
     """
 
-    def __init__(self, config: ImageDedupSchema) -> None:
-        super().__init__(config)
+    def __init__(self, config: ImageDedupSchema, stage_name: Optional[str] = None) -> None:
+        super().__init__(config, stage_name=stage_name)
         try:
             self.validated_config = config
-            logger.info("ImageDedupStage configuration validated successfully.")
+            logger.debug("ImageDedupStage configuration validated successfully.")
         except Exception as e:
             logger.exception(f"Error validating Image Deduplication config: {e}")
             raise
 
-    @traceable("image_deduplication")
+    @nv_ingest_node_failure_try_except()
+    @traceable()
+    @udf_intercept_hook()
     @filter_by_task(required_tasks=["dedup"])
-    @nv_ingest_node_failure_try_except(annotation_id="image_dedup", raise_on_failure=False)
     def on_data(self, control_message: IngestControlMessage) -> IngestControlMessage:
         """
         Process the control message by deduplicating images.
@@ -57,7 +60,7 @@ class ImageDedupStage(RayActorStage):
         IngestControlMessage
             The updated message with deduplicated images in the payload.
         """
-        logger.info("ImageDedupStage.on_data: Starting image deduplication process.")
+        logger.debug("ImageDedupStage.on_data: Starting image deduplication process.")
         try:
             # Extract the DataFrame payload.
             df_ledger = control_message.payload()
@@ -74,7 +77,7 @@ class ImageDedupStage(RayActorStage):
                 mutate_config=self.validated_config,
                 execution_trace_log=None,
             )
-            logger.info("Image deduplication completed. Resulting DataFrame has %d rows.", len(new_df))
+            logger.debug("Image deduplication completed. Resulting DataFrame has %d rows.", len(new_df))
 
             # Update the message payload with the deduplicated DataFrame.
             control_message.payload(new_df)