PaperPilot

A Fully Open-Source, AI-Native Paper Reading & Management Platform

English | 中文

---

This project is developed based on the open-source project Resophy. Special thanks to the original author for their interesting creation.

📖 Introduction

<iframe src="//player.bilibili.com/player.html?bvid=BV1kGcGzdEYk&page=1&high_quality=1" scrolling="no" border="0" frameborder="no" allowfullscreen="true" width="100%"></iframe>

PaperPilot is a next-generation research assistant designed to streamline your academic workflow. By integrating advanced AI capabilities with a robust document management system, PaperPilot helps you discover, read, understand, and manage research papers more efficiently than ever before.

Whether you are tracking the latest ArXiv preprints or deep-diving into complex PDFs, PaperPilot acts as your intelligent co-pilot.

Note: This project was built using Trae Coding Agent via Vibe Coding, leveraging two models (Gemini-3-Pro-Preview for feature development and GPT-5.2 for bug fixes and performance optimization). It is truly incredible for someone like me who hasn't written modern Web frontend code 🤯 (the last time I wrote Web code was manually coding HTML and CSS during my undergraduate years).

✨ Key Features

📚 Smart Paper Management

• Seamless Upload: Drag & drop PDF uploads with automatic metadata extraction.
• Organization: Custom categories, folders, and full-text search.
• Zotero Integration: One-click import from Zotero RDF libraries.
• Reading Heatmap: Visualize your reading habits with a GitHub-style contribution graph.

🤖 AI-Powered Reading Assistant

• AI Translation: Generate pixel-perfect English-to-Chinese (and other languages) translations using BabelDOC, preserving original layout and charts.
• AI Interpretation: Deep analysis of papers using MinerU (PDF-to-Markdown) and LLMs to generate structured summaries (Abstract, Methods, Experiments, Conclusions).
• Chat with Paper: Interactive Q&A with your documents to clarify concepts and details.

📡 Daily ArXiv Radar

• Automated Tracking: Schedule daily fetches from specific ArXiv categories (e.g., cs.CV, cs.AI).
• Smart Filtering: Filter papers by keywords, institution weights, and more.
• AI Summarization: Automatically generate concise summaries for new arrivals.
• Offline Capable: Works even without LLM connections (skips summary/institution details).

📸 Feature Showcase

📡 Daily ArXiv Tracking

Automated daily paper fetching with AI summaries to keep you updated.

🤖 AI Interpretation & Chat

Deep full-text analysis and interactive Q&A to bridge language and understanding gaps.

📚 Management & Configuration

Efficient reading list management and flexible system configuration.

🔐 Secure Authentication & Access Control

Supports user authentication for secure private access and public network deployment.

🛠️ Tech Stack

• Backend: Python 3.10+, Flask
• Frontend: HTML5, CSS3, Vanilla JS (Responsive)
• Database: SQLite (Metadata), Supabase (Optional Auth)
• AI Core:
  • MinerU (High-fidelity PDF parsing)
  • BabelDOC (Document Translation)
  • OpenAI-compatible LLM Interface

🚀 Installation

We recommend using uv for fast and reliable dependency management.

Prerequisites

• Python 3.10 or higher
• uv package manager

Steps

1. Clone the Repository

   git clone https://github.com/flyflypeng/PaperPilot
   cd PaperPilot

2. Initialize Environment

   uv venv
   source .venv/bin/activate  # Linux/macOS
   # .venv\Scripts\activate   # Windows

3. Install Dependencies

   Option A: Standard (Client-only) Suitable if you use external APIs for AI tasks.

   uv pip install -e ".[local]"

   Option B: Full Server (Local AI) Includes dependencies for local MinerU and VLM inference.

   uv pip install -e ".[server]"

