pi-literature-review

Local, open, login-free academic literature review for the Pi coding agent.

One package, three tools:

• /lit-search — search the literature
• /lit-selection — download selected papers
• /lit-synthesis — read, discuss and synthesize papers

It uses the public APIs of arXiv, CrossRef and OpenAlex, plus Semantic Scholar when you add a free API key. No account, API key or paid service is required. The workflow can run locally with a small LLM and embedding model. See Requirements.

The central design rule: models never modify or generate paper data.

Metadata, abstracts, PDF text, filtering, verification and citations are handled by APIs and deterministic code. The embedding model only retrieves relevant passages. The LLM suggests search variants and writes answers, summaries and syntheses from those passages.

How it works

The workflow has three stages:

Stage	Command	What it does	Creates
Literature search	/lit-search	Searches arXiv, CrossRef, OpenAlex (and Semantic Scholar with an API key); filters, deduplicates, verifies, enriches and labels the records	One HTML page + JSON file per run in lit-search/
Literature selection	/lit-selection	Downloads the papers you ticked on the results page (legal open access only)	A PDF library in lit-selection/
Literature synthesis	/lit-synthesis	Chats about one paper or builds a report across one or several papers (PDFs), with page-exact citations	HTML reports and chat protocols in lit-synthesis/

Each command opens its wizard-dialog directly in Pi. Dialogs can be cancelled with Esc before anything is sent.

You can also just describe the task in chat and let the agent invoke the same tools:

I want to conduct a literature review on the use of satellite remote sensing for estimating water levels in rivers.

Which cameras do Blanch et al. (2026) use in their paper
"Image-based method for real-time water level monitoring"?

The stages connect through the HTML-page, generated by lit-search: there you select papers, copy the download request, and pass it to /lit-selection in Pi. Once downloaded, you can chat about, summarize or synthesize the papers (PDFs) by using /lit-synthesis.

Features

Search Assistance

The /lit-search-wizard starts from user defined keyword blocks or free text. The model can suggest query variants that you can edit or select.

It can also help identify relevant journals and authors, and lets you filter the results. Each result shows which query found it and which terms matched.

HTML literature-search report

Each search run produces a sortable HTML results page and a JSON file.

Results include bibliographic metadata, verified DOI, BibTeX, citation and open-access metrics, and an on-target / adjacent label.

The page also contains the exact database queries, raw hit counts and a PRISMA-2020-style flow diagram.

Citation graphs

Each result can open a citation graph showing references, citing works and related literature.

The graph is fetched from OpenAlex when opened; only the DOI or title leaves your machine.

Papers with code

Optionally search for papers with code using Hugging Face Papers, GitHub READMEs, curated awesome-lists and Google Earth Engine repositories.

Known repositories and data archives are shown directly in the results: links named in the abstract and archives the publisher deposited at CrossRef appear in every search, no tick needed.

Legal open-access downloads

Select papers directly from the results page and copy a download request.

/lit-selection resolves legal open-access routes through the publisher, Unpaywall and arXiv. Papers that cannot be downloaded are reported with the reason and a browser link.

Page-exact citations

Synthesis answers and reports cite the page containing the supporting passage.

Clicking a citation opens the PDF at the relevant page and highlights the cited text.

Synthesis across a paper library

/lit-synthesis can work with one paper, several papers or an entire PDF library.

It can provide per-paper summaries, answer questions about individual or multiple papers, and optionally produce a cross-paper review synthesis.

Install

From npm:

pi install npm:pi-literature-review

Or directly from the repository:

pi install git:github.com/flindenberger/pi-literature-review

Search and selection work without a model selected in Pi.

Synthesis additionally needs an embedding model. On first use, /lit-synthesis can offer to fetch a local Ollama model (~1.2 GB). llama.cpp and remote backends can also be configured; see Configuration.

For tested hardware and model combinations, see Requirements.

Privacy

The package uses public, login-free endpoints. Search text and paper identifiers are sent to the relevant services.

Used services include:

• arXiv, CrossRef, OpenAlex (and Semantic Scholar, only with an API key) for search and verification
• Hugging Face Papers, GitHub and ecosyste.ms when code search is enabled
• Unpaywall and the relevant publisher or repository for downloads
• OpenAlex for citation graphs

There is no account requirement, scraping or telemetry.

An optional contact email (required by Unpaywall) is sent with every API request once it is set. Paper text is processed locally by the embedding server and by the model selected in Pi. With local models, the paper text stays on your machine. With a cloud model or remote backend, excerpts are sent to that provider.

Check the papers' licenses and your institution's rules before using a remote model. See Configuration.

Documentation

Document	Purpose
Requirements	Hardware, models and prerequisites
Search	Search wizard, pipeline and results
Selection	PDF downloads and resolution
Synthesis	Indexing, chat and reports
Configuration	Optional backends, models and keys
Command line	Use without the Pi agent
Development and tests	Development, testing and releases

Limits

• Search runs on titles, abstracts and metadata; OpenAlex also matches full text where it has it. The on_target label only looks at title and abstract.
• Scopus, Web of Science and Sci-Hub are not used.
• Short result lists are not padded: if a query finds two papers, it returns two.
• Source metadata is passed through as delivered, including broken characters.
• Windows and macOS paths are implemented but currently untested.

Status

Version 0.1.1.

Developed and field-tested on Linux. See Requirements.

Contributing

This package grew out of the collaborative research project Satellite Remote Sensing and Field Data Fusion for Hydraulic Engineering, involving BAW, UPC and TU Dresden.

This extension was developed with substantial help from the Claude Code coding agent. It was used for code and test generation, refactoring, debugging against live APIs, comparing implementation approaches, discussing design decisions and writing documentation. The maintainer made the design decisions and critically tested generated changes. Generated documentation was proofread and corrected where necessary.

How to ask questions, report bugs, propose changes or fork the project: see CONTRIBUTING.md. Security problems: see SECURITY.md.

License and attribution

MIT — see LICENSE. If this package supports your academic work, please cite it using CITATION.cff or the Zenodo DOI 10.5281/zenodo.22954995. GitHub also provides APA and BibTeX entries under Cite this repository.

The package started from the wish to use OpenScholar (Asai et al., 2024, arXiv:2411.14199) on local PDFs.

The multi-source search design was inspired by paper-search-mcp, released under MIT by OPENAGS.