docs(cli): correct agentic query JSON contract (NVBug 6657480)

docs/docs/extraction/agentic-retrieval-concept.md

@@ -4,7 +4,7 @@
 
 NeMo Retriever Library includes a first-class agentic query path. `retriever query --agentic`, `POST /v1/query` with `agentic=true`, and the `agentic_query` Model Context Protocol (MCP) tool run a Reason and Act (ReAct) loop over the same LanceDB table that one-pass retrieval uses. You do not have to implement the agent loop in application code.
 
-The agentic path ranks documents rather than chunks, and returns the same hit fields as one-pass retrieval for each selected document. Local CLI and harness runs default to an in-process vLLM agent LLM. Retriever Service requires a remote OpenAI-compatible chat-completions endpoint. A self-hosted vLLM-backed NIM must enable automatic tool choice and a tool-call parser. Helm `answer_llm` does not turn those options on by default.
+The agentic path ranks documents rather than chunks. CLI `--agentic` output is the retrieval-hop hit plus `doc_id`, `rank`, and `result_source`. It is not the five-field dense CLI projection. Local CLI and harness runs default to an in-process vLLM agent LLM. Retriever Service requires a remote OpenAI-compatible chat-completions endpoint. A self-hosted vLLM-backed NIM must enable automatic tool choice and a tool-call parser. Helm `answer_llm` does not turn those options on by default.
 
 For commands, service configuration, request and response contracts, and failure behavior, refer to [Workflow: Agentic retrieval](workflow-agentic-retrieval.md).
 

docs/docs/extraction/workflow-agentic-retrieval.md

@@ -221,19 +221,21 @@ The `ingest_documents` MCP tool accepts either paths visible to the MCP server p
 
 ## Result contract { #result-contract }
 
-One-pass retrieval returns text-enriched chunk hits. Agentic retrieval ranks documents, and returns the same hit fields as one-pass retrieval for each selected document. The agent works with reduced candidate records internally, but the selected documents are rehydrated at the end of the loop from the retrieval hop that returned them.
+One-pass retrieval returns text-enriched chunk hits. Agentic retrieval ranks documents. Each selected document is rehydrated from the retrieval hop that returned it. CLI and service output then use different JSON shapes.
 
-Every agentic hit carries the one-pass hit fields (`text`, `metadata`, `source`, `source_id`, `path`, `page_number`, `pdf_basename`, `pdf_page`, scores, and related) plus these agentic annotations:
+CLI `retriever query` without `--agentic` projects each hit to five fields: `modality`, `page_number`, `score`, `source`, and `text`. CLI `retriever query --agentic` does not use that projection. It prints the internal hit dictionary plus these ranking annotations:
 
 - `doc_id` — the document identifier the agent selected.
 - `rank` — the position in the final ranking.
 - `result_source` — `final_results`, `rrf`, or `selection_agent`, depending on which stage produced the ranked ID.
 
-CLI `retriever query --agentic` prints those hits as JSON objects.
+`modality` and `score` exist only on the dense CLI path. Agentic CLI objects can include internal fields such as `content_type`, `_distance`, `metadata`, `path`, `pdf_basename`, `pdf_page`, and `source_id` when the retrieval hop returned them.
 
-Service `POST /v1/query` with `agentic=true` uses the same hits envelope as classic retrieval. Successful responses set `query_mode` to `"agentic"`. Classic dense or hybrid `/v1/query` (including `format=evidence`) sets `query_mode` to `"classic"`. For backward compatibility with the previous agentic service contract, service and MCP hits also copy `rank` and `result_source` under `metadata`; the top-level fields are authoritative and carry the same values.
+When the agent names a document that no retrieval hop returned, the CLI object contains only `doc_id`, `rank`, and `result_source`. Classic hit keys are absent, not present with null values.
 
-An agent can name a document that no retrieval hop returned, which leaves nothing to rehydrate. Those hits report null one-pass fields, and `source` falls back to `doc_id`.
+Service `POST /v1/query` with `agentic=true` maps those ranked hits onto the classic hits envelope. Successful responses set `query_mode` to `"agentic"`. Classic dense or hybrid `/v1/query` (including `format=evidence`) sets `query_mode` to `"classic"`. For backward compatibility with the previous agentic service contract, service and MCP hits also copy `rank` and `result_source` under `metadata`; the top-level fields are authoritative and carry the same values.
+
+When no retrieval hop captured the document, the service envelope fills these classic fields with null: `text`, `source_id`, `path`, `page_number`, `pdf_basename`, and `pdf_page`. `source` falls back to `doc_id`. That null-key behavior applies to service and MCP hits only, not to CLI `--agentic` output.
 
 ## Failure and retry behavior { #failure-and-retry-behavior }
 
