pdf-craft Documentation

After installation, verify that both CUDA and Poppler are correctly configured.

Verify CUDA:

python -c "import torch; print('CUDA available:', torch.cuda.is_available())"

Expected output: CUDA available: True

Verify Poppler:

pdfinfo -v

Expected output: Poppler version information.

Run the following command to ensure PyTorch is correctly installed and to check if CUDA is accessible by the environment.

python -c "import torch; print(f'PyTorch version: {torch.__version__}'); print(f'CUDA available: {torch.cuda.is_available()}')"

pdf-craft uses Poppler (via pdf2image) for PDF parsing and rendering. You must install it separately based on your operating system:

• Ubuntu/Debian: sudo apt-get install poppler-utils
• macOS: brew install poppler
• Windows: Download the latest Poppler binaries from oschwartz10612/poppler-windows and add the bin/ directory to your system PATH. Alternatively, you can specify the path using the pdf_handler parameter during usage.

If you are upgrading from version 1.0.2 to 1.0.3, you must perform the following steps due to breaking changes:

1. Install Poppler on your operating system.
2. Rename parameters: Change ignore_fitz_errors to ignore_pdf_errors in calls to transform_markdown() and transform_epub().
3. Update exception handling: Replace FitzError with PDFError in your import and exception catching logic.

# Before (v1.0.2)
transform_markdown(..., ignore_fitz_errors=True)
from pdf_craft import FitzError

# After (v1.0.3)
transform_markdown(..., ignore_pdf_errors=True)
from pdf_craft import PDFError

In version 1.0.10, the toc_mode parameter (which used the TocExtractionMode enum) was replaced by a boolean flag toc_assumed.

Migration Mapping:

• Use toc_assumed=False if you previously used TocExtractionMode.NO_TOC_PAGE.
• Use toc_assumed=True if you previously used TocExtractionMode.AUTO_DETECT or TocExtractionMode.LLM_ENHANCED.

Note that toc_assumed defaults to False for transform_markdown() and True for transform_epub().

# For Markdown conversion (assumes no TOC pages by default)
transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    toc_assumed=False,  # New boolean parameter
)

# For EPUB conversion (assumes TOC pages exist)
transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    toc_assumed=True,  # New boolean parameter
)

For quick development on macOS or Linux without a GPU, install the CPU version of PyTorch along with the project dependencies using poetry run pip.

poetry run pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu

pdf-craft uses DeepSeek OCR models which are downloaded from Hugging Face on the first run. You can manage these models using predownload_models or by specifying a models_cache_path and using local_only=True for offline mode.

Pre-download models

from pdf_craft import predownload_models

predownload_models(
    models_cache_path="models",
    revision=None,
)

Offline mode

To ensure the process only uses local models without attempting network downloads:

from pdf_craft import transform_markdown

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    models_cache_path="./my_models",
    local_only=True,
)

To install version 1.0.4, ensure you install the CPU version of PyTorch first, then install pdf-craft.

pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
pip install pdf-craft==1.0.4

Create and activate a virtual environment for development using the standard venv module.

python -m venv .venv
. ./.venv/bin/activate