Freddie is a macOS paper reader built with SwiftUI. The app bundle name is Freddie, while the project name remain ReadPaper.

It focuses on three practical reading workflows:

• import local PDFs with conservative metadata extraction
• import arXiv papers by ID or URL and prefer HTML reading when available
• translate papers through semantic HTML blocks or full-PDF BabelDOC output

• Local-first paper library backed by SwiftData
• Local PDF import with lightweight metadata detection from PDF info and early pages
• arXiv import with step-by-step progress feedback
• arXiv HTML fallback chain: arxiv.org/html/{id} first, then ar5iv
• Readability-based HTML extraction and localization for a cleaner reading view
• Incremental HTML translation with per-block persistence and refresh
• Multi-provider, multi-model OpenAI-compatible routing
• Full PDF translation via BabelDOC with structured progress reporting
• PDF, HTML, and dual-PDF reading modes in one app

• macOS 14.0+
• Xcode with Swift 6 support
• xcodegen
• swift-readability checked out at ./swift-readability

create-dmg is only needed if you want to build a distributable DMG locally.

Clone the repository:

git clone <your-repo-url>
cd read-paper

If swift-readability is missing, clone it into the expected local path:

git clone https://github.com/SYYANI/swift-readability.git swift-readability

Generate the Xcode project:

xcodegen generate

Open the project:

open ReadPaper.xcodeproj

Or build from the command line:

xcodebuild -project ReadPaper.xcodeproj -scheme ReadPaper -destination 'platform=macOS' -derivedDataPath .DerivedData build

Run tests:

xcodebuild -project ReadPaper.xcodeproj -scheme ReadPaper -destination 'platform=macOS' -derivedDataPath .DerivedData test

• ReadPaper/Models: SwiftData models and enums
• ReadPaper/Views: app UI, library, inspector, settings
• ReadPaper/Readers: PDF, HTML, and dual-PDF readers
• ReadPaper/Services: import, arXiv, HTML localization, translation, BabelDOC, storage
• ReadPaperTests: unit tests for import, storage, translation, routing, and subprocess behavior
• project.yml: XcodeGen project definition

ReadPaper does not treat arbitrary PDF text extraction as a reliable full-document structure source.

• Local PDFs are used for reading and lightweight metadata identification
• arXiv papers prefer HTML as the structured reading and translation carrier
• full PDF translation is delegated to BabelDOC

Primary application data is stored under:

~/Library/Application Support/ReadPaper/

Key locations there:

• ReadPaper.store: the SwiftData store for papers, attachments, translation cache, provider/model profiles, and app settings
• Library/{paper UUID}/: per-paper files such as paper.pdf, paper.html, Resources/, translations/, and notes/
• Tools/: app-managed external tool files

Even though the app bundle name is Freddie, the on-disk application support directory currently remains ReadPaper.

Other system locations affected by the app:

• ~/.cache/babeldoc/: BabelDOC may create or update its own cache outside the app support directory during PDF translation-related work
• macOS Keychain: provider API keys are stored as generic password items under the Keychain service com.yiyan.ReadPaper; SwiftData keeps only references such as apiKeyRef, not the raw keys themselves

The repository includes a GitHub Actions workflow that can generate an unsigned macOS DMG on tag push or manual dispatch.

This project is released under the MIT License. See LICENSE.

Special thanks to the projects and ideas that helped shape ReadPaper:

• Mercury
• BabelDOC
• swift-readability