paperpilot 1.0.2

A CLI research agent for AI-related paper search, code discovery, PDF collection, and bilingual reports.

PaperPilot

A CLI AI literature search agent that follows a v1.0 research workflow:

Intake -> Protocol -> Search -> Corpus -> Screening -> Verification -> Synthesis -> Review -> Report

Quick Start

pip install -e .
PaperPilot

Command mode:

PaperPilot "LLM agent" --auto-confirm --max-papers 30 --since-year 2021
PaperPilot "RNA inverse folding sequence design" --github-filter required --mode apa --quality balanced
PaperPilot inspect runs/<task-id>
PaperPilot resume runs/<task-id>

LLM Config

Recommended:

PaperPilot config set --base-url https://api.deepseek.com --model deepseek-chat
PaperPilot config import ./api.json
PaperPilot config show
PaperPilot config list
PaperPilot config use deepseek

The config is stored at ~/.paperpilot/config.json with file mode 600 where supported. Running PaperPilot without an LLM config starts a setup wizard. The app requires a working LLM configuration before running searches. Inside the interactive shell, use /model to add, import, switch, test, or delete model profiles.

Priority:

1. Environment variables: OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MODEL
2. User config: ~/.paperpilot/config.json
3. Legacy project file: llmapi.txt

Without a working LLM config, PaperPilot will pause and ask you to configure one first.

Outputs

Each run writes:

• task.json
• state.json
• manifest.json
• query_understanding.md
• plan.json
• protocol.json
• metadata.json
• corpus.json
• core_papers.json
• adjacent_papers.json
• excluded_papers.json
• ranked_papers.json
• verification.json
• quality_gate.json
• literature_matrix.json
• synthesis.json
• report.canonical.json
• reflection.json
• report.zh.md
• report.en.md
• report.zh.html
• report.en.html
• report.zh.pdf
• report.en.pdf
• download_log.json
• pdfs/
• fulltext/
• paper_notes.json

The Chinese and English Markdown, HTML, and PDF reports are rendered from the same report.canonical.json, so paper lists and conclusions stay aligned.

GitHub Filter

literature-agent "retrieval augmented generation" --auto-confirm --github-filter required

• any: keep all papers and annotate code availability.
• required: the final report view keeps papers with a detected public code link; the full screened corpus is still saved.
• none: keep papers without detected public code links.

v1.0 Quality Layer

• protocol.json records research question, inclusion/exclusion rules, sources, and negative keywords.
• corpus.json stores every screened paper with core, adjacent, or exclude decisions.
• verification.json records DOI, URL, PDF, and code confidence status.
• quality_gate.json emits pass, retry, or needs_user_attention.
• literature_matrix.json and synthesis.json support APA-style reports with evidence limits and AI disclosure.
• Reports include a real review narrative: field background, method families, representative paper summaries, method comparison, trends, and open questions.