ReconstructPdf: The Forensic Surgeon of Broken PDFs

While working with Pdf, The PyPDF2 library raises an`AssertionError` Exception, the reason being PyPdf2 Lib doesn’t support Pdf files of version > 1.3 while the user was trying to upload Pdf file of version 1.5

Shobhit Bhosure, Author · Understanding and Reconstructing PDFs

The Map is Not the Territory

When a PDF refuses to open, the data is rarely gone. Instead, the map to that data is broken. A PDF file is not a continuous document. It is a strictly ordered collection of objects tied together by a Cross-Reference (xref) table. This table acts as a GPS, recording the exact byte offset of every object in the file.

If a file is manually edited or corrupted during transit, these byte offsets shift. A single misplaced character ruins the map. Traditional libraries often fail when encountering these corrupted structures because they attempt to parse the document semantically. ReconstructPdf ignores the content entirely. It focuses solely on repairing the map.

Bypassing the Abstraction Layer

The necessity for byte-level manipulation often arises when high-level tools hit a wall. Shobhit Bhosure encountered this exact problem while building a system to merge laboratory reports at LiveHealth.

Instead of waiting for an upstream fix, the solution was to drop down to the lowest level. By treating the file as a raw binary stream, the version constraints of existing libraries become irrelevant.

A State Machine Built on io.BytesIO

The architecture of ReconstructPdf is a linear state machine. It reads the corrupted file byte by byte using Python's standard io.BytesIO buffers. When it encounters an object header, it pauses to verify the structural integrity of the data block.

The most critical operation is recalculating stream lengths. In the PDF specification, stream objects must declare their exact length. If this number is missing or incorrect, the parser halts. ReconstructPdf measures the stream manually and injects the correct length back into the object dictionary before rewriting the xref table.

Structural Repair vs. Semantic Extraction

The modern document parsing landscape is heavily skewed toward semantic extraction. Tools like PyMuPDF or AI-driven systems like NVIDIA Nemotron are designed to understand what a document means. They extract text, identify tables, and preserve visual layouts for downstream systems.

ReconstructPdf serves a fundamentally different purpose. It operates beneath the semantic layer. It does not know if a document contains a medical report or a restaurant menu. It only knows if the byte offsets align.