The Role of PyMuPDF in Hiring Agent: PDF to Markdown Pipeline for LLM Resume Parsing

PyMuPDF serves as the core PDF parsing engine in the Hiring Agent project, converting unstructured resume PDFs into structured Markdown that enables downstream LLM extraction of candidate data.

The interviewstreet/hiring-agent repository relies on PyMuPDF to bridge the gap between binary PDF documents and structured JSON. By leveraging PyMuPDF's low-level APIs for text, font analysis, image extraction, and table detection, the system transforms arbitrary resume formats into clean, semantically-rich Markdown that large language models can reliably parse.

Core PDF Processing Capabilities

Document Loading and Page Iteration

The pipeline begins in pdf.py where PDFHandler.extract_text_from_pdf calls pymupdf.open() to load the file or stream. According to the source code at lines 52-57, this creates a Document object that serves as the handle for all subsequent operations. The to_markdown routine in pymupdf_rag.py (lines 376-389) then iterates over each page using doc[pno], accessing page-level APIs to extract content while handling rotation and boundary boxes.

Text Extraction and Header Detection

PyMuPDF provides the raw text blocks through page.get_text("dict"), which returns a dictionary of spans with font metadata. The Hiring Agent processes these using pymupdf4llm.helpers.get_text_lines inside write_text (pymupdf_rag.py:L118-L132).

The IdentifyHeaders class (pymupdf_rag.py:L84-L99) analyzes font sizes across all spans to build a header-id map. Larger fonts automatically map to Markdown heading levels (#, ##, etc.), preserving the document hierarchy without explicit markup.

Image, Table, and Link Resolution

For image extraction, the code uses page.get_image_info() to enumerate raster images and page.get_pixmap() to render them, as seen in save_image (pymupdf_rag.py:L71-L78). These can be saved to disk or embedded as Base64 data URIs.

For table detection, PyMuPDF's page.find_tables() convenience method discovers tabular structures (pymupdf_rag.py:L84-L95), which are then rendered as Markdown tables in the output.

For hyperlink resolution, page.get_links() supplies URI annotations (pymupdf_rag.py:L32-L66). The resolve_links function matches link rectangles to text spans and emits standard Markdown syntax: [text](url).

Background Analysis and Graphics Filtering

Helper functions like page_is_ocr, get_bg_color, and column_boxes rely on PyMuPDF's low-level drawing and pixel APIs (pymupdf_rag.py:L100-L115). These determine whether to ignore vector graphics or skip OCR-only pages, ensuring the Markdown output contains only relevant semantic content.

Implementation Examples

Converting a Single PDF to Markdown

from pymupdf_rag import to_markdown
import pymupdf

pdf_path = "candidate_resume.pdf"
doc = pymupdf.open(pdf_path)                 # ← PyMuPDF loads the file

md = to_markdown(doc, pages=range(doc.page_count))
print(md)                                    # Markdown ready for LLM

This creates a Document via pymupdf.open, then walks every page to extract headings, tables, images, and links into a unified Markdown string.

Full Resume Extraction via the Public API

from pdf import PDFHandler

handler = PDFHandler()
json_resume = handler.extract_json_from_pdf("candidate_resume.pdf")

if json_resume:
    print(json_resume.json(indent=2))
else:
    print("Failed to parse the PDF.")

Under the hood, PDFHandler.extract_text_from_pdf uses PyMuPDF to generate Markdown, which llm_utils then sends to the LLM for structured JSON extraction.

Accessing Raw PyMuPDF Objects

import pymupdf

with pymupdf.open("candidate_resume.pdf") as doc:
    for page_no, page in enumerate(doc):
        # Enumerate all images on the page

        for img in page.get_image_info():
            print(f"Page {page_no}: image {img['xref']} at {img['bbox']}")

        # Extract all URI links

        for link in page.get_links():
            if link["kind"] == pymupdf.LINK_URI:
                print(f"Link: {link['uri']} on page {page_no}")

Key Source Files and Architecture

File	Purpose	Key PyMuPDF Usage
pymupdf_rag.py	Implements the full PDF-to-Markdown pipeline, header detection, image/table handling, and link resolution.	to_markdown, IdentifyHeaders, save_image, resolve_links
pdf.py	High-level wrapper (PDFHandler) that orchestrates extraction and LLM calls.	pymupdf.open in extract_text_from_pdf (L52-57)
models.py	Defines Pydantic data models (JSONResume, Basics) receiving structured data.	Receives output from PyMuPDF processing pipeline
llm_utils.py	Provides LLM provider abstraction for JSON generation.	Consumes Markdown produced by PyMuPDF extraction

Summary

• PyMuPDF is the foundational library that enables Hiring Agent to read and analyze PDF resumes, providing all low-level parsing capabilities for text, fonts, images, tables, and links.
• The Markdown generation layer built on top of PyMuPDF (in pymupdf_rag.py) converts binary PDFs into structured text with preserved headings, tables, and hyperlinks.
• Header detection relies on PyMuPDF font size analysis to automatically map document structure to Markdown headings without manual markup.
• The pipeline flow moves from pymupdf.open() through to_markdown() to the LLM, resulting in structured JSON resume data that powers the hiring workflow.

Frequently Asked Questions

What is the primary role of PyMuPDF in Hiring Agent?

PyMuPDF acts as the core PDF parsing engine that extracts raw content from resume PDFs. It provides the low-level APIs necessary to read text blocks, identify fonts, extract images, detect tables, and resolve hyperlinks, enabling the system to convert unstructured PDFs into structured Markdown for LLM processing.

How does Hiring Agent handle PDF tables using PyMuPDF?

The system uses PyMuPDF's page.find_tables() method to discover tabular structures within the document. These tables are then rendered as Markdown tables in the output, preserving the relational data structure so the LLM can interpret candidate skills, experience timelines, and educational history accurately.

Can PyMuPDF extract images from resumes in the Hiring Agent codebase?

Yes, through page.get_image_info() and page.get_pixmap(), PyMuPDF retrieves raster images from PDF pages. The save_image function in pymupdf_rag.py can render these as files or embed them as Base64 data URIs within the Markdown, allowing the LLM to reference visual content when present in the resume.

Where does the PDF processing logic reside in the repository?

The primary PDF processing occurs in pymupdf_rag.py, which contains the to_markdown function and helper classes like IdentifyHeaders. The high-level orchestration happens in pdf.py through the PDFHandler class, which coordinates PyMuPDF extraction with LLM processing to produce the final JSON resume output.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}