### Verify Examples with OxidizePDF

Source: https://github.com/bzsanti/oxidizepdf/blob/main/scripts/README.md

Compile and optionally run all examples. Use `--run` to also execute the RAG showcase if a corpus cache is present. This is crucial for CI to catch broken examples.

```bash
./scripts/verify-examples.sh          # compile all examples (--all-features)
```

```bash
./scripts/verify-examples.sh --run    # also run rag_realworld if corpus_cache present
```

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

### Run Batch Processing Example

Source: https://github.com/bzsanti/oxidizepdf/blob/main/oxidize-pdf-core/examples/doc/BATCH_PROCESSING.md

Execute the batch processing example with default settings. Ensure the 'rayon' feature is enabled.

```bash
cargo run --example batch_processing --features rayon -- --dir ./pdfs
```

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

### Run Example: Initial Download in Bash

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/superpowers/plans/2026-05-20-rag-realworld-rust.md

Executes the `rag_realworld` example using Cargo. This command first removes any existing cache directory to ensure a fresh download and then runs the example, redirecting stderr to stdout for visibility. It expects a successful download confirmation.

```bash
rm -rf oxidize-pdf-core/corpus_cache
cargo run --manifest-path oxidize-pdf-core/Cargo.toml --example rag_realworld 2>&1
```

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

### Run Page Overlay MVP Example

Source: https://github.com/bzsanti/oxidizepdf/blob/main/oxidize-pdf-core/examples/MVP_OVERLAY_README.md

Execute the MVP example to apply an overlay to a PDF. Output files are generated in the examples/results/ directory.

```bash
# Run the MVP example
cargo run --example page_overlay_mvp

# Output files will be created in examples/results/
# - mvp_base.pdf: Original base document
# - mvp_overlaid.pdf: Document with overlay applied
```

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

### Build and Run RAG Example

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/superpowers/plans/2026-05-20-rag-realworld-rust.md

Cleans the project, builds the RAG example, and runs it. Use this to verify the core functionality and output.

```bash
rm -rf oxidize-pdf-core/corpus_cache oxidize-pdf-core/out
cargo build --manifest-path oxidize-pdf-core/Cargo.toml --example rag_realworld 2>&1 | tail -5
cargo run --manifest-path oxidize-pdf-core/Cargo.toml --example rag_realworld 2>&1
echo "exit=$?"
```

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

### Install Pre-commit Hook

Source: https://github.com/bzsanti/oxidizepdf/blob/main/CONTRIBUTING.md

Install the automated pre-commit hook for validation. This is a one-time setup.

```bash
# Install the hook (one-time setup)
./scripts/install-hooks.sh
```

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

### Convert PDF to Searchable PDF with OCR

Source: https://github.com/bzsanti/oxidizepdf/blob/main/oxidize-pdf-core/examples/results/CONFIDENTIAL_OCR_TEST_SUMMARY.md

Command-line examples for converting PDF files to searchable PDFs using the `convert_pdf_ocr` example with Tesseract OCR features. Includes examples for both a failed and a partially successful processing scenario.

```bash
cargo run --example convert_pdf_ocr --features "ocr-tesseract" -- \
  "/Users/.../MADRIDEJOS_O&M CONTRACT_2013.pdf" \
  examples/results/MADRIDEJOS_searchable.pdf \
  --lang eng+spa --dpi 150 --verbose
```

```bash
cargo run --example convert_pdf_ocr --features "ocr-tesseract" -- \
  "/Users/.../FIS2 160930 O&M Agreement ESS.pdf" \
  examples/results/FIS2_searchable.pdf \
  --lang eng+spa --dpi 150 --verbose
```

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

### Run RAG Pipeline Example

Source: https://github.com/bzsanti/oxidizepdf/blob/main/README.md

Execute the RAG pipeline example provided with the project. This requires specifying the path to a PDF file as an argument.

```bash
cargo run --example rag_pipeline -- path/to/file.pdf
```

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

### Simple PDF Generation Benchmark

Source: https://github.com/bzsanti/oxidizepdf/blob/main/PERFORMANCE.md

Measures the performance of simple PDF generation using `cargo run --example create_simple_pdf --release`. Includes cold start and warm performance metrics.

