PaperQA2: agentic RAG over a local corpus of scientific PDFs
High accuracy RAG for answering questions from scientific documents with citations
At a glance
- What is it?
- Future-House/paper-qa is an Apache-2.0 Python package that builds a full-text index over a folder of papers and answers questions with in-text citations. It is a research-grade tool with an opinionated pipeline, and its cost profile is the thing to check before adopting it.
- Who is it for?
- Adopt PaperQA2 if you need grounded, cited answers over a folder of PDFs and you are willing to pay for LLM calls on every question, since the default configuration routes retrieval, re-ranking and summarization through OpenAI models and embeddings. Do not adopt it if you want a framework to assemble a custom pipeline, or if you need a fully offline stack with no external metadata providers.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem PaperQA2 targets: cited answers over a paper folder
General-purpose RAG frameworks give you parts. You assemble a loader, a splitter, an embedding model, a vector store and a prompt. PaperQA2 ships the assembled thing, aimed at one corpus type: scientific literature. The README describes it as a package for high-accuracy retrieval augmented generation on PDFs, text files, Microsoft Office documents and source code, with a focus on scientific papers. The audience is narrow on purpose. If your documents are support tickets or product manuals, most of what PaperQA2 does is overhead. If they are journal articles with DOIs, the metadata layer is the reason to use it.
The output format is the other differentiator. The example in the README answers a question about neural networks computing with DNA and attaches citations of the form (Qian2011Neural pages 1-2). Those are not bibliography entries appended at the end. They point at specific page ranges inside specific documents, which means the retrieval stage has to track provenance through parsing, chunking and summarization. That constraint shapes the whole architecture.
How the pipeline works: metadata, full-text index, agentic retrieval
The Quickstart describes the flow in one sentence: get metadata including citation counts with a retraction check, parse and cache PDFs into a full-text search index, then answer with an LLM agent. Three stages, each with its own failure surface.
Metadata comes from external providers. The README lists Semantic Scholar, Crossref and Unpaywall among the dependencies, and describes automatic redundant fetching of paper metadata including citation and journal quality data from multiple providers. Redundant is the operative word: more than one provider is queried, which is what makes the retraction check and citation counts possible. It also means the pipeline touches the network before it touches your question.
Retrieval is not a single vector search. The README names LLM-based re-ranking and contextual summarization, abbreviated RCS, alongside document metadata-awareness in embeddings. So the embedding of a chunk carries information about the document it came from, and the candidate set returned by search is re-ordered by a model before being summarized. That is more model calls per question than a plain similarity search.
The agentic layer sits on top. The README describes agentic RAG as a language agent iteratively refining queries and answers, and the library section separates agentic adding and querying from manual, no-agent adding and querying. The agent decides when to search again. That is where the accuracy claims come from, and it is also where the variance comes from.
Getting it running: pip, pqa ask, and the settings that matter
Installation is a single command, and the Quickstart shows the full loop. After pip install paper-qa, you create a directory, drop a PDF into it, change into that directory and run pqa ask 'What is PaperQA2?'. The example fetches a paper from arxiv.org with curl first. Running the command from inside the paper directory is what makes the local files the corpus; there is no explicit path argument in the example.
The README also documents bundled settings, which are named configurations you select rather than building from individual keys, and a rate limits section, which matters because the default configuration makes multiple provider calls per question. On the library side, the README covers choosing a model, specifying an embedding model, adjusting the number of sources, using code or HTML, multimodal support, and using an external DB or vector DB with caching. There is a Settings Cheatsheet section and a Customizing Prompts section with pre and post prompts, so the prompt surface is exposed rather than hardcoded.
Indexing has its own path. The README documents creating an index and manifest files, then reusing that index, which is the difference between a one-off question and a repeatable workflow over the same corpus. Caching embeddings is documented under callbacks. For local models, the README points at locally hosted models and at Sentence Transformers for local embeddings, which is the route to avoid sending text to a hosted embedding API. The default remains OpenAI embeddings and models with a Numpy vector DB.
The cost and latency profile is the real constraint
Every stage in this pipeline is a model call or a network call, and the README's own feature list confirms it: metadata fetching from multiple providers, LLM-based re-ranking, contextual summarization, and an agent that can iterate. A single question is not one embedding lookup plus one completion. It is a search, a re-rank, a summarization pass, and possibly several agent turns, each of which may re-enter the loop.
The README does not publish a per-question token or dollar figure, and I have not measured one. What the documentation does give you is the control surface: bundled settings, a rate limits section, the ability to adjust the number of sources, and the option to swap the model and embedding provider. Those are the levers. If you point the default configuration at a large corpus and a busy user base, the bill scales with questions asked, not with documents indexed. That is the opposite of a traditional search engine, where indexing is the expensive part and queries are cheap.
The retraction check and citation counts add a second dependency: the pipeline assumes it can reach Semantic Scholar, Crossref and Unpaywall. In an air-gapped environment those calls fail or must be disabled, and the metadata-awareness in embeddings is one of the features the README lists as core. Running fully local is possible for models and embeddings, but the metadata providers are external services by design.
What PaperQA2 is not: a framework, and not a drop-in for every corpus
The README answers the framework question directly. Asked how it differs from LlamaIndex or LangChain, the project positions itself as the assembled application rather than the components. That is a real trade-off. If your retrieval logic is unusual, you will be working around a pipeline that has already decided the order of operations: metadata, then index, then re-rank, then summarize, then optionally iterate. The customization surface is prompts and settings, not the control flow.
Corpus fit is the second boundary. The metadata layer assumes documents that have DOIs and appear in citation databases. A folder of internal reports, scanned documents or preprints that no provider knows about will still parse, but the citation counts, journal quality signals and retraction checks have nothing to attach to. The README does list support for text files, Office documents, source code and HTML, so the parser is broader than the metadata layer. The mismatch is worth naming: broad parsing, narrow enrichment.
There is also a reproducibility caveat the README raises itself, in the FAQ entry about getting different results than the published papers. An agentic pipeline with model-based re-ranking is not deterministic across model versions or provider updates. The repository pins releases through CalVer, which the README explains was adopted in December 2025, but the models behind LiteLLM are not pinned by the package.
Alternatives and where the approach diverges
The obvious comparison is a general-purpose framework such as LlamaIndex or LangChain. The difference is not quality, it is where the decisions live. With a framework you choose the retriever, the re-ranker, the prompt chain and the citation mechanism, and you own the result. With PaperQA2 those choices are made for you and the citation format is built into the output. If you need a citation style or a retrieval strategy the project does not implement, the framework route is shorter than fighting the pipeline.
A second alternative is a plain vector store plus a chat interface. That gets you semantic search over chunks with no metadata enrichment, no re-ranking and no agent loop. It is cheaper per question by a wide margin and it will answer simple lookup questions about as well. It will not produce page-level citations that survive a re-ranking step, and it will not tell you that a cited paper has been retracted. The gap between the two approaches is exactly the set of features the README lists: metadata-awareness in embeddings, re-ranking, contextual summarization, and the agent loop.
A third option, for teams already standardized on a hosted document assistant, is to stay there. PaperQA2's argument is local corpus control plus provider-agnostic models through LiteLLM. If you do not need either, the switching cost has no payoff.
Maintenance, licensing and what to check before you commit
The package is Apache-2.0, which permits commercial use and modification, and the README carries the standard Apache 2.0 badge. That covers the code. It does not cover the models, embeddings or metadata providers you point it at, each of which has its own terms. The default configuration uses OpenAI models and embeddings, so a deployment inherits those terms on top of the licence. I am not giving legal advice here; the point is that the Apache-2.0 grant is one layer of several.
Release cadence is visible from the tags. The project moved to CalVer in December 2025, and the supplied releases run from v2026.03.12 through v2026.08.12, roughly monthly. CalVer with dated tags makes it easy to see how far behind you are, and the README notes the project previously followed SemVer with major bumps on breaking changes. Neither scheme removes the need to read release notes before upgrading, particularly for a package whose behaviour depends on prompts and model versions.
The upgrade cost is concentrated in two places: the settings surface and the prompts. The README exposes a Settings Cheatsheet, bundled settings, pre and post prompts, and callbacks for embedding caches. If you customize prompts, an upgrade that changes the default prompt structure can shift your answers without any API change on your side. Before adopting, run pqa ask on a small directory of your own PDFs and read the citations it produces, then check whether the papers you care about resolve through the metadata providers. If they do not, you are paying for the agentic pipeline without getting the enrichment that justifies it.
Editorial conclusion
Adopt PaperQA2 if you need grounded, cited answers over a folder of PDFs and you are willing to pay for LLM calls on every question, since the default configuration routes retrieval, re-ranking and summarization through OpenAI models and embeddings. Do not adopt it if you want a framework to assemble a custom pipeline, or if you need a fully offline stack with no external metadata providers. Before committing, verify what a single pqa ask costs against your own corpus by running it on one directory with a small paper count, and check whether your documents parse cleanly, since the pipeline depends on PDF text extraction before any of the retrieval stages run.
Community notes