Quick Start

Get up and running with PDFStract in just a few minutes! This guide covers the complete data preparation pipeline — Extract, Chunk, and Embed — to get your PDFs ready for RAG.

Prerequisites

• Python 3.11 or higher
• pip (Python package installer)

Installation

PDFStract offers tiered installation based on your needs:

Tier	Libraries	Install Command
Base	pymupdf4llm, markitdown	pip install pdfstract
Standard	pytesseract, unstructured	pip install pdfstract[standard]
Advanced	marker, docling, paddleocr, deepseek	pip install pdfstract[advanced]
All	All libraries combined	pip install pdfstract[all]

# Quick start with base libraries
pip install pdfstract

# Recommended for most users
pip install pdfstract[standard]

# Best quality (larger download)
pip install pdfstract[advanced]

# All converters combined
pip install pdfstract[all]

For development or latest features:

git clone https://github.com/aksarav/pdfstract.git
cd pdfstract
pip install -e .

Your First Conversion

Let's convert a PDF to text using the simplest approach:

from pdfstract import PDFStract

# Initialize PDFStract
pdfstract = PDFStract()

# Convert PDF to text (use 'auto' to select best available library)
text = pdfstract.convert('your-document.pdf', library='auto')

print("Extracted text:")
print(text[:500] + "...")  # Show first 500 characters

Auto Mode

Set library='auto' to automatically select the best available converter based on priority: pymupdf4llm → markitdown → marker → docling → etc. This ensures your code works regardless of which tier you installed!

Create Your First Chunks

Now let's chunk that text for RAG applications:

# Chunk the text for RAG (use 'auto' to select best available chunker)
chunks = pdfstract.chunk(text, chunker='auto', chunk_size=512, chunk_overlap=50)

print(f"Created {chunks['total_chunks']} chunks")
print("First chunk:")
print(chunks['chunks'][0]['text'][:200] + "...")

Auto Mode for Chunking

Set chunker='auto' to automatically select the best available method (typically token chunker). For semantic chunking, explicitly specify chunker='semantic'.

Generate Embeddings

PDFStract supports multiple embedding providers for vector search and RAG pipelines.

from pdfstract import PDFStract

pdfstract = PDFStract()

# Embed multiple texts
vectors = pdfstract.embed_texts(["First sentence", "Second sentence"], model='auto')
print(f"Dimension: {len(vectors[0])}")

# Embed single text
vector = pdfstract.embed_text("Hello world", model='sentence-transformers')

Available Providers

Provider	Type	Setup
sentence-transformers	Local	No setup needed
openai	Cloud	OPENAI_API_KEY
azure-openai	Cloud	AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT
google-generative	Cloud	GOOGLE_API_KEY
ollama	Local	Local Ollama daemon

Local Embeddings

Use model='sentence-transformers' for free, local embeddings with no API key required!

Complete RAG Pipeline

Combine all three steps (extract, chunk, embed) in one call:

Python API

from pdfstract import PDFStract

pdfstract = PDFStract()

# Convert + Chunk + Embed in one step
result = pdfstract.convert_chunk_embed(
    'document.pdf',
    library='marker',
    chunker='semantic',
    embedding='sentence-transformers',
    chunker_params={'chunk_size': 512}
)

print(f"Chunks: {result['chunking_result']['total_chunks']}")
print(f"Embeddings: {len(result['embeddings'])} vectors")

# Each chunk has its embedding attached
for chunk in result['chunking_result']['chunks']:
    print(f"Chunk {chunk['chunk_id']}: {len(chunk['embedding'])} dimensions")

CLI

# Full pipeline with auto-selection
pdfstract convert-chunk-embed document.pdf

# With specific options
pdfstract convert-chunk-embed document.pdf \
  --library marker \
  --chunker semantic \
  --embedding sentence-transformers \
  --chunk-size 512 \
  --output result.json

# Using OpenAI embeddings (requires OPENAI_API_KEY)
pdfstract convert-chunk-embed document.pdf \
  --library docling \
  --embedding openai \
  --output chunks_with_vectors.json

The output JSON contains extracted text, chunks, and embedding vectors ready for your vector database.

Available Libraries by Tier

Base (pip install pdfstract)

• pymupdf4llm - Fast and lightweight
• markitdown - Microsoft's markdown converter

Standard (pip install pdfstract[standard])

• All Base libraries plus:
• pytesseract - OCR for scanned PDFs
• unstructured - Smart document parsing

Advanced (pip install pdfstract[advanced])

• All Standard libraries plus:
• marker - Excellent for complex layouts
• docling - IBM's document intelligence
• paddleocr - Accurate OCR engine
• deepseek - GPU-accelerated OCR

Example with specific tools:

# Use Marker for PDF conversion and semantic chunking
text = pdfstract.convert('document.pdf', library='marker')
chunks = pdfstract.chunk(text, chunker='semantic', chunk_size=1024)

Web Interface

Try the visual interface:

# Start the web server
pdfstract web

# Open http://localhost:8000 in your browser

CLI Usage

Use PDFStract from the command line:

# Convert a single PDF
pdfstract convert document.pdf

# Convert and chunk in one command
pdfstract process document.pdf --chunker semantic --chunk-size 512

# Batch process multiple files
pdfstract batch ./pdfs/ --output ./results/

Next Steps

Now that you have the basics down, explore more advanced features:

Feature Guides

• Extract - All PDF conversion options and libraries
• Chunk - Text chunking methods and parameters
• Embed - Embedding providers and configuration

Interface Guides

• Python API - Complete module reference
• CLI Guide - Full command-line interface
• Web UI - Using the visual interface
• Installation Guide - Advanced installation options

Common Use Cases

For RAG Applications

# Optimized for RAG pipelines
text = pdfstract.convert('research-paper.pdf', library='docling')
chunks = pdfstract.chunk(text, 
                        chunker='semantic', 
                        chunk_size=512,
                        chunk_overlap=100)

# Chunks are ready for embedding!
for chunk in chunks['chunks']:
    print(f"Chunk {chunk['chunk_id']}: {len(chunk['text'])} chars")

For Document Analysis

# Extract with structure preservation  
text = pdfstract.convert('report.pdf', 
                        library='unstructured',
                        preserve_structure=True)

# Use recursive chunking to maintain context
chunks = pdfstract.chunk(text, chunker='recursive')

Ready to dive deeper? Check out the detailed guides for your specific use case! 🚀