### Install Dependencies (Quick Start - CPU)

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/DEVELOPMENT.md

Installs PyTorch CPU version and project dependencies for quick development on macOS or Linux without a GPU.

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

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

### CPU Environment Installation

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/INSTALLATION.md

Commands to install PyTorch with CPU support and pdf-craft.

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

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

### Install pdf-craft

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/INSTALLATION.md

Command to install the pdf-craft package.

```bash
pip install pdf-craft
```

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

### Install Poppler on Ubuntu/Debian

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/INSTALLATION.md

Command to install Poppler utilities on Ubuntu or Debian-based systems.

```bash
sudo apt-get install poppler-utils
```

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

### Verify Poppler Installation

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/INSTALLATION.md

Command to verify if Poppler is installed and accessible in the system PATH.

```bash
pdfinfo -v
```

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

### Install Poppler on macOS

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/INSTALLATION.md

Command to install Poppler on macOS using Homebrew.

```bash
brew install poppler
```

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

### Create and Activate Virtual Environment

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/INSTALLATION.md

Commands to create and activate a Python virtual environment, followed by CUDA installation.

```bash
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate  # Windows

# Then follow the CUDA environment installation steps above
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
pip install pdf-craft
```

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

### Verify poppler-utils Installation

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/DEVELOPMENT.md

Checks the installed version of poppler-utils.

```shell
pdfinfo --version
```

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

### Install System Dependencies (WSL/Linux)

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/DEVELOPMENT.md

Installs poppler-utils on WSL or Linux systems.

```shell
sudo apt-get update
sudo apt-get install poppler-utils
```

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

### Verify CUDA Installation

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/INSTALLATION.md

Python command to verify if PyTorch can detect the CUDA environment.

```python
import torch; print('CUDA available:', torch.cuda.is_available())
```

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

### Create and Activate Python Environment

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/DEVELOPMENT.md

Sets up a Python virtual environment and activates it.

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

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

### Run Tests

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/DEVELOPMENT.md

Executes the project's test suite.

```shell
poetry run python test.py
```

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

### Build Package

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/DEVELOPMENT.md

Cleans old builds and creates distribution files for the package.

```shell
python build.py
```

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

### Check CUDA Version

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/INSTALLATION.md

Command to check the installed NVIDIA driver and CUDA version.

```bash
nvidia-smi
```

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

### Install PyTorch with CUDA 12.1

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/DEVELOPMENT.md

Installs PyTorch with CUDA 12.1 support.

```shell
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121
```

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

### Verify PyTorch Installation

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/DEVELOPMENT.md

Checks if PyTorch is installed correctly and if CUDA is available.

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

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

### Install Project Dependencies (CUDA Environment)

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/DEVELOPMENT.md

Installs project dependencies after manually setting up PyTorch with CUDA.

```shell
poetry install
```

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

### Install PyTorch with CUDA 11.8

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/DEVELOPMENT.md

Installs PyTorch with CUDA 11.8 support.

```shell
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu118
```

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

### Install PyTorch with CUDA 12.4

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/DEVELOPMENT.md

Installs PyTorch with CUDA 12.4 support.

```shell
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu124
```

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

### Configure PyPI token

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/RELEASE.md

Configures the PyPI token for publishing. This is a one-time setup.

```shell
poetry config pypi-token.pypi $PYPI_TOKEN
```

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

### Run Lint (pylint)

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/DEVELOPMENT.md

Checks code quality using pylint.

```shell
python lint.py
```

```shell
poetry run pylint pdf_craft
```

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

### API Parameter Migration Example

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/changelog/v1.0.2.md

Example demonstrating the migration from the old 'model' parameter to the new 'ocr_size' parameter in the transform_epub function.

```python
# Old (v1.0.1)
transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    model="gundam"
)

# New (v1.0.2)
transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    ocr_size="gundam"
)
```

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

### Install previous version

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/changelog/v1.0.0.md

Command to install the previous version (v0.2.8) if a CUDA environment is not available.

```bash
pip install pdf-craft==0.2.8
```

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

### Installation

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/changelog/v1.0.4.md

Install torch, torchvision, and pdf-craft version 1.0.4.

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

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

### Pre-submission Checks

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/DEVELOPMENT.md

Runs tests and linting before submitting a Pull Request.

```shell
poetry run python test.py
python lint.py
```

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

### Pre-download Models

