github oomol-lab/pdf-craft v1.0.10

latest releases: v2.6.7, v2.6.6, v2.6.5...
9 months ago

This release simplifies the table of contents (TOC) extraction API by replacing enum-based modes with a boolean flag, while adding LLM-powered chapter title analysis capabilities for improved TOC hierarchy detection.

What's Changed

Breaking Changes

  • Simplified TOC API: Replaced TocExtractionMode enum with a simpler toc_assumed boolean parameter in #341
    • Removed toc_mode parameter from transform_markdown() and transform_epub() functions
    • Removed TocExtractionMode from public API exports
    • Introduced toc_assumed boolean flag to control TOC detection behavior

Features

  • LLM-Powered Chapter Title Analysis: Added support for LLM-based analysis of chapter titles to enhance TOC extraction accuracy in #341
    • Automatically analyzes chapter title hierarchies when toc_llm is configured
    • Provides more accurate chapter level detection for complex book structures
    • Intelligently falls back to standard analysis when LLM is unavailable or encounters errors

Improvements

  • Enhanced Error Handling: Added robust error handling for LLM-based analysis with automatic recovery mechanisms in #341
    • Better error diagnostics for LLM analysis failures
    • Graceful degradation when LLM analysis fails, ensuring conversion continues successfully

Migration Guide

If you were using toc_mode in previous versions, update your code as follows:

Previous API (v1.0.9 and earlier)

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
)

New API (v1.0.10)

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
)

Migration Mapping

Old toc_mode Value New toc_assumed Value
TocExtractionMode.NO_TOC_PAGE False
TocExtractionMode.AUTO_DETECT True
TocExtractionMode.LLM_ENHANCED True (with toc_llm configured)

LLM-Enhanced TOC Extraction

To use LLM-powered chapter title analysis:

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"],
    ),
)

Notes

  • The toc_assumed parameter defaults to False for Markdown conversion and True for EPUB conversion (maintaining backward-compatible behavior)
  • LLM-powered chapter title analysis is optional and automatically falls back to standard analysis if not configured or if errors occur
  • The new API is simpler and more intuitive, reducing the cognitive load of choosing between multiple enum values

Full Changelog: v1.0.9...v1.0.10

Don't miss a new pdf-craft release

NewReleases is sending notifications on new releases.