@@ -257,7 +259,7 @@ Agentic runs use a dedicated worker pool in the VectorDB process so they cannot
 - Local CLI and harness runs need a CUDA GPU host and the `[local]` extra. `super-49b` needs two visible GPUs and `--agentic-local-tensor-parallel-size 2`.
 - Retriever Service agentic queries require a remote chat-completions URL, a remote embedding endpoint, and matching credentials in the process environment.
 - The default Helm `answer_llm` Super-49B NIM is limited to `POST /v1/answer` until you add the tool-call passthrough arguments. Enabling `nimOperator.answer_llm` does not configure `serviceConfig.agentic`.
-- Agentic results are document IDs, not chunk text. Downstream answer generation must load source documents by those IDs if it needs passage text.
+- Agentic ranking is document-level. Rehydrated hits include chunk `text` when a retrieval hop returned the document. Otherwise load the source document by `doc_id`.
 - Service agentic queries accept a single query string, `format=hits` only, and cannot combine `rerank=true` on the same `/v1/query` request. On the CLI, `--rerank` applies to each agent retrieve hop.
 
 ## Related Topics { #related-topics }

nemo_retriever/README.md

@@ -411,8 +411,11 @@ endpoint. Refer to
 [Agentic retrieval (self-hosted Super-49B)](helm/README.md#agentic-retrieval-llm)
 in the Helm chart README.
 
-Unlike dense retrieval, agentic mode returns ranked document IDs as JSON, not
-text-enriched hits.
+Agentic CLI output is not the five-field dense projection (`modality`,
+`page_number`, `score`, `source`, and `text`). Each JSON object is the
+internal hit dictionary plus `doc_id`, `rank`, and `result_source`.
+`result_source` is `final_results`, `rrf`, or `selection_agent`. When no
+retrieval hop returned the document, only those three keys are present.
 
 For a quick smoke test, reduce agent work:
 

nemo_retriever/docs/cli/README.md

@@ -199,8 +199,10 @@ output are not used for content-type matching.
 
 `--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.
+ranking. It searches the same LanceDB table built by `retriever ingest`. You can
+reuse the same table, embedding flags, and `--top-k` as standard retrieval.
+The JSON hit shape is not a drop-in replacement for dense `retriever query`
+output.
 
 By default, agentic retrieval runs the agent LLM in process with local vLLM and
 `nemotron-8b` (`nvidia/Llama-3.1-Nemotron-Nano-8B-v1`). This requires a CUDA GPU
@@ -221,15 +223,27 @@ retriever query "summarize the deployment options" \
   --agentic-react-max-steps 5
 ```
 
-Agentic mode returns the agent's ranked documents as JSON, with the same hit
-fields as the dense path (`text`, `metadata`, `source`, `page_number`, and
-related) plus `doc_id`, `rank`, and the stage that produced the ranking
-(`final_results`, `rrf`, or `selection_agent`). Hit fields are rehydrated at the
-end of the loop from the retrieval hop that returned the document, so a document
-the agent named without retrieving it reports null hit fields. It reuses the same
-`--top-k`, `--lancedb-uri`, `--table-name`, `--embed-invoke-url`, and
-`--embed-model-name` options as standard retrieval. Agentic retrieval uses the
-selected table's model automatically when `--embed-model-name` is omitted.
+Agentic mode returns the agent's ranked documents as JSON. The dense path
+projects each hit to five fields: `modality`, `page_number`, `score`,
+`source`, and `text`. Agentic mode does not use that projection. It prints
+the internal hit dictionary plus `doc_id`, `rank`, and `result_source`.
+`result_source` is `final_results`, `rrf`, or `selection_agent`, depending
+on which stage produced the ranking.
+`modality` and `score` exist only on the dense path. Fields such as
+`content_type`, `_distance`, `metadata`, `path`, `pdf_basename`,
+`pdf_page`, and `source_id` appear on the agentic path when the retrieval
+hop returned them.
+
+Hit fields are rehydrated at the end of the loop from the retrieval hop
+that returned the document. When the agent names a document that no
+retrieval hop returned, the object contains only `doc_id`, `rank`, and
+`result_source`. Classic hit keys such as `text` and `source` are
+absent. They are not present with null values.
+
+Agentic retrieval reuses the same `--top-k`, `--lancedb-uri`, `--table-name`,
+`--embed-invoke-url`, and `--embed-model-name` options as standard retrieval.
+Agentic retrieval uses the selected table's model automatically when
+`--embed-model-name` is omitted.
 
 **How it works.** Each agentic query runs `Query -> ReActAgentOperator -> (RRF
 fusion) -> SelectionAgentOperator -> ranked results`:
@@ -240,7 +254,8 @@ fusion) -> SelectionAgentOperator -> ranked results`:
 - `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, which are then rehydrated into full hits.
+  emits ranked document IDs. Those IDs are then rehydrated from the retrieval-hop
+  hit dictionary.
 
 Agentic-only knobs (apply only with `--agentic`):