Source: https://github.com/oomol-lab/pdf-craft/blob/main/README.md

Example of pre-downloading DeepSeek OCR models using the `predownload_models` function.

```python
from pdf_craft import predownload_models

predownload_models(
    models_cache_path="models",  # Specify model cache directory
    revision=None,  # Optional: specify model version
)
```

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

### Example Usage

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/changelog/v1.0.6.md

Demonstrates how to use the transform_markdown function with new parameters for DPI control, image size optimization, and OCR error handling.

```python
from pdf_craft import transform_markdown

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    dpi=300,  # Control rendering resolution
    max_page_image_file_size=5242880,  # 5MB limit per page
    ignore_ocr_errors=True,  # Continue on OCR failures
)
```

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

### Convert to Markdown

Source: https://github.com/oomol-lab/pdf-craft/blob/main/README.md

Example of converting a PDF file to Markdown format using the `transform_markdown` function.

```python
from pdf_craft import transform_markdown

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    markdown_assets_path="images",
    analysing_path="temp",  # Optional: specify temporary folder
    ocr_size="gundam",  # Optional: tiny, small, base, large, gundam
    models_cache_path="models",  # Optional: model cache path
    dpi=300,  # Optional: DPI for rendering PDF pages (default: 300)
    max_page_image_file_size=None,  # Optional: max image file size in bytes, auto-adjust DPI if exceeded
    includes_cover=False,  # Optional: include cover
    includes_footnotes=True,  # Optional: include footnotes
    ignore_pdf_errors=False,  # Optional: continue on PDF rendering errors
    ignore_ocr_errors=False,  # Optional: continue on OCR recognition errors
    generate_plot=False,  # Optional: generate visualization charts
    toc_llm=None,  # Optional: LLM instance for enhanced TOC extraction
    toc_assumed=False,  # Optional: whether to assume TOC pages exist (default: False)
)
```

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

### Offline Mode

Source: https://github.com/oomol-lab/pdf-craft/blob/main/README.md

Example of running pdf-craft in offline mode using `local_only=True`.

```python
from pdf_craft import transform_markdown

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    models_cache_path="./my_models",
    local_only=True,  # Use local models only, do not download from network
)
```

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

### Convert to EPUB

Source: https://github.com/oomol-lab/pdf-craft/blob/main/README.md

Example of converting a PDF file to EPUB format using the `transform_epub` function, including book metadata.

```python
from pdf_craft import transform_epub, BookMeta, TableRender, LaTeXRender

transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    analysing_path="temp",  # Optional: specify temporary folder
    ocr_size="gundam",  # Optional: tiny, small, base, large, gundam
    models_cache_path="models",  # Optional: model cache path
    dpi=300,  # Optional: DPI for rendering PDF pages (default: 300)
    max_page_image_file_size=None,  # Optional: max image file size in bytes, auto-adjust DPI if exceeded
    includes_cover=True,  # Optional: include cover
    includes_footnotes=True,  # Optional: include footnotes
    ignore_pdf_errors=False,  # Optional: continue on PDF rendering errors
    ignore_ocr_errors=False,  # Optional: continue on OCR recognition errors
    generate_plot=False,  # Optional: generate visualization charts
    toc_llm=None,  # Optional: LLM instance for enhanced TOC extraction
    toc_assumed=True,  # Optional: whether to assume TOC pages exist (default: True for EPUB)
    book_meta=BookMeta(
        title="Book Title",
        authors=["Author 1", "Author 2"],
        publisher="Publisher",
        language="en",
    ),
    lan="en",  # Optional: language (zh/en)
    table_render=TableRender.HTML,  # Optional: table rendering method
    latex_render=LaTeXRender.MATHML,  # Optional: formula rendering method
    inline_latex=True,  # Optional: preserve inline LaTeX expressions
)
```

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

### Update exception handling

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/changelog/v1.0.3.md

Example demonstrating the renaming of the `FitzError` exception to `PDFError` for exception handling.

```python
# Before (v1.0.2)
from pdf_craft import FitzError

# After (v1.0.3)
from pdf_craft import PDFError
```

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

### Specify Model Cache Path

Source: https://github.com/oomol-lab/pdf-craft/blob/main/README.md

Example of specifying a custom model cache path for pdf-craft.

```python
from pdf_craft import transform_markdown

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    models_cache_path="./my_models",  # Custom model cache directory
)
```

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

### LLM-Enhanced TOC Extraction Configuration

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/changelog/v1.0.10.md