```bash
time cargo run --example create_simple_pdf --release
# Result: 0.353s total (includes compilation overhead)
# Pure creation: ~0.35ms per PDF
```

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

### Install Tesseract OCR on Ubuntu/Debian

Source: https://github.com/bzsanti/oxidizepdf/blob/main/oxidize-pdf-core/examples/doc/OCR_USAGE.md

Installs the Tesseract OCR engine and language packs using apt-get.

```bash
sudo apt-get install tesseract-ocr
# For additional languages:
sudo apt-get install tesseract-ocr-spa tesseract-ocr-fra
```

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

### Install OxidizePDF Plugin

Source: https://github.com/bzsanti/oxidizepdf/blob/main/landing/index.html

Use this command to install the oxidize-pdf plugin.

```bash
/plugin install oxidize-pdf@oxidize-pdf
```

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

### Install External Validators (Windows)

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/ISO_TESTING_SYSTEM.md

Instructions for installing external validation tools qpdf and verapdf on Windows systems. Users are directed to download and install from the respective official websites.

```bash
# Windows
# Download and install from respective websites
```

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

### Run Rag_realworld Example

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/superpowers/plans/2026-05-25-cid-encoding-cmap.md

Execute the `rag_realworld` example to verify that real-world content remains unchanged. Check for the expected number of documents and specific content in the initial chunks.

```bash
source ~/.cargo/env && nice cargo run --release --example rag_realworld 2>&1 | tail -8
```

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

### One-time Setup for gh-pages Branch

Source: https://github.com/bzsanti/oxidizepdf/blob/main/landing/README.md

Use this command sequence to create an orphan `gh-pages` branch and populate it with the initial landing page. This is a one-time setup process.

```bash
git switch --orphan gh-pages
git rm -rf .
cp landing/index.html .
git add index.html
git commit -m "Initial landing page"
git push -u origin gh-pages
```

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

### Run rag_realworld Example and Capture Output

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/superpowers/plans/2026-05-21-marked-content-extraction.md

Executes the rag_realworld example with nice for resource management and tees the output to a log file while displaying the last 80 lines. Use this to capture the initial run results for regression testing.

```bash
nice cargo run --release --example rag_realworld 2>&1 | tee /tmp/rag_realworld_after.log | tail -80
```

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

### CLI Error Handling Examples

Source: https://github.com/bzsanti/oxidizepdf/blob/main/oxidize-pdf-core/examples/results/OCR_TEST_RESULTS.md

Demonstrates expected error messages for non-existent input files and unknown command-line options.

```text
✅ CLI error handling works:
   Error: "Input file does not exist: nonexistent.pdf"

✅ CLI invalid argument handling works:
   Error: "Unknown option: --invalid-option"
```

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

### Install Nightly Rust Toolchain and Dylint

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/LINTS.md

Installs the Rust nightly toolchain with the rustc-dev component and installs the necessary dylint tools for running custom lints.

```bash
rustup toolchain install nightly --component rustc-dev

```

```bash
cargo +nightly install cargo-dylint dylint-link

```

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

### Run RAG Real-World Example

Source: https://github.com/bzsanti/oxidizepdf/blob/main/oxidize-pdf-core/examples/README.md

Downloads and processes five real-world PDFs, chunks them using the default pipeline, and outputs RAG-ready JSON Lines to the './out/' directory. This example caches downloaded PDFs for subsequent runs.

```bash
cargo run --example rag_realworld
# → ./corpus_cache/<sha1>.pdf   (downloaded inputs, kept across runs)
# → ./out/<slug>.jsonl          (one chunk per line, RAG-ready)
```

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

### Run rag_realworld Example

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/superpowers/plans/2026-05-23-issue-265-line-interleaving.md

Execute the rag_realworld example to verify document processing and chunk counts. Log output for analysis and compare against baseline values with a ±5% tolerance per document.

```bash
nice cargo run --example rag_realworld --release 2>&1 | tee .private/rag_realworld_after_265.log | tail -30
```

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

### Batch Processing Setup

Source: https://github.com/bzsanti/oxidizepdf/blob/main/API_DOCUMENTATION.md

Details on how to initialize and configure the `BatchProcessor` for handling multiple PDF operations efficiently.

