### Install olmOCR with Benchmark Suite

Source: https://github.com/allenai/olmocr/blob/main/README.md

Install olmOCR with the dependencies required for running the benchmark suite.

```bash
pip install olmocr[bench]
```

--------------------------------

### Install System Dependencies (Ubuntu/Debian)

Source: https://github.com/allenai/olmocr/blob/main/README.md

Installs necessary system packages like poppler-utils and fonts for PDF rendering. Run this on Ubuntu/Debian-based systems.

```bash
sudo apt-get update
sudo apt-get install poppler-utils ttf-mscorefonts-installer msttcorefonts fonts-crosextra-caladea fonts-crosextra-carlito gsfonts lcdf-typetools
```

--------------------------------

### Launch Training Job

Source: https://github.com/allenai/olmocr/blob/main/olmocr/train/README.md

Use this command to start the training process for OLMOCR models. Specify the configuration file for training parameters.

```bash
python -m olmocr.train.train --config olmocr/train/configs/v0.4.0/qwen25_vl_olmocrv4_rotation_1epoch_mix_1025_filtered.yaml
```

--------------------------------

### Install olmocr from source

Source: https://github.com/allenai/olmocr/blob/main/docs/source/installation.md

After cloning the repository, use this command to install olmocr in editable mode.

```bash
pip install -e .
```

--------------------------------

### Install Training Dependencies

Source: https://github.com/allenai/olmocr/blob/main/olmocr/train/README.md

Installs the olmOCR package with training extras and specific versions of transformers and flash-attn. Ensure your environment is set up before running.

```bash
pip install .[train]
pip install transformers==4.52.4
pip install flash-attn>=2.8.0.post2 --no-build-isolation
```

--------------------------------

### Install olmOCR with Beaker Support

Source: https://github.com/allenai/olmocr/blob/main/README.md

Install olmOCR with the necessary dependencies for submitting jobs to Beaker clusters.

```bash
pip install olmocr[beaker]
```

--------------------------------

### Install Project in Editable Mode

Source: https://github.com/allenai/olmocr/blob/main/docs/source/CONTRIBUTING.md

Install the project in editable mode with development dependencies. This allows changes in your local clone to be immediately reflected.

```bash
pip install -U pip setuptools wheel
```

```bash
pip install -e .[dev]
```

--------------------------------

### Install FlashInfer for GPU Acceleration

Source: https://github.com/allenai/olmocr/blob/main/README.md

Install the FlashInfer library for faster inference on GPU. Ensure your PyTorch version and CUDA version match the wheel.

```bash
pip install https://download.pytorch.org/whl/cu128/flashinfer/flashinfer_python-0.2.5%2Bcu128torch2.7-cp38-abi3-linux_x86_64.whl
```

--------------------------------

### Launch vLLM Inference Server

Source: https://github.com/allenai/olmocr/blob/main/README.md

Example command to launch a vLLM inference server with a specified model and maximum model length. This server can then be used by olmOCR.

```bash
vllm serve allenai/olmOCR-2-7B-1025-FP8 --max-model-len 16384
```

--------------------------------

### Install olmOCR and Benchmark Requirements

Source: https://github.com/allenai/olmocr/blob/main/olmocr/bench/README.md

Installs olmOCR and its dependencies for running the benchmark, including configuring Playwright for headless browser operations.

```bash
conda create -n olmocr python=3.11
conda activate olmocr

git clone https://github.com/allenai/olmocr.git
cd olmocr

# Install olmocr and the requirements needed to run the benchmark
pip install -e .[bench]

# Configure playwright headless browser to run the math rendering tests
playwright install chromium

# Now clone the benchmark data from hugging face, this includes the PDFs and JSON annotation data
huggingface-cli download --repo-type dataset --resume-download allenai/olmOCR-bench --local-dir ./olmOCR-bench
```

--------------------------------

### Install olmocr with pip

Source: https://github.com/allenai/olmocr/blob/main/docs/source/installation.md

Use this command to install the latest version of olmocr from PyPI.

```bash
pip install olmocr
```

--------------------------------

### Build VLM Prompts

Source: https://context7.com/allenai/olmocr/llms.txt

Provides examples for constructing prompts for Vision-Language Models (VLMs), including production prompts, fine-tuning prompts with anchor text, and prompts for silver data generation.

```python
from olmocr.prompts import (
    build_no_anchoring_v4_yaml_prompt,
    build_finetuning_prompt,
    PageResponse,
    openai_response_format_schema,
)
from olmocr.prompts.prompts import build_openai_silver_data_prompt

# Production prompt (no anchor text, YAML frontmatter output)
prompt = build_no_anchoring_v4_yaml_prompt()
print(prompt)
```

```python
# Prompt with anchor text for fine-tuning
anchor_text = "[72x720]Title\n[72x680]First paragraph..."
prompt_with_anchor = build_finetuning_prompt(anchor_text)
```

```python
# Silver data generation prompt for GPT-4o
silver_prompt = build_openai_silver_data_prompt(anchor_text)
```

```python
# Get OpenAI structured output schema
schema = openai_response_format_schema()
print(schema["json_schema"]["schema"]["properties"].keys())
```

```python
# PageResponse dataclass for parsing model output
response = PageResponse(
    primary_language="en",
    is_rotation_valid=True,
    rotation_correction=0,  # Must be 0, 90, 180, or 270
    is_table=False,
    is_diagram=False,
    natural_text="# Document Title\n\nThis is the extracted text..."
)
print(f"Language: {response.primary_language}, Has table: {response.is_table}")
```

--------------------------------

### Install olmocr with GPU support

Source: https://context7.com/allenai/olmocr/llms.txt

Install the olmocr package with GPU support. Ensure your PyTorch installation matches your CUDA version.

```bash
pip install olmocr[gpu] --extra-index-url https://download.pytorch.org/whl/cu128
```

--------------------------------

### Combined Installation: GPU and Benchmark Support

Source: https://github.com/allenai/olmocr/blob/main/README.md

