Literature Review Agent

English | 简体中文

An auditable and resumable multi-agent workflow for scholarly retrieval and evidence-grounded literature review writing.

The repository combines two LangGraph agents. They work together as one end-to-end pipeline, but each agent is also a complete, independently usable tool.

General-purpose AI writing often relies on model memory or one-shot prompts, which can lead to fabricated references, insufficient citations, an uncontrolled evidence corpus, and deviations from the intended article structure. This project addresses these problems through a retrieval, human selection, evidence extraction, structured writing, and audit workflow.

• Prevent fabricated references: Writing is grounded in literature that has actually been retrieved and downloaded. The Review Agent extracts evidence cards from local full text and generates citations from real document metadata, preventing the model from inventing references.
• Broader reference coverage: The Search Agent supports Europe PMC and arXiv retrieval, deduplication, and bounded bidirectional citation expansion. The Review Agent analyzes evidence coverage by section to expose literature and evidence gaps.
• A user-controlled evidence corpus: Users inspect the links returned by the Search Agent and choose which papers to download. Because the Review Agent reads only the designated directory, the eligible evidence set remains explicitly under user control.
• A user-controlled article structure: Users approve or directly provide a Markdown outline. The Review Agent converts it into a stable section-tag tree, writes from leaf sections upward, and audits the result against the approved structure.
• Auditable and resumable execution: Retrieval results, literature cards, section drafts, coverage analysis, and audit records are retained as intermediate artifacts, making evidence tracing, troubleshooting, and recovery easier.
• Independently usable agents: The Search Agent can build a reproducible literature collection on its own, while the Review Agent can independently write from an existing outline and local document corpus.

The agents do not have to run together:

• Use Literature Search Agent alone when you need a reproducible literature collection and CSV export.
• Use Literature Review Agent alone when you already have an outline and local PDF or Markdown literature.
• Combine both agents for a full-text review by exporting links with Search, manually downloading accessible papers, and giving the approved outline and download directory to Review.
• Use the optional abstract pipeline only when abstract-level evidence is sufficient.

The primary combined workflow uses full papers. Search discovers the literature, the user downloads the selected papers, and Review writes from the downloaded files and approved outline.

flowchart TD
    A[Research topic] --> B{Outline source}
    B -->|AI-generated| C[Exploratory retrieval]
    C --> D[Evidence-grounded outline proposals]
    D --> E{User approval or feedback}
    E -->|Revise| D
    E -->|Approve| F[Formal retrieval]
    B -->|User Markdown outline| F
    F --> G[Europe PMC and arXiv]
    G --> H[Metadata screening and deduplication]
    H --> I[One-hop bidirectional citation expansion]
    I --> J[literature.csv with access_url]
    J --> K[User checks links and access rights]
    K --> L[Manual download to the literature directory]
    F --> M[Approved outline]
    L --> N[Review Agent]
    M --> N
    N --> O[Outline tag tree and literature cards]
    O --> P[Tag index and coverage analysis]
    P --> Q[Bottom-up section writing and audits]
    Q --> R[Deterministic citations and references]
    R --> S[final_review.md]

With only a topic, the Search Agent first explores real results and proposes an evidence-informed outline. It pauses for explicit approval and accepts feedback without treating feedback as approval.

A user-provided Markdown outline skips exploration and the approval gate. Every valid nested heading participates in formal retrieval.

Formal retrieval searches Europe PMC and arXiv, applies metadata and model relevance screening, deduplicates publication versions, and expands references and citations by one bounded Europe PMC hop.

The Search Agent exports literature.csv. Its access_url column points to the available landing page or document location for each included record.

Search does not download or persist the full papers. The user must review the links, respect publisher and repository access conditions, and manually download legally accessible PDF or Markdown files into a designated literature directory.

The approved outline must also be saved as a UTF-8 Markdown file. Review receives that outline and the literature directory through request.json.

This manual step is required for a full-text combined workflow. A link in literature.csv is discovery metadata; it is not evidence that Review can read until the corresponding document is placed in the input directory.

The Review Agent reads only the files present in the configured literature directory. It does not follow Search links or download papers automatically.

It converts the approved outline into a stable tag tree, defines section semantics, builds one evidence card per downloaded paper, and indexes the extracted evidence against the outline.

It writes leaf sections before parent sections, audits provenance and structure, assembles the article, formats citations deterministically, and writes the final review with inspectable intermediate artifacts.

PDF files are converted to Markdown with MinerU before evidence extraction. Existing Markdown is read directly.

Python 3.11 or later is required.

git clone https://github.com/littlelelephant/literature-review-agent.git
cd literature-review-agent
powershell -ExecutionPolicy Bypass -File .\scripts\setup.ps1
.\.venv\Scripts\Activate.ps1

Linux and macOS:

git clone https://github.com/littlelelephant/literature-review-agent.git
cd literature-review-agent
sh ./scripts/setup.sh
source .venv/bin/activate

The setup scripts create one shared virtual environment and install both agents in editable mode.

You can inspect the PowerShell setup script and POSIX setup script before running them.

The default model uses DeepSeek. Set credentials in the current shell; the project does not automatically load .env files.

$env:DEEPSEEK_API_KEY = "your-deepseek-key"

MINERU_API_KEY is needed only when the independently run Review Agent parses PDF files.

Use an existing outline to begin formal retrieval immediately:

literature-search start "Reliability of retrieval-augmented generation in healthcare" `
  --outline-file .\examples\outline.example.md `
  --config .\agents\literature-search\config.yaml

