Navigate the sea of academic papers — with AI as your co-pilot.

Features • Quick Start • Sources • Architecture • Contributing

---

What is Paper Pilot?

Paper Pilot is a local-first desktop research assistant built for scientists who are tired of switching between 10 browser tabs to find, read, and synthesize academic papers.

Projects, papers, notes, conversations, citations, and indexes stay on your machine. Ollama keeps generation local; when you select a hosted provider, only the context needed for that request is sent to the configured endpoint.

You ──▶  Ask a research question
          │
          ▼
     Paper Pilot crawls 8+ academic sources simultaneously
          │
          ▼
     Papers downloaded → converted → indexed (FTS5 + vector search)
          │
          ▼
     AI synthesizes insights from your local corpus
          │
          ▼
You ──▶  Get answers grounded in real papers, not hallucinations

---

✨ Features

🔍 Multi-Source Paper Crawling Simultaneously queries 8+ academic databases: OpenAlex, Crossref, Semantic Scholar PubMed/PMC, arXiv, Europe PMC CORE, Unpaywall Google Scholar (experimental)	🤖 AI-Assisted Synthesis Local Ollama for fully offline operation OpenAI-compatible API support Vercel AI Gateway support with non-generating provider health checks Named, streaming research chats across local and hosted providers Grounded and Exploratory modes with request-scoped source pins Inspectable citations, safe run traces, Stop/Retry, and context-window visibility Automatically saved, non-indexed answer artifacts
🗄️ Smart Local Storage SQLite with node:sqlite (zero dependencies) FTS5 full-text search across all papers sqlite-vec vector similarity search Project-scoped storage — keep research contexts separate	📄 PDF → Knowledge Pipeline Open-access PDF auto-fetching via Unpaywall MarkItDown conversion for AI-ready text Python virtualenv isolation for scripting tools Secure credential storage via Electron safeStorage
🔬 Auditable Evidence Review Versioned protocols with separate title/abstract and full-text screening Previewed RIS, BibTeX, and mapped CSV imports with conservative deduplication Typed, evidence-linked extraction matrix and append-only decision history Provider-neutral, on-demand AI suggestions that require human confirmation Deterministic review-flow summary and traceable export package See the evidence review guide.

---

🚀 Quick Start

Requirements:

• Node.js >= 22.18.0
• Python 3.11+
• (Optional) Ollama for local AI

# Clone and install
git clone https://github.com/Xueyang-Song/paper-pilot.git
cd paper-pilot
npm install

# Run in development
npm run dev

# Build for production
npm run build

# Package as desktop app
npm run package

Note: Dev server must use http://127.0.0.1:5173. If that port is busy, free it before running.

---

📚 Paper Sources

Source	Type	API Key Required
OpenAlex	Multidisciplinary	Optional (email)
Crossref	Multidisciplinary	Optional (email)
Semantic Scholar	CS + Science	Recommended
PubMed / PMC	Biomedical	No
arXiv	Physics/CS/Math	No
Europe PMC	Life Sciences	No
CORE	Open Access	Required
Unpaywall	Open Access PDFs	Optional (email)
Google Scholar	All fields	No (experimental ⚠️)

---

🏗 Architecture

paper-pilot/
├── src/
│   ├── electron/          # Main process (Node.js)
│   │   ├── crawlers/      # Academic source adapters
│   │   ├── db/            # SQLite + FTS5 + sqlite-vec
│   │   ├── agent/         # AI tool-calling agent
│   │   └── python/        # MarkItDown + Playwright bridge
│   └── renderer/          # React 19 + Vite UI
│       ├── workspace/     # ChatGPT-style chat interface
│       ├── projects/      # Project management rail
│       ├── artifacts/     # Paper & artifact panel
│       └── settings/      # API keys, policies
├── tests/                 # Vitest test suite
└── package.json

Tech Stack:

---

⚠️ Current Status

This is an early v1 — buildable, test-covered, but still hardening for production-level reliability.

Area	Status
Core crawlers (OpenAlex, Crossref, arXiv, PubMed)	✅ Stable
SQLite + FTS5 + vector search	✅ Stable
AI agent (Ollama / OpenAI-compatible)	✅ Stable
Evidence-grounded multi-chat research workspace	✅ Stable
Auditable evidence review workspace	✅ Stable
Google Scholar crawler	⚠️ Experimental
macOS / Linux packaging	⚠️ Untested
Cloud sync / collaboration	❌ Not planned

---

🤝 Contributing

Contributions welcome. Please open an issue before large PRs to discuss approach.

npm run verify                 # Format, lint, typecheck, coverage, and build
npm run format:check           # Check repository formatting
npm run lint                   # Run ESLint with zero warnings
npm run test                   # Run test suite (Vitest)
npm run test:coverage          # Run tests with enforced coverage thresholds
npm run typecheck              # TypeScript strict checks
npm run test:crawlers:api      # Live no-key HTTP source smoke
npm run test:crawlers:browser  # Playwright browser crawler smoke

See CONTRIBUTING.md for the protected PR workflow and automatic release labels.

---

Built by a researcher, for researchers.