4. Supabase Auth (Optional) PaperPilot’s login/sign-up is powered by Supabase Auth (Email + Password). When enabled, the frontend uses supabase-js in the browser to obtain a session token and attaches Authorization: Bearer <access_token> to /api/* requests; the backend validates the token via Supabase /auth/v1/user. If SUPABASE_URL and SUPABASE_ANON_KEY are not configured, auth is disabled by default: the login overlay is hidden, and /api/* endpoints do not require an Authorization header, so you can enter the management UI directly.

   1. Create a Supabase project and get API values
   • Create a project at https://supabase.com/
   • In the Supabase dashboard, open Project Settings → API
   • Copy Project URL as SUPABASE_URL
   • Copy Project API keys → anon public as SUPABASE_ANON_KEY
   2. Enable Email auth
   • Go to Authentication → Providers
   • Enable Email (Email/Password)
   • For local/private deployments, you can disable email confirmations in Authentication → Settings to avoid requiring email verification after sign-up
   3. Configure redirect URLs (important)
   • Go to Authentication → URL Configuration
   • Set Site URL to your site origin, for example:
   • Local: http://localhost:7191
   • Production: https://your-domain.com
   • Add allowed callback URLs in Redirect URLs (at least include your site root), for example:
   • http://localhost:7191/
   • https://your-domain.com/
   4. Enable auth in PaperPilot Copy and edit environment variables in the project root:

   cp .env.example .env
   # Edit .env and fill in SUPABASE_URL and SUPABASE_ANON_KEY

   Restart the server. If configured correctly, you will see the login/sign-up entry on the page.

   Security notes

   • Use only the anon public key; never put service_role keys into .env or ship them to the browser
   • This project injects SUPABASE_URL and SUPABASE_ANON_KEY into pages for browser-side login, which is expected

5. Run the Application

   Then start the application:

   python app.py

   Access the web interface at http://localhost:7191 (default port).

   Custom Launch Arguments: app.py supports the following command-line arguments for custom configuration:

   Argument	Default	Description
   --papers-dir	./papers	Path to the papers directory (absolute or relative)
   --host	0.0.0.0	Server listening address
   --port	7191	Server listening port
   --debug	False	Enable debug mode (for development)

   Typical Configuration Examples:

   • Specify Data Storage Location (useful for mounted data volumes):

     python app.py --papers-dir /mnt/data/my_papers

   • Change Server Port (if the default port is occupied):

     python app.py --port 8080

   • Allow Local Access Only (for enhanced security):

     python app.py --host 127.0.0.1

🧪 Testing

Install the test dependencies:

uv pip install -e ".[test]"

Run the fast unit tests, including mocked arXiv behavior:

uv run pytest -q -m "not integration"

Run only the tests that access the live arXiv API and validate the real response format:

uv run pytest -q -m integration

Run the arXiv-related tests directly:

uv run pytest -q tests/test_arxiv_api_interactions.py

The integration tests require network access and depend on arXiv availability. If arXiv is temporarily unavailable or rate-limited, rerun them later.

⚙️ Configuration

PaperPilot is designed to be configurable directly from the Web UI.

arXiv-only proxy

Set ARXIV_PROXY when only arXiv metadata/PDF requests should use a proxy:

ARXIV_PROXY=http://127.0.0.1:7890

Scheme-specific overrides are also supported: ARXIV_HTTP_PROXY and ARXIV_HTTPS_PROXY. These variables are applied only to arxiv.org and export.arxiv.org; DBLP, LLM providers, Supabase, MinerU, and other backend requests are not proxied by this setting.

When baking the value into a Docker image:

docker build --build-arg ARXIV_PROXY=http://host.docker.internal:7890 -t paperpilot .

Agentic Settings

Navigate to the Settings tab to configure:

• LLM Provider: Set your API Key, Base URL, and Model Name (e.g., GPT-4, Qwen, DeepSeek).
• MinerU: Choose between Local instance or Cloud API.

Daily ArXiv

Configure your research interests:

• Categories: Select ArXiv categories to monitor.
• Keywords: Define keywords for filtering and highlighting.
• Schedule: Set the automatic fetch interval.
• Max Papers per Day: Cap the total number of papers fetched per arXiv date. The recommended default is 50.
• Max New Papers per Category per Fetch: Limit how many new papers each configured category can add in a single sync, so repeated syncs can pick up papers released later in the day.
• Replacement Candidate Limit: When a category quota is already full, screen a small number of newer candidates for possible replacement.

The core paper filtering pipeline is:

1. arXiv category and date filter: PaperPilot queries each configured category with cat:<category>, sorted by newest submissions, and keeps only papers that belong to the target arXiv announcement date. Already downloaded Daily ArXiv papers are skipped.
2. Keyword hard filter: If Keywords is not empty, a paper must match at least one configured keyword in its title or abstract. Matching is case-insensitive and normalizes punctuation and whitespace.
3. Quota filter: The remaining candidates must fit both the daily global budget and the per-category budget. Each sync also respects Max New Papers per Category per Fetch.
4. Institution tier hard filter: Because arXiv metadata does not provide affiliations, PaperPilot downloads the candidate PDF first, extracts first-page affiliations through the configured LLM, then applies the selected quality strategy as a hard gate:
   • strict: keep Tier S/A papers; reject Tier B/C and unknown institutions.
   • balanced: keep Tier S/A/B papers and allow unknown institutions; reject Tier C.
   • discovery: keep Tier S/A/B/C papers and allow unknown institutions. Papers rejected by this gate are not saved, summarized, or shown in Daily ArXiv.
5. AI enrichment: Accepted papers get thumbnails, affiliation/country/project-link metadata, and an LLM-generated brief summary and keyword tags when the Daily ArXiv LLM configuration is available.
6. Replacement screening when full: When a category is already full, PaperPilot can evaluate a small number of newer candidates against already kept papers and replace a weaker paper only if the LLM judges the candidate clearly better.

Daily ArXiv can split the daily paper budget in two ways:

• Custom category ratios: In arXiv Categories, set per-category percentages when you want direct control, for example cs.CV 60%, cs.AI 25%, cs.LG 15%. Custom ratios must total exactly 100%; PaperPilot will warn you if the total is above or below 100%.
• Automatic weighted split: If no custom ratios are configured, PaperPilot keeps the existing weighted strategy.

The automatic strategy uses incremental weighted quotas when fetching multiple configured categories:

1. Weighted reservation: PaperPilot dynamically recalculates a per-category quota from the current Categories list every time settings are saved or fetches run. High-volume AI categories such as cs.AI, cs.CV, and cs.LG receive slightly lower weights, while smaller systems/infrastructure categories such as cs.DC, cs.OS, cs.NI, and cs.PF receive higher weights so they are not crowded out.
2. Incremental intake: Each sync only admits up to Max New Papers per Category per Fetch new papers per category. This avoids filling the whole daily budget during an early sync before arXiv has released papers throughout the day.
3. LLM replacement screening: When a category quota is already full, PaperPilot can send newer candidates and the existing papers in that category to the configured LLM. The payload includes paper metadata, abstracts, affiliations, countries, and the current Institution tiers configuration. The LLM should replace an existing paper only when the candidate is clearly more valuable; institution tier is used only as one signal when quality and relevance are otherwise comparable.

This keeps niche categories visible, avoids consuming all daily slots too early, and lets later high-value papers replace weaker earlier picks.

⚠️ Important Notes

• Multi-User Support: The current version of PaperPilot is designed for individuals or small teams and does not yet fully support multi-tenancy. While it supports authentication via Supabase, all users share the same backend configuration and paper library. It is recommended to deploy in a private network or trusted environment.
• BabelDOC Translation: The English-Chinese parallel translation feature based on BabelDOC has high memory consumption and a long processing time. It is recommended to use this feature primarily for papers that require intensive reading.

🗺️ Roadmap

Contributions are welcome! This roadmap is a living document and will evolve with user needs and available time.

Near-Term (Next)

• Reading annotations: highlights, comments, bookmarks, and one-click quote snippets
• Paper chat improvements: grounded answers with page/paragraph/snippet references
• Daily ArXiv rules upgrade: keyword combinations, exclusions, regex
• Deployment & ops: Docker Compose, automated backup/restore, health checks

Mid-Term (Mid)

• Semantic search: local embeddings index (optional vector store) with cross-library search
• Personal knowledge base: turn notes/summaries into a queryable research log (topics/timeline)
• Job queue & progress center: unified queue for translation/interpretation/indexing with retries and priorities

Long-Term (Future)

• Multi-tenancy: isolate libraries and settings per user/team
• Paper recommendations & graph: citation-network and reading-behavior signals
• Collaborative workspace: shared folders, team annotations, access control
• Multimodal understanding: structured extraction for figures/equations/tables and searchability
• Mobile/PWA: offline reading and cross-device sync

Performance & UX (Ongoing)

• Faster PDF rendering, page cache, and on-demand loading for long documents
• Incremental indexing for global search (avoid full rescans)
• Configuration validation and one-click diagnostics (LLM/MinerU/BabelDOC)
• Observability: job timings, failure reasons, and basic metrics

📄 License

This project is licensed under the CC BY-NC 4.0 License. See the LICENSE file for details.

---

Made with ❤️ by the PaperPilot Team