Star0
0
代码
代码
Issues
Pull Requests
项目讨论
Wiki
分析
Star0
0
LNN0212LNN0212Initial Project Submission
f73b6250创建于 3 天前历史提交

Paper Atlas 1.5

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

Python FastAPI SQLite Offline

English · 简体中文 · 中文文档

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.

Contents

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 · 简体中文 · 中文文档