```APIDOC
## Batch Processing Setup

### Description
Initialize and configure the `BatchProcessor` to manage and execute multiple PDF processing jobs concurrently or sequentially.

### Methods
- `BatchProcessor::new(options: BatchOptions) -> BatchProcessor`: Creates a new batch processor with specified options.
- `processor.add_job(job: BatchJob)`: Adds a processing job to the batch.
- `processor.execute() -> Result<BatchSummary>`: Executes all added jobs and returns a summary.

### Example
```rust
use oxidize_pdf::batch::{BatchProcessor, BatchOptions, BatchJob, BatchSummary};

let options = BatchOptions::default(); // Use default options
let mut processor = BatchProcessor::new(options);

processor.add_job(BatchJob::Split {
    input: "large.pdf".into(),
    output_pattern: "page_{}.pdf".to_string(),
    pages_per_file: 1,
});

let summary: BatchSummary = processor.execute()?;
println!("Batch processing completed. Processed {} jobs.", summary.processed_jobs);
```
```

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

### Install oxidize-pdf with OCR support

Source: https://github.com/bzsanti/oxidizepdf/blob/main/oxidize-pdf-core/examples/doc/OCR_USAGE.md

Install the oxidize-pdf CLI tool with the necessary features for Tesseract OCR. This command is used once to set up the tool.

```bash
cargo install oxidize-pdf --features ocr-tesseract
```

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

### Install External Validators (macOS/Linux)

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/ISO_TESTING_SYSTEM.md

Instructions for installing external validation tools qpdf and verapdf on macOS and Linux systems using package managers.

```bash
# macOS
brew install qpdf
brew install verapdf

# Linux
apt-get install qpdf
# Download veraPDF from https://verapdf.org/
```

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

### Run Clippy on RAG Example

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/superpowers/plans/2026-05-20-rag-realworld-rust.md

Performs a static code analysis using Clippy on the RAG example, with warnings treated as errors. Fixes any reported issues inline.

```bash
cargo clippy --manifest-path oxidize-pdf-core/Cargo.toml --example rag_realworld -- -D warnings 2>&1 | tail -20
```

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

### Run RAG Real-World PDF Example

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/superpowers/plans/2026-05-20-rag-realworld-rust-pr-body.md

Execute the Rust example to process a corpus of real-world PDFs. This command downloads, parses, and chunks documents, outputting JSONL files and statistics to stderr. Failures are handled by skipping the document and returning a non-zero exit code.

```bash
cargo run --example rag_realworld
```

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

### Install OxidizePDF Integrations

Source: https://github.com/bzsanti/oxidizepdf/blob/main/landing/index.html

Use this command to add the OxidizePDF integrations plugin to your environment.

```bash
/plugin marketplace add bzsanti/oxidize-pdf-integrations
```

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

### Run RAG Example Skeleton in Rust

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/superpowers/plans/2026-05-20-rag-realworld-rust.md

This bash command executes the `rag_realworld` example using Cargo. It specifies the manifest path for the `oxidize-pdf-core` crate. The expected output shows the number of documents in the corpus and their details, confirming the skeleton program runs as intended.

```bash
cargo run --manifest-path oxidize-pdf-core/Cargo.toml --example rag_realworld
```

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

### CI Build and Lint Check

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/superpowers/plans/2026-05-20-rag-realworld-rust-pr-body.md

Build the Rust example and perform linting checks. This ensures the code compiles and adheres to project coding standards.

```bash
cargo build --examples
```

```bash
cargo clippy --example rag_realworld -- -D warnings
```

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

### Call Rust Binary from Python

Source: https://github.com/bzsanti/oxidizepdf/blob/main/MIGRATION.md

Example of executing an oxidize-pdf command-line tool from a Python script using the subprocess module.

```python
# Option 1: Call Rust binary from Python
import subprocess
result = subprocess.run(['oxidize-pdf', 'merge', 'file1.pdf', 'file2.pdf'], 
                       capture_output=True, text=True)
```

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

### Troubleshoot Parsing Results

Source: https://github.com/bzsanti/oxidizepdf/blob/main/benches/lopdf_comparison/QUICKSTART.md

Verify the existence of test PDFs and provide commands to copy them from example or render test directories if parsing benchmarks fail.

```bash
# Ensure test PDFs exist
ls test_pdfs/*.pdf

# Copy some from examples
cp ../../examples/results/*.pdf test_pdfs/

# Or use oxidize-pdf-render tests
cp ../../oxidize-pdf-render/tests/fixtures/*.pdf test_pdfs/
```

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

