nv-ingest 2025.11.9.dev20251109__tar.gz → 2025.12.15.dev20251215__tar.gz

{nv_ingest-2025.11.9.dev20251109 → nv_ingest-2025.12.15.dev20251215}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nv-ingest
-Version: 2025.11.9.dev20251109
+Version: 2025.12.15.dev20251215
 Summary: Python module for multimodal document ingestion
 Author-email: Jeremy Dyer <jdyer@nvidia.com>
 License:                                  Apache License
@@ -219,6 +219,8 @@ Requires-Dist: diskcache>=5.6.3
 Requires-Dist: fastapi>=0.115.6
 Requires-Dist: fastparquet>=2024.11.0
 Requires-Dist: fsspec>=2024.10.0
+Requires-Dist: universal_pathlib>=0.2.6
+Requires-Dist: s3fs>=2024.10.0
 Requires-Dist: gunicorn
 Requires-Dist: h11>=0.16.0
 Requires-Dist: httpx>=0.28.1
@@ -226,7 +228,6 @@ Requires-Dist: isodate>=0.7.2
 Requires-Dist: langdetect>=1.0.9
 Requires-Dist: minio>=7.2.12
 Requires-Dist: librosa>=0.10.2
-Requires-Dist: openai>=1.82.0
 Requires-Dist: opentelemetry-api>=1.27.0
 Requires-Dist: opentelemetry-exporter-otlp>=1.27.0
 Requires-Dist: opentelemetry-sdk>=1.27.0

{nv_ingest-2025.11.9.dev20251109 → nv_ingest-2025.12.15.dev20251215}/nv_ingest/api/main.py

