pdf-backends

Configure and diagnose native and Pdfium PDF extraction backends in Xberg.

9.2k|581|Updated Jan 31, 2025
One-click install
npx skills add https://github.com/kreuzberg-dev/kreuzberg --skill pdf-backends
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: pdf-backends
Source: https://github.com/kreuzberg-dev/kreuzberg/tree/main/.ai-rulez/skills/pdf-backends
Command: npx skills add https://github.com/kreuzberg-dev/kreuzberg --skill pdf-backends

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Choosing and debugging the right PDF extraction engine in Xberg is error-prone: the native backend and the Pdfium backend have different capabilities, feature flags, and runtime requirements, and silent fallback between them produces misleading results.

Core Features & Use Cases

  • Backend Selection Guidance: Explains how PdfConfig.backend chooses between PdfBackend::Native (full pipeline: text, tables, annotations, images, attachments, OCR fallback) and PdfBackend::Pdfium (narrower surface: text, page count, Info-dictionary metadata).
  • Pdfium Runtime Diagnostics: Covers the pdf-pdfium Cargo feature, PDFIUM_DYNAMIC_LIB_PATH runtime discovery, process-global binding serialization, and actionable errors when the feature or library is missing.
  • OCR and Rendering Control: Details force_ocr, force_ocr_pages, and the PdfRenderSession primitive for efficient repeated page rendering.
  • Use Case: When a user requests Pdfium extraction but gets garbled or missing output, use this Skill to verify the feature flag, dynamic library path, and expected capability gaps instead of assuming a bug in document parsing.

Quick Start

Ask the assistant to switch the Xberg PDF extraction to the Pdfium backend and diagnose why the Pdfium library is not being found at runtime.

Frequently Asked Questions about pdf-backends

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I select the Pdfium backend for PDF extraction in Xberg?

Set PdfConfig.backend to PdfBackend::Pdfium and build with the pdf-pdfium Cargo feature enabled. Selecting Pdfium without that feature returns an actionable error rather than silently falling back to the native engine.

What is the difference between the native and Pdfium PDF backends?

The native backend supports the full pipeline: text, structure, tables, annotations, images, attachments, metadata, and OCR fallback. Pdfium intentionally offers a narrower surface limited to text, page count, and Info-dictionary metadata, warning about omitted capabilities.

Why does Pdfium fail to load at runtime?

Pdfium uses runtime dynamic loading that honors PDFIUM_DYNAMIC_LIB_PATH as a directory containing the platform library. Build-time static or dynamic link variables are not interchangeable with runtime discovery, so verify the path points to the correct library directory.

How do I force OCR on specific PDF pages?

Use config.force_ocr to force OCR on the whole document or config.force_ocr_pages to select individual pages. Otherwise, pages without usable native text automatically enter the OCR stage inside PdfExtractor.

Can I render multiple PDF pages without reopening the document?

Yes, use PdfRenderSession in pdf/render.rs, which opens document bytes once and exposes page count and page rendering. It is a Rust primitive and does not need to be exposed by every language binding.

When is a missing Pdfium library a test failure?

A missing Pdfium runtime is an infrastructure failure unless the job provisions it. When XBERG_REQUIRE_PDFIUM is set, skipping tests because the library or fixture is absent counts as a failure rather than a skip.