Installation

Complete setup guide for AI-Viewer

Prerequisites

System Requirements

Requirement	Minimum	Recommended
Python	3.10+	3.12+
Memory	2GB RAM	4GB+ RAM
Storage	500MB free	2GB+ free
Network	Internet for MathJax	Stable connection

Required Software

• Python 3.10+: Download from python.org

• Modern browser: Chrome, Firefox, Safari, or Edge

Installation

AI-Viewer is a static HTML application that requires only an HTTP server. No Python package installation is strictly necessary.

Method 1: Direct Use (Recommended)

Simply serve the project directory with any HTTP server:

# Navigate to project root
cd /path/to/2026project

# Start Python HTTP server
python -m http.server 4100

# Open browser
open http://localhost:4100/ai-viewer/viewer.html

Method 2: Package Installation

For Python integration and CLI tools:

# Navigate to ai-viewer
cd ai-viewer

# Install in development mode
pip install -e .

# Verify installation
python -c "from ai_viewer import quick_serve; print('OK')"

Method 3: Using uv (Fastest)

# Install uv if not present
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install ai-viewer
cd ai-viewer
uv pip install -e .

Verification

Test Static Viewer

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

# Open in browser
open http://localhost:4100/ai-viewer/viewer.html

You should see the home catalog with available documents.

Test with a Document

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

Project Structure

The viewer requires this directory structure:

2026project/              ← HTTP server runs from here
├── ai-viewer/
│   ├── viewer.html       ← Main viewer application
│   ├── docs/             ← Documentation
│   └── config/           ← Configuration files
├── pdai/
│   ├── index.json        ← Document catalog
│   ├── E57/
│   │   └── pages/        ← Page-centric structure
│   │       └── page_000/
│   └── Goldbach/
└── ai-scholar/           ← Processing package

Key Files

File	Purpose
ai-viewer/viewer.html	Main viewer application
pdai/index.json	Document catalog
pdai/{doc}/manifest.json	Document metadata
pdai/{doc}/pages/	Page content

Configuration

Default Settings

AI-Viewer works with sensible defaults:

Setting	Default
Server Port	4100
Theme	Dark
Math Renderer	MathJax (CDN)

Document Catalog

Create or update pdai/index.json:

{
  "documents": [
    {
      "name": "E57",
      "title": "Euler E57 - Tidal Theory",
      "path": "E57",
      "page_count": 107
    },
    {
      "name": "Goldbach",
      "title": "Euler-Goldbach Correspondence",
      "path": "Goldbach",
      "page_count": 483
    }
  ]
}

Alternative HTTP Servers

Node.js

npx serve -p 4100
# or
npx http-server -p 4100

PHP

php -S localhost:4100

nginx

server {
    listen 4100;
    root /path/to/2026project;
    
    location / {
        try_files $uri $uri/ =404;
    }
}

Troubleshooting

Port Already in Use

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

# Use different port
python -m http.server 4101

404 Errors

Ensure the server is running from the project root:

# Wrong - from inside ai-viewer
cd ai-viewer
python -m http.server 4100  # ❌

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

Math Not Rendering

MathJax loads from CDN. Ensure:

• Internet connection is available
• Browser allows external scripts
• No ad blockers interfering

CORS Errors

If accessing from different origin:

# Use CORS-enabled server
npx http-server -p 4100 --cors

Docker Deployment

FROM python:3.12-slim
WORKDIR /app
COPY . .
EXPOSE 4100
CMD ["python", "-m", "http.server", "4100"]

# Build and run
docker build -t ai-viewer .
docker run -p 4100:4100 -v $(pwd):/app ai-viewer

Next Steps

1. Quick Start — View your first document

2. CLI Reference — Server setup options

3. Features — Viewer capabilities

4. PDAI Standard — Document format specification