Install olmOCR with both GPU acceleration and benchmark suite support. Requires specifying the extra index URL for PyTorch wheels.

```bash
pip install olmocr[gpu,bench] --extra-index-url https://download.pytorch.org/whl/cu128
```

--------------------------------

### Combined Installation: GPU and Beaker Support

Source: https://github.com/allenai/olmocr/blob/main/README.md

Install olmOCR with both GPU acceleration and Beaker cluster support. Requires specifying the extra index URL for PyTorch wheels.

```bash
pip install olmocr[gpu,beaker] --extra-index-url https://download.pytorch.org/whl/cu128
```

--------------------------------

### Generate Silver Training Data (CLI)

Source: https://context7.com/allenai/olmocr/llms.txt

Command-line usage for generating silver training data using GPT-4o. Examples cover generating data from local PDFs, S3 buckets, and file lists, outputting JSONL files for OpenAI Batch API.

```bash
# From local PDFs
python -m olmocr.data.buildsilver \
  --glob_path "documents/*.pdf" \
  --num_sample_docs 1000 \
  --first_n_pages 3 \
  --max_sample_pages 10 \
  --output openai_batch_requests
```

```bash
# From S3 bucket
python -m olmocr.data.buildsilver \
  --glob_path "s3://my-bucket/pdfs/*.pdf" \
  --num_sample_docs 5000 \
  --output openai_batch_requests
```

```bash
# From file list
python -m olmocr.data.buildsilver \
  --path_list pdf_paths.txt \
  --no_filter \
  --output openai_batch_requests
```

--------------------------------

### Interactive Docker mode for debugging

Source: https://context7.com/allenai/olmocr/llms.txt

Starts an interactive Docker session with GPU support, allowing for direct debugging and command execution within the container.

```bash
docker run -it --gpus all alleninstituteforai/olmocr:latest-with-model
```

--------------------------------

### GRPO Training (Multi-GPU)

Source: https://github.com/allenai/olmocr/blob/main/olmocr/train/README.md

Initiate GRPO-based reinforcement learning training on an 8xH100 GPU node. This script is specialized for a specific cluster setup.

```bash
./scripts/train/grpotrainer-beaker-multi-gpu-augusta.sh --num-gpus 8      --model_name s3://ai2-oe-data/jakep/olmocr/qwen2.5-vl-7b-olmocrv4_1epoch_promptv4_mix1025_more_rotation-8372 --train_bench_data_folder /data/jakep/grpo_data_mixes/olmocr-synthmix-1025-v2-rotate10p/bench_data --reward_bench 1.0 --reward_front_matter 1.0 --reward_eos 1.0 --beta 0.01 --name promptv4_mix1025_more_rotation_multigpu_v1_beta_01_lr2e-6_frontmatter1_0_eos_28gen_synthmix-1025_rotate10p_finalrun1 --seed 1 --gradient_accumulation_steps 28 --learning_rate 2e-6 --preemptible
```

```bash
./scripts/train/grpotrainer-beaker-multi-gpu-augusta.sh --num-gpus 8      --model_name s3://ai2-oe-data/jakep/olmocr/qwen2.5-vl-7b-olmocrv4_1epoch_promptv4_mix1025_more_rotation-8372 --train_bench_data_folder /data/jakep/grpo_data_mixes/olmocr-synthmix-1025-v2-rotate10p/bench_data --reward_bench 1.0 --reward_front_matter 1.0 --reward_eos 1.0 --beta 0.01 --name promptv4_mix1025_more_rotation_multigpu_v1_beta_01_lr2e-6_frontmatter1_0_eos_28gen_synthmix-1025_rotate10p_importanceseq_finalrun1 --seed 1 --importance_sampling_level sequence --gradient_accumulation_steps 28 --learning_rate 2e-6 --preemptible
```

--------------------------------

### Clone olmocr repository

Source: https://github.com/allenai/olmocr/blob/main/docs/source/installation.md

Clone the olmocr repository from GitHub to install from source.

```bash
git clone https://github.com/allenai/olmocr.git
cd olmocr
```

--------------------------------

### Example Markdown Dataset Format

Source: https://github.com/allenai/olmocr/blob/main/olmocr/train/README.md

Illustrates the required markdown format for training data, including YAML front matter and document text. Each PDF must be a single page.

```markdown
---
primary_language: en
is_rotation_valid: True
rotation_correction: 0
is_table: False
is_diagram: False
---
Document text goes here...
```

--------------------------------

### Use remote inference server

Source: https://context7.com/allenai/olmocr/llms.txt

Utilizes a remote inference server for document conversion, requiring only a lightweight olmocr installation without a local GPU. Specify the server URL and model.

```bash
pip install olmocr
olmocr ./localworkspace \
  --server http://remote-server:8000/v1 \
  --model allenai/olmOCR-2-7B-1025-FP8 \
  --markdown \
  --pdfs *.pdf
```

--------------------------------

### Create and Activate Conda Environment

Source: https://github.com/allenai/olmocr/blob/main/README.md

Sets up a dedicated Python 3.11 environment named 'olmocr' using Conda. It is recommended to use a clean environment for olmOCR installation.

```bash
conda create -n olmocr python=3.11
conda activate olmocr
```

--------------------------------

### Initialize and Render PDF with PDF.js

Source: https://github.com/allenai/olmocr/blob/main/olmocr/bench/templates/review_latex.html

Sets up PDF.js worker source, loads a PDF, and renders the first page. Ensure the PDF path is correctly provided.

```javascript
pdfjsLib.GlobalWorkerOptions.workerSrc = 'https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.4.120/pdf.worker.min.js';
let currentScale = 2.0;
let pdfDoc = null;
let pageNum = 1;
let canvas = null;
const loadingTask = pdfjsLib.getDocument('{{ pdf_path }}');
loadingTask.promise.then(function(pdf) {
  pdfDoc = pdf;
  renderPage(pageNum);
});
```

--------------------------------

### Run Training with Beaker

Source: https://github.com/allenai/olmocr/blob/main/olmocr/train/README.md

