### Setup PDFStract Development Environment

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/web-ui/overview.md

Steps to clone the PDFStract repository, install frontend dependencies, and start the development server for both frontend and backend.

```bash
# Clone repository
git clone https://github.com/aksarav/pdfstract.git
cd pdfstract

# Install frontend dependencies
cd frontend
npm install

# Start development server
npm run dev

# In another terminal, start backend
cd ..
python run.py
```

--------------------------------

### Docker Installation with Make

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/installation.md

Use the make command to set up the Docker environment for PDFStract, including downloading necessary models. This is recommended for a smooth Docker setup.

```bash
# Clone the repository
git clone https://github.com/aksarav/pdfstract.git
cd pdfstract

# Download models and start services (first time)
make up

# Or step by step:
make models   # Download HuggingFace/MinerU models (~10GB)
make build    # Build Docker images
make up       # Start services
```

--------------------------------

### Quick Start

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/cli/overview.md

Get started quickly with common PDFStract commands, including a one-command RAG pipeline.

```APIDOC
## Quick Start

```bash
# Complete RAG pipeline in one command: Extract + Chunk + Embed
pdfstract convert-chunk-embed document.pdf --library auto --chunker auto --embedding auto

# Convert a single PDF
pdfstract convert document.pdf

# Convert with specific library
pdfstract convert document.pdf --library marker

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

:::tip One Command RAG Pipeline
Use `convert-chunk-embed` to extract text, chunk it, and generate embeddings in a single command—ready for your vector database!
:::
```

--------------------------------

### Build and Start Production Server

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/web-ui/overview.md

Commands to build optimized web assets and start the production server for PDFStract.

```bash
# Build optimized web assets
cd frontend
npm run build

# Start production server
pdfstract web --host 0.0.0.0 --port 8000 --production
```

--------------------------------

### Install PDFStract

Source: https://context7.com/aksarav/pdfstract/llms.txt

Install the library with varying levels of dependency support.

```bash
# Base installation - pymupdf4llm, markitdown
pip install pdfstract

# Standard - adds OCR (pytesseract, unstructured)
pip install pdfstract[standard]

# Advanced - adds ML-powered (marker, docling, paddleocr, deepseek)
pip install pdfstract[advanced]

# Everything
pip install pdfstract[all]
```

--------------------------------

### Install Dependencies

Source: https://github.com/aksarav/pdfstract/blob/main/frontend/README.md

Run this command in your terminal to install all necessary project dependencies.

```bash
npm install
```

--------------------------------

### Start Local Development Server

Source: https://github.com/aksarav/pdfstract/blob/main/docs/README.md

Starts a local development server for live preview. Changes are reflected without a server restart.

```bash
yarn start
```

--------------------------------

### Install PDFStract

Source: https://github.com/aksarav/pdfstract/blob/main/CLI_README.md

Installation commands for different feature sets of the library.

```bash
pip install pdfstract              # Base - pymupdf4llm, markitdown
pip install pdfstract[standard]    # + OCR (pytesseract, unstructured)
pip install pdfstract[advanced]    # + ML-powered (marker, docling, paddleocr)
pip install pdfstract[all]         # Everything
```

--------------------------------

### Web UI Setup

Source: https://github.com/aksarav/pdfstract/blob/main/README.md

Clone the repository and launch the Web UI and API services.

```bash
git clone https://github.com/aksarav/pdfstract.git
cd pdfstract
make up
```

--------------------------------

### Start the web interface

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/quick-start.md

Launches the visual web interface for PDFStract.

```bash
# Start the web server
pdfstract web

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

--------------------------------

### Install PDFStract from Source

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/quick-start.md

Install PDFStract directly from its GitHub repository for development or to access the latest features.

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

--------------------------------

### Install Dependencies

Source: https://github.com/aksarav/pdfstract/blob/main/docs/README.md

Installs project dependencies using Yarn. Run this command in the project root.

```bash
yarn
```

--------------------------------

### Install PDFStract with uv

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/installation.md

Utilize uv for faster package installation of PDFStract with all dependencies.

```bash
uv pip install pdfstract[all]
```

--------------------------------

### CLI List Libraries

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/features/extract.md

List all available libraries and their installation status via the CLI.

```bash
# Show all libraries with status
pdfstract libs
```

--------------------------------

### Install GPU Support and Verify Detection

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/installation.md

Install the advanced or all tiers to enable GPU acceleration. Verify GPU detection using a Python script with PyTorch.

```bash
pip install pdfstract[advanced]
```

```python
import torch; print(f'CUDA available: {torch.cuda.is_available()}')
```

--------------------------------

### Start PDFStract Web Server

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/web-ui/overview.md

Use this command to start the PDFStract web interface. You can specify a custom port and host.

```bash
# Start PDFStract web interface
pdfstract web

# Or specify custom port
pdfstract web --port 3000

# With custom host
pdfstract web --host 0.0.0.0 --port 8080
```

--------------------------------

### Install PDFStract Full Version from Source

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/installation.md

Install the complete version of PDFStract from source, including all libraries, in development mode.

```bash
git clone https://github.com/aksarav/pdfstract.git
cd pdfstract

pip install -e ".[full]"
```

--------------------------------

### Install Advanced or All pdfstract Features

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/installation.md

