# pymupdf/pymupdf4llm architecture

> Architecture diagram of the GitHub repository pymupdf/pymupdf4llm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pymupdf/pymupdf4llm
- Repository: https://github.com/pymupdf/pymupdf4llm

## Overview

PyMuPDF4LLM turns documents into Markdown, JSON, or plain text for LLM and retrieval workflows. The main path is a caller invoking the conversion API, which extracts and structures page content, selectively applies OCR, and renders output; batch conversion and layout-aware chunking are additional capabilities. The graph includes documented features whose implementation was not sampled, but omits uncertain internal links. Source excerpts and the index support the cited relationships; README-only links represent documented capabilities.

Main entry points: [`src/helpers/chunking/__init__.py`](https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/chunking/__init__.py) (Chunking API), [`src/__init__.py`](https://github.com/pymupdf/pymupdf4llm/blob/main/src/__init__.py) (Conversion API), [`src/helpers/pymupdf_rag.py`](https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/pymupdf_rag.py) (Page extraction), [`src/ocr/analyze_page.py`](https://github.com/pymupdf/pymupdf4llm/blob/main/src/ocr/analyze_page.py) (OCR decision)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_api["Conversion API<br/>[__init__.py]"]
  node_batch["Batch converter<br/>[batch_converter.py]"]
  node_cli["Command line<br/>[__main__.py]"]
end

subgraph group_extract["Document extraction"]
  node_extractor["Page extraction<br/>[pymupdf_rag.py]"]
  node_layout["Layout analysis<br/>[document_layout.py]"]
  node_columns["Column ordering<br/>[multi_column.py]"]
  node_textlines["Text lines<br/>[get_text_lines.py]"]
  node_tables["HTML tables<br/>[reconstruct.py]"]
end

subgraph group_ocr["OCR"]
  node_ocr_decision["OCR decision<br/>[analyze_page.py]"]
  node_ocr_features["OCR features"]
  node_ocr_exec["OCR execution"]
  node_ocr_backend["OCR backends"]
end

subgraph group_chunk["Chunking"]
  node_chunk_api["Chunking API<br/>[__init__.py]"]
  node_sentence["Sentence builder"]
  node_scoring["Boundary scoring<br/>[boundary_scorer.py]"]
  node_assembly["Chunk assembly<br/>[chunk_assembler.py]"]
  node_chunk_models["Chunk models<br/>[models.py]"]
  node_chunk_document["Chunked document"]
  node_serializer["Chunk serializer<br/>[serializer.py]"]
end

subgraph group_integrations["Integrations"]
  node_llama["LlamaIndex reader"]
end

node_user(("Document caller"))
node_consumer(("RAG or LLM consumer"))

node_user -->|"calls"| node_api
node_api -->|"converts documents"| node_extractor
node_extractor -->|"analyzes layout"| node_layout
node_extractor -->|"orders columns"| node_columns
node_extractor -->|"renders tables"| node_tables
node_extractor -->|"selects OCR"| node_ocr_decision
node_ocr_decision -->|"uses features"| node_ocr_features
node_ocr_decision -.->|"requests OCR"| node_ocr_exec
node_ocr_exec -.->|"uses backend"| node_ocr_backend
node_user -.->|"submits documents"| node_batch
node_batch -->|"calls converter"| node_api
node_user -.->|"runs command"| node_cli
node_api -->|"offers chunking"| node_chunk_api
node_chunk_api -->|"builds units"| node_sentence
node_chunk_api -->|"assembles chunks"| node_assembly
node_sentence -->|"creates units"| node_chunk_models
node_assembly -->|"uses models"| node_chunk_models
node_scoring -->|"scores boundaries"| node_chunk_models
node_chunk_api -->|"scores boundaries"| node_scoring
node_chunk_api -->|"returns document"| node_chunk_document
node_chunk_api -->|"serializes output"| node_serializer
node_api -->|"integrates with"| node_llama
node_llama -->|"renders pages"| node_extractor
node_api -->|"supplies output"| node_consumer

click node_api "https://github.com/pymupdf/pymupdf4llm/blob/main/src/__init__.py"
click node_batch "https://github.com/pymupdf/pymupdf4llm/blob/main/src/batch_converter.py"
click node_cli "https://github.com/pymupdf/pymupdf4llm/blob/main/src/__main__.py"
click node_extractor "https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/pymupdf_rag.py"
click node_layout "https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/document_layout.py"
click node_columns "https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/multi_column.py"
click node_textlines "https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/get_text_lines.py"
click node_tables "https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/table_html/reconstruct.py"
click node_ocr_decision "https://github.com/pymupdf/pymupdf4llm/blob/main/src/ocr/analyze_page.py"
click node_ocr_features "https://github.com/pymupdf/pymupdf4llm/blob/main/src/ocr/compute_ocr_features.py"
click node_ocr_exec "https://github.com/pymupdf/pymupdf4llm/blob/main/src/ocr/exec_ocr_interface.py"
click node_ocr_backend "https://github.com/pymupdf/pymupdf4llm/blob/main/src/ocr/rapidocr_391_backend.py"
click node_chunk_api "https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/chunking/__init__.py"
click node_sentence "https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/chunking/sentence_builder.py"
click node_scoring "https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/chunking/boundary_scorer.py"
click node_assembly "https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/chunking/chunk_assembler.py"
click node_chunk_models "https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/chunking/models.py"
click node_chunk_document "https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/chunking/chunked_document.py"
click node_serializer "https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/chunking/serializer.py"
click node_llama "https://github.com/pymupdf/pymupdf4llm/blob/main/src/llama/pdf_markdown_reader.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_batch,node_cli toneBlue
class node_extractor,node_layout,node_columns,node_textlines,node_tables toneAmber
class node_ocr_decision,node_ocr_features,node_ocr_exec,node_ocr_backend toneMint
class node_chunk_api,node_sentence,node_scoring,node_assembly,node_chunk_models,node_chunk_document,node_serializer toneRose
class node_llama,node_user,node_consumer toneIndigo
```

## Components

### Entry points

- [Conversion API](https://github.com/pymupdf/pymupdf4llm/blob/main/src/__init__.py): `src/__init__.py`
- [Batch converter](https://github.com/pymupdf/pymupdf4llm/blob/main/src/batch_converter.py): `src/batch_converter.py`
- [Command line](https://github.com/pymupdf/pymupdf4llm/blob/main/src/__main__.py): `src/__main__.py`

### Document extraction

- [Page extraction](https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/pymupdf_rag.py): `src/helpers/pymupdf_rag.py`
- [Layout analysis](https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/document_layout.py): `src/helpers/document_layout.py`
- [Column ordering](https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/multi_column.py): `src/helpers/multi_column.py`
- [Text lines](https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/get_text_lines.py): `src/helpers/get_text_lines.py`
- [HTML tables](https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/table_html/reconstruct.py): `src/helpers/table_html/reconstruct.py`

### OCR

- [OCR decision](https://github.com/pymupdf/pymupdf4llm/blob/main/src/ocr/analyze_page.py): `src/ocr/analyze_page.py`
- [OCR features](https://github.com/pymupdf/pymupdf4llm/blob/main/src/ocr/compute_ocr_features.py): `src/ocr/compute_ocr_features.py`
- [OCR execution](https://github.com/pymupdf/pymupdf4llm/blob/main/src/ocr/exec_ocr_interface.py): `src/ocr/exec_ocr_interface.py`
- [OCR backends](https://github.com/pymupdf/pymupdf4llm/blob/main/src/ocr/rapidocr_391_backend.py): `src/ocr/rapidocr_391_backend.py`

### Chunking

- [Chunking API](https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/chunking/__init__.py): `src/helpers/chunking/__init__.py`
- [Sentence builder](https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/chunking/sentence_builder.py): `src/helpers/chunking/sentence_builder.py`
- [Boundary scoring](https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/chunking/boundary_scorer.py): `src/helpers/chunking/boundary_scorer.py`
- [Chunk assembly](https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/chunking/chunk_assembler.py): `src/helpers/chunking/chunk_assembler.py`
- [Chunk models](https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/chunking/models.py): `src/helpers/chunking/models.py`
- [Chunked document](https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/chunking/chunked_document.py): `src/helpers/chunking/chunked_document.py`
- [Chunk serializer](https://github.com/pymupdf/pymupdf4llm/blob/main/src/helpers/chunking/serializer.py): `src/helpers/chunking/serializer.py`

### Integrations

- [LlamaIndex reader](https://github.com/pymupdf/pymupdf4llm/blob/main/src/llama/pdf_markdown_reader.py): `src/llama/pdf_markdown_reader.py`

### Other components

- **Document caller**
- **RAG or LLM consumer**

## Connections

- Document caller → Conversion API: calls (evidence: `README.md`)
- Conversion API → Page extraction: converts documents (evidence: `README.md`)
- Page extraction → Layout analysis: analyzes layout (evidence: `README.md`)
- Page extraction → Column ordering: orders columns (evidence: `README.md`)
- Page extraction → HTML tables: renders tables (evidence: `README.md`)
- Page extraction → OCR decision: selects OCR (evidence: `README.md`)
- OCR decision → OCR features: uses features (evidence: `src/ocr/analyze_page.py`)
- OCR decision → OCR execution: requests OCR
- OCR execution → OCR backends: uses backend
- Document caller → Batch converter: submits documents
- Batch converter → Conversion API: calls converter (evidence: `src/batch_converter.py`)
- Document caller → Command line: runs command
- Conversion API → Chunking API: offers chunking (evidence: `README.md`)
- Chunking API → Sentence builder: builds units (evidence: `src/helpers/chunking/__init__.py`)
- Chunking API → Chunk assembly: assembles chunks (evidence: `src/helpers/chunking/__init__.py`)
- Sentence builder → Chunk models: creates units (evidence: `src/helpers/chunking/sentence_builder.py`)
- Chunk assembly → Chunk models: uses models (evidence: `src/helpers/chunking/chunk_assembler.py`)
- Boundary scoring → Chunk models: scores boundaries (evidence: `src/helpers/chunking/boundary_scorer.py`)
- Chunking API → Boundary scoring: scores boundaries (evidence: `src/helpers/chunking/__init__.py`)
- Chunking API → Chunked document: returns document (evidence: `src/helpers/chunking/__init__.py`)
- Chunking API → Chunk serializer: serializes output (evidence: `src/helpers/chunking/__init__.py`)
- Conversion API → LlamaIndex reader: integrates with (evidence: `README.md`)
- LlamaIndex reader → Page extraction: renders pages (evidence: `src/llama/pdf_markdown_reader.py`)
- Conversion API → RAG or LLM consumer: supplies output (evidence: `README.md`)