This script initiates model training using the Beaker platform. It requires a configuration file to specify training parameters and settings.

```bash
scripts/train/newtrainer-beaker.sh --config [config file]
```

--------------------------------

### Build API Documentation

Source: https://github.com/allenai/olmocr/blob/main/docs/source/CONTRIBUTING.md

Generate the project's API documentation using `make docs`. This command checks for formatting issues in docstrings.

```bash
make docs
```

--------------------------------

### Convert a Single PDF to Markdown (Local GPU)

Source: https://github.com/allenai/olmocr/blob/main/README.md

Download a sample PDF and then use the olmocr command-line tool to convert it to markdown format, storing results in a local workspace. Assumes local GPU is available.

```bash
curl -o olmocr-sample.pdf https://olmocr.allenai.org/papers/olmocr_3pg_sample.pdf
```

```bash
olmocr ./localworkspace --markdown --pdfs olmocr-sample.pdf
```

--------------------------------

### Run Code Formatters

Source: https://github.com/allenai/olmocr/blob/main/docs/source/CONTRIBUTING.md

Run 'isort' and 'black' from the root of your clone to ensure code is formatted consistently.

```bash
isort .
```

```bash
black .
```

--------------------------------

### Run SFT Training

Source: https://context7.com/allenai/olmocr/llms.txt

Execute Supervised Fine-Tuning (SFT) for olmOCR models using a specified configuration file. Training involves loading the model, processing data, saving checkpoints, and logging metrics.

```bash
# Run SFT training
python -m olmocr.train.train --config olmocr/train/configs/example_config.yaml

# Training will:
# - Load Qwen2.5-VL model
# - Process PDF images with markdown targets
# - Save checkpoints to output_dir/run_name/
# - Log metrics to wandb
```

--------------------------------

### Preview Benchmark Questions with Review App

Source: https://github.com/allenai/olmocr/blob/main/olmocr/bench/README.md

Launch the OLMOCR benchmark review application to preview and edit benchmark questions. Specify the port, debug mode, and the JSONL file containing the questions. The --force flag can be used to overwrite existing data.

```bash
python -m olmocr.bench.review_app --port 5000 --debug ./olmOCR-bench/bench_data/multi_column.jsonl --force
```

--------------------------------

### Multi-node distributed processing with S3

Source: https://context7.com/allenai/olmocr/llms.txt

Configures olmocr for distributed processing across multiple nodes using AWS S3 for coordination. This setup is for large-scale processing.

```bash
olmocr s3://my_bucket/workspace --pdfs s3://my_bucket/pdfs/*.pdf
# On additional worker nodes:
olmocr s3://my_bucket/workspace
```

--------------------------------

### Create and Activate Python Virtual Environment

Source: https://github.com/allenai/olmocr/blob/main/docs/source/CONTRIBUTING.md

Create and activate a Python 3 virtual environment named 'olmocr' with Python 3.9.

```bash
conda create -n olmocr python=3.9
```

```bash
conda activate olmocr
```

--------------------------------

### Initialize and Use PdfFilter

Source: https://context7.com/allenai/olmocr/llms.txt

Shows how to initialize the PdfFilter to keep only English documents, remove forms, and filter out SEO spam. It demonstrates checking a single PDF and processing a batch.

```python
from olmocr.filter.filter import PdfFilter, Language

# Initialize filter with default settings
pdf_filter = PdfFilter(
    languages_to_keep={Language.ENGLISH, None},  # None = undetectable language (keep for OCR)
    apply_form_check=True,          # Filter out fillable forms
    apply_download_spam_check=True, # Filter SEO spam PDFs
    download_spam_threshold=0.004   # Spam word frequency threshold
)

# Check if PDF should be filtered out
pdf_path = "document.pdf"
should_filter = pdf_filter.filter_out_pdf(pdf_path)

if should_filter:
    print("PDF filtered out (form, spam, or non-English)")
else:
    print("PDF passes filters - process it")
```

```python
import glob
from concurrent.futures import ProcessPoolExecutor

pdf_paths = glob.glob("documents/*.pdf")
keep_paths = []
filter_paths = []

for pdf_path in pdf_paths:
    if pdf_filter.filter_out_pdf(pdf_path):
        filter_paths.append(pdf_path)
    else:
        keep_paths.append(pdf_path)

print(f"Keeping {len(keep_paths)} PDFs, filtering {len(filter_paths)}")
```

--------------------------------

### Load and Render Initial PDF

Source: https://github.com/allenai/olmocr/blob/main/olmocr/bench/templates/review.html

Loads the PDF document from the specified path using `pdfjsLib.getDocument`. It then sets the total page count and renders the first page. Includes error handling for loading failures.

```javascript
// Load PDF
loadingIndicator.style.display = 'block';
pdfjsLib.getDocument(pdfPath).promise.then(function(pdf) {
  pdfDoc = pdf;
  document.getElementById('page-count').textContent = pdf.numPages;
  // Initial page render
  renderPage(pageNum);
}).catch(function(error) {
  console.error('Error loading PDF:', error);
  loadingIndicator.style.display = 'none';
});
```

--------------------------------

### Start subsequent olmOCR worker nodes for S3 multi-node usage

Source: https://github.com/allenai/olmocr/blob/main/README.md

Adds additional worker nodes to an existing S3-based olmOCR processing cluster. These nodes automatically pick up tasks from the shared workspace queue.

```bash
olmocr s3://my_s3_bucket/pdfworkspaces/exampleworkspace
```

--------------------------------

### Initialize PDF.js and Rendering Variables

Source: https://github.com/allenai/olmocr/blob/main/olmocr/bench/templates/review.html

Sets up the PDF.js worker source and initializes essential variables for PDF rendering, including canvas context, scale, and rendering state.