@@ -23,7 +23,7 @@ logger = logging.getLogger(__name__)
 app = FastAPI(
     title="NV-Ingest Microservice",
     description="Service for ingesting heterogenous datatypes",
-    version="25.4.2",
+    version="26.1.0",
     contact={
         "name": "NVIDIA Corporation",
         "url": "https://nvidia.com",

{nv_ingest-2025.11.9.dev20251109 → nv_ingest-2025.12.15.dev20251215}/nv_ingest/api/v2/ingest.py

@@ -13,6 +13,8 @@ import os
 import time
 import uuid
 import random
+from pathlib import Path
+import fsspec
 
 from fastapi import APIRouter, Request, Response
 from fastapi import HTTPException
@@ -21,6 +23,8 @@ from redis import RedisError
 
 from nv_ingest.framework.schemas.framework_message_wrapper_schema import MessageWrapper
 from nv_ingest_api.util.service_clients.client_base import FetchMode
+from nv_ingest_api.util.dataloader.dataloader import DataLoader
+from nv_ingest_api.internal.schemas.meta.ingest_job_schema import DocumentTypeEnum
 
 # For PDF splitting
 import pypdfium2 as pdfium
@@ -188,28 +192,42 @@ def get_pdf_page_count(pdf_content: bytes) -> int:
         return 1  # Assume single page on error
 
 
-def _prepare_chunk_submission(
+def _create_subjob_dict(
+    job_id: str,
+    job_payload: Dict[str, Any],
     job_spec_template: Dict[str, Any],
-    chunk: Dict[str, Any],
-    *,
-    parent_uuid: uuid.UUID,
-    parent_job_id: str,
     current_trace_id: int,
-    original_source_id: str,
-    original_source_name: str,
-) -> Tuple[str, MessageWrapper]:
-    """Create a subjob MessageWrapper for a PDF chunk and return its identifier."""
-
-    chunk_number = chunk["chunk_index"] + 1
-    start_page = chunk["start_page"]
-    end_page = chunk["end_page"]
-
-    subjob_spec = {
+    parent_job_id: str,
+    start_key: Dict[str, Any],
+) -> Dict[str, Any]:
+    job_spec = {
         key: value
         for key, value in job_spec_template.items()
         if key not in {"job_payload", "job_id", "tracing_options"}
     }
+    job_spec["job_payload"] = job_payload
+    job_spec["job_id"] = job_id
 
+    base_tracing_options = job_spec_template.get("tracing_options") or {}
+    tracing_options = dict(base_tracing_options)
+    tracing_options.setdefault("trace", True)
+    tracing_options["trace_id"] = str(current_trace_id)
+    tracing_options["ts_send"] = int(time.time() * 1000)
+    tracing_options["parent_job_id"] = parent_job_id
+    for key, value in start_key.items():
+        tracing_options[key] = value
+
+    job_spec["tracing_options"] = tracing_options
+    return job_spec
+
+
+def _create_payload_dict(
+    job_spec_template: Dict[str, Any],
+    content: str,
+    source_id: str,
+    source_name: str,
+    document_type: str,
+) -> Dict[str, Any]:
     subjob_payload_template = job_spec_template.get("job_payload", {})
     subjob_payload = {
         key: value
@@ -217,27 +235,40 @@ def _prepare_chunk_submission(
         if key not in {"content", "source_id", "source_name"}
     }
 
-    chunk_bytes = chunk["bytes"]
-    subjob_payload["content"] = [base64.b64encode(chunk_bytes).decode("utf-8")]
+    subjob_payload["content"] = [content]
 
-    page_suffix = f"page_{start_page}" if start_page == end_page else f"pages_{start_page}-{end_page}"
-    subjob_payload["source_id"] = [f"{original_source_id}#{page_suffix}"]
-    subjob_payload["source_name"] = [f"{original_source_name}#{page_suffix}"]
+    subjob_payload["source_id"] = [source_id]
+    subjob_payload["source_name"] = [source_name]
+    subjob_payload["document_type"] = [document_type]
+    return subjob_payload
+
+
+def _prepare_chunk_submission(
+    job_spec_template: Dict[str, Any],
+    chunk: Dict[str, Any],
+    *,
+    parent_uuid: uuid.UUID,
+    parent_job_id: str,
+    current_trace_id: int,
+    source_id: str,
+    source_name: str,
+    document_type: str,
+) -> Tuple[str, MessageWrapper]:
+    """Create a subjob MessageWrapper for a PDF chunk and return its identifier."""
+
+    chunk_number = chunk["chunk_index"] + 1
 
     subjob_uuid = uuid.uuid5(parent_uuid, f"chunk-{chunk_number}")
     subjob_id = str(subjob_uuid)
-    subjob_spec["job_payload"] = subjob_payload
-    subjob_spec["job_id"] = subjob_id
 
-    base_tracing_options = job_spec_template.get("tracing_options") or {}
-    tracing_options = dict(base_tracing_options)
-    tracing_options.setdefault("trace", True)
-    tracing_options["trace_id"] = str(current_trace_id)
-    tracing_options["ts_send"] = int(time.time() * 1000)
-    tracing_options["parent_job_id"] = parent_job_id
-    tracing_options["page_num"] = start_page
+    subjob_payload_template = job_spec_template.get("job_payload", {})
+    chunk_bytes = base64.b64encode(chunk["bytes"]).decode("utf-8")
+    subjob_payload = _create_payload_dict(subjob_payload_template, chunk_bytes, source_id, source_name, document_type)
+    start = chunk["start_page"] if "start_page" in chunk else chunk["start"]
 
-    subjob_spec["tracing_options"] = tracing_options
+    subjob_spec = _create_subjob_dict(
+        subjob_id, subjob_payload, job_spec_template, current_trace_id, parent_job_id, {"page_num": start}
+    )
 
     return subjob_id, MessageWrapper(payload=json.dumps(subjob_spec))
 
@@ -801,6 +832,8 @@ async def submit_job_v2(
     request: Request, response: Response, job_spec: MessageWrapper, ingest_service: INGEST_SERVICE_T
 ):
     span = trace.get_current_span()
+    source_id = None
+    document_type = None
     try:
         span.add_event("Submitting file for processing (V2)")
 
@@ -827,7 +860,19 @@ async def submit_job_v2(
 
         # Track page count for all PDFs (used for both splitting logic and metadata)
         pdf_page_count_cache = None
-
+        submission_items: List[Tuple[str, MessageWrapper]] = []
+        subjob_ids: List[str] = []
+        subjob_descriptors: List[Dict[str, Any]] = []
+        parent_metadata: Dict[str, Any] = {}
+        submission_items: List[Tuple[str, MessageWrapper]] = []
+        try:
+            parent_uuid = uuid.UUID(parent_job_id)
+        except ValueError:
+            logger.warning(
+                "Parent job id %s is not a valid UUID; generating fallback namespace for subjobs",
+                parent_job_id,
+            )
+            parent_uuid = uuid.uuid4()
         # Check if this is a PDF that needs splitting
         if document_types and payloads and document_types[0].lower() == "pdf":
             # Decode the payload to check page count
@@ -836,6 +881,7 @@ async def submit_job_v2(
             pdf_page_count_cache = page_count  # Cache for later use
             qos_tier = get_qos_tier_for_page_count(page_count)
             pages_per_chunk = get_pdf_split_page_count(client_override=client_split_page_count)
+            document_type = DocumentTypeEnum.PDF
 
             # Split if the document has more pages than our chunk size
             if page_count > pages_per_chunk:
@@ -846,13 +892,11 @@ async def submit_job_v2(
                     page_count,
                     qos_tier,
                 )
-
                 chunks = split_pdf_to_chunks(pdf_content, pages_per_chunk)
 
                 subjob_ids: List[str] = []
                 subjob_descriptors: List[Dict[str, Any]] = []
                 submission_items: List[Tuple[str, MessageWrapper]] = []
-
                 try:
                     parent_uuid = uuid.UUID(parent_job_id)
                 except ValueError:
@@ -863,14 +907,20 @@ async def submit_job_v2(
                     parent_uuid = uuid.uuid4()
 
                 for chunk in chunks:
+                    start = chunk["start_page"]
+                    end = chunk["end_page"]
+                    page_suffix = f"page_{start}" if start == end else f"pages_{start}-{end}"
+                    source_id = f"{original_source_id}#{page_suffix}"
+                    source_name = f"{original_source_name}#{page_suffix}"
                     subjob_id, subjob_wrapper = _prepare_chunk_submission(
                         job_spec_dict,
                         chunk,
+                        document_type=DocumentTypeEnum.PDF,
                         parent_uuid=parent_uuid,
                         parent_job_id=parent_job_id,
                         current_trace_id=current_trace_id,
-                        original_source_id=original_source_id,
-                        original_source_name=original_source_name,
+                        source_id=source_id,
+                        source_name=source_name,
                     )
 
                     # Inject QoS routing hint into subjob routing_options (keeps API and service loosely coupled)
@@ -895,38 +945,98 @@ async def submit_job_v2(
                             "page_count": chunk.get("page_count"),
                         }
                     )
+                parent_metadata.update(
+                    {
+                        "total_pages": page_count,
+                        "pages_per_chunk": pages_per_chunk,
+                        "original_source_id": original_source_id,
+                        "original_source_name": original_source_name,
+                        "document_type": document_types[0] if document_types else "pdf",
+                        "subjob_order": subjob_ids,
+                    }
+                )
+        elif document_types and payloads and document_types[0].lower() in ["mp4", "mov", "avi", "mp3", "wav"]:
+            document_type = document_types[0]
+            upload_path = f"./{Path(original_source_id).name}"
+            # dump the payload to a file, just came from client
+            with fsspec.open(upload_path, "wb") as f:
+                f.write(base64.b64decode(payloads[0]))
+            dataloader = DataLoader(
+                path=upload_path, output_dir="./audio_chunks/", audio_only=True, split_interval=50000000
+            )
+            document_type = DocumentTypeEnum.MP3
+
+            parent_uuid = uuid.UUID(parent_job_id)
+            for task in job_spec_dict["tasks"]:
+                if "task_properties" in task and "document_type" in task["task_properties"]:
+                    task["task_properties"]["document_type"] = document_type
+            end = 0
+            for idx, (file_path, duration) in enumerate(dataloader.files_completed):
+                start = end
+                end = int(start + duration)
+                chunk = {
+                    "bytes": file_path.encode("utf-8"),
+                    "chunk_index": idx,
+                    "start": start,
+                    "end": end,
+                }
 
-                if submission_items:
-                    burst_size, pause_ms, jitter_ms = _get_submit_burst_params()
-                    await _submit_subjobs_in_bursts(
-                        submission_items,
-                        ingest_service,
-                        burst_size=burst_size,
-                        pause_ms=pause_ms,
-                        jitter_ms=jitter_ms,
-                    )
+                subjob_id, subjob_wrapper = _prepare_chunk_submission(
+                    job_spec_dict,
+                    chunk,
+                    parent_uuid=parent_uuid,
+                    parent_job_id=parent_job_id,
+                    current_trace_id=current_trace_id,
+                    source_id=file_path,
+                    source_name=upload_path,
+                    document_type=document_type,
+                )
 
-                parent_metadata: Dict[str, Any] = {
-                    "total_pages": page_count,
-                    "pages_per_chunk": pages_per_chunk,
+                submission_items.append((subjob_id, subjob_wrapper))
+                subjob_ids.append(subjob_id)
+                subjob_descriptors.append(
+                    {
+                        "job_id": subjob_id,
+                        "chunk_index": idx + 1,
+                        "start_page": chunk.get("start"),
+                        "end_page": chunk.get("end"),
+                        "page_count": chunk.get("page_count", 0),
+                    }
+                )
+            logger.debug(f"Removing uploaded file {upload_path}")
+            os.remove(upload_path)
+
+        if submission_items:
+            burst_size, pause_ms, jitter_ms = _get_submit_burst_params()
+            await _submit_subjobs_in_bursts(
+                submission_items,
+                ingest_service,
+                burst_size=burst_size,
+                pause_ms=pause_ms,
+                jitter_ms=jitter_ms,
+            )
+
+            parent_metadata.update(
+                {
                     "original_source_id": original_source_id,
                     "original_source_name": original_source_name,
-                    "document_type": document_types[0] if document_types else "pdf",
+                    "document_type": document_type,
                     "subjob_order": subjob_ids,
                 }
+            )
+            # raise ValueError(f"Setting parent job mapping for {parent_job_id} with {len(subjob_ids)} subjobs")
+            await ingest_service.set_parent_job_mapping(
+                parent_job_id,
+                subjob_ids,
+                parent_metadata,
+                subjob_descriptors=subjob_descriptors,
+            )
 
-                await ingest_service.set_parent_job_mapping(
-                    parent_job_id,
-                    subjob_ids,
-                    parent_metadata,
-                    subjob_descriptors=subjob_descriptors,
-                )
-
-                await ingest_service.set_job_state(parent_job_id, STATE_SUBMITTED)
+            await ingest_service.set_job_state(parent_job_id, STATE_SUBMITTED)
 
-                span.add_event(f"Split into {len(subjob_ids)} subjobs")
-                response.headers["x-trace-id"] = trace.format_trace_id(current_trace_id)
-                return parent_job_id
+            span.add_event(f"Split into {len(subjob_ids)} subjobs")
+            response.headers["x-trace-id"] = trace.format_trace_id(current_trace_id)
+            return parent_job_id
 
         # For non-PDFs or cases where splitting is not required, submit as normal
         if "tracing_options" not in job_spec_dict:
@@ -982,8 +1092,8 @@ async def submit_job_v2(
         return parent_job_id
 
     except Exception as ex:
-        logger.exception(f"Error submitting job: {str(ex)}")
-        raise HTTPException(status_code=500, detail=f"Nv-Ingest Internal Server Error: {str(ex)}")
+        logger.exception(f"Error submitting job: {str(ex)}, {source_id}")
+        raise HTTPException(status_code=500, detail=f"Nv-Ingest Internal Server Error: {str(ex)}, for: \n{source_id}")
 
 
 # GET /v2/fetch_job

{nv_ingest-2025.11.9.dev20251109 → nv_ingest-2025.12.15.dev20251215}/nv_ingest/framework/orchestration/process/execution.py

@@ -162,6 +162,11 @@ def build_logging_config_from_env() -> LoggingConfig:
         if key not in os.environ:
             os.environ[key] = default_value
 
+    # For PRODUCTION mode, also suppress nv-ingest module INFO logs
+    if preset_level == "PRODUCTION":
+        logging.getLogger("nv_ingest").setLevel(logging.WARNING)
+        logging.getLogger("nv_ingest_api").setLevel(logging.WARNING)
+
     logger.info(f"Applied Ray logging preset: {preset_level}")
 
     # Get log level from environment, default to INFO
@@ -324,6 +329,7 @@ def launch_pipeline(
     pipeline_config = resolve_static_replicas(pipeline_config)
 
     # Pretty print the final pipeline configuration (after replica resolution)
+    # INFO level so it shows in docker/helm deployments; quiet mode suppresses in library mode
     pretty_output = pretty_print_pipeline_config(pipeline_config, config_path=None)
     logger.info("\n" + pretty_output)
 

{nv_ingest-2025.11.9.dev20251109 → nv_ingest-2025.12.15.dev20251215}/nv_ingest/framework/orchestration/ray/examples/pipeline_test_harness.py

@@ -150,7 +150,7 @@ if __name__ == "__main__":
     os.environ["OCR_GRPC_ENDPOINT"] = "localhost:8010"
     os.environ["OCR_INFER_PROTOCOL"] = "grpc"
     os.environ["OCR_MODEL_NAME"] = "paddle"
-    os.environ["NEMORETRIEVER_PARSE_HTTP_ENDPOINT"] = "https://integrate.api.nvidia.com/v1/chat/completions"
+    os.environ["NEMOTRON_PARSE_HTTP_ENDPOINT"] = "https://integrate.api.nvidia.com/v1/chat/completions"
     os.environ["VLM_CAPTION_ENDPOINT"] = "https://integrate.api.nvidia.com/v1/chat/completions"
     os.environ["VLM_CAPTION_MODEL_NAME"] = "nvidia/nemotron-nano-12b-v2-vl"
     logger.info("Environment variables set.")
@@ -170,23 +170,23 @@ if __name__ == "__main__":
         yolox_graphic_elements_auth,
         yolox_graphic_elements_protocol,
     ) = get_nim_service("yolox_graphic_elements")
-    nemoretriever_parse_grpc, nemoretriever_parse_http, nemoretriever_parse_auth, nemoretriever_parse_protocol = (
-        get_nim_service("nemoretriever_parse")
+    nemotron_parse_grpc, nemotron_parse_http, nemotron_parse_auth, nemotron_parse_protocol = get_nim_service(
+        "nemotron_parse"
     )
     ocr_grpc, ocr_http, ocr_auth, ocr_protocol = get_nim_service("ocr")
 
-    model_name = os.environ.get("NEMORETRIEVER_PARSE_MODEL_NAME", "nvidia/nemoretriever-parse")
+    model_name = os.environ.get("NEMOTRON_PARSE_MODEL_NAME", "nvidia/nemotron-parse")
     pdf_extractor_config = {
         "pdfium_config": {
             "auth_token": yolox_auth,  # All auth tokens are the same for the moment
             "yolox_endpoints": (yolox_grpc, yolox_http),
             "yolox_infer_protocol": yolox_protocol,
         },
-        "nemoretriever_parse_config": {
-            "auth_token": nemoretriever_parse_auth,
-            "nemoretriever_parse_endpoints": (nemoretriever_parse_grpc, nemoretriever_parse_http),
-            "nemoretriever_parse_infer_protocol": nemoretriever_parse_protocol,
-            "nemoretriever_parse_model_name": model_name,
+        "nemotron_parse_config": {
+            "auth_token": nemotron_parse_auth,
+            "nemotron_parse_endpoints": (nemotron_parse_grpc, nemotron_parse_http),
+            "nemotron_parse_infer_protocol": nemotron_parse_protocol,
+            "nemotron_parse_model_name": model_name,
             "yolox_endpoints": (yolox_grpc, yolox_http),
             "yolox_infer_protocol": yolox_protocol,
         },

{nv_ingest-2025.11.9.dev20251109 → nv_ingest-2025.12.15.dev20251215}/nv_ingest/framework/orchestration/ray/stages/extractors/audio_extractor.py

@@ -5,7 +5,6 @@
 
 import logging
 from typing import Optional
-
 import ray
 
 from nv_ingest.framework.orchestration.ray.stages.meta.ray_actor_stage_base import RayActorStage
@@ -67,7 +66,6 @@ class AudioExtractorStage(RayActorStage):
         # Extract the DataFrame payload.
         df_ledger = control_message.payload()
         self._logger.debug("Extracted payload with %d rows.", len(df_ledger))
-
         # Remove the "audio_data_extract" task from the message to obtain task-specific configuration.
         task_config = remove_task_by_type(control_message, "extract")
         self._logger.debug("Extracted task config: %s", sanitize_for_logging(task_config))

nv_ingest-2025.12.15.dev20251215/nv_ingest/framework/orchestration/ray/stages/extractors/ocr_extractor.py

@@ -0,0 +1,71 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-25, NVIDIA CORPORATION & AFFILIATES.
+# All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+import logging
+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_api.internal.extract.image.ocr_extractor import extract_text_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, set_trace_timestamps_with_parent_context
+from nv_ingest_api.internal.schemas.extract.extract_ocr_schema import OCRExtractorSchema
+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 OCRExtractorStage(RayActorStage):
+    """
+    A Ray actor stage that extracts text data from image content.
+
+    It expects an IngestControlMessage containing a DataFrame with image data. It then:
+      1. Removes the "text_data_extract" task from the message.
+      2. Calls the text extraction logic using a validated configuration.
+      3. Updates the message payload with the extracted text DataFrame.
+    """
+
+    def __init__(self, config: OCRExtractorSchema, 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("OCRExtractorStage configuration validated successfully.")
+        except Exception as e:
+            self._logger.exception(f"Error validating Text extractor config: {e}")
+            raise
+
+    @nv_ingest_node_failure_try_except()
+    @traceable()
+    @udf_intercept_hook()
+    @filter_by_task(required_tasks=["ocr_data_extract"])
+    def on_data(self, control_message: IngestControlMessage) -> IngestControlMessage:
+        # Extract DataFrame payload
+        df_ledger = control_message.payload()
+        if df_ledger.empty:
+            return control_message
+
+        # Remove the "text_data_extract" task from the message
+        task_config = remove_task_by_type(control_message, "ocr_data_extract")
+
+        execution_trace_log = {}
+        new_df, extraction_info = extract_text_data_from_image_internal(
+            df_extraction_ledger=df_ledger,
+            task_config=task_config,
+            extraction_config=self.validated_config,
+            execution_trace_log=execution_trace_log,
+        )
+
+        control_message.payload(new_df)
+        control_message.set_metadata("ocr_extraction_info", extraction_info)
+
+        do_trace_tagging = control_message.get_metadata("config::add_trace_tagging") is True
+        if do_trace_tagging and execution_trace_log:
+            parent_name = self.stage_name if self.stage_name else "ocr_extractor"
+            set_trace_timestamps_with_parent_context(control_message, execution_trace_log, parent_name, logger)
+
+        return control_message

nv_ingest-2025.12.15.dev20251215/nv_ingest/framework/orchestration/ray/stages/meta/udf_parallel_helper.py

@@ -0,0 +1,64 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024-25, NVIDIA CORPORATION & AFFILIATES.
+# All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+# Added this no-op UDF ray stage to the pipeline to help speed up the LLM api calls
+
+"""
+UDF Parallel Stage - A high-concurrency no-op stage for parallel UDF execution.
+
+This stage does nothing except pass messages through, but with high replica count
+it provides a parallel execution pool for UDFs to achieve N-way concurrency.
+"""
+
+import logging
+from typing import Any, Optional
+from pydantic import BaseModel
+import ray
+
+from nv_ingest.framework.orchestration.ray.stages.meta.ray_actor_stage_base import RayActorStage
+from nv_ingest.framework.util.flow_control.udf_intercept import udf_intercept_hook
+from nv_ingest_api.internal.primitives.tracing.tagging import traceable
+from nv_ingest_api.util.exception_handlers.decorators import (
+    nv_ingest_node_failure_try_except,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@ray.remote
+class UDFParallelStage(RayActorStage):
+    """
+    A no-op pass-through stage designed for parallel UDF execution.
+
+    This stage simply returns the input message unchanged, but when configured
+    with multiple replicas, it provides a high-concurrency pool for UDFs to
+    achieve parallel execution without blocking.
+    """
+
+    def __init__(self, config: BaseModel, stage_name: Optional[str] = None) -> None:
+        super().__init__(config, stage_name=stage_name)
+        logger.info(f"UDFParallelStage initialized: {stage_name}")
+
+    @nv_ingest_node_failure_try_except()
+    @traceable()
+    @udf_intercept_hook()
+    def on_data(self, message: Any) -> Any:
+        """
+        Pass-through processing that simply returns the message unchanged.
+
+        The @udf_intercept_hook decorator allows UDFs to target this stage,
+        and multiple replicas provide parallel execution capacity.
+
+        Parameters
+        ----------
+        message : Any
+            The incoming control message.
+
+        Returns
+        -------
+        Any
+            The unmodified control message.
+        """
+        # No-op: just return the message
+        return message