pdfalive 0.17.0

A Python library and CLI toolkit that brings PDF files alive with the power of LLMs.

Highlights

Installation

Tesseract is required for OCR functionality. On macOS:

brew install tesseract

Install pdfalive via pip:

pip install pdfalive

Or run directly without installation using uvx:

uvx pdfalive generate-toc input.pdf output.pdf

Usage

Use --help on any command for detailed options:

pdfalive --help
pdfalive generate-toc --help

generate-toc

Generate a clickable Table of Contents using PDF bookmarks. The tool extracts font and text features from the PDF and uses an LLM to intelligently identify chapter and section headings.

pdfalive generate-toc input.pdf output.pdf

# Or modify the file in place
pdfalive generate-toc --inplace input.pdf

Choosing an LLM:

By default, pdfalive uses the latest OpenAI model. Use any LangChain-supported model:

# Use Claude
pdfalive generate-toc --model-identifier 'claude-sonnet-5' input.pdf output.pdf

# Use a local model via Ollama
pdfalive generate-toc --model-identifier 'ollama/llama3' input.pdf output.pdf

Set the appropriate API key for your provider (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.).

Reasoning effort:

Models that expose a reasoning-effort control accept it via --reasoning-effort, which is optional — leave it out and each provider keeps its own default:

# Spend less on reasoning for a straightforward document
pdfalive generate-toc --reasoning-effort low input.pdf output.pdf

# Spend more on a dense or badly structured one
pdfalive generate-toc --reasoning-effort xhigh input.pdf output.pdf

The accepted levels vary by model, not just by provider: gpt-6-sol and gpt-6-luna take none, low, medium, high and xhigh, gpt-6-astra takes the same minus none, and Anthropic models additionally offer max. pdfalive passes the value through rather than validating it, so a model that rejects a level answers with an error naming the levels it does accept. Providers with no such control, such as Ollama, ignore the setting.

Scanned PDFs:

OCR is enabled by default. Scanned documents without extractable text are automatically detected and processed:

# Default: OCR text layer discarded after TOC generation (preserves file size)
pdfalive generate-toc scanned.pdf output.pdf

# Include OCR text layer in output (makes PDF searchable)
pdfalive generate-toc --ocr-output scanned.pdf output.pdf

# Disable automatic OCR entirely
pdfalive generate-toc --no-ocr input.pdf output.pdf

Postprocessing:

For documents with a printed table of contents page, enable LLM postprocessing to refine results:

pdfalive generate-toc --postprocess input.pdf output.pdf

Postprocessing uses an additional LLM call to:

• Remove duplicate entries and fix typos
• Cross-reference against any printed TOC found in the document
• Add missing entries and correct page numbers

Other options:

extract-text

Extract text from scanned PDFs using OCR and save to a new PDF with an embedded text layer:

pdfalive extract-text input.pdf output.pdf

# Or modify the file in place
pdfalive extract-text --inplace input.pdf

This creates a searchable/selectable PDF without generating a TOC.

Options:

rename

Intelligently rename files using LLM inference. Analyzes filenames and applies renaming rules based on natural language instructions.

pdfalive rename -q "Add 'REVIEWED_' prefix" *.pdf

Custom naming formats:

Specify exact formatting including special characters — the LLM respects brackets, parentheses, dashes, and other formatting:

pdfalive rename -q "[Author Last Name] - Title (Year).pdf" paper1.pdf paper2.pdf

Reading paths from a file:

When dealing with many files or long filenames that exceed command-line limits, use the -f/--input-file option to read paths from a text file (one per line):

# Generate a list of files to rename
find /path/to/docs -name "*.pdf" > files.txt

# Rename using the file list
pdfalive rename -q "Standardize filenames" -f files.txt

The input file supports comments (lines starting with #) and blank lines are ignored.

Workflow:

1. The tool analyzes each filename and generates rename suggestions
2. A preview table shows original names, proposed names, confidence scores, and reasoning
3. Confirm or cancel the operation (unless -y is used)
4. Files are renamed in place

Automatic confirmation:

pdfalive rename -q "Add sequential numbering prefix" -y *.pdf

Options:

Configuration

pdfalive supports TOML configuration files for setting default options. This is useful for frequently-used settings like the --query argument for rename.

Config file locations (searched in order):

1. pdfalive.toml or .pdfalive.toml in the current directory
2. pdfalive.toml or .pdfalive.toml in your home directory
3. ~/.config/pdfalive/pdfalive.toml

Example pdfalive.toml:

# Global settings (shared across commands)
[global]
model-identifier = "gpt-5.6"
reasoning-effort = "medium"   # optional; omit to use the provider's default
show-token-usage = true

# Settings for generate-toc command
[generate-toc]
force = false
request-delay = 10.0
ocr = true
ocr-language = "eng"
ocr-dpi = 300
postprocess = false

# Settings for extract-text command
[extract-text]
ocr-language = "eng"
ocr-dpi = 300
force = false

# Settings for rename command
[rename]
query = "Rename to \"[Author Last Name] Book Title, Edition (Year).pdf\""
yes = false

# Settings for eval command (development tool)
[eval]
evals-dir = "evals"
mode = "replay"

Using a specific config file:

pdfalive --config /path/to/config.toml rename document.pdf

Override hierarchy:

1. Code defaults (lowest priority)
2. Config file values
3. CLI arguments (highest priority)

CLI arguments always override config file settings.

Development

We use uv to manage the project:

# Install dependencies
uv sync

# Install in editable mode
uv pip install -e .

Code quality tools:

# Run linting
uv run ruff check .
uv run ruff format .

# Run type checking
uv run mypy pdfalive

# Run tests
uv run pytest

Evaluation harness:

TOC generation quality is measured against golden (ground truth) data with the pdfalive eval command. LLM responses are recorded once to a cassette (VCR-style), then replayed for free, deterministic evaluation runs:

# One-time: record LLM responses for a case
pdfalive eval --mode record --case geometry

# Iterate on heuristics/corrections and re-measure without LLM costs
pdfalive eval --mode replay

# Gate regressions in CI
pdfalive eval --mode replay --min-f1 0.9 --min-page-accuracy 0.9

Reported metrics include title precision/recall/F1 (fuzzy-matched), page accuracy (exact and ±1), and hierarchy level accuracy. See docs/usage.md for the golden file format and how to add cases.

License

pdfalive is distributed under the terms of the MIT License.