文献发现、课题组织与证据可追溯的论文阅读。

Paper Atlas 1.5

Local-first AI research workspace for literature discovery, project organisation and evidence-aware paper reading.

Python FastAPI SQLite Offline

Paper Atlas turns a folder of PDFs into a research workspace. It combines arXiv and journal discovery, project-based literature management, structured AI analysis and a split-pane PDF reader that connects every AI conclusion to its source page and quote.

Everything runs on your machine. Papers, notes, annotations, analyses and settings stay in a local data/ folder; no account, cloud sync or external database is required.

This repository contains code, scripts, static assets and documentation only. It does not include downloaded PDFs, the data/ folder, a configured API key, virtual environments, caches or local build artefacts.

Why Paper Atlas
Features
Tech stack
Architecture at a glance
Quick start
Documentation
Project layout
Configuration
Data and privacy
Verification
Build a standalone app
Troubleshooting
Known limitations
Third-party components

Why Paper Atlas

Most paper tools stop at "download and preview". Research work needs the next step:

Which project is this paper for?
What question is it answering?
Which sentence supports this conclusion?
What have I already read, highlighted and written?
Can I ask questions about the paper without sending my whole library to a cloud service?

Paper Atlas organises the workflow around projects, keeps the PDF and AI analysis side by side, and stores evidence with page numbers and quotes.

Features

Literature discovery

arXiv search with keyword or AI-generated queries.
Journal search through Elsevier, OpenAlex and Crossref fallback.
Relevance screening, queueing and durable processing states.
PDF download with resume, mirror fallback, size checks and optional Playwright fallback.
Manual Firefox handoff for publisher pages that require a captcha, login or subscription.
Local library with search, filters, favourites and analysis history.

Research project workspace

Multiple projects with independent descriptions, background, objectives, directions and keywords.
Project literature sets with core/to-read markers, reading status, personal evaluation, rating and tags.
Research questions with hypotheses, keywords and linked papers.
Notes, progress logs, milestones and reports.
Project-scoped relevance and literature filters (year, tag, role, reading status, analysed state).
A paper can belong to multiple projects while the PDF and metadata are stored once.

AI-assisted PDF reader

Split-pane layout: PDF on the left, structured analysis on the right.
PDF.js rendering with text selection, zoom, fit-width/page, single-page and continuous modes.
PDF outline/TOC navigation and page search.
Twelve analysis modules: basic information, background, objectives, scientific questions, methods, data sources, technical route, experimental design, main results, innovations, limitations and future work.
Evidence links with PDF physical page, section, quote and verification status.
Click a conclusion/evidence to jump to the page; highlight the source text when the text layer supports it.
Select text to explain, summarise, translate, explain a formula/method, or relate it to the research goal.
Highlights, underlines, comments, bookmarks and key-evidence markers.
Reading notes, save selection as a project note, reading-state restore.
AI answers are advisory; they never overwrite user edits and are only saved when the user confirms.

Local-first engineering

Single Python process, single SQLite database, no external services required.
DeepSeek, Ollama or any OpenAI-compatible endpoint.
Local PDF.js assets: the reader works offline.
Incremental schema migrations with backup and verification scripts.
Windows, Ubuntu/Linux and macOS launchers.
A clean, source-only distribution: no bundled data, PDFs, keys, virtual environments or local build artefacts.

Tech stack

Layer	Technology
Web service	FastAPI + Starlette + Uvicorn
Templates	Jinja2, single-page views
Frontend	Vanilla JavaScript/CSS, no framework, no CDN
PDF rendering	PDF.js 4.10.38 (vendored)
PDF parsing	PyMuPDF
AI	OpenAI-compatible SDK (DeepSeek / Ollama / custom endpoint)
Storage	SQLite (WAL) + local files
Packaging	PyInstaller (optional)

Architecture at a glance

flowchart LR
  UI["Browser UI<br/>vanilla JS + PDF.js"] --> API["FastAPI<br/>local service"]
  API --> DB[("SQLite<br/>data/review.db")]
  API --> PDFS["Local PDFs<br/>data/"]
  API --> AI["DeepSeek / Ollama /<br/>OpenAI-compatible"]
  UI --> PDF["PDF.js<br/>vendored, offline"]

Quick start

Windows

start.bat

Linux / macOS

chmod +x start.sh
./start.sh

The launcher creates a private .venv, installs dependencies and starts the local dashboard. On first start it also creates data/ and a fixed access code.

Open:

http://127.0.0.1:8765

Enter the access code shown in the launcher console. You can change it later in Settings → Network.

Check the environment without starting

python launcher.py --check

Requirements

Python 3.10+ when running from source.
Windows 10/11, Ubuntu 20.04+ or macOS.
No administrator rights required.
Internet access is only needed for search/download and remote AI APIs; existing local reading works offline.

For a complete installation and uninstallation guide, see docs/INSTALL.md.

Documentation