Install the advanced tier for ML-powered converters or the 'all' tier for complete functionality.

```bash
pip install pdfstract[advanced]
```

```bash
pip install pdfstract[all]
```

--------------------------------

### Quick Start Pipeline

Source: https://github.com/aksarav/pdfstract/blob/main/README.md

Demonstrates the full RAG pipeline using the Python API or CLI.

```python
from pdfstract import PDFStract

pdfstract = PDFStract()

# Complete pipeline: Extract → Chunk → Embed
result = pdfstract.convert_chunk_embed('document.pdf')

# Or step by step
text = pdfstract.convert('document.pdf', library='auto')
chunks = pdfstract.chunk(text, chunker='semantic', chunk_size=512)
vectors = pdfstract.embed_texts([c['text'] for c in chunks['chunks']])
```

```bash
# CLI: Full pipeline in one command
pdfstract convert-chunk-embed document.pdf --library auto --chunker auto --embedding auto
```

--------------------------------

### Verify PDFStract Installation with CLI

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/installation.md

Use command-line interface commands to check the PDFStract installation and list available tools.

```bash
# Check installation
pdfstract --version

# List available tools
pdfstract list-converters
pdfstract list-chunkers
```

--------------------------------

### Installation

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/cli/overview.md

Install PDFStract with different tiers of functionality, from base extractors to advanced ML models and OCR.

```APIDOC
## Installation

```bash
# Base - Fast extractors (pymupdf4llm, markitdown)
pip install pdfstract

# Standard - Adds OCR (pytesseract, unstructured)
pip install pdfstract[standard]

# Advanced - ML-powered (marker, docling, paddleocr, deepseek)
pip install pdfstract[advanced]

# All - Everything including chunking
pip install pdfstract[all]
```
```

--------------------------------

### Install PDFStract All Tier

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/intro.md

Install the 'all' tier of PDFStract to include all available converters. This is recommended for users who need access to every conversion library for their RAG pipeline.

```bash
pip install pdfstract[all]
```

--------------------------------

### Install PDFStract with Pip

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/installation.md

Use pip to install PDFStract with different tiers of dependencies. The base installation includes fast extractors, while standard and advanced tiers add OCR and ML capabilities respectively. The 'all' tier includes all libraries.

```bash
pip install pdfstract

pip install pdfstract[standard]

pip install pdfstract[advanced]

pip install pdfstract[all]
```

--------------------------------

### Troubleshoot Web Interface Startup Issues

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/web-ui/overview.md

Commands to check if a port is available and how to try starting the PDFStract web interface on a different port.

```bash
# Check if port is available
lsof -i :8000

# Try different port
pdfstract web --port 8080
```

--------------------------------

### Install PDFStract with different tiers

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/cli/overview.md

Install PDFStract with base, standard, advanced, or all features. The standard tier adds OCR, while advanced includes ML-powered libraries.

```bash
pip install pdfstract
```

```bash
pip install pdfstract[standard]
```

```bash
pip install pdfstract[advanced]
```

```bash
pip install pdfstract[all]
```

--------------------------------

### Quick Start PDF Conversion

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/features/extract.md

Initialize the PDFStract client and convert a document using either the auto-selected library or a specific one.

```python
from pdfstract import PDFStract

pdfstract = PDFStract()

# Auto-select best available library
text = pdfstract.convert('document.pdf', library='auto')

# Use specific library
text = pdfstract.convert('document.pdf', library='marker')
```

--------------------------------

### JSON Output Example

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/cli/overview.md

Use the `--format json` option to get structured JSON output from `pdfstract process`. This format includes file details, converter, chunker, chunks with metadata, and processing time.

```bash
pdfstract process document.pdf --format json --output result.json
```

```json
{
  "file": "document.pdf",
  "converter": "docling",
  "chunker": "semantic", 
  "chunks": [
    {
      "chunk_id": 0,
      "text": "chunk content...",
      "metadata": {}
    }
  ],
  "total_chunks": 10,
  "processing_time": 5.2
}
```

--------------------------------

### Check pdfstract Installation

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/installation.md

Verify if pdfstract is installed in your current environment. Reinstall if necessary.

```bash
pip list | grep pdfstract
```

```bash
pip uninstall pdfstract
pip install pdfstract
```

--------------------------------

### Install missing dependencies

Source: https://github.com/aksarav/pdfstract/blob/main/docs/architecture/README.md

Use these commands to resolve ModuleNotFoundError when the openai dependency is missing.

```bash
pip install openai
```

```bash
pip install pdfstract[embeddings]
```

--------------------------------

### Verify PDFStract Installation with Python

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/installation.md

Use Python to check the installed PDFStract version and list available converters and chunkers.

```python
import pdfstract

# Check version
print(f"PDFStract version: {pdfstract.__version__}")

# List available converters
pdfstract = pdfstract.PDFStract()
print("Available converters:", pdfstract.list_converters())
print("Available chunkers:", pdfstract.list_chunkers())
```

--------------------------------

### REST API Server Management

Source: https://context7.com/aksarav/pdfstract/llms.txt

Commands to start the FastAPI server using uvicorn or docker-compose.

```bash
uvicorn main:app --host 0.0.0.0 --port 8000
```

```bash
docker-compose up
```

