Item reader

The item reader reads the books for one angle, compares them, and cites every claim. You do not start readers yourself. The librarian starts them on its own. To start the librarian, ask your agent explicitly: "Search my Trove library for how we handle retries." We are actively working on making this start automatically and reliably, but today you should not rely on it.

What it does#

The reader opens the books and pages it was given. It synthesizes across the books: it notes where they agree and where they disagree. It cites both when two books cover the same point.

When it starts#

The librarian starts one reader for each angle on its list. All readers run at the same time. A reader ignores books that belong to other angles.

After an Auto mode notebook hit, one reader can start directly. See Plan mode and Auto mode.

How it reads#

1. The reader opens a research session. The session records what you asked.
2. It runs trove items list --json to check that its book ids exist.
3. It runs trove items toc <ids>. It skips this step when the list already gives page ranges, because each TOC call uses read quota.
4. It runs trove items read on the target pages.
5. It writes the answer with citations.
6. It closes the session.

How it cites#

The reader uses two formats. A direct quote:

"Direct quote from the document" — Document Title, Page X

A paraphrase:

The document explains that [paraphrased content] (Document Title, pp. 10-12).

See Citations.

What its report contains#

The report has these sections:

• Sources consulted
• Core findings
• Additional insights
• Professional-restricted notice, only when a restricted book helped the answer
• Citation summary

The last line is COVERAGE:. It takes one of four values:

• hit: the assigned books answered the question.
• partial: a book was on topic, but a sub-topic was missing.
• none: the pages held nothing relevant.
• not-in-library: an assigned book is not in your library, so nothing was read.

Reporting a missing topic#

The reader reports a missing sub-topic to the book's author. It reports only when all four conditions are true:

1. The book's scope claims to cover the sub-topic, or an adjacent one.
2. The reader read the most likely chapters in full.
3. No relevant passage remained after that reading.
4. Your need was specific enough to check against the text.

It reports at most once per read. The topic is abstracted, because the author reads it, and the author can be a third-party seller. See Knowledge gaps.

Broken and partly imported books#

Flagging a book only queues it for metadata enrichment. It does not re-import the book.

For a partial book, the reader offers to reprocess it. To accept, ask your agent: "Reprocess this book." It never offers a reprocess for an unreadable book. The fix for those is to upload a copy that has a text layer.

What it never does#

• It never subscribes to a book.
• It never reads books outside its angle.
• It never changes a book.
• It never lets a failed report change your answer.

Errors and fixes#

Model and tools#

The item reader runs on Sonnet. It uses Bash, Read and Write.

Best practice#

When two books disagree, or a book is stale, the reader reports both with citations. Your agent says which is newer or more specific, recommends one and asks you. See Answers you can trust and Research a topic.

Direct CLI#

Your agent runs these through the trove command. You can run them yourself in a terminal, but asking your agent is the recommended way: it picks the right flags, waits for processing and checks the result.

The reader uses three forms to read pages:

trove items read "<id>:140-162"
trove items read "<id1>:1-5,<id2>:all"
trove items read <id> --pages 1,3,5

Inline, each id takes one range or all. Comma lists work only with --pages.

• Reprocess a partly imported book: trove items reprocess <id>
• Queue a book for metadata enrichment: trove items flag <id>

See the CLI reference.

Related#

• Librarian
• Citations
• Plans and limits