PDF-OCR CLI Tool

Overview

A powerful TypeScript CLI tool that transforms scanned PDFs into searchable documents by:

• Taking a PDF file input
• Processing each page with Mistral API's OCR capabilities
• Optionally verifying and improving text quality with Together.ai's free LLM
• Reassembling everything into a searchable PDF

Perfect for digitizing paper documents, making image-based PDFs searchable, and extracting text from scanned materials.

Quick Start

Prerequisites

• Node.js 14 or higher
• Mistral API key (sign up here)
• Together.ai API key for verification feature (sign up here)

Installation

# Install globally
npm install -g pdf-ocr-cli

# Or use without installing
npx pdf-ocr-cli --input input.pdf --output output.pdf

Set Up API Keys

Create a .env file in your working directory:

echo "MISTRAL_API_KEY=your_mistral_api_key_here" > .env
echo "TOGETHER_API_KEY=your_together_api_key_here" >> .env

Or set environment variables in your shell:

export MISTRAL_API_KEY=your_mistral_api_key_here
export TOGETHER_API_KEY=your_together_api_key_here

Basic Usage

# Process a PDF file
pdf-ocr --input input.pdf --output output.pdf

# With verification to improve OCR quality
pdf-ocr --input input.pdf --output output.pdf --verify

Common Use Cases

Process Large Documents Efficiently

# Process 3 pages at a time
pdf-ocr --input input.pdf --output output.pdf --concurrency 3

Handle Network Issues

# Increase retries and timeout for unstable connections
pdf-ocr --input input.pdf --output output.pdf --retries 5 --timeout 60000

Process Carefully with Detailed Logs

# Process one page at a time with longer pauses and verbose logging
pdf-ocr --input input.pdf --output output.pdf --concurrency 1 --sleep 10000 --verbose

Command Options

Basic Options

OCR Options

Verification Options

Advanced Installation

Install from Source

# Clone and build
git clone https://github.com/luandro/pdf-ocr.git
cd pdf-ocr
npm install
npm run build

# Set up environment
cp .env.example .env
# Edit .env with your API keys

Development

This project follows Test-Driven Development principles:

# Run tests with coverage
npm test

# Run tests in watch mode
npm run test:watch

# Build the project
npm run build

# Run in development mode
npm run dev -- --input input.pdf --output output.pdf

Test Coverage

The project maintains high test coverage (>80%) for quality assurance:

# Run tests with coverage
npm test

# View coverage report
open coverage/lcov-report/index.html

Continuous Integration

GitHub Actions automates testing and publishing:

• Tests run on every push to main
• Coverage reports are generated
• Automatic npm publishing when tests pass

Architecture

The application consists of these key modules:

1. PDF Splitter (src/splitPdf.ts): Divides PDFs into individual pages
2. OCR Module (src/ocr.ts): Extracts text using Mistral API
3. Content Verification (src/contentVerification.ts): Improves text with LLM
4. Text-to-PDF Converter (src/textToPdf.ts): Converts text back to PDF
5. PDF Merger (src/mergePdfs.ts): Combines processed pages
6. CLI (src/cli.ts): Provides the command interface

Processing Pipeline

1. Split input PDF into individual pages
2. Process each page sequentially:
   • Extract text with Mistral API OCR
   • Optionally verify/improve text with Together.ai
   • Convert text back to PDF format
3. Merge all processed pages into final PDF

Troubleshooting

• API Key Errors: Ensure your .env file contains valid API keys
• Network Issues: Try increasing --retries, --timeout, and --retry-delay
• Poor OCR Quality: Enable --verify to improve text with LLM
• Processing Large Files: Reduce --concurrency and increase --sleep
• Memory Issues: Process fewer pages at once with --max-pages

Contributing

Please see CONTRIBUTING.md for guidelines on contributing to this project.

License

This project is licensed under the ISC License - see the LICENSE file for details.