pdf2epub 0.1.0

Convert PDF files to EPUB format via Markdown with intelligent layout detection

PDF2EPUB 📚

A powerful Python package for converting PDF files to EPUB format via Markdown with intelligent layout detection, AI-powered postprocessing, and seamless CLI/API integration.

✨ Features

• 📖 Smart Layout Detection - Handles books, academic papers, and complex documents
• 🔍 Advanced PDF Processing - OCR, table detection, and image extraction
• 🤖 AI Postprocessing - Enhance quality with Anthropic Claude integration
• 📝 Clean Markdown Output - Structured, readable markdown with preserved formatting
• 📱 Professional EPUB - High-quality EPUB 3.0 output with customizable styling
• 🌍 Multi-language Support - Process documents in multiple languages
• 🚀 GPU Acceleration - NVIDIA CUDA and AMD ROCm support for faster processing
• 🍎 Apple Silicon Support - Optimized performance on Apple Silicon devices
• 🛠️ Flexible API - Use as CLI tool or import as Python library
• 🔌 Plugin Architecture - Extensible AI provider system

🚀 Quick Start

Installation

# Basic installation
pip install pdf2epub

# Full installation with all features
pip install pdf2epub[full]

Command Line Usage

# Convert a PDF to EPUB
pdf2epub document.pdf

# Advanced options
pdf2epub book.pdf --start-page 10 --max-pages 50 --langs "English,German"

Python API

• For Apple Silicon, install with MPS support:

pip3 uninstall torch torchvision torchaudio
pip3 install --pre torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/nightly/cpu

• For Apple Silicon, install with MPS support:

pip3 uninstall torch torchvision torchaudio
pip3 install --pre torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/nightly/cpu

3. Verify GPU support:

import torch
print(torch.__version__)  # PyTorch version
print(torch.cuda.is_available())  # Should return True for NVIDIA
print(torch.mps.is_available())  # Should return True for Apple Silicon
print(torch.version.hip)  # Should print ROCm version for AMD

import pdf2epub

# Simple conversion
pdf2epub.convert_pdf_to_markdown("document.pdf", "output/")
pdf2epub.convert_markdown_to_epub("output/", "final/")

# Advanced usage with AI enhancement
processor = pdf2epub.AIPostprocessor("output/")
processor.run_postprocessing("document.md", "anthropic")

📦 Installation Options

Basic Installation

pip install pdf2epub

Includes core functionality with minimal dependencies.

Full Installation

pip install pdf2epub[full]

Includes all features: PDF processing, AI postprocessing, and GPU acceleration.

Development Installation

pip install pdf2epub[dev]

Includes development tools: testing, linting, and formatting.

GPU Support

NVIDIA CUDA:

pip install pdf2epub[full]
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

AMD ROCm:

pip install pdf2epub[full]
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/rocm6.2

📚 Documentation

• Quick Tutorial - Convert your first PDF in 5 minutes
• Installation Guide - Detailed setup instructions
• CLI Reference - Complete command-line documentation
• Python API - Library usage and examples
• Advanced Features - GPU acceleration, batch processing
• AI Integration - Enhance quality with AI postprocessing
• Plugin Development - Create custom AI providers

🎯 Use Cases

Academic Research

• Convert research papers to readable EPUB format
• Extract and preserve mathematical equations
• Maintain citation formatting and structure

Digital Publishing

• Transform print-ready PDFs into distribution-ready EPUBs
• Preserve complex layouts and formatting
• Optimize for e-reader compatibility

Document Archival

• Convert legacy documents to modern formats
• Batch process document collections
• Enhance readability with AI postprocessing

Accessibility

• Create screen-reader compatible versions
• Improve text structure and navigation
• Add semantic markup for better accessibility

🔧 Configuration

Environment Variables

# Required for AI postprocessing
export ANTHROPIC_API_KEY="your-anthropic-api-key"