```javascript
// Set up PDF.js worker
pdfjsLib.GlobalWorkerOptions.workerSrc = 'https://cdnjs.cloudflare.com/ajax/libs/pdf.js/3.11.174/pdf.worker.min.js';

// PDF rendering variables
let pdfDoc = null;
let pageNum = 1;
let pageRendering = false;
let pageNumPending = null;
let scale = 2.0; // Increased from 1.5 to 2.0 for better text alignment

const canvas = document.getElementById('pdf-canvas');
const container = document.getElementById('pdf-container');
const textLayer = document.getElementById('text-layer');
const ctx = canvas.getContext('2d');
const loadingIndicator = document.getElementById('loading-indicator');

// Device pixel ratio for HiDPI displays
const pixelRatio = window.devicePixelRatio || 1;

// Load PDF from the provided path
const pdfPath = '{{ pdf_path }}';
```

--------------------------------

### Start olmOCR worker node for S3 multi-node usage

Source: https://github.com/allenai/olmocr/blob/main/README.md

Initiates the first worker node for distributed PDF processing using AWS S3 for work queues and storage. This command sets up the workspace and begins conversion.

```bash
olmocr s3://my_s3_bucket/pdfworkspaces/exampleworkspace --pdfs s3://my_s3_bucket/jakep/gnarly_pdfs/*.pdf
```

--------------------------------

### Start Editing a Field

Source: https://github.com/allenai/olmocr/blob/main/olmocr/bench/templates/review.html

Initiates the editing process for a specific field when clicked. It handles both regular text fields and specialized math fields, converting them to textareas for editing and managing save operations on Enter key press or blur.

```javascript
function startEditField(element) {
  const field = element.dataset.field;
  const testId = element.dataset.id;

  // Special handling for math fields
  if (element.classList.contains('math-edit')) {
    const currentValue = element.innerText;
    // Create textarea
    const textarea = document.createElement('textarea');
    textarea.value = currentValue;
    textarea.dataset.field = field;
    textarea.dataset.originalValue = currentValue;
    // Replace the span with textarea
    element.parentNode.replaceChild(textarea, element);
    // Focus the textarea
    textarea.focus();

    // Function to save and exit edit mode
    function saveAndExit() {
      const newValue = textarea.value;
      const pdfName = '{{ pdf_name }}';
      // If value changed, save it
      if (newValue !== textarea.dataset.originalValue) {
        updateTestStatus(pdfName, testId, field, newValue);
      }
      // Create span again
      const span = document.createElement('span');
      span.className = 'editable math-edit';
      span.style.display = 'none';
      span.dataset.field = field;
      span.dataset.id = testId;
      span.innerText = newValue;
      // Replace textarea with span
      if (textarea.parentNode) {
        textarea.parentNode.replaceChild(span, textarea);
      }
      // Also update and render the math display element
      const mathDisplay = document.querySelector(`.math-display[data-id="${testId}"]`);
      if (mathDisplay) {
        mathDisplay.textContent = newValue;
        mathDisplay.style.display = 'inline-block';
        // Render math with KaTeX
        try {
          katex.render(newValue, mathDisplay, { displayMode: true, throwOnError: false });
        } catch (error) {
          console.error("KaTeX rendering error:", error);
          mathDisplay.textContent = newValue;
        }
      }
      // Important: Reset edit mode flag
      isEditMode = false;
    }

    // Add keydown event to handle Enter key
    textarea.addEventListener('keydown', function(e) {
      if (e.key === 'Enter' && !e.shiftKey) {
        e.preventDefault(); // Prevent default Enter behavior
        saveAndExit(); // Save directly rather than triggering blur
      }
    });

    // Add blur event to save changes
    textarea.addEventListener('blur', function() {
      saveAndExit();
    });
    return;
  }

  // Regular (non-math) field handling
  const currentValue = element.innerText;
  // Create textarea
  const textarea = document.createElement('textarea');
  textarea.value = currentValue
```

--------------------------------

### Download and Prepare olmOCR-mix-1025 Dataset

Source: https://github.com/allenai/olmocr/blob/main/olmocr/train/README.md

Downloads and prepares the olmOCR-mix-1025 dataset for training. Requires approximately 200GB of disk space. You can select specific subsets and splits.

```bash
# Caution, requires ~200GB of disk space

# You can pick a specific split and subset to download, or just run all these commands in order to get everything
python -m olmocr.data.prepare_olmocrmix --dataset-path allenai/olmOCR-mix-1025 --destination ~/olmOCR-mix-1025-extracted --subset 00_documents --split train                       
python -m olmocr.data.prepare_olmocrmix --dataset-path allenai/olmOCR-mix-1025 --destination ~/olmOCR-mix-1025-extracted --subset 00_documents --split eval

python -m olmocr.data.prepare_olmocrmix --dataset-path allenai/olmOCR-mix-1025 --destination ~/olmOCR-mix-1025-extracted --subset 01_books --split train                       
python -m olmocr.data.prepare_olmocrmix --dataset-path allenai/olmOCR-mix-1025 --destination ~/olmOCR-mix-1025-extracted --subset 01_books --split eval

python -m olmocr.data.prepare_olmocrmix --dataset-path allenai/olmOCR-mix-1025 --destination ~/olmOCR-mix-1025-extracted --subset 02_loc_transcripts --split train                       
python -m olmocr.data.prepare_olmocrmix --dataset-path allenai/olmOCR-mix-1025 --destination ~/olmOCR-mix-1025-extracted --subset 02_loc_transcripts --split eval

python -m olmocr.data.prepare_olmocrmix --dataset-path allenai/olmOCR-mix-1025 --destination ~/olmOCR-mix-1025-extracted --subset 03_national_archives --split train                       
python -m olmocr.data.prepare_olmocrmix --dataset-path allenai/olmOCR-mix-1025 --destination ~/olmOCR-mix-1025-extracted --subset 03_national_archives --split eval
```

--------------------------------

### Compress Model Checkpoint to FP8

Source: https://github.com/allenai/olmocr/blob/main/olmocr/train/README.md

This script compresses a prepared model checkpoint to FP8 precision. It requires the path to a recipe, the input model, and the desired output path. Optional calibration PDFs can be provided.

