# future-house/paper-qa architecture

> Architecture diagram of the GitHub repository future-house/paper-qa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/future-house/paper-qa
- Repository: https://github.com/future-house/paper-qa

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input
    User["User"] 
    CLI["CLI / Library Entrypoint"]:::component
    Agent["Agent Controller"]:::component

    %% Phase: Paper Search
    User --> CLI
    CLI --> Agent
    click CLI "https://github.com/future-house/paper-qa/blob/main/src/paperqa/core.py"
    click Agent "https://github.com/future-house/paper-qa/blob/main/src/paperqa/agents/main.py"

    Agent -->|"agent_llm\n(env_system_prompt + env_reset_prompt)"| AgentLLM["agent_llm"]:::llmCall
    AgentLLM --> SearchPapers

    SearchPapers["SearchPapers Tool"]:::tool
    click SearchPapers "https://github.com/future-house/paper-qa/blob/main/src/paperqa/agents/tools.py"

    SearchPapers -->|"select_paper_prompt"| SearchLLM["summary_llm"]:::llmCall
    click SearchLLM "https://github.com/future-house/paper-qa/blob/main/src/paperqa/llms.py"
    SearchLLM --> SearchPapers

    SearchPapers --> MetadataClients
    MetadataClients["Metadata Clients"]:::datastore
    click MetadataClients "https://github.com/future-house/paper-qa/tree/main/src/paperqa/clients/"

    SearchPapers --> PDFParser["PDF/Text Parser"]:::component
    PDFParser --> Chunker["Chunker"]:::component
    click Chunker "https://github.com/future-house/paper-qa/blob/main/src/paperqa/utils.py"

    Chunker --> EmbeddingModel
    EmbeddingModel["Embedding Model"]:::component
    click EmbeddingModel "https://github.com/future-house/paper-qa/blob/main/src/paperqa/llms.py"

    EmbeddingModel --> VectorStore
    VectorStore["Vector Store"]:::datastore
    click VectorStore "https://github.com/future-house/paper-qa/blob/main/src/paperqa/paths.py"

    %% Phase: Gather Evidence
    Agent --> GatherTool["Gather Evidence Tool"]:::tool
    click GatherTool "https://github.com/future-house/paper-qa/blob/main/src/paperqa/agents/tools.py"

    GatherTool -->|"embedding"| EmbedModel["embedding model"]:::component
    click EmbedModel "https://github.com/future-house/paper-qa/blob/main/src/paperqa/llms.py"

    EmbedModel --> VectorStore
    VectorStore --> RetrievedChunks["Top-K Chunks"]:::component

    RetrievedChunks -->|"summary_prompt"| SummaryLLM1["summary_llm"]:::llmCall
    click SummaryLLM1 "https://github.com/future-house/paper-qa/blob/main/src/paperqa/llms.py"
    SummaryLLM1 --> Summaries["Chunk Summaries"]:::component

    Summaries -->|"summary_json_prompt"| SummaryLLM2["summary_llm"]:::llmCall
    click SummaryLLM2 "https://github.com/future-house/paper-qa/blob/main/src/paperqa/llms.py"
    SummaryLLM2 --> FinalSummaries["Final Summaries"]:::component

    %% Phase: Generate Answer
    Agent --> AnswerTool["Answer Generator Tool"]:::tool
    click AnswerTool "https://github.com/future-house/paper-qa/blob/main/src/paperqa/agents/tools.py"

    AnswerTool -->|"qa_prompt\n(CONTEXT_OUTER_PROMPT + CONTEXT_INNER_PROMPT)"| AnswerLLM["llm"]:::llmCall
    click AnswerLLM "https://github.com/future-house/paper-qa/blob/main/src/paperqa/llms.py"

    AnswerLLM --> FinalAnswer["Formatted Answer"]:::component
    FinalAnswer --> User

    %% Prompt Templates reference
    PromptTemplates["Prompt Templates"]:::datastore
    click PromptTemplates "https://github.com/future-house/paper-qa/blob/main/src/paperqa/prompts.py"

    %% Styles
    classDef llmCall fill:#f88,stroke:#800,stroke-width:2,stroke-dasharray: 5 5
    classDef datastore fill:#88f,stroke:#004,stroke-width:2
    classDef tool fill:#8f8,stroke:#080,stroke-width:2
    classDef component fill:#fff,stroke:#000,stroke-width:1

    class User component
    class FinalAnswer component
    class PDFParser component
    class RetrievedChunks component
    class Summaries component
    class FinalSummaries component
```