### Register rag_realworld Example

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/superpowers/plans/2026-05-20-rag-realworld-rust.md

Add a new `[[example]]` block to `Cargo.toml` to register the `rag_realworld` example, specifying its path.

```toml
[[example]]
name = "rag_realworld"
path = "examples/rag_realworld.rs"
```

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

### Open Documentation Builds

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/DEVELOPMENT_GUIDELINES.md

Build and automatically open the project's documentation in a web browser to verify its structure and content.

```bash
cargo doc --open
```

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

### Release Workflow - Tagging for Release

Source: https://github.com/bzsanti/oxidizepdf/blob/main/CONTRIBUTING.md

This bash example demonstrates how to tag a new version for triggering the release workflow, which includes building, testing, and publishing to crates.io.

```bash
git tag v1.7.0
git push origin v1.7.0
```

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

### Next Steps for Clean Build

Source: https://github.com/bzsanti/oxidizepdf/blob/main/tools/scripts/QUICK_REFERENCE.md

Follow these steps to ensure a clean build, run tests, and push changes to the repository.

```bash
# Verify build is clean: `cargo build --lib`
# Run tests: `cargo test --lib`
# Check for any new warnings: `cargo clippy -- -D warnings`
# Optional: Archive backup files if not needed anymore
# Push to repository: `git push origin develop_santi`
```

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

### Install Tesseract OCR on macOS

Source: https://github.com/bzsanti/oxidizepdf/blob/main/oxidize-pdf-core/examples/doc/OCR_USAGE.md

Installs the Tesseract OCR engine and language packs using Homebrew.

```bash
brew install tesseract
# For additional languages:
brew install tesseract-lang
```

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

### Scenario B: Back-Compat Page Creation Flow

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/superpowers/specs/2026-05-07-per-document-font-metrics-design.md

Demonstrates the data flow when using the legacy `Page::a4()` constructor without explicit metrics, which can lead to degraded measurement and a diagnostic warning. This path should be migrated to `Document::new_page_a4()`.

```text
1. let mut doc = Document::new();
2. doc.add_font_from_bytes("MyCJK", bytes)?;
3. let mut page = Page::a4();                                [store = None]
4. page.set_font(Font::custom("MyCJK"), 12.0);
5. let mut text = page.text_flow();                          [None propagates]
6. text.write("高効能");
   └─ lookup(font, None)
       ├─ store_opt = None → skip Document scope
       ├─ legacy_global_get("MyCJK") → None (doc did not write to global)
       └─ warn-once + default                                [⚠ degraded measurement]
7. page.add_text_flow(&text);                                [content stream emitted with default widths]
8. doc.add_page(page);                                       [too late: store injected, content already generated]
```

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

### Add Test PDFs for Parsing Benchmark

Source: https://github.com/bzsanti/oxidizepdf/blob/main/benches/lopdf_comparison/README.md

Prepare the environment for the PDF parsing benchmark by creating the necessary directory and copying PDF files into it. Then, run the parsing benchmark.

```bash
mkdir -p benches/lopdf_comparison/test_pdfs

```

```bash
cp path/to/pdfs/*.pdf benches/lopdf_comparison/test_pdfs/

```

```bash
cargo run --release --bin benchmark_parsing --manifest-path benches/lopdf_comparison/Cargo.toml
```

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

### Extract Legal Form Data Example

Source: https://github.com/bzsanti/oxidizepdf/blob/main/oxidize-pdf-core/examples/doc/COMPREHENSIVE_EXAMPLES.md

Demonstrates extracting predefined legal form data. This is a simplified example for demonstration purposes.

```rust
fn extract_legal_form_data(doc: &Document) -> Result<Vec<(String, FieldValue)>, PdfError> {
    // In production, this would parse actual PDF form fields
    // This is a simplified example
    Ok(vec![
        ("case_number".to_string(), FieldValue::Text("CA-2024-123456".to_string())),
        ("court_name".to_string(), FieldValue::Text("Superior Court of California".to_string())),
        ("filing_date".to_string(), FieldValue::Text("08/27/2024".to_string())),
    ])
}
```

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

### Build oxidize-pdf Benchmarks

