Reader3 - EPUB Reader with AI Analysis

A lightweight, self-hosted EPUB reader with integrated AI analysis capabilities.

Features

Reading Experience

• 📚 Clean Layout - Three-column design (TOC, Content, AI Panel)
• 📖 Sticky Navigation - Top navigation bar stays visible while scrolling
• ⌨️ Keyboard Shortcuts - Arrow keys for prev/next chapter, ESC to close panels
• 🔗 Internal Links - Footnotes and author comments open in modal popups
• 🎯 Clickable Covers - Click book covers to start reading instantly

AI & Annotations

• 🤖 AI Analysis - Right-click on text for fact-checking or discussion (Ollama local or Cloud)
• � *Personal Comments - Add your own notes without AI (no API cost)
• 💾 Manual Save - Choose what to save to avoid clutter
• ✨ Color-Coded Highlights - Yellow (fact check), Blue (discussion), Green (comments)
• 🏷️ Smart Tooltips - Hover over highlights to see type
• 🗑️ Edit & Delete - Manage all your highlights and comments
• 🎨 Markdown Support - AI responses render with proper formatting

Library & Organization

• 📝 Highlights View - See all your notes and analyses for each book
• 📤 Export to Markdown - Export highlights with AI context warnings
• 🌐 Web Upload - Upload EPUB files via click or drag & drop
• 🖼️ Cover Images - Automatic cover extraction and display
• 🔍 Search - Find books by title or author
• 🗂️ Organized Storage - All books in books/ directory, data in SQLite

Quick Start

1. Configure Ollama

Edit .env file:

# Ollama
OLLAMA_BASE_URL=http://localhost:11434/v1
OLLAMA_API_KEY=ollama
OLLAMA_MODEL=llama3
OLLAMA_CLOUD_MODEL=gpt-oss:120b-cloud

Then sign your Ollama daemon into Ollama Cloud once:

ollama signin

2. Add Books

Option A: Upload via Web Interface (Recommended)

1. Start server: uv run server.py
2. Open http://127.0.0.1:8123
3. Click the "+" card OR drag & drop EPUB file
4. Wait for automatic processing

Option B: Command Line

uv run reader3.py your_book.epub

3. Start Server

uv run server.py

The server listens on 0.0.0.0:8123 by default so other devices on your LAN can reach it. You can override that with:

READER_HOST=0.0.0.0 READER_PORT=8123 uv run server.py

4. Read and Analyze

1. Open http://127.0.0.1:8123
2. Select a book
3. Right-click on text → Choose analysis type
4. Review AI response in side panel
5. Save if important
6. Highlights appear on next visit!

Usage

AI Analysis

• Select text → Right-click → Choose:
  • 📋 Fact Check - Verify facts and get context
  • 💡 Discussion - Deep analysis and insights
  • 💬 Add Comment - Your personal notes (no AI)
• View response in right panel
• Click "Save" for important insights

Highlights

• Yellow - Fact checks
• Blue - Discussions
• Green - Your comments
• Hover to see type, click to view/edit
• All highlights are editable and deletable

View & Export Highlights

• Click ⋮ menu on any book → "View Highlights"
• See all your notes and analyses in one page
• Filter by type (Fact Check, Discussion, Comment)
• Export to markdown for AI processing
• Context length warnings for large exports
• Jump directly to any chapter

Keyboard Shortcuts

• ← → - Navigate between chapters
• ESC - Close panels and modals
• Works anywhere except when typing in text fields

Project Structure

reader3/
├── reader3.py          # EPUB processor
├── server.py           # Web server
├── database.py         # SQLite operations
├── ai_service.py       # AI integration
├── books/              # All book data here
│   └── book_name_data/
│       ├── book.pkl
│       └── images/
├── templates/          # HTML templates
├── reader_data.db      # SQLite database
└── .env                # API configuration

Data Management

View Your Highlights

• Click ⋮ menu on any book → "View Highlights"
• See all notes, comments, and analyses in one page
• Filter by type and jump to chapters

View Database (Advanced)

uv run check_database.py

Backup

# Double-click: backup.bat
# Or manually:
copy reader_data.db backups\reader_data_backup.db

Tools

• check_database.py - View raw database contents (advanced)
• backup.bat - Quick database backup

Why Ollama Cloud?

• ✅ Uses the same Ollama workflow as local models
• ✅ Lets you use larger hosted models without a local GPU
• ✅ Keeps one provider for both local and cloud modes
• ✅ Works through Ollama's OpenAI-compatible endpoint

Troubleshooting

API Key Error

1. Check .env file exists and has correct key
2. Restart server

No Highlights Showing

1. Check browser console (F12) for errors
2. Verify data exists: uv run check_database.py
3. Hard refresh (Ctrl+Shift+R)

Server Won't Start

1. Check if port 8123 is available
2. Verify .env configuration

Run At Startup On Linux

This repo includes a systemd unit template and installer so the app can start on boot. The installed service runs the app with uv run server.py, matching the normal development command.

1. Install dependencies

uv sync

2. Install the systemd service

sudo ./scripts/install-systemd-service.sh

This installs deploy/reader3.service, enables it, and starts it immediately.

3. Check service status

systemctl status reader3.service

4. Open the port on the machine firewall if needed

If you use UFW:

sudo ufw allow 8123/tcp

Then browse to http://<your-linux-machine-ip>:8123 from another device on your home network.

5. Find the machine IP

hostname -I

License

MIT

---

Note: This project is designed to be simple and hackable. Ask your LLM to modify it however you like!