Omit --outline-file to let the agent propose an outline, then approve it to continue formal retrieval:

literature-search start "Reliability of retrieval-augmented generation in healthcare" `
  --config .\agents\literature-search\config.yaml

literature-search resume SESSION_ID --approve `
  --config .\agents\literature-search\config.yaml

The completed session writes outputs/<session_id>/literature.csv. If the outline was generated by Search, save the approved outline as UTF-8 Markdown for the Review step.

Open literature.csv and use each selected record's access_url to locate the paper. Download only documents that you are authorized to access and use.

Place the PDF or Markdown files in one dedicated directory. The agents do not perform this full-text download step automatically.

review-input/
├── outline.md
├── request.json
└── literature/
    ├── paper-001.pdf
    ├── paper-002.pdf
    └── paper-003.md

The file names do not need to match Search record IDs. Review discovers supported documents in the directory and assigns stable internal paper IDs.

Create review-input/request.json. When running from the repository root, point literature_directory to the folder populated in the previous step:

{
  "review_question": "What does the evidence show?",
  "outline": "outline.md",
  "literature_directory": "review-input/literature",
  "output_directory": "review-runs",
  "output_language": "en",
  "citation_style": "elsevier-harvard"
}

Set MinerU credentials when the folder contains PDF files, then start Review:

$env:MINERU_API_KEY = "your-mineru-token"

literature-review `
  --request .\review-input\request.json `
  --run-id review-001

Review uses the supplied outline and only the documents currently present in review-input/literature.

If abstract-level evidence is sufficient, Search can launch Review without downloading full papers:

literature-search pipeline "Reliability of retrieval-augmented generation in healthcare" `
  --outline-file .\examples\outline.example.md `
  --config .\agents\literature-search\config.yaml `
  --review-agent-dir .\agents\literature-review `
  --output-language en

This mode creates Markdown evidence files from available abstracts and marks them evidence_depth: abstract. It must not be presented as a full-text review.

Request an outline revision before approval in AI-outline mode:

literature-search resume SESSION_ID `
  --feedback "Add a section on clinical validation and deployment risk" `
  --config .\agents\literature-search\config.yaml

Inspect a persisted Search session at any time:

literature-search status SESSION_ID `
  --config .\agents\literature-search\config.yaml

The full-text combined workflow uses separate Search, manual input, and Review locations:

outputs/<session_id>/
└── literature.csv

review-input/
├── outline.md
├── request.json
└── literature/
    └── manually downloaded PDF or Markdown files

review-runs/review-001/
├── final_review.md
├── references.json
├── cards/
├── section_drafts/
└── audit artifacts

Search session state and Review checkpoints are persisted separately. Reusing the same Review run ID is safe only when its resolved inputs have not changed.

literature-search start "AI-assisted medical diagnosis" `
  --config .\agents\literature-search\config.yaml

The Search Agent pauses for outline approval and then exports literature.csv. It can also accept --outline-file and begin formal retrieval immediately. See the independent Search Agent guide.

literature-review `
  --request .\request.json `
  --run-id review-001

The Review Agent reads an outline and a local PDF or Markdown directory without calling the Search Agent. See the independent Review Agent guide.

• Retrieval uses the official Europe PMC REST API and arXiv Atom API.
• Citation expansion uses only official Europe PMC references and citations endpoints and is limited to one hop.
• The default model is deepseek-v4-pro; OpenAI-compatible providers are also supported.
• Optional PDF parsing uses MinerU before the Review graph starts.
• A single search-platform outage permits degraded completion; failure of both platforms is recoverable.
• Search-only runs do not persist full paper text.
• Users are responsible for downloading papers lawfully and for complying with publisher, repository, and document-license terms.
• Abstract handoff claims are never represented as full-text findings.
• API keys, .env, generated runs, caches, databases, virtual environments, and downloaded papers must not be committed.

The Review Agent uses MinerU, developed and maintained by OpenDataLab, to convert PDF input into Markdown before evidence extraction.

This repository integrates with the hosted MinerU v4 API and does not vendor MinerU source code.

MinerU remains an independent project governed by its own MinerU Open Source License and service terms.

For academic use, please cite the MinerU version or model you use. The official repository lists the following foundational citation:

@article{wang2024mineru,
  title={Mineru: An open-source solution for precise document content extraction},
  author={Wang, Bin and Xu, Chao and Zhao, Xiaomeng and Ouyang, Linke and Wu, Fan and Zhao, Zhiyuan and Xu, Rui and Liu, Kaiwen and Qu, Yuan and Shang, Fukai and others},
  journal={arXiv preprint arXiv:2409.18839},
  year={2024}
}

See the official MinerU citation section for citations tied to newer MinerU models.

python -m pytest tests
python -m pytest agents\literature-search\tests
python -m pytest agents\literature-review\tests
ruff check --config agents\literature-search\pyproject.toml agents\literature-search\src agents\literature-search\tests
mypy --config-file agents\literature-search\pyproject.toml agents\literature-search\src
mypy --config-file agents\literature-review\pyproject.toml agents\literature-review\src
flake8 --config agents\literature-review\.flake8 agents\literature-review\src agents\literature-review\tests
isort --settings-path agents\literature-review\pyproject.toml --check-only agents\literature-review\src agents\literature-review\tests

Read CONTRIBUTING.md before opening a pull request. Report security issues through SECURITY.md.

Licensed under the GNU Affero General Public License v3.0.