```bash
scripts/train/compress_model.sh <recipe_path> <input_model_path> <output_model_path>[--calibration-pdfs PATTERN]
```

--------------------------------

### Prepare Local Workspace Data for Fine-tuning

Source: https://github.com/allenai/olmocr/blob/main/olmocr/train/README.md

Converts existing olmOCR workspace data into the format required for fine-tuning. This involves running olmOCR on local PDFs and then preparing the output.

```bash
python -m olmocr.pipeline ./localworkspace --pdfs /home/username/pdfs/*.pdf
python -m olmocr.data.prepare_workspace ./localworkspace ./localtrainingdata
```

--------------------------------

### Initialize OCR Interface and Event Listeners

Source: https://github.com/allenai/olmocr/blob/main/olmocr/bench/templates/review.html

Sets up the OCR interface on DOMContentLoaded. It initializes math rendering, sets up click handlers for math and editable fields, configures keyboard navigation for test items, and adds a global keyboard listener.

```javascript
document.addEventListener('DOMContentLoaded', function() {
  // Render all math on page load
  renderMath();

  // Set up math display fields - clicking on rendered math starts edit mode
  const mathDisplays = document.querySelectorAll('.math-display');
  mathDisplays.forEach(mathDisplay => {
    mathDisplay.onclick = function() {
      isEditMode = true;
      const testId = this.getAttribute('data-id');
      toggleMathEdit(testId);
    };
  });

  // Set up regular editable fields
  const editables = document.querySelectorAll('.editable:not(.math-edit)');
  editables.forEach(editable => {
    editable.onclick = function() {
      isEditMode = true;
      startEditField(this);
    };
  });

  // Get all test items for keyboard navigation
  testItems = Array.from(document.querySelectorAll('.test-item'));

  // Add click event listeners to test items
  testItems.forEach((item, index) => {
    item.addEventListener('click', function(e) {
      // Only handle clicks on the test item itself or its direct children
      // Ignore clicks on buttons, editable elements, and math displays
      if (e.target.tagName !== 'BUTTON' && !e.target.closest('.editable') && !e.target.closest('.math-display') && !e.target.classList.contains('kbd-shortcut')) {
        setCurrentTest(index);
        e.stopPropagation();
      }
    });
  });

  // Highlight first test
  if (testItems.length > 0) {
    highlightCurrentTest();
  }

  // Add keyboard event listener
  document.addEventListener('keydown', handleKeyboardShortcuts);

  // Flag to track if we're in edit mode
  const originalBlurHandlers = [];

  // Override blur handlers on textareas to reset edit mode flag
  const addEditModeReset = function(textarea) {
    const originalBlur = textarea.onblur;
    originalBlurHandlers.push(originalBlur);
    textarea.onblur = function(e) {
      isEditMode = false;
      if (originalBlur) originalBlur.call(this, e);
    };
  };

  // Show keyboard help initially
  toggleKeyboardHelp();
  setTimeout(function() {
    if (document.getElementById('keyboard-help').classList.contains('show')) {
      toggleKeyboardHelp();
    }
  }, 5000); // Hide after 5 seconds
});
```

--------------------------------

### Launch olmOCR cluster execution with Beaker

Source: https://github.com/allenai/olmocr/blob/main/README.md

Prepares the workspace locally and launches N GPU workers in a Beaker cluster for large-scale PDF linearization. Specify the number of GPUs to use.

```bash
olmocr s3://my_s3_bucket/pdfworkspaces/exampleworkspace --pdfs s3://my_s3_bucket/jakep/gnarly_pdfs/*.pdf --beaker --beaker_gpus 4
```

--------------------------------

### Run OLMOCR Benchmark

Source: https://github.com/allenai/olmocr/blob/main/olmocr/bench/README.md

Execute the OLMOCR benchmark using the specified directory containing benchmark data. Ensure the benchmark data is correctly formatted.

```bash
python -m olmocr.bench.benchmark --dir ./olmOCR-bench/bench_data
```

--------------------------------

### Run olmOCR-Bench Benchmark

Source: https://context7.com/allenai/olmocr/llms.txt

Execute the olmOCR-Bench benchmark suite to evaluate OCR system performance. This can be done on sample data, for specific candidates, or with options to generate reports and filter tests.

```bash
# Run benchmark on sample data
python -m olmocr.bench.benchmark --dir ./olmocr/bench/sample_data

# Run benchmark for specific candidate
python -m olmocr.bench.benchmark \
  --dir ./benchmark_data \
  --candidate olmocr_pipeline

# Generate HTML report
python -m olmocr.bench.benchmark \
  --dir ./benchmark_data \
  --test_report results.html \
  --max_reports 50

# Run subset of tests
python -m olmocr.bench.benchmark \
  --dir ./benchmark_data \
  --sample 100 \
  --skip_baseline

# Output failed tests for analysis
python -m olmocr.bench.benchmark \
  --dir ./benchmark_data \
  --output_failed failed_tests.jsonl

# Expected output:
# Candidate: olmocr_pipeline
#   Average Score: 82.4% (95% CI: [81.3%, 83.5%]) over 7234 tests.
#   Results by JSONL file:
#       arxiv.jsonl                   : 83.0% (1234/1487 tests)
#       tables.jsonl                  : 84.9% (567/668 tests)
#       old_scans.jsonl               : 47.7% (234/490 tests)
```

--------------------------------

### Configure SFT Model Training

Source: https://context7.com/allenai/olmocr/llms.txt

Configure Supervised Fine-Tuning (SFT) for olmOCR models using a YAML file. Specify model parameters, training settings, and dataset paths.

