Merge remote-tracking branch 'origin/main' into dev/mahikaw/agentic-enhancements

# Conflicts:
#	nemo_retriever/src/nemo_retriever/cli/query/options.py

Author: mahikaw

.github/workflows/reusable-pypi-publish.yml

@@ -84,7 +84,8 @@ jobs:
           DIST_FILES=(./dist/nemo_retriever/dist/*.whl ./dist/nemo_retriever/dist/*.tar.gz)
           echo "After legacy glob: count=${#DIST_FILES[@]} files=${DIST_FILES[*]:-<none>}"
 
-          # Flat layout (older upload-artifact glob uploads): ./dist/*
+          # Flat layout (upload-artifact strips to the common parent, so wheels
+          # often land directly under ./dist/): ./dist/*
           if [ "${#DIST_FILES[@]}" -eq 0 ]; then
             DIST_FILES=(./dist/*.whl ./dist/*.tar.gz)
             echo "After flat glob: count=${#DIST_FILES[@]} files=${DIST_FILES[*]:-<none>}"

Dockerfile

@@ -4,6 +4,8 @@
 # syntax=docker/dockerfile:1.3
 #
 # Build from repo root: docker build -f Dockerfile -t nemo-retriever .
+# Service (NIM-forwarding): docker build -f Dockerfile --target service -t nemo-retriever-service .
+# Service + in-pod HF:      docker build -f Dockerfile --target service-gpu -t nemo-retriever-service-gpu .
 # Runtime ffmpeg/ffprobe install for service image: docker run -e INSTALL_FFMPEG=true nemo-retriever-service
 # Run: docker run nemo-retriever  (shell with venv active)
 # Run with dev mount: docker run -v $(pwd):/workspace -it nemo-retriever   (code changes reflect without rebuild)
@@ -116,6 +118,22 @@ RUN --mount=type=cache,target=/root/.cache/pip \
     . /opt/retriever_runtime/bin/activate \
     && uv pip install -e "./nemo_retriever[service]"
 
+# GPU service install: in-pod Hugging Face models + multimedia (ASR, SVG).
+# Build target: service-gpu
+FROM base AS install-service-gpu
+
+WORKDIR /workspace
+
+ENV PYTHONUNBUFFERED=1
+ENV VIRTUAL_ENV=/opt/retriever_runtime
+ENV PATH=/opt/retriever_runtime/bin:$PATH
+
+SHELL ["/bin/bash", "-c"]
+RUN --mount=type=cache,target=/root/.cache/pip \
+    --mount=type=cache,target=/root/.cache/uv \
+    . /opt/retriever_runtime/bin/activate \
+    && uv pip install -e "./nemo_retriever[service,local,multimedia]"
+
 # Default: run in-process pipeline (help if no args)
 CMD ["/bin/bash"]
 
@@ -167,3 +185,45 @@ USER nemo
 ENTRYPOINT ["/usr/local/bin/retriever-service-entrypoint"]
 
 CMD ["retriever", "service", "start", "--config", "/etc/nemo-retriever/retriever-service.yaml"]
+
+# ---------------------------------------------------------------------------
+# GPU service profile: FastAPI ingest service with in-pod Hugging Face models.
+#
+# Build:  docker build -f Dockerfile --target service-gpu \
+#             -t nemo-retriever-service-gpu .
+#
+# Run (requires --gpus all and local_models.enabled in config):
+#   docker run --rm --gpus all -p 7670:7670 \
+#     -v /host/retriever-service.yaml:/etc/nemo-retriever/retriever-service.yaml:ro \
+#     nemo-retriever-service-gpu
+# ---------------------------------------------------------------------------
+FROM install-service-gpu AS service-gpu
+
+ENV NEMO_RETRIEVER_SERVICE_CONFIG=/etc/nemo-retriever/retriever-service.yaml
+
+ENV PATH=/opt/retriever_runtime/bin:$PATH
+
+COPY docker/scripts/retriever_service_entrypoint.sh /usr/local/bin/retriever-service-entrypoint
+COPY docker/scripts/retriever_install_ffmpeg.sh /usr/local/sbin/retriever-install-ffmpeg
+
+RUN chmod a+rx /usr/local/bin/uv /usr/local/bin/uvx /usr/local/bin/retriever-service-entrypoint \
+        /usr/local/sbin/retriever-install-ffmpeg \
+    && chmod -R a+rX /opt/uv \
+    && groupadd -r -g 1000 nemo && useradd -r -u 1000 -g nemo -d /workspace -s /sbin/nologin nemo \
+    && printf '%s\n' \
+         'nemo ALL=(root) NOPASSWD: /usr/local/sbin/retriever-install-ffmpeg' \
+         > /etc/sudoers.d/nemo-ffmpeg \
+    && chmod 0440 /etc/sudoers.d/nemo-ffmpeg \
+    && visudo -cf /etc/sudoers.d/nemo-ffmpeg \
+    && mkdir -p /etc/nemo-retriever /var/lib/nemo-retriever \
+    && cp /workspace/nemo_retriever/src/nemo_retriever/service/retriever-service.yaml \
+            "${NEMO_RETRIEVER_SERVICE_CONFIG}" \
+    && chown -R nemo:nemo /workspace /etc/nemo-retriever /var/lib/nemo-retriever /opt/retriever_runtime
+
+EXPOSE 7670
+
+USER nemo
+
+ENTRYPOINT ["/usr/local/bin/retriever-service-entrypoint"]
+
+CMD ["retriever", "service", "start", "--config", "/etc/nemo-retriever/retriever-service.yaml"]

docs/docs/extraction/audio-video.md

@@ -100,6 +100,8 @@ Instead of running the pipeline locally, you can call Parakeet through [build.nv
 
 2. Run inference from Python with the hosted gRPC endpoint and credentials from that page (the example below uses the default hosted gRPC hostname; confirm values in the **Get API Key** flow for your deployment). Pass hosted endpoint, function ID, and API key through `ASRParams` (`audio_endpoints`, `function_id`, `auth_token`).
 
+    For parameter details, refer to the [Python API guide](nemo-retriever-api-reference.md).
+
     ```python
     from nemo_retriever import create_ingestor
     from nemo_retriever.common.params.models import ASRParams

docs/docs/extraction/concepts.md

@@ -2,40 +2,40 @@
 
 These terms appear throughout NeMo Retriever Library documentation.
 
-## Job
+## Job { #job }
 
 An **ingestion job** is a unit of work you run on input content (documents, audio, video, and other supported types). You submit jobs through the **ingestor Python API** (for example `Ingestor` task chains such as `.extract(...)`) or the **`retriever ingest` CLI**—not by posting a standalone JSON job document. Default tasks target strong recall; customize behavior with task keyword arguments (including chunking and splitting on `.extract()`) or custom UDF-style operations ([NeMo Retriever graph](https://github.com/NVIDIA/NeMo-Retriever/tree/main/nemo_retriever/src/nemo_retriever/graph#nemo-retriever-graph)). Results are structured metadata and annotations (Ray Dataset, pandas `DataFrame`, or similar).
 
-## Pipeline and tasks
+## Pipeline and tasks { #pipeline-and-tasks }
 
 NeMo Retriever Library does **not** run one static pipeline on every document. You configure **tasks** such as parsing, chunking, embedding, storage, and filtering per job. Related topics: [Extending/Customizing NeMo Retriever Library with custom code](https://github.com/NVIDIA/NeMo-Retriever/tree/main/nemo_retriever/src/nemo_retriever/graph#nemo-retriever-graph).
 
-## Extraction metadata
+## Extraction metadata { #extraction-metadata }
 
 Output is a **Ray Dataset** (Ray Data) or **pandas** `DataFrame` listing extracted objects (text regions, tables, images, and so on), processing notes, and timing or trace data. Field-level detail is in the [metadata reference](content-metadata.md).
 
-## Embeddings and retrieval
+## Embeddings and retrieval { #embeddings-and-retrieval }
 
-Optionally, the library can compute **embeddings** for extracted content and store vectors in [LanceDB](https://lancedb.com/) for downstream semantic search in your application. For upload and retrieval APIs, see [Vector databases](vdbs.md). For multimodal (VLM) embedding options, see [Multimodal embeddings (VLM)](embedding.md).
+Optionally, the library can compute **embeddings** for extracted content and store vectors in [LanceDB](https://lancedb.com/) for downstream semantic search in your application. For upload and retrieval APIs, refer to [Vector databases](vdbs.md). For multimodal (VLM) embedding options, refer to [Multimodal embeddings (VLM)](embedding.md).
 
 ## Chunking { #chunking }
 
 Chunking is built into the `.extract()` task and depends on **content type**:
 
 - **PDF, DOCX, and PPTX** — Text is grouped using built-in **page** boundaries (one chunk per page where the format has pages).
-- **Plain text (`.txt`) and HTML** — Formats without natural page breaks are split into segments of **1024 tokens** by default, using the [Llama 3.2 1B tokenizer](https://huggingface.co/meta-llama/Llama-3.2-1B) so chunk boundaries stay aligned with the default embedding tokenizer. The NeMo Retriever container image bundles this tokenizer, so default text chunking does not require a Hugging Face access token. See [Token-based splitting](#token-based-splitting) and [Environment variables](environment-config.md) for overrides and other runtimes.
-- **Audio and video** — Media is split into **segments** for decoding and ASR using ffmpeg-based rules (configurable **size**, **time**, or **frame** split modes in the media chunking stage). With the Parakeet ASR path, you can optionally emit **sentence-like segments** using `extract_audio_params={"segment_audio": True}`; see [Speech and audio extraction](audio-video.md#speech-and-audio-extraction).
+- **Plain text (`.txt`) and HTML** — Formats without natural page breaks are split into segments of **1024 tokens** by default, using the [Llama 3.2 1B tokenizer](https://huggingface.co/meta-llama/Llama-3.2-1B) so chunk boundaries stay aligned with the default embedding tokenizer. The NeMo Retriever container image bundles this tokenizer, so default text chunking does not require a Hugging Face access token. Refer to [Token-based splitting](#token-based-splitting) and [Environment variables](environment-config.md) for overrides and other runtimes.
+- **Audio and video** — Media is split into **segments** for decoding and ASR using ffmpeg-based rules (configurable **size**, **time**, or **frame** split modes in the media chunking stage). With the Parakeet ASR path, you can optionally emit **sentence-like segments** using `extract_audio_params={"segment_audio": True}`; refer to [Speech and audio extraction](audio-video.md#speech-and-audio-extraction).
 
-For PDF parallelism before Ray processing (large files), see [PDF pre-splitting for parallel ingest](nemo-retriever-api-reference.md#pdf-pre-splitting-for-parallel-ingest).
+For PDF parallelism before Ray processing (large files), refer to [PDF pre-splitting for parallel ingest](nemo-retriever-api-reference.md#pdf-pre-splitting-for-parallel-ingest).
 
 ### Token-based splitting { #token-based-splitting }
 
-Token-based splitting uses the Llama 3.2 1B tokenizer (default `meta-llama/Llama-3.2-1B`) with configurable `max_tokens` and `overlap_tokens` when you add an explicit `.split(...)` stage or when the pipeline applies the default text segmentation for unstructured text. In the shipped NeMo Retriever container, tokenizer assets are included locally, so you do not need `HF_ACCESS_TOKEN` for this default path. If your runtime loads the tokenizer from the Hugging Face Hub instead (for example, some library-only installs), set `HF_ACCESS_TOKEN` or pass `hf_access_token` in task params when the Hub requires it. Details appear in the [Python API guide](nemo-retriever-api-reference.md).
+Token-based splitting uses the Llama 3.2 1B tokenizer (default `meta-llama/Llama-3.2-1B`) with configurable `max_tokens` and `overlap_tokens` when you add an explicit `.split(...)` stage or when the pipeline applies the default text segmentation for unstructured text. In the shipped NeMo Retriever container, tokenizer assets are included locally, so you do not need `HF_ACCESS_TOKEN` for this default path. If your runtime loads the tokenizer from the Hugging Face Hub instead (for example, some library-only installs), set `HF_ACCESS_TOKEN` or pass `hf_access_token` in task params when the Hub requires it. For parameter details, refer to the [Python API guide](nemo-retriever-api-reference.md).
 
-## Deployment modes
+## Deployment modes { #deployment-modes }
 
-- **Library mode** — Run without the full container stack where appropriate; see [Deployment options](deployment-options.md).
-- **Kubernetes / Helm (self-hosted)** — See [Deploy (Helm chart)](https://github.com/NVIDIA/NeMo-Retriever/blob/main/nemo_retriever/helm/README.md) and [deployment options](deployment-options.md) for running the full microservices pipeline on your infrastructure.
+- **Library mode** — Run without the full container stack where appropriate; refer to [Deployment options](deployment-options.md).
+- **Kubernetes / Helm (self-hosted)** — Refer to [Deploy (Helm chart)](https://github.com/NVIDIA/NeMo-Retriever/blob/main/nemo_retriever/helm/README.md) and [deployment options](deployment-options.md) for running the full microservices pipeline on your infrastructure.
 - **Notebooks** — [Jupyter examples](starter-kits.md) for experimentation and RAG demos.
 
 For a concise comparison, refer to [Deployment options](deployment-options.md).

docs/docs/extraction/deployment-options.md

@@ -19,10 +19,10 @@ Build and run the NeMo Retriever service image with the [Docker service image gu
 
 1. [Pre-Requisites & Support Matrix](prerequisites-support-matrix.md)
 2. **NeMo Retriever Helm chart (supported):** [Deploy (Helm chart)](https://github.com/NVIDIA/NeMo-Retriever/blob/main/nemo_retriever/helm/README.md) — sources in [`nemo_retriever/helm`](https://github.com/NVIDIA/NeMo-Retriever/tree/main/nemo_retriever/helm) on GitHub
-3. **Published Library Helm charts (supported):** cluster install and upgrade procedures are covered in the [NeMo Retriever Library](https://docs.nvidia.com/nemo/retriever/latest/extraction/overview/) — use alongside the NeMo Retriever chart README for your release
+3. **Published Library Helm charts (supported):** cluster install and upgrade procedures are covered in [About getting started](getting-started-about.md) — use alongside the NeMo Retriever chart README for your release
 4. [Environment variables](environment-config.md) and [Troubleshoot](troubleshoot.md) as needed
 
-**Core NIMs for the default extraction pipeline** (26.05): `page_elements`, `table_structure`, `ocr`, and `vlm_embed` (`llama-nemotron-embed-vl-1b-v2:1.12.0`). These four are auto-wired into the retriever service. **Nemotron Parse**, **Nemotron 3 Nano Omni**, the **VL reranker**, and **Parakeet ASR** are optional and not auto-wired. For a minimal GPU footprint, disable optional keys you do not need (refer to [Recommended minimal install (26.05)](https://github.com/NVIDIA/NeMo-Retriever/blob/26.05/nemo_retriever/helm/README.md#recommended-minimal-install-2605)). Refer to [Pre-Requisites & Support Matrix — Default Helm NIMs](prerequisites-support-matrix.md#default-helm-nims).
+**Core NIMs for the default extraction pipeline:** `page_elements`, `table_structure`, `ocr`, and `vlm_embed` (`llama-nemotron-embed-vl-1b-v2:1.12.0`). These four are auto-wired into the retriever service. **Nemotron Parse**, **Nemotron 3 Nano Omni**, the **VL reranker**, and **Parakeet ASR** are optional and not auto-wired. For a minimal GPU footprint, disable optional keys you do not need (refer to [Recommended minimal install](https://github.com/NVIDIA/NeMo-Retriever/blob/main/nemo_retriever/helm/README.md#recommended-minimal-install-2605)). Refer to [Pre-Requisites & Support Matrix — Default Helm NIMs](prerequisites-support-matrix.md#default-helm-nims).
 
 For audio and video extraction in Kubernetes, set `service.installFfmpeg=true` so the service container installs `ffmpeg` and `ffprobe` at startup. This runtime install requires package-repository network egress, a writable root filesystem, and security policy that allows the image's scoped sudo use. If your cluster blocks startup package installation, use a custom service image that already contains `ffmpeg` and `ffprobe`, then set `service.image.repository` and `service.image.tag`. For Parakeet ASR chart values, OpenShift-specific Helm configuration, and air-gapped alternatives, refer to [Audio and video (Parakeet ASR)](https://github.com/NVIDIA/NeMo-Retriever/blob/main/nemo_retriever/helm/README.md#audio-video-parakeet) and [OpenShift deployment](https://github.com/NVIDIA/NeMo-Retriever/blob/main/nemo_retriever/helm/openshift.md) in the Helm chart directory.
 
@@ -41,7 +41,7 @@ For audio and video extraction in Kubernetes, set `service.installFfmpeg=true` s
 2. [Throughput is dataset-dependent](multimodal-extraction.md#extraction-limitations-and-quality)
 3. [Evaluate on your data](evaluate-on-your-data.md)
 
-## When to use NVIDIA-hosted NIMs
+## When to use NVIDIA-hosted NIMs { #when-to-use-nvidia-hosted-nims }
 
 [NVIDIA-hosted NIMs](https://build.nvidia.com/) run inference on NVIDIA-managed infrastructure. You call models with API keys (refer to [Get your API key](api-keys.md)) without operating GPU nodes yourself.
 
@@ -53,7 +53,7 @@ Consider hosted NIMs when:
 
 **Also refer to:** [NVIDIA NIM catalog](https://build.nvidia.com/)
 
-## When to self-host NIMs
+## When to self-host NIMs { #when-to-self-host-nims }
 
 Self-hosted NIMs run on your GPUs or air-gapped hardware, typically with Kubernetes and the [NIM Operator](https://docs.nvidia.com/nim-operator/latest/index.html).
 
@@ -69,17 +69,17 @@ Consider self-hosting when:
 
 The **default document extraction pipeline** (page elements, table structure, OCR, and VL embed) runs disconnected when you mirror images and models into a private registry and configure the [NIM Operator for air-gapped environments](https://docs.nvidia.com/nim-operator/latest/air-gap.html).
 
-On a staging host with internet access, pull from NGC, retag to your private registry, stage chart archives, then install in the enclave with registry overrides. Procedures, the 26.05 image inventory, and Helm value patterns are in [Helm — Air-gapped deployment](https://github.com/NVIDIA/NeMo-Retriever/blob/26.05/nemo_retriever/helm/README.md#air-gapped-deployment).
+On a staging host with internet access, pull from NGC, retag to your private registry, stage chart archives, then install in the enclave with registry overrides. Procedures, the chart image inventory, and Helm value patterns are in [Helm — Air-gapped deployment](https://github.com/NVIDIA/NeMo-Retriever/blob/main/nemo_retriever/helm/README.md#air-gapped-deployment).
 
 !!! warning "Audio and video extraction"
 
     [Audio and video](audio-video.md) need **`ffmpeg` and `ffprobe` on `PATH`**. The bundled image omits them. Do **not** use `service.installFfmpeg=true` in an air gap (startup install needs package-repo egress). Build a custom service image on a connected staging host, mirror it, and set `service.image.repository` / `service.image.tag`. Skip this step if you do not use audio/video.
 
-For offline image captioning, deploy the in-cluster [Nemotron 3 Nano Omni](prerequisites-support-matrix.md#image-captioning-2605) NIM and point your pipeline caption endpoint at the in-cluster HTTP URL instead of `integrate.api.nvidia.com` or other hosted APIs.
+For offline image captioning, deploy the in-cluster [Nemotron 3 Nano Omni](prerequisites-support-matrix.md#image-captioning) NIM and point your pipeline caption endpoint at the in-cluster HTTP URL instead of `integrate.api.nvidia.com` or other hosted APIs.
 
 **Related**
 
-- [Deploy (Helm chart)](https://github.com/NVIDIA/NeMo-Retriever/blob/26.05/nemo_retriever/helm/README.md) ([`nemo_retriever/helm`](https://github.com/NVIDIA/NeMo-Retriever/tree/26.05/nemo_retriever/helm) on GitHub) — [air-gapped deployment](https://github.com/NVIDIA/NeMo-Retriever/blob/26.05/nemo_retriever/helm/README.md#air-gapped-deployment)
-- [NeMo Retriever Library — prerequisites / deployment](https://docs.nvidia.com/nemo/retriever/latest/extraction/overview/) (supported **Helm** handoff)
+- [Deploy (Helm chart)](https://github.com/NVIDIA/NeMo-Retriever/blob/main/nemo_retriever/helm/README.md) ([`nemo_retriever/helm`](https://github.com/NVIDIA/NeMo-Retriever/tree/main/nemo_retriever/helm) on GitHub) — [air-gapped deployment](https://github.com/NVIDIA/NeMo-Retriever/blob/main/nemo_retriever/helm/README.md#air-gapped-deployment)
+- [About getting started](getting-started-about.md) (prerequisites through first deployment)
 - [Pre-Requisites & Support Matrix](prerequisites-support-matrix.md)
 - [Audio and video](audio-video.md)