Example of configuring and using LLM for enhanced TOC extraction in EPUB conversion.

```python
from pdf_craft import transform_epub, BookMeta, LLM

# Configure LLM for TOC enhancement
toc_llm = LLM(
    key="your-api-key",
    url="https://api.openai.com/v1",
    model="gpt-4",
    token_encoding="cl100k_base",
)

transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    toc_assumed=True,  # Enable TOC detection
    toc_llm=toc_llm,   # Enable LLM-powered analysis
    book_meta=BookMeta(
        title="Book Title",
        authors=["Author"],
    ),
)
```

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

### EPUB Transformation with LLM_ENHANCED TOC mode

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/changelog/v1.0.9.md

Example of transforming an EPUB using LLM-enhanced TOC extraction, including LLM configuration.

```python
from pdf_craft import transform_epub, BookMeta, TocExtractionMode
from pdf_craft import LLM

toc_llm = LLM(
    key="your-api-key",
    url="https://api.openai.com/v1",
    model="gpt-4",
    token_encoding="cl100k_base",
)

transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    toc_mode=TocExtractionMode.LLM_ENHANCED,
    toc_llm=toc_llm,
    book_meta=BookMeta(
        title="Book Title",
        authors=["Author"],
    ),
)
```

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

### EPUB Transformation with AUTO_DETECT TOC mode

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/changelog/v1.0.9.md

Example of transforming an EPUB using the default statistical TOC detection mode.

```python
from pdf_craft import transform_epub, BookMeta, TocExtractionMode

# Use AUTO_DETECT for statistical analysis (default for EPUB)
transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    toc_mode=TocExtractionMode.AUTO_DETECT,
    book_meta=BookMeta(
        title="Book Title",
        authors=["Author"],
    ),
)
```

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

### Update parameter names

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/changelog/v1.0.3.md

Example showing the renaming of the `ignore_fitz_errors` parameter to `ignore_pdf_errors` for the `transform_markdown` function.

```python
# Before (v1.0.2)
transform_markdown(..., ignore_fitz_errors=True)

# After (v1.0.3)
transform_markdown(..., ignore_pdf_errors=True)
```

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

### Traditional Boolean Error Handling (Still Supported)

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/changelog/v1.0.8.md

Example showing the continued support for simple boolean flags for error handling.

```python
from pdf_craft import transform_markdown

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    ignore_ocr_errors=True,  # Simple boolean flag
)
```

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

### Custom Error Handling with Functions

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/changelog/v1.0.8.md

Example demonstrating how to use a custom checker function for ignoring OCR errors.

```python
from pdf_craft import transform_markdown, OCRError

def should_ignore_ocr_error(error: OCRError) -> bool:
    # Only ignore specific types of OCR errors
    return error.kind == "recognition_failed"

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    ignore_ocr_errors=should_ignore_ocr_error,  # Pass custom function
)
```

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

### EPUB with Cover Image

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/changelog/v1.0.7.md

Example of how to include a cover image when converting a PDF to EPUB. The cover image is embedded in the EPUB file.

```python
from pdf_craft import transform_epub, BookMeta

transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    includes_cover=True,  # Include cover image (default)
    book_meta=BookMeta(
        title="Book Title",
        authors=["Author"],
    ),
)
```

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

### Markdown with Cover Image

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/changelog/v1.0.7.md

Example of how to include a cover image when converting a PDF to Markdown. The cover image is saved to the specified assets path.

```python
from pdf_craft import transform_markdown

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    markdown_assets_path="images",
    includes_cover=True,  # Include cover image
)
```

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

### Handling InterruptedError in v1.0.11

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/changelog/v1.0.11.md

Example demonstrating how to catch and inspect InterruptedError exceptions, accessing new properties like 'kind' and 'metering' for detailed interruption information.

```python
from pdf_craft import transform_markdown, InterruptedError, InterruptedKind

try:
    transform_markdown(
        pdf_path="input.pdf",
        markdown_path="output.md",
    )
except InterruptedError as error:
    # New in v1.0.11: Access interruption details
    if error.kind == InterruptedKind.ABORT:
        print("User aborted the operation")
    elif error.kind == InterruptedKind.TOKEN_LIMIT_EXCEEDED:
        print(f"Token limit exceeded: {error.metering.input_tokens} input tokens used")

    # Access token usage statistics
    print(f"Total tokens: {error.metering.input_tokens + error.metering.output_tokens}")
```

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