Source: https://github.com/bzsanti/oxidizepdf/blob/main/benches/lopdf_comparison/QUICKSTART.md

Build the release version of the benchmarks. This is a one-time step that may take several minutes.

```bash
cd benches/lopdf_comparison
cargo build --release
```

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

### Test with PDF Files

Source: https://github.com/bzsanti/oxidizepdf/blob/main/PERFORMANCE.md

Execute the batch processing example with your specific PDF files to measure performance on your own data. Use the 'time' command to record execution duration.

```bash
# Test with your PDF files
time cargo run --example batch_process /path/to/your/pdfs/
```

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

### Re-run Rag Realworld Example

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/superpowers/plans/2026-05-20-issue-261-paragraph-reconstruction.md

Executes the 'rag_realworld' example using Cargo to test the fix against the real corpus. Output is redirected to stderr.

```bash
cargo run --manifest-path oxidize-pdf-core/Cargo.toml --example rag_realworld 2>&1
```

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

### Handle Tesseract Installation Errors

Source: https://github.com/bzsanti/oxidizepdf/blob/main/oxidize-pdf-core/examples/doc/OCR_USAGE.md

Check if Tesseract is installed and accessible. This snippet shows how to handle the `Err` case when initializing the Tesseract provider.

```rust
match RustyTesseractProvider::new() {
    Ok(provider) => { /* Use provider */ } 
    Err(e) => {
        eprintln!("Tesseract not installed: {}", e);
        // Handle gracefully
    }
}

```

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

### Inspect Cargo.toml for Dependencies and Examples

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/superpowers/plans/2026-05-20-rag-realworld-rust.md

Use `grep` to find the line numbers for `[dev-dependencies]` and `[[example]]` sections in `Cargo.toml`. This helps in identifying where to insert new entries.

```bash
grep -n "^\\[dev-dependencies\\]$\|^\\[\\[example\\]\\]" oxidize-pdf-core/Cargo.toml | head -5
```

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

### Create New PDF (PyPDF2 vs oxidize-pdf)

Source: https://github.com/bzsanti/oxidizepdf/blob/main/MIGRATION.md

Demonstrates the process of creating a new PDF document and adding text to it, contrasting the PyPDF2/reportlab approach with oxidize-pdf.

```python
# PyPDF2 (Before)
from reportlab.pdfgen import canvas
c = canvas.Canvas("output.pdf")
c.drawString(100, 750, "Hello World")
c.save()
```

```rust
// oxidize-pdf (After)
use oxidize_pdf::{Document, Page};

let mut document = Document::new();
let mut page = Page::new();
page.graphics().show_text_at("Hello World", 100.0, 750.0)?;
document.add_page(page);
document.save("output.pdf")?;
```

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

### Commit changes to RAG example

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/superpowers/plans/2026-05-20-rag-realworld-rust.md

Stages the modified `rag_realworld.rs` file and commits it with a descriptive message indicating the addition of corpus processing and statistics output for the RAG example.

```bash
git add oxidize-pdf-core/examples/rag_realworld.rs
git commit -m "feat(example): run rag_chunks() over corpus and print stats"
```

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

### Run Full Benchmark Suite

Source: https://github.com/bzsanti/oxidizepdf/blob/main/BENCHMARK_RESULTS.md

Execute the full benchmark suite with default or specified page counts. Use this for comprehensive performance evaluation.

```bash
# Realistic - Full test (1000 pages)
cargo run --release --example realistic_document_benchmark 1000

# Medium - Standard (50 pages default)
cargo run --release --example medium_complexity_benchmark

# High - Standard (100 pages default)
cargo run --release --example high_complexity_benchmark
```

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

### Run Invoice Test Example

Source: https://github.com/bzsanti/oxidizepdf/blob/main/oxidize-pdf-core/examples/results/parser_debug/parser_fixes_summary.md

Executes a test suite against real invoices to verify parser success. Shows individual invoice test outcomes and a summary of the overall results.

