README_EN.md

Paper Reader

Intelligent academic paper analysis tool, supporting AI programming agents such as Claude Code.

Search · Fetch · Analyze · Learn

---

简体中文 · English

---

Overview

Paper Reader is an intelligent academic paper analysis tool designed for AI coding agents. It provides a complete workflow from paper search to deep analysis, supporting multiple academic databases and producing structured Markdown output.

Use cases:

• Research literature review and summarization
• Quick paper screening for relevance
• Deep analysis of methodology and findings
• Tracking research trends and gaps
• Academic writing preparation

---

Key Features

Feature	Description
Multi-Source Search	Search papers across arXiv, PubMed, Semantic Scholar, and CrossRef simultaneously
Auto PDF Download	Automatic PDF retrieval with multi-source fallback
MinerU Integration	Convert PDF to Markdown while preserving layout, figures, and tables
v2.0 Decision-Driven Analysis	L1-L4 granular output: concepts/relations/ontology/evidence graphs
Three-Layer Quality Verification	L1 format / L2 content / L3 consistency validation
Image Smart Embedding	Base64 inline / external file / Obsidian wikilink three strategies
E2E Pipeline	PDF → VLM → analyze → verify → embed, one-click automation
Subagent Parallel Management	Five patterns: single/Map-Reduce/Pipeline/ToT/Hierarchical
Cross-Platform	Works on Windows, macOS, and Linux

---

Installation

For AI Agents (Recommended)

Simply tell your AI agent to install the skill:

Please follow the instructions in this repository: https://github.com/nowa277/paper-reader to configure and install the skill.

Manual Installation

# Clone and install locally
git clone https://github.com/nowa277/paper-reader.git
cd paper-reader
pip install -e .

# Or install from PyPI (coming soon)
# pip install paper-reader

Docker Installation (Recommended for Server/Cloud)

# Clone project
git clone https://github.com/nowa277/paper-reader.git
cd paper-reader

# Build image
docker build -t paper-reader .

# Run
docker run -it --rm -v ~/papers:/app/papers paper-reader python main_skill.py --help

# Or use docker-compose
docker-compose up --build

Docker + MinerU (PDF Conversion)

# Use docker-compose to start full environment
docker-compose up paper-reader-mineru

Requirements:

• Python 3.10+
• requests and psutil (installed automatically)

Optional: For PDF-to-Markdown conversion, install MinerU separately.

---

Quick Start

Search for Papers

/paper-reader fetch "machine learning optimization"

The agent will search multiple academic databases and return a ranked list of relevant papers with metadata (title, authors, year, abstract, source).

Analyze a Paper (v2.0 Decision-Driven)

/paper-reader analyze <paper-id>

v2.0 workflow:

1. Read METHODOLOGY.md — Decision framework constitution
2. Answer 4 Questions — Document type / Scale & structure / User intent / Output location
3. Run Decision Prompt — LLM auto-selects granularity, chunking, graph, and output strategy
4. Call API — analyze_with_decision() generates file scaffold
5. LLM Fills Content — Agent完善分析结果

Select analysis level (L1-L4) when prompted, or use v1.0 compatible A/B/C levels

Setup Commands

/paper-reader setup mineru      # Check MinerU status
/paper-reader setup mineru install  # Install MinerU
/paper-reader setup config show  # View configuration

---

Analysis Levels (v2.0)

Level	Use Case	Output	Token Budget
L1	Quick screening, concept lookup	Concept dictionary	< 1k
L2	In-depth reading, user guide	Concept + relationship graph	~2-5k
L3	Knowledge base building, textbooks	Complete ontology (concepts+relations+hierarchy)	~10-50k
L4	Research preparation, paper analysis	Complete graph (with evidence citations)	~50-200k

v1.0 Compatible: A/B/C levels still work, analyzer auto-backwards compatible

---

Multi-Source Search

Source	Best For
arXiv	Computer Science, Physics, Mathematics, Quantitative Finance
PubMed	Biomedical, Life Sciences, Medicine
Semantic Scholar	Broad coverage, citation graphs, AI-powered recommendations
CrossRef	DOI-based lookup, publisher metadata

---

Supported Platforms

Platform	Status
Linux	Supported
macOS	Supported
Windows	Supported

---

Supported Agents

Agent	Status
Claude Code	Supported
Cursor	Supported
Codex CLI	Supported
opencode	Supported
Hermes Agent	Supported
Gemini CLI	Supported
Copilot	Supported
Windsurf	Supported
Zed	Supported

---

Architecture

paper-reader/
├── skills/
│   ├── analyze/           # Paper analysis (v2.0 decision-driven)
│   │   ├── analyzer.py           # Core API (Decision, analyze_with_decision)
│   │   ├── METHODOLOGY.md        # v2.0 decision framework constitution
│   │   ├── decision_prompts/     # 4 LLM decision prompts
│   │   ├── granularity/          # L1-L4 level definitions
│   │   ├── subagent_policy.py    # Subagent parallel strategies
│   │   ├── verification/         # L1/L2/L3 quality verification
│   │   ├── image_embedder.py    # Image smart embedding
│   │   └── e2e_integration.py   # End-to-end pipeline
│   ├── config/            # Configuration management
│   ├── fetch/             # Paper retrieval and search
│   │   └── sources/      # arXiv, PubMed, Semantic Scholar, CrossRef
│   └── mineru/            # PDF to Markdown conversion
├── agent_adapters/         # Agent adapter implementations
└── tests/                 # Test suite

---

Configuration

Config file: ~/.paper-reader/config.json

{
  "version": "2.0",
  "mineru": {
    "installed": false,
    "path": null
  },
  "fetch": {
    "default_mode": "jina"
  },
  "analyze": {
    "default_level": "L2",
    "enable_verification": true,
    "enable_image_embedding": false
  },
  "subagent": {
    "default_pattern": "SINGLE",
    "token_threshold_map_reduce": 50000,
    "token_threshold_hierarchical": 200000
  }
}

---

License

MIT License