PDF to Text Conversion in Hiring Agent: PyMuPDF Implementation Guide

Hiring Agent uses PyMuPDF (the pymupdf Python package) to extract PDF content, converting documents to Markdown through a custom to_markdown pipeline defined in pymupdf_rag.py.

The interviewstreet/hiring-agent repository processes résumé PDFs to generate structured JSON data for recruiting workflows. The system relies on PyMuPDF for PDF text extraction, combining low-level document parsing with a custom Markdown conversion layer. This architecture enables accurate extraction of headers, tables, and images from candidate documents.

Core PDF Processing Architecture

The PDFHandler Class in pdf.py

The entry point for PDF processing is the PDFHandler class defined in pdf.py. According to the source code, this class opens PDF documents using pymupdf.open(...) at lines 52‑55, creating a Document object that serves as the foundation for text extraction.

The Markdown Conversion Pipeline

After opening the document, raw pages pass to the to_markdown helper function implemented in pymupdf_rag.py (lines 52‑66). This function walks the document structure, identifies headers, tables, and images, and returns a Markdown‑formatted string that the LLM consumes to build structured résumé JSON.

Implementation Examples

The following examples demonstrate how Hiring Agent extracts text from PDFs using both the high-level handler and direct PyMuPDF access.

# Example 1 – Using the high‑level PDFHandler

from pdf import PDFHandler

handler = PDFHandler()
markdown = handler.extract_text_from_pdf("resume.pdf")
print(markdown)          # Markdown representation of the PDF content

# Example 2 – Direct PyMuPDF usage (what PDFHandler does internally)

import pymupdf

doc = pymupdf.open("resume.pdf")
pages = range(doc.page_count)            # all pages

md_text = to_markdown(doc, pages=pages)  # from pymupdf_rag.py

print(md_text)

Key Files and Functions

The PDF-to-text pipeline relies on two primary files:

• pdf.py: Defines the PDFHandler class and the extract_text_from_pdf method that interfaces with PyMuPDF to open and process documents.
• pymupdf_rag.py: Implements the to_markdown function, converting a pymupdf.Document into clean Markdown text while preserving document structure.

Summary

• PyMuPDF (pymupdf) serves as the core engine for PDF text extraction in Hiring Agent.
• The PDFHandler class in pdf.py (lines 52‑55) manages document opening via pymupdf.open().
• The to_markdown function in pymupdf_rag.py (lines 52‑66) transforms raw PDF content into Markdown format.
• Extracted Markdown feeds directly into LLM processing to generate structured résumé JSON.

Frequently Asked Questions

Which Python library does Hiring Agent use for PDF text extraction?

Hiring Agent uses PyMuPDF (imported as pymupdf), a high-performance PDF manipulation library that provides direct access to document content, metadata, and structure. This library handles the low-level PDF parsing operations required to extract text from résumé documents.

How does Hiring Agent convert PDF content to Markdown?

The system uses a custom to_markdown function in pymupdf_rag.py that iterates through the pymupdf.Document object, identifying structural elements like headers and tables. It returns cleanly formatted Markdown text optimized for downstream LLM consumption and structured JSON generation.

Where is the PDF processing logic implemented in the Hiring Agent repository?

The core logic resides in two files: pdf.py contains the PDFHandler class that opens documents, while pymupdf_rag.py contains the to_markdown helper that performs the actual text extraction and formatting. These files work together to convert PDF inputs into processable Markdown outputs.

Can I use Hiring Agent's PDF extraction for documents other than résumés?

While designed specifically for résumé processing, the PDFHandler class and to_markdown function can process any PDF document supported by PyMuPDF. The resulting Markdown output is suitable for any downstream LLM consumption pipeline, not just résumé parsing.

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