Quick Start

Get viewing documents in minutes

Overview

This guide covers starting the viewer and integrating with AI-Scholar. You’ll be viewing AI-processed documents within minutes.

Starting the Viewer

The AI-Viewer is a static HTML application that runs via any HTTP server. The simplest approach uses Python’s built-in server.

Step 1: Start the Server

# Navigate to project root (parent of ai-viewer and pdai)
cd /path/to/2026project

# Start HTTP server on port 4100
python -m http.server 4100
Important

Important: The server must run from the project root, not from inside ai-viewer or pdai. This ensures both the viewer and document data are accessible.

Step 2: Open Your Browser

Navigate to: http://localhost:4100/ai-viewer/viewer.html

You’ll see the home catalog with all available documents from pdai/index.json.

Step 3: View a Document

Click “View” on any document, or navigate directly:

http://localhost:4100/ai-viewer/viewer.html?doc=pdai/E57
http://localhost:4100/ai-viewer/viewer.html?doc=pdai/Goldbach&page=10

Step 4: Navigate the Document

Use keyboard shortcuts:

Key Action
← Previous page
→ Next page
↑ Zoom in
↓ Zoom out
D Document mode (dual pane)
A Agent mode (three pane)
H Toggle navigation bar
F Toggle fullscreen

Complete Workflow with AI-Scholar

AI-Viewer displays documents processed by AI-Scholar. Here’s the complete workflow:

1. Process the PDF

# OCR processing - creates pages/page_NNN/ structure
ai-scholar process ../pdai/E57/E57.pdf --model gemini-3-flash-preview

2. Run Segmentation

# Identify logical structure - creates manifest.json
ai-scholar segment ../pdai/E57

3. Add Translations (Optional)

# Translate to English - creates pages/page_NNN/page_NNN_translation_english.xml
ai-scholar agent ../pdai/E57 translation-english --pages 0-50

4. View the Result

# Start server from project root
cd /path/to/2026project
python -m http.server 4100

# Open browser
open "http://localhost:4100/ai-viewer/viewer.html?doc=pdai/E57"

Document Structure

After processing, your document has this page-centric structure:

pdai/DocumentName/
├── DocumentName.pdf              # Original PDF
├── manifest.json                 # Segment mappings
├── ai-orchestrator.yml           # Agent configuration
├── css/                          # Display styles
├── templates/                    # Document templates
├── pages/                        # ALL page-level content
│   ├── page_000/                 # Folder per page
│   │   ├── page_000.png          # Page image
│   │   ├── page_000.xml          # OCR XML
│   │   ├── page_000.html         # HTML conversion
│   │   ├── page_000_translation_english.xml  # Agent output
│   │   └── page_000_fig_1.png    # Extracted figure
│   ├── page_001/
│   │   └── ...
│   └── ...
└── segments/                     # Document segments (optional)
    └── letters/
        ├── letter_000/
        └── letter_001/

Viewing Modes

Document Mode (Press D)

Dual-pane view for reading:

  • Left pane: High-resolution page image
  • Right pane: OCR text or translation

Use the language dropdown to switch between:

  • Original → pages/page_NNN/page_NNN.html
  • Deutsch → pages/page_NNN/page_NNN_translation_german.xml
  • English → pages/page_NNN/page_NNN_translation_english.xml

Agent Mode (Press A)

Three-pane view for agent work:

  • Left pane: Source input (image or XML)
  • Middle pane: Agent output
  • Right pane: Agent navigator and controls

Select an agent from the navigator to view its output. Click “Brew Agent” to generate new translations.

Segment Navigation

If the document has segments defined in manifest.json:

  1. Select segment type from the dropdown (letters, chapters, paragraphs)

  2. Choose a segment to jump to its start page

  3. View metadata for the selected segment

Example: Letter Edition

open "http://localhost:4100/ai-viewer/viewer.html?doc=pdai/Goldbach"

The segment dropdown shows letters. Selecting “Letter 42” jumps to its first page and displays metadata (sender, recipient, date).

Example: Scholarly Treatise

open "http://localhost:4100/ai-viewer/viewer.html?doc=pdai/E57"

Navigate by chapter or paragraph number. Mathematical formulas render with MathJax.

URL Parameters

Parameter Description Example
doc Document path doc=pdai/E57
page Starting page (0-indexed) page=5
mode View mode mode=agent
lang Language lang=english

Full example:

http://localhost:4100/ai-viewer/viewer.html?doc=pdai/E57&page=10&mode=agent

Troubleshooting

Document Won’t Load

# Check document exists
ls -la ../pdai/DocumentName/

# Verify structure
ls ../pdai/DocumentName/pages/page_000/

Missing Pages

# Check page count
ls ../pdai/DocumentName/pages/ | wc -l

# Verify page content
ls ../pdai/DocumentName/pages/page_000/

Math Not Rendering

The viewer loads MathJax from CDN. Ensure:

  • Internet connection is available

  • Browser allows external scripts

  • No ad blockers interfering

Port Already in Use

# Check what's using the port
lsof -i :4100

# Use different port
python -m http.server 4101

Server 404 Errors

Ensure the server is running from the project root:

# Wrong - from ai-viewer
cd ai-viewer
python -m http.server 4100  # ❌ pdai not accessible

# Correct - from project root
cd /path/to/2026project
python -m http.server 4100  # ✓ both ai-viewer and pdai accessible

Next Steps