> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upsonic.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# PdfPlumber Loader

> Load PDF documents using pdfplumber for superior table extraction

## Overview

PdfPlumber loader excels at extracting structured content from PDFs, especially tables and complex layouts. It provides superior table detection and preserves document structure better than standard PDF loaders.

**Loader Class:** `PdfPlumberLoader`

**Config Class:** `PdfPlumberLoaderConfig`

## Install

<Note>
  Install the PdfPlumber loader optional dependency group:

  ```bash theme={null}
  uv pip install "upsonic[pdfplumber-loader]"
  ```
</Note>

## Examples

```python theme={null}
from upsonic import Agent, Task, KnowledgeBase
from upsonic.loaders.pdfplumber import PdfPlumberLoader
from upsonic.loaders.config import PdfPlumberLoaderConfig
from upsonic.embeddings import OpenAIEmbedding, OpenAIEmbeddingConfig
from upsonic.text_splitter.recursive import RecursiveChunker, RecursiveChunkingConfig
from upsonic.vectordb import ChromaProvider, ChromaConfig, ConnectionConfig, Mode

# Configure loader with table extraction
loader_config = PdfPlumberLoaderConfig(
    extraction_mode="hybrid",
    extract_tables=True,
    table_format="markdown"
)
loader = PdfPlumberLoader(loader_config)

# Setup KnowledgeBase
embedding = OpenAIEmbedding(OpenAIEmbeddingConfig())
chunker = RecursiveChunker(RecursiveChunkingConfig())
vectordb = ChromaProvider(ChromaConfig(
    collection_name="pdf_tables",
    vector_size=1536,
    connection=ConnectionConfig(mode=Mode.IN_MEMORY)
))

kb = KnowledgeBase(
    sources=["report.pdf"],
    embedding_provider=embedding,
    vectordb=vectordb,
    loaders=[loader],
    splitters=[chunker]
)

# Query with Agent
agent = Agent("anthropic/claude-sonnet-4-5")
task = Task("Extract all table data", context=[kb])
result = agent.do(task)
print(result)
```

## Parameters

| Parameter | Type | Description | Default | Source |
| - | - | - | - | - |
| `encoding` | `str \| None` | File encoding (auto-detected if None) | None | Base |
| `error_handling` | `"ignore" \| "warn" \| "raise"` | How to handle loading errors | "warn" | Base |
| `include_metadata` | `bool` | Whether to include file metadata | True | Base |
| `custom_metadata` | `dict` | Additional metadata to include | {} | Base |
| `max_file_size` | `int \| None` | Maximum file size in bytes | None | Base |
| `skip_empty_content` | `bool` | Skip documents with empty content | True | Base |
| `extraction_mode` | `"hybrid" \| "text_only" \| "ocr_only"` | Content extraction strategy | "hybrid" | Specific |
| `start_page` | `int \| None` | First page to process (1-indexed) | None | Specific |
| `end_page` | `int \| None` | Last page to process (inclusive) | None | Specific |
| `clean_page_numbers` | `bool` | Remove page numbers from headers/footers | True | Specific |
| `page_num_start_format` | `str \| None` | Format string for page start markers | None | Specific |
| `page_num_end_format` | `str \| None` | Format string for page end markers | None | Specific |
| `extra_whitespace_removal` | `bool` | Normalize whitespace | True | Specific |
| `pdf_password` | `str \| None` | Password for encrypted PDFs | None | Specific |
| `extract_tables` | `bool` | Extract and include tables | True | Specific |
| `table_format` | `"text" \| "markdown" \| "csv" \| "grid"` | Format for extracted tables | "markdown" | Specific |
| `table_settings` | `dict` | Advanced table detection settings | Default dict | Specific |
| `extract_images` | `bool` | Extract image information | False | Specific |
| `layout_mode` | `"default" \| "layout" \| "simple"` | Text extraction layout mode | "layout" | Specific |
| `use_text_flow` | `bool` | Use text flow analysis | True | Specific |
| `char_margin` | `float` | Minimum distance between characters | 3.0 | Specific |
| `line_margin` | `float` | Minimum distance between lines | 0.5 | Specific |
| `word_margin` | `float` | Minimum distance between words | 0.1 | Specific |
| `extract_page_dimensions` | `bool` | Include page dimensions in metadata | False | Specific |
| `crop_box` | `tuple[float, float, float, float] \| None` | Crop box (x0, y0, x1, y1) | None | Specific |
| `extract_annotations` | `bool` | Extract annotations and hyperlinks | False | Specific |
| `keep_blank_chars` | `bool` | Preserve blank characters | False | Specific |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.