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
TocExtractionModeenum with a simplertoc_assumedboolean parameter in #341- Removed
toc_modeparameter fromtransform_markdown()andtransform_epub()functions - Removed
TocExtractionModefrom public API exports - Introduced
toc_assumedboolean flag to control TOC detection behavior
- Removed
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_llmis configured - Provides more accurate chapter level detection for complex book structures
- Intelligently falls back to standard analysis when LLM is unavailable or encounters errors
- Automatically analyzes chapter title hierarchies when
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_assumedparameter defaults toFalsefor Markdown conversion andTruefor 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