Document	What it covers
docs/INSTALL.md	Install, upgrade, uninstall, portable build, data folder
docs/USAGE.md	Dashboard, search, journal workflow, projects, PDF reader, AI, settings
docs/TROUBLESHOOTING.md	Startup, access code, Ollama, DeepSeek, PDFs, migrations, packaging
docs/ARCHITECTURE.md	Modules, data model, task system, AI/PDF services, security
docs/API.md	HTTP API overview and examples
docs/DEVELOPMENT.md	Local development, migrations, build, release checklist
docs/zh-CN/README.md	Chinese documentation index

Project layout

Paper_Atlas1.5/
├── README.md / README.zh-CN.md
├── app.py                     # FastAPI composition root (arXiv + system routes)
├── auth.py                    # Access code, session cookie, login page
├── config.py                  # Compatibility shim -> atlas.core.config
├── launcher.py                # uv/venv bootstrap, start, diagnose, shortcut
├── paper_atlas.py             # Frozen-build entry point
├── build.py / build.sh / build.bat
├── start.sh / start.bat
├── install.sh
├── requirements.txt
├── requirements-optional.txt
├── .env.example
├── .github/workflows/build.yml
├── packaging/paper_atlas.spec
├── atlas/
│   ├── core/                  # settings, paths, logging, errors, IDs
│   ├── api/                   # project/dashboard/reader/assistant routers
│   ├── db/                    # schema, repositories, migrations
│   ├── integrations/          # LLM client
│   ├── jobs/                  # durable download jobs
│   └── services/              # project assistant, reader service
├── review/                    # journal acquisition and analysis pipeline
├── templates/index.html
├── static/
│   ├── app.js / review.js / local.js
│   ├── dashboard.js / projects.js / project-workspace.js
│   ├── reader.js
│   ├── style.css
│   └── vendor/pdfjs/          # PDF.js runtime + cmaps + fonts
├── scripts/                   # backup, verify, migrate
└── docs/

data/ is created at runtime and is intentionally absent from this repository.

Configuration

The recommended way to configure Paper Atlas is the web UI:

AI: DeepSeek, Ollama or OpenAI-compatible base URL/model/key.
Network: host, port, access code.
Downloads: size limit, concurrency, resume, browser fallback.
Interface: language and theme.
Journal workflow: research goal, journals, analysis prompt, Python/Elsevier settings.

Settings are stored in data/config.json. Environment variables override the file and are documented in .env.example.

Never commit data/config.json or .env. They can contain API keys and the access code. This repository ships neither.

Data and privacy

All user data stays under data/ by default:

data/
├── config.json          # settings (may contain API keys)
├── library.json         # arXiv download index
├── pdfs/                # arXiv PDFs
├── jobs.db              # durable download jobs
├── logs/                # rotating application log
└── review/
    ├── review.db        # papers, projects, analyses, notes, annotations
    ├── pdfs/            # journal PDFs
    ├── analysis/        # analysis JSON copies
    ├── downloads/       # manual download inbox
    └── firefox-profile/ # manual-handoff Firefox profile (sensitive)

Backup: python scripts/backup_data.py
Verify: python scripts/verify_data.py
Migrate: python scripts/migrate_schema.py
Never copy firefox-profile/ to a shared location.
The app does not upload your library to a server; AI requests are sent only to the provider you configure.

Verification

After installing, verify the environment and the main paths manually:

python launcher.py --check
./start.sh          # or start.bat

Then open the dashboard, create a project, open a local paper, and confirm that the reader, AI panel and annotation controls render. On a release build, run:

./dist/PaperAtlas --check

Data integrity can be checked without touching the library:

python scripts/verify_data.py

Build a standalone app

# Linux / macOS
./build.sh --clean --zip

# Windows
build.bat --clean --zip

The result is written to dist/ and bundles Python, dependencies, templates, static assets and PDF.js. Build on the same OS family you intend to run on. See docs/INSTALL.md.

Troubleshooting

Start with:

python launcher.py --check

Common issues:

Port already in use → change the port in Settings or --port.
Forgot access code → see the console or data/config.json.
Ollama not reachable → run ollama serve, then check Settings → AI.
PDF not found → the paper may have no local PDF; use Download or import.
Scanned PDF → text extraction is unsupported; the app reports it instead of inventing content.
AI errors → check provider/model/key and the application log.

Full guide: docs/TROUBLESHOOTING.md.

Known limitations

Printed page numbers are not reliably detected; the reader uses PDF physical pages and labels printed pages as unknown instead of guessing.
Evidence highlighting depends on the PDF text layer. If text cannot be matched, the reader jumps to the page and shows the quote without drawing a false highlight.
Scanned/image-only PDFs need OCR, which is not implemented.
Analyses created before the structured analysis schema may have empty background/objectives/data-source/future-work panels; missing fields are not inferred.
The arXiv download job queue and the journal review queue use separate state stores.
Journal full text depends on publisher access; the app never bypasses captchas or paywalls.

Languages: English · 简体中文 · 中文文档