```yaml
# olmocr/train/configs/example_config.yaml
project_name: "olmocr-training"
run_name: "olmocr-v5-experiment"

model:
  name: "Qwen/Qwen2.5-VL-7B-Instruct"
  torch_dtype: "bfloat16"
  use_flash_attention: true
  attn_implementation: "flash_attention_2"
  use_lora: false  # Set true for LoRA training
  lora_rank: 64
  lora_alpha: 128

training:
  output_dir: "./outputs"
  num_train_epochs: 3
  per_device_train_batch_size: 1
  gradient_accumulation_steps: 8
  learning_rate: 2e-5
  warmup_ratio: 0.1
  weight_decay: 0.01
  seed: 42
  optim: "adamw_torch"  # or "muon" for Muon optimizer
  gradient_checkpointing: true
  save_steps: 500
  eval_steps: 500
  logging_steps: 10
  report_to: ["wandb"]

dataset:
  train:
    - root_dir: "s3://bucket/training_data"
      pipeline: "default"
  eval:
    - root_dir: "s3://bucket/eval_data"
      pipeline: "default"
      name: "validation"
```

--------------------------------

### Create and Push New Branch

Source: https://github.com/allenai/olmocr/blob/main/docs/source/CONTRIBUTING.md

Create a new branch for your contribution and push it to your fork's origin. Replace BRANCH with your desired branch name.

```bash
# replace BRANCH with whatever name you want to give it
git checkout -b BRANCH
```

```bash
git push -u origin BRANCH
```

--------------------------------

### Initialize UI Event Listeners

Source: https://github.com/allenai/olmocr/blob/main/scripts/eval/evalhtml_template.html

Sets up event listeners for various UI components when the DOM is fully loaded. Includes image preview toggling, reveal/diff toggles, text block selection, and voting button interactions.

```javascript
document.addEventListener('DOMContentLoaded', () => {
    fetchDataAndUpdatePage(); // Toggle the full-screen image preview
    const overlay = document.querySelector('.overlay');
    document.querySelectorAll('.image-container img').forEach(img => {
        img.addEventListener('click', () => {
            const entry = img.closest('.entry');
            entry.classList.toggle('full-screen');
            overlay.classList.toggle('active');
        });
    });
    overlay.addEventListener('click', () => {
        document.querySelectorAll('.full-screen').forEach(entry => {
            entry.classList.remove('full-screen');
        });
        overlay.classList.remove('active');
    });
    // Handle Reveal Gold/Eval Toggle
    document.getElementById('reveal-toggle').addEventListener('change', (e) => {
        document.body.classList.toggle('revealed', e.target.checked);
        updateReveal();
    });
    // Handle Diff Toggle
    document.getElementById('diff-toggle').addEventListener('change', (e) => {
        document.body.classList.toggle('diffed', e.target.checked);
        toggleDiff(e.target.checked);
    });
    // Handle text-block selections
    document.querySelectorAll('.text-block').forEach(block => {
        block.addEventListener('click', () => selectChoice(block));
    });
    // Handle voting buttons
    document.querySelectorAll('.voting-buttons button').forEach(button => {
        button.addEventListener('click', () => handleVote(button));
    });
});
```

--------------------------------

### Prepare Checkpoint for VLLM

Source: https://github.com/allenai/olmocr/blob/main/olmocr/train/README.md

Prepare saved checkpoints for use with VLLM. This script merges LoRA weights into a full model and adjusts configurations.

```bash
python -m olmocr.train.prepare_olmocr_checkpoint [source dir]/checkpoint-xxxx [destination]
```

--------------------------------

### Convert a single PDF to Markdown (local GPU)

Source: https://context7.com/allenai/olmocr/llms.txt

Converts a single PDF file to Markdown format using a local GPU. The output will be stored in the specified workspace directory.

```bash
curl -o sample.pdf https://olmocr.allenai.org/papers/olmocr_3pg_sample.pdf
olmocr ./localworkspace --markdown --pdfs sample.pdf
```

--------------------------------

### Convert Benchmark PDFs with OLMOCR Pipeline

Source: https://github.com/allenai/olmocr/blob/main/olmocr/bench/README.md

Use the OLMOCR pipeline to convert benchmark PDFs and format them. Specify the local workspace, markdown output, and input PDF directory.

```bash
python -m olmocr.pipeline ./localworkspace --markdown --pdfs ./olmOCR-bench/bench_data/pdfs/**/*.pdf
```

--------------------------------

### Download Synthetic Dataset

Source: https://github.com/allenai/olmocr/blob/main/olmocr/train/README.md

Download the synthetic dataset used for GRPO RL training. This dataset is in the olmOCR-bench format.

```bash
hf download allenai/olmOCR-synthmix-1025 --repo-type dataset --local-dir olmOCR-synthmix-1025
```

--------------------------------

### Use Remote Inference Server for Conversion

Source: https://github.com/allenai/olmocr/blob/main/README.md

Convert PDF files to markdown using a remote inference server. Specify the server URL, model name, and the PDF files to process.

```bash
olmocr ./localworkspace --server http://remote-server:8000/v1 --model allenai/olmOCR-2-7B-1025-FP8 --markdown --pdfs *.pdf
```

--------------------------------

### Prepare Checkpoint with olmocr.train.prepare_checkpoint

Source: https://github.com/allenai/olmocr/blob/main/olmocr/train/README.md

This command prepares a model checkpoint by consolidating multiple source checkpoints into a single destination. It is useful for merging distributed training results or preparing a model for further processing.

