pdf2epub 0.1.2
Convert PDF files to EPUB format via Markdown with intelligent layout detection
License: MIT
Requires Python: >=3.10
Keywords: pdf, epub, markdown, conversion, ebook, ai, postprocessing

# PDF2EPUB 📚

[![PyPI version](https://badge.fury.io/py/pdf2epub.svg)](https://badge.fury.io/py/pdf2epub)
[![CI/CD Pipeline](https://github.com/porfanid/pdf2epub/actions/workflows/ci.yml/badge.svg)](https://github.com/porfanid/pdf2epub/actions/workflows/ci.yml)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
# Basic installation
pip install pdf2epub

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

### Command Line Usage

```bash
# 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:
```bash
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:
```bash
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:
```python
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
```bash
pip install pdf2epub
```
Includes core functionality with minimal dependencies.

### Full Installation
```bash
pip install pdf2epub[full]
```
Includes all features: PDF processing, AI postprocessing, and GPU acceleration.

### Development Installation
```bash
pip install pdf2epub[dev]
```
Includes development tools: testing, linting, and formatting.

### GPU Support

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

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

## 📚 Documentation

- **[Quick Tutorial](docs/tutorial.md)** - Convert your first PDF in 5 minutes
- **[Installation Guide](docs/installation.md)** - Detailed setup instructions
- **[CLI Reference](docs/cli.md)** - Complete command-line documentation
- **[Python API](docs/api.md)** - Library usage and examples
- **[Advanced Features](docs/guides/advanced-features.md)** - GPU acceleration, batch processing
- **[AI Integration](docs/ai/overview.md)** - Enhance quality with AI postprocessing
- **[Plugin Development](docs/developers/plugins.md)** - 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

```bash
# 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

```python
import pdf2epub

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

## 🧪 Testing

Run the test suite:
```bash
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:

```python
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

```dockerfile
FROM python:3.11-slim

RUN pip install pdf2epub[full]

WORKDIR /workspace
ENTRYPOINT ["pdf2epub"]
```

### GitHub Actions

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

### Production Deployment

```python
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](CONTRIBUTING.md) 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](CONTRIBUTING.md) for detailed guidelines.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

This project builds upon excellent open-source libraries:

- **[marker-pdf](https://github.com/VikParuchuri/marker)** - PDF processing engine
- **[mark2epub](https://github.com/AlexPof/mark2epub)** - Markdown to EPUB conversion  
- **[PyTorch](https://pytorch.org/)** - GPU acceleration framework
- **[Transformers](https://huggingface.co/transformers)** - AI/ML text processing
- **[Anthropic](https://www.anthropic.com/)** - 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](https://pypi.org/project/pdf2epub/)**
- **[GitHub Repository](https://github.com/porfanid/pdf2epub)**
- **[Documentation](docs/README.md)**
- **[Issue Tracker](https://github.com/porfanid/pdf2epub/issues)**
- **[Discussions](https://github.com/porfanid/pdf2epub/discussions)**
- **[Security Policy](SECURITY.md)**

## 📞 Support

- **GitHub Issues**: [Report bugs or request features](https://github.com/porfanid/pdf2epub/issues)
- **GitHub Discussions**: [Ask questions and get help](https://github.com/porfanid/pdf2epub/discussions)
- **Documentation**: [Browse the docs](docs/README.md)

---

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