docs(26.05): split Jacob CLI and README reconcile updates#2315
Closed
kheiss-uwzoo wants to merge 1 commit into
Closed
docs(26.05): split Jacob CLI and README reconcile updates#2315kheiss-uwzoo wants to merge 1 commit into
kheiss-uwzoo wants to merge 1 commit into
Conversation
Port Jacob-owned package README, CLI, benchmarking, troubleshoot, and release note reconcile changes from PR 2311 onto 26.05. Includes Greptile fixes for README import paths.
Contributor
Greptile SummaryThis PR reconciles NeMo Retriever 26.05 documentation around CLI usage and README examples. The main changes are:
|
| Filename | Overview |
|---|---|
| docs/docs/extraction/releasenotes.md | Release-note text was narrowed around public CLI guidance and packaging notes. |
| docs/docs/extraction/troubleshoot.md | Troubleshooting text now recommends batching, sinks, service return_results=False, and updated related links. |
| nemo_retriever/README.md | README setup and workflow examples were updated, with broken markdown-import and image-storage command examples noted. |
| nemo_retriever/docs/cli/README.md | The CLI README was rewritten around new ingest, query, service, and agentic workflows, but several documented commands and flags do not match the current CLI. |
| nemo_retriever/docs/cli/benchmarking.md | Benchmarking docs now describe registry-style harness commands and agentic BEIR overrides, with unavailable harness commands noted. |
Prompt To Fix All With AI
Fix the following 6 code review issues. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 6
nemo_retriever/docs/cli/README.md:27-29
**Ingest Modes Become Subcommands**
The current root CLI treats `retriever ingest` as a leaf command with `--run-mode inprocess|batch`, not as a command group. When a reader runs `retriever ingest batch ...` or `retriever ingest service ...`, the parser receives the mode as an unexpected argument instead of selecting that backend, so the documented larger-corpus and service-ingest workflows fail before ingestion starts.
### Issue 2 of 6
nemo_retriever/docs/cli/README.md:10
**Service Query Command Missing**
`retriever query` is currently a leaf command, and the inspected CLI does not expose a `query service` subcommand or `--service-url` on query. A service user following this new entry runs `retriever query service ... --service-url ...` and gets a usage error instead of querying the deployment.
### Issue 3 of 6
nemo_retriever/docs/cli/README.md:140-148
**Query Filters Are Undeclared**
The documented local query example uses `--candidate-k` and `--content-types`, and this section also describes `--page-dedup`, but those flags are not on the current `retriever query` command surface. Copying this example makes Typer reject the command with an unknown option before retrieval can run.
### Issue 4 of 6
nemo_retriever/docs/cli/benchmarking.md:22-38
**Harness Registry Commands Missing**
The current harness app exposes the older orchestration commands such as `run`, `sweep`, `nightly`, `summary`, `compare`, and related helpers, but not `list`, `show`, `run-set`, or `diff`. The first commands in this new workflow therefore fail with no-such-command errors, so users cannot discover or run the documented benchmark registry flow.
### Issue 5 of 6
nemo_retriever/README.md:438
**Markdown Import Path Missing**
`to_markdown` is exported from `nemo_retriever.io`, and the package layout inspected for this branch does not include a `nemo_retriever.common` package. A reader copying this changed path as `from nemo_retriever.common.io import to_markdown` gets `ImportError: No module named 'nemo_retriever.common'` before any markdown rendering can run.
```suggestion
records to `nemo_retriever.io.to_markdown`. The helper returns one markdown string (or `None`
```
### Issue 6 of 6
nemo_retriever/README.md:649-650
**Image Store Flag Misplaced**
The current root ingest command does not expose `--store-images-uri`; that flag was found on the pipeline compatibility command. A user following this new root-ingest image-storage example gets an unknown-option error instead of persisting extracted images.
Reviews (1): Last reviewed commit: "docs(26.05): split Jacob CLI and README ..." | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Comment on lines
+27
to
+29
| retriever ingest local DOCUMENTS... | ||
| retriever ingest batch DOCUMENTS... | ||
| retriever ingest service DOCUMENTS... |
Contributor
There was a problem hiding this comment.
The current root CLI treats retriever ingest as a leaf command with --run-mode inprocess|batch, not as a command group. When a reader runs retriever ingest batch ... or retriever ingest service ..., the parser receives the mode as an unexpected argument instead of selecting that backend, so the documented larger-corpus and service-ingest workflows fail before ingestion starts.
Prompt To Fix With AI
This is a comment left during a code review.
Path: nemo_retriever/docs/cli/README.md
Line: 27-29
Comment:
**Ingest Modes Become Subcommands**
The current root CLI treats `retriever ingest` as a leaf command with `--run-mode inprocess|batch`, not as a command group. When a reader runs `retriever ingest batch ...` or `retriever ingest service ...`, the parser receives the mode as an unexpected argument instead of selecting that backend, so the documented larger-corpus and service-ingest workflows fail before ingestion starts.
How can I resolve this? If you propose a fix, please make it concise.|
|
||
| - `retriever ingest` - ingest supported documents and media into a Retriever index. | ||
| - `retriever query` - query a local LanceDB table written by local or batch ingest. | ||
| - `retriever query service` - query a Retriever service deployment. |
Contributor
There was a problem hiding this comment.
retriever query is currently a leaf command, and the inspected CLI does not expose a query service subcommand or --service-url on query. A service user following this new entry runs retriever query service ... --service-url ... and gets a usage error instead of querying the deployment.
Prompt To Fix With AI
This is a comment left during a code review.
Path: nemo_retriever/docs/cli/README.md
Line: 10
Comment:
**Service Query Command Missing**
`retriever query` is currently a leaf command, and the inspected CLI does not expose a `query service` subcommand or `--service-url` on query. A service user following this new entry runs `retriever query service ... --service-url ...` and gets a usage error instead of querying the deployment.
How can I resolve this? If you propose a fix, please make it concise.
Comment on lines
+140
to
148
| with `source`, `page_number`, and `text`. Use `--candidate-k`, `--page-dedup`, | ||
| and `--content-types` to control how results are selected after vector | ||
| retrieval: | ||
|
|
||
| ```bash | ||
| # Retrieve 30 candidates, then return the best 10. | ||
| retriever query "where is the warranty limitation discussed?" \ | ||
| --candidate-k 30 | ||
|
|
||
| # Keep only the first hit from each document page. | ||
| retriever query "which pages discuss operating costs?" \ | ||
| --top-k 5 \ | ||
| --candidate-k 30 \ | ||
| --page-dedup | ||
|
|
||
| # Search a wider pool, then keep only table rows. | ||
| retriever query "annual revenue by region" \ | ||
| --top-k 5 \ | ||
| --candidate-k 40 \ | ||
| --content-types table |
Contributor
There was a problem hiding this comment.
The documented local query example uses --candidate-k and --content-types, and this section also describes --page-dedup, but those flags are not on the current retriever query command surface. Copying this example makes Typer reject the command with an unknown option before retrieval can run.
Prompt To Fix With AI
This is a comment left during a code review.
Path: nemo_retriever/docs/cli/README.md
Line: 140-148
Comment:
**Query Filters Are Undeclared**
The documented local query example uses `--candidate-k` and `--content-types`, and this section also describes `--page-dedup`, but those flags are not on the current `retriever query` command surface. Copying this example makes Typer reject the command with an unknown option before retrieval can run.
How can I resolve this? If you propose a fix, please make it concise.
Comment on lines
+22
to
+38
| retriever harness list | ||
| retriever harness list --runsets | ||
|
|
||
| # Default active profile (jp20 + single_gpu in test_configs.yaml) | ||
| retriever harness run --dataset jp20 | ||
| # Inspect one concrete benchmark spec | ||
| retriever harness show jp20_beir | ||
|
|
||
| # Custom directory on disk | ||
| retriever harness run --dataset /path/to/your/data | ||
| # Run one benchmark and write stable artifacts | ||
| retriever harness run jp20_beir | ||
|
|
||
| # Override a single config key | ||
| retriever harness run --dataset bo767 --override run_mode=inprocess | ||
| # Run one benchmark in batch mode | ||
| retriever harness run bo767_beir --mode batch | ||
|
|
||
| # Override a resolved config key for this run | ||
| retriever harness run bo767_beir --set query.top_k=5 | ||
|
|
||
| # Expand and run a code-owned benchmark runset | ||
| retriever harness run-set jp20_core |
Contributor
There was a problem hiding this comment.
The current harness app exposes the older orchestration commands such as run, sweep, nightly, summary, compare, and related helpers, but not list, show, run-set, or diff. The first commands in this new workflow therefore fail with no-such-command errors, so users cannot discover or run the documented benchmark registry flow.
Prompt To Fix With AI
This is a comment left during a code review.
Path: nemo_retriever/docs/cli/benchmarking.md
Line: 22-38
Comment:
**Harness Registry Commands Missing**
The current harness app exposes the older orchestration commands such as `run`, `sweep`, `nightly`, `summary`, `compare`, and related helpers, but not `list`, `show`, `run-set`, or `diff`. The first commands in this new workflow therefore fail with no-such-command errors, so users cannot discover or run the documented benchmark registry flow.
How can I resolve this? If you propose a fix, please make it concise.|
|
||
| If you want a readable markdown view of extracted results, pass a single document's extraction | ||
| records to `nemo_retriever.io.to_markdown`. The helper returns one markdown string (or `None` | ||
| records to `nemo_retriever.common.io.to_markdown`. The helper returns one markdown string (or `None` |
Contributor
There was a problem hiding this comment.
to_markdown is exported from nemo_retriever.io, and the package layout inspected for this branch does not include a nemo_retriever.common package. A reader copying this changed path as from nemo_retriever.common.io import to_markdown gets ImportError: No module named 'nemo_retriever.common' before any markdown rendering can run.
Suggested change
| records to `nemo_retriever.common.io.to_markdown`. The helper returns one markdown string (or `None` | |
| records to `nemo_retriever.io.to_markdown`. The helper returns one markdown string (or `None` |
Prompt To Fix With AI
This is a comment left during a code review.
Path: nemo_retriever/README.md
Line: 438
Comment:
**Markdown Import Path Missing**
`to_markdown` is exported from `nemo_retriever.io`, and the package layout inspected for this branch does not include a `nemo_retriever.common` package. A reader copying this changed path as `from nemo_retriever.common.io import to_markdown` gets `ImportError: No module named 'nemo_retriever.common'` before any markdown rendering can run.
```suggestion
records to `nemo_retriever.io.to_markdown`. The helper returns one markdown string (or `None`
```
How can I resolve this? If you propose a fix, please make it concise.
Comment on lines
+649
to
650
| retriever ingest ./data \ | ||
| --store-images-uri ./processed_docs/images |
Contributor
There was a problem hiding this comment.
The current root ingest command does not expose --store-images-uri; that flag was found on the pipeline compatibility command. A user following this new root-ingest image-storage example gets an unknown-option error instead of persisting extracted images.
Prompt To Fix With AI
This is a comment left during a code review.
Path: nemo_retriever/README.md
Line: 649-650
Comment:
**Image Store Flag Misplaced**
The current root ingest command does not expose `--store-images-uri`; that flag was found on the pipeline compatibility command. A user following this new root-ingest image-storage example gets an unknown-option error instead of persisting extracted images.
How can I resolve this? If you propose a fix, please make it concise.
Collaborator
Author
|
Closing: documents main CLI/README surface not present in 26.05; redundant with #2313 where overlapping. Triage vs upstream/26.05 (post-#2313):
These are main-forward doc changes, not missing 26.5.0 fixes. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
nemo_retriever.ioandnemo_retriever.retrieverimport paths in README examples.Review context
This is part of the owner-based split of #2311 so previous contributors can review their own 26.05 reconcile changes.
Test plan
upstream/26.05: one commit, intended docs files only.