```bash
python -m olmocr.train.prepare_checkpoint s3://ai2-oe-data/jakep/olmocr-grpo-checkpoints/promptv4_mix1025_more_rotation_multigpu_v1_beta_01_lr2e-6_frontmatter1_0_eos_28gen_synthmix-1025_rotate10p_finalrun1-multigpu-01K60YDRKCJY82TKF0FP6WE4VA/checkpoint-306/ s3://ai2-oe-data/jakep/olmocr-grpo-checkpoints/promptv4_mix1025_more_rotation_multigpu_v1_beta_01_lr2e-6_frontmatter1_0_eos_28gen_synthmix-1025_rotate10p_finalrun2-multigpu-01K60YGB5Y2G15BG8CX4H1QW23/checkpoint-306/ s3://ai2-oe-data/jakep/olmocr-grpo-checkpoints/promptv4_mix1025_more_rotation_multigpu_v1_beta_01_lr2e-6_frontmatter1_0_eos_28gen_synthmix-1025_rotate10p_finalrun3-multigpu-01K60YGM2QEKJK9FC94JJG5YDP/checkpoint-306/ s3://ai2-oe-data/jakep/olmocr-grpo-checkpoints/promptv4_mix1025_more_rotation_multigpu_v1_beta_01_lr2e-6_frontmatter1_0_eos_28gen_synthmix-1025_rotate10p_importanceseq_finalrun3-multigpu-01K60YJBGC3AR7STTNH23BWH8A/checkpoint-306/ s3://ai2-oe-data/jakep/olmocr-grpo-checkpoints/promptv4_mix1025_more_rotation_multigpu_v1_beta_01_lr2e-6_frontmatter1_0_eos_28gen_synthmix-1025_rotate10p_importanceseq_finalrun2-multigpu-01K60YJ315K1GYCPN8VADTN7C3/checkpoint-306/ s3://ai2-oe-data/jakep/olmocr-grpo-checkpoints/promptv4_mix1025_more_rotation_multigpu_v1_beta_01_lr2e-6_frontmatter1_0_eos_28gen_synthmix-1025_rotate10p_importanceseq_finalrun1-multigpu-01K60YHSHCNS9RZWSF9E56J9FB/checkpoint-306/ s3://ai2-oe-data/jakep/olmocr-grpo-checkpoints/promptv4_mix1025_more_rotation_multigpu_v1_beta_01_lr2e-6_frontmatter1_0_eos_28gen_synthmix-1025_rotate10p_soupersoup
```

--------------------------------

### Prepare OLMOCR Checkpoint Interactively

Source: https://github.com/allenai/olmocr/blob/main/olmocr/train/README.md

This command prepares an OLMOCR model checkpoint from a specified source to a destination. It is typically used in interactive sessions for checkpoint management.

```bash
python -m olmocr.train.prepare_olmocr_checkpoint [source] [destination]
```

--------------------------------

### Generate Silver Training Data (Programmatic)

Source: https://context7.com/allenai/olmocr/llms.txt

Programmatic usage for generating a single page query for GPT-4o using the `buildsilver` module. This includes specifying local and remote PDF paths and the page number.

```python
# Programmatic usage
from olmocr.data.buildsilver import build_page_query, sample_pdf_pages
from olmocr.data.renderpdf import render_pdf_to_base64png

pdf_path = "document.pdf"
page = 1

# Build a single page query for GPT-4o
query = build_page_query(
    local_pdf_path=pdf_path,
    pretty_pdf_path="s3://bucket/document.pdf",  # Path for tracking
    page=page
)

print(query["custom_id"])
print(query["body"]["model"])
```

--------------------------------

### FP8 Quantization

Source: https://github.com/allenai/olmocr/blob/main/olmocr/train/README.md

Perform FP8 quantization on checkpoints for reduced memory usage and faster inference. This step is recommended after training.

```bash
python -m olmocr.train.compress_checkpoint --config olmocr/train/quantization_configs/qwen2_5vl_w8a8_fp8.yaml [destination] [destination-FP8]
```

--------------------------------

### Run Ruff Linter

Source: https://github.com/allenai/olmocr/blob/main/docs/source/CONTRIBUTING.md

Use `ruff` to check the codebase for linting errors. This command should be run from the root of the project.

```bash
ruff check .
```

--------------------------------

### Render Math with KaTeX

Source: https://github.com/allenai/olmocr/blob/main/olmocr/bench/templates/review.html

Renders mathematical expressions using KaTeX. It selects elements with the class 'math-display' and attempts to render them. Includes error handling for rendering failures.

```javascript
function renderMath() {
  const mathElements = document.querySelectorAll('.math-display');
  mathElements.forEach(elem => {
    try {
      katex.render(elem.textContent, elem, { displayMode: true, throwOnError: false });
    } catch (error) {
      console.error("KaTeX rendering error:", error);
      // If rendering fails, show the raw LaTeX
      elem.textContent = elem.textContent;
    }
  });
}
```

--------------------------------

### Configure Marked.js Options

Source: https://github.com/allenai/olmocr/blob/main/olmocr/viewer/dolmaviewer_merged_template.html

Sets up Marked.js for markdown parsing with specific options like breaks, GFM, and tables enabled. Header IDs and mangling are disabled.

```javascript
let isMarkdownView = true;
marked.setOptions({
  breaks: true,
  gfm: true,
  tables: true,
  headerIds: false,
  mangle: false
});
```

--------------------------------

### Run OLMOCR Benchmark

Source: https://github.com/allenai/olmocr/blob/main/olmocr/train/README.md

This script executes the OLMOCR benchmark test. It requires the path to the model checkpoint to be used for benchmarking.

```bash
scripts/run_benchmark.sh --model [destination]
```

--------------------------------

### Convert Documents for olmOCR-Bench

Source: https://github.com/allenai/olmocr/blob/main/olmocr/bench/README.md

Converts documents using the olmOCR pipeline, requiring the [gpu] subset of olmocr dependencies for GPU inference.

```bash
# You will need to install the [gpu] subset of olmocr dependencies to run gpu inference
# Then convert using using olmocr.bench.convert, see the olmocr/bench/runners directory for options
pip install olmocr[gpu] --find-links https://flashinfer.ai/whl/cu124/torch2.4/flashinfer/
python -m olmocr.bench.convert olmocr_pipeline --dir ./olmOCR-bench/bench_data
```

--------------------------------

### Convert multiple PDFs

Source: https://context7.com/allenai/olmocr/llms.txt

Converts multiple PDF files from a directory to Markdown format. Ensure the PDFs are in the specified directory.

```bash
olmocr ./localworkspace --markdown --pdfs documents/*.pdf
```

--------------------------------

### Select Text Block Choice

Source: https://github.com/allenai/olmocr/blob/main/scripts/eval/evalhtml_template.html

Handles the selection of a text block, updating the datastore and UI. Optionally saves the selection to the datastore.

