Merge branch 'main' into docs/ocr-v2-defaults

Author: kheiss-uwzoo

docs/docs/extraction/deployment-options.md

@@ -24,7 +24,7 @@ Build and run the NeMo Retriever service image with the [Docker service image gu
 
 **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).
 
-For audio and video dependencies and OpenShift-specific Helm configuration, 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.
+For audio and video extraction in Kubernetes, set `service.installFfmpeg=true` so the service installs `ffmpeg` and `ffprobe` at container startup. This runtime install requires package-repository egress and cluster policy that allows the image's scoped sudo use. For Helm chart procedures, OpenShift-specific 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.
 
 ### I want examples and notebooks
 

nemo_retriever/docs/cli/README.md

@@ -6,7 +6,8 @@ ingest and retrieval.
 For product-facing examples, prefer these commands:
 
 - `retriever ingest` - ingest supported documents and media into a Retriever index.
-- `retriever query` - query a local LanceDB table written by ingest.
+- `retriever query` - query a local LanceDB table written by local or batch ingest.
+- `retriever query service` - query a Retriever service deployment.
 
 `retriever pipeline run` remains available as a development and compatibility
 command for legacy pipeline workflows, evaluation, intermediate artifacts, and
@@ -69,9 +70,8 @@ retriever query "What is in this document?" \
 By default, local ingest writes to `lancedb/nemo-retriever` and `retriever query`
 reads from the same table.
 
-The `retriever query` examples below apply to local and batch ingest output
-written to LanceDB. Service ingest sends documents to a remote service; querying
-service-owned storage is handled by that service deployment.
+The plain `retriever query` examples below apply to local and batch ingest output
+written to LanceDB. Use `retriever query service` to query a Retriever service.
 
 ### Ingest a larger corpus with batch mode
 
@@ -94,8 +94,13 @@ retriever ingest service ./data/pdf_corpus \
 ```
 
 Use `--service-api-token` or `NEMO_RETRIEVER_API_TOKEN` when the service requires
-a bearer token. Service ingest does not expose `--lancedb-uri`; the service owns
-its vector database configuration.
+a bearer token. Service ingest does not expose `--lancedb-uri`; the service
+configures its vector database. Query the service with:
+
+```bash
+retriever query service "What is in this corpus?" \
+  --service-url http://localhost:7670
+```
 
 ### Route ingest to hosted or self-hosted NIM endpoints
 
@@ -131,9 +136,10 @@ retriever query "What is in this document?" \
 
 ### Query result controls
 
-`retriever query` returns compact JSON hits with `source`, `page_number`, and
-`text`. Use `--candidate-k`, `--page-dedup`, and `--content-types` to shape the
-result set after vector retrieval:
+Both `retriever query` and `retriever query service` return compact JSON hits
+with `source`, `page_number`, and `text`. Use `--candidate-k`, `--page-dedup`,
+and `--content-types` to control how results are selected after vector
+retrieval:
 
 ```bash
 retriever query "annual revenue by region" \