--------------------------------

### CLI Chunking Commands

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/features/chunk.md

Command-line interface examples for chunking text files.

```bash
# Basic chunking
pdfstract chunk text_file.txt --chunker token --size 512

# With overlap
pdfstract chunk text_file.txt --chunker token --size 512 --overlap 50

# Semantic chunking
pdfstract chunk text_file.txt --chunker semantic --size 1024
```

--------------------------------

### Start Development Server

Source: https://github.com/aksarav/pdfstract/blob/main/frontend/README.md

Use this command to launch the Vite development server, which typically runs on port 5173 and includes hot module replacement.

```bash
npm run dev
```

--------------------------------

### CLI Usage Examples

Source: https://github.com/aksarav/pdfstract/blob/main/docs/architecture/README.md

Commands for converting PDFs, listing available tools, and generating embeddings via the command line interface.

```bash
pdfstract convert <pdf> --converter marker --chunker semantic
pdfstract chunkers
pdfstract chunk "Your text here" --chunker token --chunk-size 512
pdfstract embeddings
pdfstract embed "Your text" --embedding openai
```

--------------------------------

### Install PDFStract Base Tier

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/intro.md

Install the base tier of PDFStract, which includes fast extractors like pymupdf4llm and markitdown. This is suitable for simple PDFs and fast extraction.

```bash
pip install pdfstract
```

--------------------------------

### Quick Start Chunking

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/features/chunk.md

Demonstrates the basic workflow of extracting text from a PDF and chunking it using the token method.

```python
from pdfstract import PDFStract

pdfstract = PDFStract()

# Extract and chunk in one step
text = pdfstract.convert('document.pdf', library='auto')
chunks = pdfstract.chunk(text, chunker='token', chunk_size=512)

print(f"Created {chunks['total_chunks']} chunks")
```

--------------------------------

### Install PDFStract Advanced Tier

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/intro.md

Install the advanced tier of PDFStract, which includes ML-powered converters like marker, docling, paddleocr, and deepseek. This tier provides the best quality extraction.

```bash
pip install pdfstract[advanced]
```

--------------------------------

### Quick Start: Batch process multiple files

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/cli/overview.md

Process multiple PDF files in a batch. Specify input and output directories.

```bash
pdfstract batch ./pdfs/ --output ./results/
```

--------------------------------

### Get Tool Information

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/api/overview.md

Retrieve specific configuration details for a given converter or chunker.

```python
# Get converter details
info = pdfstract.get_converter_info('marker')
print(f"Marker info: {info}")

# Get chunker details
info = pdfstract.get_chunker_info('semantic')
print(f"Semantic chunker: {info}")
```

--------------------------------

### Install PDFStract Standard Tier

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/intro.md

Install the standard tier of PDFStract, which adds OCR capabilities using pytesseract and unstructured. This tier is recommended for structured documents requiring OCR.

```bash
pip install pdfstract[standard]
```

--------------------------------

### Token Chunker Configuration

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/features/chunk.md

Example usage of the token chunker with specific size and overlap parameters.

```python
chunks = pdfstract.chunk(text, 
    chunker='token',
    chunk_size=512,      # Target tokens per chunk
    chunk_overlap=50     # Overlap between chunks
)
```

--------------------------------

### Create and Activate Conda Environment

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/installation.md

Use Conda to create a new environment with a specific Python version and install pdfstract.

```bash
conda create -n pdfstract python=3.10
conda activate pdfstract
```

```bash
pip install pdfstract
```

--------------------------------

### Library Management

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/features/extract.md

Methods to query available extraction libraries and their installation status.

```APIDOC
## list_libraries() / list_available_libraries()

### Description
Retrieves a list of all supported libraries or only those currently available in the environment.

### Response
- **libraries** (list) - A list of library objects containing name and availability status.
```

--------------------------------

### Basic Python Chunking API

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/features/chunk.md

Examples of different chunking configurations including overlap and semantic boundaries.

```python
from pdfstract import PDFStract

pdfstract = PDFStract()

# Simple token chunking
chunks = pdfstract.chunk(text, chunker='token', chunk_size=512)

# With overlap for context preservation
chunks = pdfstract.chunk(text, chunker='token', chunk_size=512, chunk_overlap=50)

# Semantic chunking for better boundaries
chunks = pdfstract.chunk(text, chunker='semantic', chunk_size=1024)
```

--------------------------------

### Quick Start: Convert a single PDF

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/cli/overview.md

Convert a single PDF file to text. You can specify a particular conversion library if needed.

```bash
pdfstract convert document.pdf
```

```bash
pdfstract convert document.pdf --library marker
```

--------------------------------

### Semantic Chunker Configuration

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/features/chunk.md

Example usage of the semantic chunker for AI-based boundary detection.

```python
chunks = pdfstract.chunk(text,
    chunker='semantic',
    chunk_size=1024
)
```

--------------------------------

### Markdown Output Format Example

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/features/extract.md

Convert a PDF to markdown format using the specified library.

```python
# Markdown (default)
md = pdfstract.convert('doc.pdf', library='marker', output_format='markdown')
```

--------------------------------

### Quick Start PDF Processing

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/api/overview.md

Perform a basic workflow of converting a PDF file to text and then chunking the resulting text.