```javascript
async function selectChoice(block, save = true) {
    let datastore = await fetchDatastore();
    const entry = block.closest('.entry');
    const entryKey = sanitizeKey(entry.getAttribute('data-entry-id'));
    const blocks = entry.querySelectorAll('.text-block');
    blocks.forEach(b => b.classList.remove('selected'));
    block.classList.add('selected');
    datastore[entryKey] = block.getAttribute('data-choice');
    const numVotes = Object.keys(datastore).length;
    document.getElementById("vote-info").innerText = `Total Votes: ${numVotes}`;
    if (save) {
        putDatastore(datastore); // Save entire datastore
    }
}
```

--------------------------------

### Reject All Tests and Next PDF Function

Source: https://github.com/allenai/olmocr/blob/main/olmocr/bench/templates/review.html

Sends a POST request to the '/reject_all' endpoint with the current PDF name. If successful, it programmatically clicks the button to navigate to the next PDF document.

```javascript
function rejectAllAndNextPdf() {
  fetch('/reject_all', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ pdf: '{{ pdf_name }}' }),
  })
  .then(response => response.json())
  .then(data => {
    if (data.status === 'success') {
      // Go to the next PDF
      document.querySelector('form[action="/next_pdf"] button').click();
    }
  })
  .catch(error => {
    console.error('Error rejecting all tests:', error);
  });
}
```

--------------------------------

### Run Release Script

Source: https://github.com/allenai/olmocr/blob/main/RELEASE_PROCESS.md

Execute the release script to commit changes and create a new git tag, which triggers the GitHub Actions release workflow.

```bash
./scripts/release.sh
```

--------------------------------

### Convert Workspace to Benchmark Format

Source: https://github.com/allenai/olmocr/blob/main/olmocr/bench/README.md

Convert the OLMOCR workspace data into the benchmark format. This script takes the workspace directory and the desired benchmark path as arguments.

```python
python olmocr/bench/scripts/workspace_to_bench.py localworkspace/ olmOCR-bench/bench_data/olmocr --bench-path ./olmOCR-bench/
```

--------------------------------

### Run olmOCR with DeepInfra

Source: https://github.com/allenai/olmocr/blob/main/README.md

This command enables olmOCR processing through the DeepInfra service. Replace DfXXXXXXX with your actual API key.

```bash
olmocr ./workspace --server https://api.deepinfra.com/v1/openai --api_key DfXXXXXXX --workers 1 --max_concurrent_requests 20 --model allenai/olmOCR-2-7B-1025 --pdfs tests/gnarly_pdfs/*.pdf
```

--------------------------------

### Initial Render on DOMContentLoaded

Source: https://github.com/allenai/olmocr/blob/main/olmocr/viewer/dolmaviewer_merged_template.html

Ensures that the markdown rendering function is called once the DOM is fully loaded, displaying the initial content.

```javascript
document.addEventListener('DOMContentLoaded', function() {
  renderMarkdown();
});
```

--------------------------------

### Configure GRPO Reinforcement Learning Training

Source: https://context7.com/allenai/olmocr/llms.txt

Initiate Group Relative Policy Optimization (GRPO) training for olmOCR models. This command-line interface allows specifying data folders, model names, output directories, and various reward functions.

```bash
# GRPO training with olmOCR-bench rewards
python -m olmocr.train.grpo_train \
  --train_bench_data_folder ./olmocr/bench/sample_data \
  --model_name Qwen/Qwen2.5-VL-7B-Instruct \
  --output_dir ./outputs/grpo_experiment \
  --learning_rate 2e-6 \
  --num_train_epochs 1 \
  --per_device_train_batch_size 1 \
  --gradient_accumulation_steps 8 \
  --num_generations 28 \
  --temperature 0.8 \
  --reward_bench 1.0 \
  --reward_front_matter 0.5 \
  --reward_rect_tables 0.3 \
  --loss_type bnpo \
  --wandb_project olmocr-grpo

# Available reward functions (can combine with weights):
# --reward_bench 1.0           # Unit test pass rate
# --reward_bench_macroavg 1.0  # Macro-averaged by test type
# --reward_medoid 0.5          # Similarity to medoid completion
# --reward_front_matter 0.5    # Valid YAML frontmatter parsing
# --reward_element_count 0.3   # Match table/equation counts
# --reward_rect_tables 0.3     # Rectangular HTML tables
# --reward_eos 0.1             # Proper EOS token ending

# Filter training data by JSONL file or test type
python -m olmocr.train.grpo_train \
  --train_bench_data_folder ./data \
  --jsonl_filter "arxiv|tables" \
  --bench_type_filter table \
  --bench_type_filter math \
  --reward_bench 1.0
```

--------------------------------

### Run olmOCR with Cirrascale

Source: https://github.com/allenai/olmocr/blob/main/README.md

Use this command to process PDFs with olmOCR via the Cirrascale external provider. Ensure you have a valid API key.

```bash
olmocr ./workspace --server https://ai2endpoints.cirrascale.ai/api --api_key sk-XXXXXXX --workers 1 --max_concurrent_requests 20 --model olmOCR-2-7B-1025 --pdfs tests/gnarly_pdfs/*.pdf
```

--------------------------------

### Clone Fork Locally

Source: https://github.com/allenai/olmocr/blob/main/docs/source/CONTRIBUTING.md

Clone your forked repository locally. Replace USERNAME with your GitHub username.

```bash
git clone https://github.com/USERNAME/olmocrgit
```

```bash
git clone git@github.com:USERNAME/olmocrgit
```

--------------------------------

### Sample PDF Pages

Source: https://context7.com/allenai/olmocr/llms.txt

Use this function to sample pages from a PDF. You can specify the total number of pages, always include the first few pages, and set a maximum number of sampled pages.

```python
num_pages = 50
sampled = sample_pdf_pages(
    num_pages=num_pages,
    first_n_pages=3,     # Always include first 3 pages
    max_sample_pages=10  # Sample up to 10 total
)
print(f"Sampled pages: {sampled}")  # [1, 2, 3, 17, 23, 31, 38, 42, 45, 49]
```