```bash
$ cargo run --example test_real_invoices
✅ Test 1/10: Tresun - SUCCESS
✅ Test 2/10: Belectric - SUCCESS
✅ Test 3/10: RES Invoice - SUCCESS
✅ Test 4/10: BayWa - SUCCESS (FIXED)
✅ Test 5/10: Greencoat - SUCCESS (FIXED)
✅ Test 6/10: REPS - SUCCESS (FIXED)
✅ Test 7/10: ENcome - SUCCESS (FIXED)
✅ Test 8/10: Plenium - SUCCESS
✅ Test 9/10: Spence & Hill - SUCCESS
✅ Test 10/10: Anesco - SUCCESS

📊 SUMMARY
Total PDFs:          10
Parsed successfully: 10  (100%)
Tables detected:     7   (70%)

```

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

### Create Feature Branch for RAG Example

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/superpowers/plans/2026-05-20-rag-realworld-rust.md

Commands to create and switch to a new Git branch for the RAG real-world Rust example. Ensures the develop branch is up-to-date before branching.

```bash
git checkout develop
git pull origin develop
git checkout -b feature/rag-realworld-rust
```

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

### Run Unit Tests for RAG Example

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/superpowers/plans/2026-05-20-rag-realworld-rust.md

Executes unit tests specifically for the RAG example's JSONL output and the library's core functionality. Ensures no regressions are introduced.

```bash
cargo test --manifest-path oxidize-pdf-core/Cargo.toml --test rag_realworld_jsonl_test 2>&1 | tail -10
```

```bash
cargo test --manifest-path oxidize-pdf-core/Cargo.toml --lib 2>&1 | tail -5
```

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

### Run Comprehensive Benchmarks

Source: https://github.com/bzsanti/oxidizepdf/blob/main/PERFORMANCE.md

Clone the repository, navigate to the directory, and run the built-in benchmarks using cargo bench. This provides a baseline performance measurement.

```bash
# Clone and build
git clone https://github.com/BelowZero/oxidize-pdf
cd oxidize-pdf

# Run comprehensive benchmarks
cargo bench
```

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

### Run Quick Benchmark Tests

Source: https://github.com/bzsanti/oxidizepdf/blob/main/BENCHMARK_RESULTS.md

Execute quick benchmark tests with a specified number of pages. Use this for rapid testing of different document complexities.

```bash
# Realistic - 100 pages
cargo run --release --example realistic_document_benchmark 100

# Medium - 100 pages
cargo run --release --example medium_complexity_benchmark 100

# High - 100 pages
cargo run --release --example high_complexity_benchmark 100
```

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

### RAG Real-World Example Architecture

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/superpowers/specs/2026-05-20-rag-realworld-examples-design.md

This pseudocode illustrates the common architectural flow for the RAG examples. It covers document processing steps from corpus definition to JSONL output and statistics reporting.

```pseudocode
example entry-point
   │
   ▼
CORPUS constant (array of {slug, name, url, country, language})
   │
   ▼
for each document in CORPUS:
   ├─ cache_path = ./corpus_cache/<sha1(url)[:16]>.pdf
   ├─ if not exists(cache_path): download(url, timeout=30s) → cache_path
   ├─ open PDF via the language's binding
   ├─ chunks = doc.rag_chunks()      # default HybridChunkConfig
   ├─ assert len(chunks) >= 1 && any chunk has non-empty text
   ├─ for each chunk: write JSONL line to ./out/<slug>.jsonl
   └─ print stats line to stderr
   │
   ▼
summary line + exit code (0 if all ok; = N if N documents failed; 2 if fatal)
```

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

### Run Creation Benchmark

Source: https://github.com/bzsanti/oxidizepdf/blob/main/benches/lopdf_comparison/QUICKSTART.md

Execute the benchmark for PDF creation, which generates 1,000 pages per test.

```bash
cargo run --release --bin benchmark_creation
```

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

### Commit RAG Example Skeleton in Git

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/superpowers/plans/2026-05-20-rag-realworld-rust.md

This bash command stages the `rag_realworld.rs` file for the `oxidize-pdf-core` example and commits it with a descriptive message. This is part of the development workflow to save the initial skeleton code.

```bash
git add oxidize-pdf-core/examples/rag_realworld.rs
git commit -m "feat(example): skeleton for rag_realworld with corpus constant"
```

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

### Prepare Release and Commit

Source: https://github.com/bzsanti/oxidizepdf/blob/main/CONTRIBUTING.md

Perform final fixes, bump the version, and update the changelog before merging the release.