```python
from pdfstract import PDFStract

# Initialize
pdfstract = PDFStract()

# Convert PDF to text
text = pdfstract.convert('document.pdf', library='docling')

# Chunk the text
chunks = pdfstract.chunk(text, 
                        chunker='semantic',
                        chunk_size=512,
                        chunk_overlap=50)

print(f"Converted PDF to {chunks['total_chunks']} chunks")
```

--------------------------------

### Docker Commands for PDFStract

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/web-ui/overview.md

Recommended Docker commands for managing PDFStract services, including starting, viewing logs, and stopping.

```bash
# Using make (downloads models + builds + starts)
make up

# Other useful commands:
make logs     # View container logs
make down     # Stop services
make status   # Show running containers
make rebuild  # Rebuild and restart
```

--------------------------------

### Store Embeddings in Vector Database

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/features/embed.md

Example demonstrating how to store processed chunks and embeddings into ChromaDB.

```python
from pdfstract import PDFStract
import chromadb  # Example: ChromaDB

pdfstract = PDFStract()

# Process document
result = pdfstract.convert_chunk_embed(
    'document.pdf',
    library='marker',
    chunker='semantic',
    embedding='sentence-transformers'
)

# Store in ChromaDB
client = chromadb.Client()
collection = client.create_collection("documents")

for chunk in result['chunking_result']['chunks']:
    collection.add(
        ids=[f"chunk_{chunk['chunk_id']}"],
        embeddings=[chunk['embedding']],
        documents=[chunk['text']],
        metadatas=[{'source': 'document.pdf', 'chunk_id': chunk['chunk_id']}]
    )

# Query
results = collection.query(
    query_embeddings=[pdfstract.embed_text("What is machine learning?")],
    n_results=5
)
```

--------------------------------

### GET /list_libraries

Source: https://context7.com/aksarav/pdfstract/llms.txt

Retrieve a list of available PDF extraction libraries supported by the current installation.

```APIDOC
## GET /list_libraries

### Description
Lists all available extraction libraries and their status.

### Method
GET

### Response
#### Success Response (200)
- **libraries** (list) - A list of dictionaries containing library names and availability status.
```

--------------------------------

### Text Output Example

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/cli/overview.md

The default output format for `pdfstract convert` is plain text, which is sent to standard output or a specified file.

```bash
pdfstract convert document.pdf
# Outputs plain text to stdout or file
```

--------------------------------

### Quick Start: One-command RAG pipeline

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/cli/overview.md

Execute a complete RAG pipeline including text extraction, chunking, and embedding generation with a single command. Auto-selection of tools is enabled by default.

```bash
pdfstract convert-chunk-embed document.pdf --library auto --chunker auto --embedding auto
```

--------------------------------

### Initialize PDFStract and List Libraries

Source: https://context7.com/aksarav/pdfstract/llms.txt

Initialize the main API entry point and inspect available extraction libraries.

```python
from pdfstract import PDFStract

# Initialize PDFStract
pdfstract = PDFStract()

# List available extraction libraries
libraries = pdfstract.list_libraries()
for lib in libraries:
    status = "Available" if lib['available'] else "Unavailable"
    print(f"{lib['name']}: {status}")

# List only available library names
available = pdfstract.list_available_libraries()
print(f"Ready to use: {available}")
# Output: ['pymupdf4llm', 'markitdown', 'marker', 'docling', ...]
```

--------------------------------

### Build for Production

Source: https://github.com/aksarav/pdfstract/blob/main/frontend/README.md

Execute this command to create a production build of the frontend. The output will be placed in the ../static directory for serving by FastAPI.

```bash
npm run build
```

--------------------------------

### List Available Tools

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/api/overview.md

Retrieve lists of supported conversion libraries and chunking methods.

```python
# List conversion libraries
converters = pdfstract.list_converters()
print("Available converters:", converters)

# List chunking methods  
chunkers = pdfstract.list_chunkers()
print("Available chunkers:", chunkers)
```

--------------------------------

### Create and Activate Python Virtual Environment

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/installation.md

Set up a dedicated virtual environment for pdfstract to manage dependencies. Activate it using the appropriate command for your OS.

```bash
python -m venv pdfstract-env
source pdfstract-env/bin/activate  # Linux/Mac
# pdfstract-env\Scripts\activate     # Windows
```

```bash
pip install pdfstract
```

--------------------------------

### GET /health

Source: https://context7.com/aksarav/pdfstract/llms.txt

Performs a health check on the API server.

```APIDOC
## GET /health

### Description
Checks the status of the API server.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The current status of the service (e.g., "healthy")

#### Response Example
{
  "status": "healthy"
}
```

--------------------------------

### List Available Providers

Source: https://github.com/aksarav/pdfstract/blob/main/docs/architecture/README.md

Commands to list available converters, chunkers, and embedding providers.

```bash
pdfstract converters list
pdfstract chunkers list
pdfstract embeddings-list
```

--------------------------------

### Batch Processing for Amortized Startup Cost

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/cli/overview.md

Process multiple documents efficiently by using batch mode. Subsequent files have reduced startup costs as the library remains loaded.

```bash
pdfstract batch ./docs --library unstructured --parallel 4
```

--------------------------------

### Sentence Chunker Configuration

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/features/chunk.md

