<div align="right">
**English** ยท [ไธญๆ](./README.zh.md)
</div>
<br />
<div align="center">
# paper-search-pro
**Academic literature discovery as a Skill.**
<br/>
Built natively for Claude Code; runs in Codex and any agent that loads the SKILL.md format.
<br/>
Five open sources + native-Chinese search + AI-venue acceptances ยท four tiers ยท journal partitions ยท paste-ready search strategies for WOS / Scopus / Embase / ็ฅ็ฝ ยท single-file Shadcn report.
<br/>
<a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-Apache_2.0-000?style=flat-square" alt="Apache 2.0"/></a>
<a href="SKILL.md"><img src="https://img.shields.io/badge/agent-Skill-000?style=flat-square" alt="Agent Skill"/></a>
<img src="https://img.shields.io/badge/Python-3.10+-000?style=flat-square" alt="Python 3.10+"/>
<img src="https://img.shields.io/badge/version-2.5.0-000?style=flat-square" alt="v2.5.0"/>
</div>
<br/>
<div align="center">
**[โ Live demo (opens the actual report in your browser)](https://o0000-code.github.io/paper-search-pro/)**
If it looks useful, a star makes it easy to find later and helps it reach the next person who needs it.
</div>
<br/>
## What it does
You ask your agent for papers; this Skill runs a real multi-source literature search across **OpenAlex ยท Semantic Scholar ยท CrossRef ยท PubMed ยท arXiv** โ plus native-Chinese sources **NSSD** (็คพไผ็งๅญฆ) and **yiigle** (ไธญๅๅปๅญฆ) when you query in Chinese, and **OpenReview** (ICLR / NeurIPS / ICML acceptances) for AI topics โ classifies relevance via parallel LLM SubAgents, and writes a self-contained HTML report you can open in any browser. No external LLM keys โ your agent **is** the LLM.
For the databases it *can't* self-containedly reach (Web of Science, Scopus, Embase, ็ฅ็ฝ CNKI, ไธๆน, SinoMed โฆ), it does the next best thing: on an Audit run or when you ask ("็ปๆ WOS ๆฃ็ดขๅผ" / "ๆ่ฆๅป็ฅ็ฝๆฅ"), it writes you a **paste-ready professional search strategy** per platform โ correct field tags, controlled vocabulary + free-text double-track, per-host syntax โ distilled from the Cochrane Handbook / PRESS / PRISMA-S, with each strategy carrying a three-state verification label and its review points. It's a professional first draft with flagged review points, not a sign-off-ready deliverable โ and it never scrapes a closed database.
```text
In your agent's chat, after install:
Find papers on working memory training in older adults
```
CJK in the query routes to Chinese UI; otherwise English. Both report flavors use the same data pipeline.
<br/>
## Use cases
| Scenario | Tier | What you get |
|---|:---:|---|
| Scope a topic before writing the proposal | Quick / Standard | 20โ60 top-RCS papers + 300-word executive summary in 8 min |
| Background section for course paper / thesis chapter | Standard | 60โ180 papers screened, BibTeX ready for Zotero / Mendeley |
| Writing a review article โ need real domain coverage | Deep | 180โ400 papers + 1-hop citation chasing + topic clustering |
| SR-prep: PRISMA log + reproducibility audit | Audit | 400โ1000+ papers, PRISMA-S 16-item disclosure, MeSH-precise |
| Onboarding a research assistant in a new field | Quick | Hand them the report.html โ three tabs, hover for context |
<br/>
## Install
Clone into your agent's Skills directory. The target path varies by agent โ pick the one matching what you use:
```bash
# Pick ONE target directory, depending on your agent:
# ~/.claude/skills/paper-search-pro # Claude Code
# ~/.codex/skills/paper-search-pro # Codex CLI
# ~/.agents/skills/paper-search-pro # cross-agent convention (Goose, Roo, etc.)
# ~/.config/opencode/skills/paper-search-pro # OpenCode
# ~/.codeium/windsurf/skills/paper-search-pro # Windsurf
# ./.claude/skills/paper-search-pro # project-local (Cursor, etc.)
git clone https://github.com/O0000-code/paper-search-pro.git \
~/.claude/skills/paper-search-pro # change to your chosen path
# Point PSP_HOME at wherever you cloned. SKILL.md STEP 0 also auto-resolves
# the common paths above, so this manual export is only needed for non-standard locations.
export PSP_HOME="$HOME/.claude/skills/paper-search-pro"
python3 -m pip install -r "$PSP_HOME/scripts/requirements.txt"
# Optional: install the exact dependency versions validated by CI.
python3 -m pip install -r "$PSP_HOME/scripts/requirements.lock"
```
Five free API keys (~15 min total) โ see [`references/setup.md`](references/setup.md).
<br/>
## Four tiers
The Skill picks **Standard** by default. Wording like *thorough*, *systematic review*, or *ๅ ็ฏ* overrides.
| | Tier | Wall-clock | Papers | Trigger signals |
|:---:|:---|:---:|:---:|:---|
| `โ` | Quick | 5โ8 min | 20โ60 | *scan ยท "5 papers" ยท before-tomorrow scope* |
| `โ` | **Standard** | 10โ17 min | 60โ180 | *default โ background reading ยท course paper* |
| `โ` | Deep | 30โ45 min | 180โ400 | *review article ยท thorough coverage ยท ็ปผ่ฟฐๅไฝ* |
| `โ` | Audit | 2โ3 hr | 400โ1000+ | *systematic review ยท PRISMA ยท Cochrane-adjacent* |
<br/>
## What each report contains
Three tabs ยท three hero layouts ยท two list densities ยท responsive at 860 px ยท bilingual UI ยท Noto Sans SC inlined ยท fully offline.
Each report has a scholarly, evidence-bounded title authored after screening. The verbatim user request remains in audit metadata, while language, date, database, journal-tier, and export constraints stay in Methods rather than being repeated in the visual H1.
<table>
<tr>
<td width="50%" valign="top">
<a href="docs/screenshots/methods.png"><img src="docs/screenshots/methods.png" alt="Methods ยท Coverage"/></a>
<br/>
<sub><strong>Methods ยท Coverage</strong> โ saturation curve, estimated coverage with its interval, current position on the curve.</sub>
</td>
<td width="50%" valign="top">
<a href="docs/screenshots/methods-2.png"><img src="docs/screenshots/methods-2.png" alt="Methods ยท Distribution"/></a>
<br/>
<sub><strong>Methods ยท Distribution</strong> โ publications by year, RCS histogram, citation scatter.</sub>
</td>
</tr>
<tr>
<td valign="top">
<a href="docs/screenshots/audit.png"><img src="docs/screenshots/audit.png" alt="Audit ยท PRISMA-S"/></a>
<br/>
<sub><strong>Audit ยท PRISMA-S</strong> โ 16-item disclosure log: performed ยท implicit ยท skipped.</sub>
</td>
<td valign="top">
<a href="docs/screenshots/discovery-report.png"><img src="docs/screenshots/discovery-report.png" alt="Discovery Report layout"/></a>
<br/>
<sub><strong>Discovery Report layout</strong> โ preprint-style hero with abstract paragraph + Roman tabs.</sub>
</td>
</tr>
</table>
**Journal partitions.** Every paper is tagged with its ไธญ็ง้ข (CAS) / JCR / SJR tier โ a quiet badge on each card, the full three-platform breakdown in the detail panel, and a zone filter (`Q1 / โฅQ2 / โฅQ3`, or `ไธๅบ / โฅไบๅบ`) in the toolbar. The tables are fetched at runtime from public mirrors โ never bundled โ and attributed; only JCR's figure is labelled an impact factor.
Outputs land in `$PWD/paper-search-results/<search_id>/`:
```text
report.html Self-contained Shadcn report (opens directly in browser)
report.md Markdown variant for pandoc ยท citation managers
papers.csv Spreadsheet export
papers.bib BibTeX for Zotero ยท Mendeley ยท LaTeX
papers.ris RIS for EndNote ยท Papers
papers.json Full structured data (UnifiedPaperEntity[])
kg_classified.json Internal KG with per-paper RCS scores
execution_log.json PRISMA-S 16-item disclosure log
summary.md 300-word executive summary in the main agent's voice
metadata.json Separate original request ยท search topic ยท display title
```
<br/>
## Configuration
Five keys, all free, ~15 min total. Real config lives at `~/.paper-search-pro/config.yaml` (mode 0600, auto-created). Template lives at [`assets/default_config.yaml`](assets/default_config.yaml).
| Layer | Source | Role | Cost | Apply at |
|:---:|:---|:---|:---:|:---|
| **L1** | OpenAlex | primary โ always on | free | <https://openalex.org/settings/api> |
| **L2** | PubMed | medical ยท MeSH enricher | free | <https://account.ncbi.nlm.nih.gov/settings/> |
| **L2** | arXiv | preprint freshness (Tโ0\~Tโ4) ยท AI topics (Tโ0\~Tโ365) | free | *(no signup โ SDK enforces 1 req / 3 s)* |
| **L3** | Semantic Scholar | influentialCitationCount + abstract fallback | free | <https://www.semanticscholar.org/product/api> |
| **L3** | CrossRef | funder ยท license ยท clinical-trial-number | free | *(no key โ `crossref_email` only)* |
Verify readiness any time:
```bash
PYTHONPATH=$PSP_HOME python3 -c \
"from scripts.config import load_config; c = load_config(); \
print('ready' if c.openalex_api_key and c.ncbi_email else 'missing')"
```
**Primary source โ by preference, *and* by fallback.** Two independent capabilities from one switch:
- **Pick your primary.** OpenAlex is the default; set Semantic Scholar as the primary source instead when its corpus or field coverage suits your topic better.
- **Automatic quota fallback.** When the active primary runs low on its daily quota (or starts erroring), the run continues on the other source rather than stopping โ a depleted key degrades gracefully.
<br/>
## Topic-specific sources
Beyond the five general sources in the table above, these three switch on only for their topics and need no key; each is run by an authority in its field:
| Source | Run by | When it is used | What it adds |
|:---|:---|:---|:---|
| NSSD (National Center for Philosophy and Social Sciences Documentation) | led by the Chinese Academy of Social Sciences | Chinese-language social-science and humanities queries | CSSCI and other Chinese social-science journals, which OpenAlex barely covers |
| yiigle (Chinese Medical Journals Full-text Database) | Chinese Medical Association Publishing House | Chinese-language medical queries | Chinese originals and abstracts of the Chinese Medical Association journals |
| OpenReview | non-profit platform run by a team at UMass Amherst | AI / machine-learning topics | Acceptance labels from ICLR, NeurIPS, ICML and others (e.g. "ICLR 2026 Oral"); accepted papers only |
<br/>
## How it works
A 14-step recipe in [`SKILL.md`](SKILL.md) drives every run. Python helpers in [`scripts/`](scripts/) do deterministic API work; relevance classification is delegated to up to five parallel SubAgents per round. No third-party LLM keys required โ your agent is the LLM.
```
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Main agent reads SKILL.md (recipe) and drives the run โ
โโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโ
โ โ
โผ โผ
โโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโ
โ Python โ โ deterministic API โ SubAgents โ
โ helpers โ work; no LLM, โ (parallel, โ
โ โ no LLM key โ 5 / round) โ
โโโโโโโโโฌโโโโโโโโ โโโโโโโโโฌโโโโโโโโ
โ โ
โโโโโโโโโโโโโโโโโโโโโฌโโโโโโโโโโโโโโโโโโโโ
โผ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
โ Single-file HTML report โ
โ + MD + BibTeX + RIS โ
โ + CSV + PRISMA-S log โ
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
```
Per-step reference documents live in [`references/`](references/) โ tier decisions, query planning (PICO / SPIDER / PEO), source routing, helper cheatsheets, the RCS rubric, stop conditions, citation chasing, the classifier SubAgent prompt, the PRISMA-S 16-item checklist, summary writer guide, error handling, output conventions.
**Headless mode for agents.** When the consumer is another agent rather than a person, [`scripts/agent_search.py`](scripts/agent_search.py) runs the deterministic core in a single command and returns one structured JSON envelope โ deduped, relevance-scored, saturation-checked โ with no HTML and no classification SubAgents. Same search discipline, machine-readable output.
<br/>
## Contributors
I maintain paper-search-pro mostly on my own, with help from two lovely contributors, [@haoxinC111](https://github.com/haoxinC111) and [@MatrixA](https://github.com/MatrixA). You're welcome to be the third. If it has helped you, your star means a lot to me, and I'll keep improving it.
<br/>
## License
Apache License 2.0 โ see [`LICENSE.txt`](LICENSE.txt).