```bash
# Bump version, final fixes
# Update CHANGELOG.md
git commit -m "chore: prepare release v1.2.0"
```

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

### Run RAG example and check exit code

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/superpowers/plans/2026-05-20-rag-realworld-rust.md

Executes the `rag_realworld` Rust example using Cargo and redirects standard error to standard output to capture all messages. It then prints the exit code of the command.

```bash
cargo run --manifest-path oxidize-pdf-core/Cargo.toml --example rag_realworld 2>&1
echo "exit=$?"
```

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

### Run All Benchmarks and Generate Report

Source: https://github.com/bzsanti/oxidizepdf/blob/main/benches/lopdf_comparison/QUICKSTART.md

Execute all defined benchmarks and generate a comprehensive report.

```bash
cargo run --release --bin run_all
```

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

### Numeric Prefix Title Detection Logic

Source: https://github.com/bzsanti/oxidizepdf/blob/main/docs/superpowers/specs/2026-05-28-issue-271-partitioner-classifier-design.md

Detects titles that start with a section prefix, have a limited length, and are followed by a word starting with an uppercase letter. This helps distinguish titles from phrases like '1.2 million'.

```rust
fn numeric_prefix_title(f: &TextFragment) -> bool {
    let trimmed = f.text.trim();
    let char_count = trimmed.chars().count();
    if char_count == 0 || char_count > MAX_NUMERIC_TITLE_LEN { return false; }
    if !matches_section_prefix(trimmed) { return false; }
    // Require a following word with capital letter (rules out "1.2 million", "version 3.0.1")
    let rest = strip_section_prefix(trimmed);
    let first_char = rest.trim_start().chars().next();
    matches!(first_char, Some(c) if c.is_uppercase())
}
```

```rust
const MAX_NUMERIC_TITLE_LEN: usize = 200;
```

```regex
^([A-Z]\d+(\.\d+)*([a-z]\.?)?|\d+(\.\d+)*\.?|Section\s+\d+:?|Chapter\s+\d+:?|[IVX]+\.)\s+
```

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

### Python Integration for Batch PDF Processing

Source: https://github.com/bzsanti/oxidizepdf/blob/main/oxidize-pdf-core/examples/doc/BATCH_PROCESSING.md

Integrate batch PDF processing into Python applications using `subprocess`. This example shows how to run the `batch_processing` example, capture its JSON output, and analyze processing statistics and failed files.

```python
import subprocess
import json

result = subprocess.run([
    'cargo',
    'run',
    '--example',
    'batch_processing',
    '--features',
    'rayon',
    '--',
    '--dir',
    './pdfs',
    '--json'
], capture_output=True, text=True)

data = json.loads(result.stdout)

print(f"Processed {data['total']} PDFs")
print(f"Success rate: {data['successful'] / data['total'] * 100:.1f}%")
print(f"Throughput: {data['throughput_docs_per_sec']:.1f} docs/sec")

# Extract failed files for manual review
failed_files = [r['filename'] for r in data['results'] if not r['success']]
print(f"Failed files: {failed_files}")
```

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

### Display Script Help

Source: https://github.com/bzsanti/oxidizepdf/blob/main/tools/scripts/QUICK_REFERENCE.md

Show the help message for the main cleanup script to understand available options and usage.

```bash
# Show help for main script
python3 tools/scripts/remove_debug_eprintln.py --help
```

```bash
# Read detailed docs
cat tools/scripts/README_DEBUG_REMOVAL.md
cat tools/scripts/ARCHITECTURE.md
cat tools/scripts/RESTORE.md
```

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

### Basic PDF Loading and Batch Processing

Source: https://github.com/bzsanti/oxidizepdf/blob/main/API_DOCUMENTATION.md

Demonstrates basic PDF loading and setting up batch processing jobs. Ensure you have a document.pdf and large.pdf in your project directory.

```rust
use oxidize_pdf::{Document, batch::*, forms::*};

// Basic PDF loading
let doc = Document::load("document.pdf")?;
println!("Pages: {}", doc.page_count());

// Batch processing
let processor = BatchProcessor::new(BatchOptions::default());
processor.add_job(BatchJob::Split {
    input: "large.pdf".into(),
    output_pattern: "page_{}.pdf".to_string(),
    pages_per_file: 1,
});
let summary = processor.execute()?;

```