Example usage of the sentence chunker to preserve sentence boundaries.

```python
chunks = pdfstract.chunk(text,
    chunker='sentence',
    chunk_size=512
)
```

--------------------------------

### List Available PDF Converters

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/cli/overview.md

Use the `pdfstract libs` command to see all available PDF conversion libraries. Common options include `docling`, `marker`, `pymupdf4llm`, `unstructured`, and `paddleocr`.

```bash
pdfstract libs
```

--------------------------------

### Build Static Website

Source: https://github.com/aksarav/pdfstract/blob/main/docs/README.md

Generates static website content into the 'build' directory. This output can be hosted anywhere.

```bash
yarn build
```

--------------------------------

### Main Commands

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/cli/overview.md

Detailed documentation for the main PDFStract commands: convert, chunk, convert-chunk, convert-chunk-embed, and batch.

```APIDOC
## Main Commands

### convert

Convert a single PDF to text:

```bash
# Auto mode (selects best available library)
pdfstract convert document.pdf --library auto

# With specific converter
pdfstract convert document.pdf --library docling

# Save to specific file
pdfstract convert document.pdf --library marker --output result.txt

# Convert specific pages
pdfstract convert document.pdf --library auto --pages 1-5,10
```

:::tip Auto Library Selection
Use `--library auto` to automatically select the best available converter based on your installation tier. This makes your commands portable across different environments!
:::

### chunk

Chunk text using various methods:

```bash
# Auto mode (selects best available chunker)
pdfstract chunk text_file.txt --chunker auto

# With specific chunker
pdfstract chunk text_file.txt --chunker semantic --size 512

# Chunk PDF directly with auto selection
pdfstract chunk document.pdf --chunker auto --overlap 50

# Recursive chunking
pdfstract chunk document.pdf --chunker recursive --overlap 50
```

:::tip Auto Chunker Selection
Use `--chunker auto` to automatically select the best available chunking method. Great for scripts that need to work across different installations!
:::

### convert-chunk

Convert and chunk in one command:

```bash
# One-step processing
pdfstract convert-chunk document.pdf --chunker semantic --chunk-size 1024

# With specific tools
pdfstract convert-chunk document.pdf \
  --library marker \
  --chunker semantic \
  --chunk-size 512 \
  --chunk-overlap 100
```

### convert-chunk-embed

Complete RAG pipeline: convert PDF, chunk text, and generate embeddings:

```bash
# 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 \
  --chunk-overlap 50 \
  --output result.json

# Using OpenAI embeddings
pdfstract convert-chunk-embed document.pdf \
  --library docling \
  --chunker token \
  --embedding openai \
  --output chunks_with_vectors.json

# Save converted text separately
pdfstract convert-chunk-embed document.pdf \
  --library marker \
  --embedding sentence-transformers \
  --save-converted converted_text.md
```

**Options:**
- `--library, -l`: PDF conversion library (default: auto)
- `--chunker, -c`: Chunking method (default: auto)
- `--embedding, -e`: Embedding provider (default: auto)
- `--chunk-size`: Target chunk size in tokens (default: 512)
- `--chunk-overlap`: Overlap between chunks (default: 50)
- `--format, -f`: Output format (markdown, text, json)
- `--output, -o`: Save results to JSON file
- `--save-converted`: Save converted text to separate file

**Available Embedding Providers:**
- `sentence-transformers` - Local, no API key needed
- `openai` - Requires `OPENAI_API_KEY`
- `azure-openai` - Requires `AZURE_OPENAI_API_KEY`
- `google-generative` - Requires `GOOGLE_API_KEY`
- `ollama` - Requires local Ollama daemon

### batch

Process multiple files:

```bash
# Basic batch processing
pdfstract batch ./input-folder/ --output ./output-folder/

# With parallel processing
pdfstract batch ./pdfs/ --output ./results/ --parallel 4

# With specific tools
pdfstract batch ./docs/ \
  --converter docling \
  --chunker semantic \
  --size 1024
```
```

--------------------------------

### Initialize PDFStract

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/api/overview.md

Instantiate the main PDFStract class with default or custom configuration settings.

```python
from pdfstract import PDFStract

# Initialize with default settings
pdfstract = PDFStract()

# Or with custom configuration
pdfstract = PDFStract(
    default_converter='marker',
    default_chunker='semantic',
    cache_dir='./cache',
    max_workers=4
)
```

--------------------------------

### Fastest Conversions with Specific Libraries

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/cli/overview.md

Use the `--library` option to select the fastest converters for quick document processing. `pymupdf4llm` is generally the fastest.

```bash
pdfstract convert file.pdf --library pymupdf4llm   # Fastest (~3s)
```

```bash
pdfstract convert file.pdf --library markitdown    # Fast (~4s)
```

```bash
pdfstract convert file.pdf --library marker        # Quality (~8s)
```

--------------------------------

### Check and prepare models via Python API

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/features/extract.md

Verify the download status of a converter and trigger model preparation programmatically.

```python
# Check download status
pdfstract = PDFStract()
status = pdfstract.get_converter_status('marker')
print(f"Download status: {status['download_status']}")

# Prepare/download models
result = pdfstract.prepare_converter('marker')
print(f"Ready: {result['success']}")
```