# Optional: Control GPU usage
export CUDA_VISIBLE_DEVICES="0"  # Use specific GPU
export CUDA_VISIBLE_DEVICES=""   # Force CPU-only mode

API Configuration

import pdf2epub

# Configure default settings
pdf2epub.config.set_default_batch_multiplier(3)
pdf2epub.config.set_default_ai_provider("anthropic")

🧪 Testing

Run the test suite:

pytest                    # Run all tests
pytest --cov=pdf2epub   # Run with coverage
pytest tests/test_pdf2md.py  # Run specific test file

Current test coverage: 49% with 100% pass rate (41/41 tests)

🔌 Plugin System

Create custom AI postprocessing providers:

from pdf2epub.postprocessing.ai import AIPostprocessor

class CustomAIProvider:
    @staticmethod
    def getjsonparams(system_prompt: str, request: str) -> str:
        # Implement your AI API integration
        return process_with_custom_ai(system_prompt, request)

# Register and use your provider
processor = AIPostprocessor(work_dir)
processor.register_provider("custom", CustomAIProvider)
processor.run_postprocessing(markdown_file, "custom")

📊 Performance

Benchmarks

Document Type	Pages	Processing Time	Memory Usage
Research Paper	20	45 seconds	2.1 GB
Technical Book	200	6 minutes	4.8 GB
Magazine	50	2 minutes	1.9 GB

Results on NVIDIA RTX 3080 with 16GB RAM

Optimization Tips

• Use GPU acceleration for 3-5x speed improvement
• Adjust batch multiplier based on available memory
• Process in chunks for very large documents
• Enable AI postprocessing for best quality (slower)

🆚 Comparison

Feature	PDF2EPUB	calibre	pandoc
AI Enhancement	✅	❌	❌
Layout Detection	✅	⚠️	⚠️
GPU Acceleration	✅	❌	❌
Python API	✅	⚠️	⚠️
Plugin System	✅	✅	❌
CLI Interface	✅	✅	✅

🚢 Deployment

Docker

FROM python:3.11-slim

RUN pip install pdf2epub[full]

WORKDIR /workspace
ENTRYPOINT ["pdf2epub"]

GitHub Actions

- name: Convert PDFs
  run: |
    pip install pdf2epub[full]
    pdf2epub documents/*.pdf

Production Deployment

import pdf2epub
from pathlib import Path

def production_converter(pdf_path: str) -> dict:
    """Production-ready PDF conversion with error handling."""
    try:
        output_dir = pdf2epub.convert_pdf_to_markdown(
            pdf_path, 
            batch_multiplier=2,  # Conservative memory usage
            max_pages=1000      # Prevent runaway processing
        )
        
        epub_path = pdf2epub.convert_to_epub(output_dir)
        
        return {
            "status": "success",
            "markdown_path": output_dir,
            "epub_path": epub_path,
            "processing_time": time.time() - start_time
        }
        
    except Exception as e:
        return {
            "status": "error", 
            "error": str(e)
        }

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contributing Steps

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and add tests
4. Test your changes: pytest
5. Format code: black .
6. Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

This project builds upon excellent open-source libraries:

• marker-pdf - PDF processing engine
• mark2epub - Markdown to EPUB conversion
• PyTorch - GPU acceleration framework
• Transformers - AI/ML text processing
• Anthropic - AI API for text enhancement

📈 Project Status

• Version: 0.1.0 (Beta)
• Status: Active development
• Python: 3.9+ supported
• Testing: 49% coverage, 100% pass rate
• CI/CD: GitHub Actions
• Documentation: Comprehensive

🔗 Links

• PyPI Package
• GitHub Repository
• Documentation
• Issue Tracker
• Discussions
• Security Policy

📞 Support

• GitHub Issues: Report bugs or request features
• GitHub Discussions: Ask questions and get help
• Documentation: Browse the docs

---

Transform your PDFs into beautiful, accessible EPUBs with AI-powered enhancement! 🚀📚