@@ -142,19 +148,80 @@ retriever query "annual revenue by region" \
   --content-types table
 ```
 
-`--top-k` is the final number of hits returned. `--candidate-k` is the wider
-candidate pool retrieved before page deduplication, content-type filtering, and
-final truncation. It must be greater than or equal to `--top-k`, and should
-usually be larger when page deduplication or content-type filtering might
-otherwise remove too many of the top retrieved rows. Page deduplication and
-content-type filtering are applied after vector retrieval, preserving the
-retriever's ranking order and truncating the final output to `--top-k`.
-When querying a table ingested with an explicit embedding model, pass the same
-`--embed-model-name` to `retriever query`.
+`--top-k` is the final number of results to return after filtering and
+deduplication. `--candidate-k` is the number of raw results to retrieve from
+LanceDB or the Retriever service before filtering, page deduplication, and
+final truncation. If omitted, the candidate pool is the same size as
+`--top-k`. Set `--candidate-k` larger than `--top-k` when page deduplication
+or content-type filtering might remove too many of the nearest retrieved rows.
+It must always be greater than or equal to `--top-k`.
+
+Page deduplication and content-type filtering are applied after vector
+retrieval, preserving retriever ranking order and truncating the final output to
+`--top-k`. When querying a local table ingested with an explicit embedding
+model, pass the same `--embed-model-name` to `retriever query`.
+
 `--content-types` accepts comma-separated content types such as `text`, `table`,
 `chart`, `image`, and `infographic`. `images` is accepted as an alias for
-captioned image rows emitted by ingest. Hits with missing or unknown content
-types are excluded while `--content-types` is active.
+captioned image rows emitted by ingest. This option filters by content-type
+metadata only; it does not filter by source, page, or other metadata
+predicates. Hits with missing or unknown content-type metadata are excluded
+while `--content-types` is active. In service mode, results must include
+content-type metadata to match this filter. Default display values in the JSON
+output are not used for content-type matching.
+
+### Agentic retrieval
+
+`--agentic` swaps the single dense pass for an LLM-driven ReAct loop: the agent
+issues several retrieval sub-queries, fuses the candidates, and selects a final
+ranking. It searches the same LanceDB table built by `retriever ingest`, so it is
+a drop-in alternative to standard retrieval — add `--agentic` and name the chat
+model the agent drives with `--agentic-llm-model` (required):
+
+```bash
+retriever query "how does the ingestion pipeline handle tables?" \
+  --agentic \
+  --agentic-llm-model nvidia/llama-3.3-nemotron-super-49b-v1.5
+
+# remote agent + embedding endpoints, fewer reasoning rounds
+retriever query "summarize the deployment options" \
+  --agentic \
+  --agentic-llm-model nvidia/llama-3.3-nemotron-super-49b-v1.5 \
+  --agentic-invoke-url http://localhost:9000/v1/chat/completions \
+  --embed-invoke-url http://localhost:8000/v1 \
+  --agentic-react-max-steps 5
+```
+
+Unlike the dense path (which returns text-enriched hits), agentic mode returns
+the agent's ranked document IDs as JSON, each annotated with the source that
+produced it (`final_results`, `rrf`, or `selection_agent`). It reuses the same
+`--top-k`, `--lancedb-uri`, `--table-name`, `--embed-invoke-url`, and
+`--embed-model-name` options as standard retrieval.
+
+**How it works.** Each agentic query runs `Query → ReActAgentOperator → (RRF
+fusion) → SelectionAgentOperator → ranked results`:
+
+- `ReActAgentOperator` runs the per-query ReAct loop; every `retrieve` tool call
+  delegates to the standard `Retriever`, so the agent searches the same vector
+  DB and embedding config as dense retrieval.
+- `RRFAggregatorOperator` fuses candidates from the loop's multiple searches with
+  reciprocal rank fusion.
+- `SelectionAgentOperator` runs a final LLM selection pass over the fused set and
+  emits the ranked document IDs.
+
+Agentic-only knobs (apply only with `--agentic`):
+
+- `--agentic-invoke-url` — OpenAI-compatible chat-completions endpoint for the
+  agent LLM; defaults to the operators' built-in endpoint when omitted.
+- `--agentic-reasoning-effort` (default `high`) — `reasoning_effort` forwarded on
+  agentic LLM calls.
+- `--agentic-backend-top-k` (default `20`) — candidates pulled from the vector DB
+  per retrieval call.
+- `--agentic-react-max-steps` (default `50`) — maximum ReAct loop iterations.
+- `--agentic-text-truncation` (default `0`) — max characters of each candidate
+  shown to the agent; `0` disables truncation.
+- `--agentic-temperature` (default `0.0`) — sampling temperature for agentic LLM
+  calls (`0.0` = greedy).
 
 <!-- --8<-- [end:quickstart] -->