--------------------------------

### Quick Start Embedding

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/features/embed.md

Basic usage for embedding single or multiple text strings using the PDFStract library.

```python
from pdfstract import PDFStract

pdfstract = PDFStract()

# Embed text with auto-selected provider
vectors = pdfstract.embed_texts(["Hello world", "Another sentence"], model='auto')

# Embed single text
vector = pdfstract.embed_text("Hello world", model='sentence-transformers')
print(f"Embedding dimension: {len(vector)}")
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/features/embed.md

Set required API keys and model preferences for various embedding providers in your environment.

```bash
# OpenAI
export OPENAI_API_KEY=sk-your-key-here
export OPENAI_EMBEDDING_MODEL=text-embedding-3-small  # Optional

# Azure OpenAI
export AZURE_OPENAI_API_KEY=your-azure-key
export AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
export AZURE_OPENAI_EMBEDDING_MODEL=text-embedding-3-large  # Optional
export AZURE_OPENAI_API_VERSION=2024-02-01  # Optional

# Google Generative AI
export GOOGLE_API_KEY=your-google-key
export GOOGLE_EMBEDDING_MODEL=gemini-embedding-001  # Optional

# Ollama (local)
export OLLAMA_HOST=http://localhost:11434
export OLLAMA_MODEL=nomic-embed-text  # Optional

# Sentence Transformers
export SENTENCE_TRANSFORMERS_MODEL=all-MiniLM-L6-v2  # Optional
```

--------------------------------

### List available converters

Source: https://github.com/aksarav/pdfstract/blob/main/docs/architecture/README.md

Run this command to identify valid converter names when encountering a ValueError.

```bash
pdfstract converters list
```

--------------------------------

### Deploy Website (SSH)

Source: https://github.com/aksarav/pdfstract/blob/main/docs/README.md

Builds and deploys the website to the 'gh-pages' branch using SSH. Assumes GitHub Pages hosting.

```bash
USE_SSH=true yarn deploy
```

--------------------------------

### Extract PDF Content

Source: https://github.com/aksarav/pdfstract/blob/main/CLI_README.md

Examples for extracting text from PDFs using specific libraries, batch processing, or asynchronous calls.

```python
# Auto-select best available library
text = pdfstract.convert('document.pdf', library='auto')

# Use specific library
text = pdfstract.convert('document.pdf', library='marker')
text = pdfstract.convert('document.pdf', library='docling', output_format='json')

# Batch processing
results = pdfstract.batch_convert('./pdfs', library='pymupdf4llm', parallel_workers=4)

# Async
text = await pdfstract.convert_async('document.pdf', library='marker')
```

--------------------------------

### CLI List Providers

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/features/embed.md

List available embedding providers via the CLI.

```bash
pdfstract embeddings-list
```

--------------------------------

### Deploy Website (No SSH)

Source: https://github.com/aksarav/pdfstract/blob/main/docs/README.md

Builds and deploys the website to the 'gh-pages' branch without SSH. Requires specifying your GitHub username.

```bash
GIT_USER=<Your GitHub username> yarn deploy
```

--------------------------------

### Extract text using specific libraries

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/features/extract.md

Examples of using different backends for document extraction based on document complexity and requirements.

```python
text = pdfstract.convert('simple.pdf', library='pymupdf4llm')
```

```python
text = pdfstract.convert('complex.pdf', library='marker')
```

```python
text = pdfstract.convert('report.pdf', library='docling')
```

```python
text = pdfstract.convert('form.pdf', library='unstructured')
```

```python
text = pdfstract.convert('scanned.pdf', library='paddleocr')
```

--------------------------------

### Manage model downloads via CLI

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/features/extract.md

Download required models for specific libraries or all available models using the command line interface.

```bash
# Download models for specific library
pdfstract download marker
pdfstract download docling

# Download all available models
pdfstract download --all
```

--------------------------------

### Enable Debug Logging

Source: https://github.com/aksarav/pdfstract/blob/main/docs/architecture/README.md

Set the log level to DEBUG and run a conversion command to troubleshoot issues.

```bash
export LOG_LEVEL=DEBUG
pdfstract convert document.pdf
```

--------------------------------

### API Response Format

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/web-ui/overview.md

Example JSON response format for API requests, including success status, extracted text, chunk details, and processing statistics.

```json
{
  "success": true,
  "data": {
    "text": "extracted text...",
    "chunks": [
      {
        "chunk_id": 0,
        "text": "chunk content...",
        "metadata": {
          "tokens": 487,
          "start_pos": 0,
          "end_pos": 512
        }
      }
    ],
    "stats": {
      "total_chunks": 15,
      "total_tokens": 7320,
      "processing_time": 3.2,
      "converter_used": "docling",
      "chunker_used": "semantic"
    }
  }
}
```

--------------------------------

### CLI Library Comparison

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/features/extract.md

Compare the output of multiple libraries on the same document.

```bash
# Compare multiple libraries on same document
pdfstract compare document.pdf --libraries marker,docling,pymupdf4llm
```

--------------------------------

### Recursive Chunking for Structured Documents

Source: https://context7.com/aksarav/pdfstract/llms.txt

Use recursive chunking for documents with a clear hierarchical structure. This method breaks down text based on a list of separators, starting with the broadest.

```python
recursive_chunks = pdfstract.chunk(
    text,
    chunker='recursive',
    chunk_size=512,
    separators=['\n\n', '\n', '. ', ' ']
)
```

--------------------------------

### List Available Libraries

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/features/extract.md

Retrieve and display the status of all supported extraction libraries.

```python
from pdfstract import PDFStract

