How future-house/paper-qa works
Project Type and Core Workflow
• PaperQA2 is a Python package + CLI for agentic retrieval-augmented generation (RAG) over scientific papers.
• Core workflow phases (per README):
1) Paper Search
2) Gather Evidence
3) Generate Answer
Main Components
A. CLI / Library Entrypoint (“pqa ask” or ask() / agent_query())
B. Agent Controller (ToolSelector agent)
C. Tools
1. SearchPapers (index + embedding store)
2. Embed & Rank Chunks
3. Contextual Summarizer (re-ranking + summarization)
4. Answer Generator
D. LLM & Embedding Backends (LiteLLM drivers, OpenAI, local LLM, etc.)
E. Vector Store (NumPy or external vector DB)
F. Metadata Clients (Crossref, Semantic Scholar, Unpaywall, etc.)
G. Local Index (persistent on-disk indexes under ~/.pqa/)
Flow of Control & LLM Calls with Prompt Names
• LLM invocation node with the exact prompt template name used.
1) User → CLI/Library
• Input: natural-language question
• No LLM call yet
2) CLI/Library → Agent Controller
• LLM : agent_llm
• Prompt :
– System prompt: env_system_prompt
– Agent prompt: env_reset_prompt (or agent_system_prompt + agent_prompt)
• Purpose: decide tool sequence (search → gather → answer, or custom order)
3) Agent → SearchPapers Tool
• LLM : summary_llm (or same LLM as agent if “fake” agent)
• Prompt : select_paper_prompt
• Purpose: convert question into keyword query, select candidate papers
4) SearchPapers → Metadata Clients
• No LLM – external HTTP calls to Crossref, Semantic Scholar, etc.
• Retrieve paper metadata, journal quality
5) SearchPapers → PDF/Text Parser → Chunker → Vector Store
• No LLM – chunk text, embed chunks using embedding model
• Store embeddings in NumPyVectorStore (or external)
6) Agent → Gather Evidence Tool
6.1) Embed Query → Vector Store
• No prompt name – uses embedding model to vectorize question
6.2) Retrieve Top-K Chunks
• Internal logic – MMR ranking
6.3) Summarize Each Chunk
• LLM : summary_llm
• Prompt : summary_prompt
• Purpose: create a scored, contextual summary per chunk
6.4) Re-score & Select Summaries
• LLM : summary_llm
• Prompt : might reuse summary_prompt or summary_json_prompt + summary_json_system_prompt if JSON output desired
• Purpose: final selection of most relevant summaries
7) Agent → Generate Answer Tool
• LLM : llm
• Prompt : qa_prompt
• Injects:
– Context wrapper: CONTEXT_OUTER_PROMPT
– Individual context formatting: CONTEXT_INNER_PROMPT (with placeholders {name}, {text})
• Purpose: produce the final answer with in-text citations
8) CLI/Library → User
• Output: formatted_answer (text with citations), context summaries, metadata
Architectural Patterns & Design Principles
• Agent-tool pattern (separation of concern between tool invocation & LLM decision logic)
• Plugin-style metadata clients (Crossref, Unpaywall, etc.)
• Modular prompt templates (all in src/paperqa/prompts.py)
• Async first design with synchronous wrappers