add agentic for query service subcommand - #2572
Conversation
Greptile SummaryThe PR adds an
|
| Filename | Overview |
|---|---|
| nemo_retriever/src/nemo_retriever/cli/query/app.py | Adds --agentic forwarding, but evidence output still labels agentic results as semantic retrieval. |
| nemo_retriever/src/nemo_retriever/query/options.py | Adds the agentic request field, but the user-facing setting remains in an unvalidated dataclass. |
| nemo_retriever/src/nemo_retriever/query/service.py | Forwards agentic mode while reusing candidate_k as endpoint top_k, which can trigger the service's agentic backend-depth validation. |
| nemo_retriever/src/nemo_retriever/service/client.py | Adds agentic payload support but permits unsupported list-query combinations and leaves the new public parameter undocumented. |
| nemo_retriever/tests/test_service_query_client.py | Covers agentic payload forwarding but does not exercise the unsupported list-query combination. |
| nemo_retriever/tests/test_root_query_cli.py | Covers CLI flag forwarding but not candidate_k limits or evidence provenance in agentic mode. |
| nemo_retriever/tests/test_query_workflow_options.py | Updates service orchestration expectations for agentic forwarding without covering its interaction with candidate_k. |
| docs/docs/extraction/workflow-agentic-retrieval.md | Documents the service-query agentic CLI workflow and clarifies that model configuration belongs to the service. |
| nemo_retriever/docs/cli/README.md | Adds an accurate quick-start example for invoking service-owned agentic retrieval. |
Flowchart
%%{init: {'theme': 'neutral'}}%%
flowchart LR
CLI[retriever query service --agentic] --> Request[ServiceQueryRequest]
Request --> Orchestration[query.service.query_documents]
Orchestration --> Client[RetrieverServiceClient query/aquery]
Client --> API[POST /v1/query agentic=true]
API --> Agentic[Service-owned agentic workflow]
Agentic --> Hits[Query hits]
Hits --> Shape[Local result shaping]
Shape --> Output[CLI JSON or evidence output]
Prompt To Fix All With AI
### Issue 1
nemo_retriever/src/nemo_retriever/service/client.py:584-591
**Reject batched agentic queries**
When `query()` or `aquery()` receives a list of query strings with `agentic=True`, the client serializes both values even though the service requires a single string for agentic mode, causing the request to fail service validation instead of returning results.
### Issue 2
nemo_retriever/src/nemo_retriever/query/service.py:30
**Candidate pool exceeds agentic depth**
When an agentic service query has a valid final `top_k` but a `candidate_k` above the configured `agentic.backend_top_k`, this call sends `candidate_k` as the endpoint's `top_k`, causing the service to reject the request with HTTP 422.
### Issue 3
nemo_retriever/src/nemo_retriever/cli/query/app.py:340
**Agentic evidence mislabeled semantic**
When `--agentic` is combined with `--format evidence`, the command runs the service's agentic workflow but still passes `strategies=["semantic"]` to output shaping, causing `coverage.strategies_used` to report incorrect provenance.
### Issue 4
nemo_retriever/src/nemo_retriever/service/client.py:556-563
**Document the agentic parameter**
The public `query()` and `aquery()` methods add `agentic` without documenting its behavior or single-query restriction, leaving library users unable to discover this changed request contract from the API documentation.
### Issue 5
nemo_retriever/src/nemo_retriever/query/options.py:95
**Validate the agentic request setting**
The new user-facing `agentic` setting is added to an unvalidated dataclass without descriptive field metadata, so unsupported option combinations are not rejected at request construction and instead fail later at the remote service boundary.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.Reviews (1): Last reviewed commit: "add agentic for query service subcommand" | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| agentic: bool = False, | ||
| ) -> list[list[dict[str, Any]]] | list[QueryHit]: | ||
| """Asynchronously search through ``POST /v1/query``.""" | ||
|
|
||
| payload: dict[str, Any] = {"query": query, "top_k": int(top_k)} | ||
| if collection_name: | ||
| payload["collection_name"] = collection_name | ||
| if agentic: |
There was a problem hiding this comment.
When query() or aquery() receives a list of query strings with agentic=True, the client serializes both values even though the service requires a single string for agentic mode, causing the request to fail service validation instead of returning results.
Prompt To Fix With AI
This is a comment left during a code review.
Path: nemo_retriever/src/nemo_retriever/service/client.py
Line: 584-591
Comment:
**Reject batched agentic queries**
When `query()` or `aquery()` receives a list of query strings with `agentic=True`, the client serializes both values even though the service requires a single string for agentic mode, causing the request to fail service validation instead of returning results.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.| api_token=request.service.service_api_token, | ||
| ) | ||
| raw_result_sets = client.query(request.query, top_k=retrieval_top_k) | ||
| raw_result_sets = client.query(request.query, top_k=retrieval_top_k, agentic=request.agentic) |
There was a problem hiding this comment.
When an agentic service query has a valid final top_k but a candidate_k above the configured agentic.backend_top_k, this call sends candidate_k as the endpoint's top_k, causing the service to reject the request with HTTP 422.
Knowledge Base Used:
Prompt To Fix With AI
This is a comment left during a code review.
Path: nemo_retriever/src/nemo_retriever/query/service.py
Line: 30
Comment:
**Candidate pool exceeds agentic depth**
When an agentic service query has a valid final `top_k` but a `candidate_k` above the configured `agentic.backend_top_k`, this call sends `candidate_k` as the endpoint's `top_k`, causing the service to reject the request with HTTP 422.
**Knowledge Base Used:**
- [Query workflow orchestration](https://app.greptile.com/nvidia-public-github/-/custom-context/knowledge-base/nvidia/nemo-retriever/-/docs/query-workflow-orchestration.md)
- [Retriever service](https://app.greptile.com/nvidia-public-github/-/custom-context/knowledge-base/nvidia/nemo-retriever/-/docs/retriever-service.md)
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.| content_types: opts.ContentTypesOption = None, | ||
| output_format: opts.OutputFormatOption = "hits", | ||
| max_text_chars: opts.MaxTextCharsOption = None, | ||
| agentic: opts.AgenticOption = False, |
There was a problem hiding this comment.
When --agentic is combined with --format evidence, the command runs the service's agentic workflow but still passes strategies=["semantic"] to output shaping, causing coverage.strategies_used to report incorrect provenance.
Prompt To Fix With AI
This is a comment left during a code review.
Path: nemo_retriever/src/nemo_retriever/cli/query/app.py
Line: 340
Comment:
**Agentic evidence mislabeled semantic**
When `--agentic` is combined with `--format evidence`, the command runs the service's agentic workflow but still passes `strategies=["semantic"]` to output shaping, causing `coverage.strategies_used` to report incorrect provenance.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.| agentic: bool = False, | ||
| ) -> list[list[dict[str, Any]]] | list[QueryHit]: | ||
| """Search ingested documents through ``POST /v1/query``. | ||
|
|
||
| Note: | ||
| ``top_k`` is required here but defaults to 10 on :meth:`aquery`. | ||
| That asymmetry is part of the released signature; do not unify it. | ||
| """ |
There was a problem hiding this comment.
The public query() and aquery() methods add agentic without documenting its behavior or single-query restriction, leaving library users unable to discover this changed request contract from the API documentation.
Rule Used: Every public class and function in nemo_retriever ... (source)
Prompt To Fix With AI
This is a comment left during a code review.
Path: nemo_retriever/src/nemo_retriever/service/client.py
Line: 556-563
Comment:
**Document the agentic parameter**
The public `query()` and `aquery()` methods add `agentic` without documenting its behavior or single-query restriction, leaving library users unable to discover this changed request contract from the API documentation.
**Rule Used:** Every public class and function in nemo_retriever ... ([source](https://github.com/nvidia/nemo-retriever/blob/f41b14e714a1883d2d8640ff2c23991b7ed9ca6d/nemo_retriever/.greptile/config.json))
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
| query: str | ||
| retrieval: QueryRetrievalOptions = field(default_factory=QueryRetrievalOptions) | ||
| service: QueryServiceOptions = field(default_factory=QueryServiceOptions) | ||
| agentic: bool = False |
There was a problem hiding this comment.
The new user-facing agentic setting is added to an unvalidated dataclass without descriptive field metadata, so unsupported option combinations are not rejected at request construction and instead fail later at the remote service boundary.
Rule Used: User-facing configuration must use Pydantic models... (source)
Prompt To Fix With AI
This is a comment left during a code review.
Path: nemo_retriever/src/nemo_retriever/query/options.py
Line: 95
Comment:
**Validate the agentic request setting**
The new user-facing `agentic` setting is added to an unvalidated dataclass without descriptive field metadata, so unsupported option combinations are not rejected at request construction and instead fail later at the remote service boundary.
**Rule Used:** User-facing configuration must use Pydantic models... ([source](https://github.com/nvidia/nemo-retriever/blob/f41b14e714a1883d2d8640ff2c23991b7ed9ca6d/nemo_retriever/.greptile/config.json))
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.1 participant
Description
Implemented retriever query service QUERY --agentic.
It now forwards agentic: true to the service’s /v1/query endpoint while using the service-owned LLM and embedding configuration—no local --agentic-* options are
added.
Updated CLI/service wiring and tests in nemo_retriever/src/nemo_retriever/cli/query/app.py, nemo_retriever/src/nemo_retriever/query/service.py, and nemo_retriever/
src/nemo_retriever/service/client.py. Documentation now includes the service CLI example.
Validation passed: 67 focused tests. git diff --check passed. Strict MkDocs build could not run because mkdocs is not installed.
Checklist