### Build the package

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/RELEASE.md

Builds the package for distribution.

```shell
poetry build
```

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

### Publish to PyPI

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/RELEASE.md

Publishes the built package to the Python Package Index (PyPI).

```shell
poetry publish
```

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

### Custom PDF Handler Configuration

Source: https://github.com/oomol-lab/pdf-craft/blob/main/README.md

Demonstrates how to specify a custom path for the Poppler binary when using transform_markdown.

```python
from pdf_craft import transform_markdown, DefaultPDFHandler

# Specify custom Poppler path
transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    pdf_handler=DefaultPDFHandler(poppler_path="/path/to/poppler/bin"),
)
```

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

### LLM-Enhanced TOC Extraction Configuration

Source: https://github.com/oomol-lab/pdf-craft/blob/main/README.md

Configures an LLM instance for TOC extraction and demonstrates its use in the transform_epub function.

```python
from pdf_craft import transform_epub, BookMeta, LLM

# Configure LLM for TOC extraction
toc_llm = LLM(
    key="your-api-key",
    url="https://api.openai.com/v1",  # Or your LLM provider URL
    model="gpt-4",
    token_encoding="cl100k_base",
    timeout=60.0,
    retry_times=3,
    retry_interval_seconds=5.0,
)

transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    toc_assumed=True,  # Enable TOC detection
    toc_llm=toc_llm,  # Enable LLM-powered chapter title analysis
    book_meta=BookMeta(
        title="Book Title",
        authors=["Author"],
    ),
)
```

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

### Convert to EPUB

Source: https://github.com/oomol-lab/pdf-craft/blob/main/README.md

Converts a PDF file to EPUB format, allowing for book metadata such as title and authors.

```python
from pdf_craft import transform_epub, BookMeta

transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    book_meta=BookMeta(
        title="Book Title",
        authors=["Author"],
    ),
)
```

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

### Previous API (v1.0.9 and earlier) for TOC extraction

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/changelog/v1.0.10.md

Demonstrates how to use the previous API with the TocExtractionMode enum for Markdown and EPUB conversion.

```python
from pdf_craft import transform_markdown, TocExtractionMode

# For Markdown conversion
transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    toc_mode=TocExtractionMode.NO_TOC_PAGE,  # Old parameter
)

# For EPUB conversion
transform_epub(
    pdf_path="input.pdf",
    epub_path="output.epub",
    toc_mode=TocExtractionMode.AUTO_DETECT,  # Old parameter
)
```

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

### Convert to Markdown

Source: https://github.com/oomol-lab/pdf-craft/blob/main/README.md

Converts a PDF file to Markdown format, including assets like images.

```python
from pdf_craft import transform_markdown

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    markdown_assets_path="images",
)
```

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

### New API (v1.0.10) for TOC extraction

Source: https://github.com/oomol-lab/pdf-craft/blob/main/docs/changelog/v1.0.10.md

Shows how to use the new API with the toc_assumed boolean parameter for Markdown and EPUB conversion.

```python
from pdf_craft import transform_markdown

# 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 (default: False)
)

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

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

### Error Handling - Boolean Mode

Source: https://github.com/oomol-lab/pdf-craft/blob/main/README.md

Illustrates using boolean flags to ignore PDF and OCR errors during markdown transformation.

```python
from pdf_craft import transform_markdown

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    ignore_pdf_errors=True,  # Ignore all PDF rendering errors
    ignore_ocr_errors=True,  # Ignore all OCR recognition errors
)
```

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

### Error Handling - Custom Function Mode

Source: https://github.com/oomol-lab/pdf-craft/blob/main/README.md

Shows how to use custom functions for fine-grained control over ignoring specific PDF and OCR errors.

```python
from pdf_craft import transform_markdown, OCRError, PDFError

def should_ignore_ocr_error(error: OCRError) -> bool:
    # Only ignore specific types of OCR errors
    return error.kind == "recognition_failed"

def should_ignore_pdf_error(error: PDFError) -> bool:
    # Custom logic to decide which PDF errors to ignore
    return "timeout" in str(error)

transform_markdown(
    pdf_path="input.pdf",
    markdown_path="output.md",
    ignore_ocr_errors=should_ignore_ocr_error,  # Pass custom function
    ignore_pdf_errors=should_ignore_pdf_error,  # Pass custom function
)
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.