pdfstract = PDFStract()

# Get all libraries with status
libraries = pdfstract.list_libraries()
for lib in libraries:
    status = "✓" if lib['available'] else "✗"
    print(f"{status} {lib['name']}")

# Get only available library names
available = pdfstract.list_available_libraries()
print(f"Available: {available}")
```

--------------------------------

### GitHub Actions Workflow for Document Processing

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/cli/overview.md

Integrate PDFStract into a CI/CD pipeline using GitHub Actions. This workflow checks out code, sets up Python, installs PDFStract, and runs a batch processing job on documents.

```yaml
name: Process Documents
on: [push]
jobs:
  process:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-python@v2
        with:
          python-version: '3.10'
      - run: pip install pdfstract
      - run: pdfstract batch ./docs --output ./processed
```

--------------------------------

### Shell Script for Batch PDF Processing

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/cli/overview.md

Automate the processing of multiple PDF files in a directory using a bash script. This example iterates through PDFs, applies specific converters and chunkers, and saves output as JSON.

```bash
#!/bin/bash
# Process all PDFs in inbox
for pdf in inbox/*.pdf; do
    echo "Processing $pdf..."
    pdfstract process "$pdf" \
        --converter docling \
        --chunker semantic \
        --output "processed/$(basename "$pdf" .pdf).json"
done
```

--------------------------------

### Configure Embedding Providers

Source: https://context7.com/aksarav/pdfstract/llms.txt

Set environment variables to authenticate and configure various cloud-based or local embedding models before initializing the PDFStract instance.

```python
import os
from pdfstract import PDFStract

# OpenAI configuration
os.environ['OPENAI_API_KEY'] = 'sk-your-key'
os.environ['OPENAI_EMBEDDING_MODEL'] = 'text-embedding-3-small'  # or text-embedding-3-large

# Azure OpenAI configuration
os.environ['AZURE_OPENAI_API_KEY'] = 'your-azure-key'
os.environ['AZURE_OPENAI_ENDPOINT'] = 'https://your-resource.openai.azure.com/'
os.environ['AZURE_OPENAI_EMBEDDING_MODEL'] = 'text-embedding-3-large'
os.environ['AZURE_OPENAI_API_VERSION'] = '2024-02-01'

# Google Generative AI configuration
os.environ['GOOGLE_API_KEY'] = 'your-google-key'
os.environ['GOOGLE_EMBEDDING_MODEL'] = 'gemini-embedding-001'

# Ollama configuration (local)
os.environ['OLLAMA_HOST'] = 'http://localhost:11434'
os.environ['OLLAMA_MODEL'] = 'nomic-embed-text'

# Sentence Transformers configuration (local, no API key needed)
os.environ['SENTENCE_TRANSFORMERS_MODEL'] = 'all-MiniLM-L6-v2'

pdfstract = PDFStract()
texts = ["Sample text for embedding"]

# Use different providers
openai_vecs = pdfstract.embed_texts(texts, model='openai')        # 1536/3072 dims
azure_vecs = pdfstract.embed_texts(texts, model='azure-openai')   # 1536/3072 dims
google_vecs = pdfstract.embed_texts(texts, model='google-generative')  # 768 dims
ollama_vecs = pdfstract.embed_texts(texts, model='ollama')        # varies
local_vecs = pdfstract.embed_texts(texts, model='sentence-transformers')  # 384/768 dims
```

--------------------------------

### Convert and chunk with specific tools and sizes

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/cli/overview.md

Perform conversion and chunking using specified libraries and chunking methods, with custom size and overlap.

```bash
pdfstract convert-chunk document.pdf \
  --library marker \
  --chunker semantic \
  --chunk-size 512 \
  --chunk-overlap 100
```

--------------------------------

### CLI List Chunkers

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/features/chunk.md

List all available chunkers via the CLI.

```bash
pdfstract chunkers
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/aksarav/pdfstract/blob/main/docs/architecture/README.md

Set required environment variables for converters, embedding providers, and logging configuration.

```bash
# Converters
export DOCLING_API_KEY=<key>           # if using remote Docling
export PADDLE_OCR_LANG=en              # PaddleOCR language

# Embeddings
export OPENAI_API_KEY=<key>
export AZURE_OPENAI_API_KEY=<key>
export AZURE_OPENAI_ENDPOINT=<url>
export GOOGLE_API_KEY=<key>
export OLLAMA_BASE_URL=http://localhost:11434

# Logging
export LOG_LEVEL=INFO
export LOG_DIR=~/.pdfstract/logs
```

--------------------------------

### Full RAG pipeline with auto-selection

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/cli/overview.md

Execute the complete RAG pipeline (convert, chunk, embed) using automatic selection for all tools.

```bash
pdfstract convert-chunk-embed document.pdf
```

--------------------------------

### Using TOML Configuration with PDFStract CLI

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/cli/overview.md

Specify a TOML configuration file to customize PDFStract's behavior. This command loads settings from `pdfstract.toml` for document conversion.

```bash
pdfstract --config pdfstract.toml convert document.pdf
```

--------------------------------

### CLI Commands

Source: https://github.com/aksarav/pdfstract/blob/main/README.md

Perform extraction, chunking, and comparison tasks directly from the command line.

```bash
# List available tools
pdfstract libs
pdfstract chunkers
pdfstract embeddings-list

# Extract
pdfstract convert document.pdf --library marker

# Chunk
pdfstract convert-chunk document.pdf --library docling --chunker semantic

# Full pipeline
pdfstract convert-chunk-embed document.pdf --embedding sentence-transformers

# Batch processing
pdfstract batch ./pdfs --library pymupdf4llm --parallel 4

# Compare libraries
pdfstract compare sample.pdf -l marker -l docling -l pymupdf4llm
```

--------------------------------

### Convert and chunk PDF in one step

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/cli/overview.md

Combine PDF conversion and text chunking into a single command. Specify chunker and chunk size.

```bash
pdfstract convert-chunk document.pdf --chunker semantic --chunk-size 1024
```

--------------------------------

### CLI Command Reference

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/cli/overview.md

Overview of the primary CLI commands for document conversion, batch processing, and pipeline management.

```APIDOC
## CLI Commands

### Convert Single Document
`pdfstract convert [FILE] [OPTIONS]`
- **--library, -l**: Specify conversion library (e.g., docling, marker, pymupdf4llm).
- **--output, -o**: Specify output file path.

### Batch Processing
`pdfstract batch [DIR] [OPTIONS]`
- **--parallel, -p**: Number of parallel workers.
- **--pattern**: File pattern to match (e.g., "*.pdf").

### RAG Pipeline
`pdfstract convert-chunk-embed [FILE] [OPTIONS]`
- **--chunker, -c**: Chunking method (e.g., semantic, token).
- **--embedding**: Embedding provider (e.g., sentence-transformers, openai).
```

--------------------------------

### Configure PDFStract Environment Variables

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/web-ui/overview.md

Set these environment variables to configure the PDFStract web server and processing settings.

```bash
# Server settings
export PDFSTRACT_HOST=0.0.0.0
export PDFSTRACT_PORT=8000
export PDFSTRACT_DEBUG=false

# Processing settings  
export PDFSTRACT_MAX_FILE_SIZE=50MB
export PDFSTRACT_TIMEOUT=300
export PDFSTRACT_CACHE_DIR=/tmp/pdfstract

# Security
export PDFSTRACT_CORS_ORIGINS=http://localhost:3000
export PDFSTRACT_API_KEY_REQUIRED=false
```

--------------------------------

### Initialize and Use Python API

Source: https://github.com/aksarav/pdfstract/blob/main/CLI_README.md

Basic usage of the PDFStract class for extraction, chunking, and embedding workflows.

```python
from pdfstract import PDFStract

pdfstract = PDFStract()

# Extract
text = pdfstract.convert('document.pdf', library='auto')

# Chunk
chunks = pdfstract.chunk(text, chunker='semantic', chunk_size=512)

# Embed
vectors = pdfstract.embed_texts([c['text'] for c in chunks['chunks']])

# Combined pipelines
result = pdfstract.convert_chunk('document.pdf', library='marker', chunker='token')
result = pdfstract.convert_chunk_embed('document.pdf', embedding='sentence-transformers')
```

--------------------------------

### PDFStract TOML Configuration

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/cli/overview.md

Define default settings, batch processing options, and output preferences in a `pdfstract.toml` file. This configuration is loaded when the `--config` flag is used.

```toml
[defaults]
converter = "docling"
chunker = "semantic"
chunk_size = 512
chunk_overlap = 50

[batch]
parallel_workers = 4
continue_on_error = true

[output]
format = "json"
include_metadata = true
```

--------------------------------

### Enable Verbose Logging for PDFStract

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/web-ui/overview.md

Run the PDFStract web interface with the --verbose flag to enable detailed logging for troubleshooting conversion errors.

```bash
pdfstract web --verbose
```

--------------------------------

### Full RAG Pipeline Preparation with Embeddings

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/cli/overview.md

Execute the full RAG pipeline, including conversion, chunking, and embedding generation, using `pdfstract convert-chunk-embed`. Specify the embedding provider and output format.

```bash
# Full pipeline with embeddings
pdfstract convert-chunk-embed document.pdf \
  --library marker \
  --chunker semantic \
  --embedding sentence-transformers \
  --chunk-size 512 \
  --output ready_for_vectordb.json
```

--------------------------------

### Configure PDFStract settings

Source: https://github.com/aksarav/pdfstract/blob/main/docs/docs/api/overview.md

Sets global defaults or instance-specific configurations for PDFStract.

```python
from pdfstract import PDFStract, set_global_config

# Set global defaults
set_global_config(
    default_converter='docling',
    default_chunker='semantic',
    cache_enabled=True,
    max_workers=6
)

# All instances will use these defaults
pdfstract = PDFStract()
```

```python
# Configure specific instance
pdfstract = PDFStract(
    default_converter='marker',
    default_chunker='recursive', 
    cache_dir='./my-cache',
